webmachine 0.1.0 → 0.2.0

data/pkg/webmachine-0.1.0/lib/webmachine/decision/fsm.rb

@@ -0,0 +1,79 @@
+require 'webmachine/decision/helpers'
+require 'webmachine/decision/fsm'
+require 'webmachine/translation'
+
+module Webmachine
+  module Decision
+    # Implements the finite-state machine described by the Webmachine
+    # sequence diagram.
+    class FSM
+      include Flow
+      include Helpers
+      include Translation
+
+      attr_reader :resource, :request, :response, :metadata
+
+      def initialize(resource, request, response)
+        @resource, @request, @response = resource, request, response
+        @metadata = {}
+      end
+
+      # Processes the request, iteratively invoking the decision methods in {Flow}.
+      def run
+        begin
+          state = Flow::START
+          loop do
+            response.trace << state
+            result = send(state)
+            case result
+            when Fixnum # Response code
+              respond(result)
+              break
+            when Symbol # Next state
+              state = result
+            else # You bwoke it
+              raise InvalidResource, t('fsm_broke', :state => state, :result => result.inspect)
+            end
+          end
+        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)
+        end
+      end
+
+      private
+      def respond(code, headers={})
+        response.headers.merge!(headers)
+        end_time = Time.now
+        case code
+        when 404
+          Webmachine.render_error(code, request, response)
+        when 304
+          response.headers.delete('Content-Type')
+          if etag = resource.generate_etag
+            response.headers['ETag'] = ensure_quoted_header(etag)
+          end
+          if expires = resource.expires
+            response.headers['Expires'] = expires.httpdate
+          end
+          if modified = resource.last_modified
+            response.headers['Last-Modified'] = modified.httpdate
+          end
+        end
+        response.code = code
+        resource.finish_request
+        # TODO: add logging/tracing
+      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
+    end
+  end
+end

data/pkg/webmachine-0.1.0/lib/webmachine/decision/helpers.rb

@@ -0,0 +1,80 @@
+require 'webmachine/streaming'
+module Webmachine
+  module Decision
+    # Methods that assist the Decision {Flow}.
+    module Helpers
+      QUOTED = /^"(.*)"$/
+
+      # Determines if the response has a body/entity set.
+      def has_response_body?
+        !response.body.nil? && !response.body.empty?
+      end
+
+      # If the response body exists, encode it.
+      # @see #encode_body
+      def encode_body_if_set
+        encode_body if has_response_body?
+      end
+
+      # Encodes the body in the selected charset and encoding.
+      def encode_body
+        body = response.body
+        chosen_charset = metadata['Charset']
+        chosen_encoding = metadata['Content-Encoding']
+        charsetter = resource.charsets_provided && resource.charsets_provided.find {|c,_| c == chosen_charset }.last || :charset_nop
+        encoder = resource.encodings_provided[chosen_encoding]
+        response.body = case body
+                        when String # 1.8 treats Strings as Enumerable
+                          resource.send(encoder, resource.send(charsetter, body))
+                        when Enumerable
+                          EnumerableEncoder.new(resource, encoder, charsetter, body)
+                        when body.respond_to?(:call)
+                          CallableEncoder.new(resource, encoder, charsetter, body)
+                        else
+                          resource.send(encoder, resource.send(charsetter, body))
+                        end
+      end
+
+      # Ensures that a header is quoted (like ETag)
+      def ensure_quoted_header(value)
+        if value =~ QUOTED
+          value
+        else
+          '"' << value << '"'
+        end
+      end
+
+      # Unquotes request headers (like ETag)
+      def unquote_header(value)
+        if value =~ QUOTED
+          $1
+        else
+          value
+        end
+      end
+
+      # Assists in receiving request bodies
+      def accept_helper
+        content_type = request.content_type || 'application/octet-stream'
+        mt = Conneg::MediaType.parse(content_type)
+        metadata['mediaparams'] = mt.params
+        acceptable = resource.content_types_accepted.find {|ct, _| mt.type_matches?(Conneg::MediaType.parse(ct)) }
+        if acceptable
+          resource.send(acceptable.last)
+        else
+          415
+        end
+      end
+
+      # Computes the entries for the 'Vary' response header
+      def variances
+        resource.variances.tap do |v|
+          v.unshift "Accept-Language" if resource.languages_provided.size > 1
+          v.unshift "Accept-Charset" if resource.charsets_provided && resource.charsets_provided.size > 1
+          v.unshift "Accept-Encoding" if resource.encodings_provided.size > 1
+          v.unshift "Accept" if resource.content_types_provided.size > 1
+        end
+      end
+    end
+  end
+end

data/pkg/webmachine-0.1.0/lib/webmachine/decision.rb

@@ -0,0 +1,12 @@
+require 'webmachine/decision/helpers'
+require 'webmachine/decision/conneg'
+require 'webmachine/decision/flow'
+require 'webmachine/decision/fsm'
+
+module Webmachine
+  # This module encapsulates the logic related to delivering the
+  # proper HTTP response, given the constraints of the {Request} and
+  # the {Resource} which is being processed.
+  module Decision
+  end
+end

data/pkg/webmachine-0.1.0/lib/webmachine/dispatcher/route.rb

@@ -0,0 +1,85 @@
+require 'webmachine/resource'
+require 'webmachine/translation'
+
+module Webmachine
+  module Dispatcher
+    # Pairs URIs with {Resource} classes in the {Dispatcher}. To
+    # create routes, use {Dispatcher#add_route}.
+    class Route
+      # @return [Class] the resource this route will dispatch to, a
+      #   subclass of {Resource}
+      attr_reader :resource
+
+      # When used in a path specification, will match all remaining
+      # segments
+      MATCH_ALL = '*'.freeze
+
+      # Creates a new Route that will associate a pattern to a
+      # {Resource}.
+      # @param [Array<String|Symbol>] path_spec a list of path
+      #   segments (String) and identifiers (Symbol) to bind.
+      #   Strings will be simply matched for equality. Symbols in
+      #   the path spec will be extracted into {Request#path_info} for use
+      #   inside your {Resource}. The special segment {MATCH_ALL} will match
+      #   all remaining segments.
+      # @param [Class] resource the {Resource} to dispatch to
+      # @param [Hash] bindings additional information to add to
+      #   {Request#path_info} when this route matches
+      # @see Dispatcher#add_route
+      def initialize(path_spec, resource, bindings={})
+        @path_spec, @resource, @bindings = path_spec, resource, bindings
+        raise ArgumentError, t('not_resource_class', :class => resource.name) unless resource < Resource
+      end
+
+      # Determines whether the given request matches this route and
+      # should be dispatched to the {#resource}.
+      # @param [Reqeust] request the request object
+      def match?(request)
+        tokens = request.uri.path.match(/^\/(.*)/)[1].split('/')
+        bind(tokens, {})
+      end
+
+      # Decorates the request with information about the dispatch
+      # route, including path bindings.
+      # @param [Request] request the request object
+      def apply(request)
+        request.disp_path = request.uri.path.match(/^\/(.*)/)[1]
+        request.path_info = @bindings.dup
+        tokens = request.disp_path.split('/')
+        depth, trailing = bind(tokens, request.path_info)
+        request.path_tokens = trailing || []
+      end
+
+      private
+      # Attempts to match the path spec against the path tokens, while
+      # accumulating variable bindings.
+      # @param [Array<String>] tokens the list of path segments
+      # @param [Hash] bindings where path bindings will be stored
+      # @return [Fixnum, Array<Fixnum, Array>, false] either the depth
+      #   that the path matched at, the depth and tokens matched by
+      #   {MATCH_ALL}, or false if it didn't match.
+      def bind(tokens, bindings)
+        depth = 0
+        spec = @path_spec
+        loop do
+          case
+          when spec.empty? && tokens.empty?
+            return depth
+          when spec == [MATCH_ALL]
+            return [depth, tokens]
+          when tokens.empty?
+            return false
+          when Symbol === spec.first
+            bindings[spec.first] = tokens.first
+          when spec.first == tokens.first            
+          else
+            return false
+          end
+          spec = spec[1..-1]
+          tokens = tokens[1..-1]
+          depth += 1
+        end
+      end
+    end
+  end
+end

data/pkg/webmachine-0.1.0/lib/webmachine/dispatcher.rb

@@ -0,0 +1,40 @@
+require 'webmachine/decision'
+require 'webmachine/dispatcher/route'
+
+module Webmachine
+  # Handles dispatching incoming requests to the proper registered
+  # resources and initializing the decision logic.
+  module Dispatcher
+    extend self
+    @routes = []
+
+    # Adds a route to the dispatch list. Routes will be matched in the
+    # order they are added.
+    # @see Route#new
+    def add_route(*args)
+      @routes << Route.new(*args)
+    end
+
+    # Dispatches a request to the appropriate {Resource} in the
+    # dispatch list. If a matching resource is not found, a "404 Not
+    # Found" will be rendered.
+    # @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
+        resource = route.resource.new(request, response)
+        route.apply(request)
+        Webmachine::Decision::FSM.new(resource, request, response).run
+      else
+        Webmachine.render_error(404, request, response)
+      end
+    end
+
+    # Resets, removing all routes. Useful for testing or reloading the
+    # application.
+    def reset
+      @routes = []
+    end
+  end
+end

data/pkg/webmachine-0.1.0/lib/webmachine/errors.rb

@@ -0,0 +1,37 @@
+require 'webmachine/translation'
+require 'webmachine/version'
+
+module Webmachine
+  extend Translation
+
+  # Renders a standard error message body for the response. The
+  # standard messages are defined in localization files.
+  # @param [Fixnum] code the response status code
+  # @param [Request] req the request object
+  # @param [Response] req the response object
+  # @param [Hash] options keys to override the defaults when rendering
+  #     the response body
+  def self.render_error(code, req, res, options={})
+    unless res.body
+      title, message = t(["errors.#{code}.title", "errors.#{code}.message"],
+                         { :method => req.method,
+                           :error => res.error}.merge(options))
+      res.body = t("errors.standard_body",
+                   {:title => title,
+                     :message => message,
+                     :version => Webmachine::SERVER_STRING}.merge(options))
+      res.headers['Content-Type'] = "text/html"
+    end
+  end
+
+  # Superclass of all errors generated by Webmachine.
+  class Error < ::StandardError; end
+
+  # Raised when the resource violates specific constraints on its API.
+  class InvalidResource < Error; end
+
+  # Raised when the client has submitted an invalid request, e.g. in
+  # the case where a request header is improperly formed. Raising this
+  # exception will result in a 400 response.
+  class MalformedRequest < Error; end
+end

data/pkg/webmachine-0.1.0/lib/webmachine/headers.rb

@@ -0,0 +1,16 @@
+module Webmachine
+  # Case-insensitive Hash of request headers
+  class Headers < ::Hash
+    def [](key)
+      super key.to_s.downcase
+    end
+
+    def []=(key,value)
+      super key.to_s.downcase, value
+    end
+
+    def grep(pattern)
+      self.class[select { |k,_| pattern === k }]
+    end
+  end
+end

data/pkg/webmachine-0.1.0/lib/webmachine/locale/en.yml

@@ -0,0 +1,28 @@
+en:
+  webmachine:
+    errors:
+      standard_body: "<!DOCTYPE html><html>
+        <head><title>%{title}</title></head>
+        <body><h1>%{title}</h1><p>%{message}</p>
+        <address>%{version} server</address></body></html>"
+      "400":
+        title: 400 Malformed Request
+        message: The request was malformed and could not be processed.
+      "404":
+        title: 404 Not Found
+        message: The requested document was not found on this server.
+      "500":
+        title: 500 Internal Server Error
+        message: "The server encountered an error while processing this request: <pre>%{error}</pre>"
+      "501":
+        title: 501 Not Implemented
+        message: "The server does not support the %{method} method."
+      "503":
+        title: 503 Service Unavailable
+        message: The server is currently unable to handl the request due to a temporary overloading or maintenance of the server.
+    create_path_nil: "post_is_create? returned true but create_path is nil! Define the create_path method in %{class}"
+    do_redirect: "Response had do_redirect but no Location header."
+    fsm_broke: "Decision FSM returned an unexpected value %{result} from decision %{state}."
+    invalid_media_type: "Invalid media type specified in Accept header: %{type}"
+    not_resource_class: "%{class} is not a subclass of Webmachine::Resource"
+    process_post_invalid: "process_post returned %{result}"

data/pkg/webmachine-0.1.0/lib/webmachine/request.rb

@@ -0,0 +1,56 @@
+require 'forwardable'
+
+module Webmachine
+  # This represents a single HTTP request sent from a client.
+  class Request
+    extend Forwardable
+    attr_reader :method, :uri, :headers, :body
+    attr_accessor :disp_path, :path_info, :path_tokens
+
+    def initialize(meth, uri, headers, body)
+      @method, @uri, @headers, @body = meth, uri, headers, body
+    end
+
+    def_delegators :headers, :[]
+
+    # @private
+    def method_missing(m, *args)
+      if m.to_s =~ /^(?:[a-z0-9])+(?:_[a-z0-9]+)*$/i
+        # Access headers more easily as underscored methods.
+        self[m.to_s.tr('_', '-')]
+      else
+        super
+      end
+    end
+
+    # Whether the request body is present.
+    def has_body?
+      !(body.nil? || body.empty?)
+    end
+    
+    # The root URI for the request, ignoring path and query. This is
+    # useful for calculating relative paths to resources.
+    # @return [URI]
+    def base_uri
+      @base_uri ||= uri.dup.tap do |u|
+        u.path = "/"
+        u.query = nil
+      end
+    end
+
+    # Returns a hash of query parameters (they come after the ? in the
+    # URI). Note that this does NOT work in the same way as Rails,
+    # i.e. it does not support nested arrays and hashes.
+    # @return [Hash] query parameters
+    def query
+      unless @query
+        @query = {}
+        uri.query.split(/&/).each do |kv|
+          k, v = URI.unescape(kv).split(/=/)
+          @query[k] = v if k && v
+        end
+      end
+      @query
+    end
+  end
+end