doze 0.0.11

data/lib/doze/response.rb

@@ -0,0 +1,78 @@
+class Doze::Response
+  include Doze::Utils
+
+  def initialize(status=STATUS_OK, headers={}, body='')
+    @headers = Rack::Utils::HeaderHash.new(headers)
+    @status = status
+    @body = body
+    @head_only = false
+  end
+
+  attr_reader :headers
+  attr_accessor :body, :status, :head_only
+
+  def finish(head_only=@head_only)
+    @headers["Content-Length"] ||= content_length.to_s unless @status == STATUS_NO_CONTENT || @status == STATUS_NOT_MODIFIED
+    @headers['Date'] = Time.now.httpdate
+    [@status, @headers.to_hash, head_only ? [] : [@body]]
+  end
+
+  def content_length
+    @body.respond_to?(:bytesize) ? @body.bytesize : @body.size
+  end
+
+  def entity=(entity)
+    content_type = entity.media_type.output_name
+    content_type = "#{content_type}; charset=#{entity.encoding}" if entity.encoding
+    language = entity.language
+    etag = entity.etag
+
+    @headers['Content-Type'] = content_type
+    @headers['Content-Language'] = language if language
+    @headers['ETag'] = quote(etag) if etag
+    @headers.merge!(entity.extra_content_headers)
+
+    @body = entity.binary_data
+  end
+
+  def self.new_from_entity(entity, status=STATUS_OK)
+    result = new(status)
+    result.entity = entity
+    result
+  end
+
+  def self.new_empty(status=STATUS_NO_CONTENT, headers={})
+    new(status, headers)
+  end
+
+  def set_redirect(resource, request, status=STATUS_SEE_OTHER)
+    raise 'Resource specified as a representation must have a uri in order to redirect to it' unless resource.uri
+    @status = status
+    set_location(resource, request)
+    @body ||= ''
+  end
+
+  def set_location(resource, request)
+    base_uri = request.app.config[:base_uri] || request_base_uri(request)
+    @headers['Location'] = base_uri.merge(resource.uri).to_s
+  end
+
+  def self.new_redirect(resource, request, status=STATUS_SEE_OTHER)
+    result = new
+    result.set_redirect(resource, request, status)
+    result
+  end
+
+  def add_header_values(header, *values)
+    values.unshift(@headers[header])
+    @headers[header] = values.compact.join(', ')
+  end
+
+  def set_cookie(key, value)
+    Rack::Utils.set_cookie_header!(@headers, key, value)
+  end
+
+  def delete_cookie(key, value={})
+    Rack::Utils.delete_cookie_header!(@headers, key, value)
+  end
+end

data/lib/doze/router/anchored_route_set.rb

@@ -0,0 +1,68 @@
+module Doze::Router::AnchoredRouteSet
+
+  # Key interface to implement here is #routes and #router_uri_prefix
+
+  def routes
+    raise NotImplementedException
+  end
+
+  def router_uri_prefix
+    raise NotImplementedException
+  end
+
+  def router_uri_prefix=
+    raise NotImplementedException
+  end
+
+  # Some utility functions based on this interface
+
+  def route_template(name)
+    route = routes[name] and route.template(router_uri_prefix)
+  end
+
+  def expand_route_template(name, vars)
+    route = routes[name] and route.expand(vars, router_uri_prefix)
+  end
+
+  def partially_expand_route_template(name, vars)
+    route = routes[name] and route.partially_expand(vars, router_uri_prefix)
+  end
+
+  def get_route(name, vars={}, session=nil)
+    route = routes[name] and route.call(self, vars, session)
+  end
+
+  def perform_routing_with_parent(parent_router, path, session, base_uri)
+    for route in routes
+      match, uri, trailing = route.match(path)
+      next unless match
+      base_uri_for_match = base_uri + uri
+      result = route.call(parent_router, match, session, base_uri_for_match) or next
+      return [result, base_uri_for_match, trailing]
+    end
+    nil
+  end
+
+  # What this does:
+  #  - Informs this instance of the fixed uri at which it's known to be anchored
+  #  - Uses this information to infer fixed uris for the target_route_set of any of
+  #    our routes which are not parameterized? and which routes_uniquely_to_target?,
+  #    and recursively tell these AnchoredRouteSets their fixed uris.
+  #
+  # This is called on the root resource as part of application initialization,
+  # to ensure that statically-known information about routing paths is propagated
+  # as far as possible through the resource model, so that resource instances can
+  # know their uris without necessarily having been a part of the routing chain for
+  # the current request.
+  def propagate_static_routes(uri)
+    self.router_uri_prefix = uri
+    routes.each do |route|
+      next if route.parameterized? or !route.routes_uniquely_to_target?
+      target = route.target_route_set
+      if target
+        route_uri = route.template(router_uri_prefix).to_s
+        target.propagate_static_routes(route_uri)
+      end
+    end
+  end
+end

data/lib/doze/router/route.rb

@@ -0,0 +1,88 @@
+class Doze::Router::Route
+
+  # Route options:
+  #   :name             :: override default name, which is based on stripping non-alphanumerics from the route template
+  #   :session_specific :: pass session as an extra last argument to the routing block
+  #   :static           :: route is not dependent on the parent router instance; parent router instance will not be
+  #                        passed as first argument to routing block
+  #   :to (Router or Resource)
+  #                     :: Route directly to this instance. Only for use where it is reachable by the
+  #                        propagate_static_routes or where its uri is otherwise guaranteed to be the one routed to
+  #   :to (Class)       :: Pass routing arguments to the constructor of this class, instead of block.
+  #                        Assumes :static => true by default.
+  #                     :: Whenever :to => xyz routing is used, and the target is an AnchoredRouteSet (eg a Router instance or
+  #                        a class that includes Router) remembers this as the target_route_set of the route.
+  #   :uniquely         :: for use with :to, indicates that this is the only, unique route to the given target.
+  #                        where the target uri is statically inferable, allows propagate_static_routes to set the uri
+  #                        on the target_route_set.
+  #   :uniquely_to      :: short-cut for :to => foo, :uniquely => true
+  #   &block            :: block which is passed (router, matched_uri, matched_vars_from_template, session), except:
+  #                        * router is ommitted when :static
+  #                        * matched_vars_from_template is ommitted when the template has no vars (!parameterized?)
+  #                        * session is ommitted unless :session_specific set
+  #                        not required where :to is used.
+  def initialize(template, options={}, &block)
+    template = Doze::URITemplate.compile(template, options[:regexps] || {}) unless template.is_a?(Doze::URITemplate)
+    @template = template
+    @name = options[:name] || template.to_s.gsub(/[^a-z0-9]+/, '_').match(/^_?(.*?)_?$/)[1]
+    @session_specific = options[:session_specific]
+    @static = options[:static]
+
+    if options[:uniquely_to]
+      options[:uniquely] = true
+      options[:to] = options[:uniquely_to]
+    end
+
+    target = options[:to]
+    case target
+    when Doze::Router, Doze::Resource
+      @static = true
+      @target_instance = target
+    when Class
+      @static = true if @static.nil?
+      @block = block || target.method(:new)
+    else
+      @block = block or raise "You must specify :to or give a block"
+    end
+
+    if target.is_a?(Doze::Router::AnchoredRouteSet)
+      @target_route_set = target
+      @routes_uniquely_to_target = !options[:uniquely].nil?
+    end
+  end
+
+  attr_reader :name, :block, :session_specific, :static, :target_route_set
+
+  def routes_uniquely_to_target?; @routes_uniquely_to_target; end
+  def static?; @static; end
+
+  def template(prefix=nil)
+    prefix ? @template.with_prefix(prefix) : @template
+  end
+
+  def call(router, vars=nil, session=nil, base_uri=nil)
+    return @target_instance if @target_instance
+    base_uri ||= expand(vars, router.router_uri_prefix) if router
+    args = [base_uri]
+    args << vars if vars && !vars.empty?
+    args << session if @session_specific
+    args.unshift(router) unless @static
+    @block.call(*args)
+  end
+
+  def match(path)
+    @template.match_with_trailing(path)
+  end
+
+  def expand(vars, prefix=nil)
+    template(prefix).expand(vars)
+  end
+
+  def partially_expand(vars, prefix=nil)
+    template(prefix).partially_expand(vars)
+  end
+
+  def parameterized?
+    !@template.variables.empty?
+  end
+end

data/lib/doze/router/route_set.rb

@@ -0,0 +1,34 @@
+class Doze::Router::RouteSet
+  def initialize(&block)
+    @routes = []
+    @routes_by_name = {}
+    instance_eval(&block) if block
+  end
+
+  def <<(route)
+    @routes << route unless @routes_by_name.has_key?(route.name)
+    @routes_by_name[route.name] = route
+    self
+  end
+
+  def [](name)
+    @routes_by_name[name]
+  end
+
+  def route(*p, &b)
+    route = Doze::Router::Route.new(*p, &b)
+    self << route
+    route
+  end
+
+  def each(&b)
+    @routes.each(&b)
+  end
+
+  def dup(&block)
+    route_set = self.class.new
+    @routes.each {|r| route_set << r}
+    route_set.instance_eval(&block) if block
+    route_set
+  end
+end

data/lib/doze/router.rb

@@ -0,0 +1,100 @@
+# A Doze::Router is a Doze::AnchoredRouteSet which routes with itself as the parent Router.
+# Including it also extends the class with Doze::AnchoredRouteSet, and the instances delegates its routes
+# to the class.
+module Doze::Router
+  require 'doze/router/anchored_route_set'
+
+  include Doze::Router::AnchoredRouteSet
+
+  def self.included(mod)
+    mod.extend(ClassMethods) if mod.is_a?(Class) # if you include this in another module, its self.included should call this one
+  end
+
+  # The main method of the Router interface.
+  #
+  # You can override this if you like, but a flexible default implementation is provided
+  # which can be configured with the 'route' class method.
+  #
+  # args:
+  #  path               - the path to match.
+  #                       may be a suffix of the actual request path, if this router has been
+  #                       delegated to by a higher-level router)
+  #  method             - symbol for the http method being routed for this path
+  #  session            - session from the request - see Application.config[:session_from_rack_env]
+  #  base_uri           - the base uri at which the routing is taking place
+  #
+  # should return either:
+  #  nil if no route matched / subresource not found, or
+  #
+  #  [route_to, base_uri_for_match, trailing] where
+  #
+  #   route_to           - Resource or Router to route the request to
+  #   base_uri_for_match - base uri for the resource or router which we matched
+  #   trailing           - any trailing bits of path following from base_uri_for_match to be passed onto the next router
+  def perform_routing(path, session, base_uri)
+    perform_routing_with_parent(self, path, session, base_uri)
+  end
+
+  # The default Router implementation can run against any RouteSet returned here.
+  # By default routes returns a RouteSet defined at the class level using the class-method routing helpers,
+  # but you can override this if you want to use some instance-specific RouteSet
+  def routes
+    @routes || self.class.routes
+  end
+
+  # Add an instance-specific route. This dups the default route-set
+  def add_route(*p, &b)
+    @routes ||= routes.dup
+    @routes.route(*p, &b)
+  end
+
+  # If this particular router instance has a uri prefix associated with it.
+  # Will use a resource's URI method where available, for the common case where the router is also a resource
+  def router_uri_prefix
+    @router_uri_prefix ||= begin
+      u = respond_to?(:uri) ? uri : nil
+      u && u.chomp('/')
+    end
+  end
+
+  # Used primarily by propagate_static_routes. As a (desired) side-effect, will also set the uri using #uri=
+  # where this router is also a resource.
+  def router_uri_prefix=(uri_prefix)
+    if respond_to?(:uri=)
+      self.uri = (uri_prefix.empty? ? '/' : uri_prefix)
+    end
+    @router_uri_prefix = uri_prefix
+  end
+
+  # called upon by the framework
+  # return false to blanket deny authorization to all methods on all routed subresources
+  def authorize_routing(session)
+    true
+  end
+
+  module ClassMethods
+    include Doze::Router::AnchoredRouteSet
+
+    def router_uri_prefix
+      return @router_uri_prefix if defined?(@router_uri_prefix)
+      @router_uri_prefix = (superclass.respond_to?(:router_uri_prefix) ? superclass.router_uri_prefix : nil)
+    end
+
+    def router_uri_prefix=(uri)
+      @router_uri_prefix = uri
+      module_eval("def uri; self.class.router_uri_prefix; end", __FILE__, __LINE__)
+      module_eval("def router_uri_prefix; self.class.router_uri_prefix; end", __FILE__, __LINE__)
+    end
+
+    def routes
+      @routes ||= (superclass.respond_to?(:routes) ? superclass.routes.dup : Doze::Router::RouteSet.new)
+    end
+
+    def route(*p, &b)
+      routes.route(*p, &b)
+    end
+  end
+end
+
+require 'doze/router/route'
+require 'doze/router/route_set'

data/lib/doze/serialization/entity.rb

@@ -0,0 +1,34 @@
+require 'doze/entity'
+
+module Doze::Serialization
+  class Entity < Doze::Entity
+    def initialize(media_type, options={}, &lazy_object_data)
+      super(media_type, options, &nil)  # ruby quirk: blocks are implicitely passed to super
+      @object_data = options[:object_data]
+      @lazy_object_data = lazy_object_data || options[:lazy_object_data]
+    end
+
+    def object_data(try_deserialize=true)
+      @object_data ||= if @lazy_object_data
+        @lazy_object_data.call
+      elsif try_deserialize
+        data = binary_data(false)
+        data && deserialize(data)
+      end
+    end
+
+    def binary_data(try_serialize=true)
+      super() || if try_serialize
+        @binary_data = serialize(object_data(false))
+      end
+    end
+
+    def serialize(object_data)
+      raise 'serialize: not supported'
+    end
+
+    def deserialize(binary_data)
+      raise 'deserialize: not supported'
+    end
+  end
+end

data/lib/doze/serialization/form_data_helpers.rb

@@ -0,0 +1,40 @@
+module Doze::Serialization::FormDataHelpers
+
+  private
+
+  def escape(s)
+    s.to_s.gsub(/([^ a-zA-Z0-9_.-]+)/n) {
+      '%'+$1.unpack('H2'*$1.size).join('%').upcase
+    }.tr(' ', '+')
+  end
+
+  def unescape(s)
+    s.tr('+', ' ').gsub(/((?:%[0-9a-fA-F]{2})+)/n){
+      [$1.delete('%')].pack('H*')
+    }
+  end
+
+  def normalize_params(parms, name, val=nil)
+    name =~ %r([\[\]]*([^\[\]]+)\]*)
+    key = $1 || ''
+    after = $' || ''
+
+    if after == ""
+      parms[key] = val
+    elsif after == "[]"
+      (parms[key] ||= []) << val
+    elsif after =~ %r(^\[\]\[([^\[\]]+)\]$)
+      child_key = $1
+      parms[key] ||= []
+      if parms[key].last.is_a?(Hash) && !parms[key].last.key?(child_key)
+        parms[key].last.update(child_key => val)
+      else
+        parms[key] << { child_key => val }
+      end
+    else
+      parms[key] ||= {}
+      parms[key] = normalize_params(parms[key], after, val)
+    end
+    parms
+  end
+end

data/lib/doze/serialization/html.rb

@@ -0,0 +1,116 @@
+require 'json'
+require 'doze/media_type'
+require 'doze/serialization/entity'
+require 'doze/utils'
+
+module Doze::Serialization
+  class Entity::HTML < Entity
+    def serialize(data)
+      # TODO move to a template
+      html = <<END
+<html>
+  <head>
+    <style>
+      body {
+        font-family: Arial;
+      }
+      body, td {
+        font-size: 13px;
+      }
+      body > table {
+        border: 1px solid black;
+      }
+      table {
+        border-color: black;
+        border-collapse: collapse;
+      }
+      td {
+        padding: 0;
+        vertical-align: top;
+      }
+      td > span, td > a, td > form {
+        display: block;
+        padding: 0.3em;
+        margin: 0;
+      }
+      td:first-child {
+        text-align: right;
+        font-weight: bold;
+        width: 1%; /* force as small as possible */
+      }
+      td > table {
+        width: 100%;
+      }
+      li > table {
+        width: 100%;
+      }
+      td > ol {
+        padding: 0.3em 0.3em 0.3em 2.3em;
+      }
+      td > ol > li > table {
+      }
+    </style>
+  </head>
+  <body>
+    #{make_html(data)}
+  </body>
+</html>
+END
+    end
+
+    private
+
+    def make_html(data)
+      case data
+      when Hash
+        pairs = data.map {|k,v| "<tr><td>#{make_html(k)}</td><td>#{make_html(v)}</td></tr>"}
+        "<table rules='all' frame='void'>#{pairs.join("\n")}</table>"
+      when Array
+        i=-1; items = data.map {|v| "<tr><td><span>#{i+=1}</span></td><td>#{make_html(v)}</td></tr>"}
+        items.empty? ? '&nbsp;' : "<table rules='all' frame='void'>#{items.join("\n")}</table>"
+      when URI
+        "<a href='#{Rack::Utils.escape_html(data)}'>#{Rack::Utils.escape_html(data)}</a>"
+      when Doze::URITemplate
+        if data.variables.length > 0
+          # Clever HTML rendering of a URI template.
+          # Make a HTML form which uses some javascript onsubmit to navigate to an expanded version of the URI template,
+          # with blanks filled in via INPUTs.
+          inputs = data.parts.map do |part|
+            case part
+            when Doze::URITemplate::String
+              Rack::Utils.escape_html(part.string)
+            when Doze::URITemplate::QuadHexBytesVariable
+              "/<input name='#{Rack::Utils.escape_html(part.name)}'>"
+            when Doze::URITemplate::Variable
+              "<input name='#{Rack::Utils.escape_html(part.name)}'>"
+            end
+          end.join
+
+          i=-1; js = data.parts.map do |part|
+            case part
+            when Doze::URITemplate::String
+              part.string.to_json
+            when Doze::URITemplate::QuadHexBytesVariable
+              i += 1; "(v = parseInt(this.elements[#{i}].value, '10').toString(16), (new Array(9-v.length).join('0')+v).replace(/(..)/g, '/$1'))"
+            when Doze::URITemplate::Variable
+              i += 1; "this.elements[#{i}].value"
+            end
+          end
+
+          js = "window.location.href = #{js.join(" + ")}; return false"
+          "<form method='GET' onsubmit='#{Rack::Utils.escape_html(js)}'>#{inputs}<input type='submit'></form>"
+        else
+          "<a href='#{Rack::Utils.escape_html(data)}'>#{Rack::Utils.escape_html(data)}</a>"
+        end
+      else
+        string = data.to_s.strip
+        string.empty? ? '&nbsp;' : "<span>#{Rack::Utils.escape_html(string)}</span>"
+      end
+    end
+  end
+
+  # A browser-friendly media type for use with Doze::Serialization::Resource.
+  # We don't register it, since you might not want to use it for submitted html entities,
+  # but you can call register! on it yourself if you do
+  HTML = Doze::MediaType.new('text/html', :entity_class => Entity::HTML, :extension => 'html')
+end

data/lib/doze/serialization/json.rb

@@ -0,0 +1,29 @@
+require 'json'
+require 'doze/media_type'
+require 'doze/serialization/entity'
+require 'doze/error'
+require 'doze/utils'
+
+module Doze::Serialization
+  class Entity::JSON < Entity
+    def serialize(ruby_data)
+      ruby_data.to_json
+    end
+
+    def deserialize(binary_data)
+      begin
+        case binary_data
+        when /^[\[\{]/
+          ::JSON.parse(binary_data)
+        else
+          # A pox on the arbitrary syntactic limitation that a top-level piece of JSON must be a hash or array
+          ::JSON.parse("[#{binary_data}]").first
+        end
+      rescue ::JSON::ParserError
+        raise Doze::ClientEntityError, "Could not parse JSON"
+      end
+    end
+  end
+
+  JSON = Doze::MediaType.register('application/json', :plus_suffix => 'json', :entity_class => Entity::JSON, :extension => 'json')
+end