source: project/wiki/web-unity @ 10860

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

Describe new cookie procedures in web-unity

File size: 9.2 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==== wu:cookie-set!
71
72  (wu:cookie-set! name value #!key comment max-age domain path secure)
73
74Set the current value of the RFC2109 cookie with the given name.
75
76Cookies will expire when the session ends (usually when the browser closes) unless {{MAX-AGE}} is supplied, which is an integer argument declaring the maximum time the cookie can be stored on the client side, in seconds. A {{MAX-AGE}} of 0 also results in the cookie being deleted when the session ends.
77
78{{COMMENT}} is an optional comment specifying the nature of the cookie. The user will see this in his browser's cookie store, and may use this to decide wether or not to accept the cookie.
79
80The {{DOMAIN}} string specifies for which domain the cookie is. The cookie will only be returned on subsequent requests to that domain. By default, the domain is the domain from which the cookie originates.
81
82The {{PATH}} string specifies the topmost path from which this cookie is active. If there are multiple cookies with the same name, the value from the cookie with the most specific ("deepest") path will be passed to the server.
83
84Finally, the boolean {{SECURE}} can be set to {{#t}} if the cookie should be treated as confidential information.
85
86==== wu:cookie-delete!
87
88  (wu:cookie-delete! name #!key domain path)
89
90Delete the given cookie. Equivalent to calling {{wu:cookie-set!}} with a {{MAX-AGE}} of zero.
91
92==== Request parameters
93
94Most request information is available through SRFI-39 parameters.
95
96; {{wu:request-method}} (symbol) : The current request's HTTP method as a lower-cased symbol (get, post).
97; {{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
98; {{wu:cookies}} (alist) : The current RFC2109 cookies, as name-value pairs (all strings).
99; {{wu:query-params}} (alist) : The current query parameters (URL commandline parameters), even if the method is {{post}}, for example.
100; {{wu:script-name}} (string): The absolute path to the script in the URL, up to, but not including, the pathinfo.
101; {{wu:script-filename}} (string) : The absolute path to the script in the filesystem.
102; {{wu:path-info}} (string) : The pathinfo component of the URL (this is the pathname part after the actual script's filename)
103; {{wu:response-headers}} (alist) : The headers that will be sent when you call {{(wu:write-headers)}}.  Default: {{(("Content-Type" . "text/html))}}
104; {{wu:response-code}} (integer-string pair) : The response code that will be sent when you call {{(wu:write-headers)}}. Default: {{(200 . "OK")}}
105; {{wu:headers-sent}} (boolean) : Whether headers have already been sent by {{wu:write-headers}}, during this request
106; {{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.
107
108==== Example
109
110TODO: Invent a better example (one that doesn't statically load one file)
111
112Here is a really small example file that is written in web-unity:
113
114<enscript highlight="scheme">
115  ;; Example.scm
116  (wu:set-header! "content-type" "text/html")
117  (wu:write-headers)
118  (printf "params: ~A<br />\nquery args: ~A\n<br />method: ~A\n" (wu:params) (wu:query-params) (wu:request-method))
119  (printf "parameter (http_)accept = ~A\n<br />" (wu:get-header "accept"))
120  (printf "script-name = ~A\n<br />" (wu:script-name))
121  (printf "script-filename = ~A\n<br />" (wu:script-filename))
122  (printf "<form action=\"\" method=\"post\"><input name=\"foo\" /><input name=\"bar\" /><input type=\"submit\" /></form>")
123</enscript>
124
125You can setup lighttpd using CGI so it loads this script as follows:
126  cgi.assign = ( ".scm" => "/usr/libexec/cgi-dispatcher.scm")
127where the cgi-dispatcher file contains the following:
128
129<enscript highlight="scheme">
130  #!/usr/pkg/bin/csi -s
131
132  (use web-unity-cgi)
133  (wu:run-handler (lambda () (load "example.scm")))
134</enscript>
135
136Lighttpd with FCGI works as follows:
137  fastcgi.server = (
138    ".scm" => (
139      "localhost" => (
140        "socket" => "/tmp/fastcgi-socket",
141        "min-procs" => 1,
142        "max-procs" => 1,
143        "bin-path" => "/usr/libexec/fcgi-dispatcher.scm"
144      )
145    )
146  )
147where the cgi-dispatcher file contains the following:
148
149<enscript highlight="scheme">
150  #!/usr/pkg/bin/csi -s
151
152  (use web-unity-fcgi)
153  (wu:run-handler (lambda () (load "example.scm")))
154</enscript>
155
156Spiffy works a little differently (the web-unity-handler comes with the web-unity egg):
157
158<enscript highlight="scheme">
159  (use web-unity-handler)
160  (spiffy-file-ext-handlers `(("scm" . ,(web-unity-handler "/usr/libexec/spiffy-dispatcher.scm"))))
161</enscript>
162
163where the spiffy-dispatcher file contains the following:
164
165<enscript highlight="scheme">
166  (use web-unity-spiffy)
167  (define lp ##sys#current-load-path)
168  (wu:run-handler (lambda () (load (string-append lp "example.scm"))))
169</enscript>
170
171=== Changelog
172
173* 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)
174* 0.21 Fix 'author' in meta file
175* 0.1 Initial release
176
177=== License
178
179  Copyright (c) 2007, Peter Bex
180  All rights reserved.
181 
182  Redistribution and use in source and binary forms, with or without
183  modification, are permitted provided that the following conditions are
184  met:
185 
186  Redistributions of source code must retain the above copyright
187  notice, this list of conditions and the following disclaimer.
188 
189  Redistributions in binary form must reproduce the above copyright
190  notice, this list of conditions and the following disclaimer in the
191  documentation and/or other materials provided with the distribution.
192 
193  Neither the name of the author nor the names of its contributors may
194  be used to endorse or promote products derived from this software
195  without specific prior written permission.
196 
197  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
198  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
199  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
200  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
201  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
202  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
203  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
204  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
205  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
206  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
207  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
208  OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.