hoodoo 1.0.2

data/lib/hoodoo/client/endpoint/endpoints/auto_session.rb

@@ -0,0 +1,194 @@
+########################################################################
+# File::    auto_session.rb
+# (C)::     Loyalty New Zealand 2015
+#
+# Purpose:: Resource endpoint definition.
+# ----------------------------------------------------------------------
+#           12-Mar-2015 (ADH): Created.
+########################################################################
+
+module Hoodoo
+  class Client     # Just used as a namespace here
+    class Endpoint # Just used as a namespace here
+
+      # This endpoint wraps something which does _actual_ communication but
+      # requires a session; it maintains a valid session for that wrapped
+      # endpoint automatically. It implements the following model:
+      #
+      # - It requires a Caller ID and Caller Authentication Secret to be
+      #   instantiated (via the +options+ parameter).
+      #
+      # - If there is no session ID available, it creates one using the above
+      #   details. Otherwise, it tries to use the given session.
+      #
+      # - If a particular request leads to an 'invalid session' response, the
+      #   request is marked for retry. A new session is obtained first, the
+      #   retry happens and if it fails this time, the failure is returned to
+      #   the caller.
+      #
+      # Since it wraps another endpoint and requires Caller information to be
+      # able to build sessions, instantiation requirements are rather unusual
+      # - see #configure_with for details.
+      #
+      class AutoSession < Hoodoo::Client::Endpoint
+
+        protected
+
+          # See Hoodoo::Client::Endpoint#configure_with.
+          #
+          # Configuration option keys which _must_ be supplied are:
+          #
+          # +caller_id+::        The UUID of the Caller instance to be used
+          #                      for session creation.
+          #
+          # +caller_secret+::    The authentication secret of the Caller
+          #                      instance to be used for session creation.
+          #
+          # +session_endpoint::  A Hooodo::Client::Endpoint subclass which
+          #                      can be used for talking to the Session
+          #                      endpoint (for obvious reasons!).
+          #
+          # +discovery_result+:: A Hoodoo::Services::Discovery::ForRemote
+          #                      instance describing the required, remotely
+          #                      available resource endpoint.
+          #
+          # The pattern for creating and using this instance is:
+          #
+          # * Discover the location of the remote resource.
+          #
+          # * Use the discovery result to build an appropriate Endpoint
+          #   subclass instance, e.g. Hoodoo::Client::Endpoint::HTTP.
+          #
+          # * Create a Hoodoo::Services::Discovery::ForRemote instance which
+          #   describes the above endpoint via the +wrapped_endpoint+ option.
+          #
+          # * Build an instance of this auto-session Endpoint subclass,
+          #   giving it the above object as the +discovery_result+.
+          #
+          # * Use this endpoint in the normal fashion. All the special
+          #   mechanics of session management are handled here.
+          #
+          def configure_with( resource, version, options )
+            @caller_id        = options[ :caller_id        ]
+            @caller_secret    = options[ :caller_secret    ]
+            @session_endpoint = options[ :session_endpoint ]
+            @wrapped_endpoint = @discovery_result.wrapped_endpoint
+          end
+
+        public
+
+          # See Hoodoo::Client::Endpoint#list.
+          #
+          def list( query_hash = nil )
+            return auto_retry( :list, query_hash )
+          end
+
+          # See Hoodoo::Client::Endpoint#show.
+          #
+          def show( ident, query_hash = nil )
+            return auto_retry( :show, ident, query_hash )
+          end
+
+          # See Hoodoo::Client::Endpoint#create.
+          #
+          def create( body_hash, query_hash = nil )
+            return auto_retry( :create, body_hash, query_hash )
+          end
+
+          # See Hoodoo::Client::Endpoint#update.
+          #
+          def update( ident, body_hash, query_hash = nil )
+            return auto_retry( :update, ident, body_hash, query_hash )
+          end
+
+          # See Hoodoo::Client::Endpoint#delete.
+          #
+          def delete( ident, query_hash = nil )
+            return auto_retry( :delete, ident, query_hash )
+          end
+
+        private
+
+          # Try to perform an action through the wrapped endpoint, acquiring a
+          # session first if need be or if necessary reacquiring a session and
+          # retrying the request.
+          #
+          # +action+:: The name of the method to call in the wrapped endpoint
+          #            - see Hoodoo::Services::Middleware::ALLOWED_ACTIONS.
+          #
+          # *args::    Any other arguments to pass to +action+.
+          #
+          def auto_retry( action, *args )
+
+            copy_updated_options_to( @wrapped_endpoint )
+
+            # We use the session endpoint as a session ID cache, in essence,
+            # storing the acquired ID there and passing it into the wrapped
+            # endpoint for the 'real' calls.
+
+            if @session_endpoint.session_id.nil?
+              session_creation_result = acquire_session_for( action )
+              return session_creation_result unless session_creation_result.nil?
+            else
+              @wrapped_endpoint.session_id = @session_endpoint.session_id
+            end
+
+            result = @wrapped_endpoint.send( action, *args )
+
+            if result.platform_errors.has_errors? &&
+               result.platform_errors.errors.size == 1 &&
+               result.platform_errors.errors[ 0 ][ 'code' ] == 'platform.invalid_session'
+
+              session_creation_result = acquire_session_for( action )
+              return session_creation_result unless session_creation_result.nil?
+              return @wrapped_endpoint.send( action, *args )
+            else
+              return result
+            end
+          end
+
+          # Acquire a sessino using the configured session endpoint. If this
+          # fails, the failure result is returned. If it seems to succeed but
+          # a session ID cannot be found, an internal 'generic.malformed'
+          # result is generated and returned.
+          #
+          # The returned data uses an appropriate response class for the
+          # action at hand - an augmented array for lists, else an augmented
+          # hash. It can be returned directly up to the calling layer.
+          #
+          # Returns +nil+ if all goes well; #session_id will be updated.
+          #
+          # +action+:: As given to #auto_retry.
+          #
+          def acquire_session_for( action )
+            session_creation_result = @session_endpoint.create(
+              'caller_id'             => @caller_id,
+              'authentication_secret' => @caller_secret
+            )
+
+            if session_creation_result.platform_errors.has_errors?
+              data = response_class_for( action ).new
+              data.platform_errors.merge!( session_creation_result.platform_errors )
+              return data
+            end
+
+            @session_endpoint.session_id = session_creation_result[ 'id' ]
+
+            if @session_endpoint.session_id.nil? || @session_endpoint.session_id.empty?
+              data = response_class_for( action ).new
+              data.platform_errors.add_error(
+                'generic.malformed',
+                'message' => 'Received bad session description from Session endpoint despite "200" response code'
+              )
+
+              return data
+            else
+              @wrapped_endpoint.session_id = @session_endpoint.session_id
+              return nil
+            end
+          end
+
+      end
+    end
+  end
+end

data/lib/hoodoo/client/endpoint/endpoints/http.rb

@@ -0,0 +1,203 @@
+########################################################################
+# File::    http.rb
+# (C)::     Loyalty New Zealand 2015
+#
+# Purpose:: Resource endpoint definition.
+# ----------------------------------------------------------------------
+#           05-Mar-2015 (ADH): Created.
+########################################################################
+
+require 'net/http'
+require 'net/https'
+
+module Hoodoo
+  class Client     # Just used as a namespace here
+    class Endpoint # Just used as a namespace here
+
+      # Talk to a resource that is contacted over HTTP or HTTPS.
+      #
+      # Configured with a Hoodoo::Services::Discovery::ForHTTP discovery
+      # result instance.
+      #
+      class HTTP < Hoodoo::Client::Endpoint::HTTPBased
+
+        protected
+
+          # See Hoodoo::Client::Endpoint#configure_with.
+          #
+          # Requires a Hoodoo::Services::Discovery::ForHTTP instance in the
+          # +discovery_result+ field of the +options+ Hash.
+          #
+          def configure_with( resource, version, options )
+            unless @discovery_result.is_a?( Hoodoo::Services::Discovery::ForHTTP )
+              raise "Hoodoo::Client::Endpoint::HTTP must be configured with a Hoodoo::Services::Discovery::ForHTTP instance - got '#{ @discovery_result.class.name }'"
+            end
+
+            @description                  = Hoodoo::Client::Endpoint::HTTPBased::DescriptionOfRequest.new
+            @description.discovery_result = @discovery_result
+            @description.endpoint_uri     = @discovery_result.endpoint_uri
+            @description.proxy_uri        = @discovery_result.proxy_uri
+            @description.ca_file          = @discovery_result.ca_file
+            @description.http_timeout     = @discovery_result.http_timeout
+          end
+
+        public
+
+          # See Hoodoo::Client::Endpoint#list.
+          #
+          def list( query_hash = nil )
+            d            = @description.dup # This does NOT dup the objects to which @description points
+            d.action     = :list
+            d.query_hash = query_hash
+
+            return do_http( d )
+          end
+
+          # See Hoodoo::Client::Endpoint#show.
+          #
+          def show( ident, query_hash = nil )
+            d            = @description.dup
+            d.action     = :show
+            d.ident      = ident
+            d.query_hash = query_hash
+
+            return do_http( d )
+          end
+
+          # See Hoodoo::Client::Endpoint#create.
+          #
+          def create( body_hash, query_hash = nil )
+            d            = @description.dup
+            d.action     = :create
+            d.body_hash  = body_hash
+            d.query_hash = query_hash
+
+            return do_http( d )
+          end
+
+          # See Hoodoo::Client::Endpoint#update.
+          #
+          def update( ident, body_hash, query_hash = nil )
+            d            = @description.dup
+            d.action     = :update
+            d.ident      = ident
+            d.body_hash  = body_hash
+            d.query_hash = query_hash
+
+            return do_http( d )
+          end
+
+          # See Hoodoo::Client::Endpoint#delete.
+          #
+          def delete( ident, query_hash = nil )
+            d            = @description.dup
+            d.action     = :delete
+            d.ident      = ident
+            d.query_hash = query_hash
+
+            return do_http( d )
+          end
+
+        private
+
+          # Make real HTTP(S) request to a target resource and return the
+          # result as a Hoodoo::Client::AugmentedArray (for 'list' calls) or
+          # Hoodoo::Client::AugumentedHash (for all other calls) instance.
+          #
+          # +description_of_request+:: A Hoodoo::Client::Endpoint::HTTPBased::DescriptionOfRequest
+          #                            instance with all the request details
+          #                            set inside. The +discovery_data+ field
+          #                            must refer to a
+          #                            Hoodoo::Services::Discovery::ForHTTP
+          #                            instance (not re-checked internally).
+          #
+          def do_http( description_of_request )
+
+            data = get_data_for_request( description_of_request )
+
+            action       = description_of_request.action
+            proxy        = description_of_request.proxy_uri
+            ca_file      = description_of_request.ca_file
+            http_timeout = description_of_request.http_timeout
+
+            proxy_host = :ENV
+            proxy_port = proxy_user = proxy_pass = nil
+
+            unless proxy.nil?
+              proxy_host = proxy.host
+              proxy_port = proxy.port
+              proxy_user = proxy.user
+              proxy_pass = proxy.password
+            end
+
+            http = Net::HTTP.new(
+              data.full_uri.host,
+              data.full_uri.port,
+              proxy_host,
+              proxy_port,
+              proxy_user,
+              proxy_pass
+            )
+
+            if data.full_uri.scheme == 'https'
+              http.use_ssl = true
+
+              # The verify_mode is *important* - VERIFY_PEER ensures that we always validate
+              # the connection, *and* that the presented SSL Certificate by the endpoint is
+              # verifiable through our CA certificate trust store.
+              #
+              # To use a self-signed cert, you may configure the ca_file to a CA that
+              # includes the self-signed cert, but the verify_mode setting should remain.
+              #
+              http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+
+              if ca_file
+                http.ca_file = ca_file
+              end
+            end
+
+            http.read_timeout = http_timeout unless http_timeout.nil?
+
+            request_class = {
+              :create => Net::HTTP::Post,
+              :update => Net::HTTP::Patch,
+              :delete => Net::HTTP::Delete
+            }[ action ] || Net::HTTP::Get
+
+            request      = request_class.new( data.full_uri.request_uri() )
+            request.body = data.body_string unless data.body_string.empty?
+
+            request.initialize_http_header( data.header_hash )
+
+            description_of_response              = DescriptionOfResponse.new
+            description_of_response.action       = action
+            description_of_response.http_headers = {}
+
+            begin
+              http_response = http.request( request )
+
+              description_of_response.http_status_code = http_response.code.to_i
+              description_of_response.http_headers     = http_response
+              description_of_response.raw_body_data    = http_response.body
+
+            rescue Errno::ECONNREFUSED => e
+              description_of_response.http_status_code = 404
+              description_of_response.raw_body_data    = ''
+
+            rescue Net::ReadTimeout => e
+              description_of_response.http_status_code = 408
+              description_of_response.raw_body_data    = ''
+
+            rescue => e
+              description_of_response.http_status_code = 500
+              description_of_response.raw_body_data    = e.message
+
+            end
+
+            return get_data_for_response( description_of_response )
+          end
+
+      end
+    end
+  end
+end

data/lib/hoodoo/client/endpoint/endpoints/http_based.rb

@@ -0,0 +1,367 @@
+########################################################################
+# File::    http_based.rb
+# (C)::     Loyalty New Zealand 2015
+#
+# Purpose:: Resource endpoint definition.
+# ----------------------------------------------------------------------
+#           05-Mar-2015 (ADH): Created.
+########################################################################
+
+require 'json'
+
+module Hoodoo
+  class Client     # Just used as a namespace here
+    class Endpoint # Just used as a namespace here
+
+      # Base class for endpoints that have an HTTP basis to their request
+      # and responses, even if the underlying transport is not HTTP. This
+      # is basically a collection of library-like routines useful to such
+      # classes and specifically excludes the part which actually makes
+      # an HTTP call (or AMQP call, or whatever) to a resource. That's up
+      # to the subclass.
+      #
+      # This must never be instantiated directly as an endpoint. Instead,
+      # instantiate a subclass such as Hoodoo::Client::Endpoint::HTTP or
+      # Hoodoo::Client::Endpoint::AMQP.
+      #
+      class HTTPBased < Hoodoo::Client::Endpoint
+
+        protected
+
+          # Describe a request for HTTP-like endpoints.
+          #
+          class DescriptionOfRequest
+
+            # The action to perform - a Symbol from
+            # Hoodoo::Services::Middleware::ALLOWED_ACTIONS.
+            #
+            attr_accessor :action
+
+            # A Hoodoo::Services::Discovery "For..." family member instance
+            # giving information required to 'find' the target resource. The
+            # required class instance depends upon the endpoint in use.
+            #
+            attr_accessor :discovery_result
+
+            # The full HTTP URI (or equivalent HTTP URI for HTTP-like, but
+            # non-HTTP systems like AMQP) at which the endpoint is found.
+            # Excludes any query string or resource identifier portion (it
+            # is the "list" action URI without query data, in essence)
+            #
+            attr_accessor :endpoint_uri
+
+            # Full URI (as a URI object) of an HTTP proxy to use as an
+            # override to <tt>ENV['HTTP_PROXY']</tt> which Ruby itself
+            # will otherwise read. Will be +nil+ for no proxy override.
+            #
+            attr_accessor :proxy_uri
+
+            # An optional String indicating a relative or absolute file
+            # path to the location of a .pem format Certificate
+            # Authority file (trust store), which may include multliple
+            # certificates. The certificates in the file will be used
+            # by Net::HTTP to validate the SSL Ceritificate Chain
+            # presented by remote servers, when calling endpoints over
+            # HTTPS with Hoodoo::Client.
+            #
+            # Default +nil+ value should be used in nearly all cases
+            # and uses Ruby OpenSSL defaults which are generally
+            # Operating System provided.
+            #
+            attr_accessor :ca_file
+
+            # Optional Float indicating the Net::HTTP read timeout value.
+            # This operates at the HTTP transport level and is independent
+            # of any timeouts set within the API providing server.
+            #
+            attr_accessor :http_timeout
+
+            # Optional Hash of query data.
+            #
+            attr_accessor :query_hash
+
+            # Optional Hash of body data for actions +:create+ and +:update+.
+            #
+            attr_accessor :body_hash
+
+            # Optional resource identifier for actions +:show+, +:update+ and
+            # +:delete+:
+            #
+            attr_accessor :ident
+
+          end
+
+          # Description of data that will be used for request - essentially a
+          # compilation of a DescriptionOfRequest instance produced via a call
+          # to #get_data_for_request.
+          #
+          class DataForRequest
+
+            # The full HTTP URI (or equivalent HTTP URI for HTTP-like, but
+            # non-HTTP systems like AMQP) for the call, including any resource
+            # identifier and query data.
+            #
+            attr_accessor :full_uri
+
+            # String of compiled body data for all actions (may be empty).
+            #
+            attr_accessor :body_string
+
+            # Hash of headers; keys are HTTP header names as a Strings (e.g.
+            # "Content-Type", "X-Interaction-ID"), values are header values
+            # as Strings.
+            #
+            attr_accessor :header_hash
+
+            # Hash of query; keys are query keys as Strings (e.g.
+            # "search"), values are query values as URL encoded Strings. (e.g.
+            # "outlet_id%3Dd32a0e15754a486989fdde2b0830fe12")
+            #
+            attr_accessor :query_hash
+
+          end
+
+          # Description of data describing an HTTP response. Used by
+          # #get_data_for_response to generate a response array or hash
+          # (see #response_class_for).
+          #
+          class DescriptionOfResponse
+
+            # The action that was performed - a Symbol from
+            # Hoodoo::Services::Middleware::ALLOWED_ACTIONS.
+            #
+            attr_accessor :action
+
+            # The HTTP status code _as an Integer_.
+            #
+            attr_accessor :http_status_code
+
+            # The raw ("unparsed") returned body data as a String.
+            #
+            attr_accessor :raw_body_data
+
+            # An object that will allow Hash-like lookup and iteration of
+            # key/value pairs via +each+. A raw Net::HTTPOK (sic.) instance
+            # from a successful response is an example of such an object.
+            #
+            # May be unset (+nil+) or empty, especially for error cases.
+            #
+            attr_accessor :http_headers
+
+          end
+
+          # Preprocess a high level request description, returning HTTP
+          # orientated compiled data as a DataForRequest instance.
+          #
+          # +description_of_request+:: DescriptionOfRequest instance.
+          #
+          def get_data_for_request( description_of_request )
+            body_hash  = Hoodoo::Utilities.stringify( description_of_request.body_hash  )
+            query_hash = Hoodoo::Utilities.stringify( description_of_request.query_hash )
+            ident      = description_of_request.ident.to_s
+
+            body_data  = body_hash.nil? ? '' : ::JSON.generate( body_hash )
+
+            # Amazingly, there's no fast way to deep clone a URI. Long story
+            # short - Marshal.load(Marshal.dump(uri)) takes, astonishingly,
+            # twice as long to execute as URI.parse(uri.to_s). I have no idea
+            # how that's possible. The Addressable gem is even slower.
+            #
+            #   require 'benchmark'
+            #   require 'addressable/uri' # Assuming gem is present
+            #
+            #   s='http://user:password@pond.org.uk:9924/foo/bar.baz?thing=that'
+            #   u=URI.parse(s)
+            #   a=Addressable::URI.parse(s)
+            #
+            #   Benchmark.realtime { 1000000.times { u2=URI.parse(u.to_s) } }
+            #   # => 14.110195
+            #   Benchmark.realtime { 1000000.times { a2=a.dup } }
+            #   # => 26.530487
+            #   Benchmark.realtime { 1000000.times { u2=Marshal.load(Marshal.dump(u)) } }
+            #   # => 22.048637
+            #
+            # ...repeatably.
+            #
+            # TODO: Is it possible to improve this? It's truly awful, to the
+            #       extent I'm almost motivated to write a URI handler gem.
+            #       The core library URI API is tragically bad.
+
+            remote_uri = URI.parse( description_of_request.endpoint_uri.to_s )
+
+            # Now we've a copy, we can use high level URI methods to manipulate
+            # it to form the full request URI.
+
+            remote_uri.path << "/#{ URI::escape( ident ) }" unless ident.nil?
+
+            # Grey area over whether this encodes spaces as "%20" or "+", but
+            # so long as the middleware consistently uses the URI encode/decode
+            # calls, it should work out in the end anyway.
+
+            unless query_hash.nil?
+              query_hash = query_hash.dup
+              query_hash[ 'search' ] = URI.encode_www_form( query_hash[ 'search' ] ) if ( query_hash[ 'search' ].is_a?( ::Hash ) )
+              query_hash[ 'filter' ] = URI.encode_www_form( query_hash[ 'filter' ] ) if ( query_hash[ 'filter' ].is_a?( ::Hash ) )
+
+              query_hash[ '_embed'     ] = query_hash[ '_embed'     ].join( ',' ) if ( query_hash[ '_embed'     ].is_a?( ::Array ) )
+              query_hash[ '_reference' ] = query_hash[ '_reference' ].join( ',' ) if ( query_hash[ '_reference' ].is_a?( ::Array ) )
+
+              query_hash.delete( 'search'     ) if query_hash[ 'search'     ].nil? || query_hash[ 'search'     ].empty?
+              query_hash.delete( 'filter'     ) if query_hash[ 'filter'     ].nil? || query_hash[ 'filter'     ].empty?
+              query_hash.delete( '_embed'     ) if query_hash[ '_embed'     ].nil? || query_hash[ '_embed'     ].empty?
+              query_hash.delete( '_reference' ) if query_hash[ '_reference' ].nil? || query_hash[ '_reference' ].empty?
+            end
+
+            remote_uri.query = URI.encode_www_form( query_hash ) unless query_hash.nil? || query_hash.empty?
+
+            headers = {
+              'Content-Type'     => 'application/json; charset=utf-8',
+              'Content-Language' => self.locale() || 'en-nz', # Locale comes from Endpoint superclass
+              'Accept-Language'  => self.locale() || 'en-nz'
+            }
+
+            # Interaction comes from Endpoint superclass.
+            #
+            # TODO: Can anything be done about inbound X-Interaction-ID
+            #       headers or interaction ID values specified by the
+            #       calling client which would be stripped by an Alchemy
+            #       architecture but not by conventional HTTP servers?
+            #
+            unless self.interaction().nil?
+              headers[ 'X-Interaction-ID' ] = self.interaction().interaction_id
+            end
+
+            # Session ID comes from Endpoint superclass.
+            #
+            unless self.session_id().nil?
+              headers[ 'X-Session-ID'] = self.session_id()
+            end
+
+            # A suite of options is defined by a constant in the Endpoint
+            # superclass.
+            #
+            Hoodoo::Client::Headers::HEADER_TO_PROPERTY.each do | rack_header, description |
+              header_name = description[ :header      ]
+              header_proc = description[ :header_proc ]
+              property    = description[ :property    ]
+
+              property_value  = self.send( property )
+
+              unless property_value.nil?
+                headers[ header_name ] = header_proc.call( property_value )
+              end
+            end
+
+            data             = DataForRequest.new
+            data.full_uri    = remote_uri
+            data.body_string = body_data
+            data.header_hash = headers
+            data.query_hash  = query_hash
+
+            return data
+          end
+
+          # Process a raw HTTP response description, returning an instance of
+          # Hoodoo::Client::AugmentedArray or Hoodoo::Client::AugmentedHash
+          # with either processed body data inside, or error data associated.
+          #
+          # +description_of_response+:: DescriptionOfResponse instance.
+          #
+          def get_data_for_response( description_of_response )
+            code = description_of_response.http_status_code
+            body = description_of_response.raw_body_data
+
+            begin
+              parsed = ::JSON.parse(
+                body,
+                :object_class => Hoodoo::Client::AugmentedHash,
+                :array_class  => Hoodoo::Client::AugmentedArray
+              )
+
+            rescue => e
+              data = response_class_for( description_of_response.action ).new
+              data.response_options = Hoodoo::Client::Headers.x_header_to_options(
+                description_of_response.http_headers
+              )
+
+              case code
+                when 404
+                  return generate_404_response_for( description_of_response.action )
+                when 408
+                  data.platform_errors.add_error( 'platform.timeout' )
+                when 200
+                  data.platform_errors.add_error(
+                    'platform.fault',
+                    :message   => 'Could not parse body data returned from inter-resource call despite receiving HTTP status code 200',
+                    :reference => { :exception => RuntimeError.new( "#{ body }" ) }
+                  )
+                when 204
+                  if data.response_options[ 'deja_vu' ] != 'confirmed'
+                    data.platform_errors.add_error(
+                      'platform.fault',
+                      :message   => "Unexpected raw HTTP status code 204 with 'X-Deja-Vu: confirmed' not present",
+                      :reference => { :exception => RuntimeError.new( '204' ) }
+                    )
+                  end # Else do nothing; keep the empty 'data'
+                else
+                  data.platform_errors.add_error(
+                    'platform.fault',
+                    :message   => "Unexpected raw HTTP status code #{ code } with non-JSON response",
+                    :reference => { :exception => RuntimeError.new( "#{ body }" ) }
+                  )
+              end
+
+              return data
+            end
+
+            # Just in case someone changes JSON parsers under us and the
+            # replacement doesn't support the options used above...
+
+            unless parsed.is_a?( Hoodoo::Client::AugmentedHash )
+              raise "Hoodoo::Services::Middleware: Incompatible JSON implementation in use which doesn't understand 'object_class' or 'array_class' options"
+            end
+
+            # If the parsed data wrapped an array, extract just the array
+            # part, else the hash part.
+
+            if ( parsed[ '_data' ].is_a?( ::Array ) )
+              size   = parsed[ '_dataset_size' ]
+              parsed = parsed[ '_data'         ]
+              parsed.dataset_size = size
+
+            elsif ( parsed[ 'kind' ] == 'Errors' )
+
+              # This isn't an array, it's an AugmentedHash describing errors.
+              # Turn this into a formal errors collection.
+
+              errors_from_resource = Hoodoo::Errors.new()
+
+              parsed[ 'errors' ].each do | error |
+                errors_from_resource.add_precompiled_error(
+                  error[ 'code'      ],
+                  error[ 'message'   ],
+                  error[ 'reference' ],
+                  code
+                )
+              end
+
+              # Use a 'clean' copy of the response class rather than keeping
+              # the originating data. People will not make assumptions about
+              # error payloads and trip over with the early return 404 stuff
+              # etc. this way.
+
+              parsed = response_class_for( description_of_response.action ).new
+              parsed.set_platform_errors( errors_from_resource )
+
+            end
+
+            parsed.response_options = Hoodoo::Client::Headers.x_header_to_options(
+              description_of_response.http_headers
+            )
+
+            return parsed
+          end
+      end
+    end
+  end
+end