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

Last change on this file since 12514 was 12514, checked in by sjamaan, 12 years ago

Revert spiffy, base64 and wmiirc documentation back to chicken 3 for the root wiki page. Chicken 4 docs are under eggref/4 now

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