hoodoo 2.5.1 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: bcd6275929dde876479da0087f2eef17e4d9fd3c8606182daeff2fd4c02c35c9
-  data.tar.gz: 3763e2d462802bbdae8240864e7bf73b83eb5458675da127af70edba8013dc1b
+SHA1:
+  metadata.gz: cbae2491898cb113ffb0d3b9580e860e050d0fd5
+  data.tar.gz: d7dd9c51af9a0015572d9cb46d5a0fb63ee679c4
 SHA512:
-  metadata.gz: 6492416bb7afa5d8e7d9a23169293f055c73a6b9e8c63362f65b08ce7f49bd219874be90480ea7156c02373725e8088b19f9dfdda3a9ba2329b3037b7bc8b958
-  data.tar.gz: a8142c1c0973b77b1101af5f757b088b81a11bac48cce8597691288dcc288c8a786efd1ea6dd16820c44b9c222fb8df351cb739e6a2a6ea3e248f09b3943bacb
+  metadata.gz: 1e2bf59ec7c80eb94e45a3cb549f18f783b4fce0d5b263c4da9b92b7bf01c69b32f8a0980f5ce25f7a7ebc4bff5f0d60d63e2b51dea93784491382abc58f0571
+  data.tar.gz: 0a55cfb887c0fbf48594081bc2cd44e51b48c3e46dbc22018937acfc6645caca60e1981fcc3f49dea5883b8a925ae37dc1e9c2972e88472ae7436d7957651795

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

@@ -393,8 +393,9 @@ module Hoodoo
         )
 
         unless model == Hoodoo::ActiveRecord::Base
-          model.send( :include, Hoodoo::ActiveRecord::UUID )
+          model.send( :include, Hoodoo::ActiveRecord::UUID   )
           model.send( :include, Hoodoo::ActiveRecord::Finder )
+
           instantiate( model )
         end
 

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

@@ -9,6 +9,8 @@
 #           25-Nov-2014 (ADH): Created.
 ########################################################################
 
+require 'hoodoo/active/active_record/security_helper'
+
 module Hoodoo
   module ActiveRecord
 
@@ -58,6 +60,16 @@ module Hoodoo
         model.extend( ClassMethods )
       end
 
+      # Convenience constant defining an equals-single-security-value wildcard
+      # security exemption using the String '*'.
+      #
+      OBJECT_EQLS_STAR = Hoodoo::ActiveRecord::Secure::SecurityHelper::eqls_wildcard( '*' )
+
+      # Convenience constant defining an included-in-enumerable-security-value
+      # wildcard security excemption using the String '*'.
+      #
+      ENUMERABLE_INCLUDES_STAR = Hoodoo::ActiveRecord::Secure::SecurityHelper::includes_wildcard( '*' )
+
       # Collection of class methods that get defined on an including class via
       # Hoodoo::ActiveRecord::Secure::included.
       #
@@ -69,7 +81,9 @@ module Hoodoo
         # alternative argument generator is given in the longhand form's
         # value Hash's +:using+ key.
         #
-        DEFAULT_SECURE_PROC = Proc.new { | model_class, database_column_name, session_field_value | [ { database_column_name => session_field_value } ] }
+        DEFAULT_SECURE_PROC = Proc.new do | model_class, database_column_name, session_field_value |
+          [ { database_column_name => session_field_value } ]
+        end
 
         # The core of out-of-the-box Hoodoo data access security layer.
         #
@@ -255,6 +269,9 @@ module Hoodoo
         # +using+::               See the _Advanced_ _query_ _conditions_
         #                         section later for details.
         #
+        # +exemptions+::          See the _Security_ _exemptions_ section later
+        #                         for details.
+        #
         # To help clarify the above, the following two calls to #secure_with
         # have exactly the same effect.
         #
@@ -320,7 +337,7 @@ module Hoodoo
         #
         # This leads to SQL along the following lines:
         #
-        #    AND ("model_table"."creating_caller_uuid" = '[val]')
+        #    AND ("model_table"."creating_caller_uuid" IN ('[val]'))
         #
         # ...where <tt>val</tt> is from the Session +authorised_caller_uuids+
         # data in the +scoping+ section (so this might be an SQL +IN+ rather
@@ -352,7 +369,7 @@ module Hoodoo
         #
         # ...yields something like:
         #
-        #     AND ( "model_table"."creating_caller_uuid" = '[val]' OR "model_table"."other_column_name" = '[val]' )
+        #     AND ( "model_table"."creating_caller_uuid" IN ('[val]') OR "model_table"."other_column_name" IN ('[val]') )
         #
         # A Proc specified with +:using+ is called with:
         #
@@ -369,6 +386,92 @@ module Hoodoo
         # +where+ via <tt>where( *returned_values )</tt> as part of the wider
         # query chain.
         #
+        # == Security exemptions
+        #
+        # Sometimes you might want a security bypass mechanism for things like
+        # a Superuser style caller that can "see everything". It's more secure,
+        # where possible and scalable, to simply have the session data match
+        # every known value of some particular secured-with quantity, but this
+        # might get unwieldy. "WHERE IN" queries with hundreds or thousands of
+        # listed items can cause problems!
+        #
+        # Noting that with any security exemption there is elevated risk, you
+        # can use the +:exemptions+ key to provide a Proc which is passed the
+        # secure value(s) under consideration (the data taken directly from
+        # the session scoping section) and evaluates to +true+ if the value(s)
+        # indicate that a security exemption applies, else evaluates "falsey"
+        # for normal behaviour. We say "value(s)" here as a single key used to
+        # read from the scoping section of a session may yield either a simple
+        # value such as a String, or an Enumerable object such as an array of
+        # many Strings.
+        #
+        # If the Proc evaluates to +true+, the result is no modification to the
+        # secure scope chain being constructed for the secured ActiveRecord
+        # query the caller will eventually run. Helper methods which construct
+        # common use case Procs are present in
+        # Hoodoo::ActiveRecord::Secure::SecurityHelper and there are
+        # convenience constants defined in Hoodoo::ActiveRecord::Secure, such
+        # as Hoodoo::ActiveRecord::Secure::ENUMERABLE_INCLUDES_STAR.
+        #
+        # Taking an earlier example:
+        #
+        #     secure_with( {
+        #       :creating_caller_uuid => :authorised_caller_uuids
+        #     } )
+        #
+        #     # ...has this minimal longhand equivalent...
+        #
+        #     secure_with( {
+        #       :creating_caller_uuid => {
+        #         :session_field_name => :authorised_caller_uuids
+        #       }
+        #     } )
+        #
+        # ...which leads to SQL along the following lines:
+        #
+        #    AND ("model_table"."creating_caller_uuid" IN ('[val]'))
+        #
+        # ...then suppose we wanted to allow a session scoping value of '*'
+        # bypass security ("see everything"). We could use the
+        # Enumerable-includes-star matcher Proc
+        # Hoodoo::ActiveRecord::Secure::ENUMERABLE_INCLUDES_STAR here. At the
+        # time of writing, it is defined as the following Proc:
+        #
+        #    Proc.new do | security_values |
+        #      security_values.is_a?( Enumerable ) &&
+        #      security_values.include?( '*' ) rescue false
+        #    end
+        #
+        # This is activated through the +:exemptions+ key:
+        #
+        #     secure_with( {
+        #       :creating_caller_uuid => {
+        #         :session_field_name => :authorised_caller_uuids,
+        #         :exemptions         => Hoodoo::ActiveRecord::Secure::ENUMERABLE_INCLUDES_STAR
+        #       }
+        #     } )
+        #
+        # If the looked up value of the +authorised_caller_uuids+ attribute
+        # in the prevailing Session scoping section data was ["1234"], then the
+        # SQL query additions would occur as above:
+        #
+        #    AND ("model_table"."creating_caller_uuid" IN ('1234'))
+        #
+        # ...but if there is a value of "*", the security layer will ignore the
+        # normal restrictions, resulting in no SQL additions whatsoever.
+        #
+        # Since a Proc is used to compare the data found in the session against
+        # some wildcard, things like checking an array of values for some magic
+        # bypass characters / key, using regular expression matching, or other
+        # more heavyweight options are all possible. Remember, though, that all
+        # of this comes at a risk, since the mechanism is bypassing the normal
+        # scope chain security. If used improperly or somehow compromised, it
+        # will allow data to be read by an API caller that should not have been
+        # permitted to access it.
+        #
+        # See module Hoodoo::ActiveRecord::Secure::SecurityHelper for methods
+        # to help with exemption Proc construction.
+        #
         def secure( context )
           prevailing_scope = all() # "Model.all" -> returns anonymous scope
           extra_scope_map  = secured_with()
@@ -377,25 +480,33 @@ module Hoodoo
             return none() if context.session.nil? || context.session.scoping.nil?
 
             extra_scope_map.each do | model_field_name, key_or_options |
-              params_proc = DEFAULT_SECURE_PROC
+              exemption_proc = nil
+              params_proc    = DEFAULT_SECURE_PROC
 
               if key_or_options.is_a?( Hash )
                 session_scoping_key = key_or_options[ :session_field_name ]
+                exemption_proc      = key_or_options[ :exemptions ]
                 params_proc         = key_or_options[ :using ] if key_or_options.has_key?( :using )
               else
                 session_scoping_key = key_or_options
               end
 
               if context.session.scoping.respond_to?( session_scoping_key )
-                args = params_proc.call(
-                  self,
-                  model_field_name,
-                  context.session.scoping.send( session_scoping_key )
-                )
-                prevailing_scope = prevailing_scope.where( *args )
+                security_value = context.session.scoping.send( session_scoping_key )
+
+                if exemption_proc.nil? || exemption_proc.call( security_value ) != true
+                  args = params_proc.call(
+                    self,
+                    model_field_name,
+                    security_value
+                  )
+                  prevailing_scope = prevailing_scope.where( *args )
+                end
+
               else
                 prevailing_scope = none()
                 break
+
               end
             end
           end

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

@@ -0,0 +1,143 @@
+########################################################################
+# File::    security_helper.rb
+# (C)::     Loyalty New Zealand 2018
+#
+# Purpose:: Supplementary helper class included by "finder.rb". See
+#           Hoodoo::ActiveRecord::Secure, especially
+#           Hoodoo::ActiveRecord::Secure::ClassMethods#secure_with and
+#           its options Hash, for details.
+# ----------------------------------------------------------------------
+#           05-Apr-2018 (ADH): Created.
+########################################################################
+
+module Hoodoo
+  module ActiveRecord
+    module Secure
+
+      # Help build security exemption Procs to pass into
+      # Hoodoo::ActiveRecord::Secure::ClassMethods#secure_with via its options
+      # Hash. The following extends an example given in the documentation (at
+      # the time of writing here) for the underlying implementation method
+      # Hoodoo::ActiveRecord::Secure::ClassMethods#secure:
+      #
+      #     class Audit < ActiveRecord::Base
+      #       include Hoodoo::ActiveRecord::Secure
+      #
+      #       secure_with(
+      #         {
+      #           :creating_caller_uuid => :authorised_caller_uuids
+      #         },
+      #         {
+      #           :exemptions => Hoodoo::ActiveRecord::Secure::SecurityHelper::includes_wildcard( '*' )
+      #         }
+      #       )
+      #     end
+      #
+      # Note that the Hoodoo::ActiveRecord::Secure module includes some belper
+      # constants to aid brevity for common cases such as the single value
+      # <tt>#eql?</tt> or enumerable <tt>#include?</tt> matchers checking for
+      # a '*' as an indiscriminate wildcard - see for example
+      # Hoodoo::ActiveRecord::Secure::ENUMERABLE_INCLUDES_STAR.
+      #
+      class SecurityHelper
+
+        # Internally used by ::matches_wildcard for Ruby 2.4.0+ performance.
+        #
+        RUBY_FAST_WILDCARD_PROC_CONTENTS = %q{
+          security_value.match?( wildcard_regexp ) rescue false
+        }
+
+        # Internally used by ::matches_wildcard for Ruby < 2.4 compatibility.
+        #
+        RUBY_SLOW_WILDCARD_PROC_CONTENTS = %q{
+          wildcard_regexp.match( security_value ) != nil rescue false
+        }
+
+        # Match a given wildcard, typically a String, to a single value
+        # via <tt>#eql?</tt>.
+        #
+        # +wildcard_value+:: Wildcard value to match, e.g. <tt>'*'</tt>.
+        #
+        # Returns a Proc suitable for passing to the +:exemptions+ option for
+        # Hoodoo::ActiveRecord::Secure::ClassMethods#secure_with.
+        #
+        def self.eqls_wildcard( wildcard_value )
+          Proc.new do | security_value |
+            security_value.eql?( wildcard_value ) rescue false
+          end
+        end
+
+        # Match a given wildcard, typically a String, inside an Enumerable
+        # subclass via <tt>#include?</tt>.
+        #
+        # +wildcard_value+:: Wildcard value to match, e.g. <tt>'*'</tt>.
+        #
+        # Returns a Proc suitable for passing to the +:exemptions+ option for
+        # Hoodoo::ActiveRecord::Secure::ClassMethods#secure_with.
+        #
+        def self.includes_wildcard( wildcard_value )
+          Proc.new do | security_values |
+            security_values.is_a?( Enumerable ) &&
+            security_values.include?( wildcard_value ) rescue false
+          end
+        end
+
+        # Match a given wildcard Regexp to a value via <tt>#match?</tt>.
+        #
+        # +wildcard_value+:: Wildcard Regexp to use, e.g. <tt>/.*/</tt>.
+        #                    Strings are coerced to Regexps without any
+        #                    escaping but doing so reduces performance.
+        #
+        # Returns a Proc suitable for passing to the +:exemptions+ option for
+        # Hoodoo::ActiveRecord::Secure::ClassMethods#secure_with.
+        #
+        def self.matches_wildcard( wildcard_regexp )
+          wildcard_regexp = Regexp.new( wildcard_regexp ) unless wildcard_regexp.is_a?( Regexp )
+
+          # Use security_value's #match? (if present) to ensure that we have
+          # an expected "matchable" type. This is only available in Ruby 2.4
+          # or later, so a patch is performed below for earlier Rubies.
+          #
+          Proc.new do | security_value |
+
+            # Ruby 2.4.0 and later introduce the Regexp#match? family, which
+            # is the fastest way to determine a simple does-or-does-not match
+            # condition. Ruby 2.3.x and earlier need different, slower code.
+            #
+            if ''.respond_to?( :match? )
+              eval( RUBY_FAST_WILDCARD_PROC_CONTENTS )
+            else
+              eval( RUBY_SLOW_WILDCARD_PROC_CONTENTS )
+            end
+          end
+        end
+
+        # Match a given wildcard Regexp to any value in an enumerable
+        # object via iteration and <tt>#match?</tt>. Exists with +true+
+        # as soon as any match is made.
+        #
+        # +wildcard_value+:: Wildcard Regexp to use, e.g. <tt>/.*/</tt>.
+        #                    Strings are coerced to Regexps without any
+        #                    escaping but doing so reduces performance.
+        #
+        # Returns a Proc suitable for passing to the +:exemptions+ option for
+        # Hoodoo::ActiveRecord::Secure::ClassMethods#secure_with.
+        #
+        def self.matches_wildcard_enumerable( wildcard_regexp )
+          match_proc = self.matches_wildcard( wildcard_regexp )
+
+          Proc.new do | security_values |
+            begin
+              security_values.any? do | security_value |
+                match_proc.call( security_value )
+              end
+            rescue
+              false
+            end
+          end
+        end
+
+      end
+    end
+  end
+end

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

@@ -41,12 +41,17 @@ module Hoodoo
       #       # ...
       #     end
       #
+      # Depends upon and auto-includes Hoodoo::ActiveRecord::Creator
+      # and Hoodoo::ActiveRecord::ErrorMapping.
+      #
       # +model+:: The ActiveRecord::Base descendant that is including
       #           this module.
       #
       def self.included( model )
         unless model == Hoodoo::ActiveRecord::Base
+          model.send( :include, Hoodoo::ActiveRecord::Creator      )
           model.send( :include, Hoodoo::ActiveRecord::ErrorMapping )
+
           instantiate( model )
         end
 
@@ -75,18 +80,93 @@ module Hoodoo
         end
       end
 
-      # Instance equivalent of
-      # Hoodoo::ActiveRecord::Writer::ClassMethods.persist_in - see that for
-      # details. The class method just calls here, having constructed an
-      # instance based on the attributes it was given. If you have already
-      # built an instance yourself, just call this instance method equivalent
-      # instead.
-      #
-      # As an instance-based method, the return value and error handling
-      # semantics differ from the class-based counterpart. Instead of
-      # checking "persisted?", check the return value of +persist_in+. This
-      # means you can also use +persist_in+ to save a previously persisted,
-      # but now updated record, should you so wish.
+      # == Overview
+      #
+      # Service authors _SHOULD_ use this method when persisting data with
+      # ActiveRecord if there is a risk of duplication constraint violation
+      # of any kind. This will include a violation on the UUID of a resource
+      # if you support external setting of this value via the body of a
+      # +create+ call containing the +id+ field, injected by Hoodoo as the
+      # result of an authorised use of the <tt>X-Resource-UUID</tt> HTTP
+      # header.
+      #
+      # You can use this method for both persisting new records or
+      # persisting updates, in the same way as ActiveRecord's +save+ is
+      # used for either.
+      #
+      #
+      # == Concurrency
+      #
+      # Services often run in highly concurrent environments and uniqueness
+      # constraint validations with ActiveRecord cannot protect against
+      # race conditions in such cases. Those work at the application level;
+      # the check to see if a record exists with a duplicate value in some
+      # given column is a separate operation from that which stores the
+      # record subsequently. As per the Rails Guides entry on the uniqueness
+      # validation at the time of writing:
+      #
+      # http://guides.rubyonrails.org/active_record_validations.html#uniqueness
+      #
+      # <i>"It does not create a uniqueness constraint in the database, so
+      # it may happen that two different database connections create two
+      # records with the same value for a column that you intend to be
+      # unique. To avoid that, you must create a unique index on both
+      # columns in your database."</i>
+      #
+      # You *MUST* always use a uniqueness constraint at the database level
+      # and *MAY* additionally use ActiveRecord validations for a higher
+      # level warning in all but race condition edge cases. If you then use
+      # this +persist_in+ method to store records, all duplication cases
+      # will be handled elegantly and reported as a
+      # <tt>generic.invalid_duplication</tt> error. In the event that a
+      # caller has used the <tt>X-Deja-Vu</tt> HTTP header, Hoodoo will take
+      # such an error and transform it into a non-error 204 HTTP response;
+      # so by using +persist_in+, you also ensure that your service
+      # participates successfully in this process without any additional
+      # coding effort. You get safe concurrency and protection against the
+      # inherent lack of idempotency in HTTP +POST+ operations via any
+      # must-be-unique fields (within your defined scope) automatically.
+      #
+      # Using this method for data storage instead of plain ActiveRecord
+      # +save+ or <tt>save!</tt> will also help your code auto-inherit any
+      # additional future write-related enhancements in Hoodoo should they
+      # arise, without necessarily needing service code changes.
+      #
+      #
+      # == 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 Symbol of +:success+ or +:failure+ indicating the outcome
+      # of the same attempt. In the event of failure, the model will be
+      # invalid and not persisted; you can read errors immediately and should
+      # avoid unnecessarily re-running validations by calling +valid?+ or
+      # +validate+ on the instance.
+      #
+      #
+      # == Example
+      #
+      #     class Unique < ActiveRecord::Base
+      #       include Hoodoo::ActiveRecord::Writer
+      #       validates :unique_code, :presence => true, :uniqueness => true
+      #     end
+      #
+      # The migration to create the table for the Unique model _MUST_ have a
+      # uniqueness constraint on the +unique_code+ field, e.g.:
+      #
+      #     def change
+      #       add_column :uniques, :unique_code, :null => false
+      #       add_index :uniques, [ :unique_code ], :unique => true
+      #     end
+      #
+      # Then, inside the implementation class which uses the above model,
+      # where you have (say) written private methods +mapping_of+ which
+      # maps +context.request.body+ to an attributes Hash for persistence
+      # and +rendering_of+ which uses Hoodoo::Presenters::Base.render_in to
+      # properly render a representation of your resource, you would write:
       #
       #     def create( context )
       #       attributes = mapping_of( context.request.body )
@@ -109,18 +189,49 @@ module Hoodoo
       #       context.response.set_resource( rendering_of( context, model_instance ) )
       #     end
       #
-      # 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
       #
-      # Returns a Symbol of +:success+ or +:failure+ indicating the outcome
-      # of the same attempt. In the event of failure, the model will be
-      # invalid and not persisted; you can read errors immediately and should
-      # avoid unnecessarily re-running validations by calling +valid?+ or
-      # +validate+ on the instance.
+      # There is a class method equivalent which combines creating a new record
+      # and persisting it in a single call. If you prefer that code style, see
+      # Hoodoo::ActiveRecord::Writer::ClassMethods.persist_in. In such cases,
+      # it could look quite odd to mix the class method and instance method
+      # variants for new records or existing record updates; as syntax sugar,
+      # an alias of the #persist_in instance method is available under the name
+      # #update_in, so that you can use the class method for creation and the
+      # aliased instance method for updates.
+      #
+      #
+      # == Nested transaction note
+      #
+      # Ordinarily an exception in a nested transaction does not roll back.
+      # ActiveRecord wraps all saves in a transaction "out of the box", so
+      # the following construct could have unexpected results...
+      #
+      #     Model.transaction do
+      #       instance.persist_in( context )
+      #     end
+      #
+      # ...if <tt>instance.valid?</tt> runs any SQL queries - which is very
+      # likely. PostgreSQL, for example, would then raise an exception; the
+      # inner transaction failed, leaving the outer one in an aborted state:
+      #
+      #     PG::InFailedSqlTransaction: ERROR:  current transaction is
+      #     aborted, commands ignored until end of transaction block
+      #
+      # ActiveRecord provides us with a way to define a transaction that
+      # does roll back via the <tt>requires_new: true</tt> option. Hoodoo
+      # thus protects callers from the above artefacts by ensuring that all
+      # saves are wrapped in an outer transaction that causes rollback in
+      # any parents. This sidesteps the unexpected behaviour, but service
+      # authors might sometimes need to be aware of this if using complex
+      # transaction behaviour along with <tt>persist_in</tt>.
+      #
+      # In pseudocode, the internal implementation is:
+      #
+      #     self.transaction( :requires_new => true ) do
+      #       self.save
+      #     end
       #
       def persist_in( context )
 
@@ -171,77 +282,28 @@ module Hoodoo
         return errors_occurred.nil? ? :success : :failure
       end
 
+      # Alias of #persist_in. Although that can be used for new records or
+      # updates, it's nice to have the syntax sugar of an "update in context"
+      # method to sit alongside things like #persist_in and
+      # Hoodoo::ActiveRecord::Creator::ClassMethods::new_in.
+      #
+      alias_method :update_in, :persist_in
+
       # Collection of class methods that get defined on an including class via
       # Hoodoo::ActiveRecord::Writer::included.
       #
       module ClassMethods
 
-        # == Overview
-        #
-        # Service authors _SHOULD_ use this method when persisting data with
-        # ActiveRecord if there is a risk of duplication constraint violation
-        # of any kind. This will include a violation on the UUID of a resource
-        # if you support external setting of this value via the body of a
-        # +create+ call containing the +id+ field, injected by Hoodoo as the
-        # result of an authorised use of the <tt>X-Resource-UUID</tt> HTTP
-        # header.
-        #
-        # Services often run in highly concurrent environments and uniqueness
-        # constraint validations with ActiveRecord cannot protect against
-        # race conditions in such cases. IT works at the application level;
-        # the check to see if a record exists with a duplicate value in some
-        # given column is a separate operation from that which stores the
-        # record subsequently. As per the Rails Guides entry on the uniqueness
-        # validation at the time of writing:
-        #
-        # http://guides.rubyonrails.org/active_record_validations.html#uniqueness
-        #
-        # <i>"It does not create a uniqueness constraint in the database, so
-        # it may happen that two different database connections create two
-        # records with the same value for a column that you intend to be
-        # unique. To avoid that, you must create a unique index on both
-        # columns in your database."</i>
-        #
-        # You *MUST* always use a uniqueness constraint at the database level
-        # and *MAY* additionally use ActiveRecord validations for a higher
-        # level warning in all but race condition edge cases. If you then use
-        # this +persist_in+ method to store records, all duplication cases
-        # will be handled elegantly and reported as a
-        # <tt>generic.invalid_duplication</tt> error. In the event that a
-        # caller has used the <tt>X-Deja-Vu</tt> HTTP header, Hoodoo will take
-        # such an error and transform it into a non-error 204 HTTP response;
-        # so by using +persist_in+, you also ensure that your service
-        # participates successfully in this process without any additional
-        # coding effort. You get safe concurrency and protection against the
-        # inherent lack of idempotency in HTTP +POST+ operations via any
-        # must-be-unique fields (within your defined scope) automatically.
+        # A class-based equivalent of the
+        # Hoodoo::ActiveRecord::Writer#persist_in method which creates a
+        # record using Hoodoo::ActiveRecord::Creator::ClassMethods::new_in,
+        # then calls Hoodoo::ActiveRecord::Writer#persist_in to persist the
+        # data; see that for full details.
         #
-        # Using this method for data storage instead of plain ActiveRecord
-        # +save+ or <tt>save!</tt> will also help your code auto-inherit any
-        # additional future write-related enhancements in Hoodoo should they
-        # arise, without necessarily needing service code changes.
-        #
-        #
-        # == Example
-        #
-        #     class Unique < ActiveRecord::Base
-        #       include Hoodoo::ActiveRecord::Writer
-        #       validates :unique_code, :presence => true, :uniqueness => true
-        #     end
-        #
-        # The migration to create the table for the Unique model _MUST_ have a
-        # uniqueness constraint on the +unique_code+ field, e.g.:
-        #
-        #     def change
-        #       add_column :uniques, :unique_code, :null => false
-        #       add_index :uniques, [ :unique_code ], :unique => true
-        #     end
-        #
-        # Then, inside the implementation class which uses the above model,
-        # where you have (say) written private methods +mapping_of+ which
-        # maps +context.request.body+ to an attributes Hash for persistence
-        # and +rendering_of+ which uses Hoodoo::Presenters::Base.render_in to
-        # properly render a representation of your resource, you would write:
+        # As a class-based method, the return value and error handling
+        # semantics differ from the instance-based counterpart. Instead of
+        # checking the return value of +persist_in+ for success or failure,
+        # use ActiveRecord's "persisted?":
         #
         #     def create( context )
         #       attributes = mapping_of( context.request.body )
@@ -276,40 +338,8 @@ module Hoodoo
         # See also the Hoodoo::ActiveRecord::Writer#persist_in instance method
         # equivalent of this class method.
         #
-        #
-        # == Nested transaction note
-        #
-        # Ordinarily an exception in a nested transaction does not roll back.
-        # ActiveRecord wraps all saves in a transaction "out of the box", so
-        # the following construct could have unexpected results...
-        #
-        #     Model.transaction do
-        #       instance.persist_in( context )
-        #     end
-        #
-        # ...if <tt>instance.valid?</tt> runs any SQL queries - which is very
-        # likely. PostgreSQL, for example, would then raise an exception; the
-        # inner transaction failed, leaving the outer one in an aborted state:
-        #
-        #     PG::InFailedSqlTransaction: ERROR:  current transaction is
-        #     aborted, commands ignored until end of transaction block
-        #
-        # ActiveRecord provides us with a way to define a transaction that
-        # does roll back via the <tt>requires_new: true</tt> option. Hoodoo
-        # thus protects callers from the above artefacts by ensuring that all
-        # saves are wrapped in an outer transaction that causes rollback in
-        # any parents. This sidesteps the unexpected behaviour, but service
-        # authors might sometimes need to be aware of this if using complex
-        # transaction behaviour along with <tt>persist_in</tt>.
-        #
-        # In pseudocode, the internal implementation is:
-        #
-        #     self.transaction( :requires_new => true ) do
-        #       self.save
-        #     end
-        #
         def persist_in( context, attributes )
-          instance = self.new( attributes )
+          instance = self.new_in( context, attributes )
           instance.persist_in( context )
 
           return instance