webmachine 0.1.0

data/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/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/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/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/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/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

data/lib/webmachine/resource/callbacks.rb

@@ -0,0 +1,362 @@
+module Webmachine
+  class Resource
+    # These
+    module Callbacks
+      # Does the resource exist? Returning a falsey value (false or nil)
+      # will result in a '404 Not Found' response. Defaults to true.
+      # @return [true,false] Whether the resource exists
+      # @api callback
+      def resource_exists?
+        true
+      end
+
+      # Is the resource available? Returning a falsey value (false or
+      # nil) will result in a '503 Service Not Available'
+      # response. Defaults to true.  If the resource is only temporarily
+      # not available, add a 'Retry-After' response header in the body
+      # of the method.
+      # @return [true,false]
+      # @api callback
+      def service_available?
+        true
+      end
+
+      # Is the client or request authorized? Returning anything other than true
+      # will result in a '401 Unauthorized' response.  Defaults to
+      # true. If a String is returned, it will be used as the value in
+      # the WWW-Authenticate header, which can also be set manually.
+      # @param [String] authorization_header The contents of the
+      #     'Authorization' header sent by the client, if present.
+      # @return [true,false,String] Whether the client is authorized,
+      #     and if not, the WWW-Authenticate header when a String.
+      # @api callback
+      def is_authorized?(authorization_header = nil)
+        true
+      end
+
+      # Is the request or client forbidden? Returning a truthy value
+      # (true or non-nil) will result in a '403 Forbidden' response.
+      # Defaults to false.
+      # @return [true,false] Whether the client or request is forbidden.
+      # @api callback
+      def forbidden?
+        false
+      end
+
+      # If the resource accepts POST requests to nonexistent resources,
+      # then this should return true. Defaults to false.
+      # @return [true,false] Whether to accept POST requests to missing
+      #     resources.
+      # @api callback
+      def allow_missing_post?
+        false
+      end
+
+      # If the request is malformed, this should return true, which will
+      # result in a '400 Malformed Request' response. Defaults to false.
+      # @return [true,false] Whether the request is malformed.
+      # @api callback
+      def malformed_request?
+        false
+      end
+
+      # If the URI is too long to be processed, this should return true,
+      # which will result in a '414 Request URI Too Long'
+      # response. Defaults to false.
+      # @param [URI] uri the request URI
+      # @return [true,false] Whether the request URI is too long.
+      # @api callback
+      def uri_too_long?(uri = nil)
+        false
+      end
+
+      # If the Content-Type on PUT or POST is unknown, this should
+      # return false, which will result in a '415 Unsupported Media
+      # Type' response. Defaults to true.
+      # @param [String] content_type the 'Content-Type' header sent by
+      #     the client
+      # @return [true,false] Whether the passed media type is known or
+      #     accepted
+      # @api callback
+      def known_content_type?(content_type = nil)
+        true
+      end
+
+      # If the request includes any invalid Content-* headers, this
+      # should return false, which will result in a '501 Not
+      # Implemented' response. Defaults to false.
+      # @param [Hash] content_headers Request headers that begin with
+      #     'Content-'
+      # @return [true,false] Whether the Content-* headers are invalid
+      #     or unsupported
+      # @api callback
+      def valid_content_headers?(content_headers = nil)
+        true
+      end
+
+      # If the entity length on PUT or POST is invalid, this should
+      # return false, which will result in a '413 Request Entity Too
+      # Large' response. Defaults to true.
+      # @param [Fixnum] length the size of the request body (entity)
+      # @return [true,false] Whether the body is a valid length (not too
+      #    large)
+      # @api callback
+      def valid_entity_length?(length = nil)
+        true
+      end
+
+      # If the OPTIONS method is supported and is used, this method
+      # should return a Hash of headers that should appear in the
+      # response. Defaults to {}.
+      # @return [Hash] headers to appear in the response
+      # @api callback
+      def options
+        {}
+      end
+
+      # HTTP methods that are allowed on this resource. This must return
+      # an Array of Strings in all capitals. Defaults to ['GET','HEAD'].
+      # @return [Array<String>] allowed methods on this resource
+      # @api callback
+      def allowed_methods
+        ['GET', 'HEAD']
+      end
+
+      # HTTP methods that are known to the resource. Like
+      # {#allowed_methods}, this must return an Array of Strings in
+      # all capitals. Default includes all standard HTTP methods. One
+      # could override this callback to  allow additional methods,
+      # e.g. WebDAV.
+      # @return [Array<String>] known methods
+      # @api callback
+      def known_methods
+        ['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'TRACE', 'CONNECT', 'OPTIONS']
+      end
+
+      # This method is called when a DELETE request should be enacted,
+      # and should return true if the deletion succeeded. Defaults to false.
+      # @return [true,false] Whether the deletion succeeded.
+      # @api callback
+      def delete_resource
+        false
+      end
+
+      # This method is called after a successful call to
+      # {#delete_resource} and should return false if the deletion was
+      # accepted but cannot yet be guaranteed to have finished. Defaults
+      # to true.
+      # @return [true,false] Whether the deletion completed
+      # @api callback
+      def delete_completed?
+        true
+      end
+
+      # If POST requests should be treated as a request to put content
+      # into a (potentially new) resource as opposed to a generic
+      # submission for processing, then this method should return
+      # true. If it does return true, then {#create_path} will be called
+      # and the rest of the request will be treated much like a PUT to
+      # the path returned by that call.  Default is false.
+      # @return [true,false] Whether POST creates a new resource
+      # @api callback
+      def post_is_create?
+        false
+      end
+
+      # This will be called on a POST request if post_is_create? returns
+      # true. The path returned should be a valid URI part following the
+      # dispatcher prefix. That path will replace the previous one in
+      # the return value of {Request#disp_path} for all subsequent
+      # resource function calls in the course of this request.
+      # @return [String, URI] the path to the new resource
+      # @api callback
+      def create_path
+        nil
+      end
+
+      # This will be called after {#create_path} but before setting the
+      # Location response header, and is used to determine the root
+      # URI of the new resource. Default is nil, which uses the URI of
+      # the request as the base.
+      # @return [String, URI, nil]
+      # @api callback
+      def base_uri
+        nil
+      end
+
+      # If post_is_create? returns false, then this will be called to
+      # process any POST request. If it succeeds, it should return true.
+      # @return [true,false,Fixnum] Whether the POST was successfully
+      #    processed, or an alternate response code
+      # @api callback
+      def process_post
+        false
+      end
+
+      # This should return an array of pairs where each pair is of the
+      # form [mediatype, :handler] where mediatype is a String of
+      # Content-Type format and :handler is a Symbol naming the method
+      # which can provide a resource representation in that media
+      # type. For example, if a client request includes an 'Accept'
+      # header with a value that does not appear as a first element in
+      # any of the return pairs, then a '406 Not Acceptable' will be
+      # sent.  Default is [['text/html', :to_html]].
+      # @return an array of mediatype/handler pairs
+      # @api callback
+      def content_types_provided
+        [['text/html', :to_html]]
+      end
+
+      # Similarly to content_types_provided, this should return an array
+      # of mediatype/handler pairs, except that it is for incoming
+      # resource representations -- for example, PUT requests. Handler
+      # functions usually want to use {Request#body} to access the
+      # incoming entity.
+      # @return [Array] an array of mediatype/handler pairs
+      # @api callback
+      def content_types_accepted
+        []
+      end
+
+      # If this is anything other than nil, it must be an array of pairs
+      # where each pair is of the form Charset, Converter where Charset
+      # is a string naming a charset and Converter is an arity-1 method
+      # in the resource which will be called on the produced body in a
+      # GET and ensure that it is in Charset.
+      # @return [nil, Array] The provided character sets and encoder
+      #     methods, or nothing.
+      # @api callback
+      def charsets_provided
+        nil
+      end
+
+      # This should return a list of language tags provided by the
+      # resource. Default is the empty Array, in which the content is
+      # in no specific language.
+      # @return [Array<String>] a list of provided languages      
+      # @api callback
+      def languages_provided        
+        []
+      end
+
+      # This should return a hash of encodings mapped to encoding
+      # methods for Content-Encodings your resource wants to
+      # provide. The encoding will be applied to the response body
+      # automatically by Webmachine. A number of built-in encodings
+      # are provided in the {Encodings} module. Default includes only
+      # the 'identity' encoding.
+      # @return [Hash] a hash of encodings and encoder methods/procs
+      # @api callback
+      # @see Encodings
+      def encodings_provided
+        {"identity" => :encode_identity }
+      end
+
+      # If this method is implemented, it should return a list of
+      # strings with header names that should be included in a given
+      # response's Vary header. The standard conneg headers (Accept,
+      # Accept-Encoding, Accept-Charset, Accept-Language) do not need to
+      # be specified here as Webmachine will add the correct elements of
+      # those automatically depending on resource behavior. Default is
+      # [].
+      # @api callback
+      # @return [Array<String>] a list of variance headers
+      def variances
+        []
+      end
+
+      # If this returns true, the client will receive a '409 Conflict'
+      # response. This is only called for PUT requests. Default is false.
+      # @api callback
+      # @return [true,false] whether the submitted entity is in conflict
+      #     with the current state of the resource
+      def is_conflict?
+        false
+      end
+
+      # If this returns true, then it is assumed that multiple
+      # representations of the response are possible and a single one
+      # cannot be automatically chosen, so a 300 Multiple Choices will
+      # be sent instead of a 200. Default is false.
+      # @api callback
+      # @return [true,false] whether the multiple representations are
+      #     possible
+      def multiple_choices?
+        false
+      end
+
+      # If this resource is known to have existed previously, this
+      # method should return true. Default is false.
+      # @api callback
+      # @return [true,false] whether the resource existed previously
+      def previously_existed?
+        false
+      end
+
+      # If this resource has moved to a new location permanently, this
+      # method should return the new location as a String or
+      # URI. Default is to return false.
+      # @api callback
+      # @return [String,URI,false] the new location of the resource, or
+      #    false
+      def moved_permanently?
+        false
+      end
+
+      # If this resource has moved to a new location temporarily, this
+      # method should return the new location as a String or
+      # URI. Default is to return false.
+      # @api callback
+      # @return [String,URI,false] the new location of the resource, or
+      #    false
+      def moved_temporarily?
+        false
+      end
+
+      # This method should return the last modified date/time of the
+      # resource which will be added as the Last-Modified header in the
+      # response and used in negotiating conditional requests. Default
+      # is nil.
+      # @api callback
+      # @return [Time,DateTime,Date,nil] the last modified time
+      def last_modified
+        nil
+      end
+
+      # If the resource expires, this method should return the date/time
+      # it expires. Default is nil.
+      # @api callback
+      # @return [Time,DateTime,Date,nil] the expiration time
+      def expires
+        nil
+      end
+
+      # If this returns a value, it will be used as the value of the
+      # ETag header and for comparison in conditional requests. Default
+      # is nil.
+      # @api callback
+      # @return [String,nil] the entity tag for this resource
+      def generate_etag
+        nil
+      end
+
+      # This method is called just before the final response is
+      # constructed and sent. The return value is ignored, so any effect
+      # of this method must be by modifying the response.
+      # @api callback
+      def finish_request; 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
+      # validation, simply return true.  Default is nil, which will
+      # invoke Webmachine's default validation.
+      # @api callback
+      # @return [true,false,nil] Whether the Content-MD5 header
+      #     validates against the request body
+      def validate_content_checksum
+        nil
+      end
+    end
+  end
+end

data/lib/webmachine/resource/encodings.rb

@@ -0,0 +1,36 @@
+require 'zlib'
+require 'stringio'
+
+module Webmachine
+  class Resource
+    # This module implements standard Content-Encodings that you might
+    # want to use in your {Resource}.  To use one, simply return it in
+    # the hash from {Callbacks#encodings_provided}.
+    module Encodings
+      # The 'identity' encoding, which does no compression.
+      def encode_identity(data)
+        data
+      end
+
+      # The 'deflate' encoding, which uses libz's DEFLATE compression.
+      def encode_deflate(data)
+        # The deflate options were borrowed from Rack and Mongrel1.
+        Zlib::Deflate.deflate(data, *[Zlib::DEFAULT_COMPRESSION,
+                                      # drop the zlib header which causes both Safari and IE to choke
+                                      -Zlib::MAX_WBITS,
+                                      Zlib::DEF_MEM_LEVEL,
+                                      Zlib::DEFAULT_STRATEGY
+                                     ])
+      end
+
+      # The 'gzip' encoding, which uses GNU Zip (via libz).
+      # @note Because of the header/checksum requirements, gzip cannot
+      #     be used on streamed responses.
+      def encode_gzip(data)
+        "".tap do |out|
+          Zlib::GzipWriter.wrap(StringIO.new(out)){|gz| gz << data }
+        end
+      end
+    end
+  end
+end