294 lines
13 KiB
Racket
294 lines
13 KiB
Racket
#reader(lib "docreader.ss" "scribble")
|
|
@require["../web-server.ss"]
|
|
|
|
@title[#:style 'toc]{Dispatchers}
|
|
|
|
The @file{web-server} is really just a peculiar configuration of a
|
|
dispatching server. There are a number of dispatchers that are defined
|
|
to support the @file{web-server}. Other dispatching servers, or variants
|
|
of the @file{web-server}, may find these useful. In particular, if you want
|
|
a peculiar processing pipeline for your @file{web-server} installation, this
|
|
documentation will be useful.
|
|
|
|
@local-table-of-contents[]
|
|
|
|
@; XXX Include connection? and request?
|
|
|
|
@; ------------------------------------------------------------
|
|
@section[#:tag "dispatch.ss"]{General}
|
|
|
|
@file{dispatchers/dispatch.ss} provides a few functions for dispatchers in general.
|
|
|
|
@defthing[dispatcher? contract?]{
|
|
Equivalent to @scheme[(connection? request? . -> . void)].
|
|
}
|
|
|
|
@defproc[(dispatcher-interface-version? (any any/c)) boolean?]{
|
|
Returns @scheme[#t] if @scheme[any] is @scheme['v1]. Returns @scheme[#f] otherwise.
|
|
}
|
|
|
|
@defstruct[exn:dispatcher ()]{
|
|
An exception thrown to indicate that a dispatcher does not apply to a particular
|
|
request.
|
|
}
|
|
|
|
@defproc[(next-dispatcher) void]{
|
|
Raises a @scheme[exn:dispatcher]
|
|
}
|
|
|
|
As the @scheme[dispatcher?] contract suggests, a dispatcher is a function that takes a connection
|
|
and request object and does something to them. Mostly likely it will generate
|
|
some response and output it on the connection, but it may do something
|
|
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.
|
|
|
|
@; XXX Rename const to lift
|
|
@; ------------------------------------------------------------
|
|
@section[#:tag "dispatch-const.ss"]{Lifting Procedures}
|
|
|
|
@file{dispatchers/dispatch-const.ss} defines:
|
|
|
|
@defproc[(make (proc (request? . -> . response?)))
|
|
dispatcher?]{
|
|
Constructs a dispatcher that calls @scheme[proc] on the request
|
|
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}
|
|
|
|
@file{dispatchers/dispatch-filter.ss} defines a dispatcher constructer
|
|
that calls an underlying dispatcher
|
|
with all requests that pass a predicate.
|
|
|
|
@defproc[(make (regex regexp?) (inner dispatcher?))
|
|
dispatcher?]{
|
|
Calls @scheme[inner] if the URL path of the request, converted to
|
|
a string, matches @scheme[regex]. Otherwise, calls @scheme[next-dispatcher].
|
|
}
|
|
|
|
@; ------------------------------------------------------------
|
|
@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.
|
|
|
|
@defproc[(make (lookup-dispatcher (symbol? . -> . dispatcher?)))
|
|
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['<none>]
|
|
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.
|
|
}
|
|
|
|
@; ------------------------------------------------------------
|
|
@section[#:tag "dispatch-log.ss"]{Logging}
|
|
|
|
@file{dispatchers/dispatch-log.ss} defines a dispatcher constructer
|
|
for transparent logging of requests.
|
|
|
|
@; XXX Take formating procedure
|
|
@defproc[(make [#:log-format log-format symbol? 'parenthesized-default]
|
|
[#:log-path log-path (or/c path-string? false/c) #f])
|
|
dispatcher?]{
|
|
If @scheme[log-path] is not @scheme[#f] and @scheme[log-format] is
|
|
@scheme['parenthesized-default] or @scheme[extended], then the request
|
|
is logged to the @scheme[log-path]. In either case, @scheme[next-dispatcher]
|
|
is invoked after this.
|
|
|
|
If @scheme[log-format] is @scheme['parenthesized-default], then the
|
|
log looks like: @scheme[(list 'from (request-client-ip req)
|
|
'to (request-host-ip req)
|
|
'for (url->string (request-uri req)) 'at
|
|
(date->string (seconds->date (current-seconds)) #t))].
|
|
|
|
If @scheme[log-format] is @scheme['extended], then the log looks like:
|
|
@scheme[`((client-ip ,(request-client-ip req))
|
|
(host-ip ,(request-host-ip req))
|
|
(referer ,(or/c bytes? false/c))
|
|
(uri ,(url->string (request-uri req)))
|
|
(time ,(current-seconds)))].
|
|
}
|
|
|
|
@; ------------------------------------------------------------
|
|
@section[#:tag "dispatch-passwords.ss"]{Password Protection}
|
|
|
|
@file{dispatchers/dispatch-passwords.ss} defines a dispatcher constructor
|
|
that performs HTTP Basic authentication filtering.
|
|
|
|
@defproc[(make [#:password-file password-file path-string? "passwords"]
|
|
[#:password-connection-timeout password-connection-timeout integer? 300]
|
|
[#:authentication-responder
|
|
authentication-responder
|
|
((url url?) (header (cons/c symbol? string?)) . -> . response?)
|
|
(gen-authentication-responder "forbidden.html")])
|
|
(values (-> void)
|
|
dispatcher?)]{
|
|
The first returned value is a procedure that refreshes the password
|
|
file used by the dispatcher.
|
|
|
|
The dispatcher that is returned does the following:
|
|
Extends connection timeout by @scheme[password-connection-timeout].
|
|
Checks if the request contains Basic authentication credentials, and that
|
|
they are included in @scheme[password-file]. If they are not,
|
|
@scheme[authentication-responder] is called with a @scheme[header] that
|
|
requests credentials. If they are, then @scheme[next-dispatcher] is
|
|
invoked.
|
|
}
|
|
|
|
@; ------------------------------------------------------------
|
|
@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
|
|
URL path.
|
|
|
|
@defproc[(make (path string?) (proc (request? . -> . response?)))
|
|
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.
|
|
|
|
@; ------------------------------------------------------------
|
|
@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.
|
|
}
|
|
|
|
@; ------------------------------------------------------------
|
|
@section[#:tag "dispatch-servlets.ss"]{Serving Scheme Servlets}
|
|
|
|
@file{dispatchers/dispatch-servlets.ss} defines a dispatcher constructor
|
|
that runs servlets written in Scheme.
|
|
|
|
@; XXX Add default manager arg
|
|
@; XXX Remove config:instances
|
|
@; XXX Remove config:scripts
|
|
@; XXX Define make-servlet-namespace?
|
|
@defproc[(make [config:instances any/c]
|
|
[config:scripts (box/c cache-table?)]
|
|
[config:make-servlet-namespace make-servlet-namespace?]
|
|
[#:url->path url->path url->path?]
|
|
[#:responders-servlet-loading
|
|
responders-servlet-loading
|
|
((url url?) (exn any/c) . -> . response?)
|
|
servlet-loading-responder]
|
|
[#:responders-servlet
|
|
responders-servlet
|
|
((url url?) (exn any/c) . -> . response?)
|
|
(gen-servlet-responder "servlet-error.html")]
|
|
[#:timeouts-servlet-connection
|
|
timeouts-servlet-connection
|
|
integer?
|
|
(* 60 60 24)]
|
|
[#:timeouts-default-servlet
|
|
timeouts-default-servlet
|
|
integer?
|
|
30])
|
|
(values (-> void)
|
|
dispatcher?)]{
|
|
The first returned value is a procedure that refreshes the servlet
|
|
code cache.
|
|
|
|
The dispatcher does the following:
|
|
Extends the timeout of the connection by @scheme[timeouts-servlet-connection].
|
|
If the request URL contains a continuation reference, 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.
|
|
|
|
Servlets that do not specify timeouts are given timeouts according to @scheme[timeouts-default-servlet].
|
|
}
|
|
|
|
@; ------------------------------------------------------------
|
|
@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.} |