Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 241 lines (196 sloc) 9.276 kb
9cc2cde @bernd Revert "Change the URL to the travis-ci logo so it will be shown."
bernd authored
1 # webmachine for Ruby [![travis](https://secure.travis-ci.org/seancribbs/webmachine-ruby.png)](http://travis-ci.org/seancribbs/webmachine-ruby)
b5bafa0 @seancribbs Add a README.
authored
2
b651e5b @seancribbs Complete repository rename and fix a few typos in the docs.
authored
3 webmachine-ruby is a port of
b5bafa0 @seancribbs Add a README.
authored
4 [Webmachine](https://github.com/basho/webmachine), which is written in
5 Erlang. The goal of both projects is to expose interesting parts of
6 the HTTP protocol to your application in a declarative way. This
7 means that you are less concerned with handling requests directly and
8 more with describing the behavior of the resources that make up your
9 application. Webmachine is not a web framework _per se_, but more of a
10 toolkit for building HTTP-friendly applications. For example, it does
11 not provide a templating engine or a persistence layer; those choices
12 are up to you.
13
5709892 @seancribbs Extract header-conversion code and update a bunch of documentation.
authored
14 ## A Note about Rack
15
16 Webmachine has a Rack adapter -- thanks to Jamis Buck -- but when
17 using it, we recommend you ensure that NO middleware is used. The
18 behaviors that are encapsulated in Webmachine could be broken by
19 middlewares that sit above it, and there is no way to detect them at
304e34c 'Emptor' means 'buyer,' 'implementor' approximates 'builder.'
Steven G. Harms authored
20 runtime. _Caveat implementor_. That said, Webmachine should behave properly
5709892 @seancribbs Extract header-conversion code and update a bunch of documentation.
authored
21 when given a clear stack.
b5bafa0 @seancribbs Add a README.
authored
22
23 ## Getting Started
24
11051db @seancribbs Witness the power of this fully functional HTTP toolkit.
authored
25 Webmachine is very young, but it's still easy to construct an
26 application for it!
b5bafa0 @seancribbs Add a README.
authored
27
28 ```ruby
5709892 @seancribbs Extract header-conversion code and update a bunch of documentation.
authored
29 require 'webmachine'
30 # Require any of the files that contain your resources here
31 require 'my_resource'
9bffad4 @seancribbs Roll 0.4.1 and update README with application examples.
authored
32
33 # Create an application which encompasses routes and configruation
34 MyApp = Webmachine::Application.new do |app|
35 app.routes do
36 # Point all URIs at the MyResource class
37 add ['*'], MyResource
38 end
39 end
40
5709892 @seancribbs Extract header-conversion code and update a bunch of documentation.
authored
41 # Start the server, binds to port 8080 using WEBrick
9bffad4 @seancribbs Roll 0.4.1 and update README with application examples.
authored
42 MyApp.run
b5bafa0 @seancribbs Add a README.
authored
43 ```
44
45 Your resource will look something like this:
46
47 ```ruby
5709892 @seancribbs Extract header-conversion code and update a bunch of documentation.
authored
48 class MyResource < Webmachine::Resource
49 def to_html
50 "<html><body>Hello, world!</body></html>"
51 end
52 end
b5bafa0 @seancribbs Add a README.
authored
53 ```
54
55 Run the first file and your application is up. That's all there is to
56 it! If you want to customize your resource more, look at the available
11051db @seancribbs Witness the power of this fully functional HTTP toolkit.
authored
57 callbacks in lib/webmachine/resource/callbacks.rb. For example, you
58 might want to enable "gzip" compression on your resource, for which
59 you can simply add an `encodings_provided` callback method:
60
61 ```ruby
5709892 @seancribbs Extract header-conversion code and update a bunch of documentation.
authored
62 class MyResource < Webmachine::Resource
63 def encodings_provided
64 {"gzip" => :encode_gzip, "identity" => :encode_identity}
65 end
66
67 def to_html
68 "<html><body>Hello, world!</body></html>"
69 end
70 end
11051db @seancribbs Witness the power of this fully functional HTTP toolkit.
authored
71 ```
72
73 There are many other HTTP features exposed to your resource through
5709892 @seancribbs Extract header-conversion code and update a bunch of documentation.
authored
74 {Webmachine::Resource::Callbacks}. Give them a try!
b5bafa0 @seancribbs Add a README.
authored
75
9bffad4 @seancribbs Roll 0.4.1 and update README with application examples.
authored
76 ### Application/Configurator
bb37e72 @bernd Add configurator example to the README.
bernd authored
77
78 There's a configurator that allows you to set the ip address and port
5709892 @seancribbs Extract header-conversion code and update a bunch of documentation.
authored
79 bindings as well as a different webserver adapter. You can also add
9bffad4 @seancribbs Roll 0.4.1 and update README with application examples.
authored
80 your routes in a block (as shown above). Both of these call return the
81 `Webmachine::Application` instance, so you could chain them if you
82 like. If you don't want to create your own separate application
83 object, `Webmachine.application` will return a global one.
bb37e72 @bernd Add configurator example to the README.
bernd authored
84
85 ```ruby
5709892 @seancribbs Extract header-conversion code and update a bunch of documentation.
authored
86 require 'webmachine'
87 require 'my_resource'
88
9bffad4 @seancribbs Roll 0.4.1 and update README with application examples.
authored
89 Webmachine.application.routes do
5709892 @seancribbs Extract header-conversion code and update a bunch of documentation.
authored
90 add ['*'], MyResource
91 end
92
9bffad4 @seancribbs Roll 0.4.1 and update README with application examples.
authored
93 Webmachine.application.configure do |config|
5709892 @seancribbs Extract header-conversion code and update a bunch of documentation.
authored
94 config.ip = '127.0.0.1'
95 config.port = 3000
96 config.adapter = :Mongrel
97 end
98
99 # Start the server.
9bffad4 @seancribbs Roll 0.4.1 and update README with application examples.
authored
100 Webmachine.application.run
bb37e72 @bernd Add configurator example to the README.
bernd authored
101 ```
102
b5bafa0 @seancribbs Add a README.
authored
103 ## Features
104
105 * Handles the hard parts of content negotiation, conditional
106 requests, and response codes for you.
107 * Most callbacks can interrupt the decision flow by returning an
108 integer response code. You generally only want to do this when new
109 information comes to light, requiring a modification of the response.
5709892 @seancribbs Extract header-conversion code and update a bunch of documentation.
authored
110 * Supports WEBrick and Mongrel (1.2pre+), and a Rack shim. Other host
111 servers are being investigated.
112 * Streaming/chunked response bodies are permitted as Enumerables,
113 Procs, or Fibers!
36c2cc9 @seancribbs This is a unique feature of the Ruby version.
authored
114 * Unlike the Erlang original, it does real Language negotiation.
b5bafa0 @seancribbs Add a README.
authored
115
116 ## Problems/TODOs
117
c51e43c @seancribbs Version bump to 0.2.
authored
118 * Command-line tools, and general polish.
b651e5b @seancribbs Complete repository rename and fix a few typos in the docs.
authored
119 * Tracing is exposed as an Array of decisions visited on the response
120 object. You should be able to turn this off and on, and visualize
121 the decisions on the sequence diagram.
c51e43c @seancribbs Version bump to 0.2.
authored
122
bda6b91 @seancribbs webmachine-ruby is Apache licensed. Thanks for catching that, @strmpnk.
authored
123 ## LICENSE
124
125 webmachine-ruby is licensed under the
126 [Apache v2.0 license](http://www.apache.org/licenses/LICENSE-2.0). See
127 LICENSE for details.
128
c51e43c @seancribbs Version bump to 0.2.
authored
129 ## Changelog
130
b2d292d @seancribbs Version bump to 0.4.2.
authored
131 ### 0.4.2 March 22, 2012
132
133 0.4.2 is a bugfix release that corrects a few minor issues. Added Lars
134 Gierth and Rob Gleeson as contributors. Thank you for your
135 contributions!
136
137 * I always intended for Webmachine-Ruby to be Apache licensed, but now
138 that is explicit.
139 * When the `#process_post` callback returns an invalid value, that
140 will now be `inspect`ed in the raised exception's message.
141 * Route bindings are now applied to the `Request` object before the
142 `Resource` class is instantiated. This means you can inspect them
143 inside the `#initialize` method of your resource.
144 * Some `NameError` exceptions and scope problems in the Mongrel
145 adapter were resolved.
146 * URL-encoded `=` characters in the query string decoded in the proper
147 order.
148
9bffad4 @seancribbs Roll 0.4.1 and update README with application examples.
authored
149 ### 0.4.1 February 8, 2012
150
151 0.4.1 is a bugfix release that corrects a few minor issues. Added Sam
152 Goldman as a contributor. Thank you for your contributions!
153
154 * Updated README with `Webmachine::Application` examples.
155 * The CGI env vars `CONTENT_LENGTH` and `CONTENT_TYPE` are now being
156 correctly converted into their Webmachine equivalents.
157 * The request body given via the Rack and Mongrel adapters now
158 responds to `#to_s` and `#each` so it can be treated like a `String`
159 or `Enumerable` that yields chunks.
160
161 ### 0.4.0 February 5, 2012
ed0e765 @seancribbs Update README with release notes. [ci skip]
authored
162
163 0.4.0 includes some important refactorings, isolating the idea of
164 global state into an Application object with its own Dispatcher and
165 configuration, and making Adapters into real classes with a consistent
166 interface. It also adds some query methods on the Request object for
167 the HTTP method and scheme and Route guards (matching predicates).
168 Added Michael Maltese, Emmanuel Gomez, and Bernerd Schaefer as
169 committers. Thank you for your contributions!
170
171 * Fixed `Request#query` to handle nil values for the URI query accessor.
172 * `Webmachine::Dispatcher` is a real class rather than a module with
173 state.
174 * `Webmachine::Application` is a class that includes its own
175 dispatcher and configuration. The default instance is accessible via
176 `Webmachine.application`.
177 * `Webmachine::Adapter` is now the superclass of all implemented
178 adapters so that they have a uniform interface.
179 * The Mongrel spec is skipped on JRuby since version 1.2 (pre-release)
180 doesn't work. Direct Mongrel support may be removed in a later
181 release.
182 * `Webmachine::Dispatcher::Route` now accepts guards, which may be
183 expressed as lambdas/procs or any object responding to `call`
184 preceding the `Resource` class in the route definition, or as a
185 trailing block. All guards will be passed the `Request` object when
186 matching the route and should return a truthy or falsey value
187 (without side-effects).
188
d99417e @seancribbs Version bump to v0.3.0
authored
189 ### 0.3.0 November 9, 2011
190
191 0.3.0 introduces some new features, refactorings, and now has 100%
192 documentation coverage! Among the new features are minimal Rack
193 compatibility, streaming responses via Fibers and a friendlier route
194 definition syntax. Added Jamis Buck as a committer. Thank you for your
195 contributions!
196
197 * Chunked bodies are now wrapped in a way that works on webservers
198 that don't automatically produce them.
199 * HTTP Basic Authentication is easy to add to resources, just include
200 `Webmachine::Resource::Authentication`.
201 * Routes are a little less painful to add, you can now specify them
202 with `Webmachine.routes` which will be evaled into the `Dispatcher`.
203 * The new default port is 8080.
204 * Rack is minimally supported as a host server. _Don't put middleware
205 above Webmachine!_
206 * Fibers can be used as streamed response bodies.
207 * `Dispatcher#add_route` will now return the added `Route` instance.
208 * The header-conversion code for CGI-style servers has been extracted
209 into `Webmachine::Headers`.
210 * `Route#path_spec` is now public so that applications can inspect
211 existing routes, perhaps for URL generation.
212 * `Request#query` now uses `CGI.unescape` so '+' characters are
213 correctly parsed.
214 * YARD documentation has 100% coverage.
215
c51e43c @seancribbs Version bump to 0.2.
authored
216 ### 0.2.0 September 11, 2011
217
218 0.2.0 includes an adapter for Mongrel and a central place for
219 configuration as well as numerous bugfixes. Added Ian Plosker and
220 Bernd Ahlers as committers. Thank you for your contributions!
221
222 * Acceptable media types are matched less strictly, which has
223 implications on both responses and PUT requests. See the
224 [discussion on the commit](https://github.com/seancribbs/webmachine-ruby/commit/3686d0d9ff77fc98aff59f89478e9c6c18844ca1).
225 * Resources now receive a callback after the language has been
226 negotiated, so they can decide what to do with it.
227 * Added `Webmachine::Configuration` so we can more easily support more
228 than one host server/adapter.
229 * Added Mongrel adapter, supporting 1.2pre+.
230 * Media type headers are more lax about whitespace following
231 semicolons.
232 * Fix some problems with callable response bodies.
233 * Make sure String response bodies get a Content-Length header added
234 and streaming responses get chunked encoding.
235 * Numerous refactorings, including extracting `MediaType` into its own
236 top-level class.
237
238 ### 0.1.0 August 25, 2011
239
240 This is the initial release. Most things work, but only WEBrick is supported.
Something went wrong with that request. Please try again.