hoodoo 1.0.2

data/lib/hoodoo/services/services/permissions.rb

@@ -0,0 +1,250 @@
+########################################################################
+# File::    permissions.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Allow/ask/deny support for resources and actions.
+# ----------------------------------------------------------------------
+#           26-Jan-2015 (ADH): Created.
+########################################################################
+
+module Hoodoo; module Services
+
+  # The Permissions class provides a way to store and recall information on
+  # action behaviour for resources. It is just a way to store and query this
+  # information; actually enforcing the result is up to the caller.
+  #
+  # Permissions are based on the standard actions - +list+, +show+, +create+,
+  # +update+ and +delete+ - with defined permissions of constants DENY
+  # (prohibit access), ALLOW (allow access) and ASK. The intention of ASK is
+  # that some other component - usually a service application - should be
+  # passed details of the request and asked if it should be permitted.
+  #
+  # Callers must *ensure* they *only* use the DENY, ALLOW and ASK constants
+  # defined herein, without making assumptions about their assigned values.
+  #
+  # There is both a default set of permissions in addition to per-resource
+  # permissions and there is a fallback for cases where a permission for a
+  # particular action has not been defined. This lets you define the baseline
+  # behaviour in the fallback cases and only describe exceptions to that
+  # baseline through the Permissions interface, minimising caller workload.
+  #
+  # Hoodoo::Services::Middleware uses an instance of this class to determine
+  # whether or not it should pass on inbound requests to service applications.
+  #
+  # Example:
+  #
+  # Here, an object is created with a default fallback of DENY, then has the
+  # action "list" allowed for all resources and says that resource "Member"
+  # must ask someone for permission if its "show" action is requested.
+  # Another resource "Ping" allows any action unconditionally.
+  #
+  #     p = Hoodoo::Services::Permissions.new
+  #     p.set_default( :list, Hoodoo::Services::Permissions::ALLOW )
+  #     p.set_resource( :Member, :show, Hoodoo::Services::Permissions::ASK )
+  #     p.set_resource_fallback( :Ping, Hoodoo::Services::Permissions::ALLOW )
+  #
+  #     puts JSON.pretty_generate( p.to_h() )
+  #
+  #     # Yields...
+  #     #
+  #     # {
+  #     #   "default": {
+  #     #     "else": "deny",
+  #     #     "actions": {
+  #     #       "list": "allow"
+  #     #     }
+  #     #   },
+  #     #   "resources": {
+  #     #     "Member": {
+  #     #       "actions": {
+  #     #         "show": "ask"
+  #     #       }
+  #     #     },
+  #     #     "Ping": {
+  #     #       "else": "allow"
+  #     #     }
+  #     #   }
+  #     # }
+  #
+  class Permissions
+
+    # Permission is denied; the action should not be permitted.
+    #
+    DENY  = 'deny'
+
+    # Permission is granted; the action should be permitted.
+    #
+    ALLOW = 'allow'
+
+    # Something else (e.g. a service application) needs to be asked to see if
+    # it permits the action.
+    #
+    ASK   = 'ask'
+
+    # All currently known (allowed/supported) permission policies.
+    #
+    ALLOWED_POLICIES = [
+      DENY,
+      ALLOW,
+      ASK
+    ]
+
+    # Create a new Permissions instance, optionally from a Hash of the format
+    # returned by #to_h.
+    #
+    # By default the object is initialised with a default fallback which
+    # denies all actions for all resources.
+    #
+    def initialize( hash = nil )
+      if hash.nil?
+        @permissions = {}
+        set_default_fallback( DENY )
+      else
+        from_h!( hash )
+      end
+    end
+
+    # Set the default fallback for actions. If a resource does not have a
+    # specific entry for it in the Permissions object and if the action does
+    # not have a default permission, then this permission used.
+    #
+    # +permission+:: DENY, ALLOW or ASK.
+    #
+    def set_default_fallback( permission )
+      action_name = action_name.to_s
+
+      @permissions[ 'default' ] ||= {}
+      @permissions[ 'default' ][ 'else' ] = permission
+    end
+
+    # Set the default permission for the given action. If a resource does not
+    # have a specific entry for it in the Permissions object but the action
+    # matches the given name, then this permission is used.
+    #
+    # +action_name+:: Action as a String or Symbol, from: +list+, +show+,
+    #                 +create+, +update+ or +delete+.
+    #
+    # +permission+::  DENY, ALLOW or ASK.
+    #
+    def set_default( action_name, permission )
+      action_name = action_name.to_s
+
+      @permissions[ 'default' ] ||= {}
+      @permissions[ 'default' ][ 'actions' ] ||= {}
+      @permissions[ 'default' ][ 'actions' ][ action_name ] = permission
+    end
+
+    # Set the default fallback for a resource. If the resource is asked to
+    # perform an action that's not otherwise listed in the resource's entry
+    # in the Permissions object, then this permission is used.
+    #
+    # +resource_name+:: Resource name as a Symbol or String, e.g. "+Purchase+"
+    #                   or +:Member+.
+    #
+    # +permission+::    DENY, ALLOW or ASK.
+    #
+    def set_resource_fallback( resource_name, permission )
+      resource_name = resource_name.to_s
+
+      @permissions[ 'resources' ] ||= {}
+      @permissions[ 'resources' ][ resource_name ] ||= {}
+      @permissions[ 'resources' ][ resource_name ][ 'else' ] = permission
+    end
+
+    # Set the permissions an action on a resource.
+    #
+    # +resource_name+:: Resource name as a Symbol or String, e.g. "+Purchase+"
+    #                   or +:Member+.
+    #
+    # +action_name+::   Action as a String or Symbol, from: +list+, +show+,
+    #                   +create+, +update+ or +delete+.
+    #
+    # +permission+::    DENY, ALLOW or ASK.
+    #
+    def set_resource( resource_name, action_name, permission )
+      resource_name = resource_name.to_s
+      action_name   = action_name.to_s
+
+      @permissions[ 'resources' ] ||= {}
+      @permissions[ 'resources' ][ resource_name ] ||= {}
+      @permissions[ 'resources' ][ resource_name ][ 'actions' ] ||= {}
+      @permissions[ 'resources' ][ resource_name ][ 'actions' ][ action_name ] = permission
+    end
+
+    # For the given resource, is the given action permitted? Returns one of the
+    # ALLOW, DENY or ASK constant values.
+    #
+    # +resource_name+:: Resource name as a Symbol or String, e.g. "+Purchase+"
+    #                   or +:Member+.
+    #
+    # +action_name+::   Action as a String or Symbol, from: +list+, +show+,
+    #                   +create+, +update+ or +delete+.
+    #
+    def permitted?( resource_name, action_name )
+      resource_name = resource_name.to_s
+      action_name   = action_name.to_s
+
+      tree = if @permissions.has_key?( 'resources' )
+        @permissions[ 'resources' ][ resource_name ]
+      end || {}
+
+      result = permitted_in?( tree, action_name )
+
+      if result.nil?
+        tree = @permissions[ 'default' ] || {}
+        result = permitted_in?( tree, action_name )
+      end
+
+      return result || DENY
+    end
+
+    # Return a Hash representative of this permissions object, which can be
+    # stored elsewhere, used to initialise another instance or written to an
+    # existing instance with #from_h!.
+    #
+    def to_h
+      @permissions
+    end
+
+    # Overwrite this instances's permissions with those from the given Hash.
+    #
+    # +hash+:: Permissions hash, which must come (directly or indirectly) from
+    #          a #to_h call.
+    #
+    def from_h!( hash )
+      @permissions = Hoodoo::Utilities.stringify( hash )
+    end
+
+    # Merge the permissions described by the given Hash with those inside this
+    # instance. This will add to, or overwrite permissions with those from the
+    # given input Hash.
+    #
+    # +hash+:: Permissions hash, which must come (directly or indirectly) from
+    #          a #to_h call.
+    #
+    def merge!( hash )
+      @permissions = Hoodoo::Utilities.deep_merge_into(
+        @permissions,
+        Hoodoo::Utilities.stringify( hash )
+      )
+    end
+
+  private
+
+    # For a given permissions sub-tree at the level of +actions+ / +else+,
+    # return an entry for the given action name. May return +nil+ if the
+    # tree has neither a matching action nor an +else+ case.
+    #
+    # +tree+::        Permissions sub-tree at the +actions+ / +else+ level.
+    # +action_name+:: As for #permitted?
+    #
+    def permitted_in?( tree, action_name )
+      result = if tree.has_key?( 'actions' )
+        tree[ 'actions' ][ action_name ]
+      end || tree[ 'else' ]
+
+      return result
+    end
+  end
+
+end; end

data/lib/hoodoo/services/services/request.rb

@@ -0,0 +1,189 @@
+########################################################################
+# File::    request.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: A high level description of a client's request, with all of
+#           the "raw" Rack request data parsed, verified as far as
+#           possible and generally cleaned up. Instances of this class
+#           are given to Hoodoo::Services::Implementation methods for
+#           each new request.
+# ----------------------------------------------------------------------
+#           24-Sep-2014 (ADH): Created.
+########################################################################
+
+module Hoodoo; module Services
+
+  # Instances of the Hoodoo::Services::Request class are passed to service
+  # interface implementations when requests come in via Rack, after basic
+  # checks have been passed and a particular interface implementation has
+  # been identified by endpoint.
+  #
+  # Descriptions of default values expected out of accessors herein refer
+  # to the use case when driven through Hoodoo::Services::Middleware. If the
+  # class is instantiated "bare" it gains no default values at all (all
+  # read accessors would report +nil+).
+  #
+  class Request
+
+    # Encapsulation of all parameters related only to modifying a
+    # list of results. Other parameters may modify lists too, but they
+    # also modify other representations (e.g. single-resource 'show').
+    #
+    class ListParameters
+
+      # List offset, for index views; an integer; always defined.
+      #
+      attr_accessor :offset
+
+      # List page size, for index views; an integer; always defined.
+      #
+      attr_accessor :limit
+
+      # A Hash of String keys and values, where each key is a field for
+      # sorting and each value is the direction to sort that field.
+      #
+      attr_accessor :sort_data
+
+      # List search key/value pairs as a hash, all keys/values strings; {}
+      # if there's no search data in the request URI query string.
+      #
+      attr_accessor :search_data
+
+      # List filter key/value pairs as a hash, all keys/values strings; {}
+      # if there's no filter data in the request URI query string.
+      #
+      attr_accessor :filter_data
+
+      # Set up defaults in this instance.
+      #
+      def initialize
+        self.offset      = 0
+        self.limit       = 50
+        self.sort_data   = { 'created_at' => 'desc' }
+        self.search_data = {}
+        self.filter_data = {}
+      end
+    end
+
+    # Requested locale for internationalised operations; +"en-nz"+ by
+    # default.
+    #
+    attr_accessor :locale
+
+    # Define read/write accessors for properties related to "X-Foo"
+    # headers. See the Middleware for details.
+    #
+    Hoodoo::Client::Headers.define_accessors_for_header_equivalents( self )
+
+    # Hash of HTTP headers _in_ _Rack_ _format_ - e.g. +HTTP_X_INTERACTION_ID+
+    # for the "X-Interaction-ID" header, for read-only use. All keys are in
+    # upper case, are Strings, have "HTTP_" at the start and use underscores
+    # where the original request might've used an underscore or hyphen. The
+    # usual curious Rack exceptions of +CONTENT_TYPE+ and +CONTENT_LENGTH+ do
+    # apply, though. This is a superset of header values including those sent
+    # by the client in its request and anything Rack itself might have added.
+    #
+    attr_accessor :headers
+
+    # Parsed payload hash, for create and update actions only; else +nil+.
+    #
+    attr_accessor :body
+
+    # An array of zero or more path components making up the URI *after* the
+    # service endpoint has been accounted for. For example, with a service
+    # endpoint of "products", this URI:
+    #
+    #     http://test.com/v1/products/1234/foo.json
+    #
+    # ...would lead to this path component array:
+    #
+    #     [ '1234', 'foo' ]
+    #
+    # The first element of the path components array is exposed in the
+    # read-only #ident accessor.
+    #
+    attr_reader :uri_path_components
+
+    # Set the array returned by #uri_path_components and record the first
+    # element in the value returned by #ident.
+    #
+    # +ary+:: Path component array to record. If +nil+ or not an array,
+    #         +nil+ is stored for uri_path_components and #ident.
+    #
+    def uri_path_components=( ary )
+      if ary.is_a?( ::Array )
+        @uri_path_components = ary
+        @ident               = ary.first
+      else
+        @uri_path_components = nil
+        @ident               = nil
+      end
+    end
+
+    # The first entry in the #uri_path_components array, or +nil+ if the
+    # array is empty. This supports a common case for inter-resource calls
+    # where a UUID or other unique identifier is provided through the first
+    # path element ("+.../v1/resource/uuid+").
+    #
+    attr_reader :ident
+
+    # A filename extension on the URI path component, if any, else an empty
+    # string. The _first_ dot in the _last_ path component is looked for (see
+    # also #uri_path_components), so for example this URI:
+    #
+    #     http://test.com/v1/products/1.2.3.4/foo.my.tar.gz
+    #
+    # ...would lead to this URI path extension string:
+    #
+    #     'my.tar.gz'
+    #
+    attr_accessor :uri_path_extension
+
+    # The Hoodoo::Services::Request::ListParameters instance
+    # associated with this request.
+    #
+    attr_accessor :list
+
+    # Define a set of now-deprecated accessors that are basically
+    # just proxies through to the "list" instance. See #list.
+    #
+    %i{
+      offset
+      limit
+      sort_data
+      search_data
+      filter_data
+    }.each do | method |
+      define_method( "list_#{ method }" ) do
+        list.send( method )
+      end
+
+      define_method( "list_#{ method }=" ) do | value |
+        list.send( "#{ method }=", value )
+      end
+    end
+
+    # Array of strings giving requested embedded items; [] if there are
+    # none requested.
+    #
+    attr_accessor :embeds
+
+    # Array of strings giving requested referenced items; [] if there are
+    # none requested.
+    #
+    attr_accessor :references
+
+    # Set up defaults in this instance.
+    #
+    def initialize
+      self.locale              = 'en-nz'
+      self.uri_path_components = []
+      self.uri_path_extension  = ''
+      self.list                = Hoodoo::Services::Request::ListParameters.new
+      self.embeds              = []
+      self.references          = []
+      self.headers             = {}.freeze
+    end
+  end
+
+end; end

data/lib/hoodoo/services/services/response.rb

@@ -0,0 +1,316 @@
+########################################################################
+# File::    response.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: A high level description of a service's response to a
+#           client's request. The middleware constructs instances and
+#           fills in some of the data for every client request, then
+#           passes it to Hoodoo::Services::Implementation methods so
+#           the service can fill in the rest of the data.
+# ----------------------------------------------------------------------
+#           24-Sep-2014 (ADH): Created.
+########################################################################
+
+require 'json'
+
+module Hoodoo; module Services
+
+  # The service middleware creates a Hoodoo::Services::Response instance for
+  # each request it handles, populating it with some data before and after the
+  # service implementation runs as part of standard pre- and post-processing.
+  # In the middle, the service implementation is given the instance and adds
+  # its own data to it.
+  #
+  # The instance carries data about both error conditions and successful work.
+  # In the successful case, #http_status_code and #body data is set by the
+  # service and used in the response. In the error case (see #errors), the
+  # HTTP status code is taken from the first error in the errors collection and
+  # the response body will be the JSON representation of that collection - any
+  # HTTP status code or response body data previously set by the service will
+  # be ignored.
+  #
+  class Response
+
+    # Obtain a reference to the Hoodoo::Errors instance for this response;
+    # use Hoodoo::Errors#add_error to add to the collection directly. For
+    # convenience, this class also provides the #add_error proxy instance
+    # method (syntactic sugar for most service implementations, but with a
+    # return value that helps keep the service middleware code clean).
+    #
+    # It's possible to change the errors object if you want to swap it for any
+    # reason, though this is generally discouraged - especially if the existing
+    # errors collection isn't empty. The middleware does this as part of
+    # request handling, but generally speaking nobody else should need to.
+    #
+    attr_accessor :errors
+
+    # HTTP status code that will be involved in the response. Default is 200.
+    # Integer, or something that can be converted to one with +to_i+. If errors
+    # are added to the response then the status code is derived from the first
+    # error in the collection, overriding any value set here. See #errors.
+    #
+    attr_accessor :http_status_code
+
+    # A service implementation can set (and read back, should it wish) the
+    # API call response body data using this #body / #body= accessor. This is
+    # converted to a client-facing representation automatically (e.g. to JSON).
+    #
+    # The response body *MUST* be either a Ruby +Array+ or a Ruby +Hash+.
+    # For *internal* *use* *only* a Ruby +String+ of pre-encoded response data
+    # is also accepted.
+    #
+    # This method is aliased as #set_resource, for semantic use when you want
+    # to set the response body to a representation (as a Hash) of a resource.
+    # When you want to set an Array of items for a list, it is strongly
+    # recommended that you call #set_resources and pass a total dataset size
+    # in addition to just the Array containing a page of list data.
+    #
+    # When reading response data, the body information is only valid if
+    # method #halt_processing? returns +false+.
+    #
+    attr_accessor :body
+    alias_method  :set_resource, :body=
+
+    # Read back a the dataset size given by a prior call to #set_resources,
+    # or +nil+ if none has been provided (either the response contains no
+    # list yet/at all, or an Array was given but the dataset size was not
+    # supplied).
+    #
+    attr_reader :dataset_size
+
+    # Create a new instance, ready to take on a response. The service
+    # middleware is responsible for doing this.
+    #
+    # +interaction_id+:: The UUID of the interaction taking place for which a
+    #                    response is required.
+    #
+    def initialize( interaction_id )
+
+      unless Hoodoo::UUID.valid?( interaction_id )
+        raise "Hoodoo::Services::Response.new must be given a valid Interaction ID (got '#{ interaction_id.inspect }')"
+      end
+
+      @interaction_id   = interaction_id
+      @errors           = Hoodoo::Errors.new()
+      @headers          = {}
+      @http_status_code = 200
+      @body             = {}
+      @dataset_size     = nil
+
+    end
+
+    # Returns +true+ if processing should halt, e.g. because errors have been
+    # added to the errors collection. Check here whenever you would consider an
+    # early exit due to errors arising in processing (otherwise they will just
+    # continue to accumulate).
+    #
+    def halt_processing?
+      @errors.has_errors?
+    end
+
+    # Similar to #body and #set_resource, but used when you are returning an
+    # array of items. Although you can just assign an array to either of
+    # #body or #set_resource, calling #set_resources is more semantically
+    # correct and provides an additional feature; you can specify the total
+    # number of items in the dataset.
+    #
+    # For example, if you were listing a page of 50 resource instances but
+    # the total matching dataset of that list included 344 instances, you
+    # would pass 344 in the +dataset_size+ input parameter. This is optional
+    # but highly recommended as it is often very useful for calling clients.
+    #
+    # +array+::        Array of resource representations (Ruby Array with
+    #                  Ruby Hash entries representing rendered resources,
+    #                  ideally through the Hoodoo::Presenters framework).
+    #
+    # +dataset_size+:: Optional _total_ number of items in the entire dataset
+    #                  of which +array+ is, most likely, just a subset due to
+    #                  paginated lists via offset and limit parameters.
+    #
+    def set_resources( array, dataset_size = nil )
+      self.body = array
+      @dataset_size = dataset_size
+    end
+
+    # Add an HTTP header to the internal collection that will be used for the
+    # response. Trying to set data for the same HTTP header name more than once
+    # will result in an exception being raised unless the +overwrite+ parameter
+    # is used (this is strongly discouraged in the general case).
+    #
+    # +name+::      Correct case and punctuation HTTP header name (e.g.
+    #               "Content-Type").
+    #
+    # +value+::     Value for the header, as a string or something that behaves
+    #               sensibly when +to_s+ is invoked upon it.
+    #
+    # +overwrite+:: Optional. Pass +true+ to allow the same HTTP header name to
+    #               be set more than once - the new value overwrites the old.
+    #               By default this is prohibited and an exception will be
+    #               raised to avoid accidental value overwrites.
+    #
+    def add_header( name, value, overwrite = false )
+      name = name.to_s
+      dname = name.downcase
+      value = value.to_s
+
+      if ( overwrite == false && @headers.has_key?( dname ) )
+        hash  = @headers[ dname ]
+        name  = hash.keys[ 0 ]
+        value = hash.values[ 0 ]
+        raise "Hoodoo::Services::Response\#add_header: Value '#{ value }' already defined for header '#{ name }'"
+      else
+        @headers[ dname ] = { name => value }
+      end
+    end
+
+    # Check the stored value of a given HTTP header. Checks are case
+    # insensitive. Returns the value stored by a prior #add_header call, or
+    # +nil+ for no value (or an explicitly stored value of +nil+)
+    #
+    # +name+:: HTTP header name (e.g. "Content-Type", "CONTENT-TYPE").
+    #
+    def get_header( name )
+      value_hash = @headers[ name.downcase ]
+      return nil if value_hash.nil?
+      return value_hash.values[ 0 ]
+    end
+
+    # Returns the list previously set headers in a name: value Hash.
+    #
+    def headers
+      @headers.inject( {} ) do | result, kv_array |
+        result.merge( kv_array[ 1 ] )
+      end
+    end
+
+    # Add an error to the internal collection. Passes input parameters through
+    # to Hoodoo::Errors#add_error, so see that for details. For convenience,
+    # returns the for-rack representation of the response so far, so that code
+    # which wishes to add one error and abort request processing immediately
+    # can just do:
+    #
+    #     return response_object.add_error( ... )
+    #
+    # ...as part of processing a Rack invocation of the +call+ method. This is
+    # really only useful for the service middleware.
+    #
+    # +code+::    Error code (e.g. "platform.generic").
+    # +options+:: Options Hash - see Hoodoo::Errors#add_error.
+    #
+    # Example:
+    #
+    #     response.add_error(
+    #       'generic.not_found',
+    #       'message' => 'Optional custom message',
+    #       'reference' => { :ident => 'mandatory reference data' }
+    #     )
+    #
+    # In the above example, the mandatory reference data +uuid+ comes
+    # from the description for the 'platform.not_found' message - see the
+    # Hoodoo::ErrorDescriptions#initialize _implementation_ and Platform API.
+    #
+    def add_error( code, options = nil )
+      @errors.add_error( code, options )
+      return for_rack()
+    end
+
+    # Add a precompiled error to the error collection. Pass error code,
+    # error message and reference data directly.
+    #
+    # In most cases you should be calling #add_error instead, *NOT* here.
+    #
+    # *No* *validation* is performed. You should only really call here if
+    # storing an error / errors from another, trusted source with assumed
+    # validity (e.g. another service called remotely with errors in the JSON
+    # response). It's possible to store invalid error data using this call,
+    # which means counter-to-documentation results could be returned to API
+    # clients. That is Very Bad.
+    #
+    # Pass optionally the HTTP status code to use if this happens to be the
+    # first stored error. If this is omitted, 500 is kept as the default.
+    #
+    # As with #add_error, returns a Rack representation of the response.
+    #
+    def add_precompiled_error( code, message, reference, http_status = 500 )
+      @errors.add_precompiled_error( code, message, reference, http_status )
+      return for_rack()
+    end
+
+    # Add errors from a Hoodoo::Errors instance to this response's error
+    # collection.
+    #
+    # +errors_object+:: Hoodoo::Errors instance to merge into the error
+    #                   collection of 'this' response object.
+    #
+    # Returns +true+ if errors were merged, else +false+ (the source
+    # collection was empty).
+    #
+    def add_errors( errors_object )
+      return @errors.merge!( errors_object )
+    end
+
+    # Set the standard not found error message (generic.not_found), to
+    # be used durning a 'show' call when the requested resource does not
+    # exist.
+    #
+    # +ident+::  The identifier of the resource which was not found
+    #
+    # Example:
+    #
+    #      return response.not_found( ident ) if resource.nil?
+    #
+    def not_found( ident )
+      @errors.add_error( 'generic.not_found', :reference => { :ident => ident } )
+    end
+
+    # Convert the internal response data into something that Rack expects.
+    # The return value of this method can be passed back to Rack from Rack
+    # middleware or applications. Usually, this is only called directly by
+    # Hoodoo::Services::Middleware.
+    #
+    def for_rack
+
+      rack_response = Rack::Response.new
+
+      # Work out the status code and basic response body
+
+      if @errors.has_errors?
+        http_status_code = @errors.http_status_code
+        body_data        = @errors.render( @interaction_id )
+      else
+        http_status_code = @http_status_code
+        body_data        = @body
+      end
+
+      rack_response.status = http_status_code.to_i
+
+      # We're not using JSON5, so the Platform API says that outmost arrays
+      # are wrapped with a top-level object key "_data".
+
+      if body_data.is_a?( ::Array )
+        response_hash = { '_data' => body_data }
+        response_hash[ '_dataset_size' ] = @dataset_size unless @dataset_size.nil?
+        response_string = ::JSON.generate( response_hash )
+      elsif body_data.is_a?( ::Hash )
+        response_string = ::JSON.generate( body_data )
+      elsif body_data.is_a?( ::String )
+        response_string = body_data
+      else
+        raise "Hoodoo::Services::Response\#for_rack given unrecognised body data class '#{ body_data.class.name }'"
+      end
+
+      rack_response.write( response_string )
+
+      # Finally, sort out the headers
+
+      headers().each do | header_name, header_value |
+        rack_response[ header_name ] = header_value
+      end
+
+      # Return the complete response
+
+      return rack_response.finish
+    end
+  end
+
+end; end