webmachine 1.2.2 → 1.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9c535ba9701c69baab3387693d7060214271a615
+  data.tar.gz: 2701314eb2dd27ba6af46013532b6e653f63ac95
+SHA512:
+  metadata.gz: 5e24dfb767ed02c92a69c8d8962dad39abb1652baeb0f7852a692cf61f5baa6fbd36ca297dfca9b10a3262579c4047b83ea6fe1861927177fa50f4e6522803d2
+  data.tar.gz: a2cabce4143030fbec07b5ebdc65c38c1018df32fe6844a23c0ced95c1dc88e434be17c260dadb0205d6279a6c915c67c321f62665a4a4b247f1da9145d42775

data/.gitignore

@@ -26,3 +26,7 @@ Gemfile.lock
 **/bin
 *.rbc
 .rvmrc
+.SyncID
+.SyncIgnore
+vendor
+

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+### HEAD
+
+* decode the value of the header 'Content-MD5' as base64-encoded string.
+
 ### 1.2.2 January 8, 2014
 
 1.2.2 is a bugfix/patch release that expands functionality with some edge

data/Gemfile

@@ -1,15 +1,22 @@
 require 'rbconfig'
-
 source 'https://rubygems.org'
-
 gemspec
 
-gem 'bundler'
+group :development do
+  gem "yard"
+  gem "rake"
+end
+
+group :test do
+  gem "rspec", '~> 3.0.0'
+  gem "rspec-its"
+  gem "rack"
+end
 
 group :webservers do
-  gem 'mongrel',  '~> 1.2.beta', :platform => [:mri, :rbx]
-  gem 'reel', '~> 0.4.0.pre5'
-  gem 'hatetepe', '~> 0.5.2'
+  gem 'reel', '~> 0.5.0'
+  gem 'http', '~> 0.6.0'
+  gem 'httpkit', :platform => [:mri, :rbx]
 end
 
 group :guard do
@@ -34,8 +41,3 @@ end
 platforms :jruby do
   gem 'jruby-openssl'
 end
-
-platform :rbx do
-  gem 'rubysl'
-  gem 'racc'
-end

data/README.md

@@ -4,9 +4,10 @@ webmachine-ruby is a port of
 [Webmachine](https://github.com/basho/webmachine), which is written in
 Erlang.  The goal of both projects is to expose interesting parts of
 the HTTP protocol to your application in a declarative way.  This
-means that you are less concerned with handling requests directly and
-more with describing the behavior of the resources that make up your
-application. Webmachine is not a web framework _per se_, but more of a
+means that you are less concerned with the procedures involved in handling
+requests directly and more with describing facts about the resources
+that make up your application.
+Webmachine is not a web framework _per se_, but more of a
 toolkit for building HTTP-friendly applications. For example, it does
 not provide a templating engine or a persistence layer; those choices
 are up to you.
@@ -15,46 +16,34 @@ are up to you.
 
 * Handles the hard parts of content negotiation, conditional
   requests, and response codes for you.
-* Most callbacks can interrupt the decision flow by returning an
-  integer response code. You generally only want to do this when new
-  information comes to light, requiring a modification of the response.
-* Supports WEBrick and Mongrel (1.2pre+), and a Rack shim. Other host
+* Provides a base resource with points of extension to let you
+  describe what is relevant about your particular resource.
+* Supports WEBrick, Reel, HTTPkit, and a Rack shim. Other host
   servers are being investigated.
 * Streaming/chunked response bodies are permitted as Enumerables,
   Procs, or Fibers!
 * Unlike the Erlang original, it does real Language negotiation.
-* Includes the visual debugger so you can look through the decision
+* Includes a visual debugger so you can look through the decision
   graph to determine how your resources are behaving.
 
 ## Documentation & Finding Help
 
+* [How it works](/documentation/how-it-works.md) - understand how Webmachine works and the basics of creating a resource.
+* [Example resources][example-resources] showing how to implement each HTTP method.
+* [Routes][routes]
+* [Authentication and authorization][authentication-and-authorization]
+* [Validation][validation]
+* [Error handling][error-handling]
+* [Visual debugger][visual-debugger]
+* [Configurator][configurator]
+* [Webserver adapters][adapters]
+* [Versioning APIs][versioning-apis]
 * [API documentation](http://rubydoc.info/gems/webmachine/frames/file/README.md)
 * [Mailing list](mailto:webmachine.rb@librelist.com)
 * IRC channel #webmachine on freenode
 
-## A Note about Rack
-
-In order to be compatible with popular deployment stacks,
-Webmachine has a [Rack](https://github.com/rack/rack) adapter (thanks to Jamis Buck).
-**n.b.:** We recommend that NO middleware is used. The
-behaviors that are encapsulated in Webmachine assume that no modifications
-are done to requests or response outside of Webmachine.
-
-## A Note about MRI 1.9
-
-The [Reel](https://github.com/celluloid/reel) and [Hatetepe](https://github.com/lgierth/hatetepe)
-adapters might crash with a `SystemStackError` on MRI 1.9 due to its
-limited fiber stack size. If your application is affected by this, the
-only known solution is to switch to JRuby, Rubinius or MRI 2.0.
-
-
 ## Getting Started
 
-[GiddyUp](https://github.com/basho/giddyup) is an actively
-developed webmachine-ruby app that is in production. You
-can look there for an example of how to write and structure a
-webmachine-ruby app (although it is hacky in places).
-
 Below we go through some examples of how to do basic things
 with webmachine-ruby.
 
@@ -71,8 +60,11 @@ There are many other HTTP features exposed to a resource through
 of the decision tree Webmachine implements, and the decision tree
 is what makes Webmachine unique and powerful.
 
+### A simple static  HTML resource
+
 ```ruby
 require 'webmachine'
+
 class MyResource < Webmachine::Resource
   def to_html
     "<html><body>Hello, world!</body></html>"
@@ -83,6 +75,39 @@ end
 MyResource.run
 ```
 
+### A simple dynamic JSON Resource
+
+```ruby
+require 'webmachine'
+require 'widget'
+
+class MyResource < Webmachine::Resource
+
+  # GET and HEAD are allowed by default, but are shown here for clarity.
+  def allowed_methods
+    ['GET','HEAD']
+  end
+
+  def content_types_provided
+    [['application/json', :to_json]]
+  end
+
+  # Return a Truthy or Falsey value
+  def resource_exists?
+    widget
+  end
+
+  def widget
+    @widget ||= Widget.find(request.path_info[:id])
+  end
+
+  def to_json
+    widget.to_json
+  end
+end
+
+```
+
 ### Router
 
 The router is used to map a resource to a given path. To map the class `MyResource` to
@@ -97,83 +122,44 @@ end
 Webmachine.application.run
 ```
 
-### Application/Configurator
-
-There's a configurator that allows you to set what IP address and port
-a web server should bind to as well as what web server should serve a
-webmachine resource.
-
-A call to `Webmachine::Application#configure` returns a `Webmachine::Application` instance,
-so you could chain other method calls if you like. If you don't want to create your own separate
-application object `Webmachine.application` will return a global one.
+When the resource needs to be mapped with variables that will be passed into the resource, use symbols to identify which path components are variables.
 
 ```ruby
-require 'webmachine'
-require 'my_resource'
 
-Webmachine.application.configure do |config|
-  config.ip = '127.0.0.1'
-  config.port = 3000
-  config.adapter = :Mongrel
+Webmachine.application.routes do
+  add ['myresource', :id], MyResource
 end
 
-# Start a web server to serve requests via localhost
-Webmachine.application.run
 ```
 
-Webmachine includes adapters for [Webrick][webrick], [Mongrel][mongrel],
-[Reel][reel], and [Hatetepe][hatetepe]. Additionally, the [Rack][rack] adapter lets it
-run on any webserver that provides a Rack interface. It also lets it run on
-[Shotgun][shotgun] ([example][shotgun_example]).
-
-[webrick]: http://rubydoc.info/stdlib/webrick
-[mongrel]: https://github.com/evan/mongrel
-[reel]: https://github.com/celluloid/reel
-[hatetepe]: https://github.com/lgierth/hatetepe
-[rack]: https://github.com/rack/rack
-[shotgun]: https://github.com/rtomayko/shotgun
-[shotgun_example]: https://gist.github.com/4389220
-
-### Visual debugger
-
-It can be hard to understand all of the decisions that Webmachine
-makes when servicing a request to your resource, which is why we have
-the "visual debugger". In development, you can turn on tracing of the
-decision graph for a resource by implementing the `#trace?` callback
-so that it returns true:
+To add more components to the URL mapping, simply add them to the array.
 
 ```ruby
-class MyTracedResource < Webmachine::Resource
-  def trace?
-    true
-  end
 
-  # The rest of your callbacks...
+Webmachine.application.routes do
+  add ['myparentresource', :parent_id, 'myresource', :id], MyResource
 end
+
 ```
 
-Then enable the visual debugger resource by adding a route to your
-configuration:
+Read more about routing [here][routes].
 
-```ruby
-Webmachine.application.routes do
-  # This can be any path as long as it ends with '*'
-  add ['trace', '*'], Webmachine::Trace::TraceResource
-  # The rest of your routes...
-end
-```
+### Application/Configurator
+
+There is a configurator that allows you to set what IP address and port
+a web server should bind to as well as what web server should serve a
+webmachine resource. Learn how to configure your application [here][configurator].
 
-Now when you visit your traced resource, a trace of the request
-process will be recorded in memory. Open your browser to `/trace` to
-list the recorded traces and inspect the result. The response from your
-traced resource will also include the `X-Webmachine-Trace-Id` that you
-can use to lookup the trace. It might look something like this:
 
-![preview calls at decision](http://seancribbs-skitch.s3.amazonaws.com/Webmachine_Trace_2156885920-20120625-100153.png)
+### Adapters
 
-Refer to
-[examples/debugger.rb](/examples/debugger.rb)
-for an example of how to enable the debugger.
+Webmachine provides adapters for many popular webservers. Learn more [here][adapters].
+
+### Visual debugger
+
+It can be hard to understand all of the decisions that Webmachine
+makes when servicing a request to your resource, which is why we have
+the "visual debugger". Learn how to configure it [here][visual-debugger].
 
 ## Related libraries
 
@@ -183,6 +169,7 @@ for an example of how to enable the debugger.
 * [webmachine-sprockets](https://github.com/lgierth/webmachine-sprockets) - Integration with Sprockets assets packaging system
 * [webmachine-actionview](https://github.com/rgarner/webmachine-actionview) - Integration of some Rails-style view conventions into Webmachine
 * [jruby-http-kit](https://github.com/nLight/jruby-http-kit) - Includes an adapter for the Clojure-based Ring library/server
+* [newrelic-webmachine](https://github.com/mdub/newrelic-webmachine) - NewRelic instrumentation
 
 ## LICENSE
 
@@ -190,3 +177,12 @@ webmachine-ruby is licensed under the
 [Apache v2.0 license](http://www.apache.org/licenses/LICENSE-2.0). See
 LICENSE for details.
 
+[example-resources]: /documentation/examples.md
+[versioning-apis]: /documentation/versioning-apis.md
+[routes]: /documentation/routes.md
+[error-handling]: /documentation/error-handling.md
+[authentication-and-authorization]: /documentation/authentication-and-authorization.md
+[adapters]: /documentation/adapters.md
+[visual-debugger]: /documentation/visual-debugger.md
+[configurator]: /documentation/configurator.md
+[validation]: /documentation/validation.md

data/Rakefile

@@ -51,7 +51,6 @@ task :clean_whitespace do
   end
 end
 
-require 'rspec/core'
 require 'rspec/core/rake_task'
 
 desc "Run specs"

data/documentation/adapters.md

@@ -0,0 +1,39 @@
+### Adapters
+
+Webmachine includes adapters for [WEBrick][webrick], [Reel][reel], and
+[HTTPkit][httpkit]. Additionally, the [Rack][rack] adapter lets it
+run on any webserver that provides a Rack interface. It also lets it run on
+[Shotgun][shotgun] ([example][shotgun_example]).
+
+#### A Note about Rack
+
+In order to be compatible with popular deployment stacks,
+Webmachine has a [Rack](https://github.com/rack/rack) adapter (thanks to Jamis Buck).
+
+Webmachine can be used with Rack middlware features such as Rack::Map and Rack::Cascade as long as:
+
+1. The Webmachine app is mounted at the root directory.
+2. Any requests/responses that are handled by the Webmachine app are not modified by the middleware. The behaviours that are encapsulated in Webmachine assume that no modifications
+are done to requests or response outside of Webmachine.
+
+Keep in mind that Webmachine already supports many things that Rack middleware is used for with other HTTP frameworks (eg. etags, specifying supported/preferred Accept and Content-Types).
+
+For an example of using Webmachine with Rack middleware, see the [Pact Broker][middleware-example].
+
+See the [Rack Adapter API docs][rack-adapter-api-docs] for more information.
+
+#### A Note about MRI 1.9
+
+The [Reel][reel] and [HTTPkit][httpkit]
+adapters might crash with a `SystemStackError` on MRI 1.9 due to its
+limited fiber stack size. If your application is affected by this, the
+only known solution is to switch to JRuby, Rubinius or MRI 2.0.
+
+[webrick]: http://rubydoc.info/stdlib/webrick
+[reel]: https://github.com/celluloid/reel
+[httpkit]: https://github.com/lgierth/httpkit
+[rack]: https://github.com/rack/rack
+[shotgun]: https://github.com/rtomayko/shotgun
+[shotgun_example]: https://gist.github.com/4389220
+[rack-adapter-api-docs]: http://rubydoc.info/gems/webmachine/Webmachine/Adapters/Rack
+[middleware-example]: https://github.com/bethesque/pact_broker/blob/6dfa71d98e38be94f0776d30bf66cfca58f97d61/lib/pact_broker/app.rb

data/documentation/authentication-and-authorization.md

@@ -0,0 +1,37 @@
+# Authentication
+
+To secure a resource, override the `is_authorized?` method to return a boolean indicating whether or not the client is authenticated (ie. your application believes they are who they say they are). Confusingly, the HTTP "401 Unauthorized" response code actually relates to authentication, not authorization (see the [Authorization](#authorization) section below).
+
+## HTTP Basic Auth
+
+```ruby
+
+class MySecureResource < Webmachine::Resource
+
+  include Webmachine::Resource::Authentication
+
+  def is_authorized?(authorization_header)
+    basic_auth(authorization_header, "My Application") do |username, password|
+      @user = User.find_by_username(username)
+      !@user.nil? && @user.auth?(password)
+    end
+  end
+
+end
+
+```
+
+# Authorization
+
+Once the client is authenticated (that is, you believe they are who they say they are), override `forbidden?` to return true if the client does not have permission to perform the given method this resource.
+
+```ruby
+
+class MySecureResource < Webmachine::Resource
+
+  def forbidden?
+    MySecureResourcePolicy.new(@user, my_secure_domain_model).forbidden?(request.method)
+  end
+
+end
+```

data/documentation/configurator.md

@@ -0,0 +1,19 @@
+### Application/Configurator
+
+A call to `Webmachine::Application#configure` returns a `Webmachine::Application` instance,
+so you could chain other method calls if you like. If you don't want to create your own separate
+application object `Webmachine.application` will return a global one.
+
+```ruby
+require 'webmachine'
+require 'my_resource'
+
+Webmachine.application.configure do |config|
+  config.ip = '127.0.0.1'
+  config.port = 3000
+  config.adapter = :WEBrick
+end
+
+# Start a web server to serve requests via localhost
+Webmachine.application.run
+```

data/documentation/error-handling.md

@@ -0,0 +1,86 @@
+# Error handling
+
+## Handling runtime errors
+
+Runtime errors should happen infrequently when using Webmachine, as many of the potential causes of "error" will have already been checked in the appropriate callback, and handled with a meaningful HTTP response code (eg. `resource_exists?` or `is_authorized?`).
+
+To return a custom error response, override `handle_exception` and modify the response body and headers as desired.
+
+```ruby
+
+class MyResource < Webmachine::Resource
+
+  def handle_exception e
+    response.headers['Content-Type'] = 'application/json'
+    response.body = {:message => e.message, :backtrace => e.backtrace }.to_json
+  end
+
+end
+
+```
+
+Given that this should be a genuine "Server Error", the response code is set to 500, and cannot be overridden in `handle_exception`. If you must set a custom error response code, but were unable to use one of the previous callbacks to set it, use `finish_request` to set the response code as desired.
+
+## Customising the error response
+
+You can modify the response headers and body in any callback.
+
+```ruby
+
+class MyResource < Webmachine::Resource
+
+  def resource_exists?
+    @droid = Droid.find(request.path_info[:droid_id]).tap do | droid |
+      unless droid
+        response.headers['Content-Type'] = "text/plain"
+        response.body = "These aren't the droids you're looking for."
+      end
+    end
+  end
+
+end
+
+```
+
+## Returning a custom error code
+
+If your response code cannot be determined in an appropriate callback, returning an integer response code from most of the callbacks will cause the response to be returned immediately. You generally only want to do this when new information comes to light, requiring a modification of the response.
+
+```ruby
+
+class MyResource < Webmachine::Resource
+
+  def content_types_accepted
+    [
+      ["application/json", :from_json],
+      ["application/xml", :from_xml]
+    ]
+  end
+
+  def malformed_request?
+    # Is this JSON or XML? Don't know without a messy if statement.
+    # Maybe cleaner to decide in the response handler for the appropriate Content-Type?
+    false
+  end
+
+  def from_json
+    return 400 if invalid_json?
+    ...
+  end
+
+  def from_xml
+    return 400 if invalid_xml?
+    ...
+  end
+
+  def invalid_json?
+    ...
+  end
+
+  def invalid_xml?
+    ...
+  end
+
+end
+
+```