garner 0.3.3 → 0.4.0

data/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2012 Art.sy, Frank Macreery, Daniel Doubrovkine & Contributors
+Copyright (c) 2012-2013 Artsy, Frank Macreery, Daniel Doubrovkine & contributors.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,91 +1,58 @@
-Garner [![Build Status](https://secure.travis-ci.org/artsy/garner.png)](http://travis-ci.org/artsy/garner)
+Garner [![Build Status](https://secure.travis-ci.org/artsy/garner.png)](http://travis-ci.org/artsy/garner) [![Dependency Status](https://gemnasium.com/artsy/garner.png)](https://gemnasium.com/artsy/garner) [![Coverage Status](https://coveralls.io/repos/artsy/garner/badge.png)](https://coveralls.io/r/artsy/garner)
 ======
 
-Garner is a practical Rack-based cache implementation for RESTful APIs with support for HTTP 304 Not Modified based on time and ETags, model and instance binding and hierarchical invalidation. Garner is currently targeted at [Grape](https://github.com/intridea/grape), other systems may need some work.
+Garner is a cache layer for Ruby and Rack applications, supporting model and instance binding and hierarchical invalidation. To "garner" means to gather data from various sources and to make it readily available in one place, kind of like a cache!
 
-To "garner" means to gather data from various sources and to make it readily available in one place, kind-of like a cache!
+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.
 
-Usage
------
+Stable Release
+--------------
 
-Add Garner to Gemfile with `gem "garner"` and run `bundle install`. Include the Garner mixin into your API. Currently Grape is supported out of the box. It's also recommended to prevent clients from caching dynamic data by default using the `Garner::Middleware::Cache::Bust` middleware. See below for a detailed explanation.
+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).
 
-Note that if you are using Grape, `gem "garner"` must be listed AFTER `gem "grape"` in the Gemfile (see [#6](https://github.com/artsy/garner/issues/6)).
+Usage
+-----
 
-```ruby
-class API < Grape::API
-  use Garner::Middleware::Cache::Bust
-  helpers Garner::Mixins::Grape::Cache
-end
-```
+### Application Logic Caching
 
-To cache a value, invoke `cache` from within your API. Without any parameters it generates a key based on the source code location, request parameters and path, and stores the value in the cache configured as `Garner.config.cache`. The cache is automatically `Rails.cache` when mounted in Rails and an instance of `ActiveSupport::Cache::MemoryStore` otherwise.
+Add Garner to your Gemfile with `gem "garner"` and run `bundle install`. Next, include the appropriate mixin in your app:
 
-``` ruby
-get "/" do
-  cache do
-    { counter: 42 }
-  end
-end
-```
+* For plain-old Ruby apps, `include Garner::Cache::Context`.
+* For Rack apps, `include Garner::Mixins::Rack`. (This provides saner defaults for injecting request parameters into the cache context key. More on cache context keys later.)
 
-To enable support for the date-based `If-Modified-Since` and the ETag-based `If-None-Match`, use `cache_or_304`. If the data hasn't changed, the API will return `304 Not Modified` without a cache miss. For example, if the inside of a cached block is a database query, it will not be executed the second time. This is possible because Garner stores an entry for every cache binding with the last-modified timestamp and ETag.
+Now, to use Garner's cache, invoke `garner` with a logic block from within your application. The result of the block will be computed once, and then stored in the cache.
 
 ``` ruby
-get "/" do
-  cache_or_304 do
-    { counter: 42 }
+get "/system/counts/all" do
+  # Compute once and cache for subsequent reads
+  garner do
+    {
+      "orders_count" => Order.count,
+      "users_count"  => User.count
+    }
   end
 end
 ```
 
-The cached value can also be bound to other models. For example, if a user has an address that may or may not change when the user is saved, you will want the cached address to be invalidated every time the user record changes.
+The cached value can be bound to a particular model instance. For example, if a user has an address that may or may not change when the user is saved, you will want the cached address to be invalidated every time the user record is modified.
 
 ``` ruby
 get "/me/address" do
-  cache_or_304({ bind: [ User, current_user.id ] }) do
+  # Invalidate when current_user is modified
+  garner.bind(current_user) do
     current_user.address
   end
 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.
+ORM Integrations
+----------------
 
-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
-```
+### Mongoid
 
-
-Binding Strategies
-------------------
-
-The binding parameter 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. If no bind argument is specified, the subsequent block result will remain valid until it expires due to natural causes (e.g., passage of default memcached expiry, or memcached overflow). Here are some examples of how to use the bind option.
-
-* `bind: { klass: Widget, object: { id: params[:id] } }` will cause the subsequent block result to be invalidated on any change to the `Widget` object whose `id` attribute equals `params[:id]`.
-* `bind: { klass: User, object: { id: current_user.id } }` will cause the subsequent block result 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.
-* `bind: { klass: Widget }` will cause the subsequent block result to be invalidated on any change to any object of class `Widget`. This is the appropriate strategy for index paths like `/widgets`.
-* `bind: [{ klass: Widget }, { klass: User, object: { id: current_user.id } }]` will cause the subsequent block result to be invalidated on any change to either the current user, or any object of class `Widget`.
-
-Bind supports some nice shorthands.
-
-* `bind: [Widget]` is shorthand for `bind: { klass: Widget }`
-* `bind: [Widget, params[:id]]` is shorthand for `bind: { klass: Widget, object: { id: params[:slug] } }`
-* `bind: [User, { id: current_user.id }]` is shorthand for `bind: { klass: User, object: { id: current_user.id } }`
-* `bind: [[Widget], [User, { id: current_user.id }]]` is shorthand for `bind: [{ klass: Widget }, { klass: User, object: { id: current_user.id } }]`
-
-Invalidation
-------------
-
-You must take care of data invalidation on save. Garner currently includes a mixin with support for [Mongoid](https://github.com/mongoid/mongoid). Extend `Mongoid::Document` as follows (eg. in `config/initializers/mongoid_document.rb`).
+To use Mongoid documents and classes for Garner bindings, use `Garner::Mixins::Mongoid::Document`. You can set it up in an initializer:
 
 ``` ruby
 module Mongoid
@@ -95,96 +62,102 @@ module Mongoid
 end
 ```
 
-Please contribute other invalidation mixins.
+This enables binding to Mongoid classes as well as instances. For example:
 
-Role-Based Caching
-------------------
-
-Role-Based caching is a subset of the generic problem of binding data to groups of other objects. For example, a `Widget` may have a different representation for an `admin` vs. a `user`. In Garner you can inject something called a "key strategy" into the current key generation pipeline. A strategy is a plain module that must implement two methods: `apply` and `field`. The former applies a strategy to a key within a context and the latter is a unique name that is produced by the strategy.
+```ruby
+get "/system/counts/orders" do
+  # Invalidate when any order is created, updated or deleted
+  garner.bind(Order) do
+    {
+      "orders_count" => Order.count,
+    }
+  end
+end
+```
 
-The following example introduces the role of the current user into the cache key.
+What if you want to bind a cache result to a persisted object that hasn't been retrieved yet? Consider the example of caching a particular order without a database query:
 
-``` ruby
-module MyApp
-  module Garner
-    module RoleStrategy
-      class << self
-        def field
-          :role
-        end
-        def apply(key, context = {})
-          key = key ? key.dup : {}
-          key[:role] = current_user.role
-          key
-        end
-      end
-    end
+```ruby
+get "/order/:id" do
+  # Invalidate when Order.find(params[:id]) is modified
+  garner.bind(Order.identify(params[:id])) do
+    Order.find(params[:id])
   end
 end
 ```
 
-Garner key strategies are applied in order and can be currently set at application startup time.
+In the above example, the `Order.identify` call will not result in a database query. Instead, it just communicates to Garner's cache sweeper that whenever the order with identity `params[:id]` is updated, this cache result should be invalidated. The `identify` method is provided by the Mongoid mixin. To use it, you should configure `Garner.config.mongoid_identity_fields`, e.g.:
 
+```ruby
+Garner.configure.do |config|
+  config.mongoid_identity_fields = [:_id, :_slugs]
+end
 ```
-Garner::Cache::ObjectIdentity::KEY_STRATEGIES = [
-  Garner::Strategies::Keys::Caller, # support multiple calls from the same function
-  MyApp::Garner::RoleStrategy, # custom strategy for role-based access
-  Garner::Strategies::Keys::RequestPath # injects the HTTP request's URL
-]
+
+These may be scalar or array fields. Only uniquely-constrained fields should be used here; otherwise you risk caching the same result for two different blocks.
+
+The Mongoid mixin also provides helper methods for cached `find` operations. The following code will fetch an order once (via `find`) from the database, and then fetch it from the cache on subsequent requests. The cache will be invalidated whenever the underlying `Order` changes in the database.
+
+```ruby
+order = Order.garnered_find(3)
 ```
 
-This method of registration does need improvement, please contribute.
+Explicit invalidation should be unnecessary, since callbacks are declared to invalidate the cache whenever a Mongoid object is created, updated or destroyed, but for special cases, `invalidate_garner_caches` may be called on a Mongoid object or class:
 
-Available Key Strategies
-------------------------
+```ruby
+Order.invalidate_garner_caches
+Order.find(3).invalidate_garner_caches
+```
 
-* `Garner::Strategies::Keys::Caller` inserts the calling file and line number, allowing multiple calls from the same function to generate different keys. The caller can be specified explicitly by passing a value for `:caller` in the requesting context.
-* `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::RequestPost` inserts the value of HTTP request's POST 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.
+### ActiveRecord
 
-Fetching Objects Directly from Cache
-------------------------------------
+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 supports fetching objects or collections of objects directly from cache by supplying a binding or an array of bindings.
 
-``` ruby
-object_id = ...
-Garner::Cache::ObjectIdentity.cache({ bind: [ Model, { id: object_id }] }) do
-  Model.find(object_id)
-end
-```
+Under The Hood: Bindings
+------------------------
 
-When fetching directly from the cache, it may be useful to supply a generational cache key in addition to the bindings. (When the generational component changes, the cache result is invalidated independent of the bindings' state.) E.g.:
+As we've seen, a cache result can be bound to a model instance (e.g., `current_user`) or a virtual instance reference (`Order.identify(params[:id])`). In some cases, we may want to compose bindings:
 
 ```ruby
-Garner::Cache::ObjectIdentity.cache(bind: [Model, {id: object_id}], key: {v: '1'}) do
-  # ...
+get "/system/counts/all" do
+  # Invalidate when any order or user is modified
+  garner.bind(Order).bind(User) do
+    {
+      "orders_count" => Order.count,
+      "users_count"  => User.count
+    }
+  end
 end
 ```
 
-Or, using the Grape mix-in:
+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`.
+
+
+Under The Hood: Cache Context Keys
+----------------------------------
+
+Explicit cache context keys are usually unnecessary in Garner. Given a cache binding, Garner will compute an appropriately unique cache key. Moreover, in the context of `Garner::Mixins::Rack`, Garner will compose the following key factors by default:
+
+* `Garner::Strategies::Context::Key::Caller` inserts the calling file and line number, allowing multiple calls from the same function to generate different results.
+* `Garner::Strategies::Context::Key::RequestGet` inserts the value of HTTP request's GET parameters into the cache key when `:request` is present in the context.
+* `Garner::Strategies::Context::Key::RequestPost` inserts the value of HTTP request's POST parameters into the cache key when `:request` is present in the context.
+* `Garner::Strategies::Context::Key::RequestPath` inserts the value of the HTTP request's path into the cache key when `:request` is present in the context.
+
+Additional key factors may be specified explicitly using the `key` method. To see a specific example of this in action, let's consider the case of role-based caching. For example, an order may have a different representation for an admin versus an ordinary user:
 
 ```ruby
-cache_or_304(bind: [User, current_user.id], key: {v: '1'}) do
-  # ...
+get "/order/:id" do
+  garner.bind(Order.identify(params[:id])).key({ role: current_user.role }) do
+    Order.find(params[:id])
+  end
 end
 ```
 
-Various cache stores, including Memcached, support bulk read operations. The [Dalli gem](https://github.com/mperham/dalli) exposes this via the `read_multi` method. When invoked with a collection of bindings, Garner will call `read_multi` if available. This may significantly reduce the number of network roundtrips to the cache servers.
+As with bindings, context key factors may be composed by calling `key()` multiple times on a `garner` invocation. The keys will be applied in the order in which they are called.
 
-``` ruby
-object_ids = [ ... ]
-bindings = object_ids.map do |object_id|
-  { bind: [ Model, { id: object_id }]}
-end
-Garner::Cache::ObjectIdentity.cache_multi(bindings) do |binding|
-  # the object binding is passed into the block for every cache miss
-  Model.find(binding[:bind][1][:id])
-end
-```
 
 Configuration
 -------------
@@ -197,27 +170,35 @@ Garner.configure do |config|
 end
 ```
 
-Preventing Clients from Caching Dynamic Data
---------------------------------------------
+The full list of  `Garner.config` attributes is:
 
-Generally, dynamic data cannot have a well-defined expiration time. Therefore, we must tell the client not to cache it. This can be accomplished using the `Garner::Middleware::Cache::Bust` middleware, executed after any API call. The middleware adds a `Cache-Control` and an `Expires` header.
-
-```
-Cache-Control: private, max-age=0, must-revalidate
-Expires: Fri, 01 Jan 1990 00:00:00 GMT
+* `:global_cache_options`: A hash of options to be passed on every call to `Garner.config.cache`, like `{ :expires_in => 10.minutes }`. Defaults to `{}`
+* `:context_key_strategies`: An array of context key strategies, to be applied in order. Defaults to `[Garner::Strategies::Context::Key::Caller]`
+* `:rack_context_key_strategies`: Rack-specific context key strategies. Defaults to:
+```ruby
+[
+  Garner::Strategies::Context::Key::Caller,
+  Garner::Strategies::Context::Key::RequestGet,
+  Garner::Strategies::Context::Key::RequestPost,
+  Garner::Strategies::Context::Key::RequestPath
+]
 ```
-
-The `private` option of the `Cache-Control` header instructs the client that it is allowed to store data in a private cache (unnecessary, but is known to work around overzealous cache implementations), `max-age` that it must check with the server every time it needs this data and `must-revalidate` prevents gateways from returning a response if your API server is unreachable. An additional `Expires` header will make double-sure the entire request expires immediately.
+* `: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.
 
 Contributing
 ------------
 
-Fork the project. Make your feature addition or bug fix with tests. Send a pull request. Bonus points for topic branches.
+Fork the project. Make your feature addition or bug fix with tests. Send a pull request.
 
 Copyright and License
 ---------------------
 
-MIT License, see [LICENSE](https://github.com/dblock/garner/blob/master/LICENSE.md) for details.
+MIT License, see [LICENSE](LICENSE.md) for details.
 
-(c) 2012 [Art.sy Inc.](http://artsy.github.com), [Frank Macreery](https://github.com/macreery), [Daniel Doubrovkine](https://github.com/dblock) and [Contributors](https://github.com/dblock/garner/blob/master/CHANGELOG.md)
+(c) 2012-2013 [Artsy](http://artsy.github.com), [Frank Macreery](https://github.com/fancyremarker), [Daniel Doubrovkine](https://github.com/dblock) and [contributors](CHANGELOG.md).
 

data/lib/garner/cache/binding.rb

@@ -0,0 +1,58 @@
+# Set up Garner configuration parameters
+Garner.config.option(:binding_key_strategy, {
+  :default => Garner::Strategies::Binding::Key::SafeCacheKey
+})
+Garner.config.option(:binding_invalidation_strategy, {
+  :default => Garner::Strategies::Binding::Invalidation::Touch
+})
+
+module Garner
+  module Cache
+    module Binding
+
+      # Override this method to use a custom key strategy.
+      #
+      # @return [Object] The strategy to be used for instances of this class.
+      def key_strategy
+        Garner.config.binding_key_strategy
+      end
+
+      # Apply the cache key strategy to this binding.
+      def garner_cache_key
+        key_strategy.apply(self)
+      end
+
+      # Override this method to use a custom invalidation strategy.
+      #
+      # @return [Object] The strategy to be used for instances of this class.
+      def invalidation_strategy
+        Garner.config.binding_invalidation_strategy
+      end
+
+      # Apply the invalidation strategy to this binding.
+      def invalidate_garner_caches
+        invalidation_strategy.apply(self)
+      end
+
+      protected
+      def _garner_after_create
+        if invalidation_strategy.apply_on_callback?(:create)
+          invalidation_strategy.apply(self)
+        end
+      end
+
+      def _garner_after_update
+        if invalidation_strategy.apply_on_callback?(:update)
+          invalidation_strategy.apply(self)
+        end
+      end
+
+      def _garner_after_destroy
+        if invalidation_strategy.apply_on_callback?(:destroy)
+          invalidation_strategy.apply(self)
+        end
+      end
+
+    end
+  end
+end

data/lib/garner/cache/context.rb

@@ -0,0 +1,27 @@
+# Set up Garner configuration parameters
+Garner.config.option(:context_key_strategies, {
+  :default => [Garner::Strategies::Context::Key::Caller]
+})
+
+module Garner
+  module Cache
+    module Context
+
+      # Instantiate a context-appropriate cache identity.
+      #
+      # @example
+      #   garner.bind(current_user) do
+      #     { count: current_user.logins.count }
+      #   end
+      # @return [Garner::Cache::Identity] The cache identity.
+      def garner(&block)
+        identity = Garner::Cache::Identity.new
+        Garner.config.context_key_strategies.each do |strategy|
+          identity = strategy.apply(identity, self)
+        end
+
+        block_given? ? identity.fetch(&block) : identity
+      end
+    end
+  end
+end

data/lib/garner/cache/identity.rb

@@ -0,0 +1,45 @@
+module Garner
+  module Cache
+    class Identity
+      attr_accessor :bindings, :key_hash, :options_hash
+
+      def initialize
+        @bindings = []
+        @key_hash = {}
+
+        # Set up options hash with defaults
+        @options_hash = Garner.config.global_cache_options || {}
+        @options_hash.merge!({ :expires_in => Garner.config.expires_in })
+      end
+
+      def fetch(&block)
+        Garner::Cache.fetch(@bindings, @key_hash, @options_hash, &block)
+      end
+
+      # Bind this cache identity to a (bindable) object.
+      #
+      # @param object [Object] An object; should support configured binding strategy.
+      def bind(object, &block)
+        @bindings << object
+        block_given? ? fetch(&block) : self
+      end
+
+      # Merge the given hash into the cache identity's key hash.
+      #
+      # @param hash [Hash] A hash to merge on top of the current key hash.
+      def key(hash, &block)
+        @key_hash.merge!(hash)
+        block_given? ? fetch(&block) : self
+      end
+
+      # Merge the given hash into the cache identity's cache options.
+      # Any cache_options supported by Garner.config.cache may be passed.
+      #
+      # @param hash [Hash] Options to pass to Garner.config.cache.
+      def options(hash, &block)
+        @options_hash.merge!(hash)
+        block_given? ? fetch(&block) : self
+      end
+    end
+  end
+end

data/lib/garner/cache.rb

@@ -0,0 +1,41 @@
+module Garner
+  module Cache
+
+    # Fetch a result from cache.
+    #
+    # @param bindings [Array] Objects to which the the cache result should be
+    #        bound. These objects' keys are injected into the compound cache key.
+    # @param key_hash [Hash] Hash to comprise the compound cache key.
+    # @param options_hash [Hash] Options to be passed to Garner.config.cache.
+    def self.fetch(bindings, key_hash, options_hash, &block)
+      if (compound_key = compound_key(bindings, key_hash))
+        result = Garner.config.cache.fetch(compound_key, options_hash) do
+          yield
+        end
+        Garner.config.cache.delete(compound_key) unless result
+      else
+        result = yield
+      end
+      result
+    end
+
+    private
+    def self.compound_key(bindings, key_hash)
+      binding_keys = bindings.map(&:garner_cache_key).compact
+
+      if binding_keys.size == bindings.size
+        # All bindings have non-nil cache keys, proceed.
+        {
+          :binding_keys => binding_keys,
+          :context_keys => key_hash
+        }
+      else
+        # A nil cache key was generated. Skip caching.
+        # TODO: Replace this ill-documented "nil to skip" behavior
+        # with exceptions on inability to generate a cache key.
+        nil
+      end
+    end
+
+  end
+end

data/lib/garner/config.rb

@@ -1,7 +1,6 @@
 module Garner
 
   class << self
-
     # Set the configuration options. Best used by passing a block.
     #
     # @example Set up configuration options.
@@ -9,7 +8,7 @@ module Garner
     #     config.cache = Rails.cache
     #   end
     #
-    # @return [ Config ] The configuration object.
+    # @return [Config] The configuration object.
     def configure
       block_given? ? yield(Garner::Config) : Garner::Config
     end
@@ -21,10 +20,10 @@ module Garner
 
     # Current configuration settings.
     attr_accessor :settings
-    
+
     # Default configuration settings.
     attr_accessor :defaults
-    
+
     @settings = {}
     @defaults = {}
 
@@ -33,10 +32,10 @@ module Garner
     # @example Define the option.
     #   Config.option(:cache, :default => nil)
     #
-    # @param [ Symbol ] name The name of the configuration option.
-    # @param [ Hash ] options Extras for the option.
+    # @param [Symbol] name The name of the configuration option.
+    # @param [Hash] options Extras for the option.
     #
-    # @option options [ Object ] :default The default value.
+    # @option options [Object] :default The default value.
     def option(name, options = {})
       defaults[name] = settings[name] = options[:default]
 
@@ -54,23 +53,29 @@ module Garner
         end
       RUBY
     end
-    
-    # Returns the default cache store, either Rails.cache or an instance of ActiveSupport::Cache::MemoryStore.
+
+    # Returns the default cache store, either Rails.cache or an instance
+    # of ActiveSupport::Cache::MemoryStore.
     #
     # @example Get the default cache store
     #   config.default_cache
     #
-    # @return [ Cache ] The default cache store instance.
+    # @return [Cache] The default cache store instance.
     def default_cache
-      defined?(Rails) && Rails.respond_to?(:cache) ? Rails.cache : ::ActiveSupport::Cache::MemoryStore.new
+      if defined?(Rails) && Rails.respond_to?(:cache)
+        Rails.cache
+      else
+        ::ActiveSupport::Cache::MemoryStore.new
+      end
     end
 
-    # Returns the cache, or defaults to Rails cache when running in Rails or an instance of ActiveSupport::Cache::MemoryStore otherwise.
+    # Returns the cache, or defaults to Rails cache when running in Rails
+    # or an instance of ActiveSupport::Cache::MemoryStore otherwise.
     #
     # @example Get the cache.
     #   config.cache
     #
-    # @return [ Cache ] The configured cache or a default cache instance.
+    # @return [Cache] The configured cache or a default cache instance.
     def cache
       settings[:cache] = default_cache unless settings.has_key?(:cache)
       settings[:cache]
@@ -81,11 +86,34 @@ module Garner
     # @example Set the cache.
     #   config.cache = Rails.cache
     #
-    # @return [ Cache ] The newly set cache.
+    # @return [Cache] The newly set cache.
     def cache=(cache)
       settings[:cache] = cache
     end
 
+    # Returns the default caller root, as determined by
+    # Garner::Strategies::Context::Key::Caller.
+    #
+    # @return [String] The default caller_root path.
+    def default_caller_root
+      Garner::Strategies::Context::Key::Caller.default_root
+    end
+
+    # Returns the manually configured caller_root, or a default.
+    #
+    # @return [String] The configured caller_root or a default.
+    def caller_root
+      settings[:caller_root] = default_caller_root unless settings.has_key?(:caller_root)
+      settings[:caller_root]
+    end
+
+    # Sets the caller_root to use.
+    #
+    # @return [String] The newly set caller_root.
+    def caller_root=(caller_root)
+      settings[:caller_root] = caller_root
+    end
+
     # Reset the configuration options to the defaults.
     #
     # @example Reset the configuration options.
@@ -93,7 +121,10 @@ module Garner
     def reset!
       settings.replace(defaults)
     end
-   
+
+    # Default cache options
+    option(:global_cache_options, :default => {})
+
     # Default cache expiration time.
     option(:expires_in, :default => nil)
   end