garner 0.1.2 → 0.1.3

data/README.md

@@ -47,6 +47,22 @@ get "/me/address" do
 end
 ```
 
+ETag Generation Strategies
+--------------------------
+
+The primary purpose of the ETag header is to define a short string representation of a cached object that is both (a) deterministic and (b) unique, so that Garner's `cache_or_304` method can quickly determine whether a client's cached content matches the latest server object. As such, an MD5 hash applied to *any* object serialization would suffice. However, some applications may wish to control the manner in which ETags are generated, and so Garner supports arbitrary ETag strategies.
+
+The default strategy, `Garner::Strategies::ETags::Grape`, follows the serialization strategy used by Grape for coercing objects into JSON. Using this strategy, Garner will generate an ETag for each cache object that is identical to what `Rack::ETag` would return if that object was returned by Grape. This property could be useful for Grape applications.
+
+Another, simpler strategy, `Garner::Strategies::ETags::Marshal`, simply applies an MD5 hash to `Marshal.dump(object)`. This strategy might be more applicable for applications not using Grape.
+
+An ETag strategy may be defined at application startup time:
+
+```
+ETAG_STRATEGY = Garner::Strategies::ETags::Grape
+```
+
+
 Binding Strategies
 ------------------
 
@@ -117,6 +133,15 @@ Garner::Cache::ObjectIdentity::KEY_STRATEGIES = [
 
 This method of registration does need improvement, please contribute.
 
+Available Key Strategies
+------------------------
+
+* `Garner::Strategies::Keys::Caller` inserts the calling file and line number, allowing multiple calls from the same function to generate different keys.
+* `Garner::Strategies::Keys::Version` inserts the output of a `version` method, when available, primarily targeted at API implementations.
+* `Garner::Strategies::Keys::Key` inserts the value of `:key` within the requested context, useful to explicitly declare an element of a cache key.
+* `Garner::Strategies::Keys::RequestGet` inserts the value of HTTP request's GET parameters into the cache key when `:request` is present in the context.
+* `Garner::Strategies::Keys::RequestPath` inserts the value of the HTTP request's path into the cache key when `:request` is present in the context.
+
 Configuration
 -------------
 

data/lib/garner/cache/object_identity.rb

@@ -44,6 +44,8 @@ module Garner
       CACHE_STRATEGIES = [
         Garner::Strategies::Cache::Expiration
       ]
+
+      ETAG_STRATEGY = Garner::Strategies::ETags::Grape
       
       class << self
 
@@ -107,7 +109,7 @@ module Garner
           def reset_cache_metadata(key, object)
             return unless object
             metadata = {
-              :etag => Garner::Objects::ETag.from(object),
+              :etag => ETAG_STRATEGY.apply(object),
               :last_modified => Time.now
             }
             meta_key = meta(key)

data/lib/garner/config.rb

@@ -9,7 +9,7 @@ module Garner
     #     config.cache = Rails.cache
     #   end
     #
-    # @return [ Config ] The configuration obejct.
+    # @return [ Config ] The configuration object.
     def configure
       block_given? ? yield(Garner::Config) : Garner::Config
     end

data/lib/garner/mixins/grape_cache.rb

@@ -56,6 +56,7 @@ module Garner
             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 } : {}

data/lib/garner/strategies/cache/expiration_strategy.rb

@@ -1,7 +1,7 @@
 module Garner
   module Strategies
     module Cache
-      # Injects an expires_in value from the globl configuration.
+      # Injects an expires_in value from the global configuration.
       module Expiration
         class << self
           def apply(current, options = {})

data/lib/garner/strategies/etags/grape_strategy.rb

@@ -0,0 +1,32 @@
+module Garner
+  module Strategies
+    module ETags
+      module Grape
+        class << self
+          # @abstract
+          # Serialize in a way such that the ETag matches that which would
+          # be returned by Grape + Rack::ETag at response time.
+          def apply(object)
+            serialization = encode_json(object || "")
+            %("#{Digest::MD5.hexdigest(serialization)}")
+          end
+
+          # See https://github.com/intridea/grape/blob/master/lib/grape/middleware/base.rb
+          def encode_json(object)
+            return object if object.is_a?(String)
+
+            if object.respond_to? :serializable_hash
+              MultiJson.dump(object.serializable_hash)
+            elsif object.kind_of?(Array) && !object.map {|o| o.respond_to? :serializable_hash }.include?(false)
+              MultiJson.dump(object.map {|o| o.serializable_hash })
+            elsif object.respond_to? :to_json
+              object.to_json
+            else
+              MultiJson.dump(object)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/garner/strategies/etags/marshal_strategy.rb

@@ -0,0 +1,16 @@
+module Garner
+  module Strategies
+    module ETags
+      module Marshal
+        class << self
+          # @abstract
+          # Serialize using Ruby's Marshal.dump.
+          def apply(object)
+            serialization = ::Marshal.dump(object || "")
+            %("#{Digest::MD5.hexdigest(serialization)}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/garner/strategies/keys/caller_strategy.rb

@@ -11,11 +11,11 @@ module Garner
           
           def apply(key, context = {})
             rc = key ? key.dup : {}
-            clr = nil
             caller.each do |line|
               split = line.split(":")
               next unless split.length >= 2
               path = Pathname.new(split[0]).realpath.to_s
+              next if path.include?("lib/garner")
               next unless path.include?("/app/") || path.include?("/spec/")
               rc[field] = "#{path}:#{split[1]}"
               break

data/lib/garner/strategies/keys/jsonp_strategy.rb

@@ -0,0 +1,24 @@
+module Garner
+  module Strategies
+    module Keys
+      # Strips JSONP parameters from the key.
+      module Jsonp
+        class << self
+
+          def field
+            :params
+          end
+
+          def apply(key, context = {})
+            key = key ? key.dup : {}
+            return unless key[field]
+            key[field].delete("callback")
+            key[field].delete("_")
+            key
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/garner/strategies/keys/key_strategy.rb

@@ -0,0 +1,21 @@
+module Garner
+  module Strategies
+    module Keys
+      # Inject a key into the cache key.
+      module Key
+        class << self
+        
+          def field
+            :key
+          end
+          
+          def apply(key, context = {})
+            key = key ? key.dup : {}
+            key[field] = context[:key] if context && context.has_key?(:key)
+            key
+          end
+        end
+      end
+    end
+  end
+end

data/lib/garner/version.rb

@@ -1,5 +1,3 @@
 module Garner
-  VERSION = '0.1.2'
+  VERSION = '0.1.3'
 end
-
-

data/lib/garner.rb

@@ -3,8 +3,6 @@ require 'active_support'
 # garner
 require 'garner/version'
 require 'garner/config'
-# objects
-require 'garner/objects/etag'
 # middleware
 require 'garner/middleware/base'
 require 'garner/middleware/cache/bust'
@@ -13,10 +11,15 @@ 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/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'
-require 'garner/mixins/mongoid_document'
+require 'garner/mixins/grape_cache' if defined?(Grape)
+require 'garner/mixins/mongoid_document' if defined?(Mongoid)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: garner
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
   prerelease: 
 platform: ruby
 authors:
@@ -10,11 +10,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-06-25 00:00:00.000000000 Z
+date: 2012-07-18 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
-  requirement: &70317016435700 !ruby/object:Gem::Requirement
+  requirement: &70261714866040 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,10 +22,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70317016435700
+  version_requirements: *70261714866040
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: &70317016434120 !ruby/object:Gem::Requirement
+  requirement: &70261714865560 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -33,21 +33,21 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70317016434120
+  version_requirements: *70261714865560
 - !ruby/object:Gem::Dependency
   name: multi_json
-  requirement: &70317016432160 !ruby/object:Gem::Requirement
+  requirement: &70261714865080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.3.0
   type: :runtime
   prerelease: false
-  version_requirements: *70317016432160
+  version_requirements: *70261714865080
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70317016430400 !ruby/object:Gem::Requirement
+  requirement: &70261714864600 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -55,10 +55,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70317016430400
+  version_requirements: *70261714864600
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &70317016428340 !ruby/object:Gem::Requirement
+  requirement: &70261714864120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -66,10 +66,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70317016428340
+  version_requirements: *70261714864120
 - !ruby/object:Gem::Dependency
   name: grape
-  requirement: &70317016441760 !ruby/object:Gem::Requirement
+  requirement: &70261714863640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - =
@@ -77,10 +77,10 @@ dependencies:
         version: 0.2.0
   type: :development
   prerelease: false
-  version_requirements: *70317016441760
+  version_requirements: *70261714863640
 - !ruby/object:Gem::Dependency
   name: rack-test
-  requirement: &70317016438060 !ruby/object:Gem::Requirement
+  requirement: &70261714863160 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - =
@@ -88,10 +88,10 @@ dependencies:
         version: 0.6.1
   type: :development
   prerelease: false
-  version_requirements: *70317016438060
+  version_requirements: *70261714863160
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70317016452220 !ruby/object:Gem::Requirement
+  requirement: &70261714862680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -99,10 +99,10 @@ dependencies:
         version: '2.10'
   type: :development
   prerelease: false
-  version_requirements: *70317016452220
+  version_requirements: *70261714862680
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &70317016480360 !ruby/object:Gem::Requirement
+  requirement: &70261714878560 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - =
@@ -110,10 +110,10 @@ dependencies:
         version: 1.8.3
   type: :development
   prerelease: false
-  version_requirements: *70317016480360
+  version_requirements: *70261714878560
 - !ruby/object:Gem::Dependency
   name: mongoid
-  requirement: &70317016476340 !ruby/object:Gem::Requirement
+  requirement: &70261714878080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -121,10 +121,10 @@ dependencies:
         version: '2.4'
   type: :development
   prerelease: false
-  version_requirements: *70317016476340
+  version_requirements: *70261714878080
 - !ruby/object:Gem::Dependency
   name: bson_ext
-  requirement: &70317020028420 !ruby/object:Gem::Requirement
+  requirement: &70261714877600 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -132,10 +132,10 @@ dependencies:
         version: '1.6'
   type: :development
   prerelease: false
-  version_requirements: *70317020028420
+  version_requirements: *70261714877600
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &70317020022760 !ruby/object:Gem::Requirement
+  requirement: &70261714877120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -143,10 +143,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70317020022760
+  version_requirements: *70261714877120
 - !ruby/object:Gem::Dependency
   name: redcarpet
-  requirement: &70317020102160 !ruby/object:Gem::Requirement
+  requirement: &70261714876640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -154,10 +154,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70317020102160
+  version_requirements: *70261714876640
 - !ruby/object:Gem::Dependency
   name: github-markup
-  requirement: &70317020288700 !ruby/object:Gem::Requirement
+  requirement: &70261714876160 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -165,7 +165,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70317020288700
+  version_requirements: *70261714876160
 description: Garner is a set of Rack middleware and cache helpers that implement various
   strategies.
 email: dblock@dblock.org
@@ -182,16 +182,19 @@ files:
 - lib/garner/middleware/cache/bust.rb
 - lib/garner/mixins/grape_cache.rb
 - lib/garner/mixins/mongoid_document.rb
-- lib/garner/objects/etag.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/version_strategy.rb
 - lib/garner/version.rb
 - LICENSE.md
 - README.md
-homepage: http://github.com/dblock/garner
+homepage: http://github.com/artsy/garner
 licenses:
 - MIT
 post_install_message: 
@@ -206,7 +209,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1217542249029147985
+      hash: -3554335930431109647
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:

data/lib/garner/objects/etag.rb

@@ -1,20 +0,0 @@
-module Garner
-  module Objects
-    module ETag
-      class << self
-        # @abstract
-        # Serialize in a way such that the ETag matches that which would 
-        # be returned by Rack::ETag at response time.
-        def from(object)
-          serialization = case object
-            when nil then ""
-            when String then object
-            when Hash then object.respond_to?(:to_json) ? object.to_json : MultiJson.dump(object)
-            else Marshal.dump(object)
-          end
-          %("#{Digest::MD5.hexdigest(serialization)}")
-        end
-      end
-    end
-  end
-end