garner 0.4.5 → 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9a593ed7c69343123cf6aa7152da17d9403455cc
+  data.tar.gz: 2c93f44ef0551b09a947a54dd1dcdaac8145dac4
+SHA512:
+  metadata.gz: f1448f9b7506742c5ceaae135f9e193080e76350366ed9e62cde64c7dd47f0dd7064a934dad934e6ae722823f64c5044da92899d6934c57924e29b9836ce3d21
+  data.tar.gz: 61ffea9d8c44c86e5fae7f5db352c0fa83880e6e8d317533e81953d5c36ded5beec5802d5846916fbcbc1f9f243898646e4c0f32aad163a002671a9f53eba837

data/.gitignore

@@ -0,0 +1,7 @@
+Gemfile.lock
+.yardoc
+coverage
+doc
+pkg
+log
+.bundle

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format=documentation
+

data/.rubocop.yml

@@ -0,0 +1,35 @@
+AllCops:
+  Exclude:
+    - vendor/**/*
+
+LineLength:
+  Enabled: false
+
+MethodLength:
+  Enabled: false
+
+ClassLength:
+  Enabled: false
+
+CyclomaticComplexity:
+  Enabled: false
+
+Documentation:
+  # don't require classes to be documented
+  Enabled: false
+
+Encoding:
+  # no need to always specify encoding
+  Enabled: false
+
+DoubleNegation:
+  Enabled: false
+
+RaiseArgs:
+  Enabled: false
+
+RescueModifier:
+  Enabled: false
+
+ModuleFunction:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,13 @@
+services:
+  - mongodb
+  - memcache
+
+rvm:
+  - 1.9.3
+  - 2.1.2
+  - rbx-2
+  - jruby-19mode
+
+env:
+  - MONGOID_VERSION=3
+  - MONGOID_VERSION=4

data/CHANGELOG.md

@@ -0,0 +1,130 @@
+0.5.0 (7/17/2014)
+-----------------
+
+* [#70](https://github.com/artsy/garner/pull/70): Added a `whiny_nils` configuration variable (default: `true`) which determines whether Garner raises exceptions on `nil` bindings - [@fancyremarker](https://github.com/fancyremarker).
+* [#72](https://github.com/artsy/garner/issues/72): Fix: ActiveRecord 4 support, `cache_key` is now in `:nsec` format - [@dblock](https://github.com/dblock).
+* [#74](https://github.com/artsy/garner/pull/74): Removed Jeweler, rewritten .gemspec - [@dblock](https://github.com/dblock).
+* [#76](https://github.com/artsy/garner/pull/76): Added Rubocop, Ruby-style linter - [@dblock](https://github.com/dblock).
+* [#77](https://github.com/artsy/garner/pull/77): Running tests on Ruby 2.0, 2.1.2, Rubinius and JRuby - [@dblock](https://github.com/dblock).
+
+0.4.5 (10/15/2013)
+------------------
+
+* Fixed [#62](https://github.com/artsy/garner/issues/62): fix garnered_find in `Garner::Mixins::Mongoid::Document.garnered_find` to support finding multiple objects, matching Mongoid's find - [@mzikherman](https://github.com/mzikherman).
+* Fixed [#60](https://github.com/artsy/garner/issues/60): don't return cache keys for Mongoid::Document#identify(nil) - [@fancyremarker](https://github.com/fancyremarker).
+
+0.4.4 (7/11/2013)
+-----------------
+
+* Fixed [#47](https://github.com/artsy/garner/issues/47): use a database index when generating proxy binding in `Garner::Mixins::Mongoid::Identity` with multiple `Garner.config.mongoid_identity_fields` - [@dblock](https://github.com/dblock).
+
+0.4.3 (7/5/2013)
+----------------
+
+* Stored `ruby_context` from which a `Garner::Cache::Identity` was initialized as an `attr_accessor` on the object - [@fancyremarker](https://github.com/fancyremarker).
+* Fixed `cache_enabled?` logic and added a `nocache` declaration to `Garner::Cache::Identity` - [@fancyremarker](https://github.com/fancyremarker).
+* Fixed #44, in which the BindingIndex was mistakenly storing values to cache for bindings with a nil canonical binding - [@fancyremarker](https://github.com/fancyremarker).
+* Added `Garner.config.invalidate_mongoid_root` option, to always invalidate the root document when an embedded document is invalidated - [@fancyremarker](https://github.com/fancyremarker).
+
+0.4.2 (6/28/2013)
+-----------------
+
+* Fixed `Caller` strategy when using Rails - [@fancyremarker](https://github.com/fancyremarker).
+
+0.4.1 (6/28/2013)
+-----------------
+
+* Added a `rake benchmark` task to compare different binding key/invalidation strategy pairs - [@fancyremarker](https://github.com/fancyremarker).
+* Improved the performance of the `SafeCacheKey` strategy on virtual `Garner::Mixins::Mongoid::Identity` bindings by properly memoizing the corresponding document - [@fancyremarker](https://github.com/fancyremarker).
+* Improved the performance of the `SafeCacheKey` strategy on class bindings by making 1 database call per key application, instead of 3 - [@fancyremarker](https://github.com/fancyremarker).
+* Removed the `Garner.config.mongoid_binding_key_strategy` and `Garner.config.mongoid_invalidation_key_strategy`. Garner now uses just one default key/invalidation strategy pair for all binding types - [@fancyremarker](https://github.com/fancyremarker).
+* Added an ActiveRecord mixin, `Garner::Mixins::ActiveRecord::Base`, per #35 - [@fancyremarker](https://github.com/fancyremarker).
+* Eliminated the need to `require "garner/mixins/rack"` before declaring `Garner.config.rack_context_key_strategies`, per #35 - [@fancyremarker](https://github.com/fancyremarker).
+* Fixed a bug in binding to classes via the `SafeCacheKey` and `Touch` strategy pair, where class-bound results would not be invalidated when an instance of the class was destroyed - [@fancyremarker](https://github.com/fancyremarker).
+* Added `BindingIndex` binding key/invalidation strategy pair, which uses a two-level lookup for computing cache keys - [@fancyremarker](https://github.com/fancyremarker).
+
+0.4.0 (6/14/2013)
+-----------------
+
+* Complete rewrite of Garner. See [UPGRADING](UPGRADING.md) for details on how to upgrade from Garner 0.3.3 and earlier versions - [@fancyremarker](https://github.com/fancyremarker).
+* Fixed #6: Garner fails if Mongoid not loaded yet - [@fancyremarker](https://github.com/fancyremarker).
+* Closed #12: Support arrays in `Garner.config.mongoid_identity_fields`- [@fancyremarker](https://github.com/fancyremarker).
+* Closed #13: Replace faulty multiple-identity logic- [@fancyremarker](https://github.com/fancyremarker).
+* Fixed #14: Disambiguate binding models by `:id` and `:slug`- [@fancyremarker](https://github.com/fancyremarker).
+* Fixed #15: Remove need for `cache_as` from subclassed Mongoid models - [@fancyremarker](https://github.com/fancyremarker).
+* Closed #23: Abstract all Grape mixins to be more generically Rack mixins - [@fancyremarker](https://github.com/fancyremarker).
+* Closed #24: Implement `garnered_find` method for `Mongoid::Document` classes - [@fancyremarker](https://github.com/fancyremarker).
+* Extracted `Binding`, `Context` and `Identity` as explicit classes from `ObjectIdentity` - [@fancyremarker](https://github.com/fancyremarker).
+* Added support for all ActiveModel-compliant ORMs - [@fancyremarker](https://github.com/fancyremarker).
+* Removed HTTP caching responsibilities from the library entirely - [@fancyremarker](https://github.com/fancyremarker).
+* Introduced a `SafeCacheKey` binding key strategy, which appends subsecond precision to cache keys, to make them usable - [@fancyremarker](https://github.com/fancyremarker).
+* Added a `cache_key` implementation at the class level in Mongoid, which returns the `cache_key` of the most recently updated document in the collection (by `:updated_at`) - [@fancyremarker](https://github.com/fancyremarker).
+* Fixed #29: Restrict the filename string used for the `Caller` context key strategy to just the portion of the path relevant to the current app. In a Rails app, this defaults to Rails.root; otherwise we search for the nearest ancestor directory containing a Gemfile - [@fancyremarker](https://github.com/fancyremarker).
+
+0.3.3 (6/10/2013)
+-----------------
+
+* Fix: parent documents are properly invalidated on creation of an embedded document - [@fancyremarker](https://github.com/fancyremarker).
+
+0.3.2 (5/16/2013)
+-----------------
+
+* Fix: calling `invalidate` on an embedded document in an `embeds_many` relationship - [@fancyremarker](https://github.com/fancyremarker).
+* `Garner::Strategies::Keys::Caller` no longer depends on ActiveSupport - [@oripekelman](https://github.com/oripekelman), [@dblock](https://github.com/dblock).
+* Added `Garner::Strategies::Keys::RequestPost` for POST parameters - [@oripekelman](https://github.com/oripekelman).
+
+0.3.1
+-----
+
+* Do not attempt to fetch again objects in `Garner::Cache::ObjectIdentity.cache_multi` after they were not retrieved from `read_multi`, write them directly to cache - [@dblock](https://github.com/dblock).
+
+0.3
+---
+
+* Added `Garner::Cache::ObjectIdentity.cache_multi` that can now take an array of bindings to return an array of objects - [@dblock](https://github.com/dblock).
+* When fetching an array of objects via `Garner::Cache::ObjectIdentity.cache_multi`, Garner will use `read_multi` if provided by the cache store - [@dblock](https://github.com/dblock).
+
+0.2.1
+-----
+
+* Faster invalidation on Mongoid model creation, only invalidate class - [@dblock](https://github.com/dblock).
+* Invalidate cache after a Mongoid model has been updated or destroyed, not before - [@dblock](https://github.com/dblock).
+
+0.2
+---
+
+* The `Keys::Caller` strategy now allows specifying the caller explicitly by passing a `:caller` as part of the context - [@fancyremarker](https://github.com/fancyremarker).
+* Fix: `invalidate` no longer writes a new index key for each object binding; instead it only deletes existing index keys - [@fancyremarker](https://github.com/fancyremarker).
+* Fix: Invoking Garner helper methods from within an IRB session no longer crashes inside the `Keys::Caller` strategy - [@fancyremarker](https://github.com/fancyremarker).
+
+0.1.3
+-----
+
+* Split `Garner::Objects::ETag` into a configurable `Garner::Strategies::ETags` module, making `Garner::Strategies::ETags::GrapeETag` the new default, for better integration with Grape - [@fancyremarker](https://github.com/fancyremarker).
+* Added `Garner::Strategies::Keys::Key`, that inserts the value of `:key` within the requested context, useful to explicitly declare an element of a cache key - [@dblock](https://github.com/dblock).
+* Fix: `Garner::Strategies::Keys::Caller` excludes lines with `lib/garner`, workaround for Heroku - [@dblock](https://github.com/dblock).
+* Only load Grape and Mongoid mixins when necessary - [@billgloff](https://github.com/billgloff).
+* Fix: Grape API version is properly passed through to key context when using `Garner::Strategies::Keys::Version` - [@fancyremarker](https://github.com/fancyremarker).
+* Added support for caching responses to JSONP requests, via `Garner::Strategies::Keys::Jsonp` - [@fancyremarker](https://github.com/fancyremarker).
+
+0.1.2
+-----
+
+* Fix: `Garner::Mixins::Grape::Cache` improperly handles `nil` cache hits or `cache_enabled?` returning `false` in `cache_or_304` - [@dblock](https://github.com/dblock).
+
+0.1.1
+-----
+
+* Initial public release at [GoRuCo](http://goruco.com), read the [announcement](http://artsy.github.com/blog/2012/05/30/restful-api-caching-with-garner/).
+* Grape mixin takes a single parameter, binding and context are extracted from it - [@dblock](https://github.com/dblock).
+
+0.1
+---
+
+* Initial implementation based on [@fancyremarker](https://github.com/fancyremarker)'s original code.
+* Rack middleware for cache busting, `Garner::Middleware::Cache::Bust` - [@dblock](https://github.com/dblock).
+* Generating ETags, `Garner::Objects::ETag` - [@dblock](https://github.com/dblock).
+* `Garner::Cache::ObjectIdentity` cache - [@dblock](https://github.com/dblock).
+* `Version`, `Caller`, `RequestPath` and `RequestGet` key generation strategies - [@dblock](https://github.com/dblock).
+* `Expiration` cache strategy - [@dblock](https://github.com/dblock).
+* [Grape](https://github.com/intridea/grape) and [Mongoid](https://github.com/mongoid/mongoid/) mixins - [@dblock](https://github.com/dblock).

data/CONTRIBUTING.md

@@ -0,0 +1,118 @@
+Contributing to Garner
+======================
+
+Garner is work of [many of contributors](https://github.com/artsy/garner/graphs/contributors). You're encouraged to submit [pull requests](https://github.com/artsy/garner/pulls), [propose features and discuss issues](https://github.com/artsy/garner/issues).
+
+#### Fork the Project
+
+Fork the [project on Github](https://github.com/artsy/garner) and check out your copy.
+
+```
+git clone https://github.com/contributor/garner.git
+cd garner
+git remote add upstream https://github.com/artsy/garner.git
+```
+
+#### Create a Topic Branch
+
+Make sure your fork is up-to-date and create a topic branch for your feature or bug fix.
+
+```
+git checkout master
+git pull upstream master
+git checkout -b my-feature-branch
+```
+
+#### Bundle Install and Test
+
+Ensure that you can build the project and run tests.
+
+```
+bundle install
+bundle exec rake
+```
+
+#### Write Tests
+
+Try to write a test that reproduces the problem you're trying to fix or describes a feature that you want to build. Add to [spec](spec).
+
+We definitely appreciate pull requests that highlight or reproduce a problem, even without a fix.
+
+#### Write Code
+
+Implement your feature or bug fix.
+
+Ruby style is enforced with [Rubocop](https://github.com/bbatsov/rubocop), run `bundle exec rubocop` and fix any style issues highlighted.
+
+Make sure that `bundle exec rake` completes without errors.
+
+#### Write Documentation
+
+Document any external behavior in the [README](README.md).
+
+#### Update Changelog
+
+Add a line to [CHANGELOG](CHANGELOG.md) under *Next Release*. Make it look like every other line, including your name and link to your Github account.
+
+#### Commit Changes
+
+Make sure git knows your name and email address:
+
+```
+git config --global user.name "Your Name"
+git config --global user.email "contributor@example.com"
+```
+
+Writing good commit logs is important. A commit log should describe what changed and why.
+
+```
+git add ...
+git commit
+```
+
+#### Push
+
+```
+git push origin my-feature-branch
+```
+
+#### Make a Pull Request
+
+Go to https://github.com/contributor/garner and select your feature branch. Click the 'Pull Request' button and fill out the form. Pull requests are usually reviewed within a few days.
+
+#### Rebase
+
+If you've been working on a change for a while, rebase with upstream/master.
+
+```
+git fetch upstream
+git rebase upstream/master
+git push origin my-feature-branch -f
+```
+
+#### Update CHANGELOG Again
+
+Update the [CHANGELOG](CHANGELOG.md) with the pull request number. A typical entry looks as follows.
+
+```
+* [#123](https://github.com/artsy/garner/pull/123): Reticulated splines - [@contributor](https://github.com/contributor).
+```
+
+Amend your previous commit and force push the changes.
+
+```
+git commit --amend
+git push origin my-feature-branch -f
+```
+
+#### Check on Your Pull Request
+
+Go back to your pull request after a few minutes and see whether it passed muster with Travis-CI. Everything should look green, otherwise fix issues and amend your commit as described above.
+
+#### Be Patient
+
+It's likely that your change will not be merged and that the nitpicky maintainers will ask you to do more, or fix seemingly benign problems. Hang on there!
+
+#### Thank You
+
+Please do know that we really appreciate and value your time and work. We love you, really.

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/README.md

@@ -212,6 +212,7 @@ The full list of  `Garner.config` attributes is:
 * `: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.
 * `:invalidate_mongoid_root`: If set to true, invalidates the `_root` document along with any embedded Mongoid document binding. Defaults to `true`.
+* `:whiny_nils`: If set to true, raises an exception when a `nil` binding is specified (i.e., `garner.bind(nil)`). Defaults to `true`.
 
 Contributing
 ------------

data/Rakefile

@@ -0,0 +1,39 @@
+require 'rubygems'
+require 'bundler'
+
+require File.expand_path('../lib/garner/version', __FILE__)
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts 'Run `bundle install` to install missing gems'
+  exit e.status_code
+end
+
+require 'rake'
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+Bundler::GemHelper.install_tasks
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+require 'yard'
+YARD::Rake::YardocTask.new(:doc)
+
+task :benchmark do
+  require 'performance/strategy_benchmark'
+  StrategyBenchmark.new(
+                          n: ENV['N'].try(&:to_i),
+                          d: ENV['D'].try(&:to_i),
+                          r: ENV['R'].try(&:to_i)
+                        ).run!
+end
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new(:rubocop)
+
+task default: [:rubocop, :spec]

data/UPGRADING.md

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