stockpile 1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d12f955c01ed9d46dd13ec2fc357cbb086094146
+  data.tar.gz: 5612ead9571a141b3b68695727655c1e03d680e0
+SHA512:
+  metadata.gz: a3734ac43b06cfe7fe5d3fdbdc60cbd9f7560dfdce10fdee63d1d8128291de176baa307b368ef39fc02fe9aa307fde5a552262f50455fb02ab4058ebd8c2a2a9
+  data.tar.gz: 99989e77edc96cc5f193b1c327cf42c4c573b43250f236ffe018cbf4f23240cbc5c327065ae063eec4e99e9b090b8a3c188cea37c07dac8138a25f71a34aa221

data/.autotest

@@ -0,0 +1,27 @@
+# -*- ruby -*-
+
+require "autotest/restart"
+
+Autotest.add_hook :initialize do |at|
+  # .minitest.rb ensures that the gem version of minitest is used.
+  at.testlib = ".minitest.rb"
+  # at.testlib = "minitest/unit"
+  #
+  # at.extra_files << "../some/external/dependency.rb"
+  #
+  # at.libs << ":../some/external"
+  #
+  # at.add_exception "vendor"
+  #
+  # at.add_mapping(/dependency.rb/) do |f, _|
+  #   at.files_matching(/test_.*rb$/)
+  # end
+  #
+  # %w(TestA TestB).each do |klass|
+  #   at.extra_class_map[klass] = "test/test_misc.rb"
+  # end
+end
+
+# Autotest.add_hook :run_command do |at|
+#   system "rake build"
+# end

data/.gemtest

@@ -0,0 +1 @@
+

data/.minitest.rb

@@ -0,0 +1,2 @@
+gem "minitest"
+require "minitest/autorun"

data/.travis.yml

@@ -0,0 +1,34 @@
+---
+language: ruby
+rvm:
+  - 2.1.0
+  - 2.0.0
+  - 1.9.3
+  - ruby-head
+  - jruby-19mode
+  - jruby-head
+  - rbx-2
+matrix:
+  allow_failures:
+    - rvm: rbx-2
+    - rvm: jruby-head
+    - rvm: ruby-head
+gemfile:
+  - Gemfile
+before_script:
+  - |
+    case "${TRAVIS_RUBY_VERSION}" in
+      rbx*)
+        gem install psych
+        ;;
+    esac
+  - rake travis:before -t
+script: rake travis
+after_script:
+  - rake travis:after -t
+notifications:
+  email:
+    recipients:
+      - FIX@example.com
+    on_success: change
+    on_failure: always

data/Contributing.rdoc

@@ -0,0 +1,65 @@
+== Contributing
+
+I value any contribution to stockpile you can provide: a bug report, a
+feature request, or code contributions.
+
+As stockpile is a complex codebase, there are a few guidelines:
+
+* Changes *will* *not* be accepted without tests. The test suite is written
+  with {Minitest}[https://github.com/seattlerb/minitest].
+* Match my coding style.
+* Use a thoughtfully-named topic branch that contains your change. Rebase your
+  commits into logical chunks as necessary.
+* Use {quality commit messages}[http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html].
+* Do not change the version number; when your patch is accepted and a release
+  is made, the version will be updated at that point.
+* Submit a GitHub pull request with your changes.
+* New behaviours require new or updated documentation.
+
+=== Test Dependencies
+
+stockpile uses Ryan Davis’s {Hoe}[https://github.com/seattlerb/hoe]
+to manage the release process, and it adds a number of rake tasks. You will
+mostly be interested in:
+
+    $ rake
+
+which runs the tests the same way that:
+
+    $ rake test
+    $ rake travis
+
+will do.
+
+To assist with the installation of the development dependencies for
+stockpile, I have provided the simplest possible Gemfile pointing to
+the (generated) +stockpile.gemspec+ file. This will permit you to do:
+
+    $ bundle install
+
+to get the development dependencies. If you aleady have +hoe+ installed, you
+can accomplish the same thing with:
+
+    $ rake newb
+
+This task will install any missing dependencies, run the tests/specs, and
+generate the RDoc.
+
+=== Workflow
+
+Here's the most direct way to get your work merged into the project:
+
+* Fork the project.
+* Clone down your fork (<tt>git clone git://github.com/halostatue/stockpile.git</tt>).
+* Create a topic branch to contain your change (<tt>git checkout -b my\_awesome\_feature</tt>).
+* Hack away, add tests. Not necessarily in that order.
+* Make sure everything still passes by running +rake+.
+* If necessary, rebase your commits into logical chunks, without errors.
+* Push the branch up (<tt>git push origin my\_awesome\_feature</tt>).
+* Create a pull request against halostatue/stockpile and describe
+  what your change does and the why you think it should be merged.
+
+=== Contributors
+
+* Austin Ziegler created stockpile.
+* Sean Miller helped wordsmith the documentation. Any errors are mine, not his.

data/Gemfile

@@ -0,0 +1,9 @@
+# -*- ruby -*-
+
+# NOTE: This file is present to keep Travis CI happy. Edits to it will not
+# be accepted.
+
+source "https://rubygems.org/"
+gemspec
+
+# vim: syntax=ruby

data/History.rdoc

@@ -0,0 +1,5 @@
+=== 1.0 / 2015-01-21
+
+* 1 major enhancement
+
+  * Birthday!

data/Licence.rdoc

@@ -0,0 +1,27 @@
+== Licence
+
+This software is available under an MIT-style licence.
+
+* Copyright 2015 Austin Ziegler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+* The names of its contributors may not be used to endorse or promote
+  products derived from this software without specific prior written
+  permission.
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,14 @@
+.autotest
+.gemtest
+.minitest.rb
+.travis.yml
+Contributing.rdoc
+Gemfile
+History.rdoc
+Licence.rdoc
+Manifest.txt
+README.rdoc
+Rakefile
+lib/stockpile.rb
+test/minitest_config.rb
+test/test_stockpile.rb

data/README.rdoc

@@ -0,0 +1,157 @@
+= stockpile
+
+code :: https://github.com/halostatue/stockpile/
+bugs :: https://github.com/halostatue/stockpile/issues
+continuous integration :: {<img src="https://travis-ci.org/halostatue/stockpile.png" />}[https://travis-ci.org/halostatue/stockpile]
+
+== Description
+
+Stockpile is a simple key-value store connection manager framework. Stockpile
+itself does not implement a connection manager, but places expectations for
+implemented connection managers. So far, only Redis has been implemented
+(stockpile-redis).
+
+Stockpile also provides an adapter so that its functionality can be accessed
+from within a module.
+
+== Features
+
+* Stockpile manages key-value store connections. There are two variants:
+
+  * *wide* (<tt>Stockpile.new</tt>, the default), where additional client
+    connections are new instances of the client library;
+  * *narrow* (<tt>Stockpile.new(narrow: true)</tt>), where additional client
+    connections use the same client library instance.
+
+* Stockpile can also be injected into a module
+  (<tt>Stockpile.inject!(self, options = {})</tt>), which gives the module
+  cache management and adapter methods (<tt>.cache</tt> and
+  <tt>.cache_adapter</tt>, by default).
+
+== Requirements
+
+The desired key-value store must already be installed and/or specified in
+your Gemfile.
+
+== Synopsis
+
+  wide = Stockpile.new # A Stockpile to Redis.
+  wide.connection.set('hello', 'world') # => 'OK'
+  wide.connection.get('hello') # => 'world'
+
+  # Connections are independent from one another.
+  wide.connection_for(:other) != wide.connection # => true
+
+  # Or set ENV['STOCKPILE_CONNECTION_WDITH'] = 'narrow'
+  narrow = Stockpile.new(narrow: true) # A 'narrow' Stockpile to Redis.
+  narrow.connection_for(:other) == narrow.connection # => true
+
+  # Special Redis::Namespace handling for Resque. Assumes that redis-namespace
+  # has been installed, as well.
+  narrow.connection_for(:resque) != narrow.connection # => true
+  narrow.connection_for(:resque).redis == narrow.connection # => true
+
+  # Show a Stockpile with no adapter capabilities, but name the method
+  # stockpile, not cache. This will still usefully manage connections.
+  module Cacher
+    Stockpile.inject!(self, method: :stockpile, adaptable: false)
+  end
+  Cacher.respond_to?(:stockpile) # => true
+  Cacher.respond_to?(:stockpile_adapter) # => false
+  Cacher.stockpile.connection.set('hello', 'world') # => 'OK'
+  Cacher.stockpile.connection.get('hello') # => 'world'
+
+  # Now a Stockpile with adapter capabilities.
+  module Jobber
+    module LastRunTime
+      def last_run_time(key, value = nil)
+        if value
+          connection.hset(__method__, key, value.utc.iso8601)
+        else
+          value = connection.hget(__method__, key)
+          Time.parse(value) if value
+        end
+      end
+    end
+
+    Stockpile.inject!(self)
+  end
+  Jobber.respond_to?(:cache) # => true
+  Jobber.respond_to?(:cache_adapter) # => true
+
+  # Four ways:
+  # 1. Adapt Jobber.cache to recognize #last_run_time.
+  Jobber.cache_adapter(Jobber::LastRunTime)
+  Jobber.cache.last_run_time('hello', t = Time.now) # => true
+  Jobber.cache.last_run_time('hello') # => approximately t
+
+  # 2. Adapt Jobber.cache and another module to recognize #last_run_time.
+  module Foo; end
+  Jobber.cache_adapter(Jobber::LastRunTime, Foo)
+  Foo.last_run_time('hello', t = Time.now) # => true
+  Foo.last_run_time('hello') # => approximately t
+
+  # 3. Adapt Jobber.cache and Jobber to recognize #last_run_time.
+  Jobber.cache_adapter(Jobber::LastRunTime, Jobber)
+  Jobber.last_run_time('hello', t = Time.now) # => true
+  Jobber.last_run_time('hello') # => approximately t
+
+  # 4. Adapt Jobber.cache and Jobber::LastRunTime to recognize #last_run_time.
+  Jobber.cache_adapter!(Jobber::LastRunTime)
+  # or Jobber.cache_adapter(Jobber::LastRunTime, Jobber::LastRunTime)
+  Jobber::LastRunTime.last_run_time('hello', t = Time.now) # => true
+  Jobber::LastRunTime.last_run_time('hello') # => approximately t
+
+== Background
+
+Stockpile is the evolution of concepts I have applied to Rails applications
+over the last few years when working with Redis, and avoids the following
+common but suboptimal patterns:
+
+* Developers use +REDIS+ or <tt>$redis</tt> to initialize and access their
+  Redis instances. This could be fixed by using +Redis.current+, but that still
+  exposes implementation details unnecessarily.
+* Redis methods are often exposed directly in controllers or models, as
+
+    render json: $redis.hget('last_run_time', params[:method])
+
+  We don’t like seeing direct database access methods in our controllers, so
+  why do we put up with this for Redis?
+* Each Redis client manages its own connections, and at least one client
+  reconnection is forgotten when using a forking server like Unicorn.
+* Some providers of Redis services restrict the number of simultaneous
+  connections to a given Redis instance. With Rails caching, an application
+  cache, and Resque there are at least three simultaneous connections to Redis
+  for a given Rails server instancne, unless the same connection is reused.
+
+=== Sample Rails Application
+
+I will be adapting a sample Rails application to demonstrate how Stockpile can
+be used in Rails. A link to it will be provided here when it is complete.
+
+== Install
+
+Stockpile is not intended to be installed by itself, as it does not implement a
+key-value store specific connection manager. Instead, install an
+store-specific gem which depends on Stockpile.
+
+  gem 'stockpile-redis', '~> 1.0'
+
+Or manually install:
+
+  % gem install stockpile-redis
+
+and require Stockpile in your code:
+
+  require 'stockpile/redis'
+
+== Stockpile Semantic Versioning
+
+Stockpile uses a {Semantic Versioning}[http://semver.org/] scheme with one
+change:
+
+* When PATCH is zero (+0+), it will be omitted from version references.
+
+:include: Contributing.rdoc
+
+:include: Licence.rdoc

data/Rakefile

@@ -0,0 +1,51 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+
+Hoe.plugin :doofus
+Hoe.plugin :gemspec2
+Hoe.plugin :git
+Hoe.plugin :minitest
+Hoe.plugin :travis
+Hoe.plugin :email unless ENV['CI'] or ENV['TRAVIS']
+
+spec = Hoe.spec 'stockpile' do
+  developer('Austin Ziegler', 'halostatue@gmail.com')
+
+  self.history_file = 'History.rdoc'
+  self.readme_file = 'README.rdoc'
+  self.extra_rdoc_files = FileList["*.rdoc"].to_a
+
+  license "MIT"
+
+  self.need_tar = true
+  self.require_ruby_version '>= 1.9.2'
+
+  self.extra_dev_deps << ['hoe-doofus', '~> 1.0']
+  self.extra_dev_deps << ['hoe-gemspec2', '~> 1.1']
+  self.extra_dev_deps << ['hoe-git', '~> 1.5']
+  self.extra_dev_deps << ['hoe-travis', '~> 1.2']
+  self.extra_dev_deps << ['minitest', '~> 5.4']
+  self.extra_dev_deps << ['minitest-around', '~> 0.3']
+  self.extra_dev_deps << ['minitest-autotest', '~> 1.0']
+  self.extra_dev_deps << ['minitest-bisect', '~> 1.2']
+  self.extra_dev_deps << ['minitest-focus', '~> 1.1']
+  self.extra_dev_deps << ['minitest-moar', '~> 0.0']
+  self.extra_dev_deps << ['minitest-pretty_diff', '~> 0.1']
+  self.extra_dev_deps << ['rake', '>= 10.0']
+  self.extra_dev_deps << ['simplecov', '~> 0.7']
+end
+
+namespace :test do
+  task :coverage do
+    spec.test_prelude = [
+      'require "simplecov"',
+      'SimpleCov.start("test_frameworks") { command_name "Minitest" }',
+      'gem "minitest"'
+    ].join('; ')
+    Rake::Task['test'].execute
+  end
+end
+
+# vim: syntax=ruby

data/lib/stockpile.rb

@@ -0,0 +1,220 @@
+# coding: utf-8
+
+require 'forwardable'
+
+# Stockpile is a thin wrapper around connections to a fast key-value store used
+# for caching (currently only supporting Redis).
+#
+# This provides a couple of layers of functionality:
+#
+# * Connection management. Some third-party providers of Redis limit
+#   simultaneous connections; Stockpile can manage a single connection that
+#   gets shared by all clients using a Stockpile instance.
+# * Providing an application-level cache adapter mechanism.
+class Stockpile
+  extend Forwardable
+
+  VERSION = "1.0" # :nodoc:
+
+  @default_manager = nil
+
+  class << self
+    # Determines if the default connection width is narrow or wide based on
+    # the environment variable STOCKPILE_CONNECTION_WIDTH.
+    def narrow?
+      (ENV['STOCKPILE_CONNECTION_WIDTH'] == 'narrow')
+    end
+
+    # Enables module or class +mod+ to contain a Stockpile instance and
+    # provide an adapter interface (this can be disabled). This creates a
+    # singleton method that returns a singleton Stockpile instance.
+    #
+    # === Options
+    # +method+:: The name of the method that manages the Stockpile instance.
+    #            Defaults to +cache+.
+    # +adaptable+:: Defines an adapter method if truthy (the default). Pass a
+    #               falsy value to disable. (The created adapter method will be
+    #               named according to the value of +method+, and so defaults
+    #               to +cache_adapter+.
+    #
+    # === Synopsis
+    #
+    #   # Using only for connection management.
+    #   module Application
+    #     Stockpile.inject!(self, adaptable: false)
+    #   end
+    #   Application.cache # => a stockpile instance
+    #   Application.cache.connection.set('answer', 42)
+    #   Application.cache.connection.get('answer')
+    #
+    #   module LastRunTime
+    #     def last_run_time(key, value = nil)
+    #       if value
+    #         connection.hset(__method__, key, value.utc.iso8601)
+    #       else
+    #         value = connection.hget(__method__, key)
+    #         Time.parse(value) if value
+    #       end
+    #     end
+    #   end
+    #
+    #   module AdaptableApplication; end
+    #   Stockpile.inject!(AdaptableApplication)
+    #
+    #   # Adapt the cache object to recognize #last_run_time;
+    #   AdaptableApplication.cache_adapter(LastRunTime)
+    #   AdaptableApplication.cache.last_run_time('adaptable_application')
+    #
+    #   # or adapt AdaptableApplication to recognize #last_run_time;
+    #   AdaptableApplication.cache_adapter(LastRunTime,
+    #                                      AdaptableApplication)
+    #   AdaptableApplication.last_run_time('adaptable_application')
+    #
+    #   # or adapt LastRunTime to recognize #last_run_time.
+    #   AdaptableApplication.cache_adapter!(LastRunTime)
+    #   LastRunTime.last_run_time('adaptable_application')
+    def inject!(mod, options = {})
+      unless mod.kind_of?(Module)
+        raise ArgumentError, "#{mod} is not a class or module"
+      end
+
+      name    = options.fetch(:method, :cache).to_sym
+      msc     = mod.singleton_class
+
+      default = options.fetch(:default_manager, nil)
+
+      msc.send(:define_method, name) do |init_options = {}|
+        init_options = init_options.merge(default_manager: default)
+        @__stockpile__ ||= ::Stockpile.new(init_options)
+      end
+
+      if options.fetch(:adaptable, true)
+        adapter = :"#{name}_adapter"
+        msc.send(:define_method, adapter) do |m, k = nil|
+          o = self
+          send(name).singleton_class.send(:include, m)
+
+          if k
+            mk = k.singleton_class
+            m.public_instance_methods.each do |pim|
+              mk.send(:define_method, pim) do |*args, &block|
+                o.send(name).send(pim, *args, &block)
+              end
+            end
+          end
+        end
+
+        msc.send(:define_method, :"#{adapter}!") do |m|
+          send(adapter, m, m)
+        end
+      end
+    end
+
+    # The default Stockpile cache connection manager.
+    attr_accessor :default_manager
+  end
+
+  # Creates a new Stockpile instance and connects to the connection provider
+  # using the provided options and block.
+  #
+  # === Options
+  #
+  # The options hash contains configuration for the Stockpile and its
+  # connection manager. The following options are handled specially by the
+  # Stockpile constructor and not made available to the connection provider
+  # constructor.
+  #
+  # +manager+:: The connection manager that will be used for creating
+  #             connections to this Stockpile. If not provided, either
+  #             +default_manager+ or ::Stockpile.default_manager will be used.
+  #             An error will be raised if no connection provider is available
+  #             through any means.
+  # +clients+:: Connections will be created for the provided list of clients.
+  #             These connections must be assigned to their appropriate clients
+  #             after initialization. This may also be called +client+.
+  #
+  # All other options will be passed to the connection provider.
+  #
+  # === Synopsis
+  #
+  #  # Create and assign a connection to Redis.current, Resque, and Rollout.
+  #  # Under a narrow connection management width, all three will be the
+  #  # same client connection.
+  #  Stockpile.new(manager: Stockpile::Redis, clients: [ :redis, :resque ]) do |stockpile|
+  #    Redis.current = stockpile.connection_for(:redis)
+  #    Resque.redis = stockpile.connection_for(:resque)
+  #    # Clients will be created by name if necessary.
+  #    $rollout = Rollout.new(stockpile.connection_for(:rollout))
+  #  end
+  def initialize(options = {})
+    manager = options.fetch(:manager) {
+      options[:default_manager] || self.class.default_manager
+    }
+
+    unless manager
+      raise ArgumentError, "No connection manager provided or set as default."
+    end
+
+    clients = (Array(options[:clients]) + Array(options[:client])).flatten.uniq
+
+    options = { narrow: Stockpile.narrow? }.merge(options.reject { |k, _|
+      k == :manager || k == :clients || k == :client
+    })
+
+    @manager = manager.new(options)
+    connect(*clients)
+    yield self if block_given?
+  end
+
+  ##
+  # :attr_reader: connection
+  #
+  # The currently active connection to the cache provider.
+  def_delegator :@manager, :connection
+
+  ##
+  # :method: connect
+  # :call-seq:
+  #   connect
+  #   connect(*clients)
+  #
+  # This will connect the Stockpile instance to the cache provider, optionally
+  # including for a set of named clients.
+  #
+  # If the connection is using a narrow connection width, the same connection
+  # will be shared.
+  def_delegator :@manager, :connect
+
+  ##
+  # :method: connection_for
+  # :call-seq:
+  #   connection_for(client_name)
+  #
+  # Returns a connection for a particular client. If the connection manager is
+  # using a narrow connection width, this returns the same as #connection.
+  #
+  # The +client_name+ of +:all+ will always return +nil+.
+  #
+  # If the requested client does not yet exist, the connection will be created.
+  def_delegator :@manager, :connection_for
+
+  ##
+  # :method: reconnect
+  # :call-seq:
+  #   reconnect
+  #   reconnect(:all)
+  #   reconnect(*clients)
+  #
+  # This will reconnect one or more clients.
+  def_delegator :@manager, :reconnect
+
+  ##
+  # :method: disconnect
+  # :call-seq:
+  #   disconnect
+  #   disconnect(:all)
+  #   disconnect(*clients)
+  #
+  # This will disconnect one or more clients.
+  def_delegator :@manager, :disconnect
+end

data/test/minitest_config.rb

@@ -0,0 +1,163 @@
+# -*- ruby encoding: utf-8 -*-
+
+gem 'minitest'
+require 'minitest/autorun'
+require 'minitest/pretty_diff'
+require 'minitest/focus'
+require 'minitest/moar'
+require 'minitest/bisect'
+
+require 'stockpile'
+
+class StockpileTestManager
+  class Connection
+    class << self
+      attr_reader :data
+
+      def reset_data
+        @data = Hash.new { |h, k| h[k] = {} }
+      end
+    end
+
+    reset_data
+
+    def initialize
+      @connected = false
+      connect
+    end
+
+    def connect
+      @connected = true
+    end
+    alias_method :reconnect, :connect
+
+    def disconnect
+      @connected = false
+    end
+
+    def connected?
+      !!@connected
+    end
+
+    def get(key)
+      raise unless connected?
+      self.class.data[key]
+    end
+
+    def set(key, value)
+      raise unless connected?
+      self.class.data[key] = value
+    end
+
+    def hget(key, field)
+      raise unless connected?
+      self.class.data[key][field]
+    end
+
+    def hset(key, field, value)
+      raise unless connected?
+      self.class.data[key][field] = value
+    end
+  end
+
+  def initialize(options = {})
+    @narrow     = !!options.fetch(:narrow, ::Stockpile.narrow?)
+    @connection = nil
+    @clients    = {}
+  end
+
+  attr_reader :connection
+
+  def narrow?
+    @narrow
+  end
+
+  def connect(*client_names)
+    @connection ||= connect_for_any
+
+    clients_from(*client_names).each { |client_name|
+      connection_for(client_name)
+    }
+
+    connection
+  end
+
+  def connection_for(client_name)
+    connect unless connection
+    return nil if client_name == :all
+    @clients[client_name] ||= connect_for_any
+  end
+
+  def reconnect(*client_names)
+    return unless connection
+
+    connection.reconnect
+
+    unless narrow?
+      clients_from(*client_names).each { |client_name|
+        client = @clients[client_name]
+        client.reconnect if client
+      }
+    end
+
+    connection
+  end
+
+  def disconnect(*client_names)
+    return unless connection
+
+    unless narrow?
+      clients_from(*client_names).each { |client_name|
+        client = @clients[client_name]
+        client.disconnect if client
+      }
+    end
+
+    connection.disconnect
+  end
+
+  private
+  def clients_from(*client_names)
+    if client_names.size == 1
+      if client_names.first == :all
+        @clients.keys
+      else
+        client_names
+      end
+    else
+      client_names
+    end
+  end
+
+  def connect_for_any
+    return connection if connection && narrow?
+    Connection.new
+  end
+end
+
+module Minitest::ENVStub
+  def setup
+    super
+    StockpileTestManager::Connection.reset_data
+  end
+
+  def stub_env env, options = {}, *block_args, &block
+    mock = lambda { |key|
+      env.fetch(key) { |k|
+        if options[:passthrough]
+          ENV.send(:"__minitest_stub__[]", k)
+        else
+          nil
+        end
+      }
+    }
+
+    if defined? Minitest::Moar::Stubbing
+      stub ENV, :[], mock, *block_args, &block
+    else
+      ENV.stub :[], mock, *block_args, &block
+    end
+  end
+
+  Minitest::Test.send(:include, self)
+end

data/test/test_stockpile.rb

@@ -0,0 +1,133 @@
+require 'minitest_config'
+require 'stockpile'
+require 'time'
+
+describe Stockpile do
+  describe ".narrow?" do
+    it "is wide by default" do
+      stub_env({}) do
+        refute Stockpile.narrow?
+      end
+    end
+
+    it "is narrow when $STOCKPILE_CONNECTION_WIDTH = 'narrow'" do
+      stub_env({ 'STOCKPILE_CONNECTION_WIDTH' => 'narrow' }) do
+        assert Stockpile.narrow?
+      end
+    end
+  end
+
+  describe ".inject!" do
+    let(:mod) { Module.new }
+    let(:lrt) {
+      Module.new do
+        def last_run_time(key, value = nil)
+          if value
+            connection.hset(__method__, key, value.utc.iso8601)
+          else
+            value = connection.hget(__method__, key)
+            Time.parse(value) if value
+          end
+        end
+      end
+    }
+
+    describe "Stockpile.inject!(Mod):" do
+      before { ::Stockpile.inject!(mod) }
+
+      it "defines Mod.cache" do
+        assert_respond_to mod, :cache
+      end
+
+      it "defines Mod.cache_adapter" do
+        assert_respond_to mod, :cache_adapter
+      end
+
+      it "defines Mod.cache_adapter!" do
+        assert_respond_to mod, :cache_adapter!
+      end
+
+      it "Fails cache initialization" do
+        assert_raises ArgumentError do
+          mod.cache
+        end
+      end
+    end
+
+    describe "Stockpile.inject!(Mod, adaptable: false)" do
+      before { ::Stockpile.inject!(mod, adaptable: false) }
+
+      it "defines Mod.cache" do
+        assert_respond_to mod, :cache
+      end
+
+      it "does not define Mod.cache_adapter or Mod.cache_adapter!" do
+        refute_respond_to mod, :cache_adapter
+        refute_respond_to mod, :cache_adapter!
+      end
+    end
+
+    describe "Stockpile.inject!(Mod, method: stockpile)" do
+      before { ::Stockpile.inject!(mod, method: :stockpile) }
+
+      it "defines Mod.stockpile" do
+        assert_respond_to mod, :stockpile
+      end
+
+      it "defines Mod.stockpile_adapter" do
+        assert_respond_to mod, :stockpile_adapter
+      end
+
+      it "defines Mod.stockpile_adapter!" do
+        assert_respond_to mod, :stockpile_adapter!
+      end
+    end
+
+    describe "Stockpile.inject!(Mod, method: :stockpile, adaptable: false)" do
+      before { ::Stockpile.inject!(mod, method: :stockpile, adaptable: false) }
+
+      it "defines Mod.stockpile" do
+        assert_respond_to mod, :stockpile
+      end
+
+      it "does not define Mod.stockpile_adapter or Mod.stockpile_adapter!" do
+        refute_respond_to mod, :stockpile_adapter
+        refute_respond_to mod, :stockpile_adapter!
+      end
+    end
+
+    describe "Mod.cache_adapter" do
+      let(:now) { Time.now }
+      let(:iso) { now.utc.iso8601 }
+      before do
+        ::Stockpile.inject!(mod, adaptable: true,
+                            default_manager: StockpileTestManager)
+      end
+
+      it "adapts the cache with last_run_time" do
+        mod.cache_adapter(lrt)
+        assert_nil mod.cache.last_run_time('foo')
+        assert_equal iso, mod.cache.last_run_time('foo', now)
+        assert_equal now.to_i, mod.cache.last_run_time('foo').to_i
+      end
+
+      it "adapts the module with last_run_time" do
+        mod.cache_adapter(lrt, mod)
+        assert_nil mod.last_run_time('foo')
+        assert_equal iso, mod.last_run_time('foo', now)
+        assert_equal now.to_i, mod.last_run_time('foo').to_i
+      end
+
+      it "adapts the lrt module with last_run_time" do
+        mod.cache_adapter!(lrt)
+        assert_nil lrt.last_run_time('foo')
+        assert_equal iso, lrt.last_run_time('foo', now)
+        assert_equal now.to_i, lrt.last_run_time('foo').to_i
+      end
+    end
+  end
+
+  # Testing #connection, #connect, #connection_for, #reconnect, and #disconnect
+  # are testing Forwardable. Those tests are to be done in the individual
+  # connectors.
+end

metadata

@@ -0,0 +1,283 @@
+--- !ruby/object:Gem::Specification
+name: stockpile
+version: !ruby/object:Gem::Version
+  version: '1.0'
+platform: ruby
+authors:
+- Austin Ziegler
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-01-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.5'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: hoe-doofus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: hoe-gemspec2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: hoe-git
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: hoe-travis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: minitest-around
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: minitest-autotest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: minitest-bisect
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: minitest-focus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: minitest-moar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
+- !ruby/object:Gem::Dependency
+  name: minitest-pretty_diff
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: hoe
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: |-
+  Stockpile is a simple key-value store connection manager framework. Stockpile
+  itself does not implement a connection manager, but places expectations for
+  implemented connection managers. So far, only Redis has been implemented
+  (stockpile-redis).
+
+  Stockpile also provides an adapter so that its functionality can be accessed
+  from within a module.
+email:
+- halostatue@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- Contributing.rdoc
+- History.rdoc
+- Licence.rdoc
+- Manifest.txt
+- README.rdoc
+files:
+- ".autotest"
+- ".gemtest"
+- ".minitest.rb"
+- ".travis.yml"
+- Contributing.rdoc
+- Gemfile
+- History.rdoc
+- Licence.rdoc
+- Manifest.txt
+- README.rdoc
+- Rakefile
+- lib/stockpile.rb
+- test/minitest_config.rb
+- test/test_stockpile.rb
+homepage: https://github.com/halostatue/stockpile/
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--main"
+- README.rdoc
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Stockpile is a simple key-value store connection manager framework
+test_files:
+- test/test_stockpile.rb