[Seaside] HTTP Server Structure

[Stephen Pair]

Sven Van Caekenberghe wrote:

> On 17 Nov 2003, at 17:47, Stephen Pair wrote:
>
>> For Comanche 6.2, the following will start an http file server on 
>> your default directory:
>>
>>    | ma |
>>    ma := ModuleAssembly core.
>>    ma serverRoot: FileDirectory default fullName.
>>    ma documentRoot: FileDirectory default fullName.
>>    ma directoryIndex: 'index.html index.htm'.
>>    ma serveFiles.
>>    (HttpService startOn: 8080 named: 'httpd') plug: ma rootModule
>
>
> Yeah, I found that somewhere in a class comment, I now have it working as
>
>  | ma |
>  ma := ModuleAssembly core.
>  ma serverRoot: (FileDirectory on: '/Users/sven/Sites/') fullName.
>  ma documentRoot: (FileDirectory on: '/Users/sven/Sites/') fullName.
>  ma directoryIndex: 'index.html index.htm'.
>  ma serveFiles.
>  (HttpService startOn: 8080 named: 'httpd') plug: ma rootModule
>
> I don't understand the difference between #serverRoot and 
> #documentRoot, I thought an HTTP service only needed a directory to 
> serve files from, and an optional URL prefix ?


This was originally intended to be something akin to Apache's notion of 
a server root and a document root.  The document root can be different 
in different contents (i.e. for different virtual hosts) and is used to 
establish the root path for serving static documents from disk.  Server 
root is a location on disk that is not in the document root hiearchy and 
is thus appropriate for things that shouldn't be accessible over the 
web.  A module could use this path to store configuration settings or 
something (as an example).  However, at this point, I don't think 
anything uses the server root variable.


>> The best docs for Comanche 6.2 (registered as KomHttpServer on 
>> SqueakMap) are located in various class comments.  Start with the 
>> class comments for KomHttpServerInfo.  Most (if not all) of the 
>> ComancheModule subclasses also include helpful class comments with 
>> examples.
>
>
> There are indeed some class comments, but the overall structure is 
> quite factored and hard to follow/grasp. Many classes in Squeak(Map) 
> are lacking (class) comments. Unless I am mistaken and remember it 
> incorrectly, VisualWorks used to be (and maybe still is) much better 
> in that respect (let alone the fact that there was a real manual). 


Yes, I know...with Comanche I've tried to be better that what is 
typically found in Squeak (therefore, people often just assume that 
Comanche has no docs).  I just checked and all but one class (the SUnit 
test class) in the KomHttpServer package is documented with class comments.

The basic idea in Comanche is that an HttpRequest is received then 
delegated to a hierarchy of ComancheModules.  A module accepts a request 
and decides if it can build a response or whether it should delegate the 
request to its sub-modules.  Some modules transform a request on the way 
in, and other modules will modify a response on the way out, and still 
others do both. 

- Stephen