webmachine 1.2.2 → 1.3.0

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.

data/lib/webmachine/adapters.rb

@@ -5,8 +5,7 @@ module Webmachine
   # Contains classes and modules that connect Webmachine to Ruby
   # application servers.
   module Adapters
-    autoload :Mongrel,  'webmachine/adapters/mongrel'
     autoload :Reel,     'webmachine/adapters/reel'
-    autoload :Hatetepe, 'webmachine/adapters/hatetepe'
+    autoload :HTTPkit,  'webmachine/adapters/httpkit'
   end
 end

data/lib/webmachine/adapters/httpkit.rb

@@ -0,0 +1,74 @@
+require 'webmachine/adapter'
+require 'webmachine/constants'
+require 'webmachine/version'
+require 'httpkit'
+require 'webmachine/version'
+require 'webmachine/response'
+require 'webmachine/request'
+require 'webmachine/headers'
+
+module Webmachine
+  module Adapters
+    class HTTPkit < Adapter
+      VERSION_STRING = "#{Webmachine::SERVER_STRING} HTTPkit/#{::HTTPkit::VERSION}".freeze
+
+      def options
+        @options ||= {
+          :address => application.configuration.ip,
+          :port => application.configuration.port,
+          :handlers => [
+            ::HTTPkit::Server::TimeoutsHandler.new,
+            ::HTTPkit::Server::KeepAliveHandler.new,
+            self
+          ]
+        }
+      end
+
+      def run
+        ::HTTPkit.start do
+          ::HTTPkit::Server.start(options)
+        end
+      end
+
+      # Called by HTTPkit::Server for every request
+      def serve(request, served)
+        response = Webmachine::Response.new
+        application.dispatcher.dispatch(convert_request(request), response)
+
+        served.fulfill(convert_response(response))
+      end
+
+      private
+
+      # Converts HTTPkit::Request to Webmachine::Request
+      def convert_request(request)
+        Webmachine::Request.new(
+          request.http_method.to_s.upcase,
+          request.uri,
+          Webmachine::Headers[request.headers.dup],
+          request.body)
+      end
+
+      # Converts Webmachine::Response to HTTPkit::Response
+      def convert_response(response)
+        response.headers[SERVER] = VERSION_STRING
+
+
+        ::HTTPkit::Response.new(
+          response.code.to_i,
+          response.headers,
+          convert_body(response.body))
+      end
+
+      # HTTPkit::Body accepts strings and enumerables, i.e. Webmachine's
+      # Callable, Enumerable, IO, and Fiber encoders are supported.
+      def convert_body(body)
+        if body.respond_to?(:call)
+          [body.call]
+        else
+          body || ''
+        end
+      end
+    end
+  end
+end

data/lib/webmachine/adapters/lazy_request_body.rb

@@ -1,5 +1,4 @@
-
-module Webmachine
+module Webmachine
   module Adapters
     # Wraps a request body so that it can be passed to
     # {Request} while still lazily evaluating the body.

data/lib/webmachine/adapters/rack.rb

@@ -1,17 +1,20 @@
+require 'webmachine/adapter'
 require 'rack'
-require 'webmachine/version'
+require 'webmachine/constants'
 require 'webmachine/headers'
 require 'webmachine/request'
 require 'webmachine/response'
-require 'webmachine/dispatcher'
+require 'webmachine/version'
 require 'webmachine/chunked_body'
 
 module Webmachine
   module Adapters
     # A minimal "shim" adapter to allow Webmachine to interface with Rack. The
     # intention here is to allow Webmachine to run under Rack-compatible
-    # web-servers, like unicorn and pow, and is not intended to allow Webmachine
-    # to be "plugged in" to an existing Rack app as middleware.
+    # web-servers, like unicorn and pow.
+    # The adapter expects your Webmachine application to be mounted at the root path -
+    # it will NOT allow you to nest your Webmachine application at an arbitrary path
+    # eg. map "/api" { run MyWebmachineAPI }
     #
     # To use this adapter, create a config.ru file and populate it like so:
     #
@@ -26,7 +29,7 @@ module Webmachine
     # all "just work".
     #
     # And for development or testing your application can be run with Rack's
-    # builtin Server identically to the Mongrel and WEBrick adapters with:
+    # builtin Server identically to the WEBrick adapter with:
     #
     #     MyApplication.run
     #
@@ -34,22 +37,22 @@ module Webmachine
       # Used to override default Rack server options (useful in testing)
       DEFAULT_OPTIONS = {}
 
+      REQUEST_URI = 'REQUEST_URI'.freeze
+      VERSION_STRING = "#{Webmachine::SERVER_STRING} Rack/#{::Rack.version}".freeze
+      NEWLINE = "\n".freeze
+
       # Start the Rack adapter
       def run
         options = DEFAULT_OPTIONS.merge({
           :app => self,
-          :Port => configuration.port,
-          :Host => configuration.ip
-        }).merge(configuration.adapter_options)
+          :Port => application.configuration.port,
+          :Host => application.configuration.ip
+        }).merge(application.configuration.adapter_options)
 
         @server = ::Rack::Server.new(options)
         @server.start
       end
 
-      def shutdown
-        @server.server.shutdown if @server
-      end
-
       # Handles a Rack-based request.
       # @param [Hash] env the Rack environment
       def call(env)
@@ -57,26 +60,28 @@ module Webmachine
 
         rack_req = ::Rack::Request.new env
         request = Webmachine::Request.new(rack_req.request_method,
-                                          URI.parse(rack_req.url),
+                                          env[REQUEST_URI],
                                           headers,
                                           RequestBody.new(rack_req))
 
         response = Webmachine::Response.new
-        @dispatcher.dispatch(request, response)
+        application.dispatcher.dispatch(request, response)
 
-        response.headers['Server'] = [Webmachine::SERVER_STRING, "Rack/#{::Rack.version}"].join(" ")
+        response.headers[SERVER] = VERSION_STRING
 
         rack_status  = response.code
-        rack_headers = response.headers.flattened("\n")
+        rack_headers = response.headers.flattened(NEWLINE)
         rack_body = case response.body
                     when String # Strings are enumerable in ruby 1.8
                       [response.body]
                     else
-                      if response.body.respond_to?(:call)
+                      if (io_body = IO.try_convert(response.body))
+                        io_body
+                      elsif response.body.respond_to?(:call)
                         Webmachine::ChunkedBody.new(Array(response.body.call))
                       elsif response.body.respond_to?(:each)
                         # This might be an IOEncoder with a Content-Length, which shouldn't be chunked.
-                        if response.headers["Transfer-Encoding"] == "chunked"
+                        if response.headers[TRANSFER_ENCODING] == "chunked"
                           Webmachine::ChunkedBody.new(response.body)
                         else
                           response.body
@@ -91,6 +96,8 @@ module Webmachine
       end
 
       class RackResponse
+        ONE_FIVE = '1.5'.freeze
+
         def initialize(body, status, headers)
           @body    = body
           @status  = status
@@ -98,8 +105,8 @@ module Webmachine
         end
 
         def finish
-          @headers['Content-Type'] ||= 'text/html' if rack_release_enforcing_content_type
-          @headers.delete('Content-Type')          if response_without_body
+          @headers[CONTENT_TYPE] ||= TEXT_HTML if rack_release_enforcing_content_type
+          @headers.delete(CONTENT_TYPE)        if response_without_body
           [@status, @headers, @body]
         end
 
@@ -110,7 +117,7 @@ module Webmachine
         end
 
         def rack_release_enforcing_content_type
-          ::Rack.release < '1.5'
+          ::Rack.release < ONE_FIVE
         end
       end
 
@@ -123,6 +130,15 @@ module Webmachine
           @request = request
         end
 
+        # Rack Servers differ in the way you can access their request bodys.
+        # While some allow you to directly get a Ruby IO object others don't.
+        # You have to check the methods they expose, like #gets, #read, #each, #rewind and maybe others.
+        # See: https://github.com/rack/rack/blob/rack-1.5/lib/rack/lint.rb#L296
+        # @return [IO] the request body
+        def to_io
+          @request.body
+        end
+
         # Converts the body to a String so you can work with the entire
         # thing.
         # @return [String] the request body as a string

data/lib/webmachine/adapters/reel.rb

@@ -1,40 +1,41 @@
+require 'webmachine/adapter'
+require 'webmachine/constants'
+require 'set'
 require 'reel'
-require 'webmachine/version'
 require 'webmachine/headers'
 require 'webmachine/request'
 require 'webmachine/response'
-require 'webmachine/dispatcher'
-require 'set'
 
 module Webmachine
   module Adapters
     class Reel < Adapter
       # Used to override default Reel server options (useful in testing)
       DEFAULT_OPTIONS = {}
-      
+
       def run
         @options = DEFAULT_OPTIONS.merge({
-          :port => configuration.port,
-          :host => configuration.ip
-        }).merge(configuration.adapter_options)
+          :port => application.configuration.port,
+          :host => application.configuration.ip
+        }).merge(application.configuration.adapter_options)
 
-        if extra_verbs = configuration.adapter_options[:extra_verbs]
+        if extra_verbs = application.configuration.adapter_options[:extra_verbs]
           @extra_verbs = Set.new(extra_verbs.map(&:to_s).map(&:upcase))
         else
           @extra_verbs = Set.new
         end
 
-        @server = ::Reel::Server.supervise(@options[:host], @options[:port], &method(:process))
+        if @options[:ssl]
+          unless @options[:ssl][:cert] && @options[:ssl][:key]
+            raise ArgumentError, 'Certificate or Private key missing for HTTPS Server'
+          end
+          @server = ::Reel::Server::HTTPS.supervise(@options[:host], @options[:port], @options[:ssl], &method(:process))
+        else
+          @server = ::Reel::Server::HTTP.supervise(@options[:host], @options[:port], &method(:process))
+        end
 
-        # FIXME: this will no longer work on Ruby 2.0. We need Celluloid.trap
-        trap("INT") { @server.terminate; exit 0 }
         Celluloid::Actor.join(@server)
       end
 
-      def shutdown
-        @server.terminate! if @server
-      end
-
       def process(connection)
         connection.each_request do |request|
           # Users of the adapter can configure a custom WebSocket handler
@@ -54,7 +55,7 @@ module Webmachine
           # state machine. Do the "Railsy" thing and handle them like POSTs
           # with a magical parameter
           if @extra_verbs.include?(request.method)
-            method = "POST"
+            method = POST_METHOD
             param  = "_method=#{request.method}"
             uri    = request_uri(request.url, request.headers, param)
           else
@@ -64,8 +65,9 @@ module Webmachine
 
           wm_headers  = Webmachine::Headers[request.headers.dup]
           wm_request  = Webmachine::Request.new(method, uri, wm_headers, request.body)
+
           wm_response = Webmachine::Response.new
-          @dispatcher.dispatch(wm_request, wm_response)
+          application.dispatcher.dispatch(wm_request, wm_response)
 
           fixup_headers(wm_response)
           fixup_callable_encoder(wm_response)
@@ -77,13 +79,9 @@ module Webmachine
       end
 
       def request_uri(path, headers, extra_query_params = nil)
-        host_parts = headers.fetch('Host').split(':')
         path_parts = path.split('?')
-
-        uri_hash = {host: host_parts.first, path: path_parts.first}
-
-        uri_hash[:port]  = host_parts.last.to_i if host_parts.length == 2
-        uri_hash[:query] = path_parts.last      if path_parts.length == 2
+        uri_hash = {path: path_parts.first}
+        uri_hash[:query] = path_parts.last if path_parts.length == 2
 
         if extra_query_params
           if uri_hash[:query]