hoodoo 1.0.2

data/lib/hoodoo/active/active_record/error_mapping.rb

@@ -0,0 +1,351 @@
+########################################################################
+# File::    error_mapping.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Support mixin for models subclassed from ActiveRecord::Base
+#           providing a mapping between API level errors and model
+#           validation errors.
+# ----------------------------------------------------------------------
+#           17-Nov-2014 (ADH): Created.
+########################################################################
+
+module Hoodoo
+
+  # Support mixins for models subclassed from ActiveRecord::Base. See:
+  #
+  # * http://guides.rubyonrails.org/active_record_basics.html
+  #
+  module ActiveRecord
+
+    # Support mixin for models subclassed from ActiveRecord::Base providing
+    # a mapping between ActiveRecord validation errors and platform errors
+    # via Hoodoo::ErrorDescriptions and Hoodoo::Errors. See individual
+    # module methods for examples, along with:
+    #
+    # * http://guides.rubyonrails.org/active_record_basics.html
+    #
+    # The error handling mechanism this mixin provides is intentionally
+    # analogous to that used for resource-to-resource calls through
+    # Hoodoo::Client::AugmentedBase.
+    #
+    module ErrorMapping
+
+      # Validates the model instance and adds mapped-to-platform errors to
+      # a given Hoodoo::Errors instance, if any validation errors occur.
+      # For ActiveRecord validation documentation, see:
+      #
+      # * http://guides.rubyonrails.org/active_record_validations.html
+      #
+      # Returns +true+ if any errors were added (model instance is invalid)
+      # else +false+ if everything is OK (model instance is valid).
+      #
+      # == Mapping ActiveRecord errors to API errors
+      #
+      # The method makes an idiomatic example for "check errors in the model,
+      # map them to platform errors in my service's response and return the
+      # result" very simple, at the expense of modifying the passed-in
+      # error collection contents (mutating a parameter is a risky pattern).
+      #
+      # Given this example model:
+      #
+      #     class SomeModel < ActiveRecord::Base
+      #       include Hoodoo::ActiveRecord::ErrorMapping
+      #       # ...
+      #     end
+      #
+      # ...then a service's #create method could do something like:
+      #
+      #     def create( context )
+      #
+      #       # Validate inbound creation data by e.g. schema through the
+      #       # presenter layer - Hoodoo::Presenters::Base and
+      #       # Hoodoo::Presenters::Base - then...
+      #
+      #       model         = SomeModel.new
+      #       model.param_1 = 'something based on inbound creation data'
+      #
+      #       # Ideally use the Writer mixin for concurrency-safe saving,
+      #       # but in this simple example we'll just use #save directly;
+      #       # unhandled database exceptions might be thrown:
+      #
+      #       model.save()
+      #
+      #       # Now exit, adding mapped errors to the response, if there
+      #       # were validation failures when attempting to save.
+      #
+      #       return if model.adds_errors_to?( context.response.errors )
+      #
+      #       # ...else set 'context.response' data appropriately.
+      #
+      #     end
+      #
+      # An alternative pattern which avoids mutating the input parameter
+      # uses the potentially less efficient, but conceptually cleaner method
+      # #platform_errors. Using #adds_errors_to? as per the above code is
+      # faster, but the above example's use of +save+, as per its comments,
+      # does not fully handle some concurrency edge cases.
+      #
+      # To win on both fronts use Hoodoo::ActiveRecord::Writer:
+      #
+      #     def create( context )
+      #
+      #       model         = SomeModel.new
+      #       model.param_1 = 'something based on inbound creation data'
+      #
+      #       unless model.persist_in( context ) === :success
+      #         context.response.add_errors( model.platform_errors )
+      #         return
+      #       end
+      #
+      #       # ...else set 'context.response' data appropriately.
+      #
+      #     end
+      #
+      # In this case, the less efficient #platform_errors call only happens
+      # when we know we are in an error recovery situation anyway, in which
+      # case it isn't as important to operate in as efficient a manner as
+      # possible - provided one assumes that the non-error path is the much
+      # more common case!
+      #
+      # == Associations
+      #
+      # When a model has associations and nested attributes are accepted for
+      # those associations, a validity query on an instance constructed with
+      # nested attributes will cause ActiveRecord to traverse all such
+      # attributes and aggregate specific errors on the parent object. This
+      # is specifically different from +validates_associated+, wherein
+      # associations constructed and attached through any means are validated
+      # independently, with validation errors independently added to those
+      # objects and the parent only gaining a generic "foo is invalid" error.
+      #
+      # In such cases, the error mapper will attempt to path-traverse the
+      # error's column references to determine the association's column type
+      # and produce a fully mapped error with a reference to the full path.
+      # Service authors are encouraged to use this approach if associations
+      # are involved, as it yields the most comprehensive mapped error
+      # collection.
+      #
+      # In the example below, note how the Child model does not need to
+      # include Hoodoo error mapping (though it can do so harmlessly if it so
+      # wishes) because it is the Parent model that drives the mapping of all
+      # the validations aggregated by ActiveRecord into an instance of Parent
+      # due to +accepts_nested_attributes_for+.
+      #
+      # So, given this:
+      #
+      #     def Parent < ActiveRecord::Base
+      #       include Hoodoo::ActiveRecord::ErrorMapping
+      #
+      #       has_many :children
+      #       accepts_nested_attributes_for :children
+      #     end
+      #
+      #     def Child < ActiveRecord::Base
+      #       belongs_to :parent
+      #
+      #       # ...then add ActiveRecord validations - e.g.:
+      #
+      #       validates :some_child_field, :length => { :maximum => 5 }
+      #     end
+      #
+      # ...then if a Parent were to be constructed thus:
+      #
+      #     parent = Parent.new( {
+      #       "parent_field_1" = "foo",
+      #       "parent_field_2" = "bar",
+      #       "children_attributes" = [
+      #         { "some_child_field" = "child_1_foo" },
+      #         { "some_child_field" = "child_2_foo" },
+      #         # ...
+      #       ],
+      #       # ...
+      #     } )
+      #
+      # ...then <tt>parent.adds_errors_to?( some_collection )</tt> could lead
+      # to +some_collection+ containing errors such as:
+      #
+      #     {
+      #       "code"      => "generic.invalid_string",
+      #       "message    => "is too long (maximum is 5 characters)",
+      #       "reference" => "children.some_child_field"
+      #     }
+      #
+      # +collection+:: A Hoodoo::Errors instance, typically obtained
+      #                from the Hoodoo::Services::Context instance passed to
+      #                a service implementation in calls like
+      #                Hoodoo::Services::Implementation#list or
+      #                Hoodoo::Services::Implementation#show, via
+      #                +context.response.errors+
+      #                (i.e. Hoodoo::Services::Context#response /
+      #                Hoodoo::Services::Response#errors). The collection you
+      #                pass is updated if there are any errors recorded in
+      #                the model, by adding equivalent structured errors to
+      #                the collection.
+      #
+      def adds_errors_to?( collection )
+
+        self.validate()
+
+        self.errors.messages.each_pair do | attribute_name, message_array |
+          attribute_name = attribute_name.to_s
+
+          attribute_type = nz_co_loyalty_determine_deep_attribute_type( attribute_name )
+          attribute_name = 'model instance' if attribute_name == 'base'
+
+          message_array.each do | message |
+            error_code = case message
+              when 'has already been taken'
+                'generic.invalid_duplication'
+              else
+                attribute_type == 'text' ? 'generic.invalid_string' : "generic.invalid_#{ attribute_type }"
+            end
+
+            unless collection.descriptions.recognised?( error_code )
+              error_code = 'generic.invalid_parameters'
+            end
+
+            collection.add_error(
+              error_code,
+              :message   => message,
+              :reference => { :field_name => attribute_name }
+            )
+          end
+        end
+
+        return self.errors.any?
+      end
+
+      # Validate the model instance and return a Hoodoo::Errors instance
+      # which contains no platform errors if there are no model validation
+      # errors, else mapped-to-platform errors if validation errors are
+      # encountered. For ActiveRecord validation documentation, see:
+      #
+      # * http://guides.rubyonrails.org/active_record_validations.html
+      #
+      # This mixin method provides support for an alternative coding style to
+      # method #adds_errors_to?, by generating an Errors collection internally
+      # rather than modifying one passed by the caller. It is less efficient
+      # than calling #adds_errors_to? if you have an existing errors collection
+      # already constructed, but otherwise follows a cleaner design pattern.
+      #
+      # See #adds_errors_to? examples first, then compare the idiom shown
+      # there:
+      #
+      #     return if model.adds_errors_to?( context.response.errors )
+      #
+      # ...with the idiomatic use of this method:
+      #
+      #     context.response.add_errors( model.platform_errors )
+      #     return if context.response.halt_processing?
+      #
+      # It is a little more verbose and in this example will run a little
+      # slower due to the construction of the internal Hoodoo::Errors
+      # instance followed by the addition to the +context.response+
+      # collection, but you may prefer the conceptually cleaner approach.
+      # You can lean on the return value of #add_errors and end up back at
+      # one line of (very slightly less obvious) code, too:
+      #
+      #     return if context.response.add_errors( model.platform_errors )
+      #
+      def platform_errors
+        collection = Hoodoo::Errors.new
+        self.adds_errors_to?( collection )
+
+        return collection
+      end
+
+    private
+
+      # Given an attribute for this model as a string, return the column type
+      # associated with it.
+      #
+      # The attribute name intended for use here comes from validation and,
+      # when there are unsaved associations in an ActiveRecord graph that is
+      # being saved, ActiveRecord aggregates child object errors into the
+      # target parent being saved with the attribute names using a dot
+      # notation to indicate the path of methods to get from one instance to
+      # the next. This is resolved. For example:
+      #
+      # * <tt>address</tt> would look up the type of a column called
+      #   "address" in 'this' model.
+      #
+      # * <tt>addresses.home</tt> would look up the type of a column called
+      #   "home" in whatever is accessed by "model.addresses". If this gives
+      #   an array, the first entry in the array is taken for column type
+      #   retrieval.
+      #
+      # This path chasing will be done to an arbitrary depth. If at any point
+      # there is a failure to follow the path, the path follower exits and
+      # the top-level error is used instead, with a generic unknown column
+      # type returned.
+      #
+      # Parameters:
+      #
+      # +attribute_path+:: _String_ attribute path. Not a Symbol or Array!
+      #
+      # Return values are any ActiveRecord column type or these special
+      # values:
+      #
+      # * +unknown+ for any unrecognised attribute name or an attribute name
+      #   that is a path (it has one or more "."s in it) but where the path
+      #   cannot be followed.
+      #
+      # * +array+ for columns that appear to respond to the +array+ method.
+      #
+      # * +uuid+ for columns of any known but non-array type, where there is
+      #   a UuidValidator present.
+      #
+      def nz_co_loyalty_determine_deep_attribute_type( attribute_path )
+
+        attribute_name  = attribute_path
+        target_instance = self
+
+        # Descend a path of "foo.bar.baz" dereferencing associations from the
+        # field names in the dot-separated path until we're at the lowest leaf
+        # object with "baz" as its errant field.
+
+        if attribute_path.include?( '.' )
+
+          leaf_instance = target_instance
+          leaf_field    = attribute_path
+
+          fields        =  attribute_path.split( '.' )
+          leaf_field    = fields.pop() # (remove final entry - the leaf object's errant field)
+          reached_field = nil
+
+          fields.each do | field |
+            object_at_field = leaf_instance.send( field ) if   leaf_instance.respond_to?(  field )
+            object_at_field = object_at_field.first       if object_at_field.respond_to?( :first )
+
+            break if object_at_field.nil?
+
+            leaf_instance = object_at_field
+            reached_field = field
+          end
+
+          if reached_field === fields.last
+            attribute_name  = leaf_field
+            target_instance = leaf_instance
+          end
+        end
+
+        column = target_instance.class.columns_hash[ attribute_name ]
+
+        attribute_type = if column.nil?
+          'unknown'
+        elsif column.respond_to?( :array ) && column.array
+          'array'
+        elsif target_instance.class.validators_on( attribute_name ).any? { | v |
+            v.instance_of?( UuidValidator )
+          } # Considered a UUID since it uses the UUID validator
+          'uuid'
+        else
+          column.type.to_s()
+        end
+
+        return attribute_type
+      end
+
+    end
+  end
+end

data/lib/hoodoo/active/active_record/finder.rb

@@ -0,0 +1,606 @@
+########################################################################
+# File::    finder.rb
+# (C)::     Loyalty New Zealand 2014
+#
+# Purpose:: Support mixin for models subclassed from ActiveRecord::Base
+#           providing enhanced find mechanisms for data retrieval,
+#           especially +show+ and +list+ action handling.
+# ----------------------------------------------------------------------
+#           25-Nov-2014 (ADH): Created.
+########################################################################
+
+require 'hoodoo/active/active_record/search_helper'
+
+module Hoodoo
+  module ActiveRecord
+
+    # Mixin for models subclassed from ActiveRecord::Base providing support
+    # methods to handle common +show+ and +list+ filtering actions based on
+    # inbound data and create instances in a request context aware fashion.
+    #
+    # It is _STRONGLY_ _RECOMMENDED_ that you use the likes of:
+    #
+    # * Hoodoo::ActiveRecord::Finder::ClassMethods::acquire_in
+    # * Hoodoo::ActiveRecord::Finder::ClassMethods::list_in
+    #
+    # ...to retrieve model data related to resource instances and participate
+    # "for free" in whatever plug-in ActiveRecord modules are mixed into the
+    # model classes, such as Hoodoo::ActiveRecord::Secure.
+    #
+    # See also:
+    #
+    # * http://guides.rubyonrails.org/active_record_basics.html
+    #
+    # Dependency Hoodoo::ActiveRecord::Secure is included automatically.
+    #
+    module Finder
+
+      # Instantiates this module when it is included:
+      #
+      # Example:
+      #
+      #     class SomeModel < ActiveRecord::Base
+      #       include Hoodoo::ActiveRecord::Finder
+      #       # ...
+      #     end
+      #
+      # +model+:: The ActiveRecord::Base descendant that is including
+      #           this module.
+      #
+      def self.included( model )
+        model.class_attribute(
+          :nz_co_loyalty_hoodoo_show_id_fields,
+          :nz_co_loyalty_hoodoo_search_with,
+          :nz_co_loyalty_hoodoo_filter_with,
+          {
+            :instance_predicate => false,
+            :instance_accessor  => false
+          }
+        )
+
+        unless model == Hoodoo::ActiveRecord::Base
+          model.send( :include, Hoodoo::ActiveRecord::Secure )
+          instantiate( model )
+        end
+
+        super( model )
+      end
+
+      # When instantiated in an ActiveRecord::Base subclass, all of the
+      # Hoodoo::ActiveRecord::Finder::ClassMethods methods are defined as
+      # class methods on the including class.
+      #
+      # This module depends upon Hoodoo::ActiveRecord::Secure, so that
+      # will be auto-included first if it isn't already.
+      #
+      # +model+:: The ActiveRecord::Base descendant that is including
+      #           this module.
+      #
+      def self.instantiate( model )
+        model.extend( ClassMethods )
+      end
+
+      # Collection of class methods that get defined on an including class via
+      # Hoodoo::ActiveRecord::Finder::included.
+      #
+      module ClassMethods
+
+        # "Polymorphic" find - support for finding a model by fields other
+        # than just +:id+, based on a single unique identifier. Use #acquire
+        # just like you'd use +find_by_id+ and only bother with it if you
+        # support finding a resource instance by +id+ _and_ one or more
+        # other model fields. Otherwise, just use +find_by_id+.
+        #
+        # In the model, you declare the list of fields _in_ _addition_ _to_
+        # +id+ by calling #acquire_with thus:
+        #
+        #     class SomeModel < ActiveRecord::Base
+        #       include Hoodoo::ActiveRecord::Finder
+        #       acquire_with ... # <list-of-other-fields>
+        #     end
+        #
+        # For example, maybe you allow some resource to be looked up by fields
+        # +id+ or +code+, both of which are independently unique sets. Since
+        # +id+ is always automatically included, you only need to do this:
+        #
+        #     class SomeModel < ActiveRecord::Base
+        #       include Hoodoo::ActiveRecord::Finder
+        #       acquire_with :code
+        #     end
+        #
+        # Then, in a resource's implementation:
+        #
+        #     def show( context )
+        #       found = SomeModel.acquire( context.request.ident )
+        #       return context.response.not_found( context.request.ident ) if found.nil?
+        #
+        #       # ...map 'found' to whatever resource you're representing,
+        #       # e.g. via a Hoodoo::Presenters::Base subclass with resource
+        #       # schema and the subclass's Hoodoo::Presenters::Base::render
+        #       # call, then...
+        #
+        #       context.response.set_resource( resource_representation_of_found )
+        #     end
+        #
+        # There is nothing magic "under the hood" - Hoodoo just tries to
+        # find records with a value matching the incoming identifier for
+        # each of the fields in turn. It starts with +id+ then runs through
+        # any other fields in the order given through #acquire_with.
+        #
+        # This can only be used <i>if your searched fields are strings</i> in
+        # the database. This includes, for example, the +id+ column; Hoodoo
+        # usually expects to be a string field holding a 32-character UUID. If
+        # any of the fields contain non-string types, attempts to use the
+        # #acquire mechanism (or a related one) may result in database errors
+        # due to type mismatches, depending upon the database engine in use.
+        #
+        # In more complex scenarious, you can just call #acquire at the end
+        # of any chain of AREL queries just as you would call ActiveRecord's
+        # own #find_by_id method, e.g.:
+        #
+        #     SomeModel.where( :foo => :bar ).acquire( context.request.ident )
+        #
+        # Usually for convenience you should use #acquire_in instead, or only
+        # call #acquire with (say) a secure scope via for example a call to
+        # Hoodoo::ActiveRecord::Secure::ClassMethods#secure. Other scopes may
+        # be needed depending on the mixins your model uses.
+        #
+        # +ident+:: The value to search for in the fields (attributes)
+        #           specified via #acquire_with, matched using calls to
+        #           <tt>where( attr => ident )</tt>.
+        #
+        # Returns a found model instance or +nil+ for no match.
+        #
+        def acquire( ident )
+          extra_fields = self.nz_co_loyalty_hoodoo_show_id_fields || []
+
+          id_fields = [ :id ] + extra_fields
+          id_fields.each do | field |
+
+            # This is fiddly.
+            #
+            # You must use a string with field substitution approach, rather
+            # than e.g. ".where( :field => :ident )". AREL/ActiveRecord will,
+            # in the latter case, compose rational SQL based on column data
+            # types. If you have an *integer* ID field, then, it'll try to
+            # convert a *string* ident to an integer. This can give Hilarious
+            # Consequences. Consider looking up on (integer) field "id" or
+            # (text) field "uuid", with a string ident of "1f294942..." - the
+            # text UUID would be fine, but the integer ID may end up with the
+            # UUID being "to_i"'d, yielding integer 1. If the ID field is
+            # looked at first, you're highly likely to find the wrong record.
+            #
+            # The solution is, as written, simple; just use the substitution
+            # approach rather than higher level AREL, causing a string-like SQL
+            # query on all adapters which SQL handles just fine for varying
+            # field data types.
+            #
+            # The caveat is that should the database object to mismatched type
+            # comparisons it will actually raise an error - we see this on
+            # for example PostgreSQL where a column is an integer but we try
+            # to match it against a string that cannot be cleanly converted to
+            # one (e.g. trying to find an integer column 'id' based on a text
+            # UUID value containing alphabetic characters). That is still
+            # preferable to looking up the wrong record!
+
+            checker = where( [ "\"#{ self.table_name }\".\"#{ field }\" = ?", ident ] )
+            return checker.first unless checker.count == 0
+          end
+
+          return nil
+        end
+
+        # Implicily secure, translated, dated etc. etc. version of #acquire,
+        # according to which modules are mixed into your model class. See
+        # Hoodoo::ActiveRecord::Support#full_scope_for to see the list of
+        # things that get included in the scope according to the mixins
+        # that are in use.
+        #
+        # For example, if you are using or at some point intend to mix in and
+        # use the mechanism described by the likes of
+        # Hoodoo::ActiveRecord::Secure::ClassMethods#secure, call here as a
+        # convenience to both obtain a secure context and find a record
+        # (with or without additional find-by fields other than +id+) in one
+        # go. Building on the example from
+        # Hoodoo::ActiveRecord::Secure::ClassMethods#secure, we might have an
+        # Audit model as follows:
+        #
+        #     class Audit < ActiveRecord::Base
+        #       include Hoodoo::ActiveRecord::Secure
+        #
+        #       secure_with( {
+        #         :creating_caller_uuid => :authorised_caller_uuid
+        #       } )
+        #
+        #       # Plus perhaps a call to "acquire_with"
+        #     end
+        #
+        # Then, in a resource's implementation:
+        #
+        #     def show( context )
+        #       found = SomeModel.acquire_in( context )
+        #       return context.response.not_found( context.request.ident ) if found.nil?
+        #
+        #       # ...map 'found' to whatever resource you're representing,
+        #       # e.g. via a Hoodoo::Presenters::Base subclass with resource
+        #       # schema and the subclass's Hoodoo::Presenters::Base::render
+        #       # call, then...
+        #
+        #       context.response.set_resource( resource_representation_of_found )
+        #     end
+        #
+        # The value of +found+ will be acquired within the secure context
+        # determined by the prevailing call context (and its session), so
+        # the data it finds is inherently correctly scoped - provided your
+        # model's Hoodoo::ActiveRecord::Secure::ClassMethods#secure_with
+        # call describes things correctly.
+        #
+        # This method is for convenience and safety - you can't accidentally
+        # forget the secure scope:
+        #
+        #     SomeModel.secure( context ).acquire( context.request.ident )
+        #
+        #     # ...has the same result as...
+        #
+        #     SomeModel.acquire_in( context )
+        #
+        # The same applies to forgetting dated scopes, translated scopes, or
+        # anything else that Hoodoo::ActiveRecord::Support#full_scope_for
+        # might include for you.
+        #
+        # Parameters:
+        #
+        # +context+:: Hoodoo::Services::Context instance describing a call
+        #             context. This is typically a value passed to one of
+        #             the Hoodoo::Services::Implementation instance methods
+        #             that a resource subclass implements.
+        #
+        # Returns a found model instance or +nil+ for no match.
+        #
+        def acquire_in( context )
+          scope = Hoodoo::ActiveRecord::Support.full_scope_for( self, context )
+          return scope.acquire( context.request.ident )
+        end
+
+        # Describe the list of model fields _in_ _addition_ _to_ +id+ which
+        # are to be used to "find-by-identifier" through calls #acquire and
+        # #acquire_in. See those for more details.
+        #
+        # *args:: One or more field names as Strings or Symbols.
+        #
+        def acquire_with( *args )
+          self.nz_co_loyalty_hoodoo_show_id_fields = args
+        end
+
+        # Generate an ActiveRecord::Relation instance which can be used to
+        # count, retrieve or further refine a list of model instances from
+        # the database.
+        #
+        # Usually for convenience you should use #list_in instead, or only
+        # call #acquire with (say) a secure scope via for example a call to
+        # Hoodoo::ActiveRecord::Secure::ClassMethods#secure. An example of
+        # this second option is shown below.
+        #
+        # Pass a Hoodoo::Services::Request::ListParameters instance, e.g.
+        # via the Hoodoo::Services::Context instance passed to resource
+        # endpoint implementations and accessor +context.request.list+. It
+        # takes into account the list offset, limit, sort key and sort
+        # direction automatically. In addition, it can do simple search and
+        # filter operations if search and filter mappings are set up via
+        # #search_with and #filter_with.
+        #
+        # For exampe, in a simple case where a model can be listed without
+        # any unusual constraints, we might do this:
+        #
+        #     class SomeModel < ActiveRecord::Base
+        #       include Hoodoo::ActiveRecord::Finder
+        #
+        #       search_with # ...<field-to-search-info mapping>
+        #       # ...and/or...
+        #       filter_with # ...<field-to-search-info mapping>
+        #     end
+        #
+        #     # ...then, in the resource implementation...
+        #
+        #     def list( context )
+        #       finder = SomeModel.list( context.request.list )
+        #       results = finder.all.map do | item |
+        #         # ...map database objects to response objects...
+        #       end
+        #       context.response.set_resources( results, finder.dataset_size )
+        #     end
+        #
+        # Note the use of helper method #dataset_size to count the total
+        # amount of results in the dataset without pagination.
+        #
+        # The service middleware enforces sane values for things like list
+        # offsets, sort keys and so-on according to service interface
+        # definitions, so if using the middleware you don't need to do any
+        # extra checking yourself.
+        #
+        # Since the returned object is just a relation, adding further
+        # constraints is easy - call things like +where+, +group+ and so-on
+        # as normal. You can also list in a secure context via the included
+        # Hoodoo::ActiveRecord::Secure::ClassMethods#secure, assuming
+        # appropriate data is set in the model via
+        # Hoodoo::ActiveRecord::Secure::ClassMethods#secure_with:
+        #
+        #     def list( context )
+        #       finder = SomeModel.secure( context ).list( context.request.list )
+        #       finder = finder.where( :additional_filter => 'some value' )
+        #       results = finder.all.map do | item |
+        #         # ...map database objects to response objects...
+        #       end
+        #       context.response.set_resources( results, finder.dataset_size )
+        #     end
+        #
+        # Since it's just a chained scope, you can call in any order:
+        #
+        #     SomeModel.secure( context ).list( context.request.list )
+        #
+        #     # ...has the same result as...
+        #
+        #     SomeModel.list( context.request.list ).secure( context )
+        #
+        # Any of the ActiveRecord::QueryMethods can be called on the returned
+        # value. See:
+        #
+        # http://api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html
+        #
+        # +list_parameters+:: Hoodoo::Services::Request::ListParameters
+        #                     instance, typically obtained from the
+        #                     Hoodoo::Services::Context instance passed to
+        #                     a service implementation in
+        #                     Hoodoo::Services::Implementation#list, via
+        #                     +context.request.list+ (i.e.
+        #                     Hoodoo::Services::Context#request
+        #                     / Hoodoo::Services::Request#list).
+        #
+        def list( list_parameters )
+          finder = all.offset( list_parameters.offset ).limit( list_parameters.limit )
+          finder = finder.order( list_parameters.sort_data )
+
+          # DRY up the 'each' loops below. Use a Proc not a method because any
+          # methods we define will end up being defined on the including Model,
+          # increasing the chance of a name collision.
+          #
+          dry_proc = Proc.new do | data, attr, proc |
+            value = data[ attr ]
+            proc.call( attr, value ) unless value.nil?
+          end
+
+          search_map = self.nz_co_loyalty_hoodoo_search_with
+
+          unless search_map.nil?
+            search_map.each do | attr, proc |
+              args   = dry_proc.call( list_parameters.search_data, attr, proc )
+              finder = finder.where( *args ) unless args.nil?
+            end
+          end
+
+          filter_map = self.nz_co_loyalty_hoodoo_filter_with
+
+          unless filter_map.nil?
+            filter_map.each do | attr, proc |
+              args   = dry_proc.call( list_parameters.filter_data, attr, proc )
+              finder = finder.where.not( *args ) unless args.nil?
+            end
+          end
+
+          return finder
+        end
+
+        # Implicily secure, translated, dated etc. etc. version of #list,
+        # according to which modules are mixed into your model class. See
+        # Hoodoo::ActiveRecord::Support#full_scope_for to see the list of
+        # things that get included in the scope according to the mixins
+        # that are in use.
+        #
+        # For example, if you have included Hoodoo::ActiveRecord::Secure,
+        # this method provides you with an implicitly secure query. Read the
+        # documentation on #acquire_in versus #acquire for information
+        # on the use of secure scopes; as with #acquire_in and the "Secure"
+        # mixin, this method becomes for convenience and safety - you
+        # can't accidentally forget the secure scope:
+        #
+        #     SomeModel.secure( context ).list( context.request.list )
+        #
+        #     # ...has the same result as...
+        #
+        #     SomeModel.list_in( context )
+        #
+        # The same applies to forgetting dated scopes, translated scopes, or
+        # anything else that Hoodoo::ActiveRecord::Support#full_scope_for
+        # might include for you.
+        #
+        # +context+:: Hoodoo::Services::Context instance describing a call
+        #             context. This is typically a value passed to one of
+        #             the Hoodoo::Services::Implementation instance methods
+        #             that a resource subclass implements.
+        #
+        # Returns a secure list scope, for either further modification with
+        # query methods like +where+ or fetching from the database with +all+.
+        #
+        def list_in( context )
+          scope = Hoodoo::ActiveRecord::Support.full_scope_for( self, context )
+          return scope.list( context.request.list )
+        end
+
+        # Given some scope - typically that obtained from a prior call to
+        # #list or #list_in, with possibly other query modifiers too - return
+        # the total dataset size. This is basically a +COUNT+ operation, but
+        # run without offset or limit considerations (ignoring pagination).
+        #
+        # This is particularly useful if you are calling
+        # Hoodoo::Services::Response#set_resources and want to fill in its
+        # +dataset_size+ parameter.
+        #
+        def dataset_size
+          return all.limit( nil ).offset( nil ).count
+        end
+
+        # Specify a search mapping for use by #list to automatically restrict
+        # list results.
+        #
+        # In the simplest case, search query string entries and model field
+        # (attribute) names are assumed to be the same; if you wanted to
+        # search for values of model attributes +name+ and +colour+ using
+        # query string entries of +name+ and +colour+ you would just do this:
+        #
+        #     class SomeModel < ActiveRecord::Base
+        #       search_with(
+        #         :name   => nil,
+        #         :colour => nil
+        #       )
+        #     end
+        #
+        # The +nil+ values mean a default, case sensitive match is performed
+        # with the query string keys and values mapping directly to model
+        # query attribute names and values.
+        #
+        # More complex example where +colour+ is matched verbatim, but +name+
+        # is matched case-insensitive, assuming PostgreSQL's ILIKE is there:
+        #
+        #     class SomeModel < ActiveRecord::Base
+        #       search_with(
+        #         :name => Proc.new { | attr, value |
+        #           [ 'name ILIKE ?', value ]
+        #         },
+        #         :colour => nil
+        #       )
+        #     end
+        #
+        # Extending the above to use a single Proc that handles case
+        # insensitive matches across all attributes:
+        #
+        #     class SomeModel < ActiveRecord::Base
+        #       CI_MATCH = Proc.new { | attr, value |
+        #         [ "#{ attr } ILIKE ?", value ]
+        #       }
+        #
+        #       search_with(
+        #         :name   => CI_MATCH,
+        #         :colour => CI_MATCH
+        #       )
+        #     end
+        #
+        # If you wanted to match against an array of possible matches, something
+        # like this would work:
+        #
+        #     ARRAY_MATCH = Proc.new { | attr, value |
+        #       [ { attr => [ value ].flatten } ]
+        #     }
+        #
+        # Note the returned *array* (see input parameter details) inside which
+        # the usual hash syntax for AREL +.where+-style queries is present.
+        #
+        # To help out with common cases other than just specifying +nil+, the
+        # Hoodoo::ActiveRecord::Finder::SearchHelper class provides a method
+        # chaining approach which builds up the Hash used by #search_with and
+        # filter_with. See that class's API documentation for details.
+        #
+        # *args:: A Hash. Keys are both search field names and model attribute
+        #         names, unless overridden by values; values of +nil+ are used
+        #         for simple cases - "where( { attr_name => value } )" will be
+        #         the resulting query modification. Alternatively, pass a
+        #         callable Proc/Lambda. This is pased the attribute under
+        #         consideration (and so you can ignore that and query against
+        #         one or more different-named model attributes) and the
+        #         context-caller-supplied value to search for. Return *AN*
+        #         *ARRAY* of parameters to pass to +where+. For parameters to
+        #         +where+, see:
+        #
+        #         http://api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html#method-i-where
+        #
+        #         The Hash keys giving the search attribute names can be
+        #         specified as Strings or Symbols.
+        #
+        #         See Hoodoo::ActiveRecord::Finder::SearchHelper for methods
+        #         which assist with filling in non-nil values for this Hash.
+        #
+        def search_with( hash )
+          self.nz_co_loyalty_hoodoo_search_with = Hoodoo::ActiveRecord::Support.process_to_map( hash )
+        end
+
+        # As #search_with, but used in +where.not+ queries.
+        #
+        # <b><i>IMPORTANT:</i></b> Beware +null+ column values and filters
+        # given SQL's strange behaviour with such things. The search helpers
+        # in Hoodoo::ActiveRecord::Finder::SearchHelper class will work as
+        # logically expected ("field not 'foo'" will find fields with a null
+        # value), though if you're expecting SQL-like behaviour it might come
+        # as a surprise! Using <tt>...AND field IS NOT NULL</tt> in queries
+        # for +filter_with+ tends to work reasonably when the query is
+        # negated for filter use via <tt>...NOT(...)...</tt>. Examining the
+        # implementation of Hoodoo::ActiveRecord::Finder::SearchHelper may
+        # help if confused. See also:
+        #
+        # * https://en.wikipedia.org/wiki/Null_(SQL)
+        #
+        # +map+:: As #search_with.
+        #
+        def filter_with( hash )
+          self.nz_co_loyalty_hoodoo_filter_with = Hoodoo::ActiveRecord::Support.process_to_map( hash )
+        end
+
+        # Deprecated interface replaced by #acquire. Instead of:
+        #
+        #     Model.polymorphic_find( foo, ident )
+        #
+        # ...use:
+        #
+        #     foo.acquire( ident )
+        #
+        # This implementation is for legacy support and just calls through
+        # to #acquire.
+        #
+        # +finder+:: #acquire is called on this.
+        #
+        # +ident+::  Passed to #acquire.
+        #
+        # Returns a found model instance or +nil+ for no match.
+        #
+        def polymorphic_find( finder, ident )
+          $stderr.puts( 'Hoodoo:ActiveRecord::Finder#polymorphic_find is deprecated - use "foo.acquire( ident )" instead of "Model.polymorphic_find( foo, ident )"' )
+          finder.acquire( ident ) # Ignore 'finder'
+        end
+
+        # Deprecated interface replaced by #acquire_with (this is an alias).
+        #
+        # *args:: Passed to #acquire_with.
+        #
+        def polymorphic_id_fields( *args )
+          $stderr.puts( 'Hoodoo:ActiveRecord::Finder#polymorphic_id_fields is deprecated - rename call to "#acquire_with"' )
+          acquire_with( *args )
+        end
+
+        # Deprecated interface replaced by #list (this is an alias).
+        #
+        # +list_parameters+:: Passed to #list.
+        #
+        def list_finder( list_parameters )
+          $stderr.puts( 'Hoodoo:ActiveRecord::Finder#list_finder is deprecated - rename call to "#list"' )
+          return list( list_parameters )
+        end
+
+        # Deprecated interface replaced by #search_with (this is an alias).
+        #
+        # +map+:: Passed to #search_with.
+        #
+        def list_search_map( map )
+          $stderr.puts( 'Hoodoo:ActiveRecord::Finder#list_search_map is deprecated - rename call to "#search_with"' )
+          search_with( map )
+        end
+
+        # Deprecated interface replaced by #filter_with (this is an alias).
+        #
+        # +map+:: Passed to #filter_with.
+        #
+        def list_filter_map( map )
+          $stderr.puts( 'Hoodoo:ActiveRecord::Finder#list_filter_map is deprecated - rename call to "#filter_with"' )
+          filter_with( map )
+        end
+      end
+    end
+  end
+end