webmachine 0.4.2 → 1.0.0

data/lib/webmachine/decision/conneg.rb

@@ -97,7 +97,7 @@ module Webmachine
       # @api private
       def do_choose(choices, header, default)
         choices = choices.dup.map {|s| s.downcase }
-        accepted = PriorityList.build(header.split(/\s*,\s/))
+        accepted = PriorityList.build(header.split(/\s*,\s*/))
         default_priority = accepted.priority_of(default)
         star_priority = accepted.priority_of("*")
         default_ok = (default_priority.nil? && star_priority != 0.0) || default_priority

data/lib/webmachine/decision/flow.rb

@@ -8,7 +8,7 @@ module Webmachine
     # This module encapsulates all of the decisions in Webmachine's
     # flow-chart. These invoke {Webmachine::Resource::Callbacks} methods to
     # determine the appropriate response code, headers, and body for
-    # the response.    
+    # the response.
     #
     # This module is included into {FSM}, which drives the processing
     # of the chart.

data/lib/webmachine/decision/fsm.rb

@@ -16,13 +16,15 @@ module Webmachine
       def initialize(resource, request, response)
         @resource, @request, @response = resource, request, response
         @metadata = {}
+        initialize_tracing
       end
 
       # Processes the request, iteratively invoking the decision methods in {Flow}.
       def run
         state = Flow::START
+        trace_request(request)
         loop do
-          response.trace << state
+          trace_decision(state)
           result = send(state)
           case result
           when Fixnum # Response code
@@ -37,14 +39,16 @@ module Webmachine
       rescue MalformedRequest => malformed
         Webmachine.render_error(400, request, response, :message => malformed.message)
         respond(400)
-      rescue => e # Handle all exceptions without crashing the server
-        error_response(e, state)
+      rescue Exception => e # Handle all exceptions without crashing the server
+        code = resource.handle_exception(e)
+        code = (100...600).include?(code) ? (code) : (500)
+        respond(code)
       end
 
       private
+
       def respond(code, headers={})
         response.headers.merge!(headers)
-        end_time = Time.now
         case code
         when 404
           Webmachine.render_error(code, request, response)
@@ -54,17 +58,20 @@ module Webmachine
         end
         response.code = code
         resource.finish_request
-        # TODO: add logging/tracing
+        ensure_content_length
+        trace_response(response)
       end
 
-      # Renders a 500 error by capturing the exception information.
-      def error_response(exception, state)
-        response.error = [exception.message, exception.backtrace].flatten.join("\n    ")
-        response.end_state = state
-        Webmachine.render_error(500, request, response)
-        respond(500)
-      end
+      # When tracing is disabled, this does nothing.
+      def trace_decision(state); end
+      # When tracing is disabled, this does nothing.
+      def trace_request(request); end
+      # When tracing is disabled, this does nothing.
+      def trace_response(response); end
 
+      def initialize_tracing
+        extend Trace::FSM if Trace.trace?(resource)
+      end
     end # class FSM
   end # module Decision
 end # module Webmachine

data/lib/webmachine/decision/helpers.rb

@@ -41,7 +41,7 @@ module Webmachine
                           end
                         end
         if String === response.body
-          response.headers['Content-Length'] = response.body.respond_to?(:bytesize) ? response.body.bytesize.to_s : response.body.length.to_s
+          set_content_length
         else
           response.headers.delete 'Content-Length'
           response.headers['Transfer-Encoding'] = 'chunked'
@@ -99,6 +99,30 @@ module Webmachine
           response.headers['Last-Modified'] = modified.httpdate
         end
       end
+
+      # Ensures that responses have an appropriate Content-Length
+      # header
+      def ensure_content_length
+        case
+        when response.headers['Transfer-Encoding']
+          return
+        when [204, 304].include?(response.code)
+          response.headers.delete 'Content-Length'
+        when has_response_body?
+          set_content_length
+        else
+          response.headers['Content-Length'] = '0'
+        end
+      end
+
+      # Sets the Content-Length header on the response
+      def set_content_length
+        if response.body.respond_to?(:bytesize)
+          response.headers['Content-Length'] = response.body.bytesize.to_s
+        else
+          response.headers['Content-Length'] = response.body.length.to_s
+        end
+      end
     end # module Helpers
   end # module Decision
 end # module Webmachine

data/lib/webmachine/dispatcher.rb

@@ -11,9 +11,16 @@ module Webmachine
     # @see #add_route
     attr_reader :routes
 
+    # The creator for resources used to process requests.
+    # Must respond to call(route, request, response) and return
+    # a newly created resource instance.
+    attr_accessor :resource_creator
+
     # Initialize a Dispatcher instance
-    def initialize
+    # @param resource_creator Invoked to create resource instances.
+    def initialize(resource_creator = method(:create_resource))
       @routes = []
+      @resource_creator = resource_creator
     end
 
     # Adds a route to the dispatch list. Routes will be matched in the
@@ -32,10 +39,7 @@ module Webmachine
     # @param [Request] request the request object
     # @param [Response] response the response object
     def dispatch(request, response)
-      route = @routes.find {|r| r.match?(request) }
-      if route
-        route.apply(request)
-        resource = route.resource.new(request, response)
+      if resource = find_resource(request, response)
         Webmachine::Decision::FSM.new(resource, request, response).run
       else
         Webmachine.render_error(404, request, response)
@@ -47,6 +51,31 @@ module Webmachine
     def reset
       @routes.clear
     end
+
+    # Find the first resource that matches an incoming request
+    # @param [Request] request the request to match
+    # @param [Response] response the response for the resource
+    def find_resource(request, response)
+      if route = find_route(request)
+        prepare_resource(route, request, response)
+      end
+    end
+
+    # Find the first route that matches an incoming request
+    # @param [Request] request the request to match
+    def find_route(request)
+      @routes.find {|r| r.match?(request) }
+    end
+
+    private
+    def prepare_resource(route, request, response)
+      route.apply(request)
+      @resource_creator.call(route, request, response)
+    end
+
+    def create_resource(route, request, response)
+      route.resource.new(request, response)
+    end
   end
 
   # Evaluates the passed block in the context of

data/lib/webmachine/dispatcher/route.rb

@@ -6,6 +6,8 @@ module Webmachine
     # Pairs URIs with {Resource} classes in the {Dispatcher}. To
     # create routes, use {Dispatcher#add_route}.
     class Route
+      include Webmachine::Translation
+
       # @return [Class] the resource this route will dispatch to, a
       #   subclass of {Resource}
       attr_reader :resource

data/lib/webmachine/media_type.rb

@@ -62,7 +62,7 @@ module Webmachine
     # Detects whether this {MediaType} matches the other {MediaType},
     # taking into account wildcards. Sub-type parameters are treated
     # strictly.
-    # @param [MediaType, String, Array<String,Hash>] other the other type 
+    # @param [MediaType, String, Array<String,Hash>] other the other type
     # @return [true,false] whether it is an acceptable match
     def exact_match?(other)
       other = self.class.parse(other)
@@ -73,7 +73,7 @@ module Webmachine
     # other {MediaType}, taking into account wildcards and satisfying
     # all requested parameters, but allowing this type to have extra
     # specificity.
-    # @param [MediaType, String, Array<String,Hash>] other the other type 
+    # @param [MediaType, String, Array<String,Hash>] other the other type
     # @return [true,false] whether it is an acceptable match
     def match?(other)
       other = self.class.parse(other)
@@ -88,7 +88,7 @@ module Webmachine
     def params_match?(other)
       other.all? {|k,v| params[k] == v }
     end
-    
+
     # Reconstitutes the type into a String
     # @return [String] the type as a String
     def to_s

data/lib/webmachine/request.rb

@@ -68,6 +68,17 @@ module Webmachine
       @query
     end
 
+    # The cookies sent in the request.
+    #
+    # @return [Hash]
+    #   {} if no Cookies header set
+    def cookies
+      unless @cookies
+        @cookies = Webmachine::Cookie.parse(headers['Cookie'])
+      end
+      @cookies
+    end
+
     # Is this an HTTPS request?
     #
     # @return [Boolean]

data/lib/webmachine/resource.rb

@@ -1,6 +1,7 @@
 require 'webmachine/resource/callbacks'
 require 'webmachine/resource/encodings'
 require 'webmachine/resource/authentication'
+require 'webmachine/resource/tracing'
 
 module Webmachine
   # Resource is the primary building block of Webmachine applications,
@@ -21,6 +22,7 @@ module Webmachine
   class Resource
     include Callbacks
     include Encodings
+    include Tracing
 
     attr_reader :request, :response
 
@@ -38,7 +40,7 @@ module Webmachine
       instance.send :initialize
       instance
     end
-    
+
     private
     # When no specific charsets are provided, this acts as an identity
     # on the response body. Probably deserves some refactoring.

data/lib/webmachine/resource/authentication.rb

@@ -11,7 +11,7 @@ module Webmachine
       # A simple implementation of HTTP Basic auth. Call this from the
       # {Webmachine::Resource::Callbacks#is_authorized?} callback,
       # giving it a block which will be yielded the username and
-      # password and return true or false.      
+      # password and return true or false.
       # @param [String] header the value of the Authentication request
       #   header, passed to the {Callbacks#is_authorized?} callback.
       # @param [String] realm the "realm", or description of the

data/lib/webmachine/resource/callbacks.rb

@@ -360,6 +360,22 @@ module Webmachine
       # @api callback
       def finish_request; end
 
+      #
+      # This method is called when an exception is raised within a subclass of
+      # {Webmachine::Resource}.
+      #
+      # @param [Exception] e
+      #   The exception.
+      #
+      # @return [void]
+      #
+      # @api callback
+      #
+      def handle_exception(e)
+        response.error = [e.message, e.backtrace].flatten.join("\n    ")
+        Webmachine.render_error(500, request, response)
+      end
+
       # This method is called when verifying the Content-MD5 header
       # against the request body. To do your own validation, implement
       # it in this callback, returning true or false. To bypass header

data/lib/webmachine/resource/tracing.rb

@@ -0,0 +1,20 @@
+module Webmachine
+  class Resource
+    # Contains {Resource} methods related to the visual debugger.
+    module Tracing
+      # Whether this resource should be traced. By default, tracing is
+      # disabled, but you can override it by setting the @trace
+      # instance variable in the initialize method, or by overriding
+      # this method. When enabled, traces can be visualized using the
+      # web debugging interface.
+      # @example
+      #   def initialize
+      #     @trace = true
+      #   end
+      # @api callback
+      def trace?
+        !!@trace
+      end
+    end
+  end
+end

data/lib/webmachine/response.rb

@@ -1,7 +1,7 @@
 module Webmachine
   # Represents an HTTP response from Webmachine.
   class Response
-    # @return [Hash] Response headers that will be sent to the client
+    # @return [HeaderHash] Response headers that will be sent to the client
     attr_reader :headers
 
     # @return [Fixnum] The HTTP status code of the response
@@ -15,21 +15,17 @@ module Webmachine
 
     # @return [Array] the list of states that were traversed
     attr_reader :trace
-    
-    # @return [Symbol] When an error has occurred, the last state the
-    #   FSM was in
-    attr_accessor :end_state
 
     # @return [String] The error message when responding with an error
     #   code
     attr_accessor :error
-    
+
     # Creates a new Response object with the appropriate defaults.
     def initialize
-      @headers = {}
+      @headers = HeaderHash.new
       @trace = []
       self.code = 200
-      self.redirect = false      
+      self.redirect = false
     end
 
     # Indicate that the response should be a redirect. This is only
@@ -44,8 +40,42 @@ module Webmachine
       self.redirect = true
     end
 
+    # Set a cookie for the response.
+    # @param [String, Symbol] name the name of the cookie
+    # @param [String] value the value of the cookie
+    # @param [Hash] attributes for the cookie. See RFC2109.
+    def set_cookie(name, value, attributes = {})
+      cookie = Webmachine::Cookie.new(name, value).to_s
+      case headers['Set-Cookie']
+      when nil
+        headers['Set-Cookie'] = cookie
+      when String
+        headers['Set-Cookie'] = [headers['Set-Cookie'], cookie]
+      when Array
+        headers['Set-Cookie'] = headers['Set-Cookie'] + cookie
+      end
+    end
+
     alias :is_redirect? :redirect
     alias :redirect_to :do_redirect
 
+    # A {Hash} that can flatten array values into single values with a separator
+    class HeaderHash < ::Hash
+      # Return a new array with any {Array} values combined with the separator
+      # @param [String] The separator used to join Array values
+      # @return [HeaderHash] A new {HeaderHash} with Array values flattened
+      def flattened(separator = ',')
+        Hash[self.collect { |k,v|
+          case v
+          when Array
+            [k,v.join(separator)]
+          else
+            [k,v]
+          end
+        }]
+
+      end
+    end
+
   end # class Response
 end # module Webmachine

data/lib/webmachine/trace.rb

@@ -0,0 +1,74 @@
+require 'webmachine/trace/resource_proxy'
+require 'webmachine/trace/fsm'
+require 'webmachine/trace/pstore_trace_store'
+require 'webmachine/trace/trace_resource'
+
+module Webmachine
+  # Contains means to enable the Webmachine visual debugger.
+  module Trace
+    module_function
+    # Classes that implement storage for visual debugger traces.
+    TRACE_STORES = {
+      :memory => Hash,
+      :pstore => PStoreTraceStore
+    }
+
+    # Determines whether this resource instance should be traced.
+    # @param [Webmachine::Resource] resource a resource instance
+    # @return [true, false] whether to trace the resource
+    def trace?(resource)
+      # For now this defers to the resource to enable tracing in the
+      # initialize method. At a later time, we can add tracing at the
+      # Application level, perhaps.
+      resource.trace?
+    end
+
+    # Records a trace from a processed request. This is automatically
+    # called by {Webmachine::Trace::ResourceProxy} when finishing the
+    # request.
+    # @api private
+    # @param [String] key a unique identifier for the request
+    # @param [Array] trace the raw trace generated by processing the
+    #   request
+    def record(key, trace)
+      trace_store[key] = trace
+    end
+
+    # Retrieves keys of traces that have been recorded. This is used
+    # to present a list of available traces in the visual debugger.
+    # @api private
+    # @return [Array<String>] a list of recorded traces
+    def traces
+      trace_store.keys
+    end
+
+    # Fetches a given trace from the trace store. This is used to
+    # send specific trace information to the visual debugger.
+    # @api private
+    # @param [String] key the trace's key
+    # @return [Array] the raw trace
+    def fetch(key)
+      trace_store.fetch(key)
+    end
+
+    # Sets the trace storage method. The first parameter should be a
+    # Symbol, followed by any additional options for the
+    # store. Defaults to :memory, which is an in-memory Hash.
+    # @example
+    #   Webmachine::Trace.trace_store = :pstore, "/tmp/webmachine.trace"
+    def trace_store=(*args)
+      @trace_store = nil
+      @trace_store_opts = args
+    end
+    self.trace_store = :memory
+
+    def trace_store
+      @trace_store ||= begin
+                         opts = Array(@trace_store_opts).dup
+                         type = opts.shift
+                         TRACE_STORES[type].new(*opts)
+                       end
+    end
+    private :trace_store
+  end
+end