From d98743e1e9f5a141c8fe4b98ec998227da3f8d9d Mon Sep 17 00:00:00 2001 From: Jay McCarthy Date: Tue, 5 Jun 2007 05:06:16 +0000 Subject: [PATCH] Updating documentation svn: r6479 --- .../dispatchers/dispatch-servlets.ss | 16 +- .../docs/reference/dispatchers.scrbl | 220 +++++++++--------- collects/web-server/docs/reference/lang.scrbl | 2 +- .../web-server/docs/reference/reference.scrbl | 7 +- .../docs/reference/servlet-env.scrbl | 17 +- .../web-server/docs/reference/servlet.scrbl | 90 ++++++- .../docs/reference/web-config-unit.scrbl | 64 ++++- collects/web-server/run.ss | 1 + collects/web-server/servlet-env.ss | 1 + collects/web-server/web-config-unit.ss | 4 +- 10 files changed, 282 insertions(+), 140 deletions(-) diff --git a/collects/web-server/dispatchers/dispatch-servlets.ss b/collects/web-server/dispatchers/dispatch-servlets.ss index 3ef7011602..a6ff69a138 100644 --- a/collects/web-server/dispatchers/dispatch-servlets.ss +++ b/collects/web-server/dispatchers/dispatch-servlets.ss @@ -31,15 +31,13 @@ (gen-servlet-responder "servlet-error.html")] [timeouts-servlet-connection (* 60 60 24)] [timeouts-default-servlet 30]) - ;; ************************************************************ - ;; ************************************************************ - ;; SERVING SERVLETS - + ;; servlet-content-producer: connection request -> void (define (servlet-content-producer conn req) (define meth (request-method req)) (define uri (request-uri req)) ;; XXX - make timeouts proportional to size of bindings + ; XXX Move outside (adjust-connection-timeout! conn timeouts-servlet-connection) @@ -277,7 +275,7 @@ ; XXX load/use-compiled breaks errortrace (define s (load/use-compiled a-path)) (cond - ; FIX - reason about exceptions from dynamic require (catch and report if not already) + ; XXX - reason about exceptions from dynamic require (catch and report if not already) ;; module servlet [(void? s) (let* ([module-name `(file ,(path->string a-path))] @@ -293,7 +291,7 @@ timeouts-servlet-connection timeout) (v1.module->v1.lambda timeout start)))] - [(v2 v2-transitional) ; XXX: Undocumented + [(v2 v2-transitional) ; XXX: Depreciate v2-transitional (let ([start (dynamic-require module-name 'start)] [manager (with-handlers ([exn:fail:contract? @@ -316,10 +314,8 @@ [(response? s) (make-servlet (current-custodian) (current-namespace) - (create-timeout-manager - default-servlet-instance-expiration-handler - timeouts-servlet-connection - timeouts-default-servlet) + (create-none-manager + default-servlet-instance-expiration-handler) (v0.response->v1.lambda s a-path))] [else (error 'load-servlet/path "Loading ~e produced ~n~e~n instead of a servlet." a-path s)]))) diff --git a/collects/web-server/docs/reference/dispatchers.scrbl b/collects/web-server/docs/reference/dispatchers.scrbl index 2160b95a0d..5675f41cb2 100644 --- a/collects/web-server/docs/reference/dispatchers.scrbl +++ b/collects/web-server/docs/reference/dispatchers.scrbl @@ -43,6 +43,49 @@ different. For example, it may apply some test to the request object, perhaps checking for a valid source IP address, and error if the test is not passed, and call @scheme[next-dispatcher] otherwise. +@; ------------------------------------------------------------ +@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. + +@; XXX Change to listof path? +@defthing[url-path? contract?]{ + This contract is equivalent to @scheme[((url?) . ->* . (path? list?))]. + The returned @scheme[path?] is the path on disk. The list is the list of + path elements that correspond to the path of the URL.} + +@defproc[(make-url->path (base path?)) + url-path?]{ + The @scheme[url-path?] returned by this procedure considers the root + URL to be @scheme[base]. It ensures that @scheme[".."]s in the URL + do not escape the @scheme[base].} + +@; XXX Rename to /valid +@defproc[(make-url-path/optimism (url->path url->path?)) + url->path?]{ + Runs the underlying @scheme[url->path], but only returns if the path + refers to a file that actually exists. If it is does not, then the suffix + elements of the URL are removed until a file is found. If this never occurs, + then an error is thrown. + + This is primarily useful for dispatchers that allow path information after + the name of a service to be used for data, but where the service is represented + by a file. The most prominent example is obviously servlets.} + +@; ------------------------------------------------------------ +@section[#:tag "dispatch-sequencer.ss"]{Sequencing} + +@file{dispatchers/dispatch-sequencer.ss} defines a dispatcher constructor +that invokes a sequence of dispatchers until one applies. + +@defproc[(make (dispatcher dispatcher?) ...0) + dispatcher?]{ + Invokes each @scheme[dispatcher], invoking the next if the first + calls @scheme[next-dispatcher]. If no @scheme[dispatcher] applies, + then it calls @scheme[next-dispatcher] itself. +} + @; XXX Rename const to lift @; ------------------------------------------------------------ @section[#:tag "dispatch-const.ss"]{Lifting Procedures} @@ -55,28 +98,6 @@ otherwise. object, and outputs the response to the connection. } -@; ------------------------------------------------------------ -@section[#:tag "dispatch-files.ss"]{Serving Files} - -@file{dispatchers/dispatch-files.ss} allows files to be served. -It defines a dispatcher construction procedure: - -@; XXX Change mime-types-path to path->mime-type -@; XXX Include make-get-mime-type -@defproc[(make [#:url->path url->path url->path?] - [#:mime-types-path mime-types-path path-string? "mime.types"] - [#:indices indices (listof string?) (list "index.html" "index.htm")]) - dispatcher?]{ - Uses @scheme[url->path] to extract a path from the URL in the request - object. If this path does not exist, then the dispatcher does not apply. - If the path is a directory, then the @scheme[indices] are checked in order - for an index file to serve. In that case, or in the case of a path that is - a file already, the @scheme[mime-types-path] file is consulted for the MIME - Type of the path, via @scheme[make-get-mime-type]. The file is then - streamed out the connection object. - - This dispatcher supports HTTP Range GET requests and HEAD requests.} - @; XXX Change filtering to take predicate, rather than regexp @; ------------------------------------------------------------ @section[#:tag "dispatch-filter.ss"]{Filtering Requests} @@ -92,45 +113,21 @@ with all requests that pass a predicate. } @; ------------------------------------------------------------ -@section[#:tag "dispatch-host.ss"]{Virtual Hosts} +@section[#:tag "dispatch-pathprocedure.ss"]{Procedure Invocation upon Request} -@file{dispatchers/dispatch-host.ss} defines a dispatcher constructor -that calls a different dispatcher based upon the host requested. +@file{dispatchers/dispatch-pathprocedure.ss} defines a dispatcher constructor +for invoking a particular procedure when a request is given to a particular +URL path. -@defproc[(make (lookup-dispatcher (symbol? . -> . dispatcher?))) +@defproc[(make (path string?) (proc (request? . -> . response?))) dispatcher?]{ - Extracts a host from the URL requested, or the Host HTTP header, - calls @scheme[lookup-dispatcher] with the host, and invokes the - returned dispatcher. If no host can be extracted, then @scheme['] - is used. -} - -@; ------------------------------------------------------------ -@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. - -@; XXX Don't include timeout logic in here, put it outside. -@; XXX Include configuration.scrbl exports -@defproc[(make [#:url->path url->path url->path?] - [#:make-servlet-namespace make-servlet-namespace - make-servlet-namespace? - (make-make-servlet-namespace)] - [#:timeouts-servlet-connection timeouts-servlet-connection integer? (* 60 60 24)] - [#:responders-servlet-loading responders-servlet-loading servlet-loading-responder] - [#:responders-servlet responders-servlet (gen-servlet-responder "servlet-error.html")]) - dispatcher?]{ - Extends the timeout of the connection by @scheme[timeouts-servlet-connection]. - If the request URL contains a serialized continuation, then it is invoked with the - request. Otherwise, @scheme[url->path] is used to resolve the URL to a path. - The path is evaluated as a module, in a namespace constructed by @scheme[make-servlet-namespace]. - If this fails then @scheme[responders-servlet-loading] is used to format a response - with the exception. If it succeeds, then @scheme[start] export of the module is invoked. - If there is an error when a servlet is invoked, then @scheme[responders-servlet] is - used to format a response with the exception. -} - + Checks if the request URL path as a string is equal to @scheme[path] + and if so, calls @scheme[proc] for a response. +} + +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-log.ss"]{Logging} @@ -185,36 +182,43 @@ that performs HTTP Basic authentication filtering. requests credentials. If they are, then @scheme[next-dispatcher] is invoked. } - + @; ------------------------------------------------------------ -@section[#:tag "dispatch-pathprocedure.ss"]{Procedure Invocation upon Request} +@section[#:tag "dispatch-host.ss"]{Virtual Hosts} -@file{dispatchers/dispatch-pathprocedure.ss} defines a dispatcher constructor -for invoking a particular procedure when a request is given to a particular -URL path. +@file{dispatchers/dispatch-host.ss} defines a dispatcher constructor +that calls a different dispatcher based upon the host requested. -@defproc[(make (path string?) (proc (request? . -> . response?))) +@defproc[(make (lookup-dispatcher (symbol? . -> . dispatcher?))) dispatcher?]{ - Checks if the request URL path as a string is equal to @scheme[path] - and if so, calls @scheme[proc] for a response. -} - -This is used in the standard @file{web-server} pipeline to provide -a URL that refreshes the password file, servlet cache, etc. + Extracts a host from the URL requested, or the Host HTTP header, + calls @scheme[lookup-dispatcher] with the host, and invokes the + returned dispatcher. If no host can be extracted, then @scheme['] + is used. +} + +@; ------------------------------------------------------------ +@section[#:tag "dispatch-files.ss"]{Serving Files} + +@file{dispatchers/dispatch-files.ss} allows files to be served. +It defines a dispatcher construction procedure: + +@; XXX Change mime-types-path to path->mime-type +@; XXX Include make-get-mime-type +@defproc[(make [#:url->path url->path url->path?] + [#:mime-types-path mime-types-path path-string? "mime.types"] + [#:indices indices (listof string?) (list "index.html" "index.htm")]) + dispatcher?]{ + Uses @scheme[url->path] to extract a path from the URL in the request + object. If this path does not exist, then the dispatcher does not apply. + If the path is a directory, then the @scheme[indices] are checked in order + for an index file to serve. In that case, or in the case of a path that is + a file already, the @scheme[mime-types-path] file is consulted for the MIME + Type of the path, via @scheme[make-get-mime-type]. The file is then + streamed out the connection object. -@; ------------------------------------------------------------ -@section[#:tag "dispatch-sequencer.ss"]{Sequencing} - -@file{dispatchers/dispatch-sequencer.ss} defines a dispatcher constructor -that invokes a sequence of dispatchers until one applies. - -@defproc[(make (dispatcher dispatcher?) ...0) - dispatcher?]{ - Invokes each @scheme[dispatcher], invoking the next if the first - calls @scheme[next-dispatcher]. If no @scheme[dispatcher] applies, - then it calls @scheme[next-dispatcher] itself. -} - + This dispatcher supports HTTP Range GET requests and HEAD requests.} + @; ------------------------------------------------------------ @section[#:tag "dispatch-servlets.ss"]{Serving Scheme Servlets} @@ -262,33 +266,29 @@ that runs servlets written in Scheme. Servlets that do not specify timeouts are given timeouts according to @scheme[timeouts-default-servlet]. } - + @; ------------------------------------------------------------ -@section[#:tag "filesystem-map.ss"]{Mapping URLs to Paths} +@section[#:tag "dispatch-lang.ss"]{Serving Web Language Servlets} -@file{dispatchers/filesystem-map.ss} provides a means of mapping -URLs to paths on the filesystem. +@file{dispatchers/dispatch-lang.ss} defines a dispatcher constructor +that runs servlets written in the Web Language. -@; XXX Change to listof path? -@defthing[url-path? contract?]{ - This contract is equivalent to @scheme[((url?) . ->* . (path? list?))]. - The returned @scheme[path?] is the path on disk. The list is the list of - path elements that correspond to the path of the URL.} - -@defproc[(make-url->path (base path?)) - url-path?]{ - The @scheme[url-path?] returned by this procedure considers the root - URL to be @scheme[base]. It ensures that @scheme[".."]s in the URL - do not escape the @scheme[base].} - -@; XXX Rename to /valid -@defproc[(make-url-path/optimism (url->path url->path?)) - url->path?]{ - Runs the underlying @scheme[url->path], but only returns if the path - refers to a file that actually exists. If it is does not, then the suffix - elements of the URL are removed until a file is found. If this never occurs, - then an error is thrown. - - This is primarily useful for dispatchers that allow path information after - the name of a service to be used for data, but where the service is represented - by a file. The most prominent example is obviously servlets.} \ No newline at end of file +@; XXX Don't include timeout logic in here, put it outside. +@; XXX Include configuration.scrbl exports +@defproc[(make [#:url->path url->path url->path?] + [#:make-servlet-namespace make-servlet-namespace + make-servlet-namespace? + (make-make-servlet-namespace)] + [#:timeouts-servlet-connection timeouts-servlet-connection integer? (* 60 60 24)] + [#:responders-servlet-loading responders-servlet-loading servlet-loading-responder] + [#:responders-servlet responders-servlet (gen-servlet-responder "servlet-error.html")]) + dispatcher?]{ + Extends the timeout of the connection by @scheme[timeouts-servlet-connection]. + If the request URL contains a serialized continuation, then it is invoked with the + request. Otherwise, @scheme[url->path] is used to resolve the URL to a path. + The path is evaluated as a module, in a namespace constructed by @scheme[make-servlet-namespace]. + If this fails then @scheme[responders-servlet-loading] is used to format a response + with the exception. If it succeeds, then @scheme[start] export of the module is invoked. + If there is an error when a servlet is invoked, then @scheme[responders-servlet] is + used to format a response with the exception. +} diff --git a/collects/web-server/docs/reference/lang.scrbl b/collects/web-server/docs/reference/lang.scrbl index 11a2dc069d..d9a763aead 100644 --- a/collects/web-server/docs/reference/lang.scrbl +++ b/collects/web-server/docs/reference/lang.scrbl @@ -1,7 +1,7 @@ #reader(lib "docreader.ss" "scribble") @require["../web-server.ss"] -@title[#:style 'toc]{Web Language} +@title[#:style 'toc]{Web Language Servlets} XXX diff --git a/collects/web-server/docs/reference/reference.scrbl b/collects/web-server/docs/reference/reference.scrbl index 77794a8d5a..233eb46ab0 100644 --- a/collects/web-server/docs/reference/reference.scrbl +++ b/collects/web-server/docs/reference/reference.scrbl @@ -13,10 +13,13 @@ develop Web applications in Scheme. @include-section["dispatchers.scrbl"] @include-section["web-config-unit.scrbl"] @include-section["web-server-unit.scrbl"] -@include-section["servlet.scrbl"] -@include-section["servlet-env.scrbl"] @include-section["managers.scrbl"] +@include-section["servlet-env.scrbl"] + +@include-section["servlet.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/servlet-env.scrbl b/collects/web-server/docs/reference/servlet-env.scrbl index 327bcf12a0..0fb74b70d0 100644 --- a/collects/web-server/docs/reference/servlet-env.scrbl +++ b/collects/web-server/docs/reference/servlet-env.scrbl @@ -3,11 +3,18 @@ @title[#:style 'toc]{Servlet Environment} -XXX +The @file{web-server} provides a means of running Scheme servlets +from within DrScheme, or any other REPL. -@local-table-of-contents[] +@file{servlet-env.ss} provides the servlet API from @file{servlet.ss} +as well as the following special forms: -@; ------------------------------------------------------------ -@section[#:tag "example"]{Example} +@defform[(on-web servlet-expr)]{This expands to @scheme[(on-web 8000 servlet-expr)].} -XXX \ No newline at end of file +@defform[(on-web port servlet-expr)]{ + This constructs a small servlet, where the body of the @scheme[start] procedure is + @scheme[servlet-expr], runs the @file{web-server} on port @scheme[port], and opens + a browser to a URL accessing the constructed servlet. The call blocks until the + servlet finishes its computation, i.e. @scheme[servlet-expr] is evaluated, and + returns its result. +} \ No newline at end of file diff --git a/collects/web-server/docs/reference/servlet.scrbl b/collects/web-server/docs/reference/servlet.scrbl index 412120aa65..571c43d8c4 100644 --- a/collects/web-server/docs/reference/servlet.scrbl +++ b/collects/web-server/docs/reference/servlet.scrbl @@ -1,13 +1,95 @@ #reader(lib "docreader.ss" "scribble") @require["../web-server.ss"] -@title[#:style 'toc]{Servlets} +@title[#:style 'toc]{Scheme Servlets} -XXX +The @file{web-server} allows servlets to be written in Scheme. It +provides the supporting API, described below, for the construction +of these servlets. @local-table-of-contents[] @; ------------------------------------------------------------ -@section[#:tag "example"]{Example} +@section[#:tag "module-servlets"]{Definition} + +A @defterm{servlet} is a module that provides the following: + +@defthing[interface-version symbol?]{ + A symbol indicating the servlet interface the servlet conforms + to. This influences the other provided identifiers. +} + +If @scheme[interface-version] is @scheme['v1], then the servlet +provides: + +@defthing[timeout integer?]{ + This number is used as the @scheme[continuation-timeout] argument to + a timeout-based continuation manager used for this servlet. (See + @secref["timeouts.ss"].) +} + +@defproc[(start [initial-request request?]) + response?]{ + This function is called when an instance of this servlet is started. + The argument is the HTTP request that initiated the instance. +} + +If @scheme[interface-version] is @scheme['v2], then the servlet +provides: + +@defthing[manager manager?]{ + The manager for the continuations of this servlet. +} + +@defproc[(start [initial-request request?]) + response?]{ + This function is called when an instance of this servlet is started. + The argument is the HTTP request that initiated the instance. +} + +@; ------------------------------------------------------------ +@section[#:tag "servlet-structs.ss"]{Contracts} + +XXX + +@; ------------------------------------------------------------ +@section[#:tag "request-structs.ss"]{HTTP Requests} + +XXX + +@; ------------------------------------------------------------ +@section[#:tag "bindings.ss"]{Request Bindings} + +XXX + +@; ------------------------------------------------------------ +@section[#:tag "response-structs.ss"]{HTTP Responses} + +XXX + +@; ------------------------------------------------------------ +@section[#:tag "web.ss"]{Web} + +XXX + +@; ------------------------------------------------------------ +@section[#:tag "helpers.ss"]{Helpers} + +XXX + +@; XXX Depreciate +@; ------------------------------------------------------------ +@section[#:tag "servlet-url.ss"]{Servlet URLs} + +XXX + +@; ------------------------------------------------------------ +@section[#:tag "basic-auth.ss"]{Basic Authentication} + +XXX + +@; ------------------------------------------------------------ +@section[#:tag "web-cells.ss"]{Web Cells} + +XXX -XXX \ No newline at end of file diff --git a/collects/web-server/docs/reference/web-config-unit.scrbl b/collects/web-server/docs/reference/web-config-unit.scrbl index 4afbb7202a..68bc825cb9 100644 --- a/collects/web-server/docs/reference/web-config-unit.scrbl +++ b/collects/web-server/docs/reference/web-config-unit.scrbl @@ -3,11 +3,65 @@ @title[#:style 'toc]{Web Config Unit} -XXX +The @file{web-server} offers a unit-based approach to configuring the server. -@local-table-of-contents[] +@file{web-config-sig.ss} provides the signature +@defthing[web-config^ signature?] signature, which contains the following +identifiers: -@; ------------------------------------------------------------ -@section[#:tag "example"]{Example} +@defthing[max-waiting integer?]{ + Passed to @scheme[tcp-accept]. +} -XXX \ No newline at end of file +@defthing[virtual-hosts (listof (cons/c string? host-table?))]{ + Contains the configuration of individual virtual hosts. +} + +@; XXX Remove access +@defthing[access any/c]{Unused.} + +@defthing[scripts (box/c (cache-table? path? servlet?))]{ + Contains initially loaded servlets. +} + +@defthing[initial-connection-timeout integer?]{ + Specifies the initial timeout given to a connection. +} + +@defthing[port (between/c 1 65535)]{ + Specifies the port to serve HTTP on. +} + +@defthing[listen-ip string?]{ + Passed to @scheme[tcp-accept]. +} + +@; XXX Remove instances +@defthing[instances any/c]{Unused.} + +@defthing[make-servlet-namespace make-servlet-namespace?]{ + Passed to @scheme[servlets:make]. +} + +@file{web-config-unit.ss} provides the following: + +@; XXX Move to configuration/configuration-table.ss +@defthing[default-configuration-table-path path?]{The default configuration table.} + +@; XXX Make port? +@defproc[(configuration-table->web-config\@ [path path?] + [#:port port (or/c false/c (between/c 1 65535)) #f] + [#:listen-ip listen-ip (or/c false/c string?) #f] + [#:make-servlet-namespace make-servlet-namespace make-servlet-namespace? (make-make-servlet-namespace)]) + (unit? web-config^)]{ + Reads the S-expression at @scheme[path] and calls @scheme[configuration-table-sexpr->web-config\@] appropriately. +} + +@defproc[(configuration-table-sexpr->web-config\@ [sexpr list?] + [#:web-server-root web-server-root path? (directory-part default-configuration-table-path)] + [#:port port (or/c false/c (between/c 1 65535)) #f] + [#:listen-ip listen-ip (or/c false/c string?) #f] + [#:make-servlet-namespace make-servlet-namespace make-servlet-namespace? (make-make-servlet-namespace)]) + (unit? web-config^)]{ + Parses @scheme[sexpr] as a configuration-table and constructs a @scheme[web-config^] unit. +} diff --git a/collects/web-server/run.ss b/collects/web-server/run.ss index 8b8dc8a6bd..253b902733 100644 --- a/collects/web-server/run.ss +++ b/collects/web-server/run.ss @@ -1,3 +1,4 @@ +; This file is intended to be copied and/or modified and used as a template. (module run mzscheme (require (lib "cmdline.ss") (lib "file.ss") diff --git a/collects/web-server/servlet-env.ss b/collects/web-server/servlet-env.ss index 81758cb9b4..811edb5b2d 100644 --- a/collects/web-server/servlet-env.ss +++ b/collects/web-server/servlet-env.ss @@ -12,6 +12,7 @@ (provide (rename on-web:syntax on-web) (all-from "servlet.ss")) + ; XXX Change to setup temporary file and special dispatcher (define-syntax (on-web:syntax stx) (syntax-case stx () [(on-web:syntax servlet-expr) diff --git a/collects/web-server/web-config-unit.ss b/collects/web-server/web-config-unit.ss index 797b9f63dd..979e7a733f 100644 --- a/collects/web-server/web-config-unit.ss +++ b/collects/web-server/web-config-unit.ss @@ -51,14 +51,12 @@ (gen-virtual-hosts expanded-virtual-host-table default-host) bct-keys)) - (define default-make-servlet-namespace (make-make-servlet-namespace)) - ; : configuration-table host-table -> configuration (define/kw (build-configuration table the-virtual-hosts #:key [port #f] [listen-ip #f] - [make-servlet-namespace default-make-servlet-namespace]) + [make-servlet-namespace (make-make-servlet-namespace)]) (define the-port (or port (configuration-table-port table))) (define the-listen-ip (or listen-ip #f)) (define the-make-servlet-namespace make-servlet-namespace)