hoodoo 2.0.0 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: dc0db0a009b321df89a2eb2e8a879c76bc875bb9
-  data.tar.gz: 29c85538f05080287181a67d3292b72f950f1872
+SHA256:
+  metadata.gz: fcb6260d51d3dd934b17047fa2db6abe3b9dc25f7f95f81be5bd0af5035ff019
+  data.tar.gz: 97f48231ab533c2aec1557679007d7ea95f5e10c0aeb262cc8a1c84d2bf611ae
 SHA512:
-  metadata.gz: 8519c31178c7439fc57888851eac50409e71c8225dfc0fd5421da540e370ab01ef92423f3a5753195efea9ca01f4954ee68d33d09fc083470a6ac5eade962f70
-  data.tar.gz: 45d7b58441e42e224624123c74f15f812880a074ea07648628f49741a3a3ba918456632b456a6b617b73d65935884ec16ad30e92176e19cc939af93fcc3437c0
+  metadata.gz: 30633c2155b09f06ac6d75c53aef460b4c04b426019a11eb9bb08040ece7586295b875ec8f3034c87e3e4a80945c1ebd0514444f2437bccef3049cbf5b616080
+  data.tar.gz: f12b6ba55fd0ad9a8f7f66e1e6924a98cbbba2eed5999cf8b14a6810c15529bff0eaf5d2fe472b5d757e15bd5877baba9724e88caab2af846a2e6394b3ecd2ae

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

@@ -177,6 +177,17 @@ module Hoodoo
 
           self.nz_co_loyalty_hoodoo_dated_with = history_klass
 
+          # Enable the monkey patch to the Finder module's '#acquire_in' class
+          # method, if need be.
+
+          if self.include?( Hoodoo::ActiveRecord::Finder )
+            Hoodoo::Monkey.register(
+              target_unit:      self,
+              extension_module: Hoodoo::Monkey::Patch::ActiveRecordDatedFinderAdditions
+            )
+
+            Hoodoo::Monkey.enable( extension_module: Hoodoo::Monkey::Patch::ActiveRecordDatedFinderAdditions )
+          end
         end
 
         # If a prior call has been made to #dating_enabled then this method
@@ -289,7 +300,7 @@ module Hoodoo
         #
         # +unquoted_column_names+:: (Optional) An Array of Strings giving one
         #                           or more column names to use for the query.
-        #                           If omitted, all model attribtues are used
+        #                           If omitted, all model attributes are used
         #                           as columns. If the "id" column is not
         #                           included in the Array, it will be added
         #                           anyway as this column is mandatory. The

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

@@ -118,6 +118,29 @@ module Hoodoo
           Hoodoo::ActiveRecord::Support.full_scope_for( self, context )
         end
 
+        # As #scoped_in, but intentionally omits any historical dating modules
+        # from the returned scope. The scope might then address both historic
+        # and contemporary records, depending on whether you are using manual
+        # or automatic dating.
+        #
+        # +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.
+        #
+        # See also:
+        #
+        # * Hoodoo::ActiveRecord::Dated
+        # * Hoodoo::ActiveRecord::ManuallyDated
+        #
+        def scoped_undated_in( context )
+          Hoodoo::ActiveRecord::Support.add_undated_scope_to(
+            self.all(), # "all" -> returns anonymous scope
+            self,
+            context
+          )
+        end
+
         # "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
@@ -173,10 +196,10 @@ module Hoodoo
         #
         #     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.
+        # Usually for convenience you should use #acquire_in! or 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
@@ -246,6 +269,10 @@ module Hoodoo
         # The same applies to forgetting dated scopes, translated scopes, or
         # anything else that #scoped_in might include for you.
         #
+        # An even higher-level method, taking care of error handling as well,
+        # is #acquire_in!. You may prefer to call this higher level interface
+        # if you don't object to the way it modifies +context+.
+        #
         # Parameters:
         #
         # +context+:: Hoodoo::Services::Context instance describing a call
@@ -253,23 +280,93 @@ module Hoodoo
         #             the Hoodoo::Services::Implementation instance methods
         #             that a resource subclass implements.
         #
-        # Returns a found model instance or +nil+ for no match.
+        # See also:
+        #
+        # * Hoodoo::ActiveRecord::Finder::ClassMethods#acquire_in!
+        # * Hoodoo::Services::Response#not_found
+        # * Hoodoo::Services::Response#contemporary_exists
+        #
+        # Returns a found model instance or +nil+ for no match / on error.
         #
         def acquire_in( context )
-          return scoped_in( context ).acquire( context.request.ident )
+          scoped_in( context ).acquire( context.request.ident )
+        end
+
+        # A higher level equivalent of #acquire_in in which the given context
+        # will be updated with error information if the requested item cannot
+        # be found. Although modifying the passed-in context may be considered
+        # an unclean pattern, it does allow extensions to that mechanism. For
+        # example, in the presence of the Hoodoo::ActiveRecord::Dated or
+        # Hoodoo::ActiveRecord::ManuallyDated modules, an additional error
+        # entry of +generic.contemporary_exists+ will be added if conditions
+        # warrant it.
+        #
+        # At the time of writing only this and/or +generic.not_found+ can be
+        # added, but in future other mixin modules may cause other additions,
+        # making preferential use of this method over #acquire_in a good way
+        # to future-proof against such changes.
+        #
+        # To be sure that these additions work, always include this module
+        # before any others (unless documentation indicates a differing
+        # inclusion order requirement), so that the dating module is able to
+        # detect the presence of this Finder module and enable the extensions.
+        #
+        # 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.
+        #
+        # See also:
+        #
+        # * Hoodoo::ActiveRecord::Finder::ClassMethods#acquire_in
+        # * Hoodoo::Services::Response#not_found
+        # * Hoodoo::Services::Response#contemporary_exists
+        #
+        # Returns a found model instance or +nil+ for no match / on error,
+        # wherein +context+ will have been updated with error details.
+        #
+        # Example, following on from those for #acquire_in:
+        #
+        #     def show( context )
+        #       resource = SomeModel.acquire_in!( context )
+        #       return if context.response.halt_processing? # Or just use 'if resource.nil?'
+        #
+        #       # ...else render...
+        #     end
+        #
+        def acquire_in!( context )
+
+          # The method is patched internally by Hoodoo::ActiveRecord::Dated
+          # and Hoodoo::ActiveRecord::ManuallyDated. The patches add in a
+          # +generic.contemporary_exists+ error using appropriate checks for
+          # a contemporary record, where necessary. This way, any performance
+          # overhead that might be introduced by the added code is only
+          # present when a class uses one of the dating modules.
+          #
+          # It's an internal patch and not intended for additional external
+          # changes, so it does not use the public "monkey_" naming prefix.
+
+          result = acquire_in( context )
+          context.response.not_found( context.request.ident ) if result.nil?
+
+          return result
         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 methods for more details.
+        # are to be used to "find-by-identifier" through calls #acquire,
+        # #acquire_in and #acquire_in!. See those methods for more details.
         #
         # Fields will be searched in the order listed. If duplicate items are
         # present, the first occurrence is kept and the rest are removed.
         #
         # *args:: One or more field names as Strings or Symbols.
         #
-        # See also: #acquired_with
-        #           #acquire_with_id_substitute
+        # See also:
+        #
+        # * #acquired_with
+        # * #acquire_with_id_substitute
         #
         def acquire_with( *args )
           self.nz_co_loyalty_hoodoo_show_id_fields = args.map( & :to_s )
@@ -277,30 +374,32 @@ module Hoodoo
         end
 
         # Return the list of model fields _in_ _addition_ _to_ +id+ which
-        # are being used to "find-by-identifier" through calls to #acquire
-        # and #acquire_in. The returned Array contains de-duplicated String
-        # values only.
+        # are being used to "find-by-identifier" through calls to #acquire,
+        # #acquire_in and #acquire_in!. The returned Array contains
+        # de-duplicated String values only.
         #
-        # See also: #acquire_with
-        #           #acquire_with_id_substitute
+        # See also:
+        #
+        # * #acquire_with
+        # * #acquire_with_id_substitute
         #
         def acquired_with
           self.nz_co_loyalty_hoodoo_show_id_fields || []
         end
 
-        # The #acquire_with method allows methods like #acquire and
-        # #acquire_in to transparently find a record based on _one_ _or_
-        # _more_ columns in the database. The columns (and corresponding
-        # model attributes) specified through a call to #acquire_with will
-        # normally be used _in_ _addition_ _to_ a lookup on the +id+
-        # column, but in rare circumstances you might need to bypass that
-        # and use an entirely different field. This is distinct from the
-        # ActiveRecord-level concept of the model's primary key column.
+        # The #acquire_with method allows methods like #acquire, #acquire_in
+        # and #acquire_in! to transparently find a record based on _one_ _or_
+        # _more_ columns in the database. The columns (and corresponding model
+        # attributes) specified through a call to #acquire_with will normally
+        # be used _in_ _addition_ _to_ a lookup on the +id+ column, but in rare
+        # circumstances you might need to bypass that and use an entirely
+        # different field. This is distinct from the ActiveRecord-level concept
+        # of the model's primary key column.
         #
         # To permanently change the use of the +id+ attribute as the first
-        # search parameter in #acquire and #acquire_in, by modifying the
-        # behaviour of #acquisition_scope, call here and pass in the new
-        # attribute name.
+        # search parameter in #acquire, #acquire_in and #acquire_in! by
+        # modifying the behaviour of #acquisition_scope, call here and pass in
+        # the new attribute name.
         #
         # +attr+:: Attribute name as a Symbol or String to use _instead_
         #          of +id+, as a default mandatory column in
@@ -310,10 +409,10 @@ module Hoodoo
           self.nz_co_loyalty_hoodoo_show_id_substitute = attr.to_sym
         end
 
-        # Back-end to #acquire and therefore, in turn, #acquire_in. Returns
-        # an ActiveRecord::Relation instance which scopes the search for a
-        # record by +id+ and across any other columns specified by
-        # #acquire_with, via SQL +OR+.
+        # Back-end to #acquire and therefore, in turn, #acquire_in and
+        # #acquire_in!. Returns an ActiveRecord::Relation instance which
+        # scopes the search for a record by +id+ and across any other columns
+        # specified by #acquire_with, via SQL +OR+.
         #
         # If you need to change the use of attribute +id+, specify a
         # different attribute with #acquire_with_id_substitute. In that case,
@@ -595,9 +694,9 @@ module Hoodoo
         #
         #     counter = Proc.new do | sql |
         #       begin
-        #         sql = sql.gsub( "'", "''" ) # Escape SQL for insertion below
+        #         escaped_sql = sql.gsub( "'", "''" )
         #         ActiveRecord::Base.connection.execute(
-        #           "SELECT estimated_count('#{ sql }')"
+        #           "SELECT estimated_count('#{ escaped_sql }')"
         #         ).first[ 'estimated_count' ].to_i
         #       rescue
         #         nil
@@ -733,7 +832,9 @@ module Hoodoo
         # 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:
+        # help if confused.
+        #
+        # See also:
         #
         # * https://en.wikipedia.org/wiki/Null_(SQL)
         #

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

@@ -111,9 +111,9 @@ module Hoodoo
     #
     # === Show and List
     #
-    # You might use Hoodoo::ActiveRecord::Finder#list_in or
-    # Hoodoo::ActiveRecord::Finder#acquire_in for +list+ or +show+ actions;
-    # such code changes from e.g.:
+    # You might use Hoodoo::ActiveRecord::Finder::ClassMethods#list_in or
+    # Hoodoo::ActiveRecord::Finder::ClassMethods#acquire_in for +list+ or
+    # +show+ actions; such code changes from e.g.:
     #
     #     SomeModel.list_in( context )
     #
@@ -487,11 +487,23 @@ module Hoodoo
             }
           )
 
-          # Lastly, we must specify an acquisition scope that's based on
-          # the "uuid" column only and *not* the "id" column.
+          # We must specify an acquisition scope that's based on the "uuid"
+          # column only and *not* the "id" column.
 
           acquire_with_id_substitute( :uuid )
 
+          # Finally, enable the monkey patch to the Finder module's
+          # '#acquire_in' class method, if need be.
+
+          if self.include?( Hoodoo::ActiveRecord::Finder )
+            Hoodoo::Monkey.register(
+              target_unit:      self,
+              extension_module: Hoodoo::Monkey::Patch::ActiveRecordManuallyDatedFinderAdditions
+            )
+
+            Hoodoo::Monkey.enable( extension_module: Hoodoo::Monkey::Patch::ActiveRecordManuallyDatedFinderAdditions )
+          end
+
         end
 
         # If a prior call has been made to #manual_dating_enabled then this

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

@@ -4,7 +4,8 @@
 #
 # Purpose:: Supplementary helper class included by "finder.rb". See
 #           Hoodoo::ActiveRecord::Finder, especially
-#           Hoodoo::ActiveRecord::Finder#search_with, for details.
+#           Hoodoo::ActiveRecord::Finder::ClassMethods#search_with, for
+#           details.
 # ----------------------------------------------------------------------
 #           09-Jul-2015 (ADH): Created.
 ########################################################################

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

@@ -82,9 +82,10 @@ module Hoodoo
       end
 
       # Takes a Hash of possibly-non-String keys and with +nil+ values or
-      # Proc instances appropriate for Hoodoo::ActiveRecord::Finder#search_with
-      # / #filter_with. Returns a similar Hash with all-String keys and a Proc
-      # for every value.
+      # Proc instances appropriate for
+      # Hoodoo::ActiveRecord::Finder::ClassMethods#search_with /
+      # Hoodoo::ActiveRecord::Finder::ClassMethods#filter_with. Returns a
+      # similar Hash with all-String keys and a Proc for every value.
       #
       # +hash+:: Hash Symbol or String keys and Proc instance or +nil+
       #          values.
@@ -142,15 +143,44 @@ module Hoodoo
           prevailing_scope = prevailing_scope.manually_dated( context )
         end
 
+        return self.add_undated_scope_to( prevailing_scope, klass, context )
+      end
+
+      # Back-end of sorts for ::full_scope_for. Given a base scope (e.g.
+      # '<tt>Model.all</tt>'), applies all available appropriate scoping
+      # additions included by that model, such as Hoodoo::ActiveRecord::Secure
+      # and Hoodoo::ActiveRecord::Translated, _except_ for the dating modules
+      # Hoodoo::ActiveRecord::Dated and Hoodoo::ActiveRecord::ManuallyDated.
+      #
+      # If you wish to use dating as well, call ::full_scope_for instead.
+      #
+      # +base_scope+:: The ActiveRecord::Relation instance providing the base
+      #                scope to which additions will be made.
+      #
+      # +klass+::      The ActiveRecord::Base subclass _class_ (not instance)
+      #                which is making the call here. This is the entity which
+      #                is checked for module inclusions to determine how the
+      #                query chain should be assembled.
+      #
+      # +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 the given input scope, with additional conditions added for
+      # any Hoodoo ActiveRecord extension modules included by the ActiveRecord
+      # model class that the scope targets.
+      #
+      def self.add_undated_scope_to( base_scope, klass, context )
         if klass.include?( Hoodoo::ActiveRecord::Secure )
-          prevailing_scope = prevailing_scope.secure( context )
+          base_scope = base_scope.secure( context )
         end
 
         if klass.include?( Hoodoo::ActiveRecord::Translated )
-          prevailing_scope = prevailing_scope.translated( context )
+          base_scope = base_scope.translated( context )
         end
 
-        return prevailing_scope
+        return base_scope
       end
 
     end

data/lib/hoodoo/errors/error_descriptions.rb

@@ -97,6 +97,7 @@ module Hoodoo
 
       errors_for 'generic' do
         error 'not_found',              status: 404, message: 'Resource not found',            reference: [ :ident ]
+        error 'contemporary_exists',    status: 404, message: 'Contemporary record exists',    reference: [ :ident ]
         error 'malformed',              status: 422, message: 'Malformed payload'
         error 'required_field_missing', status: 422, message: 'Required field missing',        reference: [ :field_name ]
         error 'invalid_string',         status: 422, message: 'Invalid string format',         reference: [ :field_name ]

data/lib/hoodoo/monkey.rb

@@ -10,6 +10,9 @@
 ########################################################################
 
 require 'hoodoo/monkey/monkey'
+
+require 'hoodoo/monkey/patch/active_record_dated_finder_additions'
+require 'hoodoo/monkey/patch/active_record_manually_dated_finder_additions'
+require 'hoodoo/monkey/patch/datadog_traced_amqp'
 require 'hoodoo/monkey/patch/newrelic_middleware_analytics'
 require 'hoodoo/monkey/patch/newrelic_traced_amqp'
-require 'hoodoo/monkey/patch/datadog_traced_amqp'

data/lib/hoodoo/monkey/patch/active_record_dated_finder_additions.rb

@@ -0,0 +1,52 @@
+########################################################################
+# File::    active_record_dated_finder_additions.rb
+# (C)::     Loyalty New Zealand 2017
+#
+# Purpose:: Extend
+#           Hoodoo::ActiveRecord::Finder::ClassMethods#acquire_in! so
+#           that it adds error +generic.contemporary_exists+ to the
+#           provided +context+ if a dated instance is absent.
+# ----------------------------------------------------------------------
+#           01-Nov-2017 (ADH): Created.
+########################################################################
+
+module Hoodoo
+  module Monkey
+    module Patch
+
+      # Extend Hoodoo::ActiveRecord::Finder::ClassMethods#acquire_in! so
+      # that it adds error +generic.contemporary_exists+ to the provided
+      # +context+ if a dated instance is absent.
+      #
+      module ActiveRecordDatedFinderAdditions
+
+        # Class methods to patch over an ActiveRecord::Base subclass
+        # which includes Hoodoo::ActiveRecord::Finder and
+        # Hoodoo::ActiveRecord::Dated.
+        #
+        module ClassExtensions
+
+          # See Hoodoo::ActiveRecord::Finder::ClassMethods#acquire_in! for
+          # details. Calls that method then, upon error, checks to see if a
+          # contemporary version of the resource exists and adds error
+          # +generic.contemporary_exists+ to the given +context+ if so.
+          #
+          def acquire_in!( context )
+            result = super( context )
+
+            if result.nil? && context.request.dated_at
+              ident               = context.request.ident
+              contemporary_result = scoped_undated_in( context ).acquire( ident )
+
+              context.response.contemporary_exists( ident ) if contemporary_result.present?
+            end
+
+            return result
+          end
+
+        end
+      end
+
+    end # module Patch
+  end   # module Monkey
+end     # module Hoodoo