hoodoo 1.0.2

data/lib/hoodoo/errors.rb

@@ -0,0 +1,19 @@
+########################################################################
+# File::    errors.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Include error management classes and data definitions.
+# ----------------------------------------------------------------------
+#           26-Jan-2015 (ADH): Split from top-level inclusion file.
+########################################################################
+
+# Dependencies
+
+require 'hoodoo/utilities'
+require 'hoodoo/presenters'
+require 'hoodoo/data'
+
+# Error management
+
+require 'hoodoo/errors/error_descriptions'
+require 'hoodoo/errors/errors'

data/lib/hoodoo/errors/error_descriptions.rb

@@ -0,0 +1,229 @@
+########################################################################
+# File::    error_descriptions.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Error descriptions - provide a DSL and a container for a
+#           list of known error codes and associated data. Defines a
+#           platform API's +platform+ and +generic+ domain codes by
+#           default. Services can declare additional errors.
+# ----------------------------------------------------------------------
+#           22-Sep-2014 (ADH): Created.
+#           09-Oct-2014 (ADH): Updated for Preview Release 8.
+#           16-Oct-2014 (TC):  Added session error
+########################################################################
+
+module Hoodoo
+
+  # A collection of error descriptions. API service implementations create one
+  # of these, which self-declares platform and generic error domain codes. A
+  # simple DSL is available to declare service-specific errors. Since the
+  # middleware is responsible for instantiating an error collection inside a
+  # response object which service implementations use to signal error
+  # conditions, the service's _interface_ class uses the interface description
+  # DSL to call through to here behind the scenes; for example:
+  #
+  #     class TransactionImplementation < Hoodoo::Services::Implementation
+  #       # ...
+  #     end
+  #
+  #     class TransactionInterface < Hoodoo::Services::Interface
+  #       interface :Transaction do
+  #         endpoint :transactions, TransactionImplementation
+  #         errors_for 'transaction' do
+  #           error 'duplicate_transaction', status: 409, message: 'Duplicate transaction', :required => [ :client_uid ]
+  #         end
+  #       end
+  #     end
+  #
+  # The #errors_for method takes the domain of the error as a string - the
+  # part that comes before the "+.+" in error codes. Then a series of +error+
+  # calls describe the individual error codes. See
+  # Hoodoo::ErrorDescriptions::DomainDescriptions#error for details.
+  #
+  # An instance of the Hoodoo::ErrorDescriptions class gets built behind
+  # the scenes as part of the service interface description. This is found by
+  # the middleware and passed to a Hoodoo::Errors constructor. The result
+  # is stored in a Hoodoo::Services::Response instance and passed to handler
+  # methods in the service's Hoodoo::Services::Implementation subclass for each
+  # request. Service implementations access the errors collection through
+  # Hoodoo::Services::Response#errors and can then add errors using the generic
+  # or platform domains, or whatever additional custom domain(s) they defined
+  # in the service interface subclass.
+  #
+  # For direct callers (e.g. the middleware), there is a shorthand form to
+  # invoke the DSL where the constructor is used in the same way as
+  # #errors_for:
+  #
+  #     ERROR_DESCRIPTIONS = Hoodoo::ErrorDescriptions.new( 'transaction' ) do
+  #       error 'duplicate_transaction', status: 409, message: 'Duplicate transaction', :required => [ :client_uid ]
+  #     end
+  #
+  # Either way,
+  #
+  # As per the example above, services can share an instance across requests
+  # (and threads) via a class's variable if the descriptions don't change. You
+  # would use the descriptions to inform a Hoodoo::Errors instance of the
+  # available codes and their requirements:
+  #
+  #    @errors = Hoodoo::Errors.new( ERROR_DESCRIPTIONS )
+  #
+  class ErrorDescriptions
+
+    # Create an instance, self-declaring +platform+ and +generic+ domain
+    # errors. You can optionally call the constructor with an error domain
+    # and code block, to declare errors all in one go rather than making a
+    # separate call to #errors_for (but both approaches are valid).
+    #
+    # +domain+:: Optional domain, just as used in #errors_for
+    # &block:: Optional block, just as used in #errors_for
+    #
+    def initialize( domain = nil, &block )
+
+      @descriptions = {}
+
+      # Up to date at Preview Release 9, 2014-11-10.
+
+      errors_for 'platform' do
+        error 'not_found',              status: 404, message: 'Not found',                    reference: [ :entity_name ]
+        error 'malformed',              status: 422, message: 'Malformed request'
+        error 'invalid_session',        status: 401, message: 'Invalid session'
+        error 'forbidden',              status: 403, message: 'Action not authorized'
+        error 'method_not_allowed',     status: 405, message: 'Method not allowed'
+        error 'timeout',                status: 408, message: 'Request timeout'
+        error 'fault',                  status: 500, message: 'Internal error',               reference: [ :exception ]
+      end
+
+      # Up to date at Preview Release 9, 2014-11-10.
+
+      errors_for 'generic' do
+        error 'not_found',              status: 404, message: 'Resource not found',            reference: [ :ident ]
+        error 'malformed',              status: 422, message: 'Malformed payload'
+        error 'required_field_missing', status: 422, message: 'Required field missing',        reference: [ :field_name ]
+        error 'invalid_string',         status: 422, message: 'Invalid string format',         reference: [ :field_name ]
+        error 'invalid_integer',        status: 422, message: 'Invalid integer format',        reference: [ :field_name ]
+        error 'invalid_float',          status: 422, message: 'Invalid float format',          reference: [ :field_name ]
+        error 'invalid_decimal',        status: 422, message: 'Invalid decimal format',        reference: [ :field_name ]
+        error 'invalid_boolean',        status: 422, message: 'Invalid boolean format',        reference: [ :field_name ]
+        error 'invalid_enum',           status: 422, message: 'Invalid enumeration',           reference: [ :field_name ]
+        error 'invalid_date',           status: 422, message: 'Invalid date specifier',        reference: [ :field_name ]
+        error 'invalid_time',           status: 422, message: 'Invalid time specifier',        reference: [ :field_name ]
+        error 'invalid_datetime',       status: 422, message: 'Invalid date-time specifier',   reference: [ :field_name ]
+        error 'invalid_uuid',           status: 422, message: 'Invalid UUID',                  reference: [ :field_name ]
+        error 'invalid_array',          status: 422, message: 'Invalid array',                 reference: [ :field_name ]
+        error 'invalid_object',         status: 422, message: 'Invalid object',                reference: [ :field_name ]
+        error 'invalid_hash',           status: 422, message: 'Invalid hash',                  reference: [ :field_name ]
+        error 'invalid_duplication',    status: 422, message: 'Duplicates not allowed',        reference: [ :field_name ]
+        error 'invalid_state',          status: 422, message: 'State transition not allowed',  reference: [ :destination_state ]
+        error 'invalid_parameters',     status: 422, message: 'Invalid parameters'
+        error 'mutually_exclusive',     status: 422, message: 'Mutually exclusive parameters', reference: [ :field_names ]
+      end
+
+      # Add caller's custom errors for the shorthand form, if provided.
+
+      if ( domain != nil && domain != '' && block_given?() )
+        errors_for( domain, &block )
+      end
+    end
+
+    # Implement the collection's part of the small DSL used for error
+    # declaration. Call here, passing the error domain (usually the singular
+    # service name or resource name, e.g. "+transaction+" and defined by the
+    # part of the platform API the service is implementing) and a block. The
+    # block makes one or more "+error+" calls, which actually end up calling
+    # Hoodoo::ErrorDescriptions::DomainDescriptions#error behind the scenes.
+    #
+    # See the implementation of #initialize for a worked example.
+    #
+    # +domain+:: Error domain, e.g. +platform+, +transaction+
+    # &block:: Block which makes one or more calls to "+error+"
+    #
+    def errors_for( domain, &block )
+      domain_descriptions = Hoodoo::ErrorDescriptions::DomainDescriptions.new( domain )
+      domain_descriptions.instance_eval( &block )
+
+      @descriptions.merge!( domain_descriptions.descriptions )
+    end
+
+    # Is the given error code recognised? Returns +true+ if so, else +false+.
+    #
+    # +code+:: Error code in full, e.g. +generic.invalid_state'.
+    #
+    def recognised?( code )
+      @descriptions.has_key?( code )
+    end
+
+    # Return the options description hash, as passed to +error+ calls in the
+    # block given to #errors_for, for the given code.
+    #
+    # +code+:: Error code in full, e.g. +generic.invalid_state'.
+    #
+    def describe( code )
+      @descriptions[ code ]
+    end
+
+    # Contain a description of errors for a particular domain, where the domain
+    # is a grouping string such as "platform", "generic", or a short service
+    # name. Usually driven via Hoodoo::ErrorDescriptions, not directly.
+    #
+    class DomainDescriptions
+
+      # Domain name for this description instance (string).
+      #
+      attr_reader( :domain )
+
+      # Hash of all descriptions, keyed by full error code, with options
+      # hash data as values (see #error for details).
+      #
+      attr_reader( :descriptions )
+
+      # Initialize a new instance for the given domain.
+      #
+      # +domain+:: The domain string - for most service-based callers, usually
+      #            a short service name like +members+ or +transactions+.
+      #
+      def initialize( domain )
+        @domain       = domain
+        @descriptions = {}
+      end
+
+      # Describe an error.
+      #
+      # +name+::    The error name - the bit after the "+.+" in the code, e.g.
+      #             +invalid_parameters+.
+      #
+      # +options+:: Options hash. See below.
+      #
+      # The options hash contains symbol keys named as follows, with values as
+      # described:
+      #
+      # +:status+::   The integer or string HTTP status code to be associated
+      #               with this error
+      #
+      # +message+::   The +en-nz+ language human-readable error message used
+      #               for developers.
+      #
+      # +reference+:: Optional array of required named references. When errors
+      #               are added (via Hoodoo::Errors#add_error) to a
+      #               collection, required reference(s) from this array must
+      #               be provided by the error-adding caller else an exception
+      #               will be raised. This ensures correct, fully qualified
+      #               error data is logged and sent to clients.
+      #
+      def error( name, options )
+        options       = Hoodoo::Utilities.stringify( options )
+        required_keys = [ 'status', 'message' ]
+
+        reference              = options[ 'reference' ]
+        options[ 'reference' ] = reference.map( &:to_s ) if reference.is_a?( ::Array )
+
+        required_keys.each do | required_key |
+          unless options.has_key?( required_key )
+            raise "Error description options hash missing required key '#{ required_key }'"
+          end
+        end
+
+        @descriptions[ "#{ @domain }.#{ name }" ] = options
+      end
+    end
+  end
+end

data/lib/hoodoo/errors/errors.rb

@@ -0,0 +1,322 @@
+########################################################################
+# File::    errors.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: A collection of error messages, starting empty, with one
+#           or more messages added to it as errors are encountered by
+#           some processing task. Errors are added according to codes
+#           described by Hoodoo::ErrorDescriptions instances.
+# ----------------------------------------------------------------------
+#           22-Sep-2014 (ADH): Created.
+########################################################################
+
+module Hoodoo
+
+  # During request processing, API service implementations create an
+  # Hoodoo::Errors instance and add error(s) to the collection as they arise
+  # using #add_error. That same instance can then be returned for the on-error
+  # handling path of whatever wider service framework is in use by the service
+  # code in question. Services should use new instances for each request.
+  #
+  class Errors
+
+    # Custom exception thrown when an unknown error code is added to a
+    # collection.
+    #
+    class UnknownCode < RuntimeError
+    end
+
+    # Custom exception thrown when an error is added to a collection without
+    # including required reference data
+    #
+    class MissingReferenceData < RuntimeError
+    end
+
+    # Default Hoodoo::ErrorDescriptions instance, used if the instantiator
+    # provides no alternative.
+    #
+    DEFAULT_ERROR_DESCRIPTIONS = Hoodoo::ErrorDescriptions.new()
+
+    # Errors are manifestations of the Errors resource. They acquire a UUID
+    # when instantiated, even if the instance is never used or persisted.
+    #
+    attr_reader( :uuid )
+
+    # Array of error data - hashes with +code+, +message+ and +reference+
+    # fields giving the error codes, human-readable messages and
+    # machine-readable reference data, where appropriate.
+    #
+    attr_reader( :errors )
+
+    # HTTP status code associated with the first error in the #errors array,
+    # _as an Integer_.
+    #
+    attr_reader( :http_status_code )
+
+    # The Hoodoo::ErrorDescriptions instance associated with this error
+    # collection. Only error codes that the instance's
+    # Hoodoo::ErrorDescriptions#recognised? method says are recognised
+    # can be added to the error collection, else
+    # Hoodoo::Errors::UnknownCode will be raised.
+    #
+    attr_reader( :descriptions )
+
+    # Create an instance.
+    #
+    # +descriptions+:: (Optional) Hoodoo::ErrorDescriptions instance with
+    #                  service-domain-specific error descriptions added, or
+    #                  omit for a default instance describing +platform+ and
+    #                  +generic+ error domains only.
+    #
+    def initialize( descriptions = DEFAULT_ERROR_DESCRIPTIONS )
+      @uuid             = Hoodoo::UUID.generate()
+      @descriptions     = descriptions
+      @errors           = []
+      @http_status_code = 200
+      @created_at       = nil # See #persist!
+    end
+
+    # Add an error instance to this collection.
+    #
+    # +code+::      Error code in full, e.g. +generic.invalid_state'.
+    #
+    # +options+::   An options Hash, optional.
+    #
+    # The options hash contains symbol keys named as follows, with values as
+    # described:
+    #
+    # +reference+:: Reference data Hash, optionality depending upon the error
+    #               code and the reference data its error description mandates.
+    #               Provide key/value pairs where (symbol) keys are names from
+    #               the array of description requirements and values are
+    #               strings. All values are concatenated into a single string,
+    #               comma-separated. Commas within values are escaped with a
+    #               backslash; backslash is itself escaped with a backslash.
+    #
+    #               You must provide that data at a minimum, but can provide
+    #               additional keys too if you so wish. Required keys are
+    #               always included first, in order of appearance in the
+    #               requirements array of the error declaration, followed by
+    #               any extra values in undefined order.
+    #
+    #               See also Hoodoo::ErrorDescriptions::DomainDescriptions#error
+    #
+    # +message+::   Optional human-readable for-developer message, +en-nz+
+    #               locale. Default messages are provided for all errors, but
+    #               if you think you can provide something more informative,
+    #               you can do so through this parameter.
+    #
+    # Example:
+    #
+    #     errors.add_error(
+    #       'platform.not_found',
+    #       :message => 'Optional custom message',
+    #       :reference => { :entity_name => 'mandatory reference data' }
+    #     )
+    #
+    # In the above example, the mandatory reference data +entity_name+ 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 )
+
+      options   = Hoodoo::Utilities.stringify( options || {} )
+      reference = options[ 'reference' ] || {}
+      message   = options[ 'message' ]
+
+      # Make sure nobody uses an undeclared error code.
+
+      raise UnknownCode, "In \#add_error: Unknown error code '#{code}'" unless @descriptions.recognised?( code )
+
+      # If the error description specifies a list of required reference keys,
+      # make sure all are present and complain if not.
+
+      description = @descriptions.describe( code )
+
+      required_keys = description[ 'reference' ] || []
+      actual_keys   = reference.keys
+      missing_keys  = required_keys - actual_keys
+
+      unless missing_keys.empty?
+        raise MissingReferenceData, "In \#add_error: Reference hash missing required keys: '#{ missing_keys.join( ', ' ) }'"
+      end
+
+      # All good!
+
+      @http_status_code = ( description[ 'status' ] || 200 ).to_i if @errors.empty? # Use first in collection for overall HTTP status code
+
+      error = {
+        'code'    => code,
+        'message' => message || description[ 'message' ] || code
+      }
+
+      ordered_keys   = required_keys + ( actual_keys - required_keys )
+      ordered_values = ordered_keys.map { | key | escape_commas( reference[ key ].to_s ) }
+
+      # See #unjoin_and_unescape_commas to undo the join below.
+
+      error[ 'reference' ] = ordered_values.join( ',' ) unless ordered_values.empty?
+
+      @errors << error
+    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.
+    #
+    def add_precompiled_error( code, message, reference, http_status = 500 )
+      @http_status_code = http_status.to_i if @errors.empty?
+
+      error = {
+        'code'    => code,
+        'message' => message
+      }
+
+      error[ 'reference' ] = reference unless reference.nil? || reference.empty?
+
+      @errors << error
+    end
+
+    # Merge the contents of a source error object with this one, adding its
+    # errors to this collection. No checks are made for duplicates (in part
+    # because, depending on error code and source/target contexts, a
+    # duplicate may be a valid thing to have).
+    #
+    # +source+:: Hoodoo::Errors instance to merge into the error collection
+    #            of 'this' target object.
+    #
+    # Returns +true+ if errors were merged, else +false+ (the source
+    # collection was empty).
+    #
+    def merge!( source )
+      source_errors = source.errors
+
+      source_errors.each do | hash |
+        add_precompiled_error(
+          hash[ 'code'      ],
+          hash[ 'message'   ],
+          hash[ 'reference' ],
+          source.http_status_code
+        )
+      end
+
+      return ! source_errors.empty?
+    end
+
+    # Does this instance have any errors added? Returns +true+ if so,
+    # else +false+.
+    #
+    def has_errors?
+      ! @errors.empty?
+    end
+
+    # Clear (delete) all previously added errors (if any). After calling here,
+    # #has_errors? would always return +false+.
+    #
+    def clear_errors
+      @errors           = []
+      @http_status_code = 200
+    end
+
+    # Return a Hash rendered through the Hoodoo::Data::Resources::Errors
+    # collection representing the formalised resource.
+    #
+    # +interaction_id+:: Mandatory Interaction ID (UUID) to associate with
+    #                    the collection.
+    #
+    def render( interaction_id )
+      unless Hoodoo::UUID.valid?( interaction_id )
+        raise "Hoodoo::Errors\#render must be given a valid Interaction ID (got '#{ interaction_id.inspect }')"
+      end
+
+      @created_at ||= Time.now
+
+      Hoodoo::Data::Resources::Errors.render(
+        {
+          'interaction_id' => interaction_id,
+          'errors'         => @errors
+        },
+        @uuid,
+        @created_at
+      )
+    end
+
+    # Make life easier for debugging on the console by having the object
+    # represent itself more concisely.
+    #
+    def inspect
+      @errors.to_s
+    end
+
+
+    # DEVELOPER: In the function comment below, RDoc escaping has to be done
+    # for RDocs to make sense. Read every "\\" as a single "\" (or read the
+    # generated docs instead of reading the source code comment below).
+
+
+    # When reference data is specified for errors, the reference values are
+    # concatenated together into a comma-separated string. Since reference
+    # values can themselves contain commas, comma is escaped with "\\," and
+    # "\\" escaped with "\\\\".
+    #
+    # Call here with such a string; return an array of 'unescaped' values.
+    #
+    # +str+:: Value-escaped ("\\\\" / "\\,") comma-separated string. Unescaped
+    #         commas separate individual values.
+    #
+    def unjoin_and_unescape_commas( str )
+
+      # In Ruby regular expressions, '(?<!pat)' is a negative lookbehind
+      # assertion, making sure that the preceding characters do not match
+      # 'pat'. To split the string joined on ',' to an array but not splitting
+      # any escaped '\,', then, we can use this rather opaque split regexp:
+      #
+      #   error[ 'reference' ].split( /(?<!\\),/ )
+      #
+      # I.e. split on ',', provided it is not preceded by a '\' (escaped in the
+      # regexp to '\\').
+
+      ary = str.split( /(?<!\\),/ )
+      ary.map { | entry | unescape_commas( entry ) }
+    end
+
+  private
+
+
+    # DEVELOPER: In the function comment below, RDoc escaping has to be done
+    # for RDocs to make sense. Read every "\\" as a single "\" (or read the
+    # generated docs instead of reading the source code comment below).
+
+
+    # Given a string, escape "," to "\\," and "\\" to "\\\\", returning the result.
+    #
+    # +str+:: String to escape.
+    #
+    def escape_commas( str )
+      # "\" in replacement strings gets evaluated twice, once for string
+      # literals (leaving '\\\\') then again for regexp group references like
+      # "\1" work (thus leaving '\\').
+      #
+      str.gsub( "\\", "\\\\\\\\" ).gsub( ",", "\\," )
+    end
+
+    # Given a string escaped via #escape_commas, unescape it.
+    #
+    # +str+:: String to escape.
+    #
+    def unescape_commas( str )
+      str.gsub( "\\,", "," ).gsub( "\\\\", "\\\\" )
+    end
+  end
+end