atomic_redis_cache 0.2.0 → 0.2.1

data/README.md

@@ -1,16 +1,17 @@
 # AtomicRedisCache
 
-AtomicRedisCache is an overlay on top of the redis-rb library that allows you to
-use Redis much like the Rails cache (ActiveSupport::Cache). It duplicates only
-the .fetch() method, which reads from a key if present and valid, or else
-evaluates the passed block and saves it as the new value at that key. The
-foremost design goals apply mainly to webapps and are twofold:
-- when cache expires, to avoid dogpile/thundering herd from multiple processes
-recalculating by serving the cached value to all but one process, then updating
-atomically when calculation by that process completes
+AtomicRedisCache is an overlay on top of Redis that allows you to use it much
+like the Rails cache (ActiveSupport::Cache). Usage centers around the `.fetch()`
+method, which reads from a key if present and valid, or else evaluates the
+passed block and saves it as the new value at that key. The foremost design
+goals apply mainly to webapps and are twofold:
+- when the cached value expires, recalculate in the first process to access it,
+  serving the old value to all other processes until completion, thus avoiding
+  the dogpile/thundering herd effect
+  (http://en.wikipedia.org/wiki/Thundering_herd_problem)
 - when calculation takes too long (i.e., due to db, network calls) and a
-recently expired cached value is available, to fail fast with it and try
-calculating again later (for a reaosnable # of retries)
+  recently expired cached value is available, fail fast with it and try
+  calculating again later (for a reasonable # of retries)
 
 ## Installation
 
@@ -31,18 +32,15 @@ Or install it yourself as:
 Ensure that you set the value of `AtomicRedisCache.redis`. This can be either an
 instance of redis-rb (or compatible), or a lambda/Proc evaluating to one. Ex.
 
-```
-AtomicRedisCache.redis = Redis.new(:host => '127.0.0.1', :port => 6379)
-```
+``` AtomicRedisCache.redis = Redis.new(:host => '127.0.0.1', :port => 6379) ```
 
 Then use it as you would Rails.cache:
 
 ```
 >> v = AtomicRedisCache.fetch('key') { Faraday.get('example.com').status }
 => 200  # network call made
->> v = AtomicRedisCache.fetch('key') { }
-=> 200  # value read from cache
-```
+>> v = AtomicRedisCache.fetch('key') { raise 'Network call attempted' }
+=> 200  # value read from cache ```
 
 There are a couple of configurable options can be set per fetch:
 - `:expires_in` - expiry in seconds; defaults to a day

data/atomic_redis_cache.gemspec

@@ -23,4 +23,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'fakeredis'
+  spec.add_development_dependency 'timecop'
 end

data/lib/atomic_redis_cache/version.rb

@@ -1,3 +1,3 @@
 module AtomicRedisCache
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

data/lib/atomic_redis_cache.rb

@@ -52,11 +52,16 @@ module AtomicRedisCache
       Marshal.load(val)
     end
 
+    # Fetch from the cache atomically; return nil if empty or expired
     def read(key)
       val, exp = redis.mget key, timer(key)
-      Marshal.dump(val) if exp > Time.now.to_i
+      Marshal.load(val) unless exp.to_i < Time.now.to_i
     end
 
+    # Write to the cache unconditionally, returns success as boolean
+    # Accepts the same options and uses the same defaults as .fetch()
+    # Note that write() ignores locks, so it can be called multiple times;
+    # prefer .fetch() unless absolutely necessary.
     def write(key, val, opts={})
       expires_in = opts[:expires_in] || DEFAULT_EXPIRATION
       race_ttl   = opts[:race_condition_ttl] || DEFAULT_RACE_TTL
@@ -72,8 +77,9 @@ module AtomicRedisCache
       response.all? { |ret| ret == 'OK' }
     end
 
+    # Delete the cache entry completely, including timer
     def delete(key)
-      redis.del(key) == 1
+      redis.del(key, timer(key)) == 2
     end
 
     def timer(key)
@@ -82,7 +88,7 @@ module AtomicRedisCache
     private :timer
 
     def redis
-      raise 'AtomicRedisCache.redis must be set before use.' unless @redis
+      raise ArgumentError.new('AtomicRedisCache.redis must be set') unless @redis
       @redis.respond_to?(:call) ? @redis.call : @redis
     end
     private :redis

data/spec/spec_helper.rb

@@ -1,2 +1,11 @@
 require 'rspec'
 require 'fakeredis/rspec'
+require 'timecop'
+
+require 'atomic_redis_cache'
+
+RSpec.configure do |config|
+  config.around(:each) do |example|
+    Timecop.freeze(Time.now.utc, &example)
+  end
+end

data/spec/unit/atomic_redis_cache_spec.rb

@@ -0,0 +1,106 @@
+require 'spec_helper'
+
+describe AtomicRedisCache, :order => :random do
+  subject         { AtomicRedisCache }
+
+  let(:redis)     { Redis.new }
+
+  let(:key)       { 'key' }
+  let(:val)       { {:a => 1} }
+  let(:m_val)     { Marshal.dump(val) }
+  let(:timer_key) { "timer:#{key}" }
+  let(:now)       { Time.now.to_i }
+
+  before { subject.redis = redis }
+
+  describe '.redis=' do
+    it 'accepts a Redis instance' do
+      subject.redis = Redis.new
+      expect { subject.read(key) }.to_not raise_error
+    end
+    it 'accepts a lambda evaluating to a Redis instance' do
+      subject.redis = lambda { Redis.new }
+      expect { subject.read(key) }.to_not raise_error
+    end
+  end
+
+  describe '.fetch' do
+    it 'requires .redis to be set' do
+      subject.redis = nil
+      expect { subject.fetch(key) { val } }.to raise_error(ArgumentError)
+    end
+
+    it 'serializes complex objects for storage' do
+      subject.fetch(key) { val }
+      expect(redis.get(key)).to eq(m_val)
+    end
+
+    it 'de-serializes objects on retrieval' do
+      redis.mset(key, m_val, timer_key, now)
+      expect(subject.fetch(key)).to eq(val)
+    end
+
+    it 'returns nil if a key does not exist' do
+      expect(subject.read(key)).to be_nil
+    end
+  end
+
+  describe '.read' do
+    it 'requires .redis to be set' do
+      subject.redis = nil
+      expect { subject.read(key) }.to raise_error(ArgumentError)
+    end
+
+    it 'de-serializes objects on retrieval' do
+      redis.mset(key, m_val, timer_key, now)
+      expect(subject.read(key)).to eq(val)
+    end
+
+    it 'returns nil if a key does not exist' do
+      expect(subject.read(key)).to be_nil
+    end
+
+    it 'returns nil if a key is present but expired' do
+      redis.mset(key, m_val, timer_key, now)
+      expect(subject.read(key)).to eq(val)
+      Timecop.travel(now + 1) do
+        expect(subject.read(key)).to be_nil
+      end
+    end
+  end
+
+  describe '.write' do
+    it 'requires .redis to be set' do
+      subject.redis = nil
+      expect { subject.write(key, val) }.to raise_error(ArgumentError)
+    end
+
+    it 'serializes complex objects for storage' do
+      subject.write(key, val)
+      expect(redis.get(key)).to eq(m_val)
+    end
+  end
+
+  describe '.delete' do
+    it 'requires .redis to be set' do
+      subject.redis = nil
+      expect { subject.delete(key) }.to raise_error(ArgumentError)
+    end
+
+    it 'returns false if a key does not exist' do
+      expect(subject.delete(key)).to be_falsey
+    end
+
+    it 'returns true if a key exists' do
+      redis.mset(key, m_val, timer_key, now)
+      expect(subject.delete(key)).to be_truthy
+    end
+
+    it 'deletes both the key and timer' do
+      redis.mset(key, m_val, timer_key, now)
+      subject.delete(key)
+      expect(redis.get(key)).to be_nil
+      expect(redis.get(timer_key)).to be_nil
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: atomic_redis_cache
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -75,6 +75,22 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: ''
 email:
 - anujdas@gmail.com
@@ -91,7 +107,7 @@ files:
 - lib/atomic_redis_cache.rb
 - lib/atomic_redis_cache/version.rb
 - spec/spec_helper.rb
-- spec/unit/.gitkeep
+- spec/unit/atomic_redis_cache_spec.rb
 homepage: https://github.com/anujdas/atomic_redis_cache
 licenses:
 - MIT
@@ -120,4 +136,4 @@ summary: Use Redis as a multi-process atomic cache to avoid thundering herds and
   calculations
 test_files:
 - spec/spec_helper.rb
-- spec/unit/.gitkeep
+- spec/unit/atomic_redis_cache_spec.rb