bulk_cache_fetcher 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 46f577da5b738735691d165c968cd243f2fff412
+  data.tar.gz: 187e82b0dd313cba27e24bb77d3323af8cc2f5b6
+SHA512:
+  metadata.gz: fa9a8f78afd53293b374db43a7a8631d4d21d0ec921752da726888ae455a3c33d46236352c5834cbe5b3d4c37806819ac465cb27a1ec9d7a857508bc0333d473
+  data.tar.gz: 92ec07ef649d39565508bbd98f94bb9c26f1a441e38f747d7a68133ce64bc29721703c9c65a8d19326d847a31d1de2c8f31372604d10faf4361bcd774bfa0f64

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,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in bulk_cache_fetcher.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Justin Weiss
+
+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,72 @@
+# BulkCacheFetcher
+
+Bulk Cache Fetcher fills the gap between [Russian doll caching](http://37signals.com/svn/posts/3113-how-key-based-cache-expiration-works) and the n+1 queries problem.
+
+Russian doll caching is really great for handling views and
+partials. When those partials show highly nested objects, though,
+cache misses are expensive. Usually, you'll either preload the entire
+object hierarchies in your controller (even on cache hits), or you'll
+accept the n+1 queries when you miss the cache.
+
+Bulk Cache Fetcher allows you to query the cache for a list of
+objects, and gives you the opportunity to fetch all of the cache
+misses at once, using whatever `:include`s you want.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'bulk_cache_fetcher'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install bulk_cache_fetcher
+
+## Usage
+
+Basic usage is pretty simple:
+
+```ruby
+cache_fetcher = BulkCacheFetcher.new(Rails.cache)
+cache_fetcher.fetch([1, 2, 3]) do |identifiers|
+  Post.includes(...).find(identifiers)
+end
+```
+
+it even returns them in the same order you return them in:
+
+```ruby
+results = cache_fetcher.fetch([2, 1, 3]) do |identifiers|
+  expensive_calculation(identifiers) # => returns [result 2, result 1, result 3]
+end
+
+results.first # => expensive_calculation([2])
+cache.read(1) # => expensive_calculation([1])
+```
+
+### Complex identifiers
+
+In a lot of cases, you'll have a cache key along with a little bit of
+extra data you'll need to find the record or perform a
+calculation. You can use the cache fetcher for this, with a hash
+instead of an array for the identifier list:
+
+```ruby
+cache_fetcher.fetch({:one => 1, :two => 2}) do |identifiers|
+  expensive_calculation(identifiers.values)
+end
+
+cache.read(:one) # => expensive_calculation([1])
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,16 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rdoc/task"
+
+task :default => :test
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/*_test.rb']
+end
+
+Rake::RDocTask.new do |rd|
+  rd.main = "README.md"
+  rd.rdoc_files.include("README.md", "lib/**/*.rb")
+  rd.rdoc_dir = 'doc'
+end

data/bulk_cache_fetcher.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'bulk_cache_fetcher'
+
+Gem::Specification.new do |spec|
+  spec.name          = "bulk_cache_fetcher"
+  spec.version       = BulkCacheFetcher::VERSION
+  spec.authors       = ["Justin Weiss"]
+  spec.email         = ["jweiss@avvo.com"]
+  spec.description   = %q{Fetches cache misses in bulk}
+  spec.summary       = %q{Bulk Cache Fetcher allows you to query the cache for a list of
+objects, and gives you the opportunity to fetch all of the cache
+misses at once, using whatever `:include`s you want.}
+  spec.homepage      = "https://github.com/justinweiss/bulk_cache_fetcher"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "minitest"
+end

data/lib/bulk_cache_fetcher.rb

@@ -0,0 +1,99 @@
+# Fetches many objects from a cache in order. In the event that some
+# objects can't be served from the cache, you will have the
+# opportunity to fetch them in bulk. This allows you to preload and
+# cache entire object hierarchies, which works particularly well with
+# Rails' nested caching while avoiding the n+1 queries problem in the
+# uncached case.
+class BulkCacheFetcher
+  VERSION = '0.0.1'
+
+  # Creates a new bulk cache fetcher, backed by +cache+. Cache must
+  # respond to the standard Rails cache API, described on
+  # http://guides.rubyonrails.org/caching_with_rails.html
+  def initialize(cache)
+    @cache = cache
+  end
+
+  # Returns a list of objects identified by
+  # <tt>object_identifiers</tt>. +fetch+ will try to find the objects
+  # from the cache first. Identifiers for objects that aren't in the
+  # cache will be passed as an ordered list to <tt>finder_block</tt>,
+  # where you can find the objects as you see fit. These objects
+  # should be returned in the same order as the identifiers that were
+  # passed into the block, because they'll be cached under their
+  # respective keys. The objects returned by +fetch+ will be returned
+  # in the same order as the <tt>object_identifiers</tt> passed in.
+  #
+  # +options+ will be passed along unmodified when caching newly found
+  # objects, so you can use it for things like setting cache
+  # expiration.
+  def fetch(object_identifiers, options = {}, &finder_block)
+    cached_objects, uncached_identifiers = partition(object_identifiers)
+    coalesce(cached_objects, find(uncached_identifiers, options, &finder_block))
+  end
+
+  private
+
+  # Partitions a list of identifiers into two lists. The first list
+  # contains all of the objects we were able to serve from the cache,
+  # while the second is a list of all of the identifiers for objects
+  # that weren't cached.
+  def partition(object_identifiers)
+    object_identifiers = normalize(object_identifiers)
+    cached_objects = []
+    uncached_identifiers = object_identifiers.dup
+
+    object_identifiers.each do |identifier|
+      cache_key = cache_key(identifier)
+      cached_object = @cache.read(cache_key)
+
+      uncached_identifiers.delete(cache_key) if cached_object
+      cached_objects << cached_object
+    end
+
+    [cached_objects, uncached_identifiers]
+  end
+
+  # Finds all of the objects identified by +identifiers+, using the
+  # +finder_block+. Will pass +options+ on to the cache.
+  def find(identifiers, options = {}, &finder_block)
+    unless identifiers.empty?
+      Array(finder_block.(identifiers)).tap do |objects|
+        verify_equal_key_and_value_counts!(identifiers, objects)
+        cache_all(identifiers, objects, options)
+      end
+    end
+  end
+
+  # Makes sure we have enough +identifiers+ to cache all of our
+  # +objects+, and vice-versa.
+  def verify_equal_key_and_value_counts!(identifiers, objects)
+    raise ArgumentError, "You are returning too many objects from your cache block!" if objects.length > identifiers.length
+    raise ArgumentError, "You are returning too few objects from your cache block!" if objects.length < identifiers.length
+  end
+
+  # Caches all +values+ under their respective +keys+.
+  def cache_all(keys, values, options = {})
+    keys.zip(values) { |k, v| @cache.write(cache_key(k), v, options) }
+  end
+
+  # With an array looking like <tt>[nil, 1, nil, 2]</tt>, replaces the
+  # nils with values taken from +found_objects+, in order.
+  def coalesce(array_with_nils, found_objects)
+    found_objects = Array(found_objects)
+    array_with_nils.map { |obj| obj ? obj : found_objects.shift }
+  end
+
+  # Returns the part of the identifier that we can use as the cache
+  # key. For simple identifiers, it's just the identifier, for
+  # identifiers with extra information attached, it's the first part
+  # of the identifier.
+  def cache_key(identifier)
+    Array(identifier).first
+  end
+
+  # Makes sure we can iterate over identifiers.
+  def normalize(identifiers)
+    identifiers.respond_to?(:each) ? identifiers : Array(identifiers)
+  end
+end

data/test/bulk_cache_fetcher_test.rb

@@ -0,0 +1,121 @@
+require 'test_helper'
+
+class InMemoryCache
+  attr_accessor :cache, :options
+
+  def initialize(options = {})
+    @cache = {}
+    @options = {}
+  end
+
+  def read(key); cache[key]; end
+  def write(key, value, opts = {}); options[key] = opts; cache[key] = value; end
+end
+
+class BulkCacheFetcherTest < Minitest::Unit::TestCase
+
+  def setup
+    @cache = InMemoryCache.new
+    @cache_fetcher = BulkCacheFetcher.new(@cache)
+  end
+
+  def test_returns_all_results_in_order
+    results = @cache_fetcher.fetch([5, 2, 3, 1, 4]) do |unfetched_objects|
+      unfetched_objects
+    end
+    assert_equal [5, 2, 3, 1, 4], results
+  end
+
+  def test_returns_without_calling_block_if_cached
+    counter = 0
+    @cache.write(1, 3)
+    @cache.write(2, 4)
+
+    results = @cache_fetcher.fetch([2, 1]) do |unfetched_objects|
+      counter += 1
+      unfetched_objects.map { |i| i += 2 }
+    end
+
+    assert_equal [4, 3], results
+    assert_equal 0, counter
+  end
+
+  def test_returns_some_from_cache_in_correct_order
+    counter = 0
+    @cache.write(1, 3)
+    @cache.write(2, 4)
+
+    results = @cache_fetcher.fetch([2, 3, 1, 4]) do |unfetched_objects|
+      counter += unfetched_objects.length
+      unfetched_objects.map { |i| i += 2 }
+    end
+
+    assert_equal [4, 5, 3, 6], results
+    assert_equal 2, counter
+  end
+
+  def test_uncached_records_stored_in_cache
+    @cache_fetcher.fetch([2, 3]) do |unfetched_objects|
+      unfetched_objects.map { |i| i += 2 }
+    end
+
+    assert_equal 4, @cache.read(2)
+    assert_equal 5, @cache.read(3)
+  end
+
+  def test_cache_key_with_associated_data
+    counter = 0
+    @cache.write(:one, 3)
+
+    identifiers = {three: 3, one: 1, two: 2}
+    results = @cache_fetcher.fetch(identifiers) do |unfetched_objects|
+      counter += unfetched_objects.length
+      unfetched_objects.values.map { |i| i += 2 }
+    end
+
+    assert_equal [5, 3, 4], results
+    assert_equal 2, counter
+  end
+
+  def test_succeeds_without_keys
+    results = @cache_fetcher.fetch([])
+    assert_equal [], results
+  end
+
+  def test_fails_with_too_many_keys
+    assert_raises ArgumentError do
+      @cache_fetcher.fetch([1, 2]) do |keys|
+        [1]
+      end
+    end
+  end
+
+  def test_fails_with_too_many_values
+    assert_raises ArgumentError do
+      @cache_fetcher.fetch([1, 2]) do |keys|
+        [1, 2, 3]
+      end
+    end
+  end
+
+  def test_can_take_cache_options
+    @cache_fetcher.fetch([1, 2], expires_in: 300) do |keys|
+      [1, 2]
+    end
+    assert_equal({expires_in: 300}, @cache.options[2])
+  end
+
+  def test_can_take_single_cache_key
+    @cache_fetcher.fetch(1) do |keys|
+      2
+    end
+    assert_equal(2, @cache.read(1))
+  end
+
+  def test_complex_key_caches_under_correct_key
+    @cache_fetcher.fetch({:one => 1}) do |keys|
+      2
+    end
+    assert_equal(2, @cache.read(:one))
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,2 @@
+require 'minitest/unit'
+require 'minitest/autorun'

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: bulk_cache_fetcher
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Justin Weiss
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-10-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Fetches cache misses in bulk
+email:
+- jweiss@avvo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bulk_cache_fetcher.gemspec
+- lib/bulk_cache_fetcher.rb
+- test/bulk_cache_fetcher_test.rb
+- test/test_helper.rb
+homepage: https://github.com/justinweiss/bulk_cache_fetcher
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.6
+signing_key: 
+specification_version: 4
+summary: Bulk Cache Fetcher allows you to query the cache for a list of objects, and
+  gives you the opportunity to fetch all of the cache misses at once, using whatever
+  `:include`s you want.
+test_files:
+- test/bulk_cache_fetcher_test.rb
+- test/test_helper.rb