source: project/wiki/spiffy @ 12039

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

Wrap example in expr tags

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  (("xml" . text/xml)
73   ("html" . text/html)
74   ("xhtml" . text/xhtml+xml)
75   ("js"  . text/javascript)
76   ("pdf" . application/pdf)
77   ("css" . text/css)
78   ("png" . image/png)
79   ("ico" . image/x-icon)
80   ("gif" . image/gif)
81   ("jpeg" . image/jpeg)
82   ("jpg" . image/jpeg)
83   ("svg" . image/svg+xml)
84   ("bmp" . image/bmp)
85   ("txt" . text/plain))
86
87<parameter>(default-mime-type [mime-type])</parameter>
88
89The mime-type (a symbol) to use if none was found in the
90{{mime-type-map}}. Defaults to {{'application/octet-stream}}
91
92<parameter>(default-host [hostname])</parameter>
93
94The host name to use when no virtual host could be determined from the
95request.  See the section on virtual hosts below.
96
97<parameter>(vhost-map [host-regex->vhost-handler])</parameter>
98
99A mapping of virtual hosts (regex) to handlers (procedures of one
100argument; a continuation thunk). See the section on virtual hosts
101below. Defaults to {{`((".*" . ,(lambda (continue) (continue))))}}
102
103<parameter>(file-extension-handlers [extension->handler-list])</parameter>
104
105An alist mapping file extensions (strings) to handler procedures
106(lambdas of one argument; the file name relative to the webroot).
107Defaults to {{'()}}. If no handler was found, defaults to just sending
108a static file.
109
110=== Handlers
111
112Besides "static" configuration, Spiffy also has several handlers for
113when something is to be served.
114
115<parameter>(handle-directory [proc])</parameter>
116
117The handler for directory entries. If the requested URL points to a
118directory which has no index file, this handler is invoked. It is a
119procedure of one argument, the path (a string) relative to the
120webroot. Defaults to a procedure which returns a "403 forbidden".
121
122<parameter>(handle-file [proc])</parameter>
123
124The handler for files. If the requested URL points to a file, this
125handler is invoked to serve the file. It is a procedure of one
126argument, the path (a string) relative to the webroot. Defaults to a
127procedure which sets the content-type and determines a handler based
128on the {{file-extension-handlers}}, or {{send-static-file}} if none
129was found.
130
131<parameter>(handle-not-found [proc])</parameter>
132
133The handler for nonexisting files. If the requested URL does not point
134to an existing file or directory, this procedure is called. It is a
135procedure of one argument, the path (a string) that was
136requested. This path should be interpreted as being relative to the
137webroot (even though it points to no existing file). Defaults to a
138procedure which returns a "404 Not found".
139
140=== Runtime information
141
142During the handling of a request, Spiffy adds more information to the
143environment by parameterizing the following parameters whenever the
144information becomes available:
145
146<parameter>(current-request [request])</parameter>
147
148An intarweb request-object that defines the current request. Available
149from the moment the request comes in and is parsed. Contains, among
150other things, the query parameters and the request-headers, in fully
151parsed form (as intarweb returns them).
152
153<parameter>(current-response [request])</parameter>
154
155An intarweb response-object that defines the current
156response. Available from the same time current-request is available.
157This keeps getting updated along the way, while the response data is
158being refined (like when headers are being added).
159
160<parameter>(current-file [path])</parameter>
161
162The path to the requested file (a string). Available from the moment
163Spiffy determined the requested URL points to a file (just before the
164{{handle-file}} procedure is called).
165
166<parameter>(current-pathinfo [path])</parameter>
167
168The trailing path ''fragments'' (a list of strings) that were passed
169in the URL after the requested filename. Available from the moment
170Spiffy determined the requested URL points to a file (just before the
171{{handle-file}} procedure is called).
172
173=== Virtual hosts
174
175Spiffy has support for virtual hosting, using the HTTP/1.1 Host
176header.  This allows you to use one Spiffy instance running on one IP
177address/port number to serve multiple webpages, as determined by the
178hostname that was requested.
179
180The virtual host is defined by a procedure, which can set arbitrary
181parameters on-the-fly. It is passed a continuation thunk, which it
182should explicitly call if it wants the processing to continue.  The
183most used parameter in virtual host setups is the {{root-path}}
184parameter, so that another docroot can be selected based on the
185requested hostname, showing different websites for different hosts:
186
187<example>
188<expr>
189(vhost-map `(("foo\\.bar\\.com" .
190               ,(lambda (continue)
191                  (parameterize ((file-extension-handlers
192                                   `(("ssp" . ,ssp-handler) ("ws" . ,web-scheme-handler)))
193                                 (root-path "/var/www/domains/foo.bar.com"))
194                     (continue))))
195             (,(glob->regexp "*.domain.com") .
196                ,(lambda (continue)
197                   (parameterize ((file-extension-handlers
198                                    `(("php" . ,(cgi-handler* "/usr/pkg/bin/php"))))
199                                  (root-path "/var/www/domains/domain.com"))
200                     (continue))))))
201</expr>
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.