Hoodoo::Services::Response

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.

Methods

A

add_error,
add_errors,
add_header,
add_precompiled_error

C

contemporary_exists

F

for_rack

G

get_header

H

halt_processing?,
headers

N

new,
not_found

S

set_estimated_resources,
set_resources

Attributes

[RW]	body	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`.
[R]	dataset_size	Read back a 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). If the dataset size is absent, an estimation may be present; see estimated_dataset_size.
[RW]	errors	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.
[R]	estimated_dataset_size	Read back an estimated 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 a dataset size estimation was not supplied).
[RW]	http_status_code	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.
[RW]	set_resource	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`.

Class Public methods

new( interaction_id ) Link

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.

Source: show

# File lib/hoodoo/services/services/response.rb, line 95
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
  @estimated_dataset_size = nil

end

Instance Public methods

add_error( code, options = nil ) Link

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.

Source: show

# File lib/hoodoo/services/services/response.rb, line 262
def add_error( code, options = nil )
  @errors.add_error( code, options )
  return for_rack()
end

add_errors( errors_object ) Link

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).

Source: show

# File lib/hoodoo/services/services/response.rb, line 298
def add_errors( errors_object )
  return @errors.merge!( errors_object )
end

add_header( name, value, overwrite = false ) Link

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.

Source: show

# File lib/hoodoo/services/services/response.rb, line 201
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

add_precompiled_error( code, message, reference, http_status = 500 ) Link

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.

Source: show

# File lib/hoodoo/services/services/response.rb, line 284
def add_precompiled_error( code, message, reference, http_status = 500 )
  @errors.add_precompiled_error( code, message, reference, http_status )
  return for_rack()
end

contemporary_exists( ident ) Link

Add the standard error message 'generic.contemporary_exists' to this response. Optionally used during a 'show' call for a historical dating-aware resource, when an instance does not exist at a requested historic date/time, but a contemporary version is present.

ident: The identifier of the resource which was not found

Example for resource implementations with a context available:

resource = SomeModel.acquire_in( context )

if resource.nil?
  ident = context.request.ident
  context.response.not_found( ident )

  # You'd omit "#manually_dated_contemporary" if using automatic
  # dating (but manual dating is recommended over automatic for
  # performance reasons).
  #
  contemporary_resource = SomeModel.
                          scoped_undated_in( context ).
                          manually_dated_contemporary().
                          acquire( ident )

  # Use of ActiveRecord means some ActiveSupport extensions
  # such as "#present?" will be available.
  #
  context.response.contemporary_exists( ident ) if contemporary_resource.present?
end

An even higher level approach through context, through which this method is called automatically:

resource = SomeModel.acquire_in!( context )
return if context.response.halt_processing?

This frees application authors of the burden of constructing an appropriately secure and “now-dated” scope for the contemporary resource lookup.

See also:

Source: show

# File lib/hoodoo/services/services/response.rb, line 373
def contemporary_exists( ident )
  @errors.add_error( 'generic.contemporary_exists', :reference => { :ident => ident } )
end

for_rack() Link

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.

Source: show

# File lib/hoodoo/services/services/response.rb, line 382
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_hash[ '_estimated_dataset_size' ] = @estimated_dataset_size unless @estimated_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

get_header( name ) Link

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”).

Source: show

# File lib/hoodoo/services/services/response.rb, line 222
def get_header( name )
  value_hash = @headers[ name.downcase ]
  return nil if value_hash.nil?
  return value_hash.values[ 0 ]
end

halt_processing?() Link

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).

Source: show

# File lib/hoodoo/services/services/response.rb, line 116
def halt_processing?
  @errors.has_errors?
end

headers() Link

Returns the list previously set headers in a name: value Hash.

Source: show

# File lib/hoodoo/services/services/response.rb, line 230
def headers
  @headers.inject( {} ) do | result, kv_array |
    result.merge( kv_array[ 1 ] )
  end
end

not_found( ident ) Link

Add the standard error message 'generic.not_found' to this response. Used during a 'show' call when the requested resource does not exist.

ident: The identifier of the resource which was not found

Low level example:

return response.not_found( ident ) if resource.nil?

High level example for resource implementations with a context available, through which this method is called automatically:

resource = SomeModel.acquire_in!( context )
return if context.response.halt_processing?

Class Hoodoo::Services::Response < Object