source: project/wiki/spiffy @ 12036

Last change on this file since 12036 was 12036, checked in by sjamaan, 13 years ago

add docs for spiffy 4, move old docs to spiffy 3 file

File size: 10.9 KB
Line 
1[[tags: egg]]
2
3== Spiffy
4
5[[toc:]]
6
7=== Description
8
9A small web-server written in [[http://www.call-with-current-continuation.org|Chicken]].
10
11This is the documentation for Spiffy 4, a rewrite from scratch.
12For information on Spiffy 3, please see [[spiffy 3]].
13
14=== Author
15
16[[Felix Winkelmann]].  Currently maintained by [[Peter Bex]].
17
18=== Requirements
19
20Requires the [[intarweb]], [[matchable]] and [[sendfile]] extensions.
21
22=== Download
23
24[[http://www.call-with-current-continuation.org/eggs/spiffy.egg|spiffy.egg]]
25
26=== Documentation
27
28Spiffy is a web-server library for the Chicken Scheme system. It's
29quite easy to set up and use (whether as a library or a standalone
30server application) and it can be customized in numerous ways.
31
32=== Starting the server
33
34<procedure>(start-server [port: port-number])</procedure>
35
36Starts the server, to listen on the given port. Other configuration
37can be tweaked through SRFI-39 parameters. These are listed below.
38Once the server is started, server behaviour can be controlled through
39these parameters as well. By default, Spiffy will only serve static
40files. On directories, it will give a "403 forbidden", unless there
41is an index-file. If there is, that file's contents will be shown.
42
43All arguments directly supplied to {{start-server}} override the
44configuration parameter values.
45
46{{Port-number}} defaults to 8080.
47
48=== Configuration parameters
49
50The following parameters can be used to control spiffy's behaviour.
51Besides these parameters, you can also influence spiffy's behaviour by
52tweaking the [[intarweb]] parameters.
53
54<parameter>(root-path [path])</parameter>
55
56The path to the document root. Defaults to {{"./web"}}.
57
58<parameter>(server-port [port-number])</parameter>
59
60The port number on which to listen. Defaults to 8080.
61
62<parameter>(index-files [file-list])</parameter>
63
64A list of filenames which are to be used as index files to serve when
65the requested URL identifies a directory.  Defaults to
66{{'("index.html" "index.xhtml")}}
67
68<parameter>(mime-type-map [extension->mimetype-list])</parameter>
69
70An alist of extensions (strings) to mime-types (symbols), to use
71for the content-type header when serving up a static file. Defaults to
72{{
73(("xml" . text/xml)
74 ("html" . text/html)
75 ("xhtml" . text/xhtml+xml)
76 ("js"  . text/javascript)
77 ("pdf" . application/pdf)
78 ("css" . text/css)
79 ("png" . image/png)
80 ("ico" . image/x-icon)
81 ("gif" . image/gif)
82 ("jpeg" . image/jpeg)
83 ("jpg" . image/jpeg)
84 ("svg" . image/svg+xml)
85 ("bmp" . image/bmp)
86 ("txt" . text/plain))
87}}
88
89<parameter>(default-mime-type [mime-type])</parameter>
90
91The mime-type (a symbol) to use if none was found in the
92{{mime-type-map}}. Defaults to {{'application/octet-stream}}
93
94<parameter>(default-host [hostname])</parameter>
95
96The host name to use when no virtual host could be determined from the
97request.  See the section on virtual hosts below.
98
99<parameter>(vhost-map [host-regex->vhost-handler])</parameter>
100
101A mapping of virtual hosts (regex) to handlers (procedures of one
102argument; a continuation thunk). See the section on virtual hosts
103below. Defaults to {{`((".*" . ,(lambda (continue) (continue))))}}
104
105<parameter>(file-extension-handlers [extension->handler-list])</parameter>
106
107An alist mapping file extensions (strings) to handler procedures
108(lambdas of one argument; the file name relative to the webroot).
109Defaults to {{'()}}. If no handler was found, defaults to just sending
110a static file.
111
112=== Handlers
113
114Besides "static" configuration, Spiffy also has several handlers for
115when something is to be served.
116
117<parameter>(handle-directory [proc])</parameter>
118
119The handler for directory entries. If the requested URL points to a
120directory which has no index file, this handler is invoked. It is a
121procedure of one argument, the path (a string) relative to the
122webroot. Defaults to a procedure which returns a "403 forbidden".
123
124<parameter>(handle-file [proc])</parameter>
125
126The handler for files. If the requested URL points to a file, this
127handler is invoked to serve the file. It is a procedure of one
128argument, the path (a string) relative to the webroot. Defaults to a
129procedure which sets the content-type and determines a handler based
130on the {{file-extension-handlers}}, or {{send-static-file}} if none
131was found.
132
133<parameter>(handle-not-found [proc])</parameter>
134
135The handler for nonexisting files. If the requested URL does not point
136to an existing file or directory, this procedure is called. It is a
137procedure of one argument, the path (a string) that were
138requested. This path should be interpreted as being relative to the
139webroot (even though it points to no existing file). Defaults to a
140procedure which returns a "404 Not found".
141
142=== Runtime information
143
144During the handling of a request, Spiffy adds more information to the
145environment by parameterizing the following parameters whenever the
146information becomes available:
147
148<parameter>(current-request [request])</parameter>
149
150An intarweb request-object that defines the current request. Available
151from the moment the request comes in and is parsed. Contains, among
152other things, the query parameters and the request-headers, in fully
153parsed form (as intarweb returns them).
154
155<parameter>(current-response [request])</parameter>
156
157An intarweb response-object that defines the current
158response. Available from the same time current-request is available.
159This keeps getting updated along the way, while the response data is
160being refined (like when headers are being added).
161
162<parameter>(current-file [path])</parameter>
163
164The path to the requested file (a string). Available from the moment
165Spiffy determined the requested URL points to a file (just before the
166{{handle-file}} procedure is called).
167
168<parameter>(current-pathinfo [path])</parameter>
169
170The trailing path ''fragments'' (a list of strings) that were passed
171in the URL after the requested filename. Available from the moment
172Spiffy determined the requested URL points to a file (just before the
173{{handle-file}} procedure is called).
174
175=== Virtual hosts
176
177Spiffy has support for virtual hosting, using the HTTP/1.1 Host
178header.  This allows you to use one Spiffy instance running on one IP
179address/port number to serve multiple webpages, as determined by the
180hostname that was requested.
181
182The virtual host is defined by a procedure, which can set arbitrary
183parameters on-the-fly. It is passed a continuation thunk, which it
184should explicitly call if it wants the processing to continue.  The
185most used parameter in virtual host setups is the {{root-path}}
186parameter, so that another docroot can be selected based on the
187requested hostname, showing different websites for different hosts:
188
189<example>
190(vhost-map `(("foo\\.bar\\.com" .
191               ,(lambda (continue)
192                  (parameterize ((file-extension-handlers
193                                   `(("ssp" . ,ssp-handler) ("ws" . ,web-scheme-handler)))
194                                 (root-path "/var/www/domains/foo.bar.com"))
195                     (continue))))
196             (,(glob->regexp "*.domain.com") .
197                ,(lambda (continue)
198                   (parameterize ((file-extension-handlers
199                                    `(("php" . ,(cgi-handler* "/usr/pkg/bin/php"))))
200                                  (root-path "/var/www/domains/domain.com"))
201                     (continue))))))
202</example>
203
204In this example, if a client accesses
205{{foo.bar.com/mumble/blah.html}}, the file
206{{/var/www/domains/foo.bar.com/mumble/blah.html}} will be served.  Any
207files ending in {{.ssp}} or {{.ws}} will be served by the
208corresponding file type handler.  If there's any PHP file, its source
209will simply be displayed.  In case of
210{{my.domain.com/something/bar.html}}, the file
211{{/var/www/domains/domain.com/something/bar.html}} will be served.  If
212there's a {{.ssp}} or {{.ws}} file there, it will not be interpreted.
213Its source will be displayed instead.  A {{.php}} file, on the other
214hand, will be passed via CGI to the program {{/usr/pkg/bin/php}}.
215
216Domain names are mapped to a lambda that sets up any parameters it
217wants to override from the defaults.  The host names are matched using
218{{string-match}}.  If the host name is not yet a regexp, it will be
219converted to a ''case-insensitive'' regexp.
220
221=== Procedures and macros
222
223The following procedures and macros can be used in dynamic web
224programs, or dynamic server configuration:
225
226<procedure>(with-headers new-headers thunk)</procedures>
227
228Call {{thunk}} with the header list {{new-headers}}. This
229parameterizes the current response to contain the new headers.  The
230existing headers are extended with {{new-headers}} through intarweb's
231{{headers}} procedure.
232
233<procedure>(send-status code reason [message])</procedure>
234
235Easy way to send a page and a status code to the client.  The optional
236message is a string containing HTML to add in the body of the
237response. Example:
238
239<example>
240<expr>
241(send-status 404 "Not found"
242 "Sorry, page not found! Please try <a href='/search.ws'>our search page</a>")
243</expr>
244</example>
245
246<procedure>(send-static-file filename)</procedure>
247
248Send a file to the client. This sets the {{content-length}} header and
249tries to send the file as quickly as possible to the client. The
250filename is interpreted relative to {{root-path}}.
251
252<procedure>(restart-request request)</procedure>
253
254Restart the entire request-handling starting at the point where the
255request was just parsed. The argument is the new request to use.
256Be careful, this makes it very easy to introduce unwanted endless loops!
257
258=== Changelog
259
260* 4.0 Rewrite from scratch, using Intarweb
261* pre-4.0 See the changelog for [[spiffy 3]]
262
263=== License
264
265  Copyright (c) 2005-2008, Felix L. Winkelmann and Peter Bex
266  All rights reserved.
267 
268  Redistribution and use in source and binary forms, with or without
269  modification, are permitted provided that the following conditions are
270  met:
271 
272  Redistributions of source code must retain the above copyright
273  notice, this list of conditions and the following disclaimer.
274 
275  Redistributions in binary form must reproduce the above copyright
276  notice, this list of conditions and the following disclaimer in the
277  documentation and/or other materials provided with the distribution.
278 
279  Neither the name of the author nor the names of its contributors may
280  be used to endorse or promote products derived from this software
281  without specific prior written permission.
282 
283  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
284  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
285  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
286  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
287  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
288  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
289  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
290  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
291  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
292  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
293  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
294  OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.