(lispkit http server)

Library (lispkit http server) implements a simple multi-threaded HTTP server which can be freely configured for different use cases. The HTTP server allows two different types of request processors to be registered: middleware processors which are applied to all incoming requests sequentially and regular request processors which define how a request for a specified route is turned into a response.

For processing an HTTP request, the HTTP server first sends the request through the middleware processors in the order they were registered. As soon as one middleware processor returns a response, this response becomes the response of the request. Only when all middleware processors did not return a response, the request handler matching the route is being invoked and the result of this handler defines the response for the request.

The following script configures and starts a simple web server. By default, a server listens on the loopback address, i.e. it can only be reached from the machine it is running on; see procedure http-server-start! for making a server available to other machines. Please note that procedure http-server-start! does not terminate until the web server is shut down (e.g. by visiting "/quit" for the server below).

(import (lispkit thread)
        (lispkit http server))
;; Make a new HTTP server
(define server (make-http-server))
;; Register a default handler which returns a "not found" response
(http-server-register-default! server
  (lambda (request) (srv-response-not-found)))
;; Register a simple handler for the "/hello" route
(http-server-register! server "GET" "/hello/:name"
  (lambda (request)
    (make-srv-response 200 #f
      (string-append
        "Hello "
        (srv-request-path-param request "name") "!"))))
;; Define a counter for the requests served
(define requests-served (make-atomic-box 0))
;; Increment the counter in a middleware processor
(http-server-register-middleware! server
  (lambda (request)
    (atomic-box-inc+mul! requests-served 1) #f))
;; Register a handler for "/quit" which terminates the server
(http-server-register! server "GET" "/quit"
  (lambda (request)
    ; Terminate the server with a 1 second delay
    (spawn (thunk
             (thread-sleep! 1.0)
             (http-server-stop! (srv-request-server request))))
    (make-srv-response 200 #f
      (string-append
        "terminating the server; "
        (number->string (atomic-box-ref requests-served))
        " requests served"))))
;; Enable debug logging
(http-server-log-severity-set! server 0)
;; Start the server; this call blocks until the server is terminated
(http-server-start! server 3000)

After starting the server, three requests are made for /hello/Matthias, /hello/World and /quit. The last request also terminates the server. This is the server log for this interaction:

[http/worker] started worker 0/0
[http/worker] started worker 1/1
[http/worker] started worker 2/2
[http/server] server started for port 3000; try connecting at http://127.0.0.1:3000
[http/req] GET /hello/Matthias (127.0.0.1)
[http/worker] worker 1 received request
[http/worker] worker 1: GET /hello/Matthias
[http/worker] worker 1 idle
[http/req] GET /hello/World (127.0.0.1)
[http/worker] worker 0 received request
[http/worker] worker 0: GET /hello/World
[http/worker] worker 0 idle
[http/req] GET /quit (127.0.0.1)
[http/worker] worker 1 received request
[http/worker] worker 1: GET /quit
[http/worker] worker 1 idle
[http/worker] closed worker 0/0
[http/worker] closed worker 2/0
[http/worker] closed worker 1/0
[http/server] server stopped for port 3000

The worker threads are picking up requests from a queue; which worker handles a request is not deterministic.

Server behavior

A server listens on the loopback address by default. It can only be reached from the machine it is running on. Procedure http-server-start! has an optional argument for listening on all network interfaces or on a specific address.

Servers support persistent HTTP/1.1 connections: a client can send many requests via the same connection. A connection that does not send a request for 60 seconds is closed. Idle connections do not occupy worker threads. Each request is entered into a queue and answered by the next available worker thread, independent of the connection it was received on.

Accepting connections, reading requests and writing responses is done by the thread calling http-server-start!. A client which stalls while sending a request or does not read its response delays all other clients. For this reason, a server gives up on a client which does not make progress for 5 seconds.

The following requests are answered by the server itself, without invoking a request handler:

• HEAD requests are answered by the handler registered for GET; the response body is not sent.
• OPTIONS requests for a path with registered handlers are answered with status 204 and an Allow header, unless there is a handler for OPTIONS.
• Requests for a path with registered handlers, but not for the method of the request, are answered with status 405 and an Allow header.
• Requests for a path without handler are answered with status 404 unless a default handler is registered via http-server-register-default!.
• Malformed requests are answered with status 400. Requests with a request line or header line of more than 8 KiB are answered with status 414 and 431 respectively. Requests with headers of more than 64 KiB are answered with status 431, and requests with a body of more than 64 MiB with status 413.
• Requests which are not completed within 5 seconds are answered with status 408.
• New connections are refused with status 503 while there are 128 open connections. Requests which find the request queue full are refused with status 503 as well (see http-server-timeout-set!).

Every response includes a Date header.

Paths and query values

The path and the query of a request are available as sent by the client, i.e. percent-encoded (e.g. /caf%C3%A9), and decoded (/café). Decoding loses information: after decoding, %2F can no longer be distinguished from a path separator. Furthermore, a value that gets decoded twice can turn into something different than the client sent, e.g. %252e%252e first turns into %2e%2e and then into .., which is dangerous for values used as file paths.

For this reason, procedures srv-request-path, srv-request-query, srv-request-query-param, srv-request-query-params, srv-request-path-param and srv-request-path-params return values as sent by the client by default. Procedures srv-request-path, srv-request-query-param, srv-request-query-params, srv-request-path-param and srv-request-path-params have an optional argument decode? for returning decoded values.

A path variable such as ::path stands for all its path segments. Its value as sent by the client consists of the path segments joined with /, whereas its decoded value consists of the decoded path segments joined with /. Procedure srv-request-path-param-set! expects the new value of a path parameter in its encoded form, because it is not possible to derive an encoded value from a decoded one. The attributes of a form (see srv-request-form-attributes) are always decoded exactly once.

HTTP servers

http-server-type-tag

Symbol representing the http-server type. The type-for procedure of library (lispkit type) returns this symbol for all HTTP server objects.

(http-server? obj)

Returns #t if obj is a HTTP server object; #f otherwise.

(make-http-server)
(make-http-server queue-size)
(make-http-server queue-size log-level)

Creates a new HTTP server. queue-size is the maximum number of requests the server is able to queue up before starting to reject requests (the default is 10). log-level is the minimum log level for the new HTTP server. log-level is an integer between 0 (= debug) and 4 (= fatal). Only log messages above and including the level will be output. For details on log levels see the documentation of (lispkit log).

(http-server-running? server)

Returns #t if the HTTP server server is currently running; #f otherwise.

(http-server-port server)

Returns the port the HTTP server server is listening on. If server is not running, #f is returned.

(http-server-ipv4 server)

Returns #t if the HTTP server server is listening on an IPv4 socket, i.e. if it is listening on the loopback address or on an IPv4 address; returns #f if server is listening on an IPv6 address or on all network interfaces (which are served via a combined socket for IPv4 and IPv6). An error is signaled if server is not running.

(http-server-open-connections server)

Returns the number of open HTTP connections for HTTP server server.

(http-server-routes server)

Returns a list of routes, i.e. URL paths, supported by the HTTP server server. An HTTP server supports a route if it explicitly defines a request handler for it.

(http-server-handlers server)

Returns an association list mapping routes, i.e. URL paths, to request handler procedures for HTTP server server.

(http-server-log-severity server)

Returns the minimum log level for HTTP server server. log-level is an integer between 0 (= debug) and 4 (= fatal). Only log messages above and including the level will be output.

(http-server-log-severity-set! server log-level)

Sets the minimum log level for HTTP server server to log-level. log-level is an integer between 0 and 4. Only log messages above and including the level will be output. It is possible to use the constants defined in library (lispkit log): debug (0), info (1), warn (2), err (3), and fatal (4).

(http-server-timeout server)

Returns the timeout used by HTTP server server in seconds, or #f if the server does not use a timeout. Once a request is received by server, it is put into a queue from which request processing worker threads pick up their work. If this queue is full, the request waits for room in the queue, but not longer than the timeout. If the request cannot be entered into the queue within that time, the server refuses the request with status 503 (Service Unavailable) and a Retry-After header. While a request waits, the server is not able to process any other request. The default timeout is 2 seconds.

(http-server-timeout-set! server timeout)

Sets the timeout used by HTTP server server to timeout seconds. If timeout is #f, the timeout mechanism is switched off: a request which finds the queue full is refused immediately with status 503, so a full queue never delays other requests.

(http-server-num-workers server)

Returns the number of worker threads used by HTTP server server to process incoming requests concurrently.

(http-server-log server log-level tag message ...)

Concatenates string representations of the message values and outputs them via the logger of HTTP server server if log-level is at least as high as the minimum log level supported by server. tag is a string defining a logging tag. See (lispkit log) for more details.

(http-server-register! server route handler)
(http-server-register! server method route handler)

Registers a request handler in HTTP server server which processes incoming requests for the given HTTP method and a URL path that matches the route pattern. handler is a procedure which accepts an HTTP request of type srv-request and returns a corresponding HTTP response of type srv-response. method is a string specifying the HTTP method the handler is handling. Supported are: "GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE", and "PATCH". Specifying #f or leaving our the method argument implies that handler is handling all possible methods. route is a pattern for URL paths supported by the provided handler. route is a string consists of segments separated by /. Each segment can either be:

• *: Segment wildcard (any path segment matches)
• **: Path wildcard (any sequence of path segments matches)
• :svar: Path parameter (any path segment matches; the path segment is assigned to path parameter svar)
• ::pvar: Path variable (any sequence of path segments matches; the sequence of path segments is assigned to path variable pvar)
• Any other string not containing a /: Concrete segment (a path segment of the same string matches)

Examples for valid routes are:

• "/person/address": This route matches only the exact URL path "/person/address"
• "/person/:id/:role": This route matches URL paths such as "/person/matthias/admin" and during the matching process, the path parameters id and role are assigned to matthias and admin respectively
• "/person/:id/*": This route is equivalent to the former route but there is no variable assignment to role
• "/person/:id/::roles": This route includes all paths matching the previous two examples and, in addition, also handles paths that have segments beyond id and role. For instance, "/person/matthias/admin/misc" also matches and path parameter id gets assigned to matthias and path variable roles gets assigned to admin/misc
• "/person/:id/**": This route is equivalent to the previous route without the roles variable being assigned

(http-server-register-default! server handler)

Registers a default handler for HTTP server server. Without a default handler, server, by default, returns an error whenever a URL path was used that did not have a matching route. By using http-server-register-default!, this behavior can be customized and all requests without a matching route are processed by handler. handler is a procedure which accepts an HTTP request of type srv-request and returns a corresponding HTTP response of type srv-response.

(http-server-register-middleware! server processor)

Registers a middleware processor for the given HTTP server server. A middleware processor is a function that receives an HTTP request of type srv-request and either returns #f (request not handled) or an HTTP response of type srv-response (request handled). For processing an HTTP request, server first sends the request through the middleware processors in the order they were registered. As soon as one middleware processor returns a response, this response becomes the response of the request. Only after all middleware processors returned #f, the request handler matching the route is being invoked and the result of this handler defines the response for the request.

(http-server-start! server port)
(http-server-start! server port address)
(http-server-start! server port address num)
(http-server-start! server port address num name)

Starts the HTTP server server listening on port for requests. address determines which network addresses the server accepts connections on:

• #f (the default) stands for the loopback address: server can only be reached from the machine it is running on.
• #t stands for all network interfaces of the machine, IPv4 and IPv6: server can be reached from all machines that can reach this machine.
• A string is an IPv4 or IPv6 address of the machine, e.g. "192.168.1.20", "0.0.0.0" (all IPv4 interfaces) or "::1" (the IPv6 loopback address).

An error is signaled if server cannot start listening, e.g. because port is in use or because address is not an address of the machine. num is the number of worker threads used for processing requests (default is 3). name is the prefix used for naming worker threads. name followed by the worker thread number determines each worker threads name. The default for name is "worker ". Procedure http-server-start! terminates only when the server is stopped, i.e. it is typically invoked on a thread to not block the execution of a program.

(http-server-stop! server)

Stops a running HTTP server server. All worker threads are terminated and procedure http-server-start!, which was used to start the server, returns. Stopping a server closes all its connections. If a request handler stops the server, the response of that request can therefore get lost. To make sure the response is sent, stop the server from a different thread after a short delay, as done in the example above.

Server requests

HTTP requests

srv-request-type-tag

Symbol representing the srv-request type. The type-for procedure of library (lispkit type) returns this symbol for all HTTP server request objects.

(srv-request? obj)

Returns #t if obj is a HTTP server request object; #f otherwise.

(srv-request-server req)

Returns the HTTP server which issued this HTTP server request object req. srv-request-server returns #f if req was persisted and the corresponding HTTP server object was garbage collected.

(srv-request-method req)

Returns the HTTP method for the given HTTP server request req as a string. The supported HTTP methods are: "GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE", and "PATCH".

(srv-request-path req)
(srv-request-path req decode?)

Returns the URL path of the given HTTP server request req as a string. By default, the path is returned as sent by the client, i.e. it is percent-encoded (e.g. /caf%C3%A9). If decode? is set to #t, the decoded path is returned (e.g. /café). A decoded path cannot distinguish %2F from a path separator, and it can contain arbitrary characters, including line breaks. It should not be decoded again; for instance, %252e%252e turns into %2e%2e when decoded once, and into .. when decoded twice.

(srv-request-query req)
(srv-request-query req incl-path?)

Returns the URL query of the given HTTP server request req as a string, exactly as sent by the client, including the leading ?. If req does not have a query, the empty string is returned. If incl-path? is provided and set to true, then the query is prefixed with the path of req (as returned by srv-request-path, i.e. as sent by the client).

(srv-request-query-param req name)
(srv-request-query-param req name decode?)

Returns the values of the query parameter name (a string) for the given HTTP server request req as a list of strings. If the query parameter name was not used in req, the empty list is returned. By default, parameter names and values are compared and returned as sent by the client, i.e. percent-encoded and with + characters left as they are. If decode? is set to #t, names and values are decoded: percent-encoded characters are replaced and + stands for a space.

(srv-request-query-params req)
(srv-request-query-params req decode?)

Returns all query parameters for the given HTTP server request req as an association list consisting of string pairs, mapping query parameter names to query parameter values. By default, names and values are returned as sent by the client, i.e. percent-encoded and with + characters left as they are. If decode? is set to #t, names and values are decoded: percent-encoded characters are replaced and + stands for a space.

(srv-request-path-param req name)
(srv-request-path-param req name default)
(srv-request-path-param req name default decode?)

Returns the value of the path parameter name (a string) for the given HTTP server request req as a string. If the path parameter name is undefined in req, default is returned instead if provided. Otherwise, #f is returned.

Path parameters are determined when a request path gets matched with the available routes of an HTTP server. For details, see documentation for procedure http-server-register!. By default, i.e. if decode? is not provided or set to #f, the value of a path parameter is returned as sent by the client, i.e. percent-encoded; the value of a path variable (::pvar) consists of the path segments joined with /. If decode? is set to #t, the value is decoded. A decoded value can contain a / if the path of the request contained %2F; the decoded value of a path variable consists of the decoded path segments joined with /, so it cannot tell %2F from a path separator:

;; Route "/files/::path", request path "/files/caf%C3%A9/a%2Fb"
(srv-request-path-param request "path")            ⇒  "caf%C3%A9/a%2Fb"
(srv-request-path-param request "path" #f #f)      ⇒  "caf%C3%A9/a%2Fb"
(srv-request-path-param request "path" #f #t)      ⇒  "café/a/b"

(srv-request-path-params req)
(srv-request-path-params req decode?)

Returns all path parameters for the given HTTP server request req as an association list consisting of string pairs, mapping path parameter names to path parameter values. Path parameters are determined when a request path gets matched with the available routes of an HTTP server. For details, see documentation for procedure http-server-register!. By default, i.e. if decode? is not provided or set to #f, the values are returned as sent by the client, i.e. percent-encoded. If decode? is set to #t, the values of path parameters are decoded. See srv-request-path-param for details.

(srv-request-path-param-set! req name value)

Sets the value of the path parameter name (a string) for the given HTTP server request req to string value. value needs to be percent-encoded, like the values returned by srv-request-path-param by default. It is not possible to derive an encoded value from a decoded one, because a / and %2F have the same decoded value. The decoded value of the parameter, returned with decode? set to #t, is derived from value. An error is signaled if value is not a valid percent-encoded string; for example, a literal % needs to be encoded as %25.

(srv-request-path-param-remove! req name)

Removes the path parameter name (a string) from the given HTTP server request req.

(srv-request-header req name)
(srv-request-header req name default)

Returns the header name (a string) for the given HTTP server request req as a string. If the header name is undefined in req, default is returned instead if provided. Otherwise, #f is returned.

(srv-request-headers req)

Returns all headers for the given HTTP server request req as an association list consisting of string pairs, mapping header names to header values.

(srv-request-header-set! req name value)

Sets the header name (a string) for the given HTTP server request req to string value.

(srv-request-header-remove! req name)

Removes the header name (a string) from the given HTTP server request req.

(srv-request-body req)

Returns the body of the HTTP server request req as a bytevector.

(srv-request-body->string req)

Returns the body of the HTTP server request req as a UTF8-encoded string. If an interpretation of the body as a UTF8-encoded string fails, #f is returned.

(srv-request-form-attributes req)

Parses the body if its content type is application/x-www-form-urlencoded and returns the query parameters in the body as an association list mapping query names to query values. Names and values are decoded: percent-encoded characters are replaced and + stands for a space.

(srv-request-form-multiparts req)

Parses the body if its content type is multipart/form-data and returns a list of multi-part request objects of type srv-multipart. If the body is not a well-formed multipart/form-data body, e.g. because it has no closing boundary, then the empty list is returned.

(srv-request-address req)

Returns the IP address of the client issueing the HTTP server request req as a string. If the IP address cannot be determind, #f is returned.

HTTP multi-part requests

HTTP multipart, specifically multipart/form-data, is a media type that allows the encoding of information as a series of parts in a single message as defined by RFC 2388. This format is commonly used for forms that are expressed in HTML and where the form values are sent via HTTP.

srv-multipart-type-tag

Symbol representing the srv-multipart type. The type-for procedure of library (lispkit type) returns this symbol for all HTTP server multipart request objects.

(srv-multipart? obj)

Returns #t if obj is a HTTP server multipart request object; #f otherwise.

(srv-multipart-header mp name)
(srv-multipart-header mp name default)

Returns the header name (a string) for the given HTTP server multipart request mp as a string. If the header name is undefined in mp, default is returned instead if provided. Otherwise, #f is returned.

(srv-multipart-headers mp)

Returns all headers for the given HTTP server multipart request mp as an association list consisting of string pairs, mapping header names to header values.

(srv-multipart-body mp)

Returns the body of the HTTP server multipart request mp as a bytevector.

(srv-multipart-body->string mp)

Returns the body of the HTTP server multipart request mp as a UTF8-encoded string. If an interpretation of the body as a UTF8-encoded string fails, #f is returned.

Server responses

Generic API

srv-response-type-tag

Symbol representing the srv-response type. The type-for procedure of library (lispkit type) returns this symbol for all HTTP server response objects.

(srv-response? obj)

Returns #t if obj is a HTTP server response object; #f otherwise.

(make-srv-response)
(make-srv-response status)
(make-srv-response status headers)
(make-srv-response status headers body)
(make-srv-response status headers body ct)

Returns a new HTTP server response based on the provided arguments. status is a fixnum defining the status code (default: 200). headers is an association list consisting of string pairs, mapping header names to header values. body is a value (default: #f) which gets mapped to suitable response content with ct being a string describing the MIME type for the content.

The following mapping rules are deriving the content of the response from value body:

• #f: Sets an empty body.
• String: The body is assigned the textual content of the string. If last is provided, it is interpreted as a string defining the MIME type of the content. Otherwise, the MIME type is assumed to be text/plain.
• Bytevector: The body is assigned the binary data of the bytevector. If last is provided, it is interpreted as a string defining the MIME type of the content. Otherwise, the MIME type is assumed to be application/octet-stream.
• Pair: body is assumed to be in an SXML representation of HTML. The body of res is assigned a textual HTML representation of body. If last is provided and set to #t or if it is detected that the outermost markup of body is not html, then the body is wrapped automatically in missing html and body markup. The MIME type is set to text/html.
• markdown, markdown-block, markdown-inline object: The body is assigned an HTML representation of the given markdown object provided by library (lispkit markdown). The MIME type is set to text/html.
• json, mutable-json object: The body is assigned a textual JSON representation of the given JSON object provided by library (lispkit json). The MIME type is set to application/json.
• styled-text object: If last is provided and set to true, the body is assigned an RTF representation (MIME type application/rtf) of the given styled text object provided by library (lispkit styled-text). If last is not provided or set to #f, the body is assigned an HTML representation (MIME type text/html) of the given styled text object.
• image object: The body is assigned a binary representation of the bitmap image provided by library (lispkit draw). If last is provided, it is interpreted as a string defining the MIME type of the content. Supported are image/tiff, image/png, image/jpeg, image/gif, and image/bmp. If last is not provided, image/png is assumed to be the default.
• All other data types are interpreted as Scheme objects representing JSON values. They are converted via procedure json into a JSON object and a textual representation of this JSON object is assigned to the body of res with MIME type application/json. If the conversion fails, an error is returned.

(srv-response-status-code res)

Returns the HTTP status code of the HTTP server response res.

(srv-response-status-code-set! res status)

Sets the HTTP status code of the HTTP server response res to status.

(srv-response-header res name)
(srv-response-header res name default)

Returns the header name (a string) for the given HTTP server response res as a string. If the header name is undefined in res, default is returned instead if provided. Otherwise, #f is returned.

(srv-response-headers res)

Returns all headers for the given HTTP server response res as an association list consisting of string pairs, mapping header names to header values.

(srv-response-header-set! res name value)

Sets the header name (a string) for the given HTTP server response res to string value.

(srv-response-header-remove! res name)

Removes the header name (a string) from the given HTTP server response res.

(srv-response-body-set! res body)
(srv-response-body-set! res body last)

Sets the body of the HTTP server response res to content derived from value body. The following mapping rules are used for the given value body:

• #f: Sets an empty body.
• String: The body is assigned the textual content of the string. If last is provided, it is interpreted as a string defining the MIME type of the content. Otherwise, the MIME type is assumed to be text/plain.
• Bytevector: The body is assigned the binary data of the bytevector. If last is provided, it is interpreted as a string defining the MIME type of the content. Otherwise, the MIME type is assumed to be application/octet-stream.
• Pair: body is assumed to be in an SXML representation of HTML. The body of res is assigned a textual HTML representation of body. If last is provided and set to #t or if it is detected that the outermost markup of body is not html, then the body is wrapped automatically in missing html and body markup. The MIME type is set to text/html.
• markdown, markdown-block, markdown-inline object: The body is assigned an HTML representation of the given markdown object provided by library (lispkit markdown). The MIME type is set to text/html.
• json, mutable-json object: The body is assigned a textual JSON representation of the given JSON object provided by library (lispkit json). The MIME type is set to application/json.
• styled-text object: If last is provided and set to true, the body is assigned an RTF representation (MIME type application/rtf) of the given styled text object provided by library (lispkit styled-text). If last is not provided or set to #f, the body is assigned an HTML representation (MIME type text/html) of the given styled text object.
• image object: The body is assigned a binary representation of the bitmap image provided by library (lispkit draw). If last is provided, it is interpreted as a string defining the MIME type of the content. Supported are image/tiff, image/png, image/jpeg, image/gif, and image/bmp. If last is not provided, image/png is assumed to be the default.
• All other data types are interpreted as Scheme objects representing JSON values. They are converted via procedure json into a JSON object and a textual representation of this JSON object is assigned to the body of res with MIME type application/json. If the conversion fails, an error is returned.

(srv-response-body-html-set! res str)
(srv-response-body-html-set! res str just-body?)

Sets the body of the HTTP server response res to string str representing HTML content. If just-body? is provided and set to #t, it is assumed that str only represents the body of a HTML document and srv-response-body-html-set! will automatically decorate str such that it represents a full HTML document.

Common responses

(srv-response-ok body)
(srv-response-ok headers body)

Returns a HTTP server response for status code 200 (= OK). This is quivalent to (make-srv-response 200 headers body).

(srv-response-bad-request)
(srv-response-bad-request body)
(srv-response-bad-request headers body)

Returns a HTTP server response for status code 400 (= Bad Request). This is quivalent to (make-srv-response 400 headers body).

(srv-response-unauthorized)
(srv-response-unauthorized body)
(srv-response-unauthorized headers body)

Returns a HTTP server response for status code 401 (= Unauthorized). This is quivalent to (make-srv-response 401 headers body).

(srv-response-forbidden)
(srv-response-forbidden body)
(srv-response-forbidden headers body)

Returns a HTTP server response for status code 403 (= Forbidden). This is quivalent to (make-srv-response 403 headers body).

(srv-response-not-found)
(srv-response-not-found body)
(srv-response-not-found headers body)

Returns a HTTP server response for status code 404 (= Not Found). This is quivalent to (make-srv-response 404 headers body).

(srv-response-method-not-allowed)
(srv-response-method-not-allowed body)
(srv-response-method-not-allowed headers body)

Returns a HTTP server response for status code 405 (= Not Allowed). This is quivalent to (make-srv-response 405 headers body).

(srv-response-not-acceptable)
(srv-response-not-acceptable body)
(srv-response-not-acceptable headers body)

Returns a HTTP server response for status code 406 (= Not Acceptable). This is quivalent to (make-srv-response 406 headers body).

(srv-response-internal-server-error)
(srv-response-internal-server-error body)
(srv-response-internal-server-error headers body)

Returns a HTTP server response for status code 500 (= Internal Server Error). This is quivalent to (make-srv-response 500 headers body).

(srv-response-not-implemented)
(srv-response-not-implemented body)
(srv-response-not-implemented headers body)

Returns a HTTP server response for status code 501 (= Not Implemented). This is quivalent to (make-srv-response 501 headers body).

(srv-response-created)

Returns a HTTP server response for status code 201 (= Created). This is quivalent to (make-srv-response 201 #f #f).

(srv-response-accepted)

Returns a HTTP server response for status code 202 (= Accepted). This is quivalent to (make-srv-response 202 #f #f).

(srv-response-moved-permanently redirect)
(srv-response-moved-permanently redirect headers)

Returns a HTTP server response for status code 301 (= Moved Permanently). This is quivalent to (make-srv-response 301 (cons (cons "Location" redirect) headers) #f).

(srv-response-moved-temporarily redirect)
(srv-response-moved-temporarily redirect headers)

Returns a HTTP server response for status code 307 (= Temporary Redirect). The client is asked to repeat the request, with the same method and body, at the new location. This is equivalent to (make-srv-response 307 (cons (cons "Location" redirect) headers) #f).

Utilities

(parse-http-header-value str)

Parses the header value string str into a list of strings and string pairs using a universal header parsing algorithm.

(parse-http-header-value "a, b, c")
  ⇒  (("a") ("b") ("c"))
(parse-http-header-value "a; b; c")
  ⇒  (("a" "b" "c"))
(parse-http-header-value "a, b1 ; b2, c")
  ⇒  (("a") ("b1" "b2") ("c"))
(parse-http-header-value "a; b=one; c=two")
  ⇒   (("a" ("b" . "one") ("c" . "two")))
(parse-http-header-value
  "foo/bar;p=\"A,B,C\", bob/dole;x=\"apples,oranges\"")
  ⇒  (("foo/bar" ("p" . "A,B,C")) ("bob/dole" ("x" . "apples,oranges")))

(http-header-param headers name)

Extracts the header value for header name from the association list headers, or returns #f if name is not contained in headers. headers is an association list of string pairs, mapping header names to header values.

(http-header-param '(("one" . "1")("Two" . "2")) "TWO")
  ⇒  "2"
(http-header-param '(("one" . "1")("Two" . "2")) "Three")
  ⇒  #f

(share-file-handler filepath)

Returns a HTTP request handler for downloading a file at the given filepath, an absolute file path. The handler sends the file with ETag and Last-Modified headers, and supports conditional requests and range requests.

(share-directory-handler root)

Returns a HTTP request handler for downloading a file at the file path consisting of the first path variable of the request which is considered to be relative to absolute directory path root. The handler needs to be registered for a route ending in a path variable (e.g. "/public/::path"). Files are sent like by share-file-handler. A request for a directory is redirected to the same path with a / appended and then answered with the file index.html or default.html of the directory, if there is one.

Requests which contain .. segments or NUL characters, or which refer to files outside of root via symbolic links, are refused with status 403. This also applies to encoded forms such as %2e%2e. Requests for files which do not exist are answered with status 404.

(browse-directory-handler root)

Returns a HTTP request handler for browsing the files in the directory consisting of the first path variable of the request which is considered to be relative to absolute directory path root. The handler needs to be registered for a route ending in a path variable (e.g. "/files/::path"). Directories are answered with an HTML page listing their entries, files are sent like by share-file-handler. The same restrictions as for share-directory-handler apply.