garner 0.3.3 → 0.4.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: garner
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-10 00:00:00.000000000 Z
+date: 2013-06-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -108,6 +108,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  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: rack-test
   requirement: !ruby/object:Gem::Requirement
@@ -172,6 +188,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: mongoid_slug
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: dalli
   requirement: !ruby/object:Gem::Requirement
@@ -188,6 +220,70 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  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: sqlite3
+  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: coveralls
+  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
+    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: yard
   requirement: !ruby/object:Gem::Requirement
@@ -236,8 +332,8 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: Garner is a set of Rack middleware and cache helpers that implement various
-  strategies.
+description: Garner is a cache layer for Ruby and Rack applications, supporting model
+  and instance binding and hierarchical invalidation.
 email: dblock@dblock.org
 executables: []
 extensions: []
@@ -246,22 +342,26 @@ extra_rdoc_files:
 - README.md
 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/base.rb
+- lib/garner/strategies/binding/invalidation/touch.rb
+- lib/garner/strategies/binding/key/base.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
+- 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
 - LICENSE.md
 - README.md
@@ -280,7 +380,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1943683014266943396
+      hash: 1734950059228816164
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -292,6 +392,6 @@ rubyforge_project:
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
-summary: Garner is a set of Rack middleware and cache helpers that implement various
-  strategies.
+summary: Garner is a cache layer for Ruby and Rack applications, supporting model
+  and instance binding and hierarchical invalidation.
 test_files: []

data/lib/garner/cache/object_identity.rb

@@ -1,249 +0,0 @@
-module Garner
-  module Cache
-    #
-    # A cache that uses an object identity binding strategy.
-    #
-    # Allows some flexibility in how caller binds objects in cache.
-    # The binding can be an object, class, array of objects, or array of classes
-    # on which to bind the validity of the cached result contained in the subsequent
-    # block.
-    #
-    # @example `bind: { klass: Widget, object: { id: params[:id] } }` will cause a cached instance to be
-    # invalidated on any change to the `Widget` object whose slug attribute equals `params[:id]`
-    #
-    # @example `bind: { klass: User, object: { id: current_user.id } }` will cause a cached instance to be
-    # invalidated on any change to the `User` object whose id attribute equals current_user.id.
-    # This is one way to bind a cache result to any change in the current user.
-    #
-    # @example `bind: { klass: Widget }` will cause the cached instance to be invalidated on any change to
-    # any object of class Widget. This is the appropriate strategy for index paths like /widgets.
-    #
-    # @example `bind: [{ klass: Widget }, { klass: User, object: { id: current_user.id } }]` will cause a
-    # cached instance to be invalidated on any change to either the current user, or any object of class Widget.
-    #
-    # @example `bind: [Artwork]` is shorthand for `bind: { klass: Artwork }`
-    #
-    # @example `bind: [Artwork, params[:id]]` is shorthand for `bind: { klass: Artwork, object: { id: params[:id] } }`
-    #
-    # @example `bind: [User, { id: current_user.id }] is shorthand for `bind: { klass: User, object: { id: current_user.id } }`
-    #
-    # @example `bind: [[Artwork], [User, { id: current_user.id }]]` is shorthand for
-    # `bind: [{ klass: Artwork }, { klass: User, object: { id: current_user.id } }]`
-    #
-    module ObjectIdentity
-
-      IDENTITY_FIELDS = [ :id ]
-
-      KEY_STRATEGIES = [
-        Garner::Strategies::Keys::Caller,
-        Garner::Strategies::Keys::Version,
-        Garner::Strategies::Keys::RequestPath,
-        Garner::Strategies::Keys::RequestGet,
-        Garner::Strategies::Keys::RequestPost
-      ]
-
-      CACHE_STRATEGIES = [
-        Garner::Strategies::Cache::Expiration
-      ]
-
-      ETAG_STRATEGY = Garner::Strategies::ETags::Grape
-
-      class << self
-
-        # cache the result of an executable block
-        def cache(binding = nil, context = {}, &block)
-          cache_options = apply_cache_options(context)
-          ctx = key_context(context)
-          fetch(key(binding, ctx), nil, cache_options, &block)
-        end
-
-        # cache a collection of results
-        def cache_multi(bindings, context = {}, &block)
-          cache_options = apply_cache_options(context)
-          ctx = key_context(context)
-          keys = bindings.map do |binding|
-            key(binding, ctx)
-          end
-          # attempt to do a read_multi if the cache supports it
-          read_multi = keys.size > 1 && Garner.config.cache.respond_to?(:read_multi)
-          local_cache = read_multi ? Garner.config.cache.read_multi(*keys) : {}
-          # fetch all missing values
-          bindings.each_with_index.map do |binding, index|
-            key = keys[index]
-            # just write the value if the key was not fetched in read_multi
-            local_cache[key] || (read_multi ?
-              write(key, binding, cache_options, &block) :
-              fetch(key, binding, cache_options, &block))
-          end
-        end
-
-        # invalidate an object that has been cached
-        def invalidate(* args)
-          options = index(*args)
-          reset_key_prefix_for(options[:klass], options[:object])
-          reset_key_prefix_for(options[:klass]) if options[:object]
-        end
-
-        # metadata for cached objects:
-        #   :etag - Unique hash of object content
-        #   :last_modified - Timestamp of last modification event
-        def cache_metadata(binding, context = {})
-          key = key(binding, key_context(context))
-          Garner.config.cache.read(meta(key))
-        end
-
-        private
-
-          # fetch an object from cache, write if not present
-          def fetch(key, binding, cache_options = {}, &block)
-            result = Garner.config.cache.fetch(key, cache_options) do
-              object = binding ? yield(binding) : yield
-              reset_cache_metadata key, object
-              object
-            end
-            Garner.config.cache.delete(key) unless result
-            result
-          end
-
-          # write an object to cache
-          def write(key, binding, cache_options = {}, &block)
-            object = binding ? yield(binding) : yield
-            if object
-              Garner.config.cache.write(key, object, cache_options)
-              reset_cache_metadata key, object
-            end
-            Garner.config.cache.delete(key) unless object
-            object
-          end
-
-          # applied cache options
-          def apply_cache_options(context)
-            cache_options = context[:cache_options] || {}
-            CACHE_STRATEGIES.each do |strategy|
-              cache_options = strategy.apply(cache_options)
-            end
-            cache_options
-          end
-
-          # applied key context
-          def key_context(context)
-            new_context = {}
-            context ||= {}
-            KEY_STRATEGIES.each do |strategy|
-              new_context = strategy.apply(new_context, context)
-            end
-            new_context
-          end
-
-          def reset_key_prefix_for(klass, object = nil)
-            Garner.config.cache.delete(index_string_for(klass, object))
-          end
-
-          def reset_cache_metadata(key, object)
-            return unless object
-            metadata = {
-              :etag => ETAG_STRATEGY.apply(object),
-              :last_modified => Time.now
-            }
-            meta_key = meta(key)
-            Garner.config.cache.write(meta_key, metadata)
-          end
-
-          def new_key_prefix_for(klass, object = nil)
-            Digest::MD5.hexdigest("#{klass}/#{object || "*"}:#{new_key_postfix}")
-          end
-
-          # Generate a key in the Klass/id format.
-          # @example Widget/id=1,Gadget/slug=forty-two,Fudget/*
-          def key(binding = nil, context = {})
-            bound = binding && binding[:bind] ? standardize(binding[:bind]) : {}
-            bound = (bound.is_a?(Array) ? bound : [ bound ]).compact
-            bound.collect { |el|
-              if el[:object] && ! IDENTITY_FIELDS.map { |id| el[:object][id] }.compact.any?
-                raise ArgumentError, ":bind object arguments (#{bound}) can only be keyed by #{IDENTITY_FIELDS.join(", ")}"
-              end
-              find_or_create_key_prefix_for(el[:klass], el[:object])
-            }.join(",") + ":" +
-            Digest::MD5.hexdigest(
-              KEY_STRATEGIES.map { |strategy| context[strategy.field] }.uniq.compact.join("\n")
-            )
-          end
-
-          # Generate an index key from args
-          def index(* args)
-            case args[0]
-            when Hash
-              args[0]
-            when Class
-              case args[1]
-              when Hash
-                { :klass => args[0], :object => args[1] }
-              when NilClass
-                { :klass => args[0] }
-              else
-                { :klass => args[0], :object => { IDENTITY_FIELDS.first => args[1] } }
-              end
-            else
-              raise ArgumentError, "invalid args, must be (klass, identifier) or hash (#{args})"
-            end
-          end
-
-          def find_or_create_key_prefix_for(klass, object = nil)
-            Garner.config.cache.fetch(index_string_for(klass, object), {}) do
-              new_key_prefix_for(klass, object)
-            end
-          end
-
-          def new_key_prefix_for(klass, object = nil)
-            Digest::MD5.hexdigest("#{klass}/#{object || "*"}:#{new_key_postfix}")
-          end
-
-          def new_key_postfix
-            SecureRandom.respond_to?(:uuid) ? SecureRandom.uuid : (0...16).map{ ('a'..'z').to_a[rand(26)] }.join
-          end
-
-          def standardize(binding)
-            case binding
-            when Hash
-              binding
-            when Array
-              bind_array(binding)
-            when NilClass
-              nil
-            end
-          end
-
-          # Generate a metadata key.
-          def meta(key)
-            "#{key}:meta"
-          end
-
-          def bind_array(ary)
-            case ary[0]
-            when Array, Hash
-              ary.collect { |subary| standardize(subary) }
-            when Class
-              h = { :klass => ary[0] }
-              h.merge!({
-                :object => (ary[1].is_a?(Hash) ? ary[1] : { IDENTITY_FIELDS.first => ary[1] })
-              }) if ary[1]
-              h
-            else
-              raise ArgumentError, "invalid argument type #{ary[0].class} in :bind (#{ary[0]})"
-            end
-          end
-
-          def index_string_for(klass, object = nil)
-            prefix = "INDEX"
-            IDENTITY_FIELDS.each do |field|
-              if object && object[field]
-                return "#{prefix}:#{klass}/#{field}=#{object[field]}"
-              end
-            end
-            "#{prefix}:#{klass}/*"
-          end
-
-      end
-    end
-  end
-end

data/lib/garner/middleware/base.rb

@@ -1,47 +0,0 @@
-# Based on https://github.com/intridea/grape/blob/master/lib/grape/middleware/base.rb.
-module Garner
-  module Middleware
-    class Base
-      attr_reader :app, :env, :options
-
-      # @param [Rack Application] app The standard argument for a Rack middleware.
-      # @param [Hash] options A hash of options, simply stored for use by subclasses.
-      def initialize(app, options = {})
-        @app = app
-        @options = default_options.merge(options)
-      end
-
-      def default_options; {} end
-
-      def call(env)
-        dup.call!(env)
-      end
-
-      def call!(env)
-        @env = env
-        before
-        @app_response = @app.call(@env)
-        after || @app_response
-      end
-
-      # @abstract
-      # Called before the application is called in the middleware lifecycle.
-      def before; end
-      
-      # @abstract
-      # Called after the application is called in the middleware lifecycle.
-      # @return [Response, nil] a Rack SPEC response or nil to call the application afterwards.
-      def after; end
-
-      def request
-        Rack::Request.new(self.env)
-      end
-
-      def response
-        Rack::Response.new(@app_response)
-      end
-
-    end
-  end
-end
-

data/lib/garner/middleware/cache/bust.rb

@@ -1,20 +0,0 @@
-module Garner
-  module Middleware
-    module Cache
-      # @abstract
-      # Add the necessary Cache-Control and Expires headers to bust client cache.
-      class Bust < Garner::Middleware::Base      
-        def after
-          # private: ok to store API results in a private cache
-          # max-age: don't reuse the cached result without checking with the server (server might say 304 Not Modified)
-          # must-revalidate: prevent gateways from returning a response if the API server is not reachable
-          @app_response[1]["Cache-Control"] = "private, max-age=0, must-revalidate"
-          # don't reuse the cached result without checking with the server
-          @app_response[1]["Expires"] = "Fri, 01 Jan 1990 00:00:00 GMT"
-          @app_response
-        end
-      end
-    end
-  end
-end
-

data/lib/garner/mixins/grape_cache.rb

@@ -1,111 +0,0 @@
-module Garner
-  module Mixins
-    module Grape
-      #
-      # A cache that supports conditional GETs
-      #
-      # Borrows generously from http://themomorohoax.com/2009/01/07/using-stale-with-rails-to-return-304-not-modified
-      # See also RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.3.4
-      #   for explanation of how If-Modified-Since and If-None-Match request headers are handled.
-      #
-      module Cache
-      
-        def cache_enabled?
-          true
-        end
-  
-        # cache a record
-        def cache(options = {}, &block)
-          unless cache_enabled?
-            yield
-          else
-            binding, context = cache_binding_and_context(options)
-            Garner::Cache::ObjectIdentity.cache(binding, context) do
-              yield
-            end
-          end
-        end
-        
-        # invalidate a cache record
-        def invalidate(*args)
-          Garner::Cache::ObjectIdentity.invalidate(* args)
-        end
-  
-        def cache_or_304(options = {}, &block)
-          unless cache_enabled?
-            yield
-          else
-            binding, context = cache_binding_and_context(options)
-            # metadata written in a previous GET
-            metadata = Garner::Cache::ObjectIdentity.cache_metadata(binding, context)
-            error!("Not Modified", 304) if metadata && fresh?(metadata)
-            rc = cache(options, &block)
-            # metadata has been generated by cache
-            metadata = Garner::Cache::ObjectIdentity.cache_metadata(binding, context)
-            if metadata
-              self.last_modified = metadata[:last_modified]
-              self.etag = metadata[:etag]
-            end
-            rc
-          end
-        end
-  
-        private
-          
-          def cache_binding_and_context(options)
-            cache_context = {}
-            cache_context.merge!(options.dup)
-            cache_context[:request] = request
-            cache_context[:version] = version if self.respond_to?(:version) && version
-            cache_context.delete(:bind)
-            cache_binding = (options || {})[:bind]
-            cache_binding = cache_binding ? { :bind => cache_binding } : {}
-            [ cache_binding, cache_context ]
-          end
-
-          def fresh?(metadata = {})
-            case
-            when if_modified_since && if_none_match
-              not_modified?(metadata[:last_modified]) && etag_matches?(metadata[:etag])
-            when if_modified_since
-              not_modified?(metadata[:last_modified])
-            when if_none_match
-              etag_matches?(metadata[:etag])
-            else
-              false
-            end
-          end
-    
-          def if_modified_since
-            if since = env["HTTP_IF_MODIFIED_SINCE"]
-              Time.rfc2822(since) rescue nil
-            end
-          end
-
-          def if_none_match
-            env["HTTP_IF_NONE_MATCH"]
-          end
-
-          def not_modified?(modified_at)
-            if_modified_since && modified_at && if_modified_since >= modified_at
-          end
-
-          def etag_matches?(etag)
-            if_none_match && if_none_match == etag
-          end
-        
-          def last_modified=(utc_time)
-            return unless utc_time
-            header "Last-Modified", utc_time.httpdate
-          end
-        
-          def etag=(etag)
-            return unless etag
-            header "ETag", etag
-          end
-          
-      end
-    end
-  end
-end
-

data/lib/garner/mixins/mongoid_document.rb

@@ -1,58 +0,0 @@
-module Garner
-  module Mixins
-    module Mongoid
-      module Document
-        extend ActiveSupport::Concern
-
-        included do
-          after_create :invalidate_api_cache
-          after_update :invalidate_api_cache
-          after_destroy :invalidate_api_cache
-          cattr_accessor :api_cache_class
-        end
-
-        # invalidate API cache
-        def invalidate_api_cache
-          self.all_embedding_documents.each { |doc| doc.invalidate_api_cache }
-          cache_class = self.class.api_cache_class || self.class
-          Garner::Cache::ObjectIdentity::IDENTITY_FIELDS.each do |identity_field|
-            next unless self.respond_to?(identity_field)
-            Garner::Cache::ObjectIdentity.invalidate(cache_class, { identity_field => self.send(identity_field) })
-          end
-          Garner::Cache::ObjectIdentity.invalidate(cache_class)
-        end
-
-        def invalidate_api_cache_for_class
-          cache_class = self.class.api_cache_class || self.class
-          Garner::Cache::ObjectIdentity.invalidate(cache_class)
-        end
-
-        # navigate the parent embedding document hierarchy
-        def all_embedding_documents
-          obj = self
-          docs = []
-          while obj.metadata && obj.embedded?
-            # FIXME: This is not a robust check for cycles
-            break if docs.detect { |doc| doc.class == obj.class }
-            break unless obj.metadata.inverse
-            parent = obj.send(obj.metadata.inverse)
-            break unless parent
-            docs << parent
-            obj = parent
-          end
-          docs
-        end
-
-        module ClassMethods
-          # Including classes can call `cache_as` to specify a different class
-          # on which to bind API cache objects.
-          # @example `Admin`, which extends `User` should call `cache_as User`
-          def cache_as(klass)
-            self.api_cache_class = klass
-          end
-        end
-      end
-    end
-  end
-end
-