webmachine 1.2.2 → 1.6.0

data/documentation/routes.md

@@ -0,0 +1,112 @@
+# Routes
+
+## Paths
+
+```ruby
+App = Webmachine::Application.new do |app|
+  app.routes do
+    # Will map to /orders
+    add ["orders"], OrdersResource
+
+    # Will map to /orders/:id
+    # request.path_info[:id] will contain the matched token value
+    add ["orders", :id], OrderResource
+
+    # Will map to /person/:person_id/orders/:order_id and
+    # provide :person_id and :order_id in request.path_info
+    add ["person", :person_id, "orders", :order_id], OrderResource
+
+    # Will map to any path starting with /orders,
+    # but will not provide any path_info
+    add ["orders", :*], OrderResource
+
+    # Will map to any path that matches the given components and regular expression
+    # Any capture groups specified in the regex will be made available in
+    # request.path_info[:captures. In this case, you would get one or two
+    # values in :captures depending on whether your request looked like:
+    # /orders/1/cancel
+    # or
+    # /orders/1/cancel.json
+    add ["orders", :id, /([^.]*)\.?(.*)?/], OrderResource
+
+    # You can even use named captures with regular expressions. This will 
+    # automatically put the captures into path_info. In the below example,
+    # you would get :id from the symbol, along with :action and :format
+    # from the regex. :format in this case would be optional.
+    add ["orders", :id, /(?<action>)[^.]*)\.?(?<format>.*)?/], OrderResource
+
+    # will map to any path
+    add [:*], DefaultResource
+  end
+end
+```
+
+## Guards
+
+Guards prevent a request being sent to a Resource with a matching route unless its conditions are met.
+
+##### Lambda
+
+```ruby
+App = Webmachine::Application.new do |app|
+  app.routes do
+    add ["orders"], lambda { |request| request.headers['X-My-App-Version'] == "1" }, OrdersResourceV1
+    add ["orders"], lambda { |request| request.headers['X-My-App-Version'] == "2" }, OrdersResourceV2
+  end
+end
+
+```
+
+##### Block
+
+```ruby
+App = Webmachine::Application.new do |app|
+  app.routes do
+    add ["orders"], OrdersResourceV1 do | request |
+      request.headers['X-My-App-Version'] == "1"
+    end
+  end
+end
+
+```
+
+##### Callable class
+
+```ruby
+class VersionGuard
+
+  def initialize version
+    @version = version
+  end
+
+  def call(request)
+    request.headers['X-My-App-Version'] == @version
+  end
+
+end
+
+App = Webmachine::Application.new do |app|
+  app.routes do
+    add ["orders"], VersionGuard.new("1"), OrdersResourceV1
+    add ["orders"], VersionGuard.new("2"), OrdersResourceV2
+  end
+end
+
+```
+
+## User defined bindings
+
+User defined bindings specified for a route will be made available through `request.path_info`.
+
+```ruby
+
+App = Webmachine::Application.new do |app|
+  app.routes do
+    add ["orders"], OrdersResource, :foo => "bar"
+  end
+end
+
+request.path_info[:foo]
+=> "bar"
+
+```

data/documentation/validation.md

@@ -0,0 +1,159 @@
+# Validation
+
+There are a couple of callbacks that are the most appropriate for doing validation in. The first is the `malformed_request?` which runs early in the Finite State Machine, and the second is inside the content type handler, for example `from_json`.
+
+## malformed_request
+
+If `malformed_request?` returns a truthy value, then a 400 Bad Request will be returned. Unfortunately, at this early stage in the flow, we don't know what the `method` or the `Content-Type` are without inspecting the request, and this leads to some very Iffy code.
+
+```ruby
+class OrdersResource < Webmachine::Resource
+
+  def allowed_methods
+    ["POST", "GET"]
+  end
+
+  # Iffy! What method? GET doesn't require any validation.
+  def malformed_request?
+    if request.post?
+      # What Content-Type? Very Iffy!
+      if request.headers['Content-Type'] == "application/json"
+        ....
+      end
+    else
+      false
+    end
+  end
+
+  def content_types_accepted
+    [
+      ["application/json", :from_json],
+      ["application/xml", :from_xml]
+    ]
+  end
+
+  def content_types_provided
+    [
+      ["application/json", :to_json],
+      ["application/xml", :to_xml]
+    ]
+  end
+
+  def post_is_create?
+    true
+  end
+
+  def create_path
+    "/orders/#{next_id}"
+  end
+
+  def from_json
+    order = Order.from_json(request.body.to_s)
+    response.body = order.save(next_id).to_json
+  end
+
+  def from_xml
+    order = Order.from_xml(request.body.to_s)
+    response.body = order.save(next_id).to_xml
+  end
+
+  def to_json
+    Order.all.to_json
+  end
+
+  def to_xml
+    Order.all.to_xml
+  end
+
+  private
+
+  def next_id
+    @next_id ||= Order.next_id
+  end
+
+end
+```
+
+## Content-Type handler
+
+A more elegant way to handle validation is to do it in a callback where we already know the `method` and the `Content-Type` - that is, the handler for the given Content-Type (eg. `from_json` and `from_xml`). By returning a `400` from the handler, we stop the state machine flow.
+
+```ruby
+class OrdersResource < Webmachine::Resource
+
+  def allowed_methods
+    ["POST", "GET"]
+  end
+
+  # Iffy! What method? GET doesn't require any validation.
+  def malformed_request?
+    if request.post?
+      invalid_create_order_request?
+    else
+      false
+    end
+  end
+
+  def content_types_accepted
+    [
+      ["application/json", :from_json],
+      ["application/xml", :from_xml]
+    ]
+  end
+
+  def content_types_provided
+    [
+      ["application/json", :to_json],
+      ["application/xml", :to_xml]
+    ]
+  end
+
+  def post_is_create?
+    true
+  end
+
+  def create_path
+    "/orders/#{next_id}"
+  end
+
+  def from_json
+    order = Order.from_json(request.body.to_s)
+    # A bit less Iffy!
+    return json_validation_errors(order) unless order.valid?
+    response.body = order.save(next_id).to_json
+  end
+
+  # This could use some DRYing up, but you get the point.
+  def from_xml
+    order = Order.from_xml(request.body.to_s)
+    # A bit less Iffy!
+    return xml_validation_errors(order) unless order.valid?
+    response.body = order.save(next_id).to_xml
+  end
+
+  def to_json
+    Order.all.to_json
+  end
+
+  def to_xml
+    Order.all.to_xml
+  end
+
+  private
+
+  def json_validation_errors(order)
+    response.body = order.validation_errors.to_json
+    400
+  end
+
+  def xml_validation_errors(order)
+    response.body = order.validation_errors.to_xml
+    400
+  end
+
+  def next_id
+    @next_id ||= Order.next_id
+  end
+
+end
+```

data/documentation/versioning-apis.md

@@ -0,0 +1,74 @@
+# Versioning APIs
+
+## By URL
+
+```ruby
+
+class MyResourceV1 < Webmachine::Resource
+
+end
+
+class MyResourceV2 < Webmachine::Resource
+
+end
+
+App = Webmachine::Application.new do |app|
+  app.routes do
+    add ["api", "v1", "myresource"], MyResourceV1
+    add ["api", "v2", "myresource"], MyResourceV2
+  end
+end
+
+```
+
+## By Content-Type
+
+Note: if no Accept header is specified, then the first content type in the list will be chosen.
+
+```ruby
+
+class MyResource < Webmachine::Resource
+
+  def content_types_provided
+    [
+      ["application/myapp.v2+json", :to_json_v2],
+      ["application/myapp.v1+json", :to_json_v1]
+    ]
+  end
+
+end
+
+```
+
+## By Header value
+
+```ruby
+
+class MyResourceV1 < Webmachine::Resource
+
+end
+
+class MyResourceV2 < Webmachine::Resource
+
+end
+
+class VersionGuard
+
+  def initialize version
+    @version = version
+  end
+
+  def call(request)
+    request.headers['X-My-App-Version'] == @version
+  end
+
+end
+
+App = Webmachine::Application.new do |app|
+  app.routes do
+    add ["api", "myresource"], VersionGuard.new("1"), MyResourceV1
+    add ["api", "myresource"], VersionGuard.new("2"), MyResourceV2
+  end
+end
+
+```

data/documentation/visual-debugger.md

@@ -0,0 +1,38 @@
+### 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:
+
+```ruby
+class MyTracedResource < Webmachine::Resource
+  def trace?
+    true
+  end
+
+  # The rest of your callbacks...
+end
+```
+
+Then enable the visual debugger resource by adding a route to your
+configuration:
+
+```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
+```
+
+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)
+
+Refer to
+[examples/debugger.rb](/examples/debugger.rb)
+for an example of how to enable the debugger.

data/examples/application.rb

@@ -25,10 +25,10 @@ MyApp = Webmachine::Application.new do |app|
     config.adapter = :WEBrick
   end
   # And add routes like this:
-  app.add_route ['fizz', :buzz, '*'], RouteDebugResource
+  app.add_route ['fizz', :buzz, :*], RouteDebugResource
   # OR add routes this way:
   app.routes do
-    add [:test, :foo, '*'], RouteDebugResource
+    add [:test, :foo, :*], RouteDebugResource
   end
 end
 

data/examples/debugger.rb

@@ -31,7 +31,7 @@ end
 
 TraceExample = Webmachine::Application.new do |app|
   app.routes do
-    add ['trace', '*'], Webmachine::Trace::TraceResource
+    add ['trace', :*], Webmachine::Trace::TraceResource
     add [], MyTracedResource
   end
 end

data/lib/webmachine.rb

@@ -1,10 +1,12 @@
-require 'webmachine/configuration'
+require 'webmachine/configuration'
+require 'webmachine/constants'
 require 'webmachine/cookie'
 require 'webmachine/headers'
 require 'webmachine/request'
 require 'webmachine/response'
 require 'webmachine/etags'
 require 'webmachine/errors'
+require 'webmachine/header_negotiation'
 require 'webmachine/decision'
 require 'webmachine/streaming'
 require 'webmachine/adapter'

data/lib/webmachine/adapter.rb

@@ -5,23 +5,17 @@ module Webmachine
   # @abstract Subclass and override {#run} to implement a custom adapter.
   class Adapter
 
-    # @return [Webmachine::Configuration] the application's configuration.
-    attr_reader :configuration
+    # @return [Webmachine::Application] returns the application
+    attr_reader :application
 
-    # @return [Webmachine::Dispatcher] the application's dispatcher.
-    attr_reader :dispatcher
-
-    # @param [Webmachine::Configuration] configuration the application's
-    # configuration.
-    # @param [Webmachine::Dispatcher] dispatcher the application's dispatcher.
-    def initialize(configuration, dispatcher)
-      @configuration = configuration
-      @dispatcher    = dispatcher
+    # @param [Webmachine::Application] application the application
+    def initialize(application)
+      @application = application
     end
 
     # Create a new adapter and run it.
-    def self.run(configuration, dispatcher)
-      new(configuration, dispatcher).run
+    def self.run(application)
+      new(application).run
     end
 
     # Start the adapter.