cashier 0.1.0

data/.rvmrc

@@ -0,0 +1 @@
+rvm use 1.9.2@cashier

data/Gemfile

@@ -0,0 +1,16 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+gem 'redis'
+gem 'redis-namespace'
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "rspec", "~> 2.3.0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+  gem "rcov", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,33 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.2)
+    git (1.2.5)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.8.7)
+    rcov (0.9.9)
+    redis (2.1.1)
+    redis-namespace (0.10.0)
+      redis (< 3.0.0)
+    rspec (2.3.0)
+      rspec-core (~> 2.3.0)
+      rspec-expectations (~> 2.3.0)
+      rspec-mocks (~> 2.3.0)
+    rspec-core (2.3.1)
+    rspec-expectations (2.3.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.3.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  jeweler (~> 1.5.2)
+  rcov
+  redis
+  redis-namespace
+  rspec (~> 2.3.0)

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/Rakefile

@@ -0,0 +1,51 @@
+require 'rubygems'
+require 'bundler'
+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 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "cashier"
+  gem.homepage = "http://github.com/Adman65/cashier"
+  gem.license = "MIT"
+  gem.summary = %Q{Tag based caching for Rails}
+  gem.description = %Q{Associate different cached content with a tag, then expire by tag instead of key}
+  gem.email = "Adman1965@gmail.com"
+  gem.authors = ["Adam Hawkins"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'redis'
+  #  gem.add_runtime_dependency 'redis-namespace'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "cashier #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/cashier.gemspec

@@ -0,0 +1,70 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{cashier}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Adam Hawkins"]
+  s.date = %q{2011-01-05}
+  s.description = %q{Associate different cached content with a tag, then expire by tag instead of key}
+  s.email = %q{Adman1965@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE.txt"
+  ]
+  s.files = [
+    ".rvmrc",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "Rakefile",
+    "VERSION",
+    "cashier.gemspec",
+    "lib/cashier.rb",
+    "lib/cashier/controller_helper.rb",
+    "readme.md",
+    "spec/cashier_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/Adman65/cashier}
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Tag based caching for Rails}
+  s.test_files = [
+    "spec/cashier_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<redis>, [">= 0"])
+      s.add_runtime_dependency(%q<redis-namespace>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, ["~> 2.3.0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+    else
+      s.add_dependency(%q<redis>, [">= 0"])
+      s.add_dependency(%q<redis-namespace>, [">= 0"])
+      s.add_dependency(%q<rspec>, ["~> 2.3.0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<redis>, [">= 0"])
+    s.add_dependency(%q<redis-namespace>, [">= 0"])
+    s.add_dependency(%q<rspec>, ["~> 2.3.0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+  end
+end
+

data/lib/cashier.rb

@@ -0,0 +1,77 @@
+# Cashier
+
+module Cashier
+  extend self
+
+  # used to track all the tags Cashier is storing
+  STORAGE_KEY = 'cashier-tags'
+
+  def perform_caching?
+    ::ApplicationController.perform_caching
+  end
+
+  # shamefully taken straight from Resque.
+  # Thanks Defunkt :D
+
+  # Accepts:
+  #   1. A 'hostname:port' string
+  #   2. A 'hostname:port:db' string (to select the Redis db)
+  #   3. A 'hostname:port/namespace' string (to set the Redis namespace)
+  #   4. A redis URL string 'redis://host:port'
+  #   5. An instance of `Redis`, `Redis::Client`, `Redis::DistRedis`,
+  #      or `Redis::Namespace`.
+  def redis=(server)
+    if server.respond_to? :split
+      if server =~ /redis\:\/\//
+        redis = Redis.connect(:url => server)
+      else
+        server, namespace = server.split('/', 2)
+        host, port, db = server.split(':')
+        redis = Redis.new(:host => host, :port => port,
+          :thread_safe => true, :db => db)
+      end
+      namespace ||= :cashier
+
+      @redis = Redis::Namespace.new(namespace, :redis => redis)
+    elsif server.respond_to? :namespace=
+        @redis = server
+    else
+      @redis = Redis::Namespace.new(:cashier, :redis => server)
+    end
+  end
+
+  # Returns the current Redis connection. If none has been created, will
+  # create a new one.
+  def redis
+    return @redis if @redis
+    self.redis = 'localhost:6379'
+    self.redis
+  end
+
+  def expire(*tags)
+    return unless perform_caching?
+
+    tags.each do |tag|
+      # check to see if the tag exsists
+      # some redis versions return nil or []
+      members = redis.smembers(tags)
+      if members.is_a?(Array)
+        members.each do |cache_key|
+          Rails.cache.delete(cache_key)
+        end
+        redis.del(tag)
+        redis.srem(STORAGE_KEY, tag)
+      end
+    end
+  end
+
+  def tags
+    redis.smembers STORAGE_KEY
+  end
+
+  def wipe
+    expire(*tags)
+  end
+end  
+
+require 'cashier/controller_helper'

data/lib/cashier/controller_helper.rb

@@ -0,0 +1,38 @@
+# Hooks into ApplicationController's write_fragment method.
+# write_fragment is used for action and fragment caching.
+# Create an alias method chain to call our customer method
+# which stores the associated key with the tag in a 
+# Redis Set. Then we can expire all those keys from anywhere
+# in the code using Rails.cache.delete
+#
+# I use alias_method_chain instead of calling 'super'
+# because there is a very rare case where someone 
+# may have redfined 'write_fragment' in their own 
+# controllers. Using an alias method chain
+# keeps those methods intact.
+
+module Cashier
+  module ControllerHelper
+    def self.included(klass)
+      klass.class_eval do
+        def write_fragment_with_tagged_key(key, content, options = nil)
+          if options && options[:tag] && Cashier.perform_caching? 
+            passed_tags = case options[:tag].class.to_s
+                   when 'Proc', 'Lambda'
+                     options[:tag].call(self)
+                   else 
+                     options[:tag]
+                   end
+            tags = passed_tags.is_a?(Array) ? passed_tags : [passed_tags]
+            tags.each do |tag|
+              Cashier.redis.sadd tag, fragment_cache_key(key)
+              Cashier.redis.sadd Cashier::STORAGE_KEY, tag
+            end
+          end
+          write_fragment_without_tagged_key(key, content, options)
+        end
+        alias_method_chain :write_fragment, :tagged_key
+      end
+    end
+  end
+end  

data/readme.md

@@ -0,0 +1,105 @@
+# Cashier: Tag Based Caching for Rails
+
+Manage your cache keys with tags, forget about keys!
+
+## What Is It?
+
+    # 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 your sweeper
+    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'
+
+    # what's cached
+    Cashier.tags
+
+    # sweep all stored keys
+    Cashier.wipe
+
+## 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 two 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' `expire_fragment` method using `alias_method_chain` to run some code that captures the key
+and tag then stores that as a set in redis. Then uses the set members to loop over keys to deleting using `Rails.cache.delete`
+
+## Configuration
+
+Cashier needs Redis to function correctly. Create a yaml file. You may call it `config/cashier.yml`
+
+    development: localhost:6379
+    test: localhost:6379/test
+
+Then write a simple initializer to configure Cahiser. Drop this file in in `config/initializers/cashier.rb`
+
+    resque_config = YAML.load_file(Raisl.root.join 'config', 'cashiser.yml')
+    Cashier.redis = resque_config[Rails.env]
+
+Now in your `application_controller.rb` file just include the module
+
+    class ApplicationController < ActionController::Base
+      include Cashier::ControllerHelper
+    end
+
+Now you're good to go!
+
+## 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/spec/cashier_spec.rb

@@ -0,0 +1,7 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "Cashier" do
+  it "fails" do
+    fail "hey buddy, you should probably rename this file and start specing for real"
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rspec'
+require 'cashier'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  
+end

metadata

@@ -0,0 +1,160 @@
+--- !ruby/object:Gem::Specification 
+name: cashier
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Adam Hawkins
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-01-05 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: redis
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: redis-namespace
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 3
+        - 0
+        version: 2.3.0
+  type: :development
+  prerelease: false
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: jeweler
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 5
+        - 2
+        version: 1.5.2
+  type: :development
+  prerelease: false
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id006
+description: Associate different cached content with a tag, then expire by tag instead of key
+email: Adman1965@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+files: 
+- .rvmrc
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- Rakefile
+- VERSION
+- cashier.gemspec
+- lib/cashier.rb
+- lib/cashier/controller_helper.rb
+- readme.md
+- spec/cashier_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/Adman65/cashier
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: -1411570206960376896
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Tag based caching for Rails
+test_files: 
+- spec/cashier_spec.rb
+- spec/spec_helper.rb