hoodoo 1.0.2

data/lib/hoodoo/services/middleware/rack_monkey_patch.rb

@@ -0,0 +1,73 @@
+########################################################################
+# File::    rack_monkey_patch.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Heyre Be Dragyns.
+#
+#           For local development, the service middleware needs to know
+#           where other resource endpoints are in terms of HTTP host and
+#           port, so that remote inter-resource calls can work without
+#           up-front static configuration of service host/port data. To
+#           have to manage a fixed list of local development ports in
+#           the face of arbitrary resource endpoint divisions would be a
+#           big pain and cause developers much frustration.
+#
+#           This means that whenever a service starts up, it needs to
+#           know the HTTP host and port under which it is running, then
+#           tell the middleware about it.
+#
+#           In the absence of a formal interface in Rack for this, then
+#           we could do still that relatively nicely by looking up the
+#           Rack server in ObjectSpace and asking it for its options -
+#           except some of the web server adapters do really dumb things
+#           like "options.delete(:Host)" to read items out, destroying
+#           the info we need.
+#
+#           So instead, we have to monkey patch :-(
+# ----------------------------------------------------------------------
+#           11-Nov-2014 (ADH): Split out from service_middleware.rb.
+########################################################################
+
+if defined?( Rack ) && defined?( Rack::Server )
+
+  # Part of the Rack monkey patch. See file
+  # "rack_monkey_path.rb"'s documentation for details.
+  #
+  module Rack
+
+    # Part of the Rack monkey patch. See file
+    # "rack_monkey_path.rb"'s documentation for details.
+    #
+    class Server
+
+      class << self
+
+        # Part of the Rack monkey patch. See file
+        # "rack_monkey_path.rb"'s documentation for details.
+        #
+        # This method is aliased in place of Rack::Server::start and reads
+        # the passed-in options hash to attempt to determine the host name
+        # and port number under which a Rack based service is running. It
+        # then calls through to Rack's original ::start implementation.
+        #
+        # +options+:: Options (see original Rack::Server documentation).
+        #
+        def start_and_record_host_and_port( options = nil )
+          Hoodoo::Services::Middleware.record_host_and_port( options )
+          racks_original_start( options )
+        end
+
+        # Part of the Rack monkey patch. Alias for the original
+        # Rack::Server::start.
+        #
+        alias racks_original_start start
+
+        # Part of the Rack monkey patch. See ::start_and_record_host_and_port.
+        #
+        # +options+:: See ::start_and_record_host_and_port.
+        #
+        alias start start_and_record_host_and_port
+      end
+    end
+  end
+end

data/lib/hoodoo/services/services/context.rb

@@ -0,0 +1,153 @@
+########################################################################
+# File::    context.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Container for information about the context of a call to
+#           a service, including session, request and response.
+# ----------------------------------------------------------------------
+#           03-Oct-2014 (ADH): Created.
+########################################################################
+
+module Hoodoo; module Services
+
+  # A collection of objects which describe the context in which a service is
+  # being called. The service reads session and request information and returns
+  # results of its processing via the associated response object.
+  #
+  class Context
+
+    public
+
+      # The Hoodoo::Services::Session instance describing the authorised call
+      # context. If a resource implementation is handling a public action this
+      # may be +nil+, else it will be a valid instance.
+      #
+      attr_reader :session
+
+      # The Hoodoo::Services::Request instance giving details about the
+      # inbound request. Relevant information will depend upon the endpoint
+      # service implementation action being addressed.
+      #
+      attr_reader :request
+
+      # The Hoodoo::Services::Response instance that a service implementation
+      # updates with results of its processing.
+      #
+      attr_reader :response
+
+      # The Hoodoo::Services::Middleware::Interaction instance for which this
+      # context exists (the 'owning' instance). Generally speaking this is
+      # only needed internally as part of the inter-resource call mechanism.
+      #
+      attr_reader :owning_interaction
+
+      # Create a new instance. There is almost certainly never any need to
+      # call this unless you're the Hoodoo::Services::Middleware::Interaction
+      # constructor! If you want to build a context for (say) test purposes,
+      # it's probably best to construct an interaction instance and use the
+      # context instance this provides.
+      #
+      # +session+:: See #session.
+      # +request+:: See #request.
+      # +response+:: See #response.
+      # +owning_interaction+:: See #interaction.
+      #
+      def initialize( session, request, response, owning_interaction )
+        @session            = session
+        @request            = request
+        @response           = response
+        @owning_interaction = owning_interaction
+      end
+
+      # Request (and lazy-initialize) a new resource endpoint instance for
+      # talking to a resource's interface. See Hoodoo::Client::Endpoint.
+      #
+      # You can request an endpoint for any resource name, whether or not an
+      # implementation actually exists for it. Until you try and talk to the
+      # interface through the endpoint instance, you won't know if it is
+      # there. All endpoint methods return instances of classes that mix in
+      # Hoodoo::Client::AugmentedBase; these
+      # mixin methods provide error handling options to detect a "not found"
+      # error (equivanent to HTTP status code 404) returned when a resource
+      # implementation turns out to not actually be present.
+      #
+      # The idiomatic call sequence is something like the following, where
+      # you get hold of an endpoint, make a call and handle the response:
+      #
+      #     clock = context.resource( :Clock, 2 ) # v2 of 'Clock' resource
+      #     time  = clock.show( 'now' )
+      #
+      #     return if time.adds_errors_to?( context.response.errors )
+      #
+      # ...or alternatively:
+      #
+      #     clock = context.resource( :Clock, 2 ) # v2 of 'Clock' resource
+      #     time  = clock.show( 'now' )
+      #
+      #     context.response.add_errors( time.platform_errors )
+      #     return if context.response.halt_processing?
+      #
+      # The return value of calls made to the endpoint is an Array or Hash
+      # that mixes in Hoodoo::Client::AugmentedBase;
+      # see this class's documentation for details of the two alternative
+      # error handling approaches shown above.
+      #
+      # +resource+:: Resource name for the endpoint, e.g. +:Purchase+. String
+      #              or symbol.
+      #
+      # +version+::  Optional required implemented version for the endpoint,
+      #              as an Integer - defaults to 1.
+      #
+      # +options+::  Optional options Hash (see below).
+      #
+      # The options Hash key/values are as follows:
+      #
+      # +locale+:: Locale string for request/response, e.g. "en-gb". Optional.
+      #            If omitted, defaults to the locale set in this Client
+      #            instance's constructor.
+      #
+      # Others::   See Hoodoo::Client::Headers' +HEADER_TO_PROPERTY+.
+      #            For any options in that map which describe themselves as
+      #            being automatically transferred from one endpoint to
+      #            another, you can prevent this by explicitly pasisng a
+      #            +nil+ value for the option; otherwise, _OMIT_ the option
+      #            for normal behaviour. Non-auto-transfer properties can be
+      #            specified as +nil+ or omitted with no change in behaviour.
+      #
+      def resource( resource, version = 1, options = {} )
+        middleware = @owning_interaction.owning_middleware_instance
+        endpoint   = middleware.inter_resource_endpoint_for(
+          resource,
+          version,
+          @owning_interaction
+        )
+
+        endpoint.locale = options[ :locale ] unless options[ :locale ].nil?
+
+        Hoodoo::Client::Headers::HEADER_TO_PROPERTY.each do | rack_header, description |
+          property        = description[ :property        ]
+          property_writer = description[ :property_writer ]
+          auto_transfer   = description[ :auto_transfer   ]
+
+          # For automatically transferred options there's no way to stop the
+          # auto transfer unless explicitly stating 'nil' to overwrite any
+          # existing value, so here, only write the value into the endpoint if
+          # the property specifically exists in the inbound options hash.
+          #
+          # For other properties, 'nil' has no meaning and there's no need to
+          # override anything, so use "unless nil?" in that case.
+
+          value = options[ property ]
+
+          if auto_transfer == true
+            endpoint.send( property_writer, value ) if options.has_key?( property )
+          else
+            endpoint.send( property_writer, value ) unless value.nil?
+          end
+        end
+
+        return endpoint
+      end
+
+  end
+end; end

data/lib/hoodoo/services/services/implementation.rb

@@ -0,0 +1,132 @@
+########################################################################
+# File::    implementation.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Service authors create subclasses of
+#           Hoodoo::Services::Service, which lists the one or more
+#           subclasses of Hoodoo::Services::Interface the service author
+#           writes; each of those declares an interface which refers,
+#           for each interface endpoint, to a subclass of the class
+#           described here. Service authors create the body of their
+#           service implementation within the subclass.
+#
+#           This file, then, does very little beyond describing the
+#           method framework that service authors use.
+# ----------------------------------------------------------------------
+#           24-Sep-2014 (ADH): Created.
+########################################################################
+
+module Hoodoo; module Services
+
+  # Service authors subclass this to produce the body of their service
+  # interface implementation. It defines a series of methods that must be
+  # implemented in order to service requests.
+  #
+  # A Hoodoo::Services::Implementation subclass is selected by the platform
+  # middleware because a Hoodoo::Services::Interface subclass tells it about
+  # the implementation class through the Hoodoo::Services::Interface::interface
+  # DSL; the interface class is referenced from an
+  # Hoodoo::Services::Service subclass through the
+  # Hoodoo::Services::Service::comprised_of DSL; and the application class
+  # is run by Rack by being passed to a call to +run+ in +config.ru+.
+  #
+  class Implementation
+
+    # Implement a "list" action (paginated, sorted list of resources).
+    #
+    # +context+:: Hoodoo::Services::Context instance describing authorised
+    #             session information, inbound request information and holding
+    #             the response object that the service updates with the results
+    #             of its processing of this action.
+    #
+    def list( context )
+      raise "Hoodoo::Services::Implementation subclasses must implement 'list'"
+    end
+
+    # Implement a "show" action (represent one existing resource instance).
+    #
+    # +context+:: Hoodoo::Services::Context instance describing authorised
+    #             session information, inbound request information and holding
+    #             the response object that the service updates with the results
+    #             of its processing of this action.
+    #
+    def show( context )
+      raise "Hoodoo::Services::Implementation subclasses must implement 'show'"
+    end
+
+    # Implement a "create" action (store one new resource instance).
+    #
+    # +context+:: Hoodoo::Services::Context instance describing authorised
+    #             session information, inbound request information and holding
+    #             the response object that the service updates with the results
+    #             of its processing of this action.
+    #
+    def create( context )
+      raise "Hoodoo::Services::Implementation subclasses must implement 'create'"
+    end
+
+    # Implement a "update" action (modify one existing resource instance).
+    #
+    # +context+:: Hoodoo::Services::Context instance describing authorised
+    #             session information, inbound request information and holding
+    #             the response object that the service updates with the results
+    #             of its processing of this action.
+    #
+    def update( context )
+      raise "Hoodoo::Services::Implementation subclasses must implement 'update'"
+    end
+
+    # Implement a "delete" action (delete one existing resource instance).
+    #
+    # +context+:: Hoodoo::Services::Context instance describing authorised
+    #             session information, inbound request information and holding
+    #             the response object that the service updates with the results
+    #             of its processing of this action.
+    #
+    def delete( context )
+      raise "Hoodoo::Services::Implementation subclasses must implement 'delete'"
+    end
+
+    # Optional verification to allow or deny authorisation for a particular
+    # action on a call-by-call basis.
+    #
+    # The middleware calls this method if a session
+    # (Hoodoo::Services::Session) has associated permissions
+    # (Hoodoo::Services::Permissions) which say that the resource's
+    # implementation should be asked via constant
+    # (Hoodoo::Services::Permissions::ASK).
+    #
+    # +context+:: Hoodoo::Services::Context instance as for action methods
+    #             such as #show, #list and so forth.
+    #
+    # +action+::  The action that the caller is trying to perform, as a
+    #             Symbol from the list in
+    #             Hoodoo::Services::Middleware::ALLOWED_ACTIONS.
+    #
+    # Your implementation *MUST* return either
+    # Hoodoo::Services::Permissions::ALLOW, to allow the action, or
+    # Hoodoo::Services::Permissions::DENY, to block the action.
+    #
+    # * If a session's permissions indicate that a resource endpoint should
+    #   be asked, but that interface does not define its own #verify method,
+    #   then the default implementation herein will _deny_ the request.
+    #
+    # * If a buggy verification method returns an unexpected value, the
+    #   middleware will ignore it and again _deny_ the request.
+    #
+    # Whether or not any of your implementations ever need to write a custom
+    # verification method will depend entirely upon your API, whether or not
+    # it has a meaningful definition of per-request assessment to allow or
+    # deny access and whether or not any sessions can exist with an 'ask'
+    # permission inside in the first place. If using the Hoodoo authorisation
+    # and authentication mechanism, this would come down to whether or not
+    # any Hoodoo::Data::Resources::Caller instances existed with the
+    # relevant permission value defined somewhere inside.
+    #
+    def verify( context, action )
+      return Hoodoo::Services::Permissions::DENY
+    end
+
+  end
+
+end; end

data/lib/hoodoo/services/services/interface.rb

@@ -0,0 +1,934 @@
+########################################################################
+# File::    interface.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Define a class (and some namespace-nested related support
+#           classes) that are subclassed by service authors and used to
+#           declare the nature of the interface the service implements
+#           via a small DSL.
+# ----------------------------------------------------------------------
+#           23-Sep-2014 (ADH): Created.
+########################################################################
+
+require 'set'
+
+module Hoodoo; module Services
+
+  # Service implementation authors subclass this to describe the interface that
+  # they implement for a particular Resource, as documented in the Loyalty
+  # Platform API.
+  #
+  # See class method ::interface for details.
+  #
+  class Interface
+
+    ###########################################################################
+
+    # A class containing a series of accessors that describe allowed parameters
+    # in a "list" call for a service implementation. The middleware uses this
+    # validate incoming query strings for lists and reject requests that ask
+    # for unsupported things. When instantiated the class sets itself up with
+    # defaults that match those described by the your platform's API. When
+    # passed to a Hoodoo::Services::Interface::ToListDSL instance, the DSL
+    # methods, if called, update the values stored herein.
+    #
+    class ToList
+
+      # Limit value; an integer that limits page size in lists.
+      #
+      attr_reader :limit
+
+      # Sort hash. Keys are supported sort fields, values are arrays of
+      # supported sort directions. The first array entry is the default sort
+      # order for the sort field.
+      #
+      attr_reader :sort
+
+      # Default sort key.
+      #
+      attr_reader :default_sort_key
+
+      # Default sort direction.
+      #
+      def default_sort_direction
+        @sort[ default_sort_key() ].first
+      end
+
+      # Array of supported search keys as Strings; empty for none defined.
+      #
+      attr_reader :search
+
+      # Array of supported filter keys as Strings; empty for none defined.
+      #
+      attr_reader :filter
+
+      # Create an instance with default settings.
+      #
+      def initialize
+
+        # Remember, these are defaults for the "to_list" object of an
+        # interface only. For interface-wide top level defaults, use the
+        # embedded calls to the DSL in Interface::interface.
+
+        @limit            = 50
+        @sort             = { 'created_at' => Set.new( [ 'desc', 'asc' ] ) }
+        @default_sort_key = 'created_at'
+        @search           = []
+        @filter           = []
+      end
+
+      private
+
+        # Private writer - see #limit - but there's a special contract with
+        # Hoodoo::Services::Interface::ToListDSL which permits it to call here
+        # bypassing +private+ via +send()+.
+        #
+        attr_writer :limit
+
+        # Private writer - see #sort - but there's a special contract with
+        # Hoodoo::Services::Interface::ToListDSL which permits it to call here
+        # bypassing +private+ via +send()+.
+        #
+        attr_writer :sort
+
+        # Private writer - see #default_sort_key - but there's a special
+        # contract with Hoodoo::Services::Interface::ToListDSL which permits it
+        # to call here bypassing +private+ via +send()+.
+        #
+        attr_writer :default_sort_key
+
+        # Private writer - see #search - but there's a special contract with
+        # Hoodoo::Services::Interface::ToListDSL which permits it to call here
+        # bypassing +private+ via +send()+.
+        #
+        attr_writer :search
+
+        # Private writer - see #filter - but there's a special contract with
+        # Hoodoo::Services::Interface::ToListDSL which permits it to call here
+        # bypassing +private+ via +send()+.
+        #
+        attr_writer :filter
+
+    end # 'class ToList'
+
+    ###########################################################################
+
+    # Implementation of the DSL that's written inside a block passed to
+    # Hoodoo::Services::Interface#to_list. This is an internal implementation
+    # class. Instantiate with a Hoodoo::Services::Interface::ToList instance,
+    # the data in which is updated as the DSL methods run.
+    #
+    class ToListDSL
+
+      # Initialize an instance and run the DSL methods.
+      #
+      # +hoodoo_interface_to_list_instance+:: Instance of
+      #                                       Hoodoo::Services::Interface::ToList
+      #                                       to update with data
+      #                                       from DSL method calls.
+      #
+      # &block:: Block of code that makes calls to the DSL herein.
+      #
+      # On exit, the DSL is run and the Hoodoo::Services::Interface::ToList has
+      # been updated.
+      #
+      def initialize( hoodoo_interface_to_list_instance, &block )
+        @tl = hoodoo_interface_to_list_instance # Shorthand!
+
+        unless @tl.instance_of?( Hoodoo::Services::Interface::ToList )
+          raise "Hoodoo::Services::Interface::ToListDSL\#initialize requires a Hoodoo::Services::Interface::ToList instance - got '#{ @tl.class }'"
+        end
+
+        self.instance_eval( &block )
+      end
+
+      # Specify the page size (limit) for lists.
+      #
+      # +limit+:: Page size (integer).
+      #
+      # Example:
+      #
+      #     limit 100
+      #
+      def limit( limit )
+        unless limit.is_a?( ::Integer )
+          raise "Hoodoo::Services::Interface::ToListDSL\#limit requires an Integer - got '#{ limit.class }'"
+        end
+
+        @tl.send( :limit=, limit )
+      end
+
+      # Specify extra sort keys and orders that add with whatever platform
+      # common defaults are already in place.
+      #
+      # +sort+:: Hash of sort keys, with values that are an array of supported
+      #          sort directions. The first array entry is used as the default
+      #          direction if no direction is specified in the client caller's
+      #          query string. Use strings or symbols.
+      #
+      #          To specify that a sort key should be the new default for the
+      #          interface in question, wrap it in a call to the #default
+      #          DSL method.
+      #
+      # Example - add sort key '+code+' with directions +:asc+ and +:desc+,
+      # plus sort key +:member+ which only supports direction +:asc+.
+      #
+      #     sort :code   => [ :asc, :desc ],
+      #          :member => [ :asc ]
+      #
+      def sort( sort )
+        unless sort.is_a?( ::Hash )
+          raise "Hoodoo::Services::Interface::ToListDSL\#sort requires a Hash - got '#{ sort.class }'"
+        end
+
+        # Convert Hash keys to Strings and Arrays to Sets of Strings too.
+
+        sort = sort.inject( {} ) do | memo, ( k, v ) |
+          memo[ k.to_s ] = Set.new( v.map do | entry |
+            entry.to_s
+          end )
+          memo
+        end
+
+        merged = @tl.sort().merge( sort )
+        @tl.send( :sort=, merged )
+      end
+
+      # Used in conjunction with #sort. Specifies that a sort key should be
+      # the default sort order for the interface.
+      #
+      # Example - add sort key '+code+' with directions +:asc+ and +:desc+,
+      # plus sort key +:member+ which only supports direction +:asc+. Say that
+      # '+code+' is to be the default sort order.
+      #
+      #     sort default( :code ) => [ :asc, :desc ],
+      #          :member          => [ :asc ]
+      #
+      def default( sort_key )
+        unless sort_key.is_a?( ::String ) || sort_key.is_a?( ::Symbol )
+          raise "Hoodoo::Services::Interface::ToListDSL\#default requires a String or Symbol - got '#{ sort_key.class }'"
+        end
+
+        @tl.send( :default_sort_key=, sort_key.to_s )
+        return sort_key
+      end
+
+      # Specify supported search keys in an array. The middleware will make
+      # sure the interface implementation is only called with search keys in
+      # that list. If a client attempts a search on an unsupported key, their
+      # request will be rejected by the middleware.
+      #
+      # If a service wants to do its own search validation, it should not list
+      # call here. Note also that only the keys are specified and validated;
+      # value escaping and validation, if necessary, is up to the service
+      # implementation.
+      #
+      # +search+:: Array of permitted search keys, as symbols or strings.
+      #            The order of array entries is arbitrary.
+      #
+      # Example - allow searches specifying +first_name+ and +last_name+ keys:
+      #
+      #     search :first_name, :last_name
+      #
+      def search( *search )
+        @tl.send( :search=, search.map { | item | item.to_s } )
+      end
+
+      # As #search, but for filtering.
+      #
+      # +filter+:: Array of permitted filter keys, as symbols or strings.
+      #            The order of array entries is arbitrary.
+      #
+      def filter( *filter )
+        @tl.send( :filter=, filter.map { | item | item.to_s } )
+      end
+    end # 'class ToListDSL'
+
+    ###########################################################################
+
+    # Mandatory part of the interface DSL. Declare the interface's URL endpoint
+    # and the Hoodoo::Services::Implementation subclass to be invoked when
+    # client requests are sent to a URL matching the endpoint.
+    #
+    # No two interfaces can use the same endpoint within a service application,
+    # unless the describe a different interface version - see #version.
+    #
+    # Example:
+    #
+    #     endpoint :estimations, PurchaseImplementation
+    #
+    # +uri_path_fragment+:: Path fragment to match at the start of a URL path,
+    #                       as a symbol or string, excluding leading "/". The
+    #                       URL path matches the fragment if the path starts
+    #                       with a "/", then matches the fragment exactly, then
+    #                       is followed by either ".", another "/", or the
+    #                       end of the path string. For example, a fragment of
+    #                       +:products+ matches all paths out of +/products+,
+    #                       +/products.json+ or +/products/22+, but does not
+    #                       match +/products_and_things+.
+    #
+    # +implementation_class+:: The Hoodoo::Services::Implementation subclass
+    #                          (the class itself, not an instance of it) that
+    #                          should be used when a request matching the
+    #                          path fragment is received.
+    #
+    def endpoint( uri_path_fragment, implementation_class )
+
+      # http://www.ruby-doc.org/core-2.2.3/Module.html#method-i-3C
+      #
+      unless implementation_class < Hoodoo::Services::Implementation
+        raise "Hoodoo::Services::Interface#endpoint must provide Hoodoo::Services::Implementation subclasses, but '#{ implementation_class }' was given instead"
+      end
+
+      self.class.send( :endpoint=,       uri_path_fragment    )
+      self.class.send( :implementation=, implementation_class )
+    end
+
+    # Declare the _major_ version of the interface being implemented. All
+    # service endpoints appear at "/v{version}/{endpoint}" relative to whatever
+    # root an edge layer defines. If a service interface does not specifiy its
+    # version, +1+ is assumed.
+    #
+    # Two interfaces can exist on the same endpoint provided their versions are
+    # different since the resulting route to reach them will be different too.
+    #
+    # +version+:: Integer major version number, e.g +2+.
+    #
+    def version( major_version )
+      self.class.send( :version=, major_version.to_s.to_i )
+    end
+
+    # List the actions that the service implementation supports. If you don't
+    # call this, the middleware assumes that all actions are available; else it
+    # only calls for supported actions. If you declared an empty array, your
+    # implementation would never be called.
+    #
+    # *supported_actions:: One or more from +:list+, +:show+, +:create+,
+    #                      +:update+ and +:delete+. Always use symbols, not
+    #                      strings. An exception is raised if unrecognised
+    #                      actions are given.
+    #
+    # Example:
+    #
+    #     actions :list, :show
+    #
+    def actions( *supported_actions )
+      supported_actions.map! { | item | item.to_sym }
+      invalid = supported_actions - Hoodoo::Services::Middleware::ALLOWED_ACTIONS
+
+      unless invalid.empty?
+        raise "Hoodoo::Services::Interface#actions does not recognise one or more actions: '#{ invalid.join( ', ' ) }'"
+      end
+
+      self.class.send( :actions=, Set.new( supported_actions ) )
+    end
+
+    # List any actions which are public - NOT PROTECTED BY SESSIONS. For
+    # public actions, no X-Session-ID or similar header is consulted and
+    # no session data will be associated with your
+    # Hoodoo::Services::Context instance when action methods are called.
+    #
+    # Use with great care!
+    #
+    # Note that if the implementation of a public action needs to call
+    # other resources, it can only ever call them if those actions in
+    # those other resources are also public. The implementation of a
+    # public action is prohibited from making calls to protected actions
+    # in other resources.
+    #
+    # *public_actions:: One or more from +:list+, +:show+, +:create+,
+    #                   +:update+ and +:delete+. Always use symbols, not
+    #                   strings. An exception is raised if unrecognised
+    #                   actions are given.
+    #
+    def public_actions( *public_actions )
+      public_actions.map! { | item | item.to_sym }
+      invalid = public_actions - Hoodoo::Services::Middleware::ALLOWED_ACTIONS
+
+      unless invalid.empty?
+        raise "Hoodoo::Services::Interface#public_actions does not recognise one or more actions: '#{ invalid.join( ', ' ) }'"
+      end
+
+      self.class.send( :public_actions=, Set.new( public_actions ) )
+    end
+
+    # Set secure log actions.
+    #
+    # +secure_log_actions+:: A Hash, described below.
+    #
+    # The given Hash keys are names of actions as Symbols: +:list+,
+    # +:show+, +:create+, +:update+ or +:delete+. Values are +:request+,
+    # +:response+ or +:both+. For a given action targeted at this resource:
+    #
+    # * A key of +:request+ means that API call-related Hoodoo automatic
+    #   logging will _exclude_ body data for the _inbound_ _request_, but
+    #   still include body data in the response. Example: A POST to a Login
+    #   resource includes a password which you don't want logged, but the
+    #   response data doesn't quote the password back so is "safe". The
+    #   secure log actions Hash for the Login resource's interface would
+    #   include <tt>:create => :request</tt>.
+    #
+    # * A key of +:response+ means that API call-related Hoodoo automatic
+    #   logging will _exclude_ body data for the _outbound_ _response_,
+    #   but still include body data in the request. Example: A POST to a
+    #   Caller resource creates a Caller with a generated authentication
+    #   secret that's only exposed in the POST's response. The inbound
+    #   data used to create that Caller can be safely logged, but the
+    #   authentication secret is sensitive and shouldn't be recorded. The
+    #   secure log actions Hash for the Caller resource's interface would
+    #   include <tt>:create => :response</tt>.
+    #
+    #   _ERROR_ _RESPONSES_ _ARE_ _STILL_ _LOGGED_ because that's useful data;
+    #   so make sure that if you generate any custom errors in your service
+    #   that secure data is not contained within them.
+    #
+    # * A key of +both+ has the same result as both +:request+ and
+    #   +:response+, so body data is never logged. It's hard to come up
+    #   with good examples of resources where both the incoming data is
+    #   sensitive and the outgoing data is sensitive but the option is
+    #   included for competion, as someone out there will need it.
+    #
+    # Example: The request body data sent by a caller into a resource's
+    # +:create+ action will not be logged:
+    #
+    #     secure_log_for( { :create => :request } )
+    #
+    # Example: Neither the request data sent by a caller, nor the
+    # response data sent back, will be logged for an +:update+ action:
+    #
+    #     secure_log_for( { :update => :both } )
+    #
+    # The default is an empty Hash; all actions have both inbound request
+    # body data and outbound response body data logged by Hoodoo.
+    #
+    def secure_log_for( secure_log_actions = {} )
+      secure_log_actions = Hoodoo::Utilities.symbolize( secure_log_actions )
+      invalid = secure_log_actions.keys - Hoodoo::Services::Middleware::ALLOWED_ACTIONS
+
+      unless invalid.empty?
+        raise "Hoodoo::Services::Interface#secure_log_for does not recognise one or more actions: '#{ invalid.join( ', ' ) }'"
+      end
+
+      self.class.send( :secure_log_for=, secure_log_actions )
+    end
+
+    # An array of supported embed keys (as per documentation, so singular or
+    # plural as per resource interface descriptions in the Loyalty Platform
+    # API). Things which can be embedded can also be referenced, via the
+    # <tt>_embed</tt> and <tt>_reference</tt> query string keys.
+    #
+    # The middleware uses the list to reject requests from clients which
+    # ask for embedded or referenced entities that were not listed by the
+    # interface. If you don't call here, or call here with an empty array,
+    # no embedding or referencing will be allowed for calls to the service
+    # implementation.
+    #
+    # +embed+:: Array of permitted embeddable entity names, as symbols or
+    #           strings. The order of array entries is arbitrary.
+    #
+    # Example: An interface permits lists that request embedding or
+    # referencing of "vouchers", "balances" and "member":
+    #
+    #     embed :vouchers, :balances, :member
+    #
+    # As a result, #embeds would return:
+    #
+    #     [ 'vouchers', 'balances', 'member' ]
+    #
+    def embeds( *embeds )
+      self.class.send( :embeds=, embeds.map { | item | item.to_s } )
+    end
+
+    # Specify parameters related to common index parameters. The block contains
+    # calls to the DSL described by Hoodoo::Services::Interface::ToListDSL. The
+    # default values should be described by your platform's API - hard-coded at
+    # the time of writing as:
+    #
+    #     limit    50
+    #     sort     :created_at => [ :desc, :asc ]
+    #     search   nil
+    #     filter   nil
+    #
+    def to_list( &block )
+      Hoodoo::Services::Interface::ToListDSL.new(
+        self.class.instance_variable_get( '@to_list' ),
+        &block
+      )
+    end
+
+    # Optional description of the JSON parameters (schema) that the interface's
+    # implementation requires for calls creating resource instances. The block
+    # uses the DSL from Hoodoo::Presenters::Object, so you can specify
+    # basic object things like +string+, or higher level things like +type+ or
+    # +resource+.
+    #
+    # If a call comes into the middleware from a client which contains body
+    # data that doesn't validate according to your schema, it'll be rejected
+    # before even getting as far as your interface implementation.
+    #
+    # Default values for fields where present are for _rendering_ _only_; they
+    # are not injected into the inbound body for (say) persistence at database
+    # levels. A returned, rendered representation based on the same schema
+    # would have the default values present only. If you need default values
+    # at the persistence layer too, define them there too with whatever
+    # mechanism is most appropriate for your chosen persistence approach.
+    #
+    # The Hoodoo::Presenters::Object#internationalised DSL method can be
+    # called within your block harmlessly, but it has no side effects. Any
+    # resource interface that can take internationalised data for creation (or
+    # modification) must already have an internationalised representation, so
+    # the standard resources in the Hoodoo::Data::Resources collection will
+    # already have declared that internationalisation applies.
+    #
+    # Example 1:
+    #
+    #     to_create do
+    #       string :name, :length => 32, :required => true
+    #       text :description
+    #     end
+    #
+    # Example 2: With a resource
+    #
+    #     to_create do
+    #       resource Product # Fields are *inline*
+    #     end
+    #
+    # &block:: Block, passed to Hoodoo::Presenters::Object, describing
+    #          the fields used for resource creation.
+    #
+    def to_create( &block )
+      obj = Class.new( Hoodoo::Presenters::Base )
+      obj.schema( &block )
+
+      self.class.send( :to_create=, obj )
+    end
+
+    # As #to_create, but applies when modifying existing resource instances.
+    # To avoid repeating yourself, if your modification and creation parameter
+    # requirements are identical, call #update_same_as_create.
+    #
+    # The "required" flag is ignored for updates, because an omitted field for
+    # an update to an existing resource instance simply means "do not change
+    # the current value". As with #to_create, default values have relevance
+    # to the rendering stage only and have no effect here.
+    #
+    # &block:: Block, passed to Hoodoo::Presenters::Object, describing
+    #          the fields used for resource modification.
+    #
+    def to_update( &block )
+      obj = Class.new( Hoodoo::Presenters::Base )
+      obj.schema( &block )
+
+      # When updating, 'required' fields in schema aren't required; you just
+      # omit a field to avoid changing its value. Walk the to-update schema
+      # graph stripping out any such problematic attributes.
+      #
+      obj.walk do | property |
+        property.required = false
+      end
+
+      self.class.send( :to_update=, obj )
+    end
+
+    # Declares that the expected JSON fields described in a #to_create call are
+    # the same as those required for modifying resources too.
+    #
+    # Example:
+    #
+    #     update_same_as_create
+    #
+    # ...and that's all. There are no parameters or blocks needed.
+    #
+    def update_same_as_create
+      self.send( :to_update, & self.class.to_create().get_schema_definition() )
+    end
+
+    # Declares custom errors that are part of this defined interface. This
+    # calls directly through to Hoodoo::ErrorDescriptions#errors_for, so
+    # see that for details.
+    #
+    # A service should usually define only a single domain of error using one
+    # call to #errors_for, but techncially can make as many calls for as many
+    # domains as required. Definitions are merged.
+    #
+    # +domain+:: Domain, e.g. 'purchase', 'transaction' - see
+    #            Hoodoo::ErrorDescriptions#errors_for for details.
+    #
+    # &block::   Code block making Hoodoo::ErrorDescriptions DSL calls.
+    #
+    # Example:
+    #
+    #     errors_for 'transaction' do
+    #       error 'duplicate_transaction', status: 409, message: 'Duplicate transaction', :required => [ :client_uid ]
+    #     end
+    #
+    def errors_for( domain, &block )
+      descriptions = self.class.errors_for
+
+      if descriptions.nil?
+        descriptions = self.class.send( :errors_for=, Hoodoo::ErrorDescriptions.new )
+      end
+
+      descriptions.errors_for( domain, &block )
+    end
+
+    # Declare additional permissions that you require for a given action.
+    #
+    # If the implementation of a resource endpoint involves making calls out
+    # to other resources, then you need to consider how authorisation is
+    # granted to those other resources.
+    #
+    # The Hoodoo::Services::Session instance for the inbound external caller
+    # carries a Hoodoo::Services::Permission instance describing the actions
+    # that the caller is permitted to do. The middleware enforces these
+    # permissions, so that a resource implementation won't be called at all
+    # unless the caller has permission to do so.
+    #
+    # These permissions continue to apply during inter-resource calls. The
+    # wider session context is always applied. So, if one resource calls
+    # another resource, either:
+    #
+    # * The inbound API caller's session must have all necessary permissions
+    #   for both the resource it is actually directly calling, and for any
+    #   actions in any resources that the called resource in turn calls (and
+    #   so-on, for any chain of resources).
+    #
+    # ...or...
+    #
+    # * The resource uses this +additional_permissions_for+ method to declare
+    #   up-front that it will require the described permissions when a
+    #   particular action is performed on it. When an inter-resource call is
+    #   made, a temporary internal-only session is constructed that merges
+    #   the permissions of the inbound caller with the additional permissions
+    #   requested by the resource. The downstream called resource needs no
+    #   special case code at all - it just sees a valid session with valid
+    #   permissions and does what the upstream resource asked of it.
+    #
+    # For example, suppose a resource Clock returns both a time and a date,
+    # by calling out to the Time and Date resources. One option is that the
+    # inbound caller must have +show+ action permissions for all of Clock,
+    # Time and Date; if any of those are missing, then an attempt to call
+    # +show+ on the Clock resource would result in a 403 response.
+    #
+    # The other option is for Clock's interface to declare its requirements:
+    #
+    #     additional_permissions_for( :show ) do | p |
+    #       p.set_resource( :Time, :show, Hoodoo::Services::Permissions::ALLOW )
+    #       p.set_resource( :Date, :show, Hoodoo::Services::Permissions::ALLOW )
+    #     end
+    #
+    # Suppose you could create Clock instances for some reason, but there
+    # was an audit trail for this; Clock must create an Audit entry itself,
+    # but you don't want to expose this ability to external callers through
+    # their session permissions; so, just declare your additional
+    # permissions for that specific inter-service case:
+    #
+    #     additional_permissions_for( :create ) do | p |
+    #       p.set_resource( :Audit, :create, Hoodoo::Services::Permissions::ALLOW )
+    #     end
+    #
+    # The call says which action in _the_ _declaring_ _interface's_ _resource_
+    # is a target. The block takes a single parameter; this is a default
+    # initialisation Hoodoo::Services::Permissions instance. Use that
+    # object's methods to set up whatever permissions you need in other
+    # resources, to successfully process the action in question. You only
+    # need to describe the resources you immediately call, not the whole
+    # chain - if "this" resource calls another, then it's up to the other
+    # resource to in turn describe additional permissions should it make its
+    # own set of downstream calls to further resource endpoints.
+    #
+    # Setting default permissions or especially the default permission
+    # fallback inside the block is possible but *VERY* *STRONGLY*
+    # *DISCOURAGED*. Instead, precisely describe the downstream resources,
+    # actions and permissions that are required.
+    #
+    # Note an important restriction - public actions (see ::public_actions)
+    # cannot be augmented in this way. A public action in one resource can
+    # only ever call public actions in other resources. This is because no
+    # session is needed _at_ _all_ to call a public action; calling into a
+    # protected action in another resource from this context would require
+    # invention of a full caller context which would be entirely invented
+    # and could represent an accidental (and significant) security hole.
+    #
+    # If you call this method for the same action more than once, the last
+    # call will be the one that takes effect - each call overwrites the
+    # results of any previous call made for the same action.
+    #
+    # Parameters are:
+    #
+    # +action+:: The action in this interface which will require the
+    #            additional permissions to be described. Pass a Symbol or
+    #            equivalent String from the list in
+    #            Hoodoo::Services::Middleware::ALLOWED_ACTIONS.
+    #
+    # &block::   Block which is passed a new, default state
+    #            Hoodoo::Services::Permissions instance; make method calls
+    #            on this instance to describe the required permissions.
+    #
+    def additional_permissions_for( action, &block )
+      action = action.to_s
+
+      unless block_given?
+        raise 'Hoodoo::Services::Interface#additional_permissions_for must be passed a block'
+      end
+
+      p = Hoodoo::Services::Permissions.new
+      yield( p )
+
+      additional_permissions = self.class.additional_permissions() || {}
+      additional_permissions[ action ] = p
+      self.class.send( :additional_permissions=, additional_permissions )
+    end
+
+  protected
+
+    # Define the subclass Service's interface. A DSL is used with methods
+    # documented in the Hoodoo::Services::InterfaceDSL class.
+    #
+    # The absolute bare minimum interface description just states that a
+    # particular implementation class is used when requests are made to a
+    # particular URL endpoint, which is implementing an interface for a
+    # particular given resource. For a hypothetical Magic resource interface:
+    #
+    #     class MagicImplementation < Hoodoo::Services::Implementation
+    #       # ...implementation code goes here...
+    #     end
+    #
+    #     class MagicInterface < Hoodoo::Services::Interface
+    #       interface :Magic do
+    #         endpoint :paul_daniels, MagicImplementation
+    #       end
+    #     end
+    #
+    # This would cause all calls to URLs at '/paul_daniels[...]' to be routed to
+    # an instance of the MagicImplementation class.
+    #
+    # Addtional DSL facilities allow the interface to say what HTTP methods
+    # it supports (in terms of the action methods that it supports inside its
+    # implementation class), describe any extra sort, search or filter data it
+    # allows beyond the common fields and describe the expected JSON fields for
+    # creation and/or modification actions. By specifing these, the service
+    # middleware code is able to do extra validation and sanitisation of client
+    # requests, but they're entirely optional if the implementation class wants
+    # to take over all of that itself.
+    #
+    # +resource+:: Name of the resource that the interface is for, as a String
+    #              or Symbol (e.g. +:Purchase+).
+    #
+    # &block::     Block that calls the Hoodoo::Services::InterfaceDSL methods;
+    #              #endpoint is the only mandatory call.
+    #
+    def self.interface( resource, &block )
+
+      if @to_list.nil?
+        @to_list = Hoodoo::Services::Interface::ToList.new
+      else
+        raise "Hoodoo::Services::Interface subclass unexpectedly ran ::interface more than once"
+      end
+
+      self.resource = resource.to_sym
+
+      interface = self.new
+      interface.instance_eval do
+        version 1
+        embeds # Nothing
+        actions *Hoodoo::Services::Middleware::ALLOWED_ACTIONS
+        public_actions # None
+        secure_log_for # None
+      end
+
+      interface.instance_eval( &block )
+
+      if self.endpoint.nil?
+        raise "Hoodoo::Services::Interface subclasses must always call the 'endpoint' DSL method in their interface descriptions"
+      end
+
+    end
+
+    # Define various class instance variable (sic.) accessors.
+    #
+    # * Instance variable: things set on individual "Foo" instances ("Foo.new")
+    # * Class instance variables: things set on the "Foo" class only
+    # * Class variables: things set on the "Foo" class _and_ _all_ _subclasses_
+    #
+    class << self
+
+      public
+
+        # Endpoint path as declared by service, without preceding "/", possibly
+        # as a symbol - e.g. +:products+ for "/products[...]" as an implied
+        # endpoint.
+        #
+        attr_reader :endpoint
+
+        # Major version of interface as an integer. All service endpoint routes
+        # have "v{version}/" as a prefix, e.g. "/v1/products[...]".
+        #
+        attr_reader :version
+
+        # Name of the resource the interface addresses as a symbol, e.g.
+        # +:Product+.
+        #
+        attr_reader :resource
+
+        # Implementation class for the service. An
+        # Hoodoo::Services::Implementation subclass - the class, not an
+        # instance of it.
+        #
+        attr_reader :implementation
+
+        # Supported action methods as a Set of symbols with one or more of
+        # +:list+, +:show+, +:create+, +:update+ or +:delete+. The presence of
+        # a Symbol indicates a supported action. If empty, no actions are
+        # supported. The default is for all actions to be present in the Set.
+        #
+        attr_reader :actions
+
+        # Public action methods as a Set of symbols with one or more of
+        # +:list+, +:show+, +:create+, +:update+ or +:delete+. The presence
+        # of a Symbol indicates an action open to the public and not subject
+        # to session security. If empty, all actions are protected by session
+        # security. The default is an empty Set.
+        #
+        attr_reader :public_actions
+
+        # Secure log actions set by #secure_log_for - see that call for
+        # details. The default is an empty Hash.
+        #
+        attr_reader :secure_log_for
+
+        # Array of strings listing allowed embeddable things. Each string
+        # matches the split up comma-separated value for query string
+        # <tt>_embed</tt> or <tt>_reference</tt> keys. For example:
+        #
+        #     ...&_embed=foo,bar
+        #
+        # ...would be valid provided there was an embedding declaration
+        # such as:
+        #
+        #     embeds :foo, :bar
+        #
+        # ...which would in turn lead this accessor to return:
+        #
+        #     [ 'foo', 'bar' ]
+        #
+        attr_reader :embeds
+
+        # A Hoodoo::Services::Interface::ToList instance describing the list
+        # parameters for the interface as a Set of Strings. See also
+        # Hoodoo::Services::Interface::ToListDSL.
+        #
+        def to_list
+          @to_list ||= Hoodoo::Services::Interface::ToList.new
+          @to_list
+        end
+
+        # A Hoodoo::Presenters::Object instance describing the schema
+        # for client JSON coming in for calls that create instances of the
+        # resource that the service's interface is addressing. If +nil+,
+        # arbitrary data is acceptable (the implementation becomes entirely
+        # responsible for data validation).
+        #
+        attr_reader :to_create
+
+        # A Hoodoo::Presenters::Object instance describing the schema
+        # for client JSON coming in for calls that modify instances of the
+        # resource that the service's interface is addressing. If +nil+,
+        # arbitrary data is acceptable (the implementation becomes entirely
+        # responsible for data validation).
+        #
+        attr_reader :to_update
+
+        # A Hoodoo::ErrorDescriptions instance describing all errors that
+        # the interface might return, including the default set of platform
+        # and generic errors. If nil, there are no additional error codes
+        # beyond the default set.
+        #
+        attr_reader :errors_for
+
+        # A Hash, keyed by String equivalents of the Symbols in
+        # Hoodoo::Services::Middleware::ALLOWED_ACTIONS, where the values
+        # are Hoodoo::Services::Permissions instances describing extended
+        # permissions for the related action. See
+        # ::additional_permissions_for.
+        #
+        attr_reader :additional_permissions
+
+      private
+
+        # Private property writer allows instances running the DSL to set
+        # values on the class for querying using the public readers.
+        # See ::endpoint.
+        #
+        attr_writer :endpoint
+
+        # Private property writer allows instances running the DSL to set
+        # values on the class for querying using the public readers.
+        # See ::version.
+        #
+        attr_writer :version
+
+        # Private property writer allows instances running the DSL to set
+        # values on the class for querying using the public readers.
+        # See ::resource.
+        #
+        attr_writer :resource
+
+        # Private property writer allows instances running the DSL to set
+        # values on the class for querying using the public readers.
+        # See ::implementation.
+        #
+        attr_writer :implementation
+
+        # Private property writer allows instances running the DSL to set
+        # values on the class for querying using the public readers.
+        # See ::actions.
+        #
+        attr_writer :actions
+
+        # Private property writer allows instances running the DSL to set
+        # values on the class for querying using the public readers.
+        # See ::public_actions.
+        #
+        attr_writer :public_actions
+
+        # Private property writer allows instances running the DSL to set
+        # values on the class for querying using the public readers.
+        # See ::secure_log_for.
+        #
+        attr_writer :secure_log_for
+
+        # Private property writer allows instances running the DSL to set
+        # values on the class for querying using the public readers.
+        # See ::embeds.
+        #
+        attr_writer :embeds
+
+        # Private property writer allows instances running the DSL to set
+        # values on the class for querying using the public readers.
+        # See ::to_create.
+        #
+        attr_writer :to_create
+
+        # Private property writer allows instances running the DSL to set
+        # values on the class for querying using the public readers.
+        # See ::to_update.
+        #
+        attr_writer :to_update
+
+        # Private property writer allows instances running the DSL to set
+        # values on the class for querying using the public readers.
+        # See ::errors_for.
+        #
+        attr_writer :errors_for
+
+        # Private property writer allows instances running the DSL to set
+        # values on the class for querying using the public readers.
+        # See ::additional_permissions.
+        #
+        attr_writer :additional_permissions
+
+    end  # 'class << self'
+  end    # 'class Interface'
+
+end; end # 'module Hoodoo; module Services'