hoodoo 1.14.0 → 1.15.0

data/lib/hoodoo/transient_store/transient_store.rb

@@ -87,7 +87,7 @@ module Hoodoo
     #
     attr_reader :storage_engine
 
-    # Read the storage engine insteance for the #storage_engine - this allows
+    # Read the storage engine instance for the #storage_engine - this allows
     # engine-specific configuration to be set where available, though this is
     # strongly discouraged as it couples client code to the engine in use,
     # defeating the main rationale behind the TransientStore abstraction.
@@ -256,7 +256,11 @@ module Hoodoo
     #
     # _Named_ parameters are:
     #
-    # +key+:: Key previously given to #set.
+    # +key+::         Key previously given to #set.
+    #
+    # +allow_throw+:: If +true+, exceptions raised by the underlying storage
+    #                 engine are thrown, else ignored and +nil+ is returned.
+    #                 Optional; default is +false+.
     #
     # Returns +nil+ if the item is not found - either the key is wrong, the
     # stored data has expired or the stored data has been evicted early from
@@ -265,9 +269,14 @@ module Hoodoo
     # Only non-empty String or Symbol keys are permitted, else an exception
     # will be raised.
     #
-    def get( key: )
+    def get( key:, allow_throw: false )
       key = normalise_key( key, 'get' )
-      @storage_engine_instance.get( key: key ) rescue nil
+
+      begin
+        @storage_engine_instance.get( key: key )
+      rescue
+        raise if allow_throw
+      end
     end
 
     # Delete data previously stored with #set.

data/lib/hoodoo/transient_store/transient_store/memcached.rb

@@ -21,6 +21,14 @@ module Hoodoo
     #
     class Memcached < Hoodoo::TransientStore::Base
 
+      # Overrideable access to this object's Dalli::Client instance. It is
+      # inadvisable to couple calling code directly into this interface as it
+      # is a Hoodoo::TransientStore::Memcached specialisation, but if deemed
+      # absolutely necessary the Dalli client can be override with a
+      # customised version.
+      #
+      attr_accessor :client
+
       # See Hoodoo::TransientStore::Base::new for details.
       #
       # Do not instantiate this class directly. Use

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.14.0'
+  VERSION = '1.15.0'
 
 end

data/spec/active/active_record/finder_spec.rb

@@ -309,7 +309,7 @@ describe Hoodoo::ActiveRecord::Finder do
     context 'only makes one database call when' do
 
       it 'finding on the first attribute' do
-        count = count_database_calls_in do
+        count = spec_helper_count_database_calls_in do
           found = RSpecModelFinderTest.acquire( @id )
           expect( found ).to eq(@a)
         end
@@ -318,7 +318,7 @@ describe Hoodoo::ActiveRecord::Finder do
       end
 
       it 'finding on the second attribute' do
-        count = count_database_calls_in do
+        count = spec_helper_count_database_calls_in do
           found = RSpecModelFinderTest.acquire( @uuid )
           expect( found ).to eq(@b)
         end
@@ -327,7 +327,7 @@ describe Hoodoo::ActiveRecord::Finder do
       end
 
       it 'finding on the third attribute' do
-        count = count_database_calls_in do
+        count = spec_helper_count_database_calls_in do
           found = RSpecModelFinderTest.acquire( @code )
           expect( found ).to eq(@c)
         end
@@ -336,7 +336,7 @@ describe Hoodoo::ActiveRecord::Finder do
       end
 
       it 'checking all three attributes but finding nothing' do
-        count = count_database_calls_in do
+        count = spec_helper_count_database_calls_in do
           found = RSpecModelFinderTest.acquire( Hoodoo::UUID.generate )
           expect( found ).to be_nil
         end

data/spec/client/client_spec.rb

@@ -214,6 +214,10 @@ end
 
 describe Hoodoo::Client do
 
+  before :each do
+    spec_helper_use_mock_memcached()
+  end
+
   before :all do
     @old_test_session = Hoodoo::Services::Middleware.test_session()
     @port = spec_helper_start_svc_app_in_thread_for( RSpecClientTestService )

data/spec/services/middleware/middleware_permissions_spec.rb

@@ -304,6 +304,8 @@ end
 describe Hoodoo::Services::Middleware do
 
   before :each do
+    spec_helper_use_mock_memcached()
+
     @session_id     = Hoodoo::UUID.generate
     @caller_id      = Hoodoo::UUID.generate
     @caller_version = 1
@@ -343,14 +345,8 @@ describe Hoodoo::Services::Middleware do
       Hoodoo::Services::Permissions::ALLOW
     )
 
-    Hoodoo::TransientStore::Mocks::DalliClient.reset()
-
-    result = @session.save_to_memcached
-    raise "Can't save to mock Memcached (result = #{result})" unless result == :ok
-  end
-
-  after :each do
-    Hoodoo::TransientStore::Mocks::DalliClient.reset()
+    result = @session.save_to_store
+    raise "Can't save to mock session store (result = #{result})" unless result == :ok
   end
 
   ############################################################################
@@ -398,8 +394,8 @@ describe Hoodoo::Services::Middleware do
           Hoodoo::Services::Permissions::ALLOW
         )
 
-        result = @session.save_to_memcached
-        raise "Can't save to mock Memcached (result = #{result})" unless result == :ok
+        result = @session.save_to_store
+        raise "Can't save to mock session store (result = #{result})" unless result == :ok
 
         expect_any_instance_of(RSpecAddPermTestClockCallsDateNoPermsImplementation).to receive( :show ).once.and_call_original
         expect_any_instance_of(RSpecAddPermTestDateImplementation).to receive( :show ).once.and_call_original
@@ -432,8 +428,8 @@ describe Hoodoo::Services::Middleware do
           Hoodoo::Services::Permissions::ALLOW
         )
 
-        result = @session.save_to_memcached
-        raise "Can't save to mock Memcached (result = #{result})" unless result == :ok
+        result = @session.save_to_store
+        raise "Can't save to mock session store (result = #{result})" unless result == :ok
 
         expect_any_instance_of(RSpecAddPermTestClockCallsDateNoPermsImplementation).to receive( :show ).once.and_call_original
         expect_any_instance_of(RSpecAddPermTestDateImplementation).to receive( :show ).once.and_call_original
@@ -488,8 +484,8 @@ describe Hoodoo::Services::Middleware do
           Hoodoo::Services::Permissions::ALLOW
         )
 
-        result = @session.save_to_memcached
-        raise "Can't save to mock Memcached (result = #{result})" unless result == :ok
+        result = @session.save_to_store
+        raise "Can't save to mock session store (result = #{result})" unless result == :ok
 
         expect_any_instance_of(RSpecAddPermTestClockCallsDateNoPermsImplementation).to receive( :show ).once.and_call_original
         expect_any_instance_of(RSpecAddPermTestDateImplementation).to receive( :show ).once.and_call_original
@@ -578,8 +574,8 @@ describe Hoodoo::Services::Middleware do
           Hoodoo::Services::Permissions::ALLOW
         )
 
-        result = @session.save_to_memcached
-        raise "Can't save to mock Memcached (result = #{result})" unless result == :ok
+        result = @session.save_to_store
+        raise "Can't save to mock session store (result = #{result})" unless result == :ok
 
         expect_any_instance_of(RSpecAddPermTestClockImplementation).to receive( :list ).once.and_call_original
         expect_any_instance_of(RSpecAddPermTestDateImplementation).to receive( :show ).once.and_call_original
@@ -646,7 +642,7 @@ describe Hoodoo::Services::Middleware do
         #
         it 'can deal with inter-resource session errors (2)' do
           expect_any_instance_of(RSpecAddPermTestClockImplementation).to receive( :show ).once.and_call_original
-          expect_any_instance_of(Hoodoo::Services::Session).to receive( :save_to_memcached ).once.and_return( :outdated )
+          expect_any_instance_of(Hoodoo::Services::Session).to receive( :save_to_store ).once.and_return( :outdated )
           expect_any_instance_of(RSpecAddPermTestDateImplementation).to_not receive( :show )
 
           get '/v1/rspec_add_perm_test_clocks/any',
@@ -663,7 +659,7 @@ describe Hoodoo::Services::Middleware do
         #
         it 'can deal with inter-resource session errors (3)' do
           expect_any_instance_of(RSpecAddPermTestClockImplementation).to receive( :show ).once.and_call_original
-          expect_any_instance_of(Hoodoo::Services::Session).to receive( :save_to_memcached ).once.and_return( :fail )
+          expect_any_instance_of(Hoodoo::Services::Session).to receive( :save_to_store ).once.and_return( :fail )
           expect_any_instance_of(RSpecAddPermTestDateImplementation).to_not receive( :show )
 
           get '/v1/rspec_add_perm_test_clocks/any',
@@ -683,8 +679,8 @@ describe Hoodoo::Services::Middleware do
         it 'handles nil permissions' do
           @session.permissions = nil
 
-          result = @session.save_to_memcached
-          raise "Can't save to mock Memcached (result = #{result})" unless result == :ok
+          result = @session.save_to_store
+          raise "Can't save to mock session store (result = #{result})" unless result == :ok
 
           expect_any_instance_of(RSpecAddPermTestClockImplementation).to_not receive( :show )
 
@@ -701,8 +697,8 @@ describe Hoodoo::Services::Middleware do
         it 'handles empty permissions' do
           @session.permissions = Hoodoo::Services::Permissions.new( {} )
 
-          result = @session.save_to_memcached
-          raise "Can't save to mock Memcached (result = #{result})" unless result == :ok
+          result = @session.save_to_store
+          raise "Can't save to mock session store (result = #{result})" unless result == :ok
 
           expect_any_instance_of(RSpecAddPermTestClockImplementation).to_not receive( :show )
 
@@ -719,8 +715,8 @@ describe Hoodoo::Services::Middleware do
         it 'handles default #verify response as deny' do
           @session.permissions.set_resource( :RSpecAddPermTestClock, :show, Hoodoo::Services::Permissions::ASK )
 
-          result = @session.save_to_memcached
-          raise "Can't save to mock Memcached (result = #{result})" unless result == :ok
+          result = @session.save_to_store
+          raise "Can't save to mock session store (result = #{result})" unless result == :ok
 
           expect_any_instance_of(Hoodoo::Services::Implementation).to receive( :verify ).once.and_call_original
           expect_any_instance_of(RSpecAddPermTestClockImplementation).to_not receive( :show ).once.and_call_original
@@ -802,8 +798,8 @@ describe Hoodoo::Services::Middleware do
           Hoodoo::Services::Permissions::ALLOW
         )
 
-        result = @session.save_to_memcached
-        raise "Can't save to mock Memcached (result = #{result})" unless result == :ok
+        result = @session.save_to_store
+        raise "Can't save to mock session store (result = #{result})" unless result == :ok
 
         expect_any_instance_of(RSpecAddPermTestClockCallsDateNoPermsImplementation).to receive( :show ).once.and_call_original
         expect_any_instance_of(RSpecAddPermTestDateImplementation).to receive( :show ).once.and_call_original
@@ -834,8 +830,8 @@ describe Hoodoo::Services::Middleware do
           Hoodoo::Services::Permissions::ALLOW
         )
 
-        result = @session.save_to_memcached
-        raise "Can't save to mock Memcached (result = #{result})" unless result == :ok
+        result = @session.save_to_store
+        raise "Can't save to mock session store (result = #{result})" unless result == :ok
 
         expect_any_instance_of(RSpecAddPermTestClockCallsDateNoPermsImplementation).to receive( :show ).once.and_call_original
         expect_any_instance_of(RSpecAddPermTestDateImplementation).to receive( :show ).once.and_call_original
@@ -879,8 +875,8 @@ describe Hoodoo::Services::Middleware do
           Hoodoo::Services::Permissions::ALLOW
         )
 
-        result = @session.save_to_memcached
-        raise "Can't save to mock Memcached (result = #{result})" unless result == :ok
+        result = @session.save_to_store
+        raise "Can't save to mock session store (result = #{result})" unless result == :ok
 
         expect_any_instance_of(RSpecAddPermTestClockCallsDateNoPermsImplementation).to receive( :show ).once.and_call_original
         expect_any_instance_of(RSpecAddPermTestDateImplementation).to receive( :show ).once.and_call_original
@@ -954,8 +950,8 @@ describe Hoodoo::Services::Middleware do
           Hoodoo::Services::Permissions::ALLOW
         )
 
-        result = @session.save_to_memcached
-        raise "Can't save to mock Memcached (result = #{result})" unless result == :ok
+        result = @session.save_to_store
+        raise "Can't save to mock session store (result = #{result})" unless result == :ok
 
         expect_any_instance_of(RSpecAddPermTestClockImplementation).to receive( :list ).once.and_call_original
         expect_any_instance_of(RSpecAddPermTestDateImplementation).to receive( :show ).once.and_call_original

data/spec/services/services/session_spec.rb

@@ -1,459 +1,591 @@
 require 'spec_helper'
+require 'hoodoo/transient_store/mocks/dalli_client'
 
 describe Hoodoo::Services::Session do
 
   before :each do
-    Hoodoo::TransientStore::Mocks::DalliClient.reset()
+    spec_helper_use_mock_memcached()
   end
 
-  it 'includes a legacy alias to the TransientStore mock back-end' do
-    expect( Hoodoo::Services::Session::MockDalliClient == Hoodoo::TransientStore::Mocks::DalliClient ).to eql( true )
-    expect {
-      Hoodoo::TransientStore::Mocks::DalliClient.reset()
-    }.to_not raise_error
-  end
+  # ==========================================================================
 
-  it 'initialises with default options' do
-    s = described_class.new()
-    expect( s.created_at ).to be_a( Time )
-    expect( Hoodoo::UUID.valid?( s.session_id ) ).to eq( true )
-    expect( s.memcached_host ).to be_nil
-    expect( s.caller_id ).to be_nil
-    expect( s.caller_version ).to eq( 0 )
-  end
+  context 'basics' do
+    it 'initialises with default options' do
+      s = described_class.new()
+      expect( s.created_at ).to be_a( Time )
+      expect( Hoodoo::UUID.valid?( s.session_id ) ).to eq( true )
+      expect( s.memcached_host ).to be_nil
+      expect( s.caller_id ).to be_nil
+      expect( s.caller_version ).to eq( 0 )
+    end
 
-  it 'initialises with given options' do
-    s = described_class.new(
-      :session_id => '1234',
-      :memcached_host => 'abcd',
-      :caller_id => '0987',
-      :caller_version => 2
-    )
-    expect( s.created_at ).to be_a( Time )
-    expect( s.session_id ).to eq( '1234' )
-    expect( s.memcached_host ).to eq( 'abcd' )
-    expect( s.caller_id ).to eq( '0987' )
-    expect( s.caller_version ).to eq( 2 )
-  end
+    it 'initialises with given options' do
+      s = described_class.new(
+        :session_id => '1234',
+        :memcached_host => 'abcd',
+        :caller_id => '0987',
+        :caller_version => 2
+      )
+      expect( s.created_at ).to be_a( Time )
+      expect( s.session_id ).to eq( '1234' )
+      expect( s.memcached_host ).to eq( 'abcd' )
+      expect( s.caller_id ).to eq( '0987' )
+      expect( s.caller_version ).to eq( 2 )
+    end
 
-  it 'reports not expired when it has no expiry' do
-    s = described_class.new
-    expect( s.expired? ).to eq( false )
-  end
+    it 'reports not expired when it has no expiry' do
+      s = described_class.new
+      expect( s.expired? ).to eq( false )
+    end
 
-  it 'knows if expired' do
-    s = described_class.new
-    s.instance_variable_set( '@expires_at', Time.now - 1 )
-    expect( s.expired? ).to eq( true )
-  end
+    it 'knows if expired' do
+      s = described_class.new
+      s.instance_variable_set( '@expires_at', Time.now - 1 )
+      expect( s.expired? ).to eq( true )
+    end
 
-  it 'converts to a Hash' do
-    s = described_class.new(
-      :session_id => '1234',
-      :memcached_host => 'abcd',
-      :caller_id => '0987',
-      :caller_version => 2
-    )
-    p = Hoodoo::Services::Permissions.new
+    it 'converts to a Hash' do
+      s = described_class.new(
+        :session_id => '1234',
+        :memcached_host => 'abcd',
+        :caller_id => '0987',
+        :caller_version => 2
+      )
+      p = Hoodoo::Services::Permissions.new
 
-    s.permissions = p
-    s.identity = { 'foo' => 'foo', 'bar' => 'bar' }
-    s.scoping = { 'baz' => [ 'foo', 'bar', 'baz' ] }
+      s.permissions = p
+      s.identity = { 'foo' => 'foo', 'bar' => 'bar' }
+      s.scoping = { 'baz' => [ 'foo', 'bar', 'baz' ] }
 
-    h = s.to_h
+      h = s.to_h
 
-    expect( h ).to eq( {
-      'session_id'     => '1234',
-      'caller_id'      => '0987',
-      'caller_version' => 2,
+      expect( h ).to eq( {
+        'session_id'     => '1234',
+        'caller_id'      => '0987',
+        'caller_version' => 2,
 
-      'created_at'     => s.created_at.iso8601,
+        'created_at'     => s.created_at.iso8601,
 
-      'identity'       => { 'foo' => 'foo', 'bar' => 'bar' },
-      'scoping'        => { 'baz' => [ 'foo', 'bar', 'baz' ] },
-      'permissions'    => p.to_h()
-    } )
-  end
+        'identity'       => { 'foo' => 'foo', 'bar' => 'bar' },
+        'scoping'        => { 'baz' => [ 'foo', 'bar', 'baz' ] },
+        'permissions'    => p.to_h()
+      } )
+    end
 
-  it 'reads from a Hash' do
-    s = described_class.new
-    p = Hoodoo::Services::Permissions.new
-    c = Time.now.utc
-    e = Time.now.utc + 10
-    h = {
-      'session_id'     => '1234',
-      'caller_id'      => '0987',
-      'caller_version' => 2,
-
-      'created_at'     => c.iso8601,
-      'expires_at'     => e.iso8601,
-
-      'identity'       => { 'foo' => 'foo', 'bar' => 'bar' },
-      'scoping'        => { 'baz' => [ 'foo', 'bar', 'baz' ] },
-      'permissions'    => p.to_h()
-    }
-
-    s.from_h!( h )
-
-    expect( s.session_id ).to eq( '1234' )
-    expect( s.caller_id ).to eq( '0987' )
-    expect( s.caller_version ).to eq( 2 )
-    expect( s.created_at ).to eq( Time.parse( c.iso8601 ) )
-    expect( s.expires_at ).to eq( Time.parse( e.iso8601 ) )
-    expect( s.identity.foo ).to eq( 'foo' )
-    expect( s.identity.bar ).to eq( 'bar' )
-    expect( s.scoping.baz ).to eq( [ 'foo', 'bar', 'baz' ] )
-    expect( s.permissions.to_h ).to eq( p.to_h )
-  end
+    it 'reads from a Hash' do
+      s = described_class.new
+      p = Hoodoo::Services::Permissions.new
+      c = Time.now.utc
+      e = Time.now.utc + 10
+      h = {
+        'session_id'     => '1234',
+        'caller_id'      => '0987',
+        'caller_version' => 2,
+
+        'created_at'     => c.iso8601,
+        'expires_at'     => e.iso8601,
+
+        'identity'       => { 'foo' => 'foo', 'bar' => 'bar' },
+        'scoping'        => { 'baz' => [ 'foo', 'bar', 'baz' ] },
+        'permissions'    => p.to_h()
+      }
+
+      s.from_h!( h )
+
+      expect( s.session_id ).to eq( '1234' )
+      expect( s.caller_id ).to eq( '0987' )
+      expect( s.caller_version ).to eq( 2 )
+      expect( s.created_at ).to eq( Time.parse( c.iso8601 ) )
+      expect( s.expires_at ).to eq( Time.parse( e.iso8601 ) )
+      expect( s.identity.foo ).to eq( 'foo' )
+      expect( s.identity.bar ).to eq( 'bar' )
+      expect( s.scoping.baz ).to eq( [ 'foo', 'bar', 'baz' ] )
+      expect( s.permissions.to_h ).to eq( p.to_h )
+    end
 
-  it 'saves/loads to/from Memcached' do
-    s1 = described_class.new(
-      :session_id => '1234',
-      :memcached_host => 'abcd',
-      :caller_id => '0987',
-      :caller_version => 2
-    )
-
-    expect( s1.save_to_memcached ).to eq( :ok )
-
-    store = Hoodoo::TransientStore::Mocks::DalliClient.store()
-    expect( store[ '1234' ] ).to_not be_nil
-    expect( store[ '0987' ] ).to eq( { :expires_at => nil, :value => { 'version' => 2 } } )
-
-    # Check that session gains an expiry time when saved.
-    #
-    expect( s1.expires_at ).to be_a( Time )
-
-    # Ensure "created_at" is significantly different in the next session.
-    # This is important to reliably detect session load failures in testing
-    # given "#iso8601()" time resolution limits and so-on.
-    #
-    sleep( 0.2 )
-
-    s2 = described_class.new
-    expect( s2.load_from_memcached!( s1.session_id ) ).to eq( :ok )
-
-    expect( s2.created_at ).to eq( Time.parse( s1.created_at.iso8601 ) )
-    expect( s2.expires_at ).to eq( Time.parse( s1.expires_at.iso8601 ) )
-    expect( s2.session_id ).to eq( s1.session_id )
-    expect( s2.memcached_host ).to be_nil
-    expect( s2.caller_id ).to eq( s1.caller_id )
-    expect( s2.caller_version ).to eq( s1.caller_version )
-  end
+    it 'saves/loads to/from Memcached' do
+      s1 = described_class.new(
+        :session_id => '1234',
+        :memcached_host => 'abcd',
+        :caller_id => '0987',
+        :caller_version => 2
+      )
+
+      expect( s1.save_to_store ).to eq( :ok )
+
+      store = Hoodoo::TransientStore::Mocks::DalliClient.store()
+      expect( store[ '1234' ] ).to_not be_nil
+      expect( store[ '0987' ] ).to include( { :value => { 'version' => 2 } } )
+      expect( store[ '0987' ] ).to have_key( :expires_at )
+      expect( store[ '0987' ][ :expires_at ] ).to be_a( Time )
+
+      # Check that session gains an expiry time when saved.
+      #
+      expect( s1.expires_at ).to be_a( Time )
+
+      # Ensure "created_at" is significantly different in the next session.
+      # This is important to reliably detect session load failures in testing
+      # given "#iso8601()" time resolution limits and so-on.
+      #
+      sleep( 0.2 )
+
+      s2 = described_class.new
+      expect( s2.load_from_store!( s1.session_id ) ).to eq( :ok )
+
+      expect( s2.created_at ).to eq( Time.parse( s1.created_at.iso8601 ) )
+      expect( s2.expires_at ).to eq( Time.parse( s1.expires_at.iso8601 ) )
+      expect( s2.session_id ).to eq( s1.session_id )
+      expect( s2.memcached_host ).to be_nil
+      expect( s2.caller_id ).to eq( s1.caller_id )
+      expect( s2.caller_version ).to eq( s1.caller_version )
+    end
 
-  it 'refuses to save if a newer caller version is present' do
-    expect( described_class ).to receive( :connect_to_memcached ).twice.and_return( Hoodoo::TransientStore::Mocks::DalliClient.new )
+    it 'can be deleted' do
+      s = described_class.new(
+        :session_id => '1234',
+        :memcached_host => 'abcd',
+        :caller_id => '0987',
+        :caller_version => 1
+      )
 
-    # Save a session with a high caller version
+      s.save_to_store
 
-    s1 = described_class.new(
-      :session_id => '1234',
-      :memcached_host => 'abcd',
-      :caller_id => '0987',
-      :caller_version => 4
-    )
+      expect{ s.delete_from_store }.to change{ s.load_from_store!( s.session_id ) }.from( :ok ).to( :not_found )
+    end
 
-    expect( s1.save_to_memcached ).to eq( :ok )
+    it 'handles attempts to delete not-found things' do
+      s = described_class.new(
+        :session_id => '1234',
+        :memcached_host => 'abcd',
+        :caller_id => '0987',
+        :caller_version => 1
+      )
 
-    # Save another with, initially, a lower caller version. The idea here
-    # is that session creation is underway when a caller gets updated.
+      expect( s.delete_from_store ).to eq( :ok )
+    end
+  end
 
-    s2 = described_class.new(
-      :session_id => '2345',
-      :memcached_host => 'abcd',
-      :caller_id => '0987',
-      :caller_version => 3
-    )
+  # ==========================================================================
 
-    expect( s2.save_to_memcached ).to eq( :outdated )
-  end
+  context 'version manager' do
+    it 'refuses to save if a newer caller version is present' do
 
-  it 'invalidates a session if the client ID advances during its lifetime' do
-    expect( described_class ).to receive( :connect_to_memcached ).exactly( 4 ).times.and_return( Hoodoo::TransientStore::Mocks::DalliClient.new )
-    loader = described_class.new
+      # Save a session with a high caller version
 
-    # Save a session with a low caller version.
+      s1 = described_class.new(
+        :session_id => '1234',
+        :memcached_host => 'abcd',
+        :caller_id => '0987',
+        :caller_version => 4
+      )
 
-    s1 = described_class.new(
-      :session_id => '1234',
-      :memcached_host => 'abcd',
-      :caller_id => '0987',
-      :caller_version => 1
-    )
+      expect( s1.save_to_store ).to eq( :ok )
 
-    expect( s1.save_to_memcached ).to eq( :ok )
+      # Save another with, initially, a lower caller version. The idea here
+      # is that session creation is underway when a caller gets updated.
 
-    # Save another with a higher caller version.
+      s2 = described_class.new(
+        :session_id => '2345',
+        :memcached_host => 'abcd',
+        :caller_id => '0987',
+        :caller_version => 3
+      )
 
-    s2 = described_class.new(
-      :session_id => '2345',
-      :memcached_host => 'abcd',
-      :caller_id => '0987',
-      :caller_version => 2
-    )
+      expect( s2.save_to_store ).to eq( :outdated )
+    end
 
-    expect( s2.save_to_memcached ).to eq( :ok )
+    it 'invalidates a session if the caller version advances during its lifetime' do
+      loader = described_class.new
 
-    # Should not be able to load the first one anymore.
+      # Save a session with a low caller version.
 
-    expect( loader.load_from_memcached!( '1234' ) ).to eq( :outdated )
-    expect( loader.load_from_memcached!( '2345' ) ).to eq( :ok       )
-  end
+      s1 = described_class.new(
+        :session_id => '1234',
+        :memcached_host => 'abcd',
+        :caller_id => '0987',
+        :caller_version => 1
+      )
 
-  it 'refuses to load if the caller version is outdated' do
-    expect( described_class ).to receive( :connect_to_memcached ).exactly( 5 ).times.and_return( Hoodoo::TransientStore::Mocks::DalliClient.new )
-    loader = described_class.new
+      expect( s1.save_to_store ).to eq( :ok )
 
-    # Save a session with a low caller version
+      # Save another with a higher caller version.
 
-    s1 = described_class.new(
-      :session_id => '1234',
-      :memcached_host => 'abcd',
-      :caller_id => '0987',
-      :caller_version => 1
-    )
+      s2 = described_class.new(
+        :session_id => '2345',
+        :memcached_host => 'abcd',
+        :caller_id => '0987',
+        :caller_version => 2
+      )
 
-    expect( s1.save_to_memcached ).to eq( :ok )
+      expect( s2.save_to_store ).to eq( :ok )
 
-    # Should be able to load it back.
+      # Should not be able to load the first one anymore.
 
-    expect( loader.load_from_memcached!( '1234' ) ).to eq( :ok )
+      expect( loader.load_from_store!( '1234' ) ).to eq( :outdated )
+      expect( loader.load_from_store!( '2345' ) ).to eq( :ok       )
+    end
 
-    # Save another with a higher caller version.
+    it 'refuses to load session if the caller version is outdated' do
+      loader = described_class.new
 
-    s2 = described_class.new(
-      :session_id => '2345',
-      :memcached_host => 'abcd',
-      :caller_id => '0987',
-      :caller_version => 2
-    )
+      # Save a session with a low caller version
 
-    expect( s2.save_to_memcached ).to eq( :ok )
+      s1 = described_class.new(
+        :session_id => '1234',
+        :memcached_host => 'abcd',
+        :caller_id => '0987',
+        :caller_version => 1
+      )
 
-    # Try to load the first one again; should fail.
+      expect( s1.save_to_store ).to eq( :ok )
 
-    expect( loader.load_from_memcached!( '1234' ) ).to eq( :outdated )
+      # Should be able to load it back.
 
-    # The newer one should load OK.
+      expect( loader.load_from_store!( '1234' ) ).to eq( :ok )
 
-    expect( loader.load_from_memcached!( '2345' ) ).to eq( :ok )
-  end
+      # Save another with a higher caller version.
 
-  it 'refuses to load if expired' do
-    expect( described_class ).to receive( :connect_to_memcached ).twice.and_return( Hoodoo::TransientStore::Mocks::DalliClient.new )
-    loader = described_class.new
+      s2 = described_class.new(
+        :session_id => '2345',
+        :memcached_host => 'abcd',
+        :caller_id => '0987',
+        :caller_version => 2
+      )
 
-    # Save a session with a high caller version
+      expect( s2.save_to_store ).to eq( :ok )
 
-    s = described_class.new(
-      :session_id => '1234',
-      :memcached_host => 'abcd',
-      :caller_id => '0987',
-      :caller_version => 1
-    )
+      # Try to load the first one again; should fail.
 
-    expect( s ).to receive( :to_h ).and_wrap_original do | obj, args |
-      h = obj.call( *args )
-      h[ 'expires_at' ] = ( Time.now - 1 ).utc.iso8601
-      h
-    end
+      expect( loader.load_from_store!( '1234' ) ).to eq( :outdated )
 
-    expect( s.save_to_memcached ).to eq( :ok )
-    expect( loader.load_from_memcached!( '1234' ) ).to eq( :outdated )
-  end
+      # The newer one should load OK.
+
+      expect( loader.load_from_store!( '2345' ) ).to eq( :ok )
+    end
 
-  it 'can explicitly update a caller' do
-    s = described_class.new(
-      :session_id => '1234',
-      :memcached_host => 'abcd',
-      :caller_id => '0987',
-      :caller_version => 1
-    )
+    it 'refuses to load session if the caller version is missing/expired' do
+      loader = described_class.new
+
+      # Save a session for caller ID '0987'.
+      #
+      s1 = described_class.new(
+        :session_id => '1234',
+        :memcached_host => 'abcd',
+        :caller_id => '0987',
+        :caller_version => 1
+      )
+
+      expect( s1.save_to_store ).to eq( :ok )
+
+      # Should be able to load it back.
+      #
+      expect( loader.load_from_store!( '1234' ) ).to eq( :ok )
+
+      # Manually wipe the caller version record, simulating expiry.
+      #
+      store = Hoodoo::TransientStore::Mocks::DalliClient.store()
+      store.delete( '0987' )
+
+      # Create a new session for some random other caller, reaffirming
+      # that we can still create new sessions for previously unrecorded
+      # caller IDs/versions.
+
+      s2 = described_class.new(
+        :session_id => '2345',
+        :memcached_host => 'abcd',
+        :caller_id => Hoodoo::UUID.generate(),
+        :caller_version => 1
+      )
+
+      expect( s2.save_to_store ).to eq( :ok )
+
+      # Try to load the first one again; should fail.
+      #
+      expect( loader.load_from_store!( '1234' ) ).to eq( :outdated )
+
+      # The newer one should load OK.
+      #
+      expect( loader.load_from_store!( '2345' ) ).to eq( :ok )
+    end
 
-    expect( described_class ).to receive( :connect_to_memcached ).once.and_return( Hoodoo::TransientStore::Mocks::DalliClient.new )
+    it 'refuses to load session if the session itself is expired' do
+      loader = described_class.new
 
-    expect( s.update_caller_version_in_memcached( '9944', 23                                                 ) ).to eq( :ok )
-    expect( s.update_caller_version_in_memcached( 'abcd', 2,  Hoodoo::TransientStore::Mocks::DalliClient.new ) ).to eq( :ok )
+      # Save a session with a high caller version
 
-    store = Hoodoo::TransientStore::Mocks::DalliClient.store()
-    expect( store[ '9944' ] ).to eq( { :expires_at => nil, :value => { 'version' => 23 } } )
-    expect( store[ 'abcd' ] ).to eq( { :expires_at => nil, :value => { 'version' => 2  } } )
-  end
+      s = described_class.new(
+        :session_id => '1234',
+        :memcached_host => 'abcd',
+        :caller_id => '0987',
+        :caller_version => 1
+      )
 
-  it 'handles invalid session IDs when loading' do
-    expect( described_class ).to receive( :connect_to_memcached ).once.and_return( Hoodoo::TransientStore::Mocks::DalliClient.new )
-    loader = described_class.new
-    expect( loader.load_from_memcached!( '1234' ) ).to eq( :not_found )
-  end
+      expect( s ).to receive( :to_h ).and_wrap_original do | obj, args |
+        h = obj.call( *args )
+        h[ 'expires_at' ] = ( Time.now - 1 ).utc.iso8601
+        h
+      end
 
-  it 'complains if there is no caller ID' do
-    s = described_class.new
-    expect {
-      s.save_to_memcached()
-    }.to raise_error RuntimeError
+      expect( s.save_to_store ).to eq( :ok )
+      expect( loader.load_from_store!( '1234' ) ).to eq( :outdated )
+    end
   end
 
-  it 'logs Memcached exceptions when loading' do
-    loader = described_class.new
+  # ==========================================================================
 
-    expect_any_instance_of( Hoodoo::TransientStore::Mocks::DalliClient ).to receive( :get ).once do
-      raise 'Mock Memcached connection failure'
+  context 'can explicitly update a caller' do
+    before :each do
+      @session = described_class.new(
+        :session_id => '1234',
+        :memcached_host => 'abcd',
+        :caller_id => '0987',
+        :caller_version => 1
+      )
     end
 
-    expect( Hoodoo::Services::Middleware.logger ).to(
-      receive( :warn ).once.with(
-        'Hoodoo::Services::Session\\#load_from_memcached!: Session loading failed - connection fault or session corrupt',
-        'Mock Memcached connection failure'
-      ).and_call_original
-    )
+    after :each do
+      store = Hoodoo::TransientStore::Mocks::DalliClient.store()
+      expect( store[ '0987' ] ).to include( { :value => { 'version' => 23 } } )
+      expect( store[ 'efgh' ] ).to include( { :value => { 'version' => 3  } } )
+    end
 
-    expect( loader.load_from_memcached!( '1234' ) ).to eq( :fail )
-  end
+    it 'with modern interface and no caller-supplied client' do
+      expect( @session.update_caller_version_in_store( '0987', 23 ) ).to eq( :ok )
+      expect( @session.update_caller_version_in_store( 'efgh', 3  ) ).to eq( :ok )
+    end
 
-  it 'logs Memcached exceptions when updating caller version during session saving' do
-    s = described_class.new(
-      :caller_id => '0987',
-      :caller_version => 1
-    )
+    it 'with modern interface and caller-supplied Hoodoo::TransientStore instance' do
+      local_store = Hoodoo::TransientStore.new(
+        storage_engine:   :memcached,
+        storage_host_uri: 'abcd'
+      )
 
-    # The first 'set' call is an attempt to update the caller version before
-    # the updated session is saved.
+      expect( @session.update_caller_version_in_store( '0987', 23, local_store ) ).to eq( :ok )
+      expect( @session.update_caller_version_in_store( 'efgh', 3,  local_store ) ).to eq( :ok )
+    end
 
-    expect_any_instance_of( Hoodoo::TransientStore::Mocks::DalliClient ).to receive( :set ).once do
-      raise 'Mock Memcached connection failure'
+    it 'with deprecated interface and no caller-supplied client' do
+      expect( @session.update_caller_version_in_memcached( '0987', 23 ) ).to eq( :ok )
+      expect( @session.update_caller_version_in_memcached( 'efgh', 3  ) ).to eq( :ok )
     end
 
-    expect( Hoodoo::Services::Middleware.logger ).to(
-      receive( :warn ).once.with(
-        'Hoodoo::Services::Session\\#update_caller_version_in_memcached: Client version update - connection fault or corrupt record',
-        'Mock Memcached connection failure'
-      ).and_call_original
-    )
+    it 'with deprecated interface and caller-supplied Dalli::Client instance' do
+      local_store = Hoodoo::TransientStore::Mocks::DalliClient.new
 
-    expect( s.save_to_memcached() ).to eq( :fail )
+      expect( @session.update_caller_version_in_memcached( '0987', 23, local_store ) ).to eq( :ok )
+      expect( @session.update_caller_version_in_memcached( 'efgh', 3,  local_store ) ).to eq( :ok )
+    end
   end
 
-  it 'logs Memcached exceptions when saving session' do
-    s = described_class.new(
-      :caller_id => '0987',
-      :caller_version => 1
-    )
+  # ==========================================================================
 
-    expect_any_instance_of( Hoodoo::TransientStore::Mocks::DalliClient ).to receive( :set ).once.and_call_original
-    expect_any_instance_of( Hoodoo::TransientStore::Mocks::DalliClient ).to receive( :set ).once do
-      raise 'Mock Memcached connection failure'
+  context 'error handling code' do
+    it 'handles invalid session IDs when loading' do
+      loader = described_class.new
+      expect( loader.load_from_store!( '1234' ) ).to eq( :not_found )
     end
 
-    expect( Hoodoo::Services::Middleware.logger ).to(
-      receive( :warn ).once.with(
-        'Hoodoo::Services::Session\\#save_to_memcached: Session saving failed - connection fault or session corrupt',
-        'Mock Memcached connection failure'
-      ).and_call_original
-    )
+    it 'complains if there is no caller ID' do
+      s = described_class.new
+      expect {
+        s.save_to_store()
+      }.to raise_error RuntimeError
+    end
 
-    expect( s.save_to_memcached() ).to eq( :fail )
-  end
+    it 'logs Memcached exceptions when loading' do
+      loader = described_class.new
 
-  it 'can be deleted' do
-    s = described_class.new(
-      :session_id => '1234',
-      :memcached_host => 'abcd',
-      :caller_id => '0987',
-      :caller_version => 1
-    )
+      expect_any_instance_of( Hoodoo::TransientStore::Mocks::DalliClient ).to receive( :get ).once do
+        raise 'Mock Memcached connection failure'
+      end
 
-    s.save_to_memcached
+      expect( Hoodoo::Services::Middleware.logger ).to(
+        receive( :warn ).once.with(
+          'Hoodoo::Services::Session\\#load_from_store!: Session loading failed - connection fault or session corrupt',
+          'Mock Memcached connection failure'
+        ).and_call_original
+      )
 
-    expect{ s.delete_from_memcached }.to change{ s.load_from_memcached!( s.session_id ) }.from( :ok ).to( :not_found )
-  end
+      expect( loader.load_from_store!( '1234' ) ).to eq( :fail )
+    end
 
-  it 'handles attempts to delete not-found things' do
-    s = described_class.new(
-      :session_id => '1234',
-      :memcached_host => 'abcd',
-      :caller_id => '0987',
-      :caller_version => 1
-    )
+    it 'logs Memcached exceptions when updating caller version during session saving' do
+      s = described_class.new(
+        :caller_id => '0987',
+        :caller_version => 1
+      )
 
-    expect( s.delete_from_memcached ).to eq( :not_found )
-  end
+      # The first 'set' call is an attempt to update the caller version before
+      # the updated session is saved.
 
-  it 'logs and reports deletion exceptions' do
-    fdc = Hoodoo::TransientStore::Mocks::DalliClient.new
-    s = described_class.new(
-      :session_id => '1234',
-      :memcached_host => 'abcd',
-      :caller_id => '0987',
-      :caller_version => 1
-    )
+      expect_any_instance_of( Hoodoo::TransientStore::Mocks::DalliClient ).to receive( :set ).once do
+        raise 'Mock Memcached connection failure'
+      end
 
-    s.save_to_memcached
+      expect( Hoodoo::Services::Middleware.logger ).to(
+        receive( :warn ).once.with(
+          'Hoodoo::Services::Session\\#update_caller_version_in_store: Client version update - connection fault or corrupt record',
+          'Mock Memcached connection failure'
+        ).and_call_original
+      )
 
-    allow( described_class ).to receive( :connect_to_memcached ) {
-      raise 'Intentional exception'
-    }
+      expect( s.save_to_store() ).to eq( :fail )
+    end
 
-    expect( Hoodoo::Services::Middleware.logger ).to receive( :warn )
-    expect( s.delete_from_memcached ).to eq( :fail )
-  end
+    it 'logs Memcached exceptions when saving session' do
+      s = described_class.new(
+        :caller_id => '0987',
+        :caller_version => 1
+      )
 
-  # We really can't do this without insisting on testers having a
-  # Memcached instance; instead, assume Dalli works (!) and mock it.
-  #
-  context 'real Memcached connection code test coverage' do
-    before :example do
-      # Clear the connection cache for each test
-      Hoodoo::Services::Session.class_variable_set( '@@dalli_clients', nil ) # Hack for test!
-      Hoodoo::TransientStore::Mocks::DalliClient.bypass( true )
-    end
+      expect_any_instance_of( Hoodoo::TransientStore::Mocks::DalliClient ).to receive( :set ).once.and_call_original
+      expect_any_instance_of( Hoodoo::TransientStore::Mocks::DalliClient ).to receive( :set ).once do
+        raise 'Mock Memcached connection failure'
+      end
 
-    after :example do
-      Hoodoo::TransientStore::Mocks::DalliClient.bypass( false )
-    end
+      expect( Hoodoo::Services::Middleware.logger ).to(
+        receive( :warn ).once.with(
+          'Hoodoo::Services::Session\\#save_to_store: Session saving failed - connection fault or session corrupt',
+          'Mock Memcached connection failure'
+        ).and_call_original
+      )
 
-    it 'complains about a missing host' do
-      expect {
-        described_class.connect_to_memcached( nil )
-      }.to raise_error RuntimeError
+      expect( s.save_to_store() ).to eq( :fail )
+    end
 
-      expect {
-        described_class.connect_to_memcached( '' )
-      }.to raise_error RuntimeError
+    it 'handles unknown Hoodoo::TransientStore engine failures' do
+      s = described_class.new(
+        :session_id => '1234',
+        :memcached_host => 'abcd',
+        :caller_id => '0987',
+        :caller_version => 1
+      )
+
+      s.save_to_store
+      allow_any_instance_of( Hoodoo::TransientStore ).to(
+        receive( :delete ).
+        and_return( false )
+      )
+
+      expect( Hoodoo::Services::Middleware.logger ).to receive( :warn )
+      expect( s.delete_from_store ).to eq( :fail )
     end
 
-    it 'tries to connect' do
-      expect_any_instance_of( Dalli::Client ).to receive( :stats ).and_return( {} )
-      expect( described_class.connect_to_memcached( '256.2.3.4:0' ) ).to be_a( Dalli::Client )
+    it 'handles unknown Hoodoo::TransientStore engine returned exceptions' do
+      s = described_class.new(
+        :session_id => '1234',
+        :memcached_host => 'abcd',
+        :caller_id => '0987',
+        :caller_version => 1
+      )
+
+      s.save_to_store
+      allow_any_instance_of( Hoodoo::TransientStore ).to(
+        receive( :delete ).
+        and_return( RuntimeError.new( 'Intentional exception' ) )
+      )
+
+      expect( Hoodoo::Services::Middleware.logger ).to receive( :warn )
+      expect( s.delete_from_store ).to eq( :fail )
     end
 
-    it 'handles connection failures' do
-      expect_any_instance_of( Dalli::Client ).to receive( :stats ).and_return( nil )
-      expect {
-        described_class.connect_to_memcached( '256.2.3.4:0' )
-      }.to raise_error RuntimeError
+    it 'logs and reports internal deletion exceptions' do
+      s = described_class.new(
+        :session_id => '1234',
+        :memcached_host => 'abcd',
+        :caller_id => '0987',
+        :caller_version => 1
+      )
+
+      s.save_to_store
+
+      allow_any_instance_of( described_class ).to(
+        receive( :get_store ).
+        and_raise( 'Intentional exception' )
+      )
+
+      expect( Hoodoo::Services::Middleware.logger ).to receive( :warn )
+      expect( s.delete_from_store ).to eq( :fail )
     end
+  end
 
-    it 'handles connection exceptions' do
-      expect_any_instance_of( Dalli::Client ).to receive( :initialize ) do
-        raise 'Mock Memcached connection failure'
+  # ==========================================================================
+
+  context 'legacy' do
+    context 'Memcached-bound code' do
+      before :example do
+
+        # Clear the connection cache for each test
+        #
+        Hoodoo::Services::Session.class_variable_set( '@@stores', nil ) # Hack for test!
+
+        @instance = described_class.new(
+          :session_id => '1234',
+          :memcached_host => 'abcd',
+          :caller_id => '0987',
+          :caller_version => 1
+        )
       end
 
-      expect {
-        described_class.connect_to_memcached( '256.2.3.4:0' )
-      }.to raise_error RuntimeError
-    end
+      it 'tries to connect' do
+        expect_any_instance_of( Hoodoo::TransientStore::Mocks::DalliClient ).to receive( :stats ).and_return( {} )
+        expect( @instance.send( :get_store ) ).to be_a( Hoodoo::TransientStore )
+      end
+
+      it 'handles connection failures' do
+        expect_any_instance_of( Hoodoo::TransientStore::Mocks::DalliClient ).to receive( :stats ).and_return( nil )
+        expect {
+          @instance.send( :get_store )
+        }.to raise_error RuntimeError
+      end
+
+      it 'handles connection exceptions' do
+        expect_any_instance_of( Hoodoo::TransientStore ).to receive( :initialize ) do
+          raise 'Mock TransientStore constructor failure'
+        end
+
+        expect {
+          @instance.send( :get_store )
+        }.to raise_error RuntimeError
+      end
+
+      it 'only initialises once for one given host' do
+        expect( Hoodoo::TransientStore::Memcached ).to receive( :new ).once.and_call_original()
+
+        @instance.memcached_host = 'one'
+        1.upto( 3 ) do
+          @instance.send( :get_store )
+        end
 
-    it 'only initialises once for one given host' do
-      expect( Dalli::Client ).to receive( :new ).once.and_return( Hoodoo::TransientStore::Mocks::DalliClient.new )
+        expect( Hoodoo::TransientStore::Memcached ).to receive( :new ).once.and_call_original()
 
-      1.upto( 3 ) do
-        described_class.connect_to_memcached( 'one' )
+        @instance.memcached_host = 'two'
+        1.upto( 3 ) do
+          @instance.send( :get_store )
+        end
       end
+    end
 
-      expect( Dalli::Client ).to receive( :new ).once.and_return( Hoodoo::TransientStore::Mocks::DalliClient.new )
+    context 'compatibility' do
+      it 'via alias to the TransientStore mock back-end' do
+        expect( Hoodoo::Services::Session::MockDalliClient == Hoodoo::TransientStore::Mocks::DalliClient ).to eql( true )
+        expect {
+          Hoodoo::TransientStore::Mocks::DalliClient.reset()
+        }.to_not raise_error
+      end
 
-      1.upto( 3 ) do
-        described_class.connect_to_memcached( 'two' )
+      it 'via aliases for deprecated methods' do
+        s = described_class.new(
+          :session_id => '1234',
+          :memcached_host => 'abcd',
+          :caller_id => '0987',
+          :caller_version => 2
+        )
+
+        expect( s ).to respond_to( :save_to_memcached )
+        expect( s ).to respond_to( :load_from_memcached! )
+        expect( s ).to respond_to( :update_caller_version_in_memcached )
+        expect( s ).to respond_to( :delete_from_memcached )
       end
     end
   end