446 lines
16 KiB
Racket
446 lines
16 KiB
Racket
#reader(lib "docreader.ss" "scribble")
|
|
@require["../web-server.ss"]
|
|
|
|
@title[#:tag "servlet"
|
|
#:style 'toc]{Scheme Servlets}
|
|
|
|
The @file{web-server} allows servlets to be written in Scheme. It
|
|
provides the supporting API, described below, for the construction
|
|
of these servlets. This API is provided by @file{servlet.ss}.
|
|
|
|
@local-table-of-contents[]
|
|
|
|
@; ------------------------------------------------------------
|
|
@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}
|
|
|
|
@file{servlet/servlet-structs.ss} provides a number of contracts
|
|
for use in servlets.
|
|
|
|
@defthing[servlet-response? contract?]{Equivalent to @scheme[any/c].}
|
|
|
|
@; XXX Remove callbacks
|
|
@defproc[(xexpr/callback? [v any/c])
|
|
boolean?]{
|
|
Checks if @scheme[v] matches @scheme[xexpr?], except that embedded
|
|
procedures are allowed.
|
|
}
|
|
|
|
@defthing[response-generator? contract?]{Equivalent to @scheme[(k-url? . -> . servlet-response?)].}
|
|
|
|
@defthing[k-url? (any/c . -> . boolean?)]{Equivalent to @scheme[string?].}
|
|
|
|
@defthing[url-transform? contract?]{Equivalent to @scheme[(k-url? . -> . k-url?)].}
|
|
|
|
@defthing[expiration-handler? contract?]{Equivalent to @scheme[(or/c false/c (request? . -> . response?))].}
|
|
|
|
@defthing[embed/url? contract?]{Equivalent to @scheme[(((request? . -> . any/c)) (expiration-handler?) . opt-> . string?)].}
|
|
|
|
@; ------------------------------------------------------------
|
|
@section[#:tag "request-structs.ss"]{HTTP Requests}
|
|
|
|
@; XXX Create http sub-directory
|
|
@; XXX Have this include read-request and write-response
|
|
@file{private/request-structs.ss} provides a number of structures and functions
|
|
related to HTTP request data structures.
|
|
|
|
@defstruct[header ([field bytes?]
|
|
[value bytes?])]{
|
|
Represents a header of @scheme[field] to @scheme[value].
|
|
}
|
|
|
|
@defproc[(headers-assq [id bytes?] [heads (listof header?)])
|
|
(or/c false/c header?)]{
|
|
Returns the header with a field equal to @scheme[id] from @scheme[heads] or @scheme[#f].
|
|
}
|
|
|
|
@defproc[(headers-assq* [id bytes?] [heads (listof header?)])
|
|
(or/c false/c header?)]{
|
|
Returns the header with a field case-insensitively equal to @scheme[id] from @scheme[heads] or @scheme[#f].
|
|
}
|
|
|
|
@defstruct[binding ([id bytes?])]{Represents a binding of @scheme[id].}
|
|
|
|
@defstruct[(binding:form binding) ([id bytes?]
|
|
[value bytes?])]{
|
|
Represents a form binding of @scheme[id] to @scheme[value].
|
|
}
|
|
|
|
@defstruct[(binding:file binding) ([id bytes?]
|
|
[filename bytes?]
|
|
[content bytes?])]{
|
|
Represents the uploading of the file @scheme[filename] with the id @scheme[id]
|
|
and the content @scheme[content].
|
|
}
|
|
|
|
@defproc[(bindings-assq [id bytes?] [binds (listof binding?)])
|
|
(or/c false/c binding?)]{
|
|
Returns the binding with an id equal to @scheme[id] from @scheme[binds] or @scheme[#f].
|
|
}
|
|
|
|
@; XXX Subtypes of request
|
|
@defstruct[request ([method symbol?]
|
|
[uri url?]
|
|
[headers/raw (listof header?)]
|
|
[bindings/raw (listof binding?)]
|
|
[post-data/raw (or/c false/c bytes?)]
|
|
[host-ip string?]
|
|
[host-port number?]
|
|
[client-ip string?])]{
|
|
An HTTP @scheme[method] request to @scheme[uri] from @scheme[client-ip]
|
|
to the server at @scheme[host-ip]:@scheme[host-port] with @scheme[headers/raw]
|
|
headers, @scheme[bindings/raw] GET and POST queries and @scheme[post-data/raw]
|
|
POST data.
|
|
}
|
|
|
|
@; ------------------------------------------------------------
|
|
@section[#:tag "bindings.ss"]{Request Bindings}
|
|
|
|
@file{servlet/bindings.ss} provides a number of helper functions
|
|
for accessing request bindings.
|
|
|
|
@; XXX Move in request-bindings
|
|
@; XXX Rename extract-binding
|
|
@defproc[(extract-binding/single [id symbol?]
|
|
[binds (listof (cons/c symbol? string?))])
|
|
string?]{
|
|
Returns the single binding associated with @scheme[id] in the a-list @scheme[binds]
|
|
if there is exactly one binding. Otherwise errors.
|
|
}
|
|
|
|
@defproc[(extract-bindings [id symbol?]
|
|
[binds (listof (cons/c symbol? string?))])
|
|
(listof string?)]{
|
|
Returns a list of all the bindings of @scheme[id] in the a-list @scheme[binds].
|
|
}
|
|
|
|
@defproc[(exists-binding? [id symbol?]
|
|
[binds (listof (cons/c symbol? string))])
|
|
boolean?]{
|
|
Returns @scheme[#t] if @scheme[binds] contains a binding for @scheme[id].
|
|
Otherwise, @scheme[#f].
|
|
}
|
|
|
|
@; ------------------------------------------------------------
|
|
@section[#:tag "response-structs.ss"]{HTTP Responses}
|
|
|
|
@file{private/response-structs.ss} provides structures and functions related to
|
|
HTTP responses.
|
|
|
|
@; XXX Rename extras to headers
|
|
@; XXX Make extras a listof header?
|
|
@defstruct[response/basic
|
|
([code number?]
|
|
[message string?]
|
|
[seconds number?]
|
|
[mime bytes?]
|
|
[extras (listof (cons/c symbol? string?))])]{
|
|
A basic HTTP response containing no body. @scheme[code] is the response code,
|
|
@scheme[message] the message, @scheme[seconds] the generation time, @scheme[mime]
|
|
the MIME type of the file, and @scheme[extras] are the extra headers, in addition
|
|
to those produced by the server.
|
|
}
|
|
|
|
@; XXX Rename string? option
|
|
@; XXX Format warning cool.
|
|
@defstruct[(response/full response/basic)
|
|
([code number?]
|
|
[message string?]
|
|
[seconds number?]
|
|
[mime bytes?]
|
|
[extras (listof (cons/c symbol? string?))]
|
|
[body (listof (or/c string? bytes?))])]{
|
|
As with @scheme[response/basic], except with @scheme[body] as the response
|
|
body.
|
|
}
|
|
|
|
@defstruct[(response/incremental response/basic)
|
|
([code number?]
|
|
[message string?]
|
|
[seconds number?]
|
|
[mime bytes?]
|
|
[extras (listof (cons/c symbol? string?))]
|
|
[generator ((() (listof (or/c bytes? string?)) . ->* . any) . -> . any)])]{
|
|
As with @scheme[response/basic], except with @scheme[generator] as a function that is
|
|
called to generate the response body, by being given an @scheme[output-response] function
|
|
that outputs the content it is called with.
|
|
}
|
|
|
|
@defproc[(response? [v any/c])
|
|
boolean?]{
|
|
Checks if @scheme[v] is a valid response. A response is either:
|
|
@itemize[
|
|
@item{A @scheme[response/basic] structure.}
|
|
@item{A value matching the contract @scheme[(cons/c (or/c bytes? string?) (listof (or/c bytes? string?)))].}
|
|
@item{A value matching @scheme[xexpr?].}
|
|
]
|
|
}
|
|
|
|
@defthing[TEXT/HTML-MIME-TYPE bytes?]{Equivalent to @scheme[#"text/html; charset=utf-8"].}
|
|
|
|
Warning: If you include a Length header in a response that is inaccurate, there WILL be an error in
|
|
transmission that the server will not catch.
|
|
|
|
@; ------------------------------------------------------------
|
|
@section[#:tag "web.ss"]{Web}
|
|
|
|
@file{servlet/web.ss} provides the primary functions of interest for the
|
|
servlet developer.
|
|
|
|
@; XXX Contract harder
|
|
@defproc[(send/back [response any/c])
|
|
void?]{
|
|
Sends @scheme[response] to the client.
|
|
}
|
|
|
|
@defthing[current-servlet-continuation-expiration-handler parameter?]{
|
|
Holds the @scheme[expiration-handler?] to be used when a continuation
|
|
captured in this context is expired, then looked up.
|
|
}
|
|
|
|
@defproc[(send/suspend [make-response response-generator?]
|
|
[exp expiration-handler? (current-servlet-continuation-expiration-handler)])
|
|
request?]{
|
|
Captures the current continuation, stores it with @scheme[exp] as the expiration
|
|
handler, and binds it to a URL. @scheme[make-response] is called with this URL and
|
|
is expected to generate a @scheme[response?], which is sent to the client. If the
|
|
continuation URL is invoked, the captured continuation is invoked and the request is
|
|
returned from this call to @scheme[send/suspend].
|
|
}
|
|
|
|
@defproc[(continuation-url? [u url?])
|
|
(or/c false/c (list/c number? number? number?))]{
|
|
Checks if @scheme[u] is a URL that refers to a continuation, if so
|
|
returns the instance id, continuation id, and nonce.
|
|
}
|
|
|
|
@; XXX Move
|
|
@defproc[(adjust-timeout! [t number?])
|
|
void?]{
|
|
Calls the servlet's manager's @scheme[adjust-timeout!] function.
|
|
}
|
|
|
|
@defproc[(clear-continuation-table!)
|
|
void?]{
|
|
Calls the servlet's manager's @scheme[clear-continuation-table!] function.
|
|
}
|
|
|
|
@defproc[(send/forward [make-response response-generator?]
|
|
[exp expiration-handler? (current-servlet-continuation-expiration-handler)])
|
|
request?]{
|
|
Calls @scheme[clear-continuation-table!], then @scheme[send/suspend].
|
|
}
|
|
|
|
@; XXX Contract harder
|
|
@defproc[(send/finish [response any/c])
|
|
void?]{
|
|
Calls @scheme[clear-continuation-table!], then @scheme[send/back].
|
|
}
|
|
|
|
@defproc[(send/suspend/dispatch [make-response (embed/url? . -> . servlet-response?)])
|
|
any/c]{
|
|
Calls @scheme[make-response] with a function that, when called with a procedure from
|
|
@scheme[request?] to @scheme[any/c] will generate a URL, that when invoked will call
|
|
the function with the @scheme[request?] object and return the result to the caller of
|
|
@scheme[send/suspend/dispatch].
|
|
}
|
|
|
|
@; XXX Remove
|
|
@defproc[(xexpr/callback->xexpr [embed/url embed/url?]
|
|
[xexpr/c xexpr/callback?])
|
|
xexpr?]{
|
|
Replaces the procedures in @scheme[xexpr/c] with URLs through @scheme[embed/url].
|
|
}
|
|
|
|
@defproc[(send/suspend/callback [xexpr/c xexpr/callback?])
|
|
any/c]{
|
|
Calls @scheme[send/suspend/dispatch] and @scheme[xexpr/callback->xexpr].
|
|
}
|
|
|
|
@defproc[(redirect/get)
|
|
request?]{
|
|
Calls @scheme[send/suspend] with @scheme[redirect-to].
|
|
}
|
|
|
|
@defproc[(redirect/get/forget)
|
|
request?]{
|
|
Calls @scheme[send/forward] with @scheme[redirect-to].
|
|
}
|
|
|
|
@; XXX Remove
|
|
@defproc[(embed-ids [ids (list/c number? number? number?)]
|
|
[u url?])
|
|
string?]{
|
|
Creates a @scheme[continuation-url?].
|
|
}
|
|
|
|
@; XXX Remove
|
|
@defthing[current-url-transform parameter?]{
|
|
Holds a @scheme[url-transform?] function that is called by
|
|
@scheme[send/suspend] to transform the URLs it generates.
|
|
}
|
|
|
|
@; ------------------------------------------------------------
|
|
@section[#:tag "helpers.ss"]{Helpers}
|
|
|
|
@file{servlet/helpers.ss} provides functions built on
|
|
@file{servlet/web.ss} that are useful in many servlets.
|
|
|
|
@; XXX Move into binding.ss
|
|
@defproc[(request-bindings [req request?])
|
|
(listof (or/c (cons/c symbol? string?)
|
|
(cons/c symbol? bytes?)))]{
|
|
Translates the @scheme[request-bindings/raw] of @scheme[req] by
|
|
interpreting @scheme[bytes?] as @scheme[string?]s, except in the case
|
|
of @scheme[binding:file] bindings, which are left as is. Ids are then
|
|
translated into lowercase symbols.
|
|
}
|
|
|
|
@defproc[(request-headers [req request?])
|
|
(listof (cons/c symbol? string?))]{
|
|
Translates the @scheme[request-headers/raw] of @scheme[req] by
|
|
interpreting @scheme[bytes?] as @scheme[string?]s. Ids are then
|
|
translated into lowercase symbols.
|
|
}
|
|
|
|
These functions, while convenient, could introduce subtle bugs in your
|
|
application. Examples: the fact they are case-insensitive could introduce
|
|
a bug; if the data submitted is not in UTF-8 format, then the conversion
|
|
to a string will fail; if an attacked submits a form field as if it were
|
|
a file, when it is not, then the @scheme[request-bindings] will hold a
|
|
@scheme[bytes?] object and your program will error; and, for file uploads
|
|
you lose the filename.
|
|
|
|
@; XXX Move into http/response.ss
|
|
@; XXX Change headers
|
|
@defproc[(redirect-to [uri string?]
|
|
[perm/temp redirection-status? temporarily]
|
|
[#:headers headers (listof (cons/c symbol? string?)) (list)])
|
|
response?]{
|
|
Generates an HTTP response that redirects the browser to @scheme[uri],
|
|
while including the @scheme[headers] in the response.
|
|
}
|
|
|
|
@defproc[(redirection-status? [v any/c])
|
|
boolean?]{
|
|
Determines if @scheme[v] is one of the following values.
|
|
}
|
|
|
|
@defthing[permanently redirection-status?]{A @scheme[redirection-status?] for permanent redirections.}
|
|
|
|
@defthing[temporarily redirection-status?]{A @scheme[redirection-status?] for temporary redirections.}
|
|
|
|
@defthing[see-other redirection-status?]{A @scheme[redirection-status?] for "see-other" redirections.}
|
|
|
|
@defproc[(with-errors-to-browser [send/finish-or-back (response? . -> . void?)]
|
|
[thunk (-> any)])]{
|
|
Calls @scheme[thunk] with an exception handler that generates an HTML error page
|
|
and calls @scheme[send/finish-or-back].
|
|
}
|
|
|
|
@; XXX Depreciate
|
|
@; ------------------------------------------------------------
|
|
@section[#:tag "servlet-url.ss"]{Servlet URLs}
|
|
|
|
@file{servlet/servlet-url.ss} provides a function that might be useful to you.
|
|
This will be collapsed somewhere else eventually.
|
|
|
|
@defproc[(request->servlet-url (req request?))
|
|
servlet-url?]{Generates a value to be passed to the next function.}
|
|
|
|
@defproc[(servlet-url->url-string/no-continuation [su servlet-url?])
|
|
string?]{
|
|
Returns a URL string without the continuation information in the URL
|
|
that went into @scheme[su]
|
|
}
|
|
|
|
@; XXX Support Digest
|
|
@; ------------------------------------------------------------
|
|
@section[#:tag "basic-auth.ss"]{Basic Authentication}
|
|
|
|
@file{servlet/basic-auth.ss} provides a function for helping with
|
|
implementation of HTTP Basic Authentication.
|
|
|
|
@defproc[(extract-user-pass [heads (listof header?)])
|
|
(or/c false/c (cons/c bytes? bytes?))]{
|
|
Returns a pair of the username and password from the authentication
|
|
header in @scheme[heads] if they are present, or @scheme[#f]
|
|
}
|
|
|
|
@; ------------------------------------------------------------
|
|
@section[#:tag "web-cells.ss"]{Web Cells}
|
|
|
|
@; XXX Cite paper
|
|
@file{servlet/web-cell.ss} provides the interface to web cells.
|
|
|
|
A web cell is a kind of state defined relative to the @defterm{frame tree}.
|
|
The frame-tree is a mirror of the user's browsing session. Every time a
|
|
continuation is invoked, a new frame (called the @defterm{current frame}) is
|
|
created as a child of the current frame when the continuation was captured.
|
|
|
|
You should use web cells if you want an effect to be encapsulated in all
|
|
interactions linked from (in a transitive sense) the HTTP response being
|
|
generated.
|
|
|
|
@; XXX Document with-frame and with-frame-after?
|
|
|
|
@defproc[(web-cell? [v any/c])
|
|
boolean?]{
|
|
Determines if @scheme[v] is a web-cell.
|
|
}
|
|
|
|
@defproc[(make-web-cell [v any/c])
|
|
web-cell?]{
|
|
Creates a web-cell with a default value of @scheme[v].
|
|
}
|
|
|
|
@defproc[(web-cell-ref [wc web-cell?])
|
|
any/c]{
|
|
Looks up the value of @scheme[wc] found in the nearest
|
|
frame.
|
|
}
|
|
|
|
@defproc[(web-cell-shadow [wc web-cell?]
|
|
[v any/c])
|
|
void]{
|
|
Binds @scheme[wc] to @scheme[v] in the current frame, shadowing any
|
|
other bindings to @scheme[wc] in the current frame.
|
|
}
|