source: project/wiki/eggref/4/spiffy @ 25624

[[tags: egg]]

== Spiffy

[[toc:]]

=== Description

A small web-server written in [[http://www.call-with-current-continuation.org|Chicken]].

=== Author

[[/users/felix-winkelmann|Felix Winkelmann]].
Currently maintained by [[/users/peter-bex|Peter Bex]].

=== Requirements

Requires the [[intarweb]], [[uri-common]], [[defstruct]], [[matchable]]
and [[sendfile]] extensions.

=== Documentation

Spiffy is a web-server library for the Chicken Scheme system. It's
quite easy to set up and use (whether as a library or a standalone
server application) and it can be customized in numerous ways.

=== Starting the server

To start the server with minimal configuration hassle, there's a simple
procedure to help you do that:

<procedure>(start-server [port: port-number] [bind-address: address] [listen: listen-procedure] [accept: accept-procedure] [addresses: addresses-procedure])</procedure>

Starts the server, to listen on the given port. Other configuration
can be tweaked through SRFI-39 parameters. These are listed below.
Once the server is started, server behaviour can be controlled through
these parameters as well.  After the listener is started, when
{{spiffy-user}} and/or {{spiffy-group}} are provided, this procedure
will drop privileges before starting the accept loop.

By default, Spiffy will only serve static files. On directories, it
will give a "403 forbidden", unless there is an index-file. If there
is, that file's contents will be shown.

All arguments directly supplied to {{start-server}} override the
configuration parameter values and will be parameterized to reflect
this new setting.

{{port-number}} defaults to the value of {{server-port}} (see below).
{{bind-address}} defaults to the value of {{server-bind-address}} (see below).
{{listen}} defaults to {{tcp-listen}} and should accept a port number, backlog and bind address.
{{accept}} defaults to {{tcp-accept}}, and is passed on as-is to {{accept-loop}}.
{{addresses-procedure}} defaults to a procedure which works like {{tcp-addresses}} but can also detect SSL ports and return the addresses of the underlying TCP connection.

<procedure>(accept-loop listener accept [addresses])</procedure>

This procedure starts the loop which accepts incoming connections and
fires off threads to handle requests on those connections.  You can
use it if you need more control over the startup process than
{{start-server}} offers.

The listener object should be an object which is accepted by the
{{accept}} procedure, which should return two values; an input and
an output port which represent an incoming connection from a client.
The optional {{addresses}} procedure should accept the input port
returned by the {{accept}} procedure and return two strings; the
local and remote addresses of the server and client, respectively.

For example, you can set up an SSL context and drop privileges,
and possibly load extra code before starting the accept loop
(Spiffy contains the required code to detect SSL ports,
and will handle those more-or-less transparently):

<enscript highlight="scheme">
(use spiffy openssl)

(server-port 443)
(spiffy-user "www")
(spiffy-group "www")

;; Bind the port as root, before we drop privileges
(define listener (ssl-listen (server-port)))

;; Load the certificate files as root so we can secure their permissions
(ssl-load-certificate-chain! listener "server.pem")
(ssl-load-private-key! listener "server.key")

;; Drop root privileges
(switch-user/group (spiffy-user) (spiffy-group))
  
;; We don't want to load this extra code as root!
(load "extra-code.scm")

;; Done! Start listening for connections.
(accept-loop listener ssl-accept)
</enscript>

<procedure>(switch-user/group user group)</procedure>

This is a helper procedure which allows you to easily drop privileges
before running the accept loop.  The user and group must be either
strings or UID/GID numbers which indicate the username and groupname
to which you want to switch.  Either is also allowed to be {{#f}}, if
you don't want to switch that aspect of the process.

=== Configuration parameters

The following parameters can be used to control spiffy's behaviour.
Besides these parameters, you can also influence spiffy's behaviour by
tweaking the [[intarweb]] parameters.

<parameter>(server-software [product])</parameter>

The server software product description. This should be a valid
product value as used in the server and user-agent headers by intarweb;
this is a list of lists. The inner lists contain the product name,
the product version and a comment, all either a string or {{#f}}.
Default: {{(("Spiffy" "a.b" "Running on Chicken x.y"))}}, with {{a.b}}
being the Spiffy major/minor version and {{x.y}} being Chicken's.

<parameter>(root-path [path])</parameter>

The path to the document root, for the current vhost.
Defaults to {{"./web"}}.

<parameter>(server-port [port-number])</parameter>

The port number on which to listen. Defaults to 8080.

<parameter>(server-bind-address [address])</parameter>

The IP address on which to listen, or all addresses if {{#f}}.
Defaults to {{#f}}.

<parameter>(max-connections [number])</parameter>

The maximum number of simultaneously active connections. Defaults to 1024.

Any new connection that comes in when this number is reached must wait
until one of the active connections is closed.

<parameter>(spiffy-user [name-or-uid])</parameter>

The name or UID of a user to switch to just after binding the
port. This only works if you start Spiffy as root, so it can bind port
80 and then drop privileges. If {{#f}}, no switch will occur.
Defaults to {{#f}}.

<parameter>(spiffy-group [name-or-gid])</parameter>

The name or GID of a group to switch to just after binding the
port. This only works if you start Spiffy as root, so it can bind port
80 and then drop privileges. If {{#f}}, it will be set to the primary
group of {{spiffy-user}} if the user was selected. Otherwise, no
change will occur.  Defaults to {{#f}}.

<parameter>(index-files [file-list])</parameter>

A list of filenames which are to be used as index files to serve when
the requested URL identifies a directory.  Defaults to
{{'("index.html" "index.xhtml")}}

<parameter>(mime-type-map [extension->mimetype-list])</parameter>

An alist of extensions (strings) to mime-types (symbols), to use
for the content-type header when serving up a static file. Defaults to

  '(("html" . text/html)
    ("xhtml" . application/xhtml+xml)
    ("js"  . application/javascript)
    ("css" . text/css)
    ("png" . image/png)
    ("xml" . application/xml)
    ("pdf" . application/pdf)
    ("jpeg" . image/jpeg)
    ("jpg" . image/jpeg)
    ("gif" . image/gif)
    ("ico" . image/vnd.microsoft.icon)
    ("txt" . text/plain))

See also {{file-extension->mime-type}} for a procedure which
can look up file extensions for you.

<parameter>(default-mime-type [mime-type])</parameter>

The mime-type (a symbol) to use if none was found in the
{{mime-type-map}}. Defaults to {{'application/octet-stream}}

<parameter>(default-host [hostname])</parameter>

The host name to use when no virtual host could be determined from the
request.  See the section on virtual hosts below.

<parameter>(vhost-map [host-regex->vhost-handler])</parameter>

A mapping of virtual hosts (regex) to handlers (procedures of one
argument; a continuation thunk). See the section on virtual hosts
below. Defaults to {{`((".*" . ,(lambda (continue) (continue))))}}

<parameter>(file-extension-handlers [extension->handler-list])</parameter>

An alist mapping file extensions (strings) to handler procedures
(lambdas of one argument; the file name relative to the webroot).
Defaults to {{'()}}. If no handler was found, defaults to just sending
a static file.

<parameter>(access-log [log-file-or-port])</parameter>

Filename (string) or port to append access log output to.  Default:
{{#f}} (disabled)

<parameter>(error-log [log-file-or-port])</parameter>

Filename (string) or port to which error messages from evaluated code
should be output. Default: {{(current-error-port)}}

<parameter>(debug-log [log-file-or-port])</parameter>

Filename (string) or port to write debugging messages to.  Default:
{{#f}} (disabled)

<parameter>(access-file [string])</parameter>

The name of an access file, or {{#f}} if not applicable.  This file is
read when the directory is entered by the directory traversal system,
and allows you to write dynamic handlers that can assign new values
for parameters only for resources below that directory, very much like
adding parameters in code before calling a procedure.  See the section
"Access files" for more information.

<parameter>(trusted-proxies [list-of-strings])</parameter>

When an incoming request is first accepted, the {{remote-address}} is
initialized to the IP address of the remote peer.  When this peer is a
reverse proxy in an internal network, that value is not so useful
because all requests would seem to come from there.

If you want to have a more meaningful value, you can add the IP
addresses of proxies to this list, and {{X-Forwarded-For}} entries
from these proxies will be stripped, and the first entry just before
the most-distant trusted proxy will be used.

Be careful: all IP addresses in this list will be trusted on their
word.

Default: {{()}} (trust no one)


=== Handlers

Besides "static" configuration, Spiffy also has several handlers for
when something is to be served.

<parameter>(handle-directory [proc])</parameter>

The handler for directory entries. If the requested URL points to a
directory which has no index file, this handler is invoked. It is a
procedure of one argument, the path (a string) relative to the
webroot. Defaults to a procedure which returns a "403 forbidden".

<parameter>(handle-file [proc])</parameter>

The handler for files. If the requested URL points to a file, this
handler is invoked to serve the file. It is a procedure of one
argument, the path (a string) relative to the webroot. Defaults to a
procedure which sets the content-type and determines a handler based
on the {{file-extension-handlers}}, or {{send-static-file}} if none
was found.

<parameter>(handle-not-found [proc])</parameter>

The handler for nonexistent files. If the requested URL does not point
to an existing file or directory, this procedure is called. It is a
procedure of one argument, the path (a string) to the first missing file
in the request path. This path should be interpreted as being relative
to the webroot (even though it points to no existing file). Defaults to
a procedure which returns a "404 Not found".

<parameter>(handle-exception [proc])</parameter>

The handler for when an exception occurs. This defaults to a procedure
that logs the error to the error log. While debugging or developing, it
may be more convenient to use a procedure that sends the error back to
the client:

<enscript highlight=scheme>
(handle-exception
  (lambda (exn chain)
    (send-status 'internal-server-error (build-error-message exn chain))))
</enscript>

<parameter>(handle-access-logging [proc])</parameter>

The handler for access logging. This is a procedure of zero arguments
which should write a line to the access log. Defaults to a procedure which
writes a line to {{access-log}} which looks like this:

   127.0.0.1 [Sun Nov 16 15:16:01 2008] "GET http://localhost:8080/foo?bar HTTP/1.1" 200 "http://localhost:8080/referer" "Links (2.2; NetBSD 5.99.01 macppc; x)"

=== Runtime information

During the handling of a request, Spiffy adds more information to the
environment by parameterizing the following parameters whenever the
information becomes available:

<parameter>(current-request [request])</parameter>

An intarweb request-object that defines the current request. Available
from the moment the request comes in and is parsed. Contains, among
other things, the query parameters and the request-headers, in fully
parsed form (as intarweb returns them).

The URI is automatically augmented with the host, scheme and port if
it is not an absolute URI.

<parameter>(current-response [response])</parameter>

An intarweb response-object that defines the current
response. Available from the same time current-request is available.
This keeps getting updated along the way, while the response data is
being refined (like when headers are being added).

<parameter>(current-file [path])</parameter>

The path to the requested file (a string). Available from the moment
Spiffy determined the requested URL points to a file (just before the
{{handle-file}} procedure is called). This file is relative to the
{{root-path}}.

<parameter>(current-pathinfo [path])</parameter>

The trailing path ''fragments'' (a list of strings) that were passed
in the URL after the requested filename. Available from the moment
Spiffy determined the requested URL points to a file (just before the
{{handle-file}} procedure is called).

<parameter>(remote-address [address])</parameter>

The IP address (a string) of the user-agent performing the current
request.  See also {{trusted-proxies}}.

<parameter>(local-address [address])</parameter>

The IP address (a string) on which the current request came in.

<parameter>(secure-connection? [boolean])</parameter>

{{#t}} when the current connection is a secure one (SSL), {{#f}} if it
isn't (regular HTTP).  This pertains only to the direct connection
itself, so if Spiffy is behind a proxy this will be {{#f}} even if the
proxy itself is connected to the client over SSL.

One way to get around this is to ''always'' add a custom header to
your reverse proxy's configuration file.  Then you can read this out
in Spiffy and set secure-connection? to {{#t}} or {{#f}}, as well as
updating the request URI's scheme.  There is no standardized header
for this, so the default Spiffy won't do this.

An easier way around this is to set up two spiffies listening on
different ports and configure one to have {{secure-connection?}} set
to {{#t}}, which you redirect incoming HTTPS requests to.

'''This parameter may disappear or change in the future''', when there
are more smart people using Spiffy who know how to deal with this or
the Spiffy maintainer has a moment of clarity and decides how to do
this cleanly.

=== Virtual hosts

Spiffy has support for virtual hosting, using the HTTP/1.1 Host
header.  This allows you to use one Spiffy instance running on one IP
address/port number to serve multiple webpages, as determined by the
hostname that was requested.

The virtual host is defined by a procedure, which can set arbitrary
parameters on-the-fly. It is passed a continuation thunk, which it
should explicitly call if it wants the processing to continue.  The
most used parameter in virtual host setups is the {{root-path}}
parameter, so that another docroot can be selected based on the
requested hostname, showing different websites for different hosts:

<enscript highlight="scheme">
(vhost-map `(("foo\\.bar\\.com" .
               ,(lambda (continue)
                  (parameterize ((file-extension-handlers
                                   `(("ssp" . ,ssp-handler) ("ws" . ,web-scheme-handler)))
                                 (root-path "/var/www/domains/foo.bar.com"))
                     (continue))))
             (,(glob->regexp "*.domain.com") .
                ,(lambda (continue)
                   (parameterize ((file-extension-handlers
                                    `(("php" . ,(cgi-handler* "/usr/pkg/libexec/cgi-bin/php"))))
                                  ;; You can also change PHP's arg_separator.input
                                  ;; to be ";&" instead of this parameter
                                  (form-urlencoded-separator "&")
                                  (root-path "/var/www/domains/domain.com"))
                     (continue))))))
</enscript>

In this example, if a client accesses
{{foo.bar.com/mumble/blah.html}}, the file
{{/var/www/domains/foo.bar.com/mumble/blah.html}} will be served.  Any
files ending in {{.ssp}} or {{.ws}} will be served by the
corresponding file type handler.  If there's any PHP file, its source
will simply be displayed.  In case of
{{my.domain.com/something/bar.html}}, the file
{{/var/www/domains/domain.com/something/bar.html}} will be served.  If
there's a {{.ssp}} or {{.ws}} file there, it will not be interpreted.
Its source will be displayed instead.  A {{.php}} file, on the other
hand, will be passed via CGI to the program {{/usr/pkg/bin/php}}.

Domain names are mapped to a lambda that sets up any parameters it
wants to override from the defaults.  The host names are matched using
{{string-match}}.  If the host name is not yet a regexp, it will be
converted to a ''case-insensitive'' regexp.

=== Access files

Fine-grained access-control can be implemented by using so-called
access files.  When a request for a specific file is made and a file
with the name given in the {{access-file}} parameter exists in any
directory between the {{root-path}} of that vhost and the directory in
which the file resides, then the access file is loaded as an
s-expression containing a function and is evaluated with a single
argument, the function that should be called to continue processing
the request.

This works just like vhosting.  The function that gets called can call
{{parameterize}} to set additional constraints on the code that
handles deeper directories.

For example, if we evaluate {{(access-file ".access")}} before
starting the server, and we put the following code in a file named
{{.access}} into the root-directory, then all accesses to any file
in the root-directory or any subdirectory will be denied unless the
request comes from localhost:

<enscript highlight=scheme>
 (lambda (continue)
   (if (string=? (remote-address) "127.0.0.1")
       (continue)
       (send-status 'forbidden "Sorry, you're not allowed here")))
</enscript>

If we only want to deny access to files that start with an X, put this
in the {{.access}} file:

<enscript highlight=scheme>
 (lambda (continue)
   (let ((old-handler (handle-file)))
     (parameterize ((handle-file
                      (lambda (path)
                        (if (not (string-prefix? "X" (pathname-file path)))
                            (send-status 'forbidden "No X-files allowed!")
                            (old-handler path)))))
       (continue))))
</enscript>

Of course, access files can be used for much more than just access
checks.  One can put anything in them that could be put in vhost
configuration or in top-level configuration.

They are very useful for making deployable web applications, so you
can just drop a directory on your server which has its own
configuration embedded in an access file in the root directory of the
application, without having to edit the server's main configuration
files.

=== Procedures and macros

The following procedures and macros can be used in dynamic web
programs, or dynamic server configuration:

<procedure>(with-headers new-headers thunk)</procedure>

Call {{thunk}} with the header list {{new-headers}}. This
parameterizes the current response to contain the new headers.  The
existing headers are extended with {{new-headers}} through intarweb's
{{headers}} procedure.

<procedure>(write-logged-response)</procedure>

This procedure simply writes {{current-response}} after calling
{{handle-access-logging}}. Responses should always go through this
procedure instead of directly using {{write-response}} from intarweb.

<procedure>(log-to log format . rest)</procedure>

Write a printf-style format string to the specified log (one of
{{access-log}}, {{error-log}} or {{debug-log}}). {{format}} is a
{{printf}}-style format string, and rest arguments should match
the arguments one would pass to printf. A newline is appended to
the end of the log message automatically.

<procedure>(send-response #!key status code reason body headers)</procedure>

Easy way to send string data to the client, with additional headers.
It will add appropriate headers and will automatically detect {{HEAD}}
requests.  If BODY is {{#f}}, no body is sent and the {{content-length}}
header is set to zero.

The status is a symbol describing the response status, which is looked
up in [[intarweb]]'s {{http-status-code}} parameter.  If {{code}} and/or
{{reason}} are supplied, these take precedence.  If {{status}} and {{code}}
are missing, the default status is {{ok}}.

<procedure>(send-status code reason [message])</procedure><br>
<procedure>(send-status status [message])</procedure>

Easy way to send a page and a status code to the client.  The optional
{{message}} is a string containing HTML to add in the body of the
response. Some structure will be added around the message, so message
should only be the actual message you want to send.

This can be called either with a numeric code, string reason and
optional message or with a symbolic status and optional message.

Example:

<enscript highight="scheme">
(send-status 404 "Not found"
 "Sorry, page not found! Please try <a href='/search.ws'>our search page</a>")

;; Alternative way of doing this:
(send-status 'not-found
 "Sorry, page not found! Please try <a href='/search.ws'>our search page</a>")
</enscript>

<procedure>(send-static-file filename)</procedure>

Send a file to the client. This sets the {{content-length}} header and
tries to send the file as quickly as possible to the client. The
filename is interpreted relative to {{root-path}}.

<procedure>(file-extension->mime-type EXT)</procedure>

Looks up the file extension {{EXT}} (without a trailing dot)
in {{mime-type-map}}, or uses {{default-mime-type}} when the
extension can't be found.

If {{EXT}} is {{#f}}, it'll look up the extension that is the
empty string.

This returns a symbol which indicates the mime-type which is matched
to the extension (for example {{text/html}}).

<procedure>(restart-request request)</procedure>

Restart the entire request-handling starting at the point where the
request was just parsed. The argument is the new request to use.
Be careful, this makes it very easy to introduce unwanted endless loops!

<procedure>(htmlize string) => string</procedure>

Encode "special" html symbols like tag and attribute characters so
they will not be interpreted by the browser.

<procedure>(build-error-message exn chain [raw-output])</procedure>

Build an error message for the exception {{exn}}, with call chain
{{chain}}. Defaults to HTML output, unless {{raw-output}} is given and
nonfalse.

=== Modules

This section will describe what the various modules that come with
Spiffy are and how they work.

==== ssp-handler

SSP, or Scheme Server Pages, are a way to embed Scheme in HTML
pages. Files with an extension of {{.ssp}} are handled specifically,
by replacing occurrences of certain reserved tags with Scheme code.
There are two possible forms, either the long version, where all
output is redirected to the HTTP response port, or the short, where
the result of the embedded expression is displayed in the response.
The tags default to {{<?scheme}} and {{<?}}, see Configuration for how
to change them.

<enscript highlight=scheme>
   <html><body>
   <ol><?scheme (for-each (lambda (i) (printf "<li>~S~%" i)) (iota 5))?></ol>
   <br />
   <b><?(call-with-values (lambda () (user-information (current-user-id))) (lambda (name . _) name))?><b>
   </body></html>
</enscript>

would generate for example something like this:

     1. 0
     2. 1
     3. 2
     4. 3
     5. 4 

  (felix x 500 100 /home/felix /bin/bash)

When a {{.ssp}} file is loaded the first time, or when it has been
modified, then a translation takes place that generates a loadable
Scheme source file (with the extension {{.sspx}}, in the same
directory as the original file) from the original data, so in the
above example something like this would be generated:

<enscript highlight=scheme>
  (let ()
    (display "<html><body>\n<ol>")
    (for-each (lambda (i) (printf "<li>~S~%" i)) (iota 5))
    (display "</ol>\n<br />\n<b>")
    (display (call-with-values (lambda () (user-information (current-user-id))) (lambda (name . _) name)))
    (display "<b>\n</body></html>\n") )
</enscript>

Note that the body is evaluated in a {{(let () ...)}} form.

Note: each request runs in a separate thread, so code in {{.ssp}}
pages should take care when using global variables.

===== Configuration

The SSP handler can be configured with the following options:

<parameter>(ssp-short-open-tag [tag-regexp])</parameter>

The opening tag for short fragments. Default: {{<?}}

<parameter>(ssp-long-open-tag [tag-regexp])</parameter>

The opening tag for long fragments. Default: {{<?scheme}}

<parameter>(ssp-close-tag [tag-regexp])</parameter>

The closing tag for Scheme fragments in {{.ssp}} files. Default: {{?>}}

<parameter>(ssp-eval-environment [environment])</parameter>

The environment passed to {{eval}} when evaluating Scheme code inside
{{.ssp}}-pages.  Default: {{interaction-environment}}

<parameter>(ssp-cache-dir [directory-name])</parameter>

The directory under which to store cached .ssp files (these end in .sspx
and are pure Scheme files).  Useful if you want to block write access to
the webserver under your docroot.  Default: {{"."}}

If it's a relative path, it is relative to {{root-path}}, if absolute
it's taken to be relative to the filesystem root.  A directory structure
similar to the docroot will be created underneath this path, so for
example if the file {{/foo/bar/qux.ssp}} exists, and the cache dir is
set to {{/cache}}, it will create the file {{/cache/foo/bar/qux.sspx}}.

===== Runtime information

For the duration of evaluating a SSP page, the following parameters
will have a value assigned to them:

<parameter>(current-workdir [path])</parameter>

During execution, the current working directory of the SSP handler.
Any of the "include" procedures (ssp-include, ssp-stringize) will
interpret their file arguments to be relative to this directory.

<parameter>(ssp-exit-handler [handler])</parameter>

During execution of an ssp page, {{ssp-exit-handler}} is bound to a
procedure that will finish the current page, ignoring any further
content or code.

===== Procedures

The ssp-handler module adds the following procedures to the environment:

<procedure>(ssp-handler filename)</procedure>

The handler itself, which should be used in the {{file-extension-handlers}}
parameter list.

<procedure>(ssp-include filename)</procedure>

Translates the file {{filename}} into Scheme by replacing {{<?scheme ... ?>}}
and {{<? ... ?>}} sequences (if needed) and writes the translated contents
to the current output-port.

<procedure>(ssp-stringize FILENAME)</procedure>

Similar to {{ssp-include}}, but instead of writing the translated
text, the text is returned as a string.

==== web-scheme-handler

Another way of executing Scheme code to produce content are {{.ws}}
files: these should contain a Scheme expression that is expected to
evaluate to a string which will be directly written as the response to
the current request. This facility is intended for Scheme code that
uses the [[web-scheme]] extension.

You can use the {{web-scheme-handler}} for any Scheme file which
returns HTML as a string or which has a side-effect of outputting the
HTML. If it's the latter, make sure the final statement in your file
does not return a string or it will be appended to the output (just
like in the {{csi}} REPL).

'''Tip''' This handler type is perfect not only for web-scheme but
also for when you're using {{SRV:send-reply}} with SXML or for example a
wiki-to-string translator.

Note: each request runs in a separate thread, so code in {{.ws}} pages
should take care when using global variables.

Note: web-scheme-handler is a separate extension and must be imported
as such.

<enscript highlight=scheme>
(require-extension web-scheme-handler)
</enscript>

===== Configuration

The Web-scheme handler can be configured with the following options:

<parameter>(web-scheme-eval-environment [environment])</parameter>

The environment passed to {{eval}} when evaluating Scheme code inside
{{.ws}}-pages.  Default: {{interaction-environment}}

===== Procedures

The Web-scheme handler adds only one procedure to the environment:

<procedure>(web-scheme-handler filename)</procedure>

The handler itself, which should be used in the {{file-extension-handlers}}
parameter list.


==== cgi-handler

Spiffy supports [[http://www.ietf.org/rfc/rfc3875|CGI/1.1 as specified by RFC 3875]].

All request headers will be passed as environment variables to the CGI
program, prefixed with {{"HTTP_"}}, and converted to uppercase, with
hyphens ("-") replaced by an underscore ("_"). The CGI program will
receive the request body in unparsed form from stdin and should write
a complete HTTP response to stdout.  Any headers that are missing but
required for HTTP will be added by Spiffy.  For more info on how a CGI
script is called, consult the spec.

The {{AUTH_TYPE}} and {{REMOTE_USER}} environment variables are
currently not set during invocation of CGI subprocesses.
The {{REMOTE_IDENT}} environment variable is not and never will be supported.

===== Configuration

CGI handler can be configured with the following parameters:

<procedure>(cgi-default-environment [env-alist])</procedure>

The environment variables that should be in the default environnment
of every CGI program.  Variables like {{SCRIPT_NAME}} will be added
dynamically to the end of this alist.

Default: 

<enscript highlight=scheme>
(("GATEWAY_INTERFACE" . "CGI/1.1"))
</enscript>

===== Procedures

CGI-handler adds two procedures to the environment:

<procedure>(cgi-handler filename [interpreter])</procedure>

The cgi handler simply calls CGI scripts. It is assumed the
requested file is executable if no interpreter is given.
(If used as a regular handler, it will only receive the
filename).  If the filename is a relative path, it is assumed
to be relative to {{(root-path)}}.  It's safer to store your
scripts outside the docroot, though!

<procedure>(cgi-handler* [interpreter])</procedure>

The {{cgi-handler*}} procedure is usually more useful.  It allows you
to define an interpreter to use for files and returns a new handler.
See the example above for {{file-extension-handlers}}.


==== simple-directory-handler

In order to get directory listings, you can use
{{simple-directory-handler}}.  Just parameterize {{handle-directory}}'s
value with the {{simple-directory-handler}} procedure and you're set.

===== Configuration

The simple directory handler has a few configuration options:

<procedure>(simple-directory-dotfiles? [dotfiles?])</procedure>

Determines if dotfiles should show up in the directory listings.
Default: {{#f}}

<procedure>(simple-directory-display-file [displayer])</procedure>

A lambda that accepts three arguments: the remote filename, the local
filename and a boolean that says if the file is a directory.  This
lambda should output a table row with the desired information.
Defaults to a lambda that prints the name, size and date when the file
was last modified.

===== Procedures

The simple-directory handler adds only one procedure to the environment:

<procedure>(simple-directory-handler pathname)</procedure>

The handler itself, which should be used in the {{handle-directory}}
parameter.

=== Examples

Spiffy is very easy to use for simple cases:

<enscript highlight=scheme>
(use spiffy)

(server-port 80)
(root-path "/var/www")
(start-server)
</enscript>

One could also use parameterize:

<enscript highlight=scheme>
(use spiffy)

(parameterize ((server-port 80)
               (root-path "/var/www"))
  (start-server))
</enscript>

==== Network tweaks

Spiffy does not activate Chicken's TCP buffering, which results in
extra traffic: one packet sent per header line.  With a TCP buffer
size greater than the total header length, all headers will be
coalesced into a single write; generally the response body will be
coalesced as well.  For example:

 (tcp-buffer-size 2048)   ; from unit tcp
 (start-server)

=== Changelog

* trunk Fix ssp-handler's pathname construction so it doesn't error on files in the rootdirectory.
* 4.13 Add trusted-proxies parameter so remote-address can have a meaningful value in the presence of reverse proxies [thanks to John J Foerch]. Allow cgi scripts to be outside the docroot. Pass on query-strings to CGI scripts as-is, if possible, to avoid breaking scripts that rely on a particular variable-separator (reported by Felix Winkelmann).  Refactor to use symbolic response codes from Intarweb.
* 4.12 Make Spiffy optionally fully independent of Unit tcp [thanks to [[/users/jim-ursetto|Jim Ursetto]]]  Tests now also work with Chickens greater than 4.6.0 (removed deprecated {{getenv}} calls)
* 4.11 Drop openssl requirement (suggested by Felix Winkelmann); split up listening and accept loop invocation to allow loading code after dropping root privileges (suggested by Mario Goulart).
* 4.10 Fix serious bug which caused Spiffy to exit after handling N requests. Fix handling of empty path components now that uri-generic preserves them.
* 4.9 Export {{file-extension->mime-type}}. Add more info about exceptional situations to the debugging logs when enabled.
* 4.8 Fix ssl support. Get rid of {{spiffy-root-uri}}. Add timestamp and request info to error log.
* 4.7 Fix redirects for directories again (thanks to [[/users/mario-domenech-goulart|Mario]]). NO TESTCASE (possibly to be fixed in [[uri-generic]])
* 4.6 Fix redirects for directories with special URI characters in them (thanks to [[/users/felix-winkelmann|Felix]])
* 4.5 Add {{send-response}} procedure; flush output after request is handled; use proper IANA-assigned MIME types in default {{mime-type-map}}; fix {{server-root-uri}} when spiffy is behind a proxy [thanks to zbigniew]
* 4.4 Fix a problem with 304 "not modified", for which Safari incorrectly tries to read a content-body when a content-length is present.
* 4.3 Fix crash with extensionless files and nonempty extension handlers
* 4.2 Add support for caching headers and proper If-Modified-Since support
* 4.1 Make cgi-handler cope with missing pathinfo. Fix statuscode related crash in cgi-handler. Make ssp handler's open/close tags parameters, so it actually matches what the documentation says. Add {{ssp-cache-dir}}. Update for latest intarweb changes (0.2)
* 4.0 Rewrite from scratch, using Intarweb
* pre-4.0 See the changelog for the [[/eggref/3/spiffy|old spiffy]]

=== License

  Copyright (c) 2005-2011, Felix L. Winkelmann and Peter Bex
  All rights reserved.
  
  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions are
  met:
  
  Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.
  
  Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.
  
  Neither the name of the author nor the names of its contributors may
  be used to endorse or promote products derived from this software
  without specific prior written permission.
  
  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  OF THE POSSIBILITY OF SUCH DAMAGE.