garner 0.4.0 → 0.4.1

data/README.md

@@ -5,11 +5,10 @@ Garner is a cache layer for Ruby and Rack applications, supporting model and ins
 
 If you're not familiar with HTTP caching, ETags and If-Modified-Since, watch us introduce Garner in [From Zero to API Cache in 10 Minutes](http://www.confreaks.com/videos/986-goruco2012-from-zero-to-api-cache-w-grape-mongodb-in-10-minutes) at GoRuCo 2012.
 
-Stable Release
---------------
+Upgrading
+---------
 
-You're reading the documentation for the next release of Garner, which should be 0.4.0. See [UPGRADING](UPGRADING.md).
-The current stable release is [0.3.3](https://github.com/artsy/garner/blob/v0.3.3/README.md).
+The current stable release of Garner is 0.4.1, and contains many breaking changes from the previous stable release, 0.3.3. For a summary of important changes, see [UPGRADING](UPGRADING.md).
 
 Usage
 -----
@@ -111,7 +110,17 @@ Order.find(3).invalidate_garner_caches
 
 ### ActiveRecord
 
-Garner provides rudimentary support for `ActiveRecord`. No mixins are required to bind to `ActiveRecord` objects. Just call `garner.bind(model)`, where `model` is an `ActiveRecord` object.
+Garner provides rudimentary support for `ActiveRecord`. To use ActiveRecord models for Garner bindings, use `Garner::Mixins::ActiveRecord::Base`. You can set it up in an initializer:
+
+``` ruby
+require "garner/mixins/active_record"
+
+module ActiveRecord
+  class Base
+    include Garner::Mixins::ActiveRecord::Base
+  end
+end
+```
 
 
 Under The Hood: Bindings
@@ -133,7 +142,7 @@ end
 
 Binding keys are computed via pluggable strategies, as are the rules for invalidating caches when a binding changes. By default, Garner uses `Garner::Strategies::Binding::Key::SafeCacheKey` to compute binding keys: this uses `cache_key` if defined on an object; otherwise it always bypasses cache. Similarly, Garner uses `Garner::Strategies::Binding::Invalidation::Touch` as its default invalidation strategy. This will call `:touch` on a document if it is defined; otherwise it will take no action.
 
-Additional binding and invalidation strategies can be written. To use them, set `Garner.config.binding_key_strategy` and `Garner.config.binding_invalidation_strategy`. Alternatively, for Mongoid-specific strategies, set `Garner.config.mongoid_binding_key_strategy` and `Garner.config.mongoid_binding_invalidation_strategy`.
+Additional binding and invalidation strategies can be written. To use them, set `Garner.config.binding_key_strategy` and `Garner.config.binding_invalidation_strategy`.
 
 
 Under The Hood: Cache Context Keys
@@ -185,8 +194,6 @@ The full list of  `Garner.config` attributes is:
 ```
 * `:binding_key_strategy`: Binding key strategy. Defaults to `Garner::Strategies::Binding::Key::SafeCacheKey`.
 * `:binding_invalidation_strategy`: Binding invalidation strategy. Defaults to `Garner::Strategies::Binding::Invalidation::Touch`.
-* `:mongoid_binding_key_strategy`: Mongoid-specific binding key strategy. Defaults to `Garner::Strategies::Binding::Key::SafeCacheKey`.
-* `:mongoid_binding_invalidation_strategy`: Mongoid-specific binding invalidation strategy. Defaults to `Garner::Strategies::Binding::Invalidation::Touch`.
 * `:mongoid_identity_fields`: Identity fields considered legal for the `identity` method. Defaults to `[:_id]`.
 * `:caller_root`: Root path of application, to be stripped out of value strings generated by the `Caller` context key strategy. Defaults to `Rails.root` if in a Rails environment; otherwise to the nearest ancestor directory containing a Gemfile.
 

data/lib/garner.rb

@@ -17,10 +17,12 @@ require "garner/strategies/context/key/jsonp"
 require "garner/strategies/binding/key/base"
 require "garner/strategies/binding/key/cache_key"
 require "garner/strategies/binding/key/safe_cache_key"
+require "garner/strategies/binding/key/binding_index"
 
 # Invalidation strategies
 require "garner/strategies/binding/invalidation/base"
 require "garner/strategies/binding/invalidation/touch"
+require "garner/strategies/binding/invalidation/binding_index"
 
 # Cache
 require "garner/cache"

data/lib/garner/cache/binding.rb

@@ -5,6 +5,9 @@ Garner.config.option(:binding_key_strategy, {
 Garner.config.option(:binding_invalidation_strategy, {
   :default => Garner::Strategies::Binding::Invalidation::Touch
 })
+Garner.config.option(:mongoid_identity_fields, {
+  :default => [:_id]
+})
 
 module Garner
   module Cache
@@ -18,6 +21,8 @@ module Garner
       end
 
       # Apply the cache key strategy to this binding.
+      #
+      # @return [String] A cache key string.
       def garner_cache_key
         key_strategy.apply(self)
       end
@@ -30,8 +35,11 @@ module Garner
       end
 
       # Apply the invalidation strategy to this binding.
+      #
+      # @return [Boolean] Returns true on success.
       def invalidate_garner_caches
         invalidation_strategy.apply(self)
+        true
       end
 
       protected

data/lib/garner/cache/context.rb

@@ -2,6 +2,14 @@
 Garner.config.option(:context_key_strategies, {
   :default => [Garner::Strategies::Context::Key::Caller]
 })
+Garner.config.option(:rack_context_key_strategies, {
+  :default => [
+    Garner::Strategies::Context::Key::Caller,
+    Garner::Strategies::Context::Key::RequestGet,
+    Garner::Strategies::Context::Key::RequestPost,
+    Garner::Strategies::Context::Key::RequestPath
+  ]
+})
 
 module Garner
   module Cache

data/lib/garner/mixins/active_record.rb

@@ -0,0 +1,4 @@
+require "garner"
+require "active_record"
+
+require "garner/mixins/active_record/base"

data/lib/garner/mixins/active_record/base.rb

@@ -0,0 +1,17 @@
+require "garner"
+require "active_record"
+
+module Garner
+  module Mixins
+    module ActiveRecord
+      module Base
+        extend ActiveSupport::Concern
+        include Garner::Cache::Binding
+
+        included do
+          extend Garner::Cache::Binding
+        end
+      end
+    end
+  end
+end

data/lib/garner/mixins/mongoid.rb

@@ -1,4 +1,5 @@
 require "garner"
+require "mongoid"
 
 require "garner/mixins/mongoid/document"
 require "garner/mixins/mongoid/identity"

data/lib/garner/mixins/mongoid/document.rb

@@ -1,12 +1,3 @@
-# Set up Garner configuration parameters
-Garner.config.option(:mongoid_binding_key_strategy, {
-  :default => Garner.config.binding_key_strategy
-})
-
-Garner.config.option(:mongoid_binding_invalidation_strategy, {
-  :default => Garner.config.binding_invalidation_strategy
-})
-
 module Garner
   module Mixins
     module Mongoid
@@ -14,45 +5,49 @@ module Garner
         extend ActiveSupport::Concern
         include Garner::Cache::Binding
 
-        def key_strategy
-          Garner.config.mongoid_binding_key_strategy
+        def proxied_classes
+          self.class.mongoid_superclasses
         end
 
-        def invalidation_strategy
-          Garner.config.mongoid_binding_invalidation_strategy
+        def identity_string
+          "#{self.class.name}/id=#{id}"
         end
 
         included do
           extend Garner::Cache::Binding
 
-          def self.cache_key
-            _latest_by_updated_at.try(:cache_key)
-          end
-
-          def self.touch
-            _latest_by_updated_at.try(:touch)
-          end
-
-          def self.updated_at
-            _latest_by_updated_at.try(:updated_at)
-          end
-
-          def self.key_strategy
-            Garner.config.mongoid_binding_key_strategy
+          # Return an array of this class and all Mongoid superclasses.
+          #
+          # @return [Array] An array of classes.
+          def self.mongoid_superclasses
+            if superclass.include?(Mongoid::Document)
+              [self] + superclass.mongoid_superclasses
+            else
+              [self]
+            end
           end
 
-          def self.invalidation_strategy
-            Garner.config.mongoid_binding_invalidation_strategy
+          # Return an object that can act as a binding on this class's behalf.
+          #
+          # @return [Mongoid::Document]
+          def self.proxy_binding
+            _latest_by_updated_at
           end
 
-          def self.identify(id)
-            Garner::Mixins::Mongoid::Identity.from_class_and_id(self, id)
+          def self.identify(handle)
+            Mongoid::Identity.from_class_and_handle(self, handle)
           end
 
-          def self.garnered_find(id)
-            return nil unless (binding = identify(id))
+          # Find an object by _id, or other findable field, first trying to
+          # fetch from Garner's cache.
+          #
+          # @return [Mongoid::Document]
+          def self.garnered_find(handle)
+            return nil unless (binding = identify(handle))
             identity = Garner::Cache::Identity.new
-            identity.bind(binding).key({ :source => :garnered_find }) { find(id) }
+            identity.bind(binding).key({ :source => :garnered_find }) do
+              find(handle)
+            end
           end
 
           after_create    :_garner_after_create

data/lib/garner/mixins/mongoid/identity.rb

@@ -1,22 +1,24 @@
-# Set up Garner configuration parameters
-Garner.config.option(:mongoid_identity_fields, {
-  :default => [:_id]
-})
-
 module Garner
   module Mixins
     module Mongoid
       class Identity
         include Garner::Cache::Binding
 
-        attr_accessor :document, :collection_name, :conditions
+        attr_accessor :klass, :handle, :proxy_binding, :conditions
 
-        def self.from_class_and_id(klass, id)
+        # Instantiate a new Mongoid::Identity.
+        #
+        # @param klass [Class] A
+        # @param handle [Object] A String, Fixnum, BSON::ObjectId, etc.
+        #   identifying the object.
+        # @return [Garner::Mixins::Mongoid::Identity]
+        def self.from_class_and_handle(klass, handle)
           validate_class!(klass)
 
           self.new.tap do |identity|
-            identity.collection_name = klass.collection_name
-            identity.conditions = conditions_for(klass, id)
+            identity.klass = klass
+            identity.handle = handle
+            identity.conditions = conditions_for(klass, handle)
           end
         end
 
@@ -24,57 +26,18 @@ module Garner
           @conditions = {}
         end
 
-        def key_strategy
-          Garner.config.mongoid_binding_key_strategy
-        end
-
-        def invalidation_strategy
-          Garner.config.mongoid_binding_invalidation_strategy
-        end
-
-        def cache_key
-          # See https://github.com/mongoid/mongoid/blob/f5ba1295/lib/mongoid/document.rb#L242
-          if updated_at
-            "#{model_cache_key}/#{_id}-#{updated_at.utc.to_s(:number)}"
-          elsif _id
-            "#{model_cache_key}/#{_id}"
-          else
-            "#{model_cache_key}/new"
-          end
-        end
-
-        def model_cache_key
-          if _type
-            ActiveModel::Name.new(_type.constantize).cache_key
-          else
-            @collection_name.to_s
-          end
-        end
-
-        def collection
-          ::Mongoid.default_session[@collection_name]
-        end
-
-        def document
-          return @document if @document
-
-          collection.where(@conditions).select({
-            :_id => 1,
-            :_type => 1,
-            :updated_at => 1
-          }).limit(1).first
-        end
-
-        def _id
-          document["_id"] if document
-        end
-
-        def updated_at
-          document["updated_at"] if document
+        # Return an object that can act as a binding on this identity's behalf.
+        #
+        # @return [Mongoid::Document]
+        def proxy_binding
+          @proxy_binding ||= klass.where(conditions).only(:_id, :_type, :updated_at).first
         end
 
-        def _type
-          document["_type"] if document
+        # Stringize this identity for purposes of marshaling.
+        #
+        # @return [String]
+        def to_s
+          "#{self.class.name}/klass=#{klass},handle=#{handle}"
         end
 
         private
@@ -86,11 +49,11 @@ module Garner
           end
         end
 
-        def self.conditions_for(klass, id)
+        def self.conditions_for(klass, handle)
           # multiple-ID conditions
           conditions = {
             "$or" => Garner.config.mongoid_identity_fields.map { |field|
-              { field => id }
+              { field => handle }
             }
           }
 

data/lib/garner/mixins/rack.rb

@@ -1,15 +1,5 @@
 require "garner"
 
-# Set up Garner configuration parameters
-Garner.config.option(:rack_context_key_strategies, {
-  :default => [
-    Garner::Strategies::Context::Key::Caller,
-    Garner::Strategies::Context::Key::RequestGet,
-    Garner::Strategies::Context::Key::RequestPost,
-    Garner::Strategies::Context::Key::RequestPath
-  ]
-})
-
 module Garner
   module Mixins
     module Rack

data/lib/garner/strategies/binding/invalidation/binding_index.rb

@@ -0,0 +1,35 @@
+module Garner
+  module Strategies
+    module Binding
+      module Invalidation
+        class BindingIndex < Base
+
+          # Specifies whether invalidation should happen on callbacks.
+          #
+          # @param kind [Symbol] One of :create, :update, :destroy
+          def self.apply_on_callback?(kind = nil)
+            true
+          end
+
+          # Force-invalidate an object binding. Used when bindings are
+          # explicitly invalidated, via binding.invalidate_garner_caches.
+          #
+          # @param binding [Object] The binding whose caches are to be
+          #   invalidated.
+          def self.apply(binding)
+            Key::BindingIndex.write_canonical_binding_for(binding)
+            Key::BindingIndex.write_cache_key_for(binding)
+
+            # Invalidate proxied classes
+            if binding.respond_to?(:proxied_classes)
+              binding.proxied_classes.each do |klass|
+                Key::BindingIndex.write_cache_key_for(klass)
+              end
+            end
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/garner/strategies/binding/invalidation/touch.rb

@@ -8,7 +8,10 @@ module Garner
           #
           # @param kind [Symbol] One of :create, :update, :destroy
           def self.apply_on_callback?(kind = nil)
-            false
+            # Only apply on destruction, so that class bindings remain
+            # valid, if the destroyed binding was not also the previous
+            # proxy_binding.
+            !!(kind == :destroy)
           end
 
           # Force-invalidate an object binding. Used when bindings are
@@ -17,6 +20,17 @@ module Garner
           # @param binding [Object] The binding whose caches are to be
           #   invalidated.
           def self.apply(binding)
+            if  binding.respond_to?(:destroyed?) &&
+                binding.destroyed? &&
+                binding.class.respond_to?(:proxy_binding)
+              # Binding is destroyed, but we must ensure that its class's
+              # proxy_binding is touched, if necessary.
+              binding = binding.class.proxy_binding
+
+            elsif binding.respond_to?(:proxy_binding)
+              binding = binding.proxy_binding
+            end
+
             binding.touch if binding.respond_to?(:touch)
           end
         end

data/lib/garner/strategies/binding/key/binding_index.rb

@@ -0,0 +1,109 @@
+module Garner
+  module Strategies
+    module Binding
+      module Key
+        class BindingIndex < Base
+          RANDOM_KEY_LENGTH = 12  # In bytes.
+
+          # Compute a cache key as follows:
+          # 1. Determine whether the binding is canonical.
+          # 2. If canonical, fetch the cache key stored for binding.class,
+          #    binding.id
+          # 3. If not canonical, determine the canonical ID from a proxy
+          #    binding. Proxy bindings must implement `proxy_binding` and
+          #    `handle`.
+          #
+          # @param binding [Object] The object from which to compute a key.
+          # @return [String] A cache key string.
+          def self.apply(binding)
+            fetch_cache_key_for(binding)
+          end
+
+          # Fetch cache key, from cache, for the given binding. Generate a
+          # random key, if not already extant.
+          #
+          # @param binding [Object] The object from which to compute a key.
+          # @return [String] A cache key string.
+          def self.fetch_cache_key_for(binding)
+            canonical_binding = fetch_canonical_binding_for(binding)
+            key = index_key_for(canonical_binding)
+            Garner.config.cache.fetch(key) { new_cache_key_for(canonical_binding) }
+          end
+
+          # Overwrite cache key for the given binding.
+          #
+          # @param binding [Object] The object from which to compute a key.
+          # @return [String] A cache key string.
+          def self.write_cache_key_for(binding)
+            canonical_binding = fetch_canonical_binding_for(binding)
+            key = index_key_for(canonical_binding)
+            value = new_cache_key_for(canonical_binding)
+            value.tap { |v| Garner.config.cache.write(key, v) }
+          end
+
+          # Fetch canonical binding for the given binding.
+          #
+          # @param binding [Object] The object from which to compute a key.
+          # @return [Object] A class, ID pair.
+          def self.fetch_canonical_binding_for(binding)
+            return binding if canonical?(binding)
+            key = index_key_for(binding)
+            Garner.config.cache.fetch(key) { canonical_binding_for(binding) }
+          end
+
+          # Overwrite canonical binding for the given binding.
+          #
+          # @param binding [Object] The object from which to compute a key.
+          # @return [Object] A class, ID pair.
+          def self.write_canonical_binding_for(binding)
+            return binding if canonical?(binding)
+            key = index_key_for(binding)
+            value = canonical_binding_for(binding)
+            value.tap { |v| Garner.config.cache.write(key, v) }
+          end
+
+          # Return canonical binding for the given binding.
+          #
+          # @param binding [Object] The (possibly) non-canonical binding.
+          # @return binding [Object] The canonical binding.
+          def self.canonical_binding_for(binding)
+            if canonical?(binding)
+              binding
+            elsif binding.respond_to?(:proxy_binding)
+              canonical_binding_for(binding.proxy_binding)
+            else
+              nil
+            end
+          end
+
+          # Determine whether the given binding is canonical.
+          #
+          # @return [Boolean]
+          def self.canonical?(binding)
+            # TODO: Implement real logic for determining canonicity.
+            binding.is_a?(Mongoid::Document) ||
+            (binding.is_a?(Class) && binding.include?(Mongoid::Document))
+          end
+
+          private
+          def self.index_key_for(binding)
+            if binding.respond_to?(:identity_string)
+              binding_key = binding.identity_string
+            else
+              binding_key = binding.to_s
+            end
+
+            {
+              :strategy => self,
+              :proxied_binding => binding_key
+            }
+          end
+
+          def self.new_cache_key_for(binding)
+            SecureRandom.hex(RANDOM_KEY_LENGTH)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/garner/strategies/binding/key/safe_cache_key.rb

@@ -15,6 +15,8 @@ module Garner
           # @param binding [Object] The object from which to compute a key.
           # @return [String] A cache key string.
           def self.apply(binding)
+            binding = binding.proxy_binding if binding.respond_to?(:proxy_binding)
+
             return unless binding.respond_to?(:cache_key) && binding.cache_key
             return unless binding.respond_to?(:updated_at) && binding.updated_at
 

data/lib/garner/version.rb

@@ -1,3 +1,3 @@
 module Garner
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: garner
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-17 00:00:00.000000000 Z
+date: 2013-06-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -268,6 +268,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: method_profiler
+  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: pry
   requirement: !ruby/object:Gem::Requirement
@@ -347,13 +363,17 @@ files:
 - lib/garner/cache/context.rb
 - lib/garner/cache/identity.rb
 - lib/garner/config.rb
+- lib/garner/mixins/active_record.rb
+- lib/garner/mixins/active_record/base.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/base.rb
+- lib/garner/strategies/binding/invalidation/binding_index.rb
 - lib/garner/strategies/binding/invalidation/touch.rb
 - lib/garner/strategies/binding/key/base.rb
+- lib/garner/strategies/binding/key/binding_index.rb
 - lib/garner/strategies/binding/key/cache_key.rb
 - lib/garner/strategies/binding/key/safe_cache_key.rb
 - lib/garner/strategies/context/key/base.rb
@@ -380,7 +400,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1734950059228816164
+      hash: 1915990174138923704
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: