doze 0.0.11

data/README

@@ -0,0 +1,6 @@
+# Doze
+
+RESTful resource-oriented API framework
+
+# Example application
+

data/lib/doze/application.rb

@@ -0,0 +1,92 @@
+require 'time' # httpdate
+require 'doze/utils'
+require 'doze/error'
+require 'doze/uri_template'
+require 'doze/request'
+require 'doze/router'
+require 'doze/resource'
+require 'doze/entity'
+require 'doze/resource/error'
+require 'doze/resource/proxy'
+require 'doze/request'
+require 'doze/response'
+require 'doze/responder'
+require 'doze/responder/main'
+require 'doze/responder/error'
+require 'doze/responder/resource'
+require 'doze/negotiator'
+
+class Doze::Application
+  include Doze::Utils
+
+  DEFAULT_CONFIG = {
+    :error_resource_class => Doze::Resource::Error,
+
+    # Setting this to false is useful for testing, so an exception can make a test fail via
+    # the normal channels rather than having to check and parse it out of a response.
+    :catch_application_errors => true,
+
+    # useful for development
+    :expose_exception_details => true,
+
+    # Methods not included here will be rejected with 'method not implemented'
+    # before any resource is called. (methods included here may still be rejected
+    # as not supported by individual resources via supports_method).
+    # Note: HEAD is supported as part of GET support, and OPTIONS comes for free.
+    :recognized_methods => [:get, :post, :put, :delete],
+
+    # You might need to change this depending on what rack middleware you use to
+    # authenticate / identify users. Eg could use
+    #   env['rack.session'] for use with Rack::Session (the default)
+    #   env['REMOTE_USER'] for use with Rack::Auth::Basic / Digest, and direct via Apache and some other front-ends that do http auth
+    #   env['rack.auth.openid'] for use with Rack::Auth::OpenID
+    # This is used to look up a session or user object in the rack environment
+    :session_from_rack_env => proc {|env| env['rack.session']},
+
+    # Used to determine whether the user/session object obtained via :session_from_rack_env is to be treated as authenticated or not.
+    # By default this looks for a key :user within a session object.
+    # For eg env['REMOTE_USER'] the session is the authenticated username and you probably just want to test for !session.nil?
+    :session_authenticated => proc {|session| !session[:user].nil?},
+
+    # Doze has a special facility to use a file extension style suffix on the URI.
+    # Instead of passing this file extension through the routing process, it is dropped from the routed URI
+    # and handled specially, effectively overriding the Accept header for that request and forcing a response
+    # with the media type in question.
+    # Relies on media types being registered by extension, see Doze::MediaType.
+    # NB: if you enable this setting, be aware that extensions are stripped prior to routing, so you will
+    # lose the ability to route based on file extensions, and must be careful to escape the extension delimiter (".")
+    # when putting a text fragment for matching at the end of a uri.
+    :media_type_extensions => false
+  }
+
+  attr_reader :config, :root, :logger
+
+  # root may be a Router, a Resource, or both.
+  # If a resource, its uri should return '/'
+  def initialize(root, config={})
+    @config = DEFAULT_CONFIG.merge(config)
+    @logger = @config[:logger] || STDOUT
+    @root = root
+
+    # This is done on application initialization to ensure that statically-known
+    # information about routing paths is propagated as far as possible, so that
+    # resource instances can know their uris without necessarily having been
+    # a part of the routing chain for the current request.
+    # TODO use SCRIPT_NAME from the rack env of the first request we get, rather than ''
+    @root.propagate_static_routes('') if @root.respond_to?(:propagate_static_routes)
+  end
+
+  def call(env)
+    begin
+      request = Doze::Request.new(self, env)
+      responder = Doze::Responder::Main.new(self, request)
+      responder.call
+    rescue => exception
+      raise unless config[:catch_application_errors]
+      lines = ['500 response via error resource failed', "#{exception.class}: #{exception.message}", *exception.backtrace]
+      @logger << lines.join("\n")
+      body = config[:expose_exception_details] ? lines : [lines.first]
+      [STATUS_INTERNAL_SERVER_ERROR, {}, [body.join("\n")]]
+    end
+  end
+end

data/lib/doze/collection/object.rb

@@ -0,0 +1,14 @@
+module Doze::Collection::Object
+
+  include Doze::Serialization::Resource
+
+  def get_data
+  end
+
+  def get_property(property)
+  end
+
+  def put_property(property, data)
+  end
+
+end

data/lib/doze/entity.rb

@@ -0,0 +1,62 @@
+require 'digest/md5'
+
+# A simple wrapper class for an entity, which is essentially a lump of binary data
+# together with some metadata about it, most importantly a MediaType, but also
+# potentially a character encoding and a content language.
+#
+# A key feature is that the binary data may be specified lazily via a block.
+# This is so that content negotiation can demand the data only once it's decided
+# which (if any) of many proferred entities it wants to respond with.
+#
+# TODO: handle character encodings here in a nicer 1.9-compatible way
+# TODO: maybe allow a stream for lazy_binary_data too
+class Doze::Entity
+  DEFAULT_TEXT_ENCODING = 'iso-8859-1'
+
+  attr_reader :media_type, :media_type_params, :encoding, :language, :binary_data_length
+
+  # Used when constructing a HTTP response from this entity
+  # For when you need to specify extra entity-content-specific HTTP headers to be included when
+  # responding with this entity.
+  # A teensy bit of an abstraction leak, but helpful for awkward cases.
+  attr_reader :extra_content_headers
+
+  class << self; alias :new_from_binary_data :new; end
+
+  def initialize(media_type, options={}, &lazy_binary_data)
+    @binary_data = options[:binary_data]
+    @binary_data_stream = options[:binary_data_stream]
+    @binary_data_length = options[:binary_data_length]
+    @lazy_binary_data = options[:lazy_binary_data] || lazy_binary_data
+
+    @media_type = media_type
+    @media_type_params = options[:media_type_params] || {}
+    @encoding   = options[:encoding] || (DEFAULT_TEXT_ENCODING if @media_type.major == 'text')
+    @language   = options[:language]
+    @extra_content_headers = options[:extra_content_headers] || {}
+  end
+
+  def binary_data_stream
+    @binary_data_stream ||= if @binary_data
+      StringIO.new(@binary_data)
+    end
+  end
+
+  def binary_data
+    @binary_data ||= if @lazy_binary_data
+      @lazy_binary_data.call
+    elsif @binary_data_stream
+      @binary_data_stream.rewind if @binary_data_stream.respond_to?(:rewind)
+      @binary_data_stream.read
+    end
+  end
+
+  # This is a 'strong' etag in that it's sensitive to the exact bytes of the entity.
+  # Note that etags are per-entity, not per-resource. (even weak etags, which we don't yet support;
+  # 'weak' appears to refer to time-based equivalence for the same entity, rather than equivalence of all entity representations of a resource.)
+  #
+  #  May return nil. Default implementation is an MD5 digest of the entity data.
+  def etag
+    Digest::MD5.hexdigest(binary_data)
+  end
+end

data/lib/doze/error.rb

@@ -0,0 +1,75 @@
+# Doze::Error wraps the data required to send an HTTP error response as an exception which Application and Responder infrastructure can raise.
+class Doze::Error < StandardError
+  def initialize(http_status=Doze::Utils::STATUS_INTERNAL_SERVER_ERROR, message='', headers={}, backtrace=nil)
+    @http_status = http_status
+    @headers = headers
+    @backtrace = backtrace
+    super(Rack::Utils::HTTP_STATUS_CODES[http_status] + (message ? ": #{message}" : ''))
+  end
+
+  def backtrace
+    @backtrace || super
+  end
+
+  attr_reader :http_status, :headers
+end
+
+# Errors intended to be raised within resource or entity code to indicate a client error.
+# Currently this is a subclass of the internally-used Doze::Error class, but could
+# equally be a separate exception class intended for Resource-level use which is caught and
+# re-raised by the internal code.
+class Doze::ClientError < Doze::Error; end
+
+# An error parsing a submitted Entity representation. Should typically only be raised within Entity code
+class Doze::ClientEntityError < Doze::ClientError
+  def initialize(message=nil)
+    super(Doze::Utils::STATUS_BAD_REQUEST, message)
+  end
+end
+
+# Unbeknownst at the time of routing, the resource is not actually there.
+class Doze::ResourceNotFoundError < Doze::ClientError
+  def initialize(message=nil)
+    super(Doze::Utils::STATUS_NOT_FOUND, message)
+  end
+end
+
+# Can be used for any error at the resource level which is caused by client error.
+# Should relate to a problem processing the resource-level semantics of a request,
+# rather than a syntactic error in a submitted entity representation.
+# see http://tools.ietf.org/html/rfc4918#section-11.2
+class Doze::ClientResourceError < Doze::ClientError
+  def initialize(message=nil)
+    super(Doze::Utils::STATUS_UNPROCESSABLE_ENTITY, message)
+  end
+end
+
+# Can be used if you want to deny an action, but you couldn't do it at the time
+# of routing (which you could have done with Router#authorize_routing) or if you
+# want to include an error reason with the response
+class Doze::UnauthorizedError < Doze::ClientError
+  def initialize(reason='unauthorized')
+    super(Doze::Utils::STATUS_UNAUTHORIZED, reason)
+  end
+end
+class Doze::ForbiddenError < Doze::ClientError
+  def initialize(reason='forbidden')
+    super(Doze::Utils::STATUS_FORBIDDEN, reason)
+  end
+end
+
+# You can raise this if there is some problem internally that can't be handled
+# by the resource
+class Doze::ServerError < Doze::Error; end
+
+# The resource might exist, but for some reason the requested operation
+# can not be performed at this moment in time.  This type of error would
+# indicate that this is a temporary situation and is due, like the error says,
+# to the resource, or some dependency of it, being unavailable.
+# This translates to a 503, innit.
+class Doze::ResourceUnavailableError < Doze::ServerError
+  def initialize(message=nil)
+    super(Doze::Utils::STATUS_SERVICE_UNAVAILABLE, message)
+  end
+end
+

data/lib/doze/media_type.rb

@@ -0,0 +1,135 @@
+class Doze::MediaType
+  NAME_LOOKUP = {}
+  BY_EXTENSION = {}
+
+  # Names for this media type.
+  # Names should uniquely identify the media type, so eg [audio/x-mpeg3, audio/mp3] might both be names of one
+  # media type, but application/xml is not a name of application/xhtml+xml; see matches_names
+  attr_reader :names
+
+  # The primary name for this media type.
+  def name; @names.first; end
+
+  # Media type strings which this media type matches.
+  # Matching means this media type is acceptable in reponse to a request for the media type string in question.
+  # Eg application/xhtml+xml is acceptable in response to a request for application/xml or text/xml,
+  # so text/xml and application/xml may be listed under the matches_names of application/xhtml+xml
+  attr_reader :matches_names
+
+  # The name used to describe this media type to clients (sometimes we want to use a more
+  # detailed media type internally). Defaults to name
+  def output_name
+    @output_name || @names.first
+  end
+
+  # Media types may be configured to use a different entity class to the default (Doze::Entity) for an
+  # entity of that media type
+  attr_reader :entity_class
+
+  # Some serialization media types have a plus suffix which can be used to create derived types, eg
+  # application/xml, with plus_suffix 'xml', could have application/xhtml+xml as a derived type
+  # see register_derived_type
+  attr_reader :plus_suffix
+
+  # Media type may be associated with a particular file extension, eg image/jpeg with .jpeg
+  # Registered media types may be looked up by extension, eg this is used when :media_type_extensions
+  # is enabled on the application.
+  #
+  # If you register more than one media type with the same extension the most recent one will
+  # take priority, ie probably best not to do this.
+  attr_reader :extension
+
+  # Creates and registers a media_type instance by its names for lookup via [].
+  # This means this instance will be used when a client submits an entity with any of the given
+  # names.
+  # You're recommended to register any media types that are frequently used as well,
+  # even if you don't need any special options or methods for them.
+  def self.register(name, options={})
+    new(name, options).register!
+  end
+
+  def register!
+    names.each do |n|
+      raise "Attempt to register media_type name #{n} twice" if NAME_LOOKUP.has_key?(n)
+      NAME_LOOKUP[n] = self
+    end
+    register_extension!
+    self
+  end
+
+  def register_extension!
+    BY_EXTENSION[@extension] = self if @extension
+  end
+
+  def self.[](name)
+    NAME_LOOKUP[name] || new(name)
+  end
+
+  # name: primary name for the media type
+  # options:
+  #   :aliases      :: extra names to add to #names
+  #   :output_name  :: defaults to name
+  #   :also_matches :: extra names to add to matches_names, in addition to names and output_name
+  #   :entity_class
+  #   :plus_suffix
+  #   :extension
+  def initialize(name, options={})
+    @names = [name]
+    @names.push(*options[:aliases]) if options[:aliases]
+
+    @output_name = options[:output_name]
+
+    @matches_names = @names.dup
+    @matches_names << @output_name if @output_name
+    @matches_names.push(*options[:also_matches]) if options[:also_matches]
+    @matches_names.uniq!
+
+    @entity_class = options[:entity_class] || Doze::Entity
+    @plus_suffix = options[:plus_suffix]
+
+    @extension = options[:extension]
+  end
+
+  def major
+    @major ||= name.split('/', 2)[0]
+  end
+
+  def minor
+    @major ||= name.split('/', 2)[1]
+  end
+
+  # Helper to derive eg application/vnd.foo+json from application/json and name_prefix application/vnd.foo
+  def register_derived_type(name_prefix, options={})
+    options = {
+      :also_matches => [],
+      :entity_class => @entity_class
+    }.merge!(options)
+    options[:also_matches].push(*self.matches_names)
+    name = @plus_suffix ? "#{name_prefix}+#{plus_suffix}" : name_prefix
+    self.class.register(name, options)
+  end
+
+  # Create a new entity of this media_type. Uses entity_class
+  def new_entity(options, &b)
+    @entity_class.new(self, options, &b)
+  end
+
+  def subtype?(other)
+    @matches_names.include?(other.name)
+  end
+
+  def matches_prefix?(prefix)
+    @matches_names.any? {|name| name.start_with?(prefix)}
+  end
+
+  # Equality override to help in case multiple temporary instances of a media type of a given name are compared.
+  def ==(other)
+    super || (other.is_a?(Doze::MediaType) && other.name == name)
+  end
+
+  alias :eql? :==
+
+  def hash
+    name.hash
+  end
+end

data/lib/doze/negotiator.rb

@@ -0,0 +1,107 @@
+# A Negotiator handles content negotiation on behalf of a client request.
+# It will choose the entity it prefers from a list of options offered to it.
+# You can ask it to give you a quality value, or to choose from a list of options.
+# It'll choose from media_types, languages, or combinations of the two.
+class Doze::Negotiator
+  def initialize(request, ignore_unacceptable_accepts=false)
+    @ignore_unacceptable_accepts = ignore_unacceptable_accepts
+
+    @media_type_criterea = if (ext = request.extension)
+      # if the request extension requests a specific media type, this overrides any Accept header and is
+      # interpreted as a demand for this media type and this one only.
+      media_type = Doze::MediaType::BY_EXTENSION[ext]
+      if media_type
+        [[media_type.name, 2, 1.0]]
+      else
+        # if there's a request extension but we can't find a media type for it, we interpret this as an
+        # 'impossible demand' that will match nothing
+        []
+      end
+
+    elsif (accept_header = request.env['HTTP_ACCEPT'])
+      parse_accept_header(accept_header) {|range| matcher_from_media_range(range)}.sort_by {|matcher,specificity,q| -specificity}
+
+    else
+      # No Accept header - anything will do
+      [[Object, 0, 1.0]]
+    end
+
+    accept_language_header = request.env['HTTP_ACCEPT_LANGUAGE']
+    @language_criterea = if accept_language_header
+      parse_accept_header(accept_language_header) {|range| matcher_from_language_range(range)}.sort_by {|matcher,specificity,q| -specificity} + [[nil, 0, 0.001]]
+      # When language_criterea are given, we allow a low-specificity tiny-but-nonzero match for a language of 'nil', ie entities with no
+      # language, even though the accept header may appear to require a particular language. Because it makes no sense to apply Accept-Language
+      # criterea to resources whose representations aren't language-specific.
+    else
+      [[Object, 0, 1.0]]
+    end
+  end
+
+  def media_type_quality(media_type)
+    @media_type_criterea.each {|matcher,specificity,quality| return quality if media_type.matches_names.any? {|name| matcher === name}}; 0
+  end
+
+  def language_quality(language)
+    @language_criterea.each {|matcher,specificity,quality| return quality if matcher === language}; 0
+  end
+
+  # Combined quality value for a (media_type, language) pair
+  def quality(media_type, language)
+    media_type_quality(media_type)*language_quality(language)
+  end
+
+  # Choose from a list of Doze::Entity
+  def choose_entity(entities)
+    max_by_non_zero(entities) {|a| quality(a.media_type, a.language)}
+  end
+
+  private
+    # Given an http-style media-range, language-range, charset-range etc string, return a ruby object which answers to ===(string)
+    # for whether or not that string matches the range given. (note: these are useful in combination with Enumerable#grep)
+    # together with a priority value for the priority of this matcher (most specific has highest priority)
+    # Example input: *, text/*, text/html, en, en-gb, utf-8
+    def matcher_from_media_range(range_string)
+      case range_string
+      when '*', '*/*'
+        # Object === 'anything'
+        [Object,                  0]
+      when /^(.*?\/)\*$/
+        # media type range eg text/*
+        [/^#{Regexp.escape($1)}/, 1]
+      else
+        [range_string,            2]
+      end
+    end
+
+    def matcher_from_language_range(range_string)
+      case range_string
+      when '*'
+        # Object === 'anything'
+        [Object,                  0]
+      else
+        # en matches en, en-gb, en-whatever-else-after-a-hyphen, with longer strings more specific
+        [/^#{Regexp.escape(range_string)}(-|$)/, range_string.length]
+      end
+    end
+
+    def parse_accept_header(accept_header_value)
+      accept_header_value.split(/,\s*/).map do |part|
+        /^([^\s,]+?)(?:;\s*q=(\d+(?:\.\d+)?))?$/.match(part) or next # From WEBrick via Rack
+        q = ($2 || 1.0).to_f
+        matcher, specificity = yield($1)
+        [matcher, specificity, q]
+      end.compact
+    end
+
+    def max_by_non_zero(array)
+      max_quality = 0; max_item = nil
+      array.each do |item|
+        quality = yield(item)
+        if quality > max_quality
+          max_quality = quality
+          max_item = item
+        end
+      end
+      max_item || (@ignore_unacceptable_accepts && array.first)
+    end
+end

data/lib/doze/request.rb

@@ -0,0 +1,119 @@
+require 'doze/error'
+require 'doze/utils'
+
+# Some helpers for Rack::Request
+class Doze::Request < Rack::Request
+  def initialize(app, env)
+    @app = app
+    super(env)
+  end
+
+  attr_reader :app
+
+  # this delibarately ignores the HEAD vs GET distinction; use head? to check
+  def normalized_request_method
+    method = @env["REQUEST_METHOD"]
+    method == 'HEAD' ? 'get' : method.downcase
+  end
+
+  # At this stage, we only care that the servlet spec says PATH_INFO is decoded so special case
+  # it.  There might be others needed, but webrick and thin return an encoded PATH_INFO so this'll
+  # do for now.
+  # http://bulknews.typepad.com/blog/2009/09/path_info-decoding-horrors.html
+  # http://java.sun.com/j2ee/sdk_1.3/techdocs/api/javax/servlet/http/HttpServletRequest.html#getPathInfo%28%29
+  def raw_path_info
+    ((servlet_request = @env['java.servlet_request']) &&
+      raw_path_info_from_servlet_request(servlet_request)) || path_info
+  end
+
+  def get_or_head?
+    method = @env["REQUEST_METHOD"]
+    method == "GET" || method == "HEAD"
+  end
+
+  def options?
+    @env["REQUEST_METHOD"] == 'OPTIONS'
+  end
+
+  def entity
+    return @entity if defined?(@entity)
+    @entity = if media_type
+      media_type.new_entity(
+        :binary_data_stream => env['rack.input'],
+        :binary_data_length => content_length && content_length.to_i,
+        :encoding           => content_charset,
+        :media_type_params  => media_type_params
+      )
+    end
+  end
+
+  def media_type
+    @mt ||= (mt = super and Doze::MediaType[mt])
+  end
+
+  # For now, to do authentication you need some (rack) middleware that sets one of these env's.
+  # See :session_from_rack_env under Doze::Application config
+  def session
+    @session ||= @app.config[:session_from_rack_env].call(@env)
+  end
+
+  def session_authenticated?
+    @session_authenticated ||= (session && @app.config[:session_authenticated].call(session))
+  end
+
+  EXTENSION_REGEXP = /\.([a-z0-9\-_]+)$/
+
+  # splits the raw_path_info into a routing path, and an optional file extension for use with
+  # special media-type-specific file extension handling (where :media_type_extensions => true
+  # configured on the app)
+  def routing_path_and_extension
+    @routing_path_and_extension ||= begin
+      path = raw_path_info
+      extension = nil
+
+      if @app.config[:media_type_extensions] && (match = EXTENSION_REGEXP.match(path))
+        path = match.pre_match
+        extension = match[1]
+      end
+
+      [path, extension]
+    end
+  end
+
+  def routing_path
+    routing_path_and_extension[0]
+  end
+
+  def extension
+    routing_path_and_extension[1]
+  end
+
+  # Makes a Doze::Negotiator to do content negotiation on behalf of this request
+  def negotiator(ignore_unacceptable_accepts=false)
+    Doze::Negotiator.new(self, ignore_unacceptable_accepts)
+  end
+
+  private
+
+    URL_CHUNK = /^\/[^\/\?]+/
+    URL_UP_TO_URI = /^(\w)+:\/\/[\w0-9\-\.]+(:[0-9]+)?/
+    URL_SEARCHPART = /\?.+$/
+
+    # FIXME - This doesn't do anything with the script name, which will cause trouble
+    # if one is specified
+    def raw_path_info_from_servlet_request(servlet_request)
+      # servlet spec decodes the path info, we want an unencoded version
+      # fortunately getRequestURL is unencoded, but includes extra stuff - chop it off
+      sb = servlet_request.getRequestURL.toString
+      # chomp off the proto, host and optional port
+      sb = sb.gsub(URL_UP_TO_URI, "")
+
+      # chop off context path if one is specified - not sure if this is desired behaviour
+      # but conforms to servlet spec and then remove the search part
+      if servlet_request.getContextPath == ""
+        sb
+      else
+        sb.gsub(URL_CHUNK, "")
+      end.gsub(URL_SEARCHPART, "")
+    end
+end

data/lib/doze/resource/error.rb

@@ -0,0 +1,21 @@
+# A special resource class used to represent errors which are available in different media_types etc.
+# Used by the framework to render 5xx / 4xx etc
+#
+# The framework supplies this, based on Doze::Serialization::Resource, as the default implementation
+# but you may specify your own error resource class in the app config.
+require 'doze/resource'
+require 'doze/serialization/resource'
+class Doze::Resource::Error
+  include Doze::Resource
+  include Doze::Serialization::Resource
+
+  def initialize(status=Doze::Utils::STATUS_INTERNAL_SERVER_ERROR, message=Rack::Utils::HTTP_STATUS_CODES[status], extras={})
+    @status = status
+    @message = message
+    @extra_properties = extras
+  end
+
+  def get_data
+    @extra_properties.merge(:status => @status, :message => @message)
+  end
+end