Merge 63166c8 into 5deae1d

.gitignore

@@ -1,4 +1,5 @@
 Gemfile.lock
 .yardoc
+coverage
 doc
 pkg

CHANGELOG.md

@@ -1,3 +1,18 @@
+0.4.0 (TBD)
+-----------
+
+* Complete rewrite of Garner. See [UPGRADING](UPGRADING.md) for details on how to upgrade from Garner 0.3.3 and earlier versions - [@macreery](https://github.com/macreery).
+* Fixed #6: Garner fails if Mongoid not loaded yet - [@macreery](https://github.com/macreery).
+* Closed #12: Support arrays in `Garner.config.mongoid_identity_fields`- [@macreery](https://github.com/macreery).
+* Closed #13: Replace faulty multiple-identity logic- [@macreery](https://github.com/macreery).
+* Fixed #14: Disambiguate binding models by `:id` and `:slug`- [@macreery](https://github.com/macreery).
+* Fixed #15: Remove need for `cache_as` from subclassed Mongoid models - [@macreery](https://github.com/macreery).
+* Closed #23: Abstract all Grape mixins to be more generically Rack mixins - [@macreery](https://github.com/macreery).
+* Closed #24: Implement `garnered_find` method for `Mongoid::Document` classes - [@macreery](https://github.com/macreery).
+* Extracted `Binding`, `Context` and `Identity` as explicit classes from `ObjectIdentity`.
+* Added support for all ActiveModel-compliant ORMs.
+* Removed HTTP caching responsibilities from the library entirely.
+
 0.3.3 (6/10/2013)
 -----------------
 

Gemfile

@@ -8,14 +8,21 @@ gem "activesupport"
 group :development, :test do
   gem "bundler",    ">= 1.3.0"
   gem "grape",      ">= 0.2.0"
+  gem "sinatra"
   gem "rack-test"
   gem "rspec",      ">= 2.10.0"
   gem "jeweler"
   gem "mongoid",    ">= 3.0.0"
+  gem "mongoid_slug", ">= 1.0.0"
   gem "dalli"
+  gem "activerecord"
+  gem "sqlite3"
+  gem "timecop"
+  gem "coveralls"
 end
 
 group :development do
+  gem "pry"
   gem "yard"
   gem "redcarpet"
   gem "github-markup"

Rakefile

@@ -1,7 +1,7 @@
-require 'rubygems'
-require 'bundler'
+require "rubygems"
+require "bundler"
 
-require File.expand_path('../lib/garner/version', __FILE__)
+require File.expand_path("../lib/garner/version", __FILE__)
 
 begin
   Bundler.setup(:default, :development)
@@ -11,38 +11,31 @@ rescue Bundler::BundlerError => e
   exit e.status_code
 end
 
-require 'rake'
+require "rake"
 
-require 'jeweler'
+require "jeweler"
 Jeweler::Tasks.new do |gem|
   gem.name = "garner"
   gem.homepage = "http://github.com/artsy/garner"
   gem.license = "MIT"
-  gem.summary = "Garner is a set of Rack middleware and cache helpers that implement various strategies."
-  gem.description = "Garner is a set of Rack middleware and cache helpers that implement various strategies."
+  gem.summary = "Garner is a cache layer for Ruby and Rack applications, supporting model and instance binding and hierarchical invalidation."
+  gem.description = "Garner is a cache layer for Ruby and Rack applications, supporting model and instance binding and hierarchical invalidation."
   gem.email = "dblock@dblock.org"
   gem.version = Garner::VERSION
-  gem.authors = [ "Daniel Doubrovkine", "Frank Macreery" ]
-  gem.files = Dir.glob('lib/**/*')
+  gem.authors = ["Daniel Doubrovkine", "Frank Macreery"]
+  gem.files = Dir.glob("lib/**/*")
 end
 
 Jeweler::RubygemsDotOrgTasks.new
 
-require 'rspec/core'
-require 'rspec/core/rake_task'
+require "rspec/core"
+require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec) do |spec|
-  spec.pattern = FileList['spec/**/*_spec.rb']
+  spec.pattern = FileList["spec/**/*_spec.rb"]
 end
 
 task :default => :spec
 
-require 'yard'
-YARD_OPTS = ['-m', 'github-markup', '-M', 'redcarpet']
-DOC_FILES = ['lib/**/*.rb', '*.md']
-
-YARD::Rake::YardocTask.new(:doc) do |t|
-  t.files   = DOC_FILES
-  t.options = YARD_OPTS
-end
-
+require "yard"
+YARD::Rake::YardocTask.new(:doc)

UPGRADING.md

@@ -0,0 +1,118 @@
+Upgrading
+=========
+
+From <= 0.3.3 to 0.4.0
+----------------------
+
+### Binding Strategies
+
+The API for declaring cache bindings has changed completely. Instead of passing a hash to `cache`, you may now call `bind` on the `garner` method. `bind` takes an explicit object as its argument. So, for example:
+
+```ruby
+cache({ bind: [ User, current_user.id ] }) do
+  current_user.address
+end
+```
+
+now becomes:
+```ruby
+garner.bind(current_user) do
+  current_user.address
+end
+```
+
+To accommodate virtual object bindings (object references by class name and ID alone), Garner 0.4.0 provides an `identify` method as part of its Mongoid mixin. So,
+
+```ruby
+cache({ :bind => [Widget, params[:id]] }) { }
+```
+
+now becomes:
+
+```ruby
+garner.bind(Widget.identify(params[:id]))
+```
+
+Please consult the following table for translations from all documented pre-0.4.0 Garner bindings:
+
+| 0.3.3 Binding | 0.4.0 Binding |
+|---------------|---------------|
+| `bind: { klass: Widget, object: { id: params[:id] } }` | `bind(Widget.identify(id))` |
+| `bind: { klass: Widget }` | `bind(Widget)` |
+| `bind: [Widget]` | `bind(Widget)` |
+| `bind: [Widget, params[:id]]` | `bind(Widget.identify(params[:id]))` |
+| `bind: [User, { id: current_user.id }]` | `bind(current_user)` |
+| `bind: [[Widget], [User, { id: current_user.id }]]` | `bind(Widget).bind(current_user)` |
+
+### Grape Integration
+
+With Garner 0.4.0, a single Rack mixin provides all necessary integration for Garner and Grape. Change:
+
+```ruby
+class API < Grape::API
+  use Garner::Middleware::Cache::Bust
+  helpers Garner::Mixins::Grape::Cache
+end
+```
+
+to:
+
+```ruby
+class API < Grape::API
+  helpers Garner::Mixins::Rack
+end
+```
+
+### Mongoid Integration
+
+The API for Mongoid integration is unchanged. Please continue to include the Mongoid mixin by placing the following code in an initializer:
+
+```ruby
+require "garner"
+require "garner/mixins/mongoid"
+
+module Mongoid
+  module Document
+    include Garner::Mixins::Mongoid::Document
+  end
+end
+```
+
+### HTTP Caching
+
+Garner no longer provides HTTP caching, beginning with 0.4.0. We recommend using `Rack::ConditionalGet` in combination with `Rack::ETag` instead. These can be easily mixed into your existing Grape app like so:
+
+```ruby
+class API < Grape::API
+  use Rack::ConditionalGet
+  use Rack::ETag
+end
+```
+
+Moreover, `cache_or_304` is no longer implemented in Garner 0.4.0. All calls to `cache_or_304` should be replaced with `garner` blocks, just like any `cache` block. To give a specific example,
+
+```ruby
+cache_or_304({ bind: [ User, current_user.id ] }) do
+  current_user.address
+end
+```
+
+should become:
+
+```ruby
+garner.bind(current_user) do
+  current_user.address
+end
+```
+
+### Context Key Strategies
+
+You should no longer need to explicitly define key strategies. You can remove definitions like:
+
+```ruby
+Garner::Cache::ObjectIdentity::KEY_STRATEGIES = [
+  # ...
+]
+```
+
+from your initializers. If you have custom context key strategies, please refer to [request_get.rb](/artsy/garner/blob/master/lib/garner/strategies/context/key/request_get.rb) for an example of how to write new context key strategies. They can be added to `Garner.config.context_key_strategies`, or if only applicable to the Rack context, `Garner.config.rack_context_key_strategies`.

garner.gemspec

@@ -5,42 +5,42 @@
 
 Gem::Specification.new do |s|
   s.name = "garner"
-  s.version = "0.3.3"
+  s.version = "0.4.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Daniel Doubrovkine", "Frank Macreery"]
   s.date = "2013-06-10"
-  s.description = "Garner is a set of Rack middleware and cache helpers that implement various strategies."
+  s.description = "Garner is a cache layer for Ruby and Rack applications, supporting model and instance binding and hierarchical invalidation."
   s.email = "dblock@dblock.org"
   s.extra_rdoc_files = [
     "LICENSE.md",
     "README.md"
   ]
   s.files = [
     "lib/garner.rb",
-    "lib/garner/cache/object_identity.rb",
+    "lib/garner/cache.rb",
+    "lib/garner/cache/binding.rb",
+    "lib/garner/cache/context.rb",
+    "lib/garner/cache/identity.rb",
     "lib/garner/config.rb",
-    "lib/garner/middleware/base.rb",
-    "lib/garner/middleware/cache/bust.rb",
-    "lib/garner/mixins/grape_cache.rb",
-    "lib/garner/mixins/mongoid_document.rb",
-    "lib/garner/strategies/cache/expiration_strategy.rb",
-    "lib/garner/strategies/etags/grape_strategy.rb",
-    "lib/garner/strategies/etags/marshal_strategy.rb",
-    "lib/garner/strategies/keys/caller_strategy.rb",
-    "lib/garner/strategies/keys/jsonp_strategy.rb",
-    "lib/garner/strategies/keys/key_strategy.rb",
-    "lib/garner/strategies/keys/request_get_strategy.rb",
-    "lib/garner/strategies/keys/request_path_strategy.rb",
-    "lib/garner/strategies/keys/request_post_strategy.rb",
-    "lib/garner/strategies/keys/version_strategy.rb",
+    "lib/garner/mixins/mongoid.rb",
+    "lib/garner/mixins/mongoid/document.rb",
+    "lib/garner/mixins/mongoid/identity.rb",
+    "lib/garner/mixins/rack.rb",
+    "lib/garner/strategies/binding/invalidation/touch.rb",
+    "lib/garner/strategies/binding/key/cache_key.rb",
+    "lib/garner/strategies/context/key/caller.rb",
+    "lib/garner/strategies/context/key/jsonp.rb",
+    "lib/garner/strategies/context/key/request_get.rb",
+    "lib/garner/strategies/context/key/request_path.rb",
+    "lib/garner/strategies/context/key/request_post.rb",
     "lib/garner/version.rb"
   ]
   s.homepage = "http://github.com/artsy/garner"
   s.licenses = ["MIT"]
   s.require_paths = ["lib"]
   s.rubygems_version = "1.8.24"
-  s.summary = "Garner is a set of Rack middleware and cache helpers that implement various strategies."
+  s.summary = "Garner is a cache layer for Ruby and Rack applications, supporting model and instance binding and hierarchical invalidation."
 
   if s.respond_to? :specification_version then
     s.specification_version = 3
@@ -52,11 +52,17 @@ Gem::Specification.new do |s|
       s.add_runtime_dependency(%q<activesupport>, [">= 0"])
       s.add_development_dependency(%q<bundler>, [">= 1.3.0"])
       s.add_development_dependency(%q<grape>, [">= 0.2.0"])
+      s.add_development_dependency(%q<sinatra>, [">= 0"])
       s.add_development_dependency(%q<rack-test>, [">= 0"])
       s.add_development_dependency(%q<rspec>, [">= 2.10.0"])
       s.add_development_dependency(%q<jeweler>, [">= 0"])
       s.add_development_dependency(%q<mongoid>, [">= 3.0.0"])
+      s.add_development_dependency(%q<mongoid_slug>, [">= 1.0.0"])
       s.add_development_dependency(%q<dalli>, [">= 0"])
+      s.add_development_dependency(%q<activerecord>, [">= 0"])
+      s.add_development_dependency(%q<sqlite3>, [">= 0"])
+      s.add_development_dependency(%q<timecop>, [">= 0"])
+      s.add_development_dependency(%q<pry>, [">= 0"])
       s.add_development_dependency(%q<yard>, [">= 0"])
       s.add_development_dependency(%q<redcarpet>, [">= 0"])
       s.add_development_dependency(%q<github-markup>, [">= 0"])
@@ -67,11 +73,17 @@ Gem::Specification.new do |s|
       s.add_dependency(%q<activesupport>, [">= 0"])
       s.add_dependency(%q<bundler>, [">= 1.3.0"])
       s.add_dependency(%q<grape>, [">= 0.2.0"])
+      s.add_dependency(%q<sinatra>, [">= 0"])
       s.add_dependency(%q<rack-test>, [">= 0"])
       s.add_dependency(%q<rspec>, [">= 2.10.0"])
       s.add_dependency(%q<jeweler>, [">= 0"])
       s.add_dependency(%q<mongoid>, [">= 3.0.0"])
+      s.add_dependency(%q<mongoid_slug>, [">= 1.0.0"])
       s.add_dependency(%q<dalli>, [">= 0"])
+      s.add_dependency(%q<activerecord>, [">= 0"])
+      s.add_dependency(%q<sqlite3>, [">= 0"])
+      s.add_dependency(%q<timecop>, [">= 0"])
+      s.add_dependency(%q<pry>, [">= 0"])
       s.add_dependency(%q<yard>, [">= 0"])
       s.add_dependency(%q<redcarpet>, [">= 0"])
       s.add_dependency(%q<github-markup>, [">= 0"])
@@ -83,11 +95,17 @@ Gem::Specification.new do |s|
     s.add_dependency(%q<activesupport>, [">= 0"])
     s.add_dependency(%q<bundler>, [">= 1.3.0"])
     s.add_dependency(%q<grape>, [">= 0.2.0"])
+    s.add_dependency(%q<sinatra>, [">= 0"])
     s.add_dependency(%q<rack-test>, [">= 0"])
     s.add_dependency(%q<rspec>, [">= 2.10.0"])
     s.add_dependency(%q<jeweler>, [">= 0"])
     s.add_dependency(%q<mongoid>, [">= 3.0.0"])
+    s.add_dependency(%q<mongoid_slug>, [">= 1.0.0"])
     s.add_dependency(%q<dalli>, [">= 0"])
+    s.add_dependency(%q<activerecord>, [">= 0"])
+    s.add_dependency(%q<sqlite3>, [">= 0"])
+    s.add_dependency(%q<timecop>, [">= 0"])
+    s.add_dependency(%q<pry>, [">= 0"])
     s.add_dependency(%q<yard>, [">= 0"])
     s.add_dependency(%q<redcarpet>, [">= 0"])
     s.add_dependency(%q<github-markup>, [">= 0"])

lib/garner.rb

@@ -1,26 +1,25 @@
-require 'multi_json'
-require 'active_support'
-# garner
-require 'garner/version'
-require 'garner/config'
-# middleware
-require 'garner/middleware/base'
-require 'garner/middleware/cache/bust'
-# key strategies
-require 'garner/strategies/keys/version_strategy'
-require 'garner/strategies/keys/caller_strategy'
-require 'garner/strategies/keys/request_path_strategy'
-require 'garner/strategies/keys/request_get_strategy'
-require 'garner/strategies/keys/request_post_strategy'
-require 'garner/strategies/keys/key_strategy'
-require 'garner/strategies/keys/jsonp_strategy'
-# etag strategies
-require 'garner/strategies/etags/grape_strategy'
-require 'garner/strategies/etags/marshal_strategy'
-# cache option strategies
-require 'garner/strategies/cache/expiration_strategy'
-# caches
-require 'garner/cache/object_identity'
-# mixins
-require 'garner/mixins/grape_cache' if defined?(Grape)
-require 'garner/mixins/mongoid_document' if defined?(Mongoid)
+require "multi_json"
+require "active_support"
+
+# Garner core
+require "garner/version"
+require "garner/config"
+
+# Key strategies
+require "garner/strategies/context/key/caller"
+require "garner/strategies/context/key/request_path"
+require "garner/strategies/context/key/request_get"
+require "garner/strategies/context/key/request_post"
+require "garner/strategies/context/key/jsonp"
+
+# Binding strategies
+require "garner/strategies/binding/key/cache_key"
+
+# Invalidation strategies
+require "garner/strategies/binding/invalidation/touch"
+
+# Cache
+require "garner/cache"
+require "garner/cache/identity"
+require "garner/cache/context"
+require "garner/cache/binding"