record-cache 0.1.0

data/lib/record_cache/statistics.rb

@@ -0,0 +1,82 @@
+module RecordCache
+  
+  # Collect cache hit/miss statistics for each cache strategy
+  module Statistics
+    
+    class << self
+
+      # returns +true+ if statistics need to be collected
+      def active?
+        !!@active
+      end
+
+      # start statistics collection
+      def start
+        @active = true
+      end
+
+      # stop statistics collection
+      def stop
+        @active = false
+      end
+
+      # toggle statistics collection
+      def toggle
+        @active = !@active
+      end
+
+      # reset all statistics
+      def reset!(base = nil)
+        stats = find(base).values
+        stats = stats.map(&:values).flatten unless base # flatten hash of hashes in case base was nil
+        stats.each{ |s| s.reset! }
+      end
+
+      # Retrieve the statistics for the given base and strategy_id
+      # Returns a hash {<stategy_id> => <statistics} for a model if no strategy is provided
+      # Returns a hash of hashes { <model_name> => {<stategy_id> => <statistics} } if no parameter is provided
+      def find(base = nil, strategy_id = nil)
+        stats = (@stats ||= {})
+        stats = (stats[base.name] ||= {}) if base
+        stats = (stats[strategy_id] ||= Counter.new) if strategy_id
+        stats
+      end
+    end
+
+    class Counter
+      attr_accessor :calls, :hits, :misses
+
+      def initialize
+        reset!
+      end
+
+      # add hit statatistics for the given cache strategy
+      # @param queried: nr of ids queried
+      # @param found: nr of records found in the cache
+      def add(queried, found)
+        @calls += 1
+        @hits += found
+        @misses += (queried - found)
+      end
+
+      def reset!
+        @hits = 0
+        @misses = 0
+        @calls = 0
+      end
+
+      def active?
+        RecordCache::Statistics.active?
+      end
+
+      def percentage
+        return 0.0 if @hits == 0
+        (@hits.to_f / (@hits + @misses)) * 100
+      end
+
+      def inspect
+        "#{percentage}% (#{@hits}/#{@hits + @misses})"
+      end
+    end
+  end
+end

data/lib/record_cache/strategy/base.rb

@@ -0,0 +1,154 @@
+module RecordCache
+  module Strategy
+    class Base
+      CLASS_KEY = :c
+      ATTRIBUTES_KEY = :a
+
+      def initialize(base, strategy_id, record_store, options)
+        @base = base
+        @strategy_id = strategy_id
+        @record_store = record_store
+        @cache_key_prefix = "rc/#{options[:key] || @base.name}/".freeze
+      end
+
+      # Fetch all records and sort and filter locally
+      def fetch(query)
+        records = fetch_records(query)
+        filter!(records, query.wheres) if query.wheres.size > 0
+        sort!(records, query.sort_orders) if query.sorted?
+        records
+      end
+
+      # Handle create/update/destroy (use record.previous_changes to find the old values in case of an update)
+      def record_change(record, action)
+        raise NotImplementedError
+      end
+
+      # Can the cache retrieve the records based on this query?
+      def cacheable?(query)
+        raise NotImplementedError
+      end
+
+      # Handle invalidation call
+      def invalidate(id)
+        raise NotImplementedError
+      end
+
+      protected
+  
+      def fetch_records(query)
+        raise NotImplementedError
+      end
+  
+      # ------------------------- Utility methods ----------------------------
+  
+      # retrieve the version store (unique store for the whole application)
+      def version_store
+        RecordCache::Base.version_store
+      end
+      
+      # retrieve the record store (store for records for this cache strategy)
+      def record_store
+        @record_store
+      end
+      
+      # find the statistics for this cache strategy
+      def statistics
+        @statistics ||= RecordCache::Statistics.find(@base, @strategy_id)
+      end
+
+      # retrieve the cache key for the given id, e.g. rc/person/14
+      def cache_key(id)
+        "#{@cache_key_prefix}#{id}".freeze
+      end
+  
+      # retrieve the versioned record key, e.g. rc/person/14v1
+      def versioned_key(cache_key, version)
+        "#{cache_key}v#{version.to_s}".freeze
+      end
+  
+      # serialize one record before adding it to the cache
+      # creates a shallow clone with a version and without associations
+      def serialize(record)
+        {CLASS_KEY => record.class.name,
+         ATTRIBUTES_KEY => record.instance_variable_get(:@attributes)}.freeze
+      end
+  
+      # deserialize a cached record
+      def deserialize(serialized)
+        record = serialized[CLASS_KEY].constantize.new
+        attributes = serialized[ATTRIBUTES_KEY]
+        record.instance_variable_set(:@attributes, Hash[attributes])
+        record.instance_variable_set(:@new_record, false)
+        record.instance_variable_set(:@changed_attributes, {})
+        record.instance_variable_set(:@previously_changed, {})
+        record
+      end
+
+      private
+
+      # Filter the cached records in memory
+      # only simple x = y or x IN (a,b,c) can be handled 
+      def filter!(records, wheres)
+        wheres.each_pair do |attr, value|
+          if value.is_a?(Array)
+            records.reject! { |record| !value.include?(record.send(attr)) }
+          else
+            records.reject! { |record| record.send(attr) != value }
+          end
+        end
+      end
+  
+      # Sort the cached records in memory
+      def sort!(records, sort_orders)
+        records.sort!(&sort_proc(sort_orders))
+        Collator.clear
+        records
+      end
+  
+      # Retrieve the Proc based on the order by attributes
+      # Note: Case insensitive sorting with collation is used for Strings
+      def sort_proc(sort_orders)
+        # [['(COLLATER.collate(x.name) || NIL_COMES_FIRST)', 'COLLATER.collate(y.name)'], ['(y.updated_at || NIL_COMES_FIRST)', 'x.updated_at']]
+        sort = sort_orders.map do |attr, asc|
+          lr = ["x.", "y."]
+          lr.reverse! unless asc
+          lr.each{ |s| s << attr }
+          lr.each{ |s| s.replace("Collator.collate(#{s})") } if @base.columns_hash[attr].type == :string
+          lr[0].replace("(#{lr[0]} || NIL_COMES_FIRST)")
+          lr
+        end
+        # ['[(COLLATER.collate(x.name) || NIL_COMES_FIRST), (y.updated_at || NIL_COMES_FIRST)]', '[COLLATER.collate(y.name), x.updated_at]']
+        sort = sort.transpose.map{|s| s.size == 1 ? s.first : "[#{s.join(',')}]"}
+        # Proc.new{ |x,y| { ([(COLLATER.collate(x.name) || NIL_COMES_FIRST), (y.updated_at || NIL_COMES_FIRST)] <=> [COLLATER.collate(y.name), x.updated_at]) || 1 }
+        eval("Proc.new{ |x,y| (#{sort[0]} <=> #{sort[1]}) || 1 }")
+      end
+  
+      # If +x.nil?+ this class will return -1 for +x <=> y+
+      NIL_COMES_FIRST = ((class NilComesFirst; def <=>(y); -1; end; end); NilComesFirst.new)
+  
+      # StringCollator uses the Rails transliterate method for collation
+      module Collator
+        @collated = []
+  
+        def self.clear
+          @collated.each { |string| string.send(:remove_instance_variable, :@rc_collated) }
+          @collated.clear
+        end
+  
+        def self.collate(string)
+          collated = string.instance_variable_get(:@rc_collated)
+          return collated if collated
+          normalized = ActiveSupport::Multibyte::Unicode.normalize(ActiveSupport::Multibyte::Unicode.tidy_bytes(string), :c).mb_chars
+          collated = I18n.transliterate(normalized).downcase.mb_chars
+          # transliterate will replace ignored/unknown chars with ? the following line replaces ? with the original character
+          collated.chars.each_with_index{ |c, i| collated[i] = normalized[i] if c == '?' } if collated.index('?')
+          # puts "collation: #{string} => #{collated.to_s}"
+          string.instance_variable_set(:@rc_collated, collated)
+          @collated << string
+          collated
+        end
+      end
+    end
+  end
+end

data/lib/record_cache/strategy/id_cache.rb

@@ -0,0 +1,93 @@
+module RecordCache
+  module Strategy
+    class IdCache < Base
+  
+      # Can the cache retrieve the records based on this query?
+      def cacheable?(query)
+        ids = query.where_ids(:id)
+        ids && (query.limit.nil? || (query.limit == 1 && ids.size == 1))
+      end
+  
+      # Update the version store and the record store
+      def record_change(record, action)
+        key = cache_key(record.id)
+        if action == :destroy
+          version_store.delete(key)
+        else
+          # update the version store and add the record to the cache
+          new_version = version_store.increment(key)
+          record_store.write(versioned_key(key, new_version), serialize(record))
+        end
+      end
+
+      # Handle invalidation call
+      def invalidate(id)
+        version_store.delete(cache_key(id))
+      end
+  
+      protected
+  
+      # retrieve the record(s) with the given id(s) as an array
+      def fetch_records(query)
+        ids = query.where_ids(:id)
+        query.wheres.delete(:id) # make sure CacheCase.filter! does not see this where anymore
+        id_to_key_map = ids.inject({}){|h,id| h[id] = cache_key(id); h }
+        # retrieve the current version of the records
+        current_versions = version_store.current_multi(id_to_key_map)
+        # get the keys for the records for which a current version was found
+        id_to_version_key_map = Hash[id_to_key_map.map{ |id, key| current_versions[id] ? [id, versioned_key(key, current_versions[id])] : nil }]
+        # retrieve the records from the cache
+        records = id_to_version_key_map.size > 0 ? from_cache(id_to_version_key_map) : []
+        # query the records with missing ids
+        id_to_key_map.except!(*records.map(&:id))
+        # logging (only in debug mode!) and statistics
+        log_id_cache_hit(ids, id_to_key_map.keys) if RecordCache::Base.logger.debug?
+        statistics.add(ids.size, records.size) if statistics.active?
+        # retrieve records from DB in case there are some missing ids
+        records += from_db(id_to_key_map, id_to_version_key_map) if id_to_key_map.size > 0
+        # return the array
+        records
+      end
+  
+      private
+  
+      # ---------------------------- Querying ------------------------------------
+
+      # retrieve the records from the cache with the given keys
+      def from_cache(id_to_versioned_key_map)
+        records = record_store.read_multi(*(id_to_versioned_key_map.values)).values.compact
+        records.map{ |record| deserialize(record) }
+      end
+    
+      # retrieve the records with the given ids from the database
+      def from_db(id_to_key_map, id_to_version_key_map)
+        RecordCache::Base.without_record_cache do
+          # retrieve the records from the database
+          records = @base.where(:id => id_to_key_map.keys).to_a
+          records.each do |record|
+            versioned_key = id_to_version_key_map[record.id]
+            unless versioned_key
+              # renew the key in the version store in case it was missing
+              key = id_to_key_map[record.id]
+              versioned_key = versioned_key(key, version_store.renew(key))
+            end
+            # store the record based on the versioned key
+            record_store.write(versioned_key, serialize(record))
+          end
+          records
+        end
+      end
+  
+      # ------------------------- Utility methods ----------------------------
+  
+      # log cache hit/miss to debug log
+      def log_id_cache_hit(ids, missing_ids)
+        hit = missing_ids.empty? ? "hit" : ids.size == missing_ids.size ? "miss" : "partial hit"
+        missing = missing_ids.empty? || ids.size == missing_ids.size ? "" : ": missing #{missing_ids.inspect}"
+        msg = "IdCache #{hit} for ids #{ids.size == 1 ? ids.first : ids.inspect}#{missing}"
+        RecordCache::Base.logger.debug(msg)
+      end
+
+    end
+  end
+end

data/lib/record_cache/strategy/index_cache.rb

@@ -0,0 +1,122 @@
+module RecordCache
+  module Strategy
+    class IndexCache < Base
+  
+      def initialize(base, strategy_id, record_store, options)
+        super
+        @index = options[:index]
+        # check the index
+        type = @base.columns_hash[@index.to_s].try(:type)
+        raise "No column found for index '#{@index}' on #{@base.name}." unless type
+        raise "Incorrect type (expected integer, found #{type}) for index '#{@index}' on #{@base.name}." unless type == :integer
+        @index_cache_key_prefix = cache_key(@index) # "/rc/<model>/<index>"
+      end
+
+      # Can the cache retrieve the records based on this query?
+      def cacheable?(query)
+        query.where_id(@index) && query.limit.nil?
+      end
+
+      # Handle create/update/destroy (use record.previous_changes to find the old values in case of an update)
+      def record_change(record, action)
+        if action == :destroy
+          remove_from_index(record.send(@index), record.id)
+        elsif action == :create
+          add_to_index(record.send(@index), record.id)
+        else
+          index_change = record.previous_changes[@index.to_s]
+          return unless index_change
+          remove_from_index(index_change[0], record.id)
+          add_to_index(index_change[1], record.id)
+        end
+      end
+
+      # Explicitly invalidate the record cache for the given value
+      def invalidate(value)
+        version_store.increment(index_cache_key(value))
+      end
+
+      protected
+
+      # retrieve the record(s) based on the given query
+      def fetch_records(query)
+        value = query.where_id(@index)
+        # make sure CacheCase.filter! does not see this where clause anymore
+        query.wheres.delete(@index)
+        # retrieve the cache key for this index and value
+        key = index_cache_key(value)
+        # retrieve the current version of the ids list
+        current_version = version_store.current(key)
+        # create the versioned key, renew the version in case it was missing in the version store
+        versioned_key = versioned_key(key, current_version || version_store.renew(key))
+        # retrieve the ids from the local cache based on the current version from the version store
+        ids = current_version ? fetch_ids_from_cache(versioned_key) : nil
+        # logging (only in debug mode!) and statistics
+        log_cache_hit(versioned_key, ids) if RecordCache::Base.logger.debug?
+        statistics.add(1, ids ? 1 : 0) if statistics.active?
+        # retrieve the ids from the DB if the result was not fresh
+        ids = fetch_ids_from_db(versioned_key, value) unless ids
+        # use the IdCache to retrieve the records based on the ids
+        @base.record_cache[:id].send(:fetch_records, ::RecordCache::Query.new({:id => ids}))
+      end
+  
+      private
+  
+      # ---------------------------- Querying ------------------------------------
+  
+      # key to retrieve the ids for a given value
+      def index_cache_key(value)
+        "#{@index_cache_key_prefix}=#{value}"
+      end
+  
+      # Retrieve the ids from the local cache
+      def fetch_ids_from_cache(versioned_key)
+        record_store.read(versioned_key)
+      end
+  
+      # retrieve the ids from the database and update the local cache
+      def fetch_ids_from_db(versioned_key, value)
+        RecordCache::Base.without_record_cache do
+          # go straight to SQL result for optimal performance
+          sql = @base.select('id').where(@index => value).to_sql
+          ids = []; @base.connection.execute(sql).each{ |row| ids << (row.is_a?(Hash) ? row['id'] : row.first).to_i }
+          record_store.write(versioned_key, ids)
+          ids
+        end
+      end
+  
+      # ---------------------------- Local Record Changes ---------------------------------
+  
+      # add one record(id) to the index with the given value
+      def add_to_index(value, id)
+        increment_version(value.to_i) { |ids| ids << id } if value
+      end
+
+      # remove one record(id) from the index with the given value
+      def remove_from_index(value, id)
+        increment_version(value.to_i) { |ids| ids.delete(id) } if value
+      end
+
+      # increment the version store and update the local store
+      def increment_version(value, &block)
+        # retrieve local version and increment version store
+        key = index_cache_key(value)
+        version = version_store.increment(key)
+        # try to update the ids list based on the last version
+        ids = fetch_ids_from_cache(versioned_key(key, version - 1))
+        if ids
+          ids = Array.new(ids)
+          yield ids
+          record_store.write(versioned_key(key, version), ids)
+        end
+      end
+  
+      # ------------------------- Utility methods ----------------------------
+  
+      # log cache hit/miss to debug log
+      def log_cache_hit(key, ids)
+        RecordCache::Base.logger.debug("IndexCache #{ids ? 'hit' : 'miss'} for #{key}: found #{ids ? ids.size : 'no'} ids")
+      end
+    end
+  end
+end

data/lib/record_cache/strategy/request_cache.rb

@@ -0,0 +1,49 @@
+# Remembers the queries performed during a single Request.
+# If the same query is requested again the result is provided straight from local memory.
+#
+# Records are invalidated per model-klass, when any record is created, updated or destroyed.
+module RecordCache
+  module Strategy
+    
+    class RequestCache < Base
+      @@request_store = {}
+
+      # call before each request: in application_controller.rb
+      # before_filter { |c| RecordCache::Strategy::RequestCache.clear }
+      def self.clear
+        @@request_store.clear
+      end
+
+      # Handle record change
+      def record_change(record, action)
+        @@request_store.delete(@base.name)
+      end
+
+      # Handle invalidation call
+      def invalidate(value)
+        @@request_store.delete(@base.name)
+      end
+
+      # return the records from the request cache, execute block in case
+      # this is the first time this query is performed during this request
+      def fetch(query, &block)
+        klass_store = (@@request_store[@base.name] ||= {})
+        key = query.cache_key
+        # logging (only in debug mode!) and statistics
+        log_cache_hit(key, klass_store.key?(key)) if RecordCache::Base.logger.debug?
+        statistics.add(1, klass_store.key?(key) ? 1 : 0) if statistics.active?
+        klass_store[key] ||= yield
+      end
+
+      private
+
+      # ------------------------- Utility methods ----------------------------
+  
+      # log cache hit/miss to debug log
+      def log_cache_hit(key, hit)
+        RecordCache::Base.logger.debug("RequestCache #{hit ? 'hit' : 'miss'} for #{key}")
+      end
+
+    end
+  end
+end

data/lib/record_cache/test/resettable_version_store.rb

@@ -0,0 +1,49 @@
+# Make sure the version store can be reset to it's starting point after each test
+# Usage:
+#   require 'record_cache/test/resettable_version_store'
+#   after(:each) { RecordCache::Base.version_store.reset! }
+module RecordCache
+  module Test
+
+    module ResettableVersionStore
+
+      def self.included(base)
+        base.extend ClassMethods
+        base.send(:include, InstanceMethods)
+        base.instance_eval do
+          alias_method_chain :increment, :reset
+          alias_method_chain :renew, :reset
+        end
+      end
+
+      module ClassMethods
+      end
+
+      module InstanceMethods
+
+        def increment_with_reset(key)
+          updated_version_keys << key
+          increment_without_reset(key)
+        end
+        
+        def renew_with_reset(key)
+          updated_version_keys << key
+          renew_without_reset(key)
+        end
+
+        def reset!
+          RecordCache::Strategy::RequestCache.clear
+          updated_version_keys.each { |key| delete(key) }
+          updated_version_keys.clear
+        end
+
+        def updated_version_keys
+          @updated_version_keys ||= []
+        end
+      end
+    end
+
+  end
+end
+
+RecordCache::VersionStore.send(:include, RecordCache::Test::ResettableVersionStore)

data/lib/record_cache/version.rb

@@ -0,0 +1,5 @@
+module RecordCache # :nodoc:
+  module Version # :nodoc:
+    STRING = '0.1.0'
+  end
+end

data/lib/record_cache/version_store.rb

@@ -0,0 +1,54 @@
+module RecordCache
+  class VersionStore
+    attr_accessor :store
+
+    def initialize(store)
+      raise "Must be an ActiveSupport::Cache::Store" unless store.is_a?(ActiveSupport::Cache::Store)
+      @store = store
+    end
+
+    # Retrieve the current versions for the given key
+    # @return nil in case the key is not known in the version store
+    def current(key)
+      @store.read(key)
+    end
+
+    # Retrieve the current versions for the given keys
+    # @param id_key_map is a map with {id => cache_key}
+    # @return a map with {id => current_version}
+    # version nil for all keys unknown to the version store
+    def current_multi(id_key_map)
+      current_versions = @store.read_multi(*(id_key_map.values))
+      Hash[id_key_map.map{ |id, key| [id, current_versions[key]] }]
+    end
+
+    # In case the version store did not have a key anymore, call this methods
+    # to reset the key with a unique new key
+    def renew(key)
+      new_version = (Time.current.to_f * 10000).to_i
+      @store.write(key, new_version)
+      RecordCache::Base.logger.debug("Version Store: renew #{key}: nil => #{new_version}") if RecordCache::Base.logger.debug?
+      new_version
+    end
+
+    # Increment the current version for the given key, in case of record updates
+    def increment(key)
+      version = @store.increment(key, 1)
+      # renew key in case the version store already purged the key
+      if version.nil? || version == 1
+        version = renew(key)
+      else
+        RecordCache::Base.logger.debug("Version Store: incremented #{key}: #{version - 1} => #{version}") if RecordCache::Base.logger.debug?
+      end
+      version
+    end
+    
+    # Delete key from the version store, in case the record(s) are destroyed
+    def delete(key)
+      deleted = @store.delete(key)
+      RecordCache::Base.logger.debug("Version Store: deleted #{key}") if RecordCache::Base.logger.debug?
+      deleted
+    end
+
+  end
+end

data/lib/record_cache.rb

@@ -0,0 +1,11 @@
+# Record Cache shared files
+["query", "version_store", "multi_read",
+ "strategy/base", "strategy/id_cache", "strategy/index_cache", "strategy/request_cache",
+ "statistics", "dispatcher", "base"].each do |file|
+  require File.dirname(__FILE__) + "/record_cache/#{file}.rb"
+end
+
+# Support for Active Record
+require 'active_record'
+ActiveRecord::Base.send(:include, RecordCache::Base)
+require File.dirname(__FILE__) + "/record_cache/active_record.rb"

data/spec/db/database.yml

@@ -0,0 +1,6 @@
+sqlite3:
+  adapter: sqlite3
+  database: ":memory:"
+  encoding: utf8
+  charset: utf8
+  timeout: 5000

data/spec/db/schema.rb

@@ -0,0 +1,42 @@
+ActiveRecord::Schema.define :version => 0 do
+
+  create_table :people, :force => true do |t|
+    t.integer :id
+    t.string  :name
+    t.date    :birthday
+    t.float   :height
+  end
+
+  create_table :stores, :force => true do |t|
+    t.integer :id
+    t.string  :name
+    t.integer :owner_id
+  end
+
+  create_table :people_stores, :id => false, :force => true do |t|
+    t.integer :person_id
+    t.string  :store_id
+  end
+
+  create_table :apples, :force => true do |t|
+    t.integer :id
+    t.string  :name
+    t.integer :store_id
+    t.integer :person_id
+  end
+
+  create_table :bananas, :force => true do |t|
+    t.integer :id
+    t.string  :name
+    t.integer :store_id
+    t.integer :person_id
+  end
+
+  create_table :pears, :force => true do |t|
+    t.integer :id
+    t.string  :name
+    t.integer :store_id
+    t.integer :person_id
+  end
+
+end