cashier-ftbpro 0.5.0

data/.gitignore

@@ -0,0 +1,9 @@
+spec/dummy/log
+spec/dummy/tmp/pids
+spec/dummy/tmp/cache
+Gemfile.lock
+.rvmrc
+coverage*
+.tags
+.tags_sorted_by_file
+.rspec

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in ..gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Adam Hawkins
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,195 @@
+# Cashier: Tag Based Caching for Rails
+
+Manage your cache keys with tags, forget about keys!
+
+## What Is It?
+
+```ruby
+# in your view
+cache @some_record, :tag => 'some-component'
+
+# in another view
+cache @some_releated_record, :tag => 'some-component'
+
+# can have multiple tags
+cache @something, :tag => ['dashboard', 'settings'] # can expire from either tag
+
+# in an observer
+Cashier.expire 'some-component' # don't worry about keys! Much easier to sweep with confidence
+
+# in your controller
+caches_action :tag => 'complicated-action', :cache_path => proc { |c| 
+  # huge complicated mess of parameters
+  c.params
+}
+
+# need to access the controller?
+caches_action :tag => proc {|c|
+  # c is the controller
+  "users/#{c.current_user.id}/dashboard"      
+}
+
+# in your sweeper, in your observers, in your Resque jobs...wherever
+Cashier.expire 'complicated-action'
+Cashier.expire 'tag1', 'tag2', 'tag3', 'tag4'
+
+# It integrates smoothly with Rails.cache as well, not just the views
+Rails.cache.fetch("user_1", :tag => ["users"]) { User.find(1) }
+Rails.cache.fetch("user_2", :tag => ["users"]) { User.find(2) }
+Rails.cache.fetch("user_3", :tag => ["users"]) { User.find(3) }
+Rails.cache.fetch("admins", :tag => ["users"]) { User.where(role: "Admin").all }
+
+# You can then expire all your users 
+Cashier.expire "users"
+
+# You can also use Rails.cache.write
+Rails.cache.write("foo", "bar", :tag => ["some_tag"])
+
+# what's cached
+Cashier.tags
+
+# sweep all stored keys
+Cashier.clear
+```
+
+## How it Came About
+
+I work on an application that involves all sorts of caching. I try to use action caching whenever I possible.
+I had an index action that had maybe ~20 different combination of filters and sorting. If you want to use
+action caching you have to create a **unique** key for every combination. This created a nice 6 nested loop
+to expire the cache. Once you had pagination, then you have even more combinations of possible cache keys.
+I needed a better solution. I wanted to expire things logically as a viewed them on the page. IE, if 
+a record was added, I wanted to say "expire that page". Problem was that page contained ~1000 different keys.
+So I needed something to store the keys for me and associate them with tags. That's exactly what cashier does.
+Cache associate individual cache keys with a tag, then expire them all at once. This took my 7 layer loop
+down to one line of code. It's also made managing the cache throught my application much easier.
+
+## Why Tag Based Caching is Useful
+
+1. You don't worry about keys. How many times have you created a complicated key for a fragment or action
+then messed up when you tried to expire the cache
+2. Associate your cached content into groups of related content. If you have records that are closely associated
+or displayed together, then you can tag them and expire them at once.
+3. **Expire cached content from anywhere.** If you've done any serious development, you know that Rails caching
+does not work (easily) outside the scope of an HTTP request. If you have background jobs that manipulate data
+or potentially invalidate cached data, you know how much of a pain it is to say `expire_fragment` in some random code.
+4. Don't do anything differently! All you have to do is pass `:tag => 'something'` into `cache` (in the view) or `caches_action` 
+in the controller.
+
+## How it Works
+
+Cashier hooks into Rails' `store_fragment` method using `alias_method_chain` to run some code that captures the key
+and tag then stores that in the rails cache. 
+
+### Adapters
+
+Cashier has 2 adapters for the tags storing, `:cache_store` or `:redis_store`.
+
+**IMPORTANT**: this store is ONLY for the tags, your fragments will still be stored in `Rails.cache`.
+
+#### Setting an adapter for working with the cache as the tags storage
+
+```ruby
+# config/environment/production.rb
+
+config.cashier.adapter = :cache_store 
+# or config.cashier.adapter = :redis_store
+```
+
+#### Setting an adapter for working with Redis as the tags storage
+
+
+```ruby
+# config/environment/production.rb
+config.cashier.adapter.redis = Redis.new(:host => '127.0.0.1', :port => '3697') # or Resque.redis or any existing redis connection
+```
+
+### Why Redis?
+
+The reason Redis was introduced is that while the Rails.cache usage 
+for the tags store is clean and involves no "outer" dependencies, 
+since memcached is limited to read/write, it can slow down the application quite a bit.
+
+If you work with very large arrays of keys and tags, you may see slowness in the cache communication.
+
+Redis was introduces since it has the ability to work with "sets", and 
+you can add/remove tags from this set without reading the entire array.
+
+
+### Benchmarking
+
+Using the cache adapter, this piece of code takes 3 seconds on average
+
+```ruby
+Benchmark.measure do
+  500.times do
+    key = (0...50).map{ ('a'..'z').to_a[rand(26)] }.join
+    tag = (0...50).map{ ('a'..'z').to_a[rand(26)] }.join
+    tag2 = (0...50).map{ ('a'..'z').to_a[rand(26)] }.join
+    Cashier.store_fragment(key, tag, tag2)
+  end
+end
+```
+Using the Redis adapter, the same piece of code takes 0.8 seconds, quite the difference :)
+
+
+### Notifications
+
+Cashier will send out events when things happen inside the library.
+The events are sent out through `ActiveSupport::Notifications` so you can pretty much subscribe to the events from anywhere you want.
+
+Here are the way you can subscribe to the events and use the data from them.
+
+```ruby
+	# Subscribe to the store fragment event, this is fired every time cashier will call the "store_fragment" method
+	# payload[:data] will be something like this: ["key", ["tag1", "tag2", "tag3"]]
+	ActiveSupport::Notifications.subscribe("store_fragment.cashier") do |name, start, finish, id, payload|
+				
+	end
+	
+	# Subscribe to the clear event. (no data)
+	ActiveSupport::Notifications.subscribe("clear.cashier") do |name, start, finish, id, payload|
+				
+	end	
+	
+	# Subscribe to the delete_cache_key event
+	# this event will fire every time there's a Rails.cache.delete with the key
+	# payload[:data] will be the key name that's been deleted from the cache
+	ActiveSupport::Notifications.subscribe("delete_cache_key.cashier") do |name, start, finish, id, payload|
+				
+	end	
+
+	# Subscribe to the o_write_cache_key event
+	# this event will fire every time there's a Rails.cache.write with the key
+	# payload[:data] will be the key name that's been written to the cache
+	ActiveSupport::Notifications.subscribe("write_cache_key.cashier") do |name, start, finish, id, payload|
+				
+	end		
+```
+
+### Notifications use case
+At [Gogobot](http://www.gogobot.com) we have a plugin to invalidate the external CDN cache on full pages for logged out users.
+The usage is pretty unlimited.
+
+If you think we're missing a notification, please do open an issue or be awesome and do it yourself and open a pull request.
+
+## Contributors
+
+* [twinturbo](http://twitter.com/adman65) - Initial Implementation
+* [KensoDev](http://twitter.com/kensodev) - Adding Redis support (Again \o/)
+* [KensoDev](http://twitter.com/kensodev) - Adding plugins support for callback methods
+
+## Contributing to Cashier
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+## Copyright
+
+Copyright (c) 2010 Adam Hawkins. See LICENSE.txt for
+further details.

data/Rakefile

@@ -0,0 +1,11 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+task :default => :spec

data/cashier.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "cashier/version"
+
+Gem::Specification.new do |s|
+  s.name        = "cashier-ftbpro"
+  s.version     = Cashier::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Adam Hawkins"]
+  s.email       = ["me@broadcastingadam.com"]
+  s.homepage    = "https://github.com/threadedlabs/cashier"
+  s.summary     = %q{Tag based caching for Rails using Redis or Memcached}
+  s.description = %q{Associate different cached content with a tag, then expire by tag instead of key}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency 'rails', '~> 3.0'
+
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'rspec-rails'
+  s.add_development_dependency 'dalli'
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'redis', '~> 2.2.0'
+end

data/lib/cashier.rb

@@ -0,0 +1,257 @@
+module Cashier
+
+  CACHE_KEY = 'cashier-tags'
+
+  def self.container_cache_key(tag)
+    "cashier-tag-containers:#{tag}"
+  end
+
+  class << self
+
+    # Public: whether the module will perform caching or not. this is being set in the application layer .perform_caching configuration
+    #
+    # Examples
+    #
+    #   Cashier.perform_caching?
+    #   # => true
+    #
+    def perform_caching?
+      ::ApplicationController.perform_caching
+    end
+
+    # Public: store a fragment with an array of tags for this fragment.
+    #
+    # fragment - cached fragment.
+    # tags - array of tags you want to assign this fragments.
+    #
+    # Examples
+    #
+    #   Cachier.store_fragment('foo', 'tag1', 'tag2', 'tag3')
+    #
+    def store_fragment(fragment, *tags)
+      return unless perform_caching?
+
+      tags = tags.flatten
+      tags = canonize_tags(tags)
+
+      ActiveSupport::Notifications.instrument("store_fragment.cashier", :data => [fragment, tags]) do
+        tags.each do |tag|
+          # store the fragment
+          adapter.store_fragment_in_tag(fragment, tag)
+        end
+
+         # now store the tag for book keeping
+        adapter.store_tags(tags)
+      end
+    end
+
+    # Public: expire tags. expiring the keys 'assigned' to the tags you expire and removes the tags from the tags list
+    # 
+    # tags - array of tags to expire.
+    # 
+    # Examples
+    #
+    #   Cashier.expire('tag1', 'tag2')
+    # 
+    def expire(*tags)
+      return unless perform_caching?
+
+      # add tags of container fragments to expired tags list
+      tags = canonize_tags(tags)
+      containers = adapter.get_tags_containers(tags) || []
+      tags = (tags + containers).compact.uniq
+
+      ActiveSupport::Notifications.instrument("expire.cashier", :data => tags) do
+        # delete them from the cache
+        tags.each do |tag|
+          fragment_keys = adapter.get_fragments_for_tag(tag)
+
+          fragment_keys.each do |fragment_key|
+            Rails.cache.delete(fragment_key)
+          end
+
+          adapter.delete_tag(tag)
+        end
+
+        # now remove them from the list
+        # of stored tags
+        adapter.remove_tags(tags)
+      end
+    end
+
+    # Public: returns the array of tags stored in the tags store.
+    #
+    #
+    # Examples
+    #
+    #   Cashier.tags
+    #   # => ['tag1', 'tag2']
+    #
+    def tags
+      adapter.tags
+    end
+
+    # Public: clears the tags.
+    #
+    #
+    # Examples
+    #
+    #   Cashier.clear
+    #
+    def clear
+      ActiveSupport::Notifications.instrument("clear.cashier") do
+        adapter.clear
+      end
+    end
+
+    # Public: get all the keys names as an array.
+    #
+    #
+    # Examples
+    #
+    #   Cachier.keys
+    #   # => ['key1', 'key2', 'key3']
+    #
+    def keys
+      adapter.keys
+    end
+
+    # Public: get all the keys for a specific tag as an array.
+    #
+    #
+    # Examples
+    #
+    #   Cashier.tags_for('tag1')
+    #   # => ['key1', 'key2', 'key3']
+    #
+    def keys_for(tag)
+      tag = canonize_tags(tag)
+      adapter.get_fragments_for_tag(tag)
+    end
+
+    # Public: adapter which is used by cashier.
+    #
+    # Examples
+    #
+    #   Cashier.adapter
+    #   # => Cashier::Adapters::CacheStore
+    # 
+    #   Cashier.adapter
+    #   # => Cashier::Adapters::RedisStore
+    #
+    def adapter
+      if @@adapter == :cache_store
+        Cashier::Adapters::CacheStore
+      else
+        Cashier::Adapters::RedisStore
+      end
+    end
+
+    # Public: set the adapter the Cashier module will use to store the keys
+    #
+    # cache_adapter - :cache_store / :redis_store
+    #
+    # Examples
+    #
+    #   Cashier.adapter = :redis_store
+    #
+    def adapter=(cache_adapter)
+      @@adapter = cache_adapter
+    end
+
+    # Public: add tags of a container fragment into the current container stack (used internally by ActiveSupport::Notifications)
+    #
+    # cache_adapter - :cache_store / :redis_store
+    #
+    # Examples
+    #
+    #   Cashier.push_container(['section2'])
+    #
+    def push_container(*tags)
+      return unless perform_caching?
+      @@container_stack ||= []
+      tags = canonize_tags(tags)
+      adapter.add_tags_containers(tags, @@container_stack)
+      @@container_stack.push tags
+    end
+    
+    # Public: remove tags of a container fragment from the current container stack
+    #
+    # cache_adapter - :cache_store / :redis_store
+    #
+    # Examples
+    #
+    #   Cashier.pop_container()
+    #
+    def pop_container()
+      return unless perform_caching?
+      @@container_stack ||= []
+      container = @@container_stack.pop  
+      container
+    end
+
+    # Public: get the tags of containers for the given fragment tags
+    #
+    # cache_adapter - :cache_store / :redis_store
+    #
+    # Examples
+    #
+    #   Cashier.get_containers(['article1'])
+    #   # => ['section2', 'section3']
+    #
+    def get_containers(tags)
+      tags = canonize_tags(tags)
+      adapter.get_tags_containers(tags)
+    end
+
+
+    # Public: canonize tags: convert ActiveRecord objects to string (inc. id)
+    #
+    # cache_adapter - :cache_store / :redis_store
+    #
+    # Examples
+    #
+    #   Cashier.canonize_tags([1, :a, Article.find(123)])
+    #   # => [1, :a, "Article-123"]
+    #
+    def canonize_tags(tags)
+      tags = [tags || []].flatten
+      tags.map do |tag| 
+        if tag.is_a?(ActiveRecord::Base) 
+          "#{tag.class.name}-#{tag.to_param}"
+        else
+          tag 
+        end
+      end
+    end
+
+  end
+
+end
+
+require 'rails'
+require 'cashier/railtie'
+require 'cashier/adapters/cache_store'
+require 'cashier/adapters/redis_store'
+
+# Connect cashier up to the low level Rails cache:
+
+# When Rails cache is missing a fragment, it is going to be rendered - add its tags to the container stack
+ActiveSupport::Notifications.subscribe("cache_read.active_support") do |*args|
+  payload = ActiveSupport::Notifications::Event.new(*args).payload
+  tag = payload[:tag]
+  # if not a cache hit, we're going to build the fragment - add to container stack
+  Cashier.push_container(*tag) if tag && !payload[:hit]
+end
+
+# When a fragment was written into Rails cache it is now rendered and done - remove its tags from the container stack
+ActiveSupport::Notifications.subscribe("cache_write.active_support") do |*args|
+  payload = ActiveSupport::Notifications::Event.new(*args).payload
+  tag = payload[:tag]
+
+  if tag
+    Cashier.store_fragment(payload[:key], tag)
+    Cashier.pop_container
+  end
+end
+