doze 0.0.11

data/lib/doze/resource/proxy.rb

@@ -0,0 +1,81 @@
+# A proxy wrapper for a resource instance, which allows you to proxy through to its resource functionality
+# while potentially overriding some of it with context-sensitive behaviour.
+# Unlike the proxies in the stdlib's 'delegate' library, this will satisfy is_a?(Doze::Resource) for the proxy instance.
+# Also note it only proxies the Resource interface, and doesn't do any method_missing magic to proxy additional methods
+# on the underlying instance. If you need this you can access the target of the proxy with #target, or use 'try',
+# which has been overridden sensibly.
+#
+# Also note the proxy is designed to do the sensible default with a nil target, however do make sure it's doing what
+# you want it to do if using with a nil target
+require 'doze/resource'
+class Doze::Resource::Proxy
+  include Doze::Resource
+
+  def initialize(uri, target)
+    @uri = uri
+    @target = target
+  end
+
+  attr_reader :target
+
+  # Methods based around use try / respond_to? need special care when proxying:
+
+  def try(method, *args, &block)
+    if respond_to?(method)
+      send(method, *args, &block)
+    elsif target.respond_to?(method)
+      target && target.send(method, *args, &block)
+    end
+  end
+
+  def supports_method?(method)
+    supports_method = "supports_#{method}?"
+    if respond_to?(supports_method)
+      send(supports_method)
+    else
+      target && target.supports_method?(method)
+    end
+  end
+
+  def other_method(method_name, entity=nil)
+    if respond_to?(method_name)
+      send(method_name, entity)
+    else
+      target && target.other_method(method_name, entity)
+    end
+  end
+
+  def accepts_method_with_media_type?(resource_method, entity)
+    method_name = "accepts_#{resource_method}_with_media_type?"
+    if respond_to?(method_name)
+      send(method_name, entity)
+    else
+      target && target.accepts_method_with_media_type?(resource_method, entity)
+    end
+  end
+
+  # proxying post is a bit fiddly due to the (in retrospect perhaps a bit unadvised) convenience support for
+  # different method arities for post.
+  # maybe move to post_with_session(entity, session) vs post(entity) if this causes any more pain.
+  def post(entity, session)
+    t = target or return
+    if t.method(:post).arity.abs > 1
+      t.post(entity, session)
+    else
+      t.post(entity)
+    end
+  end
+
+  # Some methods which should return something other than nil by default for an empty target:
+
+  def authorize(user, method)
+    target ? target.authorize(user, method) : true
+  end
+
+  # Other methods which we can proxy generically
+
+  proxied_methods = Doze::Resource.public_instance_methods(true) - ['uri', 'uri_object'] - self.public_instance_methods(false)
+  proxied_methods.each do |method|
+    module_eval("def #{method}(*args, &block); t = target and t.__send__(:#{method}, *args, &block); end", __FILE__, __LINE__)
+  end
+end

data/lib/doze/resource.rb

@@ -0,0 +1,193 @@
+module Doze::Resource
+
+  # URIs and identity
+
+  # You would typically set @uri in your constructor; resources don't have to have a URI, but certain parts of the framework require a URI
+  # in order to create links to the object for Location headers, links etc.
+  # Also see Router (and note that a Resource can also act as a Router for its subresources)
+
+  # The URI path of this resource.
+  # #uri= may be used by propagate_static_routes when a resource which is also a router, is statically routed to.
+  # you can private :uri= if you don't want it writeable, however.
+  attr_accessor :uri
+
+  # Wraps up the URI path of this resource as a URI::Generic
+  def uri_object
+    uri && URI::Generic.build(:path => uri)
+  end
+
+
+  # Authorization / Authentication:
+  #
+  # Return true or false to allow or deny the given action on this resource for the given user (if user is nil, for the unauthenticated user).
+  # If you deny an action by the unauthenticated user, this will be taken as a requirement for authentication. So eg if authentication is all you require,
+  # you could just return !user.nil?
+  #
+  # method will be one of:
+  #  * get, put, post, delete, or some other recognized_method where we supports_method?
+  #
+  # user will be the authenticated user, or nil if there is no authenticated user. The exact nature of the user object will depend on the middleware used
+  # to do authentication.
+  def authorize(user, method)
+    true
+  end
+
+  # You can return false here to make a resource instance act like it doesn't exist.
+  #
+  # You could use this if it's more convenient to have a router create an instance representing a potentially-extant resource,
+  # and to have the actual existence test run on the instance.
+  #
+  # Or you can use it if you want to support certain non-get methods on a resource, but appear non-existent in response to get requests.
+  def exists?
+    true
+  end
+
+  # A convenience which some libraries add to Kernel
+  def try(method, *args, &block)
+    send(method, *args, &block) if respond_to?(method)
+  end
+
+  def supports_method?(method)
+    try("supports_#{method}?")
+  end
+
+  def supports_get?
+    true
+  end
+
+
+  # Called to obtain one or more representations of the resource.
+  #
+  # Should be safe, that is, not have any side-effects visible to the caller. This also implies idempotency (which is weaker).
+  #
+  # You may return either:
+  #
+  #   * A single entity representation, in the form of an instance of Doze::Entity
+  #
+  #   * An array of multiple entity representations, instances of Doze::Entity with different media_types and/or languages.
+  #     Content negotiation may be used to select an appropriate entity from the list.
+  #     NB: if you return multiple entities we recommend using 'lazy' Doze::Entity instances constructed with a block -
+  #         this way the entity data will not need to be generated for entities which aren't selected by content negotiation.
+  #
+  #   * A resource representation, in the form of a Doze::Resource with a URI
+  #     This would correspond to a redirect in HTTP.
+  #
+  # If you wish to indicate that the resource is missing, return false from exists?
+  def get
+    nil
+  end
+
+  # Called to update the entirity of the this resource to the resource represented by the given representation entity.
+  # entity will be a new entity representation whose media_type has been okayed by accepts_put_with_media_type?
+  #
+  # Should be idempotent; Subsequent to a successful put, the following should hold:
+  #   * get should return the updated entity representation (or an alternative representation with the same resource-level semantics)
+  #   * parent.resolve_subresource(additional_identifier_components) should return a resource for which the same holds.
+  #
+  # Need not return anything; success is assumed unless an error is raised. (or: should we have this return true/false?)
+  def put(entity)
+    nil
+  end
+
+  # Called to delete this resource.
+  #
+  # Should be idempotent. Subsequent to a successful delete, the following should hold:
+  #  * exists? should return false, or get should return nil, or both
+  #  * parent.resolve_subresource(additional_identifier_components) should return nil, or return a resource which "doesn't exist" in the same sense as above.
+  #
+  # Need not return anything; success is assumed unless an error is raised. (or: should we have this return true/false?)
+  def delete_resource
+    nil
+  end
+
+  # Intended to be called in order to:
+  #  * Allocate an identifier for a new subresource, and create this subresource, based on the representation entity if given.
+  #    (Note: use put_on_subresource instead if you know the desired identifier)
+  #  * Create a new interal resource which isn't exposed to the caller (eg, log some data)
+  #
+  # May also be used for legacy reasons for some other wider purposes:
+  #  * To annotate, append to or otherwise modify the current resource based on instructions contained in the given representation entity,
+  #    potentially returning an anonymous resource describing the results
+  #  * Otherwise process instructions contained in the given representation entity, returning an anonymous resource describing the results
+  # Note: these uses are a bit of a catch-all, not very REST-ful, and discouraged, see other_method.
+  #
+  # entity will be a entity whose media_type has been okayed by accepts_post_with_media_type?
+  #
+  # Does not need to be idempotent or safe, and should not be assumed to be.
+  #
+  # May return:
+  #   * A Doze::Resource with identifier_components, which will be taken as a newly-created resource.
+  #     This is what we're recommending as the primary intended semantics for post.
+  #   * nil to indicate success without exposing a resulting resource
+  #   * A Doze::Resource without identifier_components, which will be taken to be a returned description of the results of some arbitrary operation performed
+  #     (see discouragement above)
+  #   * A Doze::Entity, which will be taken to be a returned description of the results of some arbitrary operation performed
+  #     (this one even more discouraged, but there if you need a quick way to make an arbitrary fixed response)
+  def post(entity)
+    nil
+  end
+
+  # This allows you to accept methods other than the standard get/put/post/delete from HTTP. When the resource is exposed over a protocol (or requested by a client)
+  # which doesn't support custom methods, some form of tunnelling will be used, typically ontop of POST.
+  #
+  # Semantics are up to you, but should not, and will not, be assumed to be idempotent or safe by any generic middleware.
+  #
+  # When should you consider using a custom method? as I understand it, the REST philosophy is that this is valid and to be encouraged if and only if:
+  #  * Your proposed method has clearly-defined semantics which have the potential to apply generically to a wide variety of resources and media types
+  #  * It doesn't overlap with the semantics of existing methods in a confusing or redundant way (exception: it may be used to replace legacy uses of post
+  #    as described; see eg patch)
+  #  * Requests with the method can safely be forwarded around by middleware which don't know anything about their semantics
+  #  * You've given due consideration to the alternative: rephrasing the problem in terms of standard methods acting on a different resource structure.
+  #    And you concluded that this would be significantly less elegant / would add excessive conceptual (or implementation) overhead
+  #  * Ideally, some attempt has been made to standardize it
+  # The proposed 'patch' method (for selective update of a resource by a diff-like media type) is a good example of something which meets these criterea.
+  # http://greenbytes.de/tech/webdav/draft-dusseault-http-patch-11.html
+  #
+  # entity will be nil, or an entity whose media_type has been okayed by accepts_method_with_media_type?(method_name, ..)
+  #
+  # Return options are the same as for post, as are their interpretations, with the exception that a resource returned will not be assumed to be newly-created.
+  # (we're taking the stance that you should be using post or put for creation of new resources).
+  #
+  # By default it'll call a ruby method of the same name to call, as already happens for post/put/delete.
+  def other_method(method_name, entity=nil)
+    try(method_name, entity)
+  end
+
+  # Called to determine whether the request entity is of a suitable media type for the method in question (eg for a put or a post).
+  # The entity itself is passed in. If you return false, the method will never be called; if true then the method may be called with the entity.
+  def accepts_method_with_media_type?(resource_method, entity)
+    try("accepts_#{resource_method}_with_media_type?", entity)
+  end
+
+
+
+
+  # Caching and modification-related metadata
+
+  # May return a Time object inidicating the last modification date, or nil if not known
+  def last_modified
+    nil
+  end
+
+  # nil = no explicit policy, false = explicitly no caching, true = caching yes please
+  def cacheable?
+    nil
+  end
+
+  # false here (when cacheable? is true) implies that private caching only is desired.
+  def publicly_cacheable?
+    cacheable?
+  end
+
+  # Integer seconds, or nil for no explicitly-specified expiry period. Will only be checked if cacheable? is true.
+  # todo: a means to specify the equivalent of 'must-revalidate'
+  def cache_expiry_period
+    nil
+  end
+
+  # You can override public_cache_expiry_period to specify a longer or shorter period for public caches.
+  # Otherwise assumed same as general cache_expiry_period.
+  def public_cache_expiry_period
+    nil
+  end
+end

data/lib/doze/responder/error.rb

@@ -0,0 +1,34 @@
+class Doze::Responder::Error < Doze::Responder
+
+  def initialize(app, request, error)
+    super(app, request)
+    @error = error
+  end
+
+  # We use a resource class to represent for errors to enable content type negotiation for them.
+  # The class used is configurable but defaults to Doze::Resource::Error
+  def response
+    response = Doze::Response.new
+    if @app.config[:error_resource_class]
+      extras = {:error => @error}
+
+      if @app.config[:expose_exception_details] && @error.http_status >= 500
+        extras[:backtrace] = @error.backtrace
+      end
+
+      resource = @app.config[:error_resource_class].new(@error.http_status, @error.message, extras)
+      # we can't have it going STATUS_NOT_ACCEPTABLE in the middle of trying to return an error resource, so :ignore_unacceptable_accepts
+      responder = Doze::Responder::Resource.new(@app, @request, resource, :ignore_unacceptable_accepts => true)
+      entity = responder.get_preferred_representation(response)
+      response.entity = entity
+    else
+      response.headers['Content-Type'] = 'text/plain'
+      response.body = @error.message
+    end
+
+    response.head_only = true if @request.head?
+    response.status = @error.http_status
+    response.headers.merge!(@error.headers) if @error.headers
+    response
+  end
+end

data/lib/doze/responder/main.rb

@@ -0,0 +1,41 @@
+class Doze::Responder::Main < Doze::Responder
+
+  def response
+    resource = nil
+    route_to = @app.root
+    remaining_path = @request.routing_path
+    remaining_path = nil if remaining_path.empty? || remaining_path == '/'
+    session = @request.session
+    base_uri = ''
+
+    # main routing loop - results in either a final Resource which has been routed to, or nil
+    # todo: maybe something recursive would be a bit more readable here
+    while true
+      if remaining_path && route_to.is_a?(Doze::Router)
+        # Bail early with a 401 or 403 if the router refuses to authorize further routing
+        return auth_failed_response unless route_to.authorize_routing(@request.session)
+        route_to, base_uri, remaining_path = route_to.perform_routing(remaining_path, session, base_uri)
+      elsif !remaining_path && route_to.is_a?(Doze::Resource)
+        resource = route_to
+        break
+      else
+        break
+      end
+    end
+
+    if resource
+      Doze::Responder::Resource.new(@app, @request, resource).response
+    elsif @request.options?
+      if @request.raw_path_info == '*'
+        # Special response for "OPTIONS *" as in HTTP spec:
+        rec_methods = (@app.config[:recognized_methods] + [:head, :options]).join(', ').upcase
+        Doze::Response.new(STATUS_NO_CONTENT, 'Allow' => rec_methods)
+      else
+        # Special OPTIONS response for non-existent resource:
+        Doze::Response.new(STATUS_NO_CONTENT, 'Allow' => 'OPTIONS')
+      end
+    else
+      error_response(STATUS_NOT_FOUND)
+    end
+  end
+end

data/lib/doze/responder/resource.rb

@@ -0,0 +1,262 @@
+class Doze::Responder::Resource < Doze::Responder
+  include Doze::Utils
+
+  attr_reader :resource, :options
+
+  def initialize(app, request, resource, options={})
+    super(app, request)
+    @resource = resource
+    @options = options
+  end
+
+
+  # Basic handling of method support and OPTIONS
+
+  def response
+    if @request.options?
+      Doze::Response.new(STATUS_NO_CONTENT, allow_header)
+    elsif !@resource.supports_method?(recognized_method)
+      error_response(STATUS_METHOD_NOT_ALLOWED, nil, allow_header)
+    else
+      response_to_supported_method
+    end
+  end
+
+  def allow_header
+    methods = @app.config[:recognized_methods].select {|m| @resource.supports_method?(m)}
+    # We support OPTIONS for free, and HEAD for free if GET is supported
+    methods << :head if methods.include?(:get)
+    methods << :options
+    {'Allow' => methods.map {|method| method.to_s.upcase}.join(', ')}
+  end
+
+
+
+  # Handling for supported methods
+
+  def response_to_supported_method
+    fail = authorization_fail_response(recognized_method) and return fail
+
+    exists = @resource.exists?
+
+    if @request.get_or_head?
+      return error_response(STATUS_NOT_FOUND) unless exists
+      response = resource_preconditions_fail_response || make_representation_of_resource_response
+      response.head_only = @request.head?
+      response
+    else
+      entity = @request.entity
+      if entity && recognized_method != :delete
+        fail = request_entity_media_type_fail_response(recognized_method, entity) and return fail
+      end
+
+      # Where the resource supports GET, we can use this to support preconditions (If-Match etc)
+      # on PUT/DELETE/POST operations based on the content that GET would return.
+      if exists && @resource.supports_get?
+        fail = resource_preconditions_fail_response and return fail
+        fail = entity_preconditions_fail_response and return fail
+      end
+
+      perform_non_get_action(entity, exists)
+    end
+  end
+
+  def perform_non_get_action(entity, existed_before)
+    case recognized_method
+    when :post
+      # Slightly hacky but for now we allow the session to be passed as an extra arg to post actions
+      # where the method has sufficient arity.
+      #
+      # This is only supported for POST at present; prefered approach (especially for GET/PUT/DELETE)
+      # is to use a session-specific route and construct the resource with the session context.
+      # Also, this should not be used for authorization logic - use the authorize method for that.
+      result = if @resource.method(:post).arity.abs > 1
+        @resource.post(entity, @request.session)
+      else
+        @resource.post(entity)
+      end
+
+      # 201 created is the default interpretation of a new resource with an identifier resulting from a post.
+      make_post_result_response(result)
+
+    when :put
+      if entity
+        result = @resource.put(entity)
+        Doze::Response.new_empty(existed_before ? STATUS_NO_CONTENT : STATUS_CREATED)
+      else
+        error_response(STATUS_BAD_REQUEST, "expected request body for PUT")
+      end
+
+    when :delete
+      result = @resource.delete_resource if existed_before
+      Doze::Response.new_empty
+
+    else
+      result = @resource.other_method(recognized_method, entity)
+      # For now we streat this pretty much as a POST
+      make_post_result_response(result)
+    end
+  end
+
+
+
+
+
+  # Precondition checkers
+
+  def request_entity_media_type_fail_response(resource_method, entity)
+    unless @resource.accepts_method_with_media_type?(resource_method, entity)
+      error_response(STATUS_UNSUPPORTED_MEDIA_TYPE)
+    end
+  end
+
+  def authorization_fail_response(action)
+    auth_failed_response unless @resource.authorize(@request.session, action)
+  end
+
+  def resource_preconditions_fail_response
+    last_modified = @resource.last_modified or return
+    if_modified_since   = @request.env['HTTP_IF_MODIFIED_SINCE']
+    if_unmodified_since = @request.env['HTTP_IF_UNMODIFIED_SINCE']
+
+    if (if_unmodified_since && last_modified > Time.httpdate(if_unmodified_since))
+      # although technically an HTTP error response, we don't use error_response (and an error resource)
+      # to send STATUS_PRECONDITION_FAILED, since the precondition check was something the client specifically
+      # requested, so we assume they don't need a special error resource to make sense of it.
+      Doze::Response.new(STATUS_PRECONDITION_FAILED, 'Last-Modified' => last_modified.httpdate)
+    elsif (if_modified_since && last_modified <= Time.httpdate(if_modified_since))
+      if request.get_or_head?
+        Doze::Response.new(STATUS_NOT_MODIFIED, 'Last-Modified' => last_modified.httpdate)
+      else
+        Doze::Response.new(STATUS_PRECONDITION_FAILED, 'Last-Modified' => last_modified.httpdate)
+      end
+    end
+  end
+
+  # Etag-based precondition checks. These are specific to the response entity that would be returned
+  # from a GET.
+  #
+  # Note: the default implementation of entity.etag just generates the entity body and hashes it,
+  # but you could return entities which lazily know their Etag without the body needing to be generated,
+  # and this code will take advantage of that
+  def entity_preconditions_fail_response(entity=nil)
+    if_match      = @request.env['HTTP_IF_MATCH']
+    if_none_match = @request.env['HTTP_IF_NONE_MATCH']
+    return unless if_match || if_none_match
+
+    entity ||= get_preferred_representation
+    return unless entity.is_a?(Doze::Entity)
+
+    etag = entity.etag
+
+    # etag membership test is kinda crude at present, really we should parse the separate quoted etags out.
+    if (if_match      && if_match != '*' &&      !(etag && if_match.include?(quote(etag))))
+      Doze::Response.new(STATUS_PRECONDITION_FAILED, 'Etag' => quote(etag))
+    elsif (if_none_match && (if_none_match == '*' || (etag && if_none_match.include?(quote(etag)))))
+      if @request.get_or_head?
+        Doze::Response.new(STATUS_NOT_MODIFIED, 'Etag' => quote(etag))
+      else
+        Doze::Response.new(STATUS_PRECONDITION_FAILED, 'Etag' => quote(etag))
+      end
+    end
+  end
+
+
+
+
+  # Response handling helpers
+
+  def get_preferred_representation(response=nil)
+    representation = @resource.get
+    if representation.is_a?(Array)
+      negotiator = @request.negotiator(@options[:ignore_unacceptable_accepts])
+
+      if response
+        # If the available representation entities differ by media type, add a Vary: Accept. similarly for language.
+        response.add_header_values('Vary', 'Accept') if not_all_equal?(representation.map {|e| e.media_type})
+        response.add_header_values('Vary', 'Accept-Language') if not_all_equal?(representation.map {|e| e.language})
+      end
+
+      # If we fail to find the requested media type when requested via a file extension (/foo.jpeg) the appropriate HTTP status
+      # is 404; at the HTTP level this is effectively a separate media-type-specific version of the resource at its own uri,
+      # which doesn't exist due to the particular media-type-specific version of the resource not being available.
+      # If we fail due to an Accept header not matching anything, of course the appropriate status is STATUS_NOT_ACCEPTABLE
+      negotiator.choose_entity(representation) or raise_error(@request.extension ? STATUS_NOT_FOUND : STATUS_NOT_ACCEPTABLE)
+    else
+      representation
+    end
+  end
+
+  def not_all_equal?(collection)
+    first = collection.first
+    collection.any? {|x| x != first}
+  end
+
+  def add_caching_headers(response)
+    # resource-level caching metadata headers
+    last_modified = @resource.last_modified and response.headers['Last-Modified'] = last_modified.httpdate
+    case @resource.cacheable?
+    when true
+      expiry_period = @resource.cache_expiry_period
+      if @resource.publicly_cacheable?
+        cache_control = 'public'
+        if expiry_period
+          cache_control << ", max-age=#{expiry_period}"
+          public_expiry_period = @resource.public_cache_expiry_period
+          cache_control << ", s-maxage=#{public_expiry_period}" if public_expiry_period
+        end
+      else
+        cache_control = 'private'
+        cache_control << ", max-age=#{expiry_period}" if expiry_period
+      end
+      response.headers['Expires'] = (Time.now + expiry_period).httpdate if expiry_period
+      response.headers['Cache-Control'] = cache_control
+    when false
+      response.headers['Expires'] = 'Thu, 01 Jan 1970 00:00:00 GMT' # Beginning of time woop woop
+      response.headers['Cache-Control'] = 'no-cache, max-age=0'
+    end
+  end
+
+  def make_representation_of_resource_response(include_location_with_status=nil)
+    response = Doze::Response.new
+    representation = get_preferred_representation(response)
+
+    case representation
+    when Doze::Resource
+      raise 'Resource representation must have a uri' unless representation.uri
+      response.set_redirect(representation, @request)
+      add_caching_headers(response)
+      response
+    when Doze::Entity
+      # preconditions on the representation only apply to the content that would be served up by a GET
+      fail_response = @request.get_or_head? && entity_preconditions_fail_response(representation)
+      response = fail_response || begin
+        response.entity = representation
+        response
+      end
+      add_caching_headers(response)
+
+      if include_location_with_status && @resource.uri
+        response.set_location(@resource, @request)
+        response.status = include_location_with_status
+      end
+
+      response
+    when Doze::Response
+      representation
+    end
+  end
+
+  def make_post_result_response(result)
+    case result
+    when Doze::Resource
+      Doze::Responder::Resource.new(@app, @request, result, @options).make_representation_of_resource_response(STATUS_CREATED)
+    when Doze::Entity
+      Doze::Response.new_from_entity(result)
+    when Doze::Response
+      result
+    when nil
+      Doze::Response.new_empty
+    end
+  end
+end

data/lib/doze/responder.rb

@@ -0,0 +1,58 @@
+class Doze::Responder
+  include Doze::Utils
+
+  attr_reader :response, :request
+
+  def initialize(app, request)
+    @app = app
+    @request = request
+  end
+
+  def recognized_method
+    @recognized_method ||= begin
+      method = @request.normalized_request_method
+      ([:options] + @app.config[:recognized_methods]).find {|m| m.to_s == method} or raise_error(STATUS_NOT_IMPLEMENTED)
+    end
+  end
+
+  # for use within #response
+  def raise_error(status=STATUS_INTERNAL_SERVER_ERROR, message=nil, headers={})
+    raise Doze::Error.new(status, message, headers)
+  end
+
+  def error_response(status=STATUS_INTERNAL_SERVER_ERROR, message=nil, headers={}, backtrace=nil)
+    error_response_from_error(Doze::Error.new(status, message, headers, backtrace))
+  end
+
+  def error_response_from_error(error)
+    Doze::Responder::Error.new(@app, @request, error).response
+  end
+
+  def call
+    begin
+      response().finish
+    rescue Doze::Error => error
+      error_response_from_error(error).finish
+    rescue => exception
+      raise unless @app.config[:catch_application_errors]
+      lines = ["#{exception.class}: #{exception.message}", *exception.backtrace].join("\n")
+      @app.logger << lines
+      if @app.config[:expose_exception_details]
+        error_response(STATUS_INTERNAL_SERVER_ERROR, exception.message, {}, exception.backtrace).finish
+      else
+        error_response.finish
+      end
+    end
+  end
+
+  def response
+    raise NotImplementedError
+  end
+
+  def auth_failed_response
+    error_response(@request.session_authenticated? ?
+                STATUS_FORBIDDEN :   # this one, 403, really means 'unauthorized', ie
+                STATUS_UNAUTHORIZED  # http status code 401 called 'unauthorized' but really used to mean 'unauthenticated'
+    )
+  end
+end