Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 182 lines (133 sloc) 6.213 kb
d773b8b @chneukirchen Add README and other documentation
authored
1 = Rack, a modular Ruby webserver interface
2
ed4bba8 @chneukirchen Fix things that should have been fixed before the release *sigh*
authored
3 Rack provides a minimal, modular and adaptable interface for developing
d773b8b @chneukirchen Add README and other documentation
authored
4 web applications in Ruby. By wrapping HTTP requests and responses in
5 the simplest way possible, it unifies and distills the API for web
9bcca54 @chneukirchen Small README fixes
authored
6 servers, web frameworks, and software in between (the so-called
d773b8b @chneukirchen Add README and other documentation
authored
7 middleware) into a single method call.
8
9 The exact details of this are described in the Rack specification,
10 which all Rack applications should conform to.
11
12 == Supported web servers
13
14 The included *handlers* connect all kinds of web servers to Rack:
15 * Mongrel
e256ec6 @chneukirchen Update README
authored
16 * Mongrel/Swiftcore (require it before Rack.)
d773b8b @chneukirchen Add README and other documentation
authored
17 * WEBrick
18 * FCGI
19 * CGI
20
21 Any valid Rack app will run the same on all these handlers, without
22 changing anything.
23
24 == Supported web frameworks
25
26 The included *adapters* connect Rack with existing Ruby web frameworks:
27 * Camping
28 * Rails (alpha)
29 * more to come soon, ...
30
31 These frameworks include Rack adapters in their distributions:
32 * Ramaze
33 * Maveric
34 * Racktools::SimpleApplication
35
36 == Available middleware
37
38 Between the server and the framework, Rack can be customized to your
39 applications needs using middleware, for example:
40 * Rack::URLMap, to route to multiple applications inside the same process.
253cb49 @chneukirchen Last-minute details
authored
41 * Rack::CommonLogger, for creating Apache-style logfiles.
d773b8b @chneukirchen Add README and other documentation
authored
42 * Rack::ShowException, for catching unhandled exceptions and
253cb49 @chneukirchen Last-minute details
authored
43 presenting them in a nice and helpful way with clickable backtrace.
d773b8b @chneukirchen Add README and other documentation
authored
44 * Rack::File, for serving static files.
45 * ...
46
47 All these components use the same interface, which is described in
48 detail in the Rack specification. You can choose to use them exactly
49 in the way you want.
50
51 == Convenience
52
53 If you want to develop outside of existing frameworks, implement your
54 own ones, or develop middleware, Rack provides many helpers to create
55 Rack applications quickly and without doing the same web stuff all
56 over:
57 * Rack::Request, which also provides query string parsing and
58 multipart handling.
59 * Rack::Response, for convenient generation of HTTP replies and
60 cookie handling.
61 * Rack::MockRequest and Rack::MockResponse for efficient and quick
9bcca54 @chneukirchen Small README fixes
authored
62 testing of Rack application without real HTTP round-trips.
d773b8b @chneukirchen Add README and other documentation
authored
63
64 == rackup
65
66 rackup is a useful tool for running Rack applications, which uses the
67 Rack::Builder DSL to configure middleware and build up applications
68 easily.
69
70 rackup automatically figures out the environment it is run in, and
71 runs your application as FastCGI, CGI, or standalone with Mongrel or
72 WEBrick---all from the same configuration.
73
74 == Quick start
75
76 Try the lobster!
77
78 Either with the embedded WEBrick starter:
79
e256ec6 @chneukirchen Update README
authored
80 ruby -Ilib lib/rack/lobster.rb
d773b8b @chneukirchen Add README and other documentation
authored
81
82 Or with rackup:
83
e256ec6 @chneukirchen Update README
authored
84 bin/rackup -Ilib example/lobster.ru
d773b8b @chneukirchen Add README and other documentation
authored
85
86 By default, the lobster is found at http://localhost:9292.
87
88 == Installing with RubyGems
89
90 A Gem of Rack is available. You can install it with:
91
92 gem install rack
93
94 I also provide a local mirror of the gems (and development snapshots)
95 at my site:
96
97 gem install rack --source http://chneukirchen.org/releases/gems
98
99 == History
100
101 * March 3rd, 2007: First public release 0.1.
102
e256ec6 @chneukirchen Update README
authored
103 * May 16th, 2007: Second public release 0.2.
e5fa2f9 @chneukirchen Integrate patches
authored
104 * HTTP Basic authentication.
cb306d7 @chneukirchen Fix Rack::Session::Cookie
authored
105 * Cookie Sessions.
e276c2d @chneukirchen Integrate Rack::Static
authored
106 * Static file handler.
e256ec6 @chneukirchen Update README
authored
107 * Improved Rack::Request.
108 * Improved Rack::Response.
109 * Added Rack::ShowStatus, for better default error messages.
110 * Bug fixes in the Camping adapter.
111 * Removed Rails adapter, was too alpha.
e5fa2f9 @chneukirchen Integrate patches
authored
112
cdab8c7 @chneukirchen Add LiteSpeed handler
authored
113 * XXX, 2007: Third public release 0.3.
114 * LiteSpeed handler, by Adrian Madrid.
6908a8f @chneukirchen Update AUTHORS and thanks
authored
115 * Pool sessions, by blink.
d2cdb24 @chneukirchen Minor tweaks in blink's code
authored
116 * OpenID authentication, by blink.
117 * :Port and :File options for opening FastCGI sockets, by blink.
118 * Last-Modified HTTP header for Rack::File, by blink.
cdab8c7 @chneukirchen Add LiteSpeed handler
authored
119
d773b8b @chneukirchen Add README and other documentation
authored
120 == Contact
121
122 Please mail bugs, suggestions and patches to
123 <mailto:chneukirchen@gmail.com>.
124
125 Darcs repository ("darcs send" is welcome for patches):
126 http://chneukirchen.org/repos/rack
127
253cb49 @chneukirchen Last-minute details
authored
128 You are also welcome to join the #rack channel on irc.freenode.net.
d773b8b @chneukirchen Add README and other documentation
authored
129
130 == Thanks to
131
e256ec6 @chneukirchen Update README
authored
132 * Michael Fellinger, for the helpful discussion, bugfixes and a better
133 Rack::Request interface.
cdab8c7 @chneukirchen Add LiteSpeed handler
authored
134 * Adrian Madrid, for the LiteSpeed handler.
d773b8b @chneukirchen Add README and other documentation
authored
135 * Christoffer Sawicki, for the Rails adapter.
e5fa2f9 @chneukirchen Integrate patches
authored
136 * Tim Fletcher, for the HTTP authentication code.
6908a8f @chneukirchen Update AUTHORS and thanks
authored
137 * Luc Heinrich for the Cookie sessions, the static file handler and bugfixes.
d2cdb24 @chneukirchen Minor tweaks in blink's code
authored
138 * blink for the Pool sessions, OpenID support, various tweaks, and bugreports.
d773b8b @chneukirchen Add README and other documentation
authored
139 * Armin Ronacher, for the logo and racktools.
e5fa2f9 @chneukirchen Integrate patches
authored
140 * Aredridel, for bug fixing.
e256ec6 @chneukirchen Update README
authored
141 * Gary Wright, for proposing a better Rack::Response interface.
e06975b @chneukirchen Make Rack::Response possibly close the body
authored
142 * Jonathan Buch, for improvements regarding Rack::Response.
6908a8f @chneukirchen Update AUTHORS and thanks
authored
143 * Armin Röhrl, for tracking down bugs in the Cookie generator.
253cb49 @chneukirchen Last-minute details
authored
144 * Alexander Kellett for testing the Gem and reviewing the announce.
d773b8b @chneukirchen Add README and other documentation
authored
145 * Marcus Rückert, for help with configuring and debugging lighttpd.
146 * The WSGI team for the well-done and documented work they've done and
147 Rack builds up on.
148
149 == Copyright
150
151 Copyright (C) 2007 Christian Neukirchen <http://purl.org/net/chneukirchen>
152
153 Permission is hereby granted, free of charge, to any person obtaining a copy
154 of this software and associated documentation files (the "Software"), to
155 deal in the Software without restriction, including without limitation the
156 rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
157 sell copies of the Software, and to permit persons to whom the Software is
158 furnished to do so, subject to the following conditions:
159
160 The above copyright notice and this permission notice shall be included in
161 all copies or substantial portions of the Software.
162
163 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
164 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
165 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
166 THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
167 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
168 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
169
170 == Links
171
172 Rack:: <http://rack.rubyforge.org/>
9bcca54 @chneukirchen Small README fixes
authored
173 Rack's Rubyforge project:: <http://rubyforge.org/projects/rack>
d773b8b @chneukirchen Add README and other documentation
authored
174
175 Camping:: <http://camping.rubyforge.org/>
176 Ramaze:: <http://ramaze.rubyforge.org/>
177 Maveric:: <http://maveric.rubyforge.org/>
178 racktools:: <http://lucumr.pocoo.org/trac/repos/racktools/>
179
180 Christian Neukirchen:: <http://chneukirchen.org/>
181
Something went wrong with that request. Please try again.