Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 209 lines (142 sloc) 7.918 kb
10f925f Eitaro Fukamachi appended README.
authored
1 # Clack - Web Application Environment for Common Lisp
af0a542 Eitaro Fukamachi first commit.
authored
2
afe043a Eitaro Fukamachi some people seem to be confusing Clack for another web framework. I appe...
authored
3 Clack is a web application environment for Common Lisp inspired by Python's WSGI and Ruby's Rack. Your awesome framework should base on this.
c076020 Eitaro Fukamachi rewrote README.
authored
4
af0a542 Eitaro Fukamachi first commit.
authored
5 ## Usage
6
8080e91 Eitaro Fukamachi deleted middleware.
authored
7 (defpackage simple-app
5953db2 Eitaro Fukamachi fixed REAME examples.
authored
8 (:use :cl
cc571d7 Eitaro Fukamachi rewrote README.
authored
9 :clack))
8080e91 Eitaro Fukamachi deleted middleware.
authored
10 (in-package :simple-app)
1ffc108 Eitaro Fukamachi wrote Usage to README.
authored
11
c0696ff Eitaro Fukamachi fixed a note.
authored
12 (defvar *handler*
13 (clackup
14 #'(lambda (env)
15 '(200 (:content-type "text/plain") ("Hello, Clack!")))))
1ffc108 Eitaro Fukamachi wrote Usage to README.
authored
16
e80b676 Eitaro Fukamachi changed default port 8080 -> 5000.
authored
17 Now access [http://localhost:5000/](http://localhost:5000/) and Clack may show you "Hello, Clack!".
cc571d7 Eitaro Fukamachi rewrote README.
authored
18
c0696ff Eitaro Fukamachi fixed a note.
authored
19 To stop the server, you should just call `(clack:stop *handler*)`.
43c09d1 Eitaro Fukamachi added a note to README.
authored
20
afe043a Eitaro Fukamachi some people seem to be confusing Clack for another web framework. I appe...
authored
21 ## About Clack
22
23 ### What is Clack?
24
25 Clack is an interface between CL web applications and web servers. It wraps HTTP requests and responses in the simplest way. This means that it unifies the API for web servers, web frameworks, and software in between (the so-called middleware) into a single method call.
26
27 But not only that.
28
29 ### Middleware is really needed
30
31 Clack provides an idea "Middleware". It allows you to develop something you need without rewriting the existing framework. It can filter HTTP request before it is passed to the application, and can modify HTTP response the application generates.
32
33 This idea is based on that loose coupling is good for writing reusable products.
34
35 There are some middlewares bundled with Clack. You can find them at more below chapter "Bundle Middleware" in this document.
36
cc571d7 Eitaro Fukamachi rewrote README.
authored
37 ## Installation
38
4fe7f4c Eitaro Fukamachi rewrote Installation part in README. Clack is now available on Quicklisp...
authored
39 Clack is now available on [Quicklisp](https://www.quicklisp.org/beta/).
4797523 Eitaro Fukamachi rewrote README, the Installation part.
authored
40
41 (ql:quickload :clack)
1ffc108 Eitaro Fukamachi wrote Usage to README.
authored
42
c3572be Eitaro Fukamachi appended README.
authored
43 ## Application
44
97f935a Eitaro Fukamachi replaced `req' by `env'. Applications and Middlewares should receive "En...
authored
45 Clack Application is just a lambda. It takes exactly one argument, the "Environment", and returns the "Response" as a list containing exactly three values.
c3572be Eitaro Fukamachi appended README.
authored
46
47 (defvar app
97f935a Eitaro Fukamachi replaced `req' by `env'. Applications and Middlewares should receive "En...
authored
48 #'(lambda (env)
c3572be Eitaro Fukamachi appended README.
authored
49 '(200 (:content-type "text/plain") ("Hello, World"))))
50
4797523 Eitaro Fukamachi rewrote README, the Installation part.
authored
51 ### Clack.App.Route
52
53 Clack is not a Web Application Framework. But Clack can also be used as such way.
54
55 Clack bundles "Clack.App.Route", written by [Tomohiro Matsuyama](http://twitter.com/#!/m2ym). It allows you to write an URL-based dispatcher, like Ruby's Sinatra.
56
97f935a Eitaro Fukamachi replaced `req' by `env'. Applications and Middlewares should receive "En...
authored
57 (defroutes app (env)
4797523 Eitaro Fukamachi rewrote README, the Installation part.
authored
58 (GET \"/\" #'index)
59 (GET \"/login\" #'login)
60 (POST \"/login\" #'authorize)
61 (GET \"/member/:id\" #'member))
62
63 (clackup #'app)
64
97f935a Eitaro Fukamachi replaced `req' by `env'. Applications and Middlewares should receive "En...
authored
65 ### The Environment
c3572be Eitaro Fukamachi appended README.
authored
66
8d7be74 Eitaro Fukamachi added examples of Request and Response.
authored
67 Example: http://localhost:4242/sns/member?id=3
68
69 (:request-method :GET
70 :script-name ""
71 :path-info "/sns/member"
72 :query-string "id=3"
73 :server-name "localhost"
74 :server-port 4242
75 :request-uri "/sns/member?id=3"
76 :server-protocol :HTTP/1.1
86fe0f2 Eitaro Fukamachi fixed README a little.
authored
77 :http-user-agent "Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_6; en-US) ..."
8d7be74 Eitaro Fukamachi added examples of Request and Response.
authored
78 :http-remote-addr "127.0.0.1"
79 :http-remote-port 26077
80 :http-referer nil
81 :http-host "localhost:4242"
82 :http-cookies nil
83 :http-server :hunchentoot
84 :%request #<request {11A02249}>)
85
97f935a Eitaro Fukamachi replaced `req' by `env'. Applications and Middlewares should receive "En...
authored
86 The Environment is a list containing at least the following keys and corresponding values.
c3572be Eitaro Fukamachi appended README.
authored
87
88 * <code>:request-method</code> (Required, Keyword): The HTTP request method, must be one of <code>:GET</code>, <code>:HEAD</code>, <code>:OPTIONS</code>, <code>:PUT</code>, <code>:POST</code>, or <code>:DELETE</code>.
89 * <code>:script-name</code> (Required, String): The initial portion of the request URL's path, corresponding to the application. This may be an empty string if the application corresponds to the server's root URI. If this key is not empty, it must start with a forward slash (<code>/</code>).
90 * <code>:path-info</code> (Required, String): The remainder of the request URL's path. This may be an empty string if the request URL targets the application root and does no have a trailing slash.
91 * <code>:query-string</code> (Optional, String): The portion of the request URL that follows the <code>?</code>, if any. This key may be empty, but must always be present, even if empty.
92 * <code>:server-name</code> (Required, String): The resolved server name, or the server IP address.
93 * <code>:server-port</code> (Required, Integer): The port on which the request is being handled.
91594a2 Eitaro Fukamachi implemented most of Request API in clack.handler.hunchentoot.
authored
94 * <code>:server-protocol</code> (Required, Keyword): The version of the protocol the client used to send the request. Typically this will be something like <code>:HTTP/1.0</code> or <code>:HTTP/1.1</code>.
c3572be Eitaro Fukamachi appended README.
authored
95 * <code>:request-uri</code> (Required, String): The request URI. Must start with "/".
96 * <code>:server-protocol</code> (Required, Keyword)
91594a2 Eitaro Fukamachi implemented most of Request API in clack.handler.hunchentoot.
authored
97 * <code>:raw-body</code> (Optional, Stream)
98 * <code>:http-user-agent</code> (Optional, String)
99 * <code>:http-referer</code> (Optional, String)
100 * <code>:remote-addr</code> (Required, String)
101 * <code>:remote-port</code> (Required, Integer)
102
c3572be Eitaro Fukamachi appended README.
authored
103 * <code>:http-server</code> (Required, Keyword): The name of Clack Handler, such as <code>:hunchentoot</code>.
104
8d7be74 Eitaro Fukamachi added examples of Request and Response.
authored
105 ### The Response
106
107 Example:
108
109 (200
110 (:content-type "text/html")
111 ("<b>Hello, Lispers!</b>"))
c3572be Eitaro Fukamachi appended README.
authored
112
113 Applications must return a response as a list containing three values.
114
115 * Status (Required, Integer): An HTTP status code. This must be an integer greater than or equal to 100, and should be an HTTP status code as documented in RFC 2616.
116 * Headers (Required, Property List): An HTTP headers. This must be a property list of key/value pairs.
13553e4 Eitaro Fukamachi appended README about Middleware.
authored
117 * Body (Required, List or Pathname): The response body. This is either a list or a pathname. If it is a list of strings, Handler should output it with #\NewLine for each elements. The body can instead be a pathname for serving static files.
c3572be Eitaro Fukamachi appended README.
authored
118
9fb9fb1 Eitaro Fukamachi rewrote README.
authored
119 ## Handler
120
c3572be Eitaro Fukamachi appended README.
authored
121 Clack Applications run via Clack Handlers, which are in turn responsible for implementing the HTTP protocol and abstracting the server.
122
123 Now Clack Applications works on Hunchentoot and Apache, by using following handler.
124
cc571d7 Eitaro Fukamachi rewrote README.
authored
125 * Clack.Handler.Hunchentoot
fd2ed54 Eitaro Fukamachi added documentations for clack.handler.apache.
authored
126 * Clack.Handler.Apache
9fb9fb1 Eitaro Fukamachi rewrote README.
authored
127
fd2ed54 Eitaro Fukamachi added documentations for clack.handler.apache.
authored
128 If you hope them to run on other server (such as AllegroServe or teepeedee2), you can write a handler for it easily.
10f925f Eitaro Fukamachi appended README.
authored
129
5c0cd38 Eitaro Fukamachi appended README abount Middleware.
authored
130 ## Middleware
131
13553e4 Eitaro Fukamachi appended README about Middleware.
authored
132 Middleware is one of the Clack Component. It takes another Application and runs it.
133
134 ### Bundle Middleware
b678d00 Eitaro Fukamachi appended README about Middleware.
authored
135
cc571d7 Eitaro Fukamachi rewrote README.
authored
136 * Clack.Middleware.Static - Serves static files.
137 * Clack.Middleware.Logger - Logging in Clack Application or Middleware.
138 * Clack.Middleware.Session - Session management.
a7eaf94 Eitaro Fukamachi changed README a bit.
authored
139
140 ### Contrib Middleware
141
cc571d7 Eitaro Fukamachi rewrote README.
authored
142 * Clack.Middleware.OAuth - Authorization by OAuth.
afe043a Eitaro Fukamachi some people seem to be confusing Clack for another web framework. I appe...
authored
143 * Clack.Middleware.Csrf - Provides easy way to protect from CSRF.
144 * Clack.Middleware.Clsql - For CLSQL connection management.
145 * Clack.Middleware.Rucksack - For wrapping Rucksack transaction.
b678d00 Eitaro Fukamachi appended README about Middleware.
authored
146
147 ### How to write Middleware?
8592927 Eitaro Fukamachi fixed middleware example at README.
authored
148
8838ff8 Eitaro Fukamachi fixed README.
authored
149 All you have to do is to inherit from <code>&lt;middleware&gt;</code> and then implement the callback <code>call</code> method (or <code>make-app</code> method that would return a function) to do the actual work. You can use <code>call-next</code> to call the original (wrapped) application.
13553e4 Eitaro Fukamachi appended README about Middleware.
authored
150
8592927 Eitaro Fukamachi fixed middleware example at README.
authored
151 (defpackage clack.middleware.example
cc571d7 Eitaro Fukamachi rewrote README.
authored
152 (:use :cl :clack)
e64a51e Eitaro Fukamachi rewrote README's example about Middleware.
authored
153 (:export :<simple-middleware>))
8592927 Eitaro Fukamachi fixed middleware example at README.
authored
154 (in-package :clack.middleware.example)
5c0cd38 Eitaro Fukamachi appended README abount Middleware.
authored
155
156 (defclass <simple-middleware> (<middleware>) ())
97f935a Eitaro Fukamachi replaced `req' by `env'. Applications and Middlewares should receive "En...
authored
157 (defmethod call ((this <simple-middleware>) env)
e64a51e Eitaro Fukamachi rewrote README's example about Middleware.
authored
158 `(200 (:content-type "text/html")
159 ,(cons "Hello, Clack Middleware!<br />"
97f935a Eitaro Fukamachi replaced `req' by `env'. Applications and Middlewares should receive "En...
authored
160 (nth 2 (call-next this env)))))
8592927 Eitaro Fukamachi fixed middleware example at README.
authored
161
162 (defpackage simple-app
9fb9fb1 Eitaro Fukamachi rewrote README.
authored
163 (:use :cl
cc571d7 Eitaro Fukamachi rewrote README.
authored
164 :clack
5953db2 Eitaro Fukamachi fixed REAME examples.
authored
165 :clack.builder
9fb9fb1 Eitaro Fukamachi rewrote README.
authored
166 :clack.middleware.example))
8592927 Eitaro Fukamachi fixed middleware example at README.
authored
167 (in-package :simple-app)
168
169 (defvar app
97f935a Eitaro Fukamachi replaced `req' by `env'. Applications and Middlewares should receive "En...
authored
170 #'(lambda (env)
cc571d7 Eitaro Fukamachi rewrote README.
authored
171 '(200 (:content-type "text/plain") ("Hello, Clack!"))))
5c0cd38 Eitaro Fukamachi appended README abount Middleware.
authored
172
cc571d7 Eitaro Fukamachi rewrote README.
authored
173 (clackup (builder <simple-middleware> app))
e64a51e Eitaro Fukamachi rewrote README's example about Middleware.
authored
174
175 And you should get following response in time.
176
177 Hello, Clack Middleware!
178 Hello, Clack!
5c0cd38 Eitaro Fukamachi appended README abount Middleware.
authored
179
c076020 Eitaro Fukamachi rewrote README.
authored
180 ## Dependency
181
5aa807c Eitaro Fukamachi rewrote README, Installation part. added macro-utils as a dependency.
authored
182 * cl-annot
10f925f Eitaro Fukamachi appended README.
authored
183 * CL-PPCRE
308f031 Eitaro Fukamachi added specification about request to README.
authored
184 * CL-FAD
10f925f Eitaro Fukamachi appended README.
authored
185 * Alexandria
186 * SPLIT-SEQUENCE
308f031 Eitaro Fukamachi added specification about request to README.
authored
187 * Anaphora
188 * metabang-bind
189 * Hunchentoot
190 * modlisp
e704933 Eitaro Fukamachi added comments to clack.middleware.oauth.
authored
191 * cl-oauth
c076020 Eitaro Fukamachi rewrote README.
authored
192
de1133e Eitaro Fukamachi rewrote README, about license and copyright.
authored
193 ## Author
194
cc571d7 Eitaro Fukamachi rewrote README.
authored
195 * Eitarow Fukamachi (e.arrows@gmail.com)
de1133e Eitaro Fukamachi rewrote README, about license and copyright.
authored
196
197 ## Copyright
198
199 Copyright (c) 2011 Eitarow Fukamachi
200
201 ## Contributors
202
cc571d7 Eitaro Fukamachi rewrote README.
authored
203 * Tomohiro Matsuyama (tomo@cx4a.org)
204 * Norihisa Fujita (n.fujita@ariel-networks.com)
de1133e Eitaro Fukamachi rewrote README, about license and copyright.
authored
205
af0a542 Eitaro Fukamachi first commit.
authored
206 ## License
207
208 Licensed under the LLGPL License.
Something went wrong with that request. Please try again.