webmachine 1.2.2 → 1.6.0

data/documentation/adapters.md

@@ -0,0 +1,41 @@
+### 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 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).
+
+The base `Webmachine::Adapters::Rack` class assumes the Webmachine application
+is mounted at the route path `/` (i.e. not using `Rack::Builder#map` or Rails
+`ActionDispatch::Routing::Mapper::Base#mount`). In order to
+map to a subpath, use the `Webmachine::Adapters::RackMapped` adapter instead.
+
+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
+
+```

data/documentation/examples.md

@@ -0,0 +1,224 @@
+Imagine an application with an "orders" resource, `OrdersResource`, that represents the collection of orders in the application, and an "order" resource, `OrderResource`, that represents a single order object.
+
+This is how the /orders and /orders/:id routes are mapped to their respective resource classes.
+
+```ruby
+App = Webmachine::Application.new do |app|
+  app.routes do
+    add ["orders"], OrdersResource
+    add ["orders", :id], OrderResource
+  end
+end
+```
+
+# GET
+* Override `resource_exists?`, `content_types_provided`, `allowed_methods`, and implement the method to render the resource.
+
+Curious as to which order the callbacks will be invoked in? Read why it [doesn't have to matter](#callback-order).
+
+```ruby
+class OrderResource < Webmachine::Resource
+  def allowed_methods
+    ["GET"]
+  end
+
+  def content_types_provided
+    [["application/json", :to_json]]
+  end
+
+  def resource_exists?
+    order
+  end
+
+  def to_json
+    order.to_json
+  end
+
+  private
+
+  def order
+    @order ||= Order.new(params)
+  end
+
+  def id
+    request.path_info[:id]
+  end
+end
+
+```
+
+# POST to create a new resource in a collection
+* Override `post_is_create?` to return true
+* Override `create_path` to return the relative path to the new resource. Note that `create_path` will be called _before_ the content type handler (eg. `from_json`) is called, which means that you need to know the ID before the object has been inserted into the database. This might seem a hassle, but it stops you from exposing your database column IDs to the world, which is a naughty and lazy habit we've all picked up from Rails.
+* The response Content-Type and status will be set for you.
+
+```ruby
+class OrdersResource < Webmachine::Resource
+
+  def allowed_methods
+    ["POST"]
+  end
+
+  def content_types_accepted
+    [["application/json", :from_json]]
+  end
+
+  def post_is_create?
+    true
+  end
+
+  def create_path
+    "/orders/#{next_id}"
+  end
+
+  private
+
+  def from_json
+    response.body = new_order.save(next_id).to_json
+  end
+
+  def next_id
+    @id ||= Order.next_id
+  end
+
+  def new_order
+    @new_order ||= Order.new(params)
+  end
+
+  def params
+    JSON.parse(request.body.to_s)
+  end
+end
+```
+
+# POST to perform a task
+* Override `allowed_methods`, `process_post`, and `content_types_provided` (if the response has a content type).
+* Rather than providing a method handler in the `content_type_provided` mappings, put all the code to be executed in `process_post`.
+* `process_post` must return true, or the HTTP response code.
+
+```ruby
+class DispatchOrderResource < Webmachine::Resource
+  def content_types_provided
+    [["application/json"]]
+  end
+
+  def allowed_methods
+    ["POST"]
+  end
+
+  def resource_exists?
+    @order = Order.find(id)
+  end
+
+  def process_post
+    @order.dispatch(params['some_param'])
+    response.body = { message: "Successfully dispatched order #{id}" }.to_json
+    true
+  end
+
+  private
+
+  def id
+    request.path_info[:id]
+  end
+
+  def params
+    JSON.parse(request.body.to_s)
+  end
+end
+
+```
+
+# PUT
+* Override `resource_exists?`, `content_types_accepted`, `allowed_methods`, and implement the method to create/replace the resource.
+
+```ruby
+class OrderResource < Webmachine::Resource
+
+  def allowed_methods
+    ["PUT"]
+  end
+
+  def content_types_accepted
+    [["application/json", :from_json]]
+  end
+
+  # Note that returning falsey will NOT result in a 404 for PUT requests.
+  # See note below.
+  def resource_exists?
+    order
+  end
+
+  def from_json
+    # Remember PUT should replace the entire resource, not merge the attributes! That's what PATCH is for.
+    # It's also why you should not expose your database IDs as your API IDs.
+    order.destroy if order
+    new_order = Order.new(params)
+    new_order.save(id)
+    response.body = new_order.to_json
+  end
+
+  private
+
+  def order
+    @order ||= Order.find(id)
+  end
+
+  def params
+    JSON.parse(request.body.to_s)
+  end
+
+  def id
+    request.path_info[:id]
+  end
+end
+```
+
+If you wish to disallow PUT to a non-existent resource, read more [here](https://github.com/webmachine/webmachine-ruby/issues/207#issuecomment-132604379).
+
+# PATCH
+* Webmachine does not currently support PATCH requests. See https://github.com/webmachine/webmachine-ruby/issues/109 for more information and https://github.com/bethesque/pact_broker/blob/2918814e70bbda14df68598a6a41502a5eac4308/lib/pact_broker/api/resources/pacticipant.rb for a dirty hack to make it work if you need to.
+
+# DELETE
+* Override `resource_exists?` and `delete_resource`
+* `delete_resource` must return true
+* See callbacks.rb for documentation on asynchronous deletes.
+
+```ruby
+class OrderResource < Webmachine::Resource
+
+  def allowed_methods
+    ["DELETE"]
+  end
+
+  def resource_exists?
+    order
+  end
+
+  def delete_resource
+    order.destroy
+    true
+  end
+
+  private
+
+  def order
+    @order ||= Order.find(id)
+  end
+
+  def id
+    request.path_info[:id]
+  end
+
+end
+```
+
+Thanks to [oestrich][oestrich] for putting together the original example. You can see the full source code [here][source].
+
+[oestrich]: https://github.com/oestrich
+[source]: https://gist.github.com/oestrich/3638605
+
+<a name="callback-order"></a>
+## What order are the callbacks invoked in?
+
+This question is actually irrelevant if you write your code in a "stateless" way using lazy initialization as the examples do above. As much as possible, think about exposing "facts" about your resource, not writing procedural code that needs to be called in a certain order. See [How it works](/documentation/how-it-works.md) for more information on how the Webmachine state machine works.

data/documentation/how-it-works.md

@@ -0,0 +1,76 @@
+### How it works
+
+Unlike frameworks like Grape and Sinatra, which create a response by running a predefined procedure when a request is received, Webmachine creates an HTTP response by determining a series of "facts" about the resource.
+
+Webmachine is implemented as a [Finite State Machine][diagram]. It uses the facts about your resource to determine the flow though the FSM in order to produce a response.
+
+As an example, imagine the following request:
+
+    $ curl  "http://example.org/widgets/1" -H "Accept: application/json" -u jsmith -p secret
+
+The series of "facts" that Webmachine will determine as it moves through the state machine for this request include:
+
+  * Does the route /widgets/:id exist?
+  * Does a widget with ID 1 exist?
+  * Is jsmith with the given password allowed to execute this HTTP method on this widget?
+  * Can the GET method be called for a widget?
+  * Can a widget be rendered as application/json?
+
+If the answer to each of these questions is "yes", then Webmachine will ask the final question - please render the response for me. If the answer to any of the questions along the way is "no", then the appropriate HTTP response code will be returned automatically.
+
+## Creating a resource
+
+* The way you tell Webmachine the facts about your resource is to create a class that extends Webmachine::Resource, and override the relevant callbacks. For example, what content types it provides (`content_types_accepted`), what HTTP methods it supports (`allowed_methods`), whether or not it exists (`resource_exists?`), and how the resource should be rendered (`to_json`). See the [examples][examples] page for examples of how to implement support for each HTTP method.
+
+```ruby
+class WidgetResource < Webmachine::Resource
+
+  def allowed_methods
+    ["GET"]
+  end
+
+  def content_types_provided
+    [["application/json", :to_json]]
+  end
+
+  def resource_exists?
+    widget # Truthy or falsey
+  end
+
+  def to_json
+    widget.to_json
+  end
+
+  private
+
+  def widget
+    @widget ||= Widget.find(id)
+  end
+
+  def id
+    request.path_info[:id]
+  end
+
+end
+```
+
+* To see a list of the callbacks that can be overridden, and documentation about how to override each one, check out the [Callbacks][callbacks] class.
+
+* Callbacks that have a name with a question mark should return a truthy or falsey value, or an integer response code.
+
+* 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.
+
+* Once an "end state" has been reached (for example, `resource_exists?` returns falsey to a GET request, or a callback returns an explicit response code), the FSM will stop the decision flow, and return the relevant response code to the client. The implication of this is that callbacks later in the flow (eg. the method to render the resource) can rely upon the fact that the resource's existence has already been proven, that authorisation has already been checked etc. so there is no need for any `if object == nil` type boilerplate.
+
+### Advanced
+
+* Once you've seen how to implement a resource, the best way to get an understanding of how the FSM uses that resource is to check out the [Decision Flow Diagram][diagram] and then see how it is implemented in the [Flow][flow] class.
+
+### Guidelines
+
+* A collection resource (eg. /orders) should be implemented as a separate class to a single object resource (eg. /orders/1), as the routes represent different underlying objects with different "facts". For example, the orders _collection_ resource probably always exists (but may be empty), however the order with ID 1 may or may not exist.
+
+[callbacks]: https://github.com/seancribbs/webmachine-ruby/blob/master/lib/webmachine/resource/callbacks.rb
+[diagram]: https://webmachine.github.io/images/http-headers-status-v3.png
+[flow]: https://github.com/seancribbs/webmachine-ruby/blob/master/lib/webmachine/decision/flow.rb
+[examples]: /documentation/examples.md