hoodoo 1.1.3 → 1.2.0

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

@@ -22,7 +22,7 @@ module Hoodoo
     #
     module Secure
 
-      # Instantiates this module when it is included:
+      # Instantiates this module when it is included.
       #
       # Example:
       #

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

@@ -64,7 +64,9 @@ module Hoodoo
       #
       # * Hoodoo::ActiveRecord::Secure#secure
       # * Hoodoo::ActiveRecord::Translated#translated
-      # * Hoodoo::ActiveRecord::Dated#dated
+      # * Hoodoo::ActiveRecord::Dated#dated (if "dating_enabled?" is +true+)
+      # * Hoodoo::ActiveRecord::ManuallyDated#manually_dated
+      #   (if "manual_dating_enabled?" is +true+)
       #
       # +klass+::   The ActiveRecord::Base subclass _class_ (not instance)
       #             which is making the call here. This is the entity which is
@@ -86,10 +88,14 @@ module Hoodoo
         # Due to the mechanism used, dating scope must be done first or the
         # rest of the query may be invalid.
         #
-        if klass.include?( Hoodoo::ActiveRecord::Dated )
+        if klass.include?( Hoodoo::ActiveRecord::Dated ) && klass.dating_enabled?()
           prevailing_scope = prevailing_scope.dated( context )
         end
 
+        if klass.include?( Hoodoo::ActiveRecord::ManuallyDated ) && klass.manual_dating_enabled?()
+          prevailing_scope = prevailing_scope.manually_dated( context )
+        end
+
         if klass.include?( Hoodoo::ActiveRecord::Secure )
           prevailing_scope = prevailing_scope.secure( context )
         end

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

@@ -21,7 +21,7 @@ module Hoodoo
     #
     module Translated
 
-      # Instantiates this module when it is included:
+      # Instantiates this module when it is included.
       #
       # Example:
       #

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

@@ -29,7 +29,7 @@ module Hoodoo
     #
     module UUID
 
-      # Instantiates this module when it is included:
+      # Instantiates this module when it is included.
       #
       # Example:
       #
@@ -69,10 +69,34 @@ module Hoodoo
         model.primary_key = 'id'
 
         model.validate( :on => :create ) do
-          self.id = Hoodoo::UUID.generate() if self.id.nil?
+          self.id ||= Hoodoo::UUID.generate()
         end
 
-        model.validates( :id, :uuid => true, :presence => true, :uniqueness => true )
+        model.validates(
+          :id,
+          {
+            :uuid       => true,
+            :presence   => true,
+            :uniqueness => true,
+          }
+        )
+
+        # We also have to remove ActiveRecord's default unscoped uniqueness
+        # check on 'id'. We've added an equivalent validator above.
+        #
+        # Sadly there is no API for this even as late as ActiveRecord 4.2,
+        # so we have to resort to fragile hackery.
+        #
+        model._validators.reject!() do | key, ignored |
+          key == :id
+        end
+
+        id_validation_callback = model._validate_callbacks.find do | callback |
+          callback.raw_filter.is_a?( ::ActiveRecord::Validations::UniquenessValidator ) &&
+          callback.raw_filter.attributes == [ :id ]
+        end
+
+        model._validate_callbacks.delete( id_validation_callback )
       end
 
     end

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

@@ -32,7 +32,7 @@ module Hoodoo
     #
     module Writer
 
-      # Instantiates this module when it is included:
+      # Instantiates this module when it is included.
       #
       # Example:
       #

data/lib/hoodoo/utilities/uuid.rb

@@ -1,5 +1,3 @@
-require "uuidtools"
-
 module Hoodoo
 
   # Class that handles generation and validation of UUIDs. Whenever you
@@ -13,22 +11,30 @@ module Hoodoo
 
     # A regexp which, as its name suggests, only matches a string that
     # contains 16 pairs of hex digits (with upper or lower case A-F).
+    # Legacy value kept in case third party client code is using it.
     #
     # http://stackoverflow.com/questions/287684/regular-expression-to-validate-hex-string
     #
     MATCH_16_PAIRS_OF_HEX_DIGITS = /^([[:xdigit:]]{2}){16}$/
 
+    # A regexp which matches V4 UUIDs with hyphens removed. Note that
+    # this is more strict than MATCH_16_PAIRS_OF_HEX_DIGITS.
+    #
+    MATCH_V4_UUID = /^[a-fA-F0-9]{12}4[a-fA-F0-9]{3}[89aAbB][a-fA-F0-9]{15}$/
+
     # Generate a unique identifier. Returns a 32 character string.
     #
     def self.generate
-      UUIDTools::UUID.random_create().hexdigest()
+      SecureRandom.uuid().gsub!( '-', '' )
     end
 
     # Checks if a UUID string is valid. Returns +true+ if so, else +false+.
     #
-    # +uuid+:: UUID string to validate. Must be a String, 32 characters
-    #          long (as 16 hex digit pairs) and parse to a valid result
-    #          internally, according to internal UUID generation rules.
+    # +uuid+:: Quantity to validate.
+    #
+    # The method will only return +true+ if the input parameter is a String
+    # containing 32 mostly random hex digits representing a valid V4 UUID
+    # with hyphens removed.
     #
     # Note that the validity of a UUID says nothing about where, if anywhere,
     # it might have been used. So, just because a UUID is valid, doesn't mean
@@ -36,9 +42,7 @@ module Hoodoo
     # row in a database.
     #
     def self.valid?( uuid )
-      uuid.is_a?( ::String )                           &&
-      ( uuid =~ MATCH_16_PAIRS_OF_HEX_DIGITS ) != nil  &&
-      UUIDTools::UUID.parse_hexdigest( uuid ).valid?()
+      uuid.is_a?( ::String ) && ( uuid =~ MATCH_V4_UUID ) != nil
     end
   end
 end

data/lib/hoodoo/version.rb

@@ -12,6 +12,6 @@ module Hoodoo
   # The Hoodoo gem version. If this changes, ensure that the date in
   # "hoodoo.gemspec" is correct and run "bundle install" (or "update").
   #
-  VERSION = '1.1.3'
+  VERSION = '1.2.0'
 
 end

data/spec/active/active_record/dated_spec.rb

@@ -53,11 +53,13 @@ describe Hoodoo::ActiveRecord::Dated do
 
     before( :all ) do
 
-      # Create some examples data for finding. The data has two different UUIDs
+      # Create some example data for finding. The data has two different UUIDs
       # which I'll referer to as A and B. The following tables contain the
-      # historical and current records separately with their attributes.
+      # historical and current records separately with their attributes, with
+      # items created in the historical or main database tables respectively.
       #
       # Historical:
+      #
       # -------------------------------------------------------------------
       #  uuid | data    | created_at    | effective_end | effective_start |
       # -------------------------------------------------------------------
@@ -67,12 +69,12 @@ describe Hoodoo::ActiveRecord::Dated do
       #  B    | "four"  | now - 4 hours | now           | now - 2 hour    |
       #
       # Current:
+      #
       # --------------------------------
       #  uuid | data   | created_at    |
       # --------------------------------
       #  B    | "five" | now - 4 hours |
       #  A    | "six"  | now - 5 hours |
-      #
 
       @uuid_a = Hoodoo::UUID.generate
       @uuid_b = Hoodoo::UUID.generate
@@ -111,7 +113,23 @@ describe Hoodoo::ActiveRecord::Dated do
 
     end
 
-    context '.dated_at' do
+    context 'unscoped' do
+      it 'counts only the current records in the main database table' do
+        expect( model_klass.count ).to be 2
+      end
+
+      it 'finds only the current records in the main database table' do
+        expect( model_klass.pluck( :data ) ).to match_array( [ 'five', 'six' ] )
+      end
+    end
+
+    context '#dating_enabled?' do
+      it 'says it is automatically dated' do
+        expect( model_klass.dating_enabled? ).to eq( true )
+      end
+    end
+
+    context '#dated_at' do
       it 'returns counts correctly' do
         expect( model_klass.dated_at( @now - 10.hours ).count ).to be 0
         expect( model_klass.dated_at( @now ).count ).to be 2
@@ -143,7 +161,7 @@ describe Hoodoo::ActiveRecord::Dated do
 
     end
 
-    context '.dated' do
+    context '#dated' do
       it 'returns counts correctly' do
         # The contents of the Context are irrelevant aside from the fact that it
         # needs a request to store the dated_at value.
@@ -207,7 +225,7 @@ describe Hoodoo::ActiveRecord::Dated do
 
     end
 
-    context '.dated_historical_and_current' do
+    context '#dated_historical_and_current' do
       it 'returns counts correctly' do
         expect( model_klass.dated_historical_and_current.count ).to be 6
       end

data/spec/active/active_record/finder_spec.rb

@@ -350,19 +350,41 @@ describe Hoodoo::ActiveRecord::Finder do
 
   # ==========================================================================
 
-  context 'acquisition_scope' do
-    it 'SQL generation is as expected' do
-      sql = RSpecModelFinderTest.acquisition_scope( @id ).to_sql()
+  context 'acquisition scope and overrides' do
+    def expect_sql( sql, id_attr_name )
       expect( sql ).to eq( "SELECT \"r_spec_model_finder_tests\".* "<<
                            "FROM \"r_spec_model_finder_tests\" " <<
                            "WHERE (" <<
                              "(" <<
-                               "\"r_spec_model_finder_tests\".\"id\" = '#{ @id }' OR " <<
+                               "\"r_spec_model_finder_tests\".\"#{ id_attr_name }\" = '#{ @id }' OR " <<
                                "\"r_spec_model_finder_tests\".\"uuid\" = '#{ @id }'" <<
                              ") OR " <<
                              "\"r_spec_model_finder_tests\".\"code\" = '#{ @id }'" <<
                            ")" )
     end
+
+    context 'acquisition_scope' do
+      it 'SQL generation is as expected' do
+        sql = RSpecModelFinderTest.acquisition_scope( @id ).to_sql()
+        expect_sql( sql, 'id' )
+      end
+    end
+
+    context 'acquire_with_id_substitute' do
+      before :each do
+        @alt_attr_name = 'foo'
+        RSpecModelFinderTest.acquire_with_id_substitute( @alt_attr_name )
+      end
+
+      after :each do
+        RSpecModelFinderTest.acquire_with_id_substitute( 'id' )
+      end
+
+      it 'SQL generation is as expected' do
+        sql = RSpecModelFinderTest.acquisition_scope( @id ).to_sql()
+        expect_sql( sql, @alt_attr_name )
+      end
+    end
   end
 
   # ==========================================================================

data/spec/active/active_record/manually_dated_spec.rb

@@ -0,0 +1,776 @@
+require 'spec_helper'
+require 'active_record'
+
+describe Hoodoo::ActiveRecord::ManuallyDated do
+
+  # ==========================================================================
+  # Data setup
+  # ==========================================================================
+
+  BAD_DATA_FOR_VALIDATIONS = 'bad_data'
+
+  before :all do
+    spec_helper_silence_stdout() do
+      ActiveRecord::Migration.create_table( :r_spec_model_manual_date_tests, :id => false ) do | t |
+        t.string :uuid, :null => false, :length => 32
+        t.string :id,   :null => false, :length => 32
+
+        t.text :data
+
+        t.timestamps
+        t.datetime :effective_start, :null => false
+        t.datetime :effective_end,   :null => false
+      end
+    end
+
+    class RSpecModelManualDateTest < ActiveRecord::Base
+      include Hoodoo::ActiveRecord::ManuallyDated
+      manual_dating_enabled()
+
+      validates_each :data do | record, attribute, value |
+        if value == BAD_DATA_FOR_VALIDATIONS
+          record.errors.add( attribute, 'contains bad text' )
+        end
+      end
+    end
+  end
+
+  # Create some example data for finding. The data has two different UUIDs
+  # which I'll referer to as A and B. The following tables list the
+  # historical and current records with their attributes. All are created
+  # as rows within the main test model class's one database table.
+  #
+  # The data is also seeded for any other tests, so that there's a known
+  # set of rows which can be examined for changes, or lack thereof.
+  #
+  # Historical:
+  #
+  # -------------------------------------------------------------------
+  #  uuid | data    | created_at    | effective_end | effective_start |
+  # -------------------------------------------------------------------
+  #  A    | 'one'   | now - 5 hours | now - 3 hours | now - 5 hours   |
+  #  B    | 'two'   | now - 4 hours | now - 2 hours | now - 4 hours   |
+  #  A    | 'three' | now - 5 hours | now - 1 hour  | now - 3 hours   |
+  #  B    | 'four'  | now - 4 hours | now           | now - 2 hour    |
+  #
+  # Current:
+  #
+  # -------------------------------------------------------------------
+  #  uuid | data    | created_at    | effective_end | effective_start |
+  # -------------------------------------------------------------------
+  #  B    | 'five'  | now - 4 hours | nil           | now - 5 hours   |
+  #  A    | 'six'   | now - 5 hours | nil           | now - 4 hours   |
+  #
+  before :each do
+
+    @now    = Time.now.utc.round( Hoodoo::ActiveRecord::ManuallyDated::SECONDS_DECIMAL_PLACES )
+    @uuid_a = Hoodoo::UUID.generate
+    @uuid_b = Hoodoo::UUID.generate
+    @eot    = Hoodoo::ActiveRecord::ManuallyDated::DATE_MAXIMUM
+
+    # uuid, data, created_at, effective_end, effective_start
+    [
+      [ @uuid_a, 'one',   @now - 5.hours, @now - 5.hours, @now - 3.hours  ],
+      [ @uuid_b, 'two',   @now - 4.hours, @now - 4.hours, @now - 2.hours  ],
+      [ @uuid_a, 'three', @now - 5.hours, @now - 3.hours, @now - 1.hour   ],
+      [ @uuid_b, 'four',  @now - 4.hours, @now - 2.hours, @now            ],
+      [ @uuid_b, 'five',  @now - 4.hours, @now,           @eot            ],
+      [ @uuid_a, 'six',   @now - 5.hours, @now - 1.hour,  @eot            ]
+    ].each do | row_data |
+      RSpecModelManualDateTest.new( {
+        :id              => row_data[ 0 ],
+        :data            => row_data[ 1 ],
+        :created_at      => row_data[ 2 ],
+        :updated_at      => row_data[ 2 ],
+        :effective_start => row_data[ 3 ],
+        :effective_end   => row_data[ 4 ]
+      } ).save!
+    end
+
+    # This is a useful thing to have around! Just the bare minimum for the
+    # API under test. At the time of writing you can actually pass a "nil"
+    # context if all other attribute values are given, but that's not
+    # documented and besides, we want to test a mixture of context-based
+    # and explicitly specified parameters.
+    #
+    @context = Hoodoo::Services::Context.new( nil,
+                                              Hoodoo::Services::Request.new,
+                                              nil,
+                                              nil )
+  end
+
+  # ==========================================================================
+  # Reading tests
+  # ==========================================================================
+
+  context 'reading data' do
+    context 'unscoped' do
+      it 'counts all historical and current records in one database table' do
+        expect( RSpecModelManualDateTest.count ).to be 6
+      end
+
+      it 'finds all historical and current records in one database table' do
+        expect( RSpecModelManualDateTest.pluck( :data ) ).to match_array( [ 'one', 'two', 'three', 'four', 'five', 'six' ] )
+      end
+    end
+
+    context '#manual_dating_enabled?' do
+      it 'says it is manually dated' do
+        expect( RSpecModelManualDateTest.manual_dating_enabled? ).to eq( true )
+      end
+    end
+
+    context '#manually_dated_at' do
+      it 'returns counts correctly' do
+        expect( RSpecModelManualDateTest.manually_dated_at( @now - 10.hours ).count ).to be 0
+        expect( RSpecModelManualDateTest.manually_dated_at( @now ).count ).to be 2
+      end
+
+      def test_expectation( time, expected_data )
+        expect( RSpecModelManualDateTest.manually_dated_at( time ).pluck( :data ) ).to match_array( expected_data )
+      end
+
+      it 'returns no records before any were effective' do
+        test_expectation( @now - 10.hours, [] )
+      end
+
+      it 'returns records that used to be effective starting at past time' do
+        test_expectation( @now - 5.hours, [ 'one'           ] )
+        test_expectation( @now - 4.hours, [ 'one', 'two'    ] )
+        test_expectation( @now - 3.hours, [ 'two', 'three'  ] )
+        test_expectation( @now - 2.hours, [ 'three', 'four' ] )
+        test_expectation( @now - 1.hour,  [ 'four', 'six'   ] )
+      end
+
+      it 'returns records that are effective now' do
+        test_expectation( @now, [ 'five', 'six' ] )
+      end
+
+      # Given the test above, if this was ignoring timezone or otherwise
+      # being confused it would take "now", subtract an hour, then add it
+      # back again; we'd see "five" and "six" instead of "four" and "six".
+      #
+      it 'converts inbound date/times to UTC' do
+        local = ( @now - 1.hour ).localtime( '+01:00' )
+        test_expectation( local, [ 'four', 'six' ] )
+      end
+
+      it 'works with further filtering' do
+        expect( RSpecModelManualDateTest.manually_dated_at( @now ).where( :uuid => @uuid_a ).pluck( :data ) ).to eq( [ 'six' ] )
+      end
+    end
+
+    context '#manually_dated' do
+      it 'returns counts correctly' do
+        # The contents of the Context are irrelevant aside from the fact that it
+        # needs a request to store the dated_at value.
+        request = Hoodoo::Services::Request.new
+        context = Hoodoo::Services::Context.new( nil, request, nil, nil )
+
+        context.request.dated_at = @now - 10.hours
+        expect( RSpecModelManualDateTest.manually_dated( context ).count ).to be 0
+
+        context.request.dated_at = @now
+        expect( RSpecModelManualDateTest.manually_dated( context ).count ).to be 2
+      end
+
+      def test_expectation( time, expected_data )
+        # The contents of the Context are irrelevant aside from the fact that it
+        # needs a request to store the dated_at value.
+        request = Hoodoo::Services::Request.new
+        context = Hoodoo::Services::Context.new( nil, request, nil, nil )
+        context.request.dated_at = time
+
+        expect( RSpecModelManualDateTest.manually_dated( context ).pluck( :data ) ).to match_array( expected_data )
+      end
+
+      it 'returns no records before any were effective' do
+        test_expectation( @now - 10.hours, [] )
+      end
+
+      it 'returns records that used to be effective starting at past time' do
+        test_expectation( @now - 5.hours, [ 'one'           ] )
+        test_expectation( @now - 4.hours, [ 'one', 'two'    ] )
+        test_expectation( @now - 3.hours, [ 'two', 'three'  ] )
+        test_expectation( @now - 2.hours, [ 'three', 'four' ] )
+        test_expectation( @now - 1.hour,  [ 'four', 'six'   ] )
+      end
+
+      it 'returns records that are effective now' do
+        test_expectation( @now, [ 'five', 'six' ] )
+      end
+
+      it 'converts inbound date/times to UTC' do
+        local = ( @now - 1.hour ).localtime( '+01:00' )
+        test_expectation( local, [ 'four', 'six' ] )
+      end
+
+      it 'works with further filtering' do
+
+        # The contents of the Context are irrelevant aside from the fact that it
+        # needs a request to store the dated_at value.
+        request = Hoodoo::Services::Request.new
+        context = Hoodoo::Services::Context.new( nil, request, nil, nil )
+        context.request.dated_at = @now
+
+        expect( RSpecModelManualDateTest.manually_dated( context ).where( :uuid => @uuid_a ).pluck( :data ) ).to eq( [ 'six' ] )
+      end
+
+      it 'works with dating last' do
+
+        # The contents of the Context are irrelevant aside from the fact that it
+        # needs a request to store the dated_at value.
+        request = Hoodoo::Services::Request.new
+        context = Hoodoo::Services::Context.new( nil, request, nil, nil )
+        context.request.dated_at = @now
+
+        expect( RSpecModelManualDateTest.where( :uuid => @uuid_a ).manually_dated( context ).pluck( :data ) ).to eq( [ 'six' ] )
+      end
+    end
+
+    context '#manually_dated_historic' do
+      it 'counts only historic entries' do
+        expect( RSpecModelManualDateTest.manually_dated_historic.count ).to eq( 4 )
+      end
+
+      it 'finds only historic entries' do
+        expect( RSpecModelManualDateTest.manually_dated_historic.pluck( :data ) ).to match_array( [ 'one', 'two', 'three', 'four' ] )
+      end
+    end
+
+    context '#manually_dated_contemporary' do
+      it 'counts only contemporary entries' do
+        expect( RSpecModelManualDateTest.manually_dated_contemporary.count ).to eq( 2 )
+      end
+
+      it 'finds only contemporary entries' do
+        expect( RSpecModelManualDateTest.manually_dated_contemporary.pluck( :data ) ).to match_array( [ 'five', 'six' ] )
+      end
+    end
+  end
+
+  # ==========================================================================
+  # Writing tests
+  # ==========================================================================
+
+  context 'writing data' do
+    context '#manually_dated_update_in' do
+      before :each do
+        @change_data_from = Hoodoo::UUID.generate()
+        @change_data_to   = Hoodoo::UUID.generate()
+
+        @record = RSpecModelManualDateTest.new( {
+          :data       => @change_data_from,
+          :created_at => @now,
+          :updated_at => @now
+        } )
+
+        @record.save!
+        sleep( ( 0.1 ** Hoodoo::ActiveRecord::ManuallyDated::SECONDS_DECIMAL_PLACES ) * 2 )
+
+        @context.request.instance_variable_set( '@ident', @record.uuid )
+        @context.request.body = { 'data' => @change_data_to }
+      end
+
+      # Call only for 'successful' update cases. Pass the result of a call to
+      # #manually_dated_update_in. Expects:
+      #
+      # * No new 'current' items
+      # * One new 'historic' item
+      # * Two unscoped things can now be found by @record's UUID
+      # * They should have the correct bounding dates and data.
+      #
+      # Remember that the very top of this file seeds in 2 contemporary and
+      # 4 historical entries, so counts are relative to that baseline.
+      #
+      def run_expectations( result )
+        expect( RSpecModelManualDateTest.manually_dated_contemporary.count ).to eq( 3 )
+        expect( RSpecModelManualDateTest.manually_dated_historic.count ).to eq( 5 )
+        expect( RSpecModelManualDateTest.manually_dated_contemporary.where( :uuid => @record.uuid ).count ).to eq( 1 )
+        expect( RSpecModelManualDateTest.manually_dated_historic.where( :uuid => @record.uuid ).count ).to eq( 1 )
+
+        # Current record is now at 'no'/nil time - i.e. actually Time.now. The
+        # time frozen into "@now" at the top of this file is by this point the
+        # historic time of the old record.
+
+        historic = RSpecModelManualDateTest.manually_dated_at( @now ).find_by_uuid( @record.uuid )
+        current  = RSpecModelManualDateTest.manually_dated_at().find_by_uuid( @record.uuid )
+
+        expect( result.uuid ).to eq( current.uuid )
+
+        expect( historic.data ).to eq( @change_data_from )
+        expect( current.data  ).to eq( @change_data_to   )
+
+        expect( historic.effective_end ).to eq( current.effective_start )
+        expect( historic.effective_end ).to eq( current.updated_at      )
+        expect( current.effective_end  ).to eq( @eot                    )
+      end
+
+      it 'via context alone' do
+        result = RSpecModelManualDateTest.manually_dated_update_in(
+          @context
+        )
+
+        run_expectations( result )
+      end
+
+      # Generate a random => invalid UUID in the request data to prove that
+      # the valid one given in the input parameter is used as an override.
+      #
+      it 'specifying "ident"' do
+        @context.request.instance_variable_set( '@ident', Hoodoo::UUID.generate() )
+
+        result = RSpecModelManualDateTest.manually_dated_update_in(
+          @context,
+          ident: @record.uuid
+        )
+
+        run_expectations( result )
+      end
+
+      # Generate a random => invalid payload in the request data to prove that
+      # the valid one given in the input parameter is used as an override.
+      #
+      it 'specifying "attributes"' do
+        @context.request.body = { Hoodoo::UUID.generate() => 42 }
+
+        result = RSpecModelManualDateTest.manually_dated_update_in(
+          @context,
+          attributes: { 'data' => @change_data_to }
+        )
+
+        run_expectations( result )
+      end
+
+      it 'uses a given scope' do
+
+        # We expect the custom scope to be customised to find an
+        # acquisition scope for locking, if it's being used OK.
+        # This is fragile; depends heavily on implementation.
+
+        custom_scope = RSpecModelManualDateTest.where( :data => [ 'one', 'two', 'three' ] + [ @change_data_from ] )
+        expect( custom_scope ).to receive( :acquisition_scope ).and_call_original
+
+        result = RSpecModelManualDateTest.manually_dated_update_in(
+          @context,
+          scope: custom_scope
+        )
+
+        run_expectations( result )
+      end
+
+      context 'handles not-found' do
+        it 'because of a bad identifier' do
+          result = RSpecModelManualDateTest.manually_dated_update_in(
+            @context,
+            ident: Hoodoo::UUID.generate() # Random => invalid
+          )
+
+          expect( result ).to be_nil
+        end
+
+        it 'because of a scope' do
+          result = RSpecModelManualDateTest.manually_dated_update_in(
+            @context,
+            scope: RSpecModelManualDateTest.where( :data => [ Hoodoo::UUID.generate() ] ) # Random => invalid
+          )
+
+          expect( result ).to be_nil
+        end
+      end
+
+      context 'exceptions' do
+        def expect_correct_rollback( &block )
+          starting_original = RSpecModelManualDateTest.manually_dated_contemporary.acquire_in( @context )
+          expect( starting_original ).to_not be_nil # Self-check this test
+
+          yield( block )
+
+          ending_original = RSpecModelManualDateTest.manually_dated_contemporary.acquire_in( @context )
+
+          expect( ending_original ).to_not be_nil
+          expect( starting_original.attributes ).to eq( ending_original.attributes )
+        end
+
+        it 'handles validation errors and does not change the contemporary record' do
+          expect_correct_rollback do
+            result = nil
+
+            expect {
+              result = RSpecModelManualDateTest.manually_dated_update_in(
+                @context,
+                attributes: { 'data' => BAD_DATA_FOR_VALIDATIONS }
+              )
+            }.to_not change( RSpecModelManualDateTest, :count )
+
+            expect( result ).to_not be_nil
+            expect( result.persisted? ).to eq( false )
+            expect( result.errors.messages ).to eq( { :data => [ 'contains bad text' ] } )
+          end
+        end
+
+        it 'correctly rolls back in the face of unexpected exceptions' do
+          expect_correct_rollback do
+            expect_any_instance_of( RSpecModelManualDateTest ).to receive( :save ) {
+              raise 'stop'
+            }
+
+            expect {
+              expect {
+                RSpecModelManualDateTest.manually_dated_update_in(
+                  @context,
+                  attributes: { 'data' => Hoodoo::UUID.generate() }
+                )
+              }.to raise_exception( RuntimeError, 'stop' )
+            }.to_not change( RSpecModelManualDateTest, :count )
+          end
+        end
+
+        it 'retries after one deadlock' do
+          raised = false
+
+          allow_any_instance_of( RSpecModelManualDateTest ).to receive( :update_column ) do | instance, name, value |
+            if raised == false
+              raised = true
+              raise ::ActiveRecord::StatementInvalid.new( 'MOCK DEADLOCK EXCEPTION' )
+            else
+              instance.update_attribute( name, value )
+            end
+          end
+
+          result = nil
+
+          expect {
+            result = RSpecModelManualDateTest.manually_dated_update_in(
+              @context,
+              attributes: { 'data' => Hoodoo::UUID.generate() }
+            )
+          }.to change( RSpecModelManualDateTest, :count ).by( 1 )
+
+          expect( result ).to_not be_nil
+          expect( result.errors ).to be_empty
+          expect( result.persisted? ).to eq( true )
+        end
+
+        it 'gives up after two deadlocks' do
+          allow_any_instance_of( RSpecModelManualDateTest ).to receive( :update_column ) do | instance, name, value |
+            raise ::ActiveRecord::StatementInvalid.new( 'MOCK DEADLOCK EXCEPTION' )
+          end
+
+          expect_correct_rollback do
+            expect {
+              result = RSpecModelManualDateTest.manually_dated_update_in(
+                @context,
+                attributes: { 'data' => Hoodoo::UUID.generate() }
+              )
+            }.to raise_exception( ::ActiveRecord::StatementInvalid )
+          end
+        end
+      end
+    end
+
+    context '#manually_dated_destruction_in' do
+      before :each do
+        @data   = Hoodoo::UUID.generate()
+        @record = RSpecModelManualDateTest.new( {
+          :data       => @data,
+          :created_at => @now,
+          :updated_at => @now
+        } )
+
+        @record.save!
+        sleep( ( 0.1 ** Hoodoo::ActiveRecord::ManuallyDated::SECONDS_DECIMAL_PLACES ) * 2 )
+
+        @old_updated_at = @record.updated_at
+
+        @context.request.instance_variable_set( '@ident', @record.uuid )
+      end
+
+      # Call only for 'successful' delete cases. Pass the result of a call to
+      # #manually_dated_update_in. Expects:
+      #
+      # * One fewer 'current' items
+      # * One more 'historic' item
+      # * One unscoped thing can now be found by @record's UUID
+      # * It should have the correct bounding dates and data.
+      #
+      # Remember that the very top of this file seeds in 2 contemporary and
+      # 4 historical entries, so counts are relative to that baseline.
+      #
+      def run_expectations( result )
+        expect( RSpecModelManualDateTest.manually_dated_contemporary.count ).to eq( 2 )
+        expect( RSpecModelManualDateTest.manually_dated_historic.count ).to eq( 5 )
+        expect( RSpecModelManualDateTest.manually_dated_contemporary.where( :uuid => @record.uuid ).count ).to eq( 0 )
+        expect( RSpecModelManualDateTest.manually_dated_historic.where( :uuid => @record.uuid ).count ).to eq( 1 )
+
+        # Current record is now at 'no'/nil time - i.e. actually Time.now. The
+        # time frozen into "@now" at the top of this file is by this point the
+        # historic time of the old record.
+
+        historic = RSpecModelManualDateTest.manually_dated_at( @now ).find_by_uuid( @record.uuid )
+
+        expect( historic.data ).to eq( @data )
+
+        expect( historic.effective_end ).to_not eq( @eot )
+        expect( historic.updated_at ).to eq( @old_updated_at )
+      end
+
+      it 'via context alone' do
+        result = RSpecModelManualDateTest.manually_dated_destruction_in(
+          @context
+        )
+
+        run_expectations( result )
+      end
+
+      # Generate a random => invalid UUID in the request data to prove that
+      # the valid one given in the input parameter is used as an override.
+      #
+      it 'specifying "ident"' do
+        @context.request.instance_variable_set( '@ident', Hoodoo::UUID.generate() )
+
+        result = RSpecModelManualDateTest.manually_dated_destruction_in(
+          @context,
+          ident: @record.uuid
+        )
+
+        run_expectations( result )
+      end
+
+      it 'uses a given scope' do
+
+        # We expect the custom scope to be customised to find an
+        # contemporary dated record for locking, if it's being used
+        # OK. This is fragile; depends heavily on implementation.
+
+        custom_scope = RSpecModelManualDateTest.where( :data => [ 'one', 'two', 'three' ] + [ @data ] )
+        expect( custom_scope ).to receive( :manually_dated_contemporary ).and_call_original
+
+        result = RSpecModelManualDateTest.manually_dated_destruction_in(
+          @context,
+          scope: custom_scope
+        )
+
+        run_expectations( result )
+      end
+
+      context 'handles not-found' do
+        it 'because of a bad identifier' do
+          result = RSpecModelManualDateTest.manually_dated_destruction_in(
+            @context,
+            ident: Hoodoo::UUID.generate() # Random => invalid
+          )
+
+          expect( result ).to be_nil
+        end
+
+        it 'because of a scope' do
+          result = RSpecModelManualDateTest.manually_dated_destruction_in(
+            @context,
+            scope: RSpecModelManualDateTest.where( :data => [ Hoodoo::UUID.generate() ] ) # Random => invalid
+          )
+
+          expect( result ).to be_nil
+        end
+      end
+    end
+
+    context 'update then delete' do
+      it 'works' do
+        record = RSpecModelManualDateTest.new( {
+          :data       => Hoodoo::UUID.generate(),
+          :created_at => @now,
+          :updated_at => @now
+        } )
+
+        record.save!
+
+        3.times do
+          result = RSpecModelManualDateTest.manually_dated_update_in(
+            @context,
+            ident: record.uuid,
+            attributes: { 'data' => Hoodoo::UUID.generate() }
+          )
+
+          expect( result ).to_not be_nil
+          expect( result.persisted? ).to eq( true )
+        end
+
+        result = RSpecModelManualDateTest.manually_dated_destruction_in(
+          @context,
+          ident: record.uuid
+        )
+
+        expect( result ).to_not be_nil
+
+        # We start with one current record, but it gets updated three times,
+        # creating three history entries. Then it gets deleted, creating
+        # another history entry and leaving no current ones.
+        #
+        # Remember that the very top of this file seeds in 2 contemporary and
+        # 4 historical entries, so counts are relative to that baseline.
+
+        expect( RSpecModelManualDateTest.manually_dated_contemporary.count ).to eq( 2 )
+        expect( RSpecModelManualDateTest.manually_dated_historic.count ).to eq( 8 )
+        expect( RSpecModelManualDateTest.manually_dated_contemporary.where( :uuid => record.uuid ).count ).to eq( 0 )
+        expect( RSpecModelManualDateTest.manually_dated_historic.where( :uuid => record.uuid ).count ).to eq( 4 )
+      end
+    end
+  end
+
+  context 'concurrent' do
+    before :all do
+      DatabaseCleaner.strategy = :truncation
+    end
+
+    after :all do
+      DatabaseCleaner.strategy = DATABASE_CLEANER_STRATEGY # spec_helper.rb
+    end
+
+    before :each do
+      @uuids   = []
+      @results = {}
+      @mutex   = Mutex.new
+
+      # From a pool of UUIDs, create a bunch of records.
+
+      50.times { @uuids << Hoodoo::UUID.generate }
+      @uuids.uniq! # Just in case I should've entered the lottery this week
+
+      @uuids.each do | uuid |
+        RSpecModelManualDateTest.new( {
+          :uuid => uuid,
+          :data => '0'
+        } ).save!
+      end
+    end
+
+    def add_result( uuid, result )
+      @mutex.synchronize do
+        @results[ uuid ] ||= []
+        @results[ uuid ] << result
+      end
+    end
+
+    # - Start threads that update the records with values, one update per thread
+    # - Check that the combined unscoped set has all integers and nothing more
+    # - Check there is only one contemporary entry per UUID and num-ints-minus-one
+    #   history entries
+    #
+    it 'updates work' do
+      values  = ( '1'..'9' ).to_a
+      threads = []
+
+      @uuids.each do | uuid |
+        values.each do | value |
+          threads << Thread.new do
+            ActiveRecord::Base.connection_pool.with_connection do
+              sleep 0.001 # Force Thread scheduler to run
+
+              result = RSpecModelManualDateTest.manually_dated_update_in(
+                @context,
+                ident: uuid,
+                attributes: { 'data' => value }
+              )
+
+              add_result( uuid, result )
+            end
+          end
+        end
+      end
+
+      threads.each { | thread | thread.join() }
+
+      @uuids.each do | uuid |
+        contemporary = RSpecModelManualDateTest.manually_dated_contemporary.where( :uuid => uuid ).to_a
+        historic     = RSpecModelManualDateTest.manually_dated_historic.where( :uuid => uuid ).to_a
+
+        expect( contemporary.count ).to eq( 1 )
+        expect( historic.count     ).to eq( values.count )
+
+        # Across all records, the starting data value of "0" plus any
+        # new items in "values" should be present exactly once.
+
+        combined = ( contemporary + historic ).map( & :data )
+        expect( combined ).to match_array( [ '0' ] + values )
+
+        # All results should be persisted model instances which, once
+        # reloaded, only have one contemporary entry and the rest historic.
+        # This double-checks the database query tests a few lines above.
+
+        results = @results[ uuid ]
+
+        results.each do | result |
+          expect( result ).to be_a( RSpecModelManualDateTest )
+          expect( result.errors ).to be_empty
+          expect( result.persisted? ).to eq( true )
+
+          result.reload
+        end
+
+        dates  = results.map( & :effective_end )
+        eots   = dates.select() { | date | date == @eot }
+        others = dates.reject() { | date | date == @eot }
+
+        # "- 1" because the results Hash only contains results of the
+        # *updates* we did, not the original starting record.
+
+        expect(   eots.count ).to eq( 1 )
+        expect( others.count ).to eq( values.count - 1 )
+      end
+    end
+
+    # - Start several threads that delete the same records
+    # - Push results into the results hash
+    # - Check that only one thread succeeded, rest of them got 'nil' (not found),
+    #     only one history entry per UUID, no contemporary entry per UUID.
+    #
+    it 'deletions work' do
+      threads  = []
+      attempts = 10
+
+      @uuids.each do | uuid |
+        attempts.times do
+          threads << Thread.new do
+            ActiveRecord::Base.connection_pool.with_connection do
+              result = RSpecModelManualDateTest.manually_dated_destruction_in(
+                @context,
+                ident: uuid
+              )
+
+              add_result( uuid, result )
+            end
+          end
+        end
+      end
+
+      threads.each { | thread | thread.join() }
+
+      @uuids.each do | uuid |
+        contemporary = RSpecModelManualDateTest.manually_dated_contemporary.where( :uuid => uuid ).to_a
+        historic     = RSpecModelManualDateTest.manually_dated_historic.where( :uuid => uuid ).to_a
+
+        expect( contemporary.count ).to eq( 0 )
+        expect( historic.count     ).to eq( 1 )
+
+        # We expect all results to contain one success and lots of failures.
+
+        results   = @results[ uuid ]
+        failures  = results.select() { | result | result.nil? }
+        successes = results.reject() { | result | result.nil? }
+
+        expect( failures.count  ).to eq( attempts - 1 )
+        expect( successes.count ).to eq( 1 )
+
+        success = successes.first
+        success.reload
+
+        expect( success ).to be_a( RSpecModelManualDateTest )
+        expect( success.errors ).to be_empty
+        expect( success.persisted? ).to eq( true )
+        expect( success.effective_end ).to_not eq( @eot )
+      end
+    end
+
+  end
+end