ca_ching 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,16 @@
+source "http://rubygems.org"
+
+gemspec
+
+# Development gems
+gem 'ruby-debug19'
+gem 'rake'
+
+gem 'sqlite3'
+
+# Testing
+gem 'rspec'
+gem 'machinist'
+gem 'faker'
+gem 'guard-rspec'
+gem 'growl_notify'

data/Guardfile

@@ -0,0 +1,9 @@
+guard 'rspec', :version => 2, :cli => "--color --format documentation" do
+  watch(%r{^spec/ca_ching/.+_spec\.rb$})
+  watch(%r{^lib/ca_ching/(.+)\.rb$})     { |m| "spec/ca_ching/#{m[1]}_spec.rb" }
+  watch(%r{^spec/ca_ching/adapters/.+_spec\.rb$})
+  watch(%r{^lib/ca_ching/adapters/(.+)\.rb$})     { |m| "spec/ca_ching/adapters/#{m[1]}_spec.rb" }
+  watch(%r{^spec/ca_ching/query/.+_spec\.rb$})
+  watch(%r{^lib/ca_ching/query/(.+)\.rb$})     { |m| "spec/ca_ching/query/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Andrew Latimer
+
+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,106 @@
+# CaChing
+
+CaChing is a write-through and read-through caching library for ActiveRecord 3.1+. 
+
+That means that when you read from the database, your results are stored in the cache (read-through). When you write to
+the database, whatever is written to the database is also written to the cache (write-through). If the results are already
+in the cache, great, they're read straight from there on a read, and updated on a write. 
+
+Take a look at `SPEC.md` for what's planned for v1.
+
+## Getting started
+
+In your Gemfile:
+
+    gem 'ca_ching'
+    # gem 'ca_ching', :git => 'git://github.com/ahlatimer/ca_ching.git' # Track git repo
+
+In an initializer:
+    
+    CaChing.configure do |config|
+      config.cache = CaChing::Adapters::Redis.new
+      config.enabled = true # defaults to true
+    end
+    
+## Defining what to cache
+
+The simplest case is to add `index :field_name` to your model. From then on, any query that does a find based on
+that field will get cached. 
+
+    class Person < ActiveRecord::Base
+      index :id
+      index :first_name
+      index :last_name
+      
+      has_many :addresses
+    end
+    
+    class Address < ActiveRecord::Base  
+      # Let's you find by associations (person.addresses.all)
+      index :person_id
+      
+      belongs_to :person
+    end
+    
+## Using the cache
+
+If you've defined your indices, everything should work without any additional effort. Doing 
+`Person.where(:first_name => 'Andrew')` should hit the cache and return what is there, or 
+miss and pull the data into the cache. 
+
+## Queries supported
+
+Generally anything `eqality` is supported by CaChing. Currently, only single fields can be found (e.g., `Person.where(:name => 'Andrew')` will be cached,
+`Person.where(:name => 'Andrew', :age => 22)` is not). There is some plumbing for adding support for the latter, and support will be
+introduced as soon as possible. 
+
+Anything including joins, includes, `OR`, and inequality (!=) are not supported, nor do I have any plans for adding support. 
+
+For example, these queries are supported:
+
+    Person.where(:first_name => 'Andrew')
+    Person.find_by_first_name('Andrew')
+    Person.find_all_by_first_name('Andrew')
+
+These queries are not:
+    
+    Person.where('first_name = ? OR first_name = ?', 'Andrew', 'David')
+    Person.where('first_name != ?', 'Andrew')
+    Person.where(:first_name => 'Andrew').order('created_at DESC') # not supported because first_name isn't sorted by anything
+    Person.where('id >= 200')
+    Person.where('created_at >= ?', Date.today - 1).where(:first_name => 'Andrew')
+    Person.where('created_at <= ?', Date.today - 1).where(:first_name => 'Andrew').limit(10).order('created_at desc')
+     
+## Caveats
+
+### Order
+
+Order is not currently supported, although there will be some order semantics in the next version. 
+
+### Composite keys and queries against multiple fields
+
+Because of the awesomeness from Redis, composite keys aren't necessary for queries with multiple fields.
+If all of the fields are indexed, CaChing will try to use the cache to build the results. 
+
+Redis requires that sorted set intersections be stored in a resulting set. If the composite key is not specified 
+for a query against those fields, that resulting set will be destroyed as soon as the results are read. If the 
+composite key *is* specified, CaChing will keep the resulting set. 
+
+While there is support for this in the Redis adapter, there isn't any support in the ActiveRecord ties as I haven't
+decided how, exactly, I'd like to add this. 
+
+## Ruby/Rails versions supported
+
+Ruby 1.9.2 and Rails 3.1+ are officially supported. I try to stick to Ruby 1.8.7 syntax, so it may be supported, 
+but use it with the understanding that you are doing so at your own risk.
+
+## Patches and Issues
+
+I'd love the help! If you find an issue, please report it on the [Github issues page](http://github.com/ahlatimer/ca_ching/issues).
+If you fix an issue, please include a spec that illustrates the issue. If you submit a feature, include thorough specs. 
+Don't bump up the version in your pull request. If you want to keep different versions in your fork, feel free, but
+please do not include them in your pull request.  
+
+## Acknowledgments
+
+Inspired by (and a bit of code copied from) [Cache Money](http://github.com/ngmoco/cache-money).

data/Rakefile

@@ -0,0 +1,19 @@
+require 'bundler'
+require 'rspec/core/rake_task'
+
+Bundler::GemHelper.install_tasks
+
+RSpec::Core::RakeTask.new(:spec) do |rspec|
+  rspec.rspec_opts = ['--debugger', '--color', '--format documentation']
+end
+
+task :default => :spec
+
+desc "Open an irb session with CaChing and the sample data used in specs"
+task :console do
+  require 'irb'
+  require 'irb/completion'
+  require 'console'
+  ARGV.clear
+  IRB.start
+end

data/SPEC.md

@@ -0,0 +1,109 @@
+# CaChing
+
+CaChing is a write-through and read-through caching library for ActiveRecord 3.1+. 
+
+That means that when you read from the database, your results are stored in the cache (read-through). When you write to
+the database, whatever is written to the database is also written to the cache (write-through). If the results are already
+in the cache, great, they're read straight from there on a read, and updated on a write. 
+
+## Getting started
+
+In your Gemfile:
+
+    gem 'ca_ching'
+    # gem 'ca_ching', :git => 'git://github.com/ahlatimer/ca_ching.git' # Track git repo
+
+In an initializer:
+    
+    CaChing.configure do |config|
+      # some configuration options go here, likely just for redis...
+    end
+    
+## Defining what to cache
+
+The simplest case is to add `index :field_name` to your model. From then on, any query that does a find based on
+that field will get cached. You can also specify the maximum number of elements stored, the TTL (time to live),
+and the order. 
+
+    class Person < ActiveRecord::Base
+      index :id
+      index :first_name, :limit => 1000
+      index :last_name,  :limit => 1000, :order => { :created_at => :desc }
+      
+      has_many :addresses
+    end
+    
+    class Address < ActiveRecord::Base  
+      # You can have associations, so person.addresses.find(1) will hit the cache if a composite index is specified
+      index [:id, :person_id], :limit => 100, :ttl => 10.minutes
+      # Or just find all of them based on person_id (person.addresses.all)
+      index :person_id
+      
+      belongs_to :person
+    end
+    
+## Using the cache
+
+If you've defined your indices, everything should work without any additional effort. Doing 
+`Person.where(:first_name => 'Andrew')` should hit the cache and return what is there, or 
+miss and pull the data into the cache. 
+
+## Queries supported
+
+Generally anything with an `AND` and/or `eqality` is supported by CaChing. Anything including
+joins, includes, `OR`, and inequality (!=) are not supported at this time. Queries involving
+comparators (>, <, >=, <=) are supported ONLY if the order is specified. The caveats for order
+(covered below) apply here as well. 
+
+For example, these queries are supported:
+
+    Person.where(:first_name => 'Andrew')
+    Person.find_by_first_name('Andrew')
+    Person.where('created_at >= ?', Date.today - 1).where(:first_name => 'Andrew')
+    Person.where('created_at <= ?', Date.today - 1).where(:first_name => 'Andrew').limit(10).order('created_at desc')
+
+These queries are not:
+    
+    Person.where('first_name = ? OR first_name = ?', 'Andrew', 'David')
+    Person.where('first_name != ?', 'Andrew')
+    Person.where(:first_name => 'Andrew').order('created_at DESC') # not supported because first_name isn't sorted by anything
+    Person.where('id >= 200')
+     
+## Caveats
+
+### Order
+
+If the order in the query is not the same as the order in the index directive, the cache will be skipped. 
+It's likely faster to take the DB hit than to try to sort in Ruby. 
+
+If multiple fields are specified, at least one of them must have the order of the query. 
+
+If the field is sorted, it must respond to `to_f` and return a reasonable response (e.g., even though a 
+string will respond to `to_f`, it will return `0.0` if it is not a number). 
+
+By default, indexes are ordered by the primary key. 
+
+### Composite keys and queries against multiple fields
+
+Because of the awesomeness from Redis, composite keys aren't necessary for queries with multiple fields.
+If all of the fields are indexed, CaChing will try to use the cache to build the results. 
+
+Redis requires that sorted set intersections be stored in a resulting set. If the composite key is not specified 
+for a query against those fields, that resulting set will be destroyed as soon as the results are read. If the 
+composite key *is* specified, CaChing will keep the resulting set. 
+
+## Ruby/Rails versions supported
+
+Ruby 1.9.2 and Rails 3.1+ are officially supported. I try to stick to Ruby 1.8.7 syntax, so it may be supported, 
+but use it with the understanding that you are doing so at your own risk.
+
+## Patches and Issues
+
+I'd love the help! If you find an issue, please report it on the [Github issues page](http://github.com/ahlatimer/ca_ching/issues).
+If you fix an issue, please include a spec that illustrates the issue. If you submit a feature, include thorough specs. 
+Don't bump up the version in your pull request. If you want to keep different versions in your fork, feel free, but
+please do not include them in your pull request.  
+
+## Acknowledgments
+
+Inspired by (and a bit of code copied from) [Cache Money](http://github.com/ngmoco/cache-money).

data/ca_ching.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "ca_ching/version"
+
+Gem::Specification.new do |s|
+  s.name        = "ca_ching"
+  s.version     = CaChing::Version.to_s
+  s.authors     = ["Andrew Latimer"]
+  s.email       = ["andrew@elpasoera.com"]
+  s.homepage    = "http://github.com/ahlatimer/ca_ching"
+  s.summary     = %q{Write-through ActiveRecord model caching that's right on the money}
+  s.description = %q{Write-through ActiveRecord model caching that's right on the money}
+
+  s.rubyforge_project = "ca_ching"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  
+  s.add_dependency 'hiredis'
+  s.add_dependency 'redis', '2.2.2'
+  s.add_dependency 'activesupport', '>= 3.1.0'
+  s.add_dependency 'activerecord', '>= 3.1.0'
+end

data/lib/ca_ching/adapters/active_record.rb

@@ -0,0 +1,23 @@
+
+ActiveRecord::Base.send :include, CaChing::Index
+ActiveRecord::Base.send :include, CaChing::WriteThrough
+ActiveRecord::Relation.send :include, CaChing::ReadThrough
+
+class ActiveRecord::Base
+  attr_accessor :from_cache
+  
+  def from_cache?
+    @from_cache ||= false
+  end
+  
+  def to_keys(options={})
+    was = options[:old_values] ? "_was" : ""
+    indexed_fields.map do |index, options|
+      if index.is_a?(Array)
+        self.class.table_name.to_s + index.map { |index| "#{index}=#{self.send("#{index}#{was}")}" }.join("&")
+      else
+        "#{self.class.table_name}:#{index}=#{self.send("#{index}#{was}")}"
+      end
+    end
+  end
+end

data/lib/ca_ching/adapters/redis.rb

@@ -0,0 +1,127 @@
+module CaChing  
+  module Adapters
+    class Redis
+      def initialize(options={})
+        @cache = ::Redis.new(options)
+      end
+      
+      def find(query, options={})
+        results = nil        
+        # where_values in the form { :field => ['=', 'value'] }
+        where_values = query.where
+        keys = where_values.map { |where_value| "#{where_value[0]}#{where_value[1][0]}#{where_value[1][1]}" }
+        return nil if keys.empty?
+        
+        offset = query.offset || 0
+        limit = (query.limit || 0) + offset - 1
+        
+        if keys.length <= 1
+          key = "#{query.table_name}:#{keys[0]}"
+          return nil unless @cache.exists key # the key has never been added to the cache, so it's a miss
+          
+          results = @cache.zrange(key, offset, limit)
+        else # needs an intersection
+          intersection_key = "#{query.table_name}:#{keys.join "&"}"
+          
+          if @cache.exists intersection_key
+            results = @cache.zrange(intersection_key, offset, limit)
+          else
+            return nil unless keys.inject(true) { |memo, key| @cache.exists("#{query.table_name}:#{key}") && memo }
+            @cache.zinterstore intersection_key, *keys.map { |key| "#{query.table_name}:#{key}" }
+            @cache.zrange(intersection_key, offset, limit)
+            @cache.del(intersection_key) unless options[:keep_intersection]
+          end
+        end
+        
+        inflate(results, :for => query)
+      end
+      
+      def insert(objects, options={})
+        key = nil
+        if options[:for]
+          query = options[:for]
+          if (where_values = query.where).length == 1
+            where_value = query.where.first
+            key = "#{query.table_name}:#{where_value[0]}#{where_value[1][0]}#{where_value[1][1]}"
+          else
+            nil
+          end
+        elsif options[:at]
+          key = options[:at]
+        end
+        
+        return nil if key.nil?
+        
+        deflated = deflate_with_score(objects)
+        deflated.each do |object_and_score|
+          @cache.zadd key, *object_and_score
+        end
+      
+        objects
+      end
+
+      def update(object, options={})
+        old_keys = object.to_keys(:old_values => true).select { |key| @cache.exists(key) }
+        new_keys = object.to_keys(:old_values => false).select { |key| @cache.exists(key) }
+        
+        @cache.multi do
+          old_keys.each do |key|
+            destroy(object, :at => key, :old_values => true)
+          end
+
+          new_keys.each do |key|
+            insert([object], :at => key)
+          end
+        end
+      end
+      
+      def destroy(object, options={})
+        @cache.zrem(options[:at], deflate(object, :old_values => options[:old_values]))
+      end
+      
+      def clear!
+        @cache.flushdb
+      end
+      
+      def inflate(objects, options={})
+        return nil if objects.nil?
+        
+        unless options[:for]
+          return objects
+        else
+          objects.map do |object|
+            obj = options[:for].klass.new
+            attributes = ActiveSupport::JSON.decode(object)
+            attributes.each do |attr, value|
+              obj.send(:"#{attr}=", value)
+            end
+            obj.changed_attributes.clear
+            obj.send(:instance_variable_set, "@new_record", false)
+            obj
+          end
+        end
+      end
+      
+      def deflate(object, options={})
+        attributes = if options[:old_values]
+          object.attributes.keys.inject({}) do |attributes, key|
+            attributes[key] = object.send(:"#{key}_was")
+            attributes
+          end
+        else
+          object.attributes
+        end
+        
+        ActiveSupport::JSON.encode(attributes)
+      end
+      
+      def deflate_with_score(objects, options={})
+        return nil if objects.nil?
+        
+        score_method = options[:sorted_by] || :id
+        
+        objects.map { |object| [object.send(score_method).to_i, deflate(object)] }
+      end
+    end
+  end
+end

data/lib/ca_ching/configuration.rb

@@ -0,0 +1,23 @@
+module CaChing
+  module Configuration
+    def configure
+      yield self
+    end
+    
+    def cache=(cache)
+      @cache = cache
+    end
+    
+    def cache
+      @cache 
+    end
+    
+    def disabled?
+      @disabled
+    end
+    
+    def disabled=(d)
+      @disabled = d
+    end
+  end
+end

data/lib/ca_ching/core_ext/array.rb

@@ -0,0 +1,7 @@
+class Array
+  attr_accessor :from_cache
+  
+  def from_cache?
+    @from_cache ||= false
+  end
+end

data/lib/ca_ching/errors.rb

@@ -0,0 +1,3 @@
+module CaChing
+  class InvalidOptionError < StandardError; end
+end

data/lib/ca_ching/index.rb

@@ -0,0 +1,28 @@
+module CaChing
+  module Index
+    extend ActiveSupport::Concern
+    
+    VALID_OPTIONS = [:order, :ttl, :limit]
+    
+    module ClassMethods
+      def index(field_name, options={})
+        raise CaChing::InvalidOptionError unless options.keys.inject(true) { |flag, key| flag && CaChing::Index::VALID_OPTIONS.include?(key) } 
+        indexed_fields[field_name] = options
+      end
+      
+      def indexes?(field_name)
+        indexed_fields.has_key?(field_name)
+      end
+      
+      def indexed_fields
+        @_indexed_fields ||= {}
+      end
+    end
+    
+    module InstanceMethods
+      def indexed_fields
+        self.class.indexed_fields
+      end
+    end
+  end
+end

data/lib/ca_ching/query/abstract.rb

@@ -0,0 +1,106 @@
+module CaChing
+  module Query
+    class Abstract      
+      # Unceremoniously taken from cache-money
+      AND = /\s+AND\s+/i
+      OR  = /\s+OR\s+/i
+      TABLE_AND_COLUMN = /(?:(?:`|")?(\w+)(?:`|")?\.)?(?:`|")?(\w+)(?:`|")?/   # Matches: `users`.id, `users`.`id`, users.id, id
+      VALUE = /'?(\d+|\?|(?:(?:[^']|'')*))'?/                                  # Matches: 123, ?, '123', '12''3'
+      KEY_CMP_VALUE = /^\(?#{TABLE_AND_COLUMN}\s+(=|<|<=|>|>=)\s+#{VALUE}\)?$/              # Matches: KEY = VALUE, (KEY = VALUE)
+      ORDER = /^#{TABLE_AND_COLUMN}\s*(ASC|DESC)?$/i                           # Matches: COLUMN ASC, COLUMN DESC, COLUMN
+      
+      attr_accessor :klass
+      
+      def initialize(active_record_collection, options={})
+        self.tap do
+          @collection = active_record_collection
+          @sql = active_record_collection.to_sql
+          @klass = active_record_collection.klass
+        end
+      end
+      
+      def table_name
+        @collection.table_name
+      end
+      
+      def where
+        raise UncacheableConditionError unless cacheable?
+        
+        @collection.where_values.inject({}) do |hash, value|
+          if value.respond_to? :left
+            left = value.left.name.to_sym
+            right = value.right
+            if right == '?'
+              right = @collection.bind_values.find { |value| value.first.name == left.to_s }[1]
+            end
+            
+            hash[left] = ['=', right]
+          else
+            value.split(AND).each do |value|
+              match = KEY_CMP_VALUE.match(value).captures
+              left, comparator, right = match[1].to_sym, match[2], match[3]
+              
+              hash[left] = [comparator, right]
+            end
+          end
+          
+          @where = hash
+        end
+      end
+      
+      def order
+        order_values = @collection.order_values.map { |v| v.split(',').map { |v| v.strip } }.flatten
+        
+        order_values.inject({}) do |hash, value|
+          match = ORDER.match(value).captures
+          hash[match[1].to_sym] = match[2] == "ASC" ? :asc : :desc
+          
+          hash
+        end
+      end
+      
+      def limit
+        @collection.limit_value
+      end
+      
+      def offset
+        @collection.offset_value
+      end
+      
+      def calculation?
+        false
+      end
+      
+      # Formats the query to a key for the value store. Takes the form 
+      # table_name:encode(field1, [operator1, value1])&encode(field2, [operator2, value2])...
+      def to_key
+        "#{table_name}:#{where.map { |field, operator_and_value| encode(field, operator_and_value) } * "&" }"
+      end
+      
+      def primary_key?
+        @where ||= where
+        @where.keys.length == 1 && @where.keys.include?(@collection.primary_key.to_sym)
+      end
+      
+      private
+      # Encodes string to the form "field_name=value" where '=' can be any arbitrary
+      # operator. 
+      #
+      # @example
+      #   encode('name', ['=', 'Andrew']) # => "name='Andrew'"
+      # 
+      # @example
+      #   encode('age', ['>=', 21]) # => "age>=21"
+      def encode(field, operator_and_value)
+        operator, value = operator_and_value
+        "#{field}#{operator}\"#{value.to_s.gsub('"', '\"')}\""
+      end
+      
+      def cacheable?
+        !(@collection.to_sql =~ OR)
+      end
+    end
+    
+    class UncacheableConditionError < StandardError; end
+  end
+end

data/lib/ca_ching/query/calculation.rb

@@ -0,0 +1,6 @@
+module CaChing
+  module Query
+    class Calculation < Abstract
+    end
+  end
+end

data/lib/ca_ching/query/select.rb

@@ -0,0 +1,6 @@
+module CaChing
+  module Query
+    class Select < Abstract
+    end
+  end
+end