source: project/wiki/web-unity @ 10857

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

Add cookie handling note

File size: 7.7 KB
Line 
1[[tags: egg]]
2
3== Web-unity
4
5[[toc:]]
6
7=== Description
8
9A unification framework for web server communications systems like CGI, SCGI or FastCGI and Spiffy.
10
11NOTE: This documentation is a quick write-up. It needs to be improved. The egg is alpha code too.
12
13=== Author
14
15[[Peter Bex]]
16
17=== Requirements
18
19It always needs [[http]]
20
21Extra requirements vary depending on how you want to run it; if you wish to
22use Spiffy, you'll need the [[spiffy]] egg, if you wish to use FastCGI you'll
23need the [[fastcgi]] egg, if you wish to use SCGI you'll need the [[scgi]]
24egg.  If you only need CGI, there are no extra requirements.
25
26=== Download
27
28[[http://www.call-with-current-continuation.org/eggs/web-unity.egg|web-unity.egg]]
29
30=== Documentation
31
32Web-unity is an attempt to remove the differences between the various ways you
33can write web applications with Chicken.  The goal is to ease professional
34webdevelopment by making it possible to deploy on different server architectures
35than you develop on, and making it easier to migrate to a different system
36when the need arises.  This allows you to move from CGI to FastCGI if your
37webserver can't handle the requests any longer, or develop on Spiffy and deploy
38on your Lighttpd production server using SCGI.
39
40This is done by abstracting away a couple of things, so it may mean slightly
41degraded performance or power.
42
43==== wu:set-header!
44
45  (wu:set-header! name value)
46
47Sets a HTTP header in the current response by changing the value of the current-response-headers parameter. If the header was already set it will be overwritten except in the case of Set-Cookie.  In this case, it will just output an additional Set-Cookie header.
48
49==== wu:run-handler
50
51  (wu:run-handler dispatcher)
52
53This invokes the main loop that handles requests.  The dispatcher is a thunk (lambda with no args) that will be invoked
54whenever a request comes in on the server.  This needs to be called last from whatever bootstrap code you run to set up
55a web application.  The run-handler takes care of setting up the environment correctly so that the given dispatcher
56can have the information it needs to work with independently of the type of web server.
57
58==== wu:write-headers
59
60  (wu:write-headers)
61
62Write the current headers from the {{wu:response-headers}} parameter.  This ''must'' be done before emitting any output and it must be done exactly once.
63
64==== wu:get-header
65
66  (wu:get-header name [default])
67
68Get the current value of the given header.  If the optional default is given, this is returned if the header is not found, otherwise {{#f}} is returned.
69
70==== Request parameters
71
72Most request information is available through SRFI-39 parameters.
73
74; {{wu:request-method}} (symbol) : The current request's HTTP method as a lower-cased symbol (get, post).
75; {{wu:params}} (alist) : The current HTTP method's parameters with their values (all strings).  With GET this is equal to the {{query-params}}, with POST it contains the POST request attributes
76; {{wu:query-params}} (alist) : The current query parameters (URL commandline parameters), even if the method is {{post}}, for example.
77; {{wu:script-name}} (string): The absolute path to the script in the URL, up to, but not including, the pathinfo.
78; {{wu:script-filename}} (string) : The absolute path to the script in the filesystem.
79; {{wu:path-info}} (string) : The pathinfo component of the URL (this is the pathname part after the actual script's filename)
80; {{wu:response-headers}} (alist) : The headers that will be sent when you call {{(wu:write-headers)}}.  Default: {{(("Content-Type" . "text/html))}}
81; {{wu:response-code}} (integer-string pair) : The response code that will be sent when you call {{(wu:write-headers)}}. Default: {{(200 . "OK")}}
82; {{wu:headers-sent}} (boolean) : Whether headers have already been sent by {{wu:write-headers}}, during this request
83; {{wu:exception-handler}} (procedure) : Exception handler for exceptions thrown in web-unity code. Override this to get pretty error output and/or hide stack traces.
84
85==== Example
86
87TODO: Invent a better example (one that doesn't statically load one file)
88
89Here is a really small example file that is written in web-unity:
90
91<enscript highlight="scheme">
92  ;; Example.scm
93  (wu:set-header! "content-type" "text/html")
94  (wu:write-headers)
95  (printf "params: ~A<br />\nquery args: ~A\n<br />method: ~A\n" (wu:params) (wu:query-params) (wu:request-method))
96  (printf "parameter (http_)accept = ~A\n<br />" (wu:get-header "accept"))
97  (printf "script-name = ~A\n<br />" (wu:script-name))
98  (printf "script-filename = ~A\n<br />" (wu:script-filename))
99  (printf "<form action=\"\" method=\"post\"><input name=\"foo\" /><input name=\"bar\" /><input type=\"submit\" /></form>")
100</enscript>
101
102You can setup lighttpd using CGI so it loads this script as follows:
103  cgi.assign = ( ".scm" => "/usr/libexec/cgi-dispatcher.scm")
104where the cgi-dispatcher file contains the following:
105
106<enscript highlight="scheme">
107  #!/usr/pkg/bin/csi -s
108
109  (use web-unity-cgi)
110  (wu:run-handler (lambda () (load "example.scm")))
111</enscript>
112
113Lighttpd with FCGI works as follows:
114  fastcgi.server = (
115    ".scm" => (
116      "localhost" => (
117        "socket" => "/tmp/fastcgi-socket",
118        "min-procs" => 1,
119        "max-procs" => 1,
120        "bin-path" => "/usr/libexec/fcgi-dispatcher.scm"
121      )
122    )
123  )
124where the cgi-dispatcher file contains the following:
125
126<enscript highlight="scheme">
127  #!/usr/pkg/bin/csi -s
128
129  (use web-unity-fcgi)
130  (wu:run-handler (lambda () (load "example.scm")))
131</enscript>
132
133Spiffy works a little differently (the web-unity-handler comes with the web-unity egg):
134
135<enscript highlight="scheme">
136  (use web-unity-handler)
137  (spiffy-file-ext-handlers `(("scm" . ,(web-unity-handler "/usr/libexec/spiffy-dispatcher.scm"))))
138</enscript>
139
140where the spiffy-dispatcher file contains the following:
141
142<enscript highlight="scheme">
143  (use web-unity-spiffy)
144  (define lp ##sys#current-load-path)
145  (wu:run-handler (lambda () (load (string-append lp "example.scm"))))
146</enscript>
147
148=== Changelog
149
150* trunk Add support for HTTP/1.1 content chunking and HTTP/1.0 force-close because web-unity does not know the content-length in advance, add exception handling, added missing response code handling in spiffy handler. Add cookie functionality (from spiffy-utils egg. Ported by David Krentzlin)
151* 0.21 Fix 'author' in meta file
152* 0.1 Initial release
153
154=== License
155
156  Copyright (c) 2007, Peter Bex
157  All rights reserved.
158 
159  Redistribution and use in source and binary forms, with or without
160  modification, are permitted provided that the following conditions are
161  met:
162 
163  Redistributions of source code must retain the above copyright
164  notice, this list of conditions and the following disclaimer.
165 
166  Redistributions in binary form must reproduce the above copyright
167  notice, this list of conditions and the following disclaimer in the
168  documentation and/or other materials provided with the distribution.
169 
170  Neither the name of the author nor the names of its contributors may
171  be used to endorse or promote products derived from this software
172  without specific prior written permission.
173 
174  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
175  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
176  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
177  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
178  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
179  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
180  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
181  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
182  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
183  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
184  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
185  OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.