diff --git a/collects/web-server/docs/reference/command-line.scrbl b/collects/web-server/docs/reference/command-line.scrbl index 4a49a33802..68b43f969b 100644 --- a/collects/web-server/docs/reference/command-line.scrbl +++ b/collects/web-server/docs/reference/command-line.scrbl @@ -1,13 +1,73 @@ #reader(lib "docreader.ss" "scribble") @require["../web-server.ss"] -@title[#:style 'toc]{Command-line Tools} +@title[#:style 'toc]{Running the Web Server} -XXX +There are a number of ways to run the Web Server. The two primary ways +are through a command-line tool or through a function call. @local-table-of-contents[] @; ------------------------------------------------------------ -@section[#:tag "example"]{Example} +@section[#:tag "command-line-tools"]{Command-line Tools} -XXX \ No newline at end of file +Two command-line utilities are provided with the @file{web-server}: + +@exec{plt-web-server-text [-f -p -a ]} +@exec{plt-web-server [-f -p -a ]} + +The first runs the @file{web-server} with MzScheme, while the second runs +the server with MrEd, providing a graphical UI. The optional file-name +argument specifies the path to a @scheme[configuration-table] S-expression +(see @secref["configuration-table"].) If this is not provided, the default +configuration shipped with the server is used. The optional port and ip-address +arguments override the corresponding portions of the @scheme[configuration-table]. + +The @scheme[configuration-table] is given to @scheme[configuration-table->web-config\@] +and used to construct a @scheme[web-config^] unit, +and is linked with the @scheme[web-server\@] unit. The resulting unit is invoked, and +the server runs until the process is killed. + +@; ------------------------------------------------------------ +@section[#:tag "web-server.ss"]{Functional} + +@file{web-server.ss} provides a number of functions for easing embedding +of the @file{web-server} in other applications, or loading a custom +dispatcher. See @file{run.ss} for an example of such a script. + +@defproc[(serve [#:dispatch dispatch dispatcher?] + [#:tcp@ tcp\@ tcp-unit^ raw:tcp\@] + [#:port port integer? 80] + [#:listen-ip listen-ip (or/c string? false/c) #f] + [#:max-waiting max-waiting integer? 40] + [#:initial-connection-timeout initial-connection-timeout integer? 60]) + (-> void)]{ + Constructs an appropriate @scheme[dispatch-config^], invokes the @scheme[dispatch-server\@], + and calls its @scheme[serve] function. +} + +@defproc[(serve/ports [#:dispatch dispatch dispatcher?] + [#:tcp@ tcp\@ tcp-unit^ raw:tcp\@] + [#:ports ports (listof integer?) (list 80)] + [#:listen-ip listen-ip (or/c string? false/c) #f] + [#:max-waiting max-waiting integer? 40] + [#:initial-connection-timeout initial-connection-timeout integer? 60]) + (-> void)]{ + Calls @scheme[serve] multiple times, once for each @scheme[port], and returns + a function that shutdowns all of the server instances. +} + +@defproc[(serve/ips+ports [#:dispatch dispatch dispatcher?] + [#:tcp@ tcp\@ tcp-unit^ raw:tcp\@] + [#:ips+ports ips+ports (listof (cons/c (or/c string? false/c) (listof integer?))) (list (cons #f (list 80)))] + [#:max-waiting max-waiting integer? 40] + [#:initial-connection-timeout initial-connection-timeout integer? 60]) + (-> void)]{ + Calls @scheme[serve/ports] multiple times, once for each @scheme[ip], and returns + a function that shutdowns all of the server instances. +} + +@defproc[(do-not-return) void]{ + This function does not return. If you are writing a script to load the @file{web-server} + you are likely to want to call this functions at the end of your script. +} diff --git a/collects/web-server/docs/reference/configuration.scrbl b/collects/web-server/docs/reference/configuration.scrbl index 0abfa1132d..ea16a43e20 100644 --- a/collects/web-server/docs/reference/configuration.scrbl +++ b/collects/web-server/docs/reference/configuration.scrbl @@ -4,10 +4,13 @@ @title[#:style 'toc]{Configuration} +There are a number of libraries and utilities useful for +configuring the @file{web-server}. + @local-table-of-contents[] @; ------------------------------------------------------------ -@section[#:tag "configuration-table-structs"]{Configuration Table Structure} +@section[#:tag "configuration-table-structs.ss"]{Configuration Table Structure} @file{configuration/configuration-table-structs.ss} provides the following structures that represent a standard configuration (see @secref["XXX"]) of the @file{web-server}. @@ -74,7 +77,7 @@ the configuration table S-expression file format described in [passwords (or/c false/c path-string?)])] @; ------------------------------------------------------------ -@section[#:tag "configuration-table"]{Configuration Table} +@section[#:tag "configuration-table.ss"]{Configuration Table} @file{configuration/configuration-table.ss} provides functions for reading, writing, parsing, and printing @scheme[configuration-table] @@ -142,7 +145,7 @@ This function writes a @scheme[configuration-table] to @scheme[path]. } @; ------------------------------------------------------------ -@section[#:tag "namespace"]{Servlet Namespaces} +@section[#:tag "namespace.ss"]{Servlet Namespaces} @; XXX Require dispatch-servlets and dispatch-lang @@ -185,7 +188,7 @@ module C to all servlet namespaces. Through other means (see @secref["pipelines" of servlets can share different sets of modules. @; ------------------------------------------------------------ -@section[#:tag "responders"]{Standard Responders} +@section[#:tag "responders.ss"]{Standard Responders} @file{configuration/responders.ss} provides some functions that help constructing HTTP responders. These functions are used by the default dispatcher constructor (see @secref["web-server-unit"]) to diff --git a/collects/web-server/docs/reference/dispatchers.scrbl b/collects/web-server/docs/reference/dispatchers.scrbl index 62ee400113..2160b95a0d 100644 --- a/collects/web-server/docs/reference/dispatchers.scrbl +++ b/collects/web-server/docs/reference/dispatchers.scrbl @@ -15,7 +15,7 @@ documentation will be useful. @; XXX Include connection? and request? @; ------------------------------------------------------------ -@section[#:tag "dispatch"]{General} +@section[#:tag "dispatch.ss"]{General} @file{dispatchers/dispatch.ss} provides a few functions for dispatchers in general. @@ -45,7 +45,7 @@ otherwise. @; XXX Rename const to lift @; ------------------------------------------------------------ -@section[#:tag "dispatch-const"]{Lifting Procedures} +@section[#:tag "dispatch-const.ss"]{Lifting Procedures} @file{dispatchers/dispatch-const.ss} defines: @@ -56,7 +56,7 @@ otherwise. } @; ------------------------------------------------------------ -@section[#:tag "dispatch-files"]{Serving Files} +@section[#:tag "dispatch-files.ss"]{Serving Files} @file{dispatchers/dispatch-files.ss} allows files to be served. It defines a dispatcher construction procedure: @@ -79,7 +79,7 @@ It defines a dispatcher construction procedure: @; XXX Change filtering to take predicate, rather than regexp @; ------------------------------------------------------------ -@section[#:tag "dispatch-filter"]{Filtering Requests} +@section[#:tag "dispatch-filter.ss"]{Filtering Requests} @file{dispatchers/dispatch-filter.ss} defines a dispatcher constructer that calls an underlying dispatcher @@ -92,7 +92,7 @@ with all requests that pass a predicate. } @; ------------------------------------------------------------ -@section[#:tag "dispatch-host"]{Virtual Hosts} +@section[#:tag "dispatch-host.ss"]{Virtual Hosts} @file{dispatchers/dispatch-host.ss} defines a dispatcher constructor that calls a different dispatcher based upon the host requested. @@ -106,7 +106,7 @@ that calls a different dispatcher based upon the host requested. } @; ------------------------------------------------------------ -@section[#:tag "dispatch-lang"]{Serving Web Language Servlets} +@section[#:tag "dispatch-lang.ss"]{Serving Web Language Servlets} @file{dispatchers/dispatch-lang.ss} defines a dispatcher constructor that runs servlets written in the Web Language. @@ -132,7 +132,7 @@ that runs servlets written in the Web Language. } @; ------------------------------------------------------------ -@section[#:tag "dispatch-log"]{Logging} +@section[#:tag "dispatch-log.ss"]{Logging} @file{dispatchers/dispatch-log.ss} defines a dispatcher constructer for transparent logging of requests. @@ -161,7 +161,7 @@ for transparent logging of requests. } @; ------------------------------------------------------------ -@section[#:tag "dispatch-passwords"]{Password Protection} +@section[#:tag "dispatch-passwords.ss"]{Password Protection} @file{dispatchers/dispatch-passwords.ss} defines a dispatcher constructor that performs HTTP Basic authentication filtering. @@ -187,7 +187,7 @@ that performs HTTP Basic authentication filtering. } @; ------------------------------------------------------------ -@section[#:tag "dispatch-pathprocedure"]{Procedure Invocation upon Request} +@section[#:tag "dispatch-pathprocedure.ss"]{Procedure Invocation upon Request} @file{dispatchers/dispatch-pathprocedure.ss} defines a dispatcher constructor for invoking a particular procedure when a request is given to a particular @@ -203,7 +203,7 @@ This is used in the standard @file{web-server} pipeline to provide a URL that refreshes the password file, servlet cache, etc. @; ------------------------------------------------------------ -@section[#:tag "dispatch-sequencer"]{Sequencing} +@section[#:tag "dispatch-sequencer.ss"]{Sequencing} @file{dispatchers/dispatch-sequencer.ss} defines a dispatcher constructor that invokes a sequence of dispatchers until one applies. @@ -216,7 +216,7 @@ that invokes a sequence of dispatchers until one applies. } @; ------------------------------------------------------------ -@section[#:tag "dispatch-servlets"]{Serving Scheme Servlets} +@section[#:tag "dispatch-servlets.ss"]{Serving Scheme Servlets} @file{dispatchers/dispatch-servlets.ss} defines a dispatcher constructor that runs servlets written in Scheme. @@ -264,7 +264,7 @@ that runs servlets written in Scheme. } @; ------------------------------------------------------------ -@section[#:tag "filesystem-map"]{Mapping URLs to Paths} +@section[#:tag "filesystem-map.ss"]{Mapping URLs to Paths} @file{dispatchers/filesystem-map.ss} provides a means of mapping URLs to paths on the filesystem. diff --git a/collects/web-server/docs/reference/managers.scrbl b/collects/web-server/docs/reference/managers.scrbl index d54c4e0f93..1f712bc99b 100644 --- a/collects/web-server/docs/reference/managers.scrbl +++ b/collects/web-server/docs/reference/managers.scrbl @@ -13,7 +13,7 @@ pluggable through the manager interface. @local-table-of-contents[] @; ------------------------------------------------------------ -@section[#:tag "manager"]{General} +@section[#:tag "manager.ss"]{General} @file{managers/manager.ss} defines the manager interface. It is required by the users and implementers of managers. @@ -69,7 +69,7 @@ the users and implementers of managers. } @; ------------------------------------------------------------ -@section[#:tag "none"]{No Continuations} +@section[#:tag "none.ss"]{No Continuations} @file{managers/none.ss} defines a manager constructor: @@ -85,7 +85,7 @@ If you are considering using this manager, also consider using the Web Language. (See @secref["lang"].) @; ------------------------------------------------------------ -@section[#:tag "timeouts"]{Timeouts} +@section[#:tag "timeouts.ss"]{Timeouts} @file{managers/timeouts.ss} defines a manager constructor: @@ -109,7 +109,7 @@ This manager has been found to be... problematic... in large-scale deployments of the @file{web-server}. @; ------------------------------------------------------------ -@section[#:tag "lru"]{LRU} +@section[#:tag "lru.ss"]{LRU} @file{managers/lru.ss} defines a manager constructor: diff --git a/collects/web-server/docs/reference/reference.scrbl b/collects/web-server/docs/reference/reference.scrbl index 24f4401419..aee6ed51dc 100644 --- a/collects/web-server/docs/reference/reference.scrbl +++ b/collects/web-server/docs/reference/reference.scrbl @@ -11,13 +11,12 @@ develop Web applications in Scheme. @include-section["command-line.scrbl"] @include-section["configuration.scrbl"] @include-section["dispatchers.scrbl"] -@include-section["lang.scrbl"] -@include-section["managers.scrbl"] -@include-section["private.scrbl"] -@include-section["servlet-env.scrbl"] -@include-section["servlet.scrbl"] @include-section["web-config-unit.scrbl"] @include-section["web-server-unit.scrbl"] -@include-section["web-server.scrbl"] +@include-section["servlet.scrbl"] +@include-section["servlet-env.scrbl"] +@include-section["managers.scrbl"] +@include-section["lang.scrbl"] +@include-section["private.scrbl"] @index-section["web-server-ref-index"] \ No newline at end of file diff --git a/collects/web-server/docs/reference/web-server-unit.scrbl b/collects/web-server/docs/reference/web-server-unit.scrbl index 2a0e39e5f8..60d7df5bce 100644 --- a/collects/web-server/docs/reference/web-server-unit.scrbl +++ b/collects/web-server/docs/reference/web-server-unit.scrbl @@ -1,13 +1,39 @@ #reader(lib "docreader.ss" "scribble") @require["../web-server.ss"] +@; XXX web-server-unit.ss @title[#:style 'toc]{Web Server Unit} -XXX +The @file{web-server} offers a unit-based approach to running the server. -@local-table-of-contents[] +@file{web-server-sig.ss} provides the @defthing[web-server^ signature?] signature +with two elements: + + @defproc[(serve) (-> void)]{ + Runs the server and returns a procedure that shuts down the server. + } + + @defproc[(serve-ports [ip input-port?] + [op output-port?]) + void]{ + Serves a single connection represented by the ports @scheme[ip] and + @scheme[op]. + } -@; ------------------------------------------------------------ -@section[#:tag "example"]{Example} +@file{web-server-unit.ss} provides the @defthing[web-server\@ unit?] unit. It +imports a @scheme[web-config^] unit and a @scheme[tcp^] unit. It uses the +@scheme[web-config^] to construct a @scheme[dispatcher?] function that +sets up one virtual host dispatcher, for each virtual host in the @scheme[web-config^], +that sequences the following operations: +@itemize[ + @item{Logs the incoming request with the given format to the given file} + @item{Performs HTTP Basic Authentization with the given password file} + @item{Allows the @scheme["/conf/refresh-passwords"] URL to refresh the password file.} + @item{Allows the @scheme["/conf/collect-garbage"] URL to call the garbage collector.} + @item{Allows the @scheme["/conf/refresh-servlets"] URL to refresh the servlets cache.} + @item{Execute servlets under the @scheme["/servlets/"] URL in the given servlet root directory.} + @item{Serves files under the @scheme["/"] URL in the given htdocs directory.} +] -XXX \ No newline at end of file +Using this @scheme[dispatcher?], it loads a dispatching server that provides @scheme[serve] +and @scheme[serve-ports] functions that operate as expected. diff --git a/collects/web-server/docs/reference/web-server.scrbl b/collects/web-server/docs/reference/web-server.scrbl deleted file mode 100644 index 69e9c77b4c..0000000000 --- a/collects/web-server/docs/reference/web-server.scrbl +++ /dev/null @@ -1,13 +0,0 @@ -#reader(lib "docreader.ss" "scribble") -@require["../web-server.ss"] - -@title[#:style 'toc]{Web Server} - -XXX - -@local-table-of-contents[] - -@; ------------------------------------------------------------ -@section[#:tag "example"]{Example} - -XXX \ No newline at end of file diff --git a/collects/web-server/private/launch.ss b/collects/web-server/private/launch.ss index 5aa5dbe9b0..e3d2ec0ab8 100644 --- a/collects/web-server/private/launch.ss +++ b/collects/web-server/private/launch.ss @@ -19,7 +19,7 @@ (define configuration@ (parse-command-line - "web-server" + "plt-web-server" (current-command-line-arguments) `((once-each [("-f" "--configuration-table") diff --git a/collects/web-server/web-server.ss b/collects/web-server/web-server.ss index 5ec69a2372..460a63b35c 100644 --- a/collects/web-server/web-server.ss +++ b/collects/web-server/web-server.ss @@ -28,8 +28,8 @@ [port 80] [listen-ip #f] [max-waiting 40] - [initial-connection-timeout 60] - [read-request http:read-request]) + [initial-connection-timeout 60]) + (define read-request http:read-request) (define-unit-binding a-tcp@ tcp@ (import) (export tcp^)) (define-compound-unit/infer dispatch-server@/tcp@ @@ -45,44 +45,29 @@ (define/kw (serve/ports #:key - dispatch - [tcp@ raw:tcp@] [ports (list 80)] - [listen-ip #f] - [max-waiting 40] - [initial-connection-timeout 60] - [read-request http:read-request]) + #:other-keys + serve-keys) (define shutdowns (map (lambda (port) - (serve #:dispatch dispatch - #:tcp@ tcp@ + (apply serve #:port port - #:listen-ip listen-ip - #:max-waiting max-waiting - #:initial-connection-timeout initial-connection-timeout - #:read-request read-request)) + serve-keys)) ports)) (lambda () (for-each apply shutdowns))) (define/kw (serve/ips+ports #:key - dispatch - [tcp@ raw:tcp@] [ips+ports (list (cons #f (list 80)))] - [max-waiting 40] - [initial-connection-timeout 60] - [read-request http:read-request]) + #:other-keys + serve-keys) (define shutdowns (map (match-lambda [(list-rest listen-ip ports) - (serve/ports #:dispatch dispatch - #:tcp@ tcp@ - #:ports ports - #:listen-ip listen-ip - #:max-waiting max-waiting - #:initial-connection-timeout initial-connection-timeout - #:read-request read-request)]) + (apply serve/ports + #:ports ports + serve-keys)]) ips+ports)) (lambda () (for-each apply shutdowns)))