cachetier 0.0.2

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in cachetier.gemspec
+gemspec
+
+group :development, :test, :cucumber do
+  gem "rspec"
+  gem "rspec-mocks"
+end
+

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Yuval Larom
+
+MIT License
+
+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 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/README.md

@@ -0,0 +1,60 @@
+# Cachetier
+
+Data caching is useful when you need to invest in order to fetch the same data over and over, especially when each fetch is expensive, for example DB queries, web service calls, or the result of a non-trivial calculations.
+
+The fastest way to cache data is local memory, but you can also use shared memory such as Redis or memcached which makes the data available to other application servers.
+In some cases, even a DB can be a useful cache for very long operations, or such that you can only access a limited number of times (e.g. web service API with a daily limit).
+
+Cachetier offers a way to define several layers of cache and automatically fetch and store the data over all layers.
+
+## Usage
+
+```ruby  
+def MyClass 
+  def self.get_value(key)
+    ...
+  end
+    
+  include Cachetier
+  cachetier :get_value, { mem: { ttl: 1.minute }, redis: { ttl: 10.minutes } } 
+end  
+```
+
+In the example above, accessing ```MyClass.get_value``` will:
+* Search a local hash for the an entry for ```key```
+* If not found, lookup entry ```key``` in Redis
+* If not found, invoke the original ```get_value``` method, and will store the result in Redis and in the local hash.
+
+Cachetier can also receive a block as a parameter instead of using an existing method. Cachetier will define a class method for the given name.
+
+```ruby
+class MyOtherClass
+  cachetier :get_other_value, { mem: { ttl: 10.sec } }, do |key|
+    ...
+  end
+end
+
+MyOtherClass.get_other_value(42)
+```
+
+## Configuration
+
+Cachetier configuration includes the layers at which data will be cached, and specific options per layer, such as TTL (time to live before expiration).
+
+It currently defined are memory (hash) and Redis layers, but more layers (such as memcached and MongoDB) can be easily added.
+
+You can set global default settings and override them for each method.
+
+```ruby
+
+Cachetier.configuration = { mem: { ttl: 10.seconds } }
+
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+task :default => :spec
+task :test => :spec
+

data/cachetier.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/cachetier/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Yuval Larom"]
+  gem.email         = ["yuval@ftbpro.com"]
+  gem.description   = %q{Multi-tiered cache}
+  gem.summary       = %q{Cache your data on multiple tiers: Redis, Memcached, Mongo, locally, etc}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "cachetier"
+  gem.require_paths = ["lib"]
+  gem.version       = Cachetier::VERSION
+
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rspec'
+end

data/lib/cachetier.rb

@@ -0,0 +1,6 @@
+require "cachetier/nil_value"
+require "cachetier/tier"
+require "cachetier/cache"
+require "cachetier/memory_tier"
+require "cachetier/cachetier"
+require "cachetier/version"

data/lib/cachetier/cache.rb

@@ -0,0 +1,67 @@
+require 'cachetier/tier'
+require 'cachetier/nil_value'
+
+module Cachetier
+	
+	class Cache
+
+    attr_reader :tiers, :getter_block
+
+		def initialize(tiers, &getter_block)
+			raise "Tiers cannot be nil" if !tiers
+			raise "Tiers cannot be empty" if tiers.empty?
+
+			@tiers = tiers.map do |name, options|
+				tier_class = Tier.get_tier_class(name)
+				tier = tier_class.new(options)
+			end
+
+			@getter_block = getter_block
+		end
+
+		def [](key)
+			prev_tiers = []
+
+			# some tiers override the key. save original clone of it
+		  orig_key = begin 
+		  	key.clone
+		  rescue
+		    key
+		  end
+
+			tiers.each do |tier|				
+				value = tier[key]
+				key = orig_key
+
+				if value
+					update_tiers(key, value, prev_tiers)
+					return nil if value == NilValue.value
+					return value
+				end
+				prev_tiers << tier
+			end
+
+			# block might change key
+			self[orig_key] = getter_block.call(key) if getter_block
+		end
+
+		def []=(key, value)
+
+			value = NilValue if value.nil?
+			tiers.each do |tier|
+				tier[key] = value if tier.writable?
+			end
+			return value
+		end
+
+	protected
+
+	  def update_tiers(key, value, tiers)
+	  	tiers.each do |tier|
+				tier[key] = value if tier.writable?
+			end
+	  end
+
+  end
+
+end

data/lib/cachetier/cachetier.rb

@@ -0,0 +1,67 @@
+require 'cachetier/cache'
+
+module Cachetier
+
+  def self.config
+    @@config ||= {}
+  end
+
+  def self.config=(val)
+    @@config = val
+  end
+  
+  def self.included(base)
+    base.send(:extend, ClassMethods)
+  end
+
+  module ClassMethods
+
+    def create_class_method(name, &block)
+      self.class.instance_eval do
+        define_method(name, &block)
+      end
+    end
+
+    def alias_class_method(new_name, original_name)
+      class_eval %Q{
+        class << self
+          alias_method :#{new_name}, :#{original_name}
+        end
+      }
+    end
+
+    def cachetier(method_name, options = nil, &block)
+
+      # given a block, create a new class method called method_name
+      # if not given a block, a method already exists. create a method called X_with_cachetier
+      cached_method_name = block ? method_name : "#{method_name}_with_cachetier"
+      
+      # create a class method that uses cachetier
+      create_class_method cached_method_name do |key|
+        @@cachetiers[method_name][key]
+      end
+
+      # no block given - need to rename the existing method
+      if !block
+        
+        # the original method will be called via X_without_cachetier
+        uncached_method_name = "#{method_name}_without_cachetier"       
+        alias_class_method uncached_method_name, method_name
+
+        # calling the original method name will call X_with_cachetier
+        alias_class_method method_name, cached_method_name
+
+        # create a block for cachetier that calls the uncached version
+        block = proc { |key| self.send(uncached_method_name, key) } 
+      end
+
+
+      options = Cachetier::config.merge(options || {})
+    	cache = Cachetier::Cache.new(options, &block)
+    	(@@cachetiers ||= {})[method_name] = cache
+    end
+
+  end
+
+
+end

data/lib/cachetier/memory_tier.rb

@@ -0,0 +1,41 @@
+require 'cachetier/tier'
+
+module Cachetier
+  class MemoryTier < Tier
+    
+    register_tier_class :mem, MemoryTier
+
+    def initialize(options = nil)
+      super
+      @cache = {}
+    end
+
+    def get_val_and_expiration_time(key)
+      val, expiration_time = @cache[key]
+    end
+
+    def reset(key)
+      @cache.delete(key)
+    end
+
+    def size
+      @cache.size
+    end
+
+    def keys
+      return @cache.keys
+    end
+
+    def expired?(key)
+      val, expiration_time = get_val_and_expiration_time(key)
+      return expiration_time < Time.now
+    end
+
+  protected
+
+    def set(key, value, ttl)
+      @cache[key] = [value, Time.now + ttl.to_f]
+    end
+
+  end
+end

data/lib/cachetier/nil_value.rb

@@ -0,0 +1,12 @@
+require 'cachetier/tier'
+
+module Cachetier
+
+  class NilValue
+  	def self.value
+  	  @@value ||= NilValue.new
+  	end
+  end
+	
+
+end

data/lib/cachetier/redis_tier.rb

@@ -0,0 +1,43 @@
+require 'cachetier/tier'
+
+module Cachetier
+	class RedisTier < Tier
+	  
+	  register_tier_class :redis, RedisTier
+
+	  def initialize(options)
+	  	super
+	  	@redis = options[:redis]
+	  	raise "Option :redis is required" if !@redis
+	  end
+
+	  def get_val_and_expiration_time(key)
+	  	val = @redis.get(key)
+	  	expiration_time = Time.now + @redis.ttl(key) if val
+	  	return [val, expiration_time]
+	  end
+
+	  def reset(key)
+	  	@redis.del(key)
+	  end
+	  
+	protected
+
+		def size
+	  	0
+	  end
+	  
+		def sweepable?
+    	false
+    end
+
+	  def set(key, value, ttl)
+	  	@redis.multi do
+	  		@redis.set(key, value)
+	  		@redis.expire(key, ttl)
+	  	end
+	  	value
+	  end
+
+	end
+end

data/lib/cachetier/tier.rb

@@ -0,0 +1,109 @@
+module Cachetier
+  class Tier
+
+    def self.register_tier_class(name, klass)
+      @@tier_classes ||= {}
+      @@tier_classes[name] = klass
+    end
+
+    def self.get_tier_class(name)
+      return @@tier_classes[name]
+    end
+    
+    DEFAULTS = {
+      ttl: 0,
+      high_watermark: nil,
+      low_watermark: nil
+    }
+
+    def initialize(options = nil)
+      @options = DEFAULTS.merge(options || {})
+      raise "TTL must be a positive number" if ttl && ttl < 0
+      raise "High watermark must be a positive number" if high_watermark && high_watermark <= 0
+      raise "Low watermark must be a positive number"  if low_watermark  && low_watermark  <= 0
+      raise "High watermark must be larger than lower watermark" if high_watermark && low_watermark && high_watermark <= low_watermark
+    end
+
+    def ttl
+      @options[:ttl]
+    end
+
+    def high_watermark
+      @options[:high_watermark]
+    end
+
+    def low_watermark
+      @options[:low_watermark]
+    end
+
+    def [](key)
+      val, expiration_time = get_val_and_expiration_time(key)
+      
+      if expiration_time && Time.now > expiration_time
+        val = nil
+        reset key
+      end
+      
+      return val
+    end
+
+    def reset(key)
+      raise NotImplementedError
+    end
+
+    def []=(key, value)
+      raise "Read-only tier" if !writable?
+      sweep_if_needed if sweepable?
+      set(key, value, ttl)
+    end
+
+    def writable?
+      return @options[:writable] if @options.has_key?(:writable)
+      true
+    end
+
+    def sweepable?
+      return @options[:sweepable] if @options.has_key?(:sweepable)
+      true
+    end
+
+  protected
+
+    def sweep_if_needed
+      if high_watermark && low_watermark
+        sweep if size >= high_watermark
+      end
+    end
+
+    def sweep
+      do_sweep(force: false)
+      if size >= high_watermark
+        do_sweep(force: true)
+      end
+    end
+
+    def do_sweep(options = {force: false})
+      force = options[:force]
+      raise "Read-only tier" if !writable?
+      raise "Un-sweeable tier" if !sweepable?
+      curr_size = size
+      keys.each do |key| 
+        if force || expired?(key)
+          reset(key)
+          curr_size -= 1
+          break if curr_size <= low_watermark
+        end
+      end
+    end
+
+    def get_val_and_expiration_time(key)
+      raise NotImplementedError
+    end
+
+
+    def keys
+      raise NotImplementedError
+    end
+  end
+
+end

data/lib/cachetier/version.rb

@@ -0,0 +1,3 @@
+module Cachetier
+  VERSION = "0.0.2"
+end

data/spec/lib/cachetier_spec.rb

@@ -0,0 +1,139 @@
+require 'spec_helper'
+require 'cachetier'
+
+class DummyTier < Cachetier::Tier	
+	def set(key, value, ttl)
+  end
+
+  def reset(key)
+  end
+end
+
+
+class AlwaysExpiredDummyTier < DummyTier
+	register_tier_class :always_expired, AlwaysExpiredDummyTier
+
+  def get_val_and_expiration_time(key)
+  	return :dummy_cached_value_that_should_never_be_returned, Time.now - 1  # always ewxpired
+  end
+end
+
+class AlwaysFreshDummyTier < DummyTier
+	register_tier_class :always_fresh, AlwaysFreshDummyTier
+
+  def get_val_and_expiration_time(key)
+  	return :dummy_cached_value, Time.now + 10  # never expires
+  end
+end
+
+class SingleValueDummyTier < DummyTier
+	register_tier_class :single_value, SingleValueDummyTier
+
+  def initialize(options)
+  	super
+  	@value = options[:value]
+  	@expires_at = Time.now + options[:ttl]
+  end
+
+	def get_val_and_expiration_time(key)
+  	return @value, @expires_at # never expires
+  end
+
+	def set(key, value, ttl)
+		@value = [:single_value_tier, value]
+		@expires_at = Time.now + ttl
+  end
+
+  def reset(key)
+  end
+
+  def has_key?(key)
+  	true
+  end
+end
+
+
+describe Cachetier::Cache do
+
+  it "should return nil if nothing there" do
+    cache = Cachetier::Cache.new(mem: { ttl: 0.2 })
+    cache[:a].should == nil
+  end
+  
+  it "should use memory tier to save data for 2 sec then expire it" do
+    cache = Cachetier::Cache.new(mem: { ttl: 0.2 })
+    cache[:a] = 1
+    cache[:a].should == 1
+    sleep 0.1
+    cache[:a].should == 1
+    sleep 0.2
+    cache[:a].should == nil
+  end
+
+  it "should use getter_block to set value" do
+    cache = Cachetier::Cache.new(mem: { ttl: 0.2 }) { :the_value }
+    cache[:a].should == :the_value
+  end
+
+  it "should create a cachetier for class and always return the cached value" do
+
+  	class DummyClass1
+  		include Cachetier
+
+  		cachetier :get_cached_val, { always_fresh: nil } do |key| 
+  			:dummy_uncached_value 
+  		end
+  	end
+
+  	DummyClass1.get_cached_val(:dummy_key).should == :dummy_cached_value
+  end
+
+  it "should create a cachetier for class and never return the cached value" do
+
+  	class DummyClass2
+  		include Cachetier
+
+  		cachetier :get_cached_val, { always_expired: nil } do |key| 
+  			:dummy_uncached_value 
+  		end
+  	end
+
+  	DummyClass2.get_cached_val(:dummy_key).should == :dummy_uncached_value
+  end
+
+  it "should fallback from one tier to the next" do
+
+  	class DummyClass3
+  		include Cachetier
+
+  		cachetier :get_cached_val, { always_expired: nil, always_fresh: nil } do |key| 
+  			:dummy_uncached_value 
+  		end
+		end
+
+		# the first tier is always expired, the second is always fresh. 
+		# the request should try the first tier, fail, and get from the fresh tier
+
+  	DummyClass3.get_cached_val(:dummy_key).should == :dummy_cached_value
+  end
+
+  it "should update expired tiers" do
+
+  	class DummyClass4
+  		  include Cachetier
+
+  		  cachetier :get_cached_val, { single_value: { value: :initial_value, ttl: 0.1 } } do |key|
+  		  	:set_value
+  		  end
+
+  	end
+
+  	DummyClass4.get_cached_val(:whatever).should == :initial_value
+  	sleep 0.2
+  	DummyClass4.get_cached_val(:whatever).should == :set_value   # returned by getter proc
+  	DummyClass4.get_cached_val(:whatever).should == [:single_value_tier, :set_value] # returned by tier
+  end
+
+
+end
+

data/spec/lib/memory_tier_spec.rb

@@ -0,0 +1,47 @@
+require 'spec_helper'
+require 'cachetier'
+
+describe Cachetier::MemoryTier do
+
+	it "should save data for 200ms sec then expire it" do
+    cache = Cachetier::MemoryTier.new(ttl: 0.2)
+    cache[:a] = 1
+    cache[:a].should == 1
+    sleep 0.1
+    cache[:a].should == 1
+    sleep 0.2
+    cache[:a].should be_nil
+  end
+
+  it "should sweep oldest keys when reaching high_watermark until only low_watermark items remain" do
+    cache = Cachetier::MemoryTier.new(ttl: 0.2, high_watermark: 20, low_watermark: 10)
+
+    20.times do |i|
+    	cache[i] = i
+    	cache.size.should == i + 1
+    end
+
+    # now that we have 20 items in the cache, 
+    # adding a new item should triggr a sweep old keys until size is 10, 
+    # and then the new item is added, bringing size to 11
+
+    cache[99] = 99
+    cache.size.should == 11
+    
+    # make sure oldest keys are gone
+
+    10.times do |i|
+    	cache[i].should == nil
+    end
+
+    # make sure newest keys are there
+
+    (11 .. 19).each do |i|
+    	cache[i].should == i
+    end
+
+    cache[99].should == 99
+  end
+
+  
+end

data/spec/lib/redis_tier_spec.rb

@@ -0,0 +1,33 @@
+require 'spec_helper'
+require 'cachetier'
+require 'cachetier/redis_tier'
+
+describe Cachetier::RedisTier do
+
+	it "should require redis param" do
+		expect { Cachetier::RedisTier.new({}) }.to raise_error
+	end
+
+	it "should try fetching value from redis, and check redis ttl" do
+  	redis = double("redis")
+  	redis.stub(get: :redis_cached_value)
+  	redis.stub(ttl: 1)
+
+		cache = Cachetier::RedisTier.new({redis: redis})
+
+		redis.should_receive(:ttl).with(:key)
+		cache[:key].should == :redis_cached_value
+	end
+
+	it "should try fetching value from redis, and check redis ttl" do
+  	redis = double("redis")
+  	redis.stub(multi: 1)
+
+		cache = Cachetier::RedisTier.new({redis: redis})
+
+		redis.should_receive(:multi)
+		cache[:key] = 1
+
+	end
+end
+

data/spec/lib/tier_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+require 'cachetier'
+
+describe Cachetier::Tier do
+
+	it "should validate tier ctor args" do
+		expect { Cachetier::Tier.new(ttl: -1) }.to raise_error
+		Cachetier::Tier.new(ttl: 10).should_not be_nil
+		
+		expect { Cachetier::Tier.new(high_watermark: -1) }.to raise_error
+		expect { Cachetier::Tier.new(low_watermark: -1) }.to raise_error
+		expect { Cachetier::Tier.new(high_watermark: 1, low_watermark: 3) }.to raise_error
+		Cachetier::Tier.new(high_watermark: 3, low_watermark: 1).should_not be_nil
+	end
+
+	it "should be able to modify tier writability and sweepability" do
+
+    Cachetier::Tier.new.writable?.should be_true
+    Cachetier::Tier.new.sweepable?.should be_true
+
+    Cachetier::Tier.new(writable: true, sweepable: false).writable?.should be_true
+    Cachetier::Tier.new(writable: true, sweepable: false).sweepable?.should be_false
+
+    Cachetier::Tier.new(writable: false, sweepable: true).writable?.should be_false
+    Cachetier::Tier.new(writable: false, sweepable: true).sweepable?.should be_true
+  end
+
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require 'cachetier'

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: cachetier
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+  prerelease: 
+platform: ruby
+authors:
+- Yuval Larom
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  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'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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: Multi-tiered cache
+email:
+- yuval@ftbpro.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- cachetier.gemspec
+- lib/cachetier.rb
+- lib/cachetier/cache.rb
+- lib/cachetier/cachetier.rb
+- lib/cachetier/memory_tier.rb
+- lib/cachetier/nil_value.rb
+- lib/cachetier/redis_tier.rb
+- lib/cachetier/tier.rb
+- lib/cachetier/version.rb
+- spec/lib/cachetier_spec.rb
+- spec/lib/memory_tier_spec.rb
+- spec/lib/redis_tier_spec.rb
+- spec/lib/tier_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -4048666811473957132
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -4048666811473957132
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: ! 'Cache your data on multiple tiers: Redis, Memcached, Mongo, locally, etc'
+test_files:
+- spec/lib/cachetier_spec.rb
+- spec/lib/memory_tier_spec.rb
+- spec/lib/redis_tier_spec.rb
+- spec/lib/tier_spec.rb
+- spec/spec_helper.rb