merb-cache 0.9.7 → 0.9.8

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2008 Alex Boussinet
+Copyright (c) 2008 Ben Burkert
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -17,4 +17,4 @@ 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.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -1,160 +1,224 @@
-= merb-cache
+merb-cache
+==========
 
-A plugin for the Merb framework that provides caching
+A plugin for the Merb framework that provides caching stores,
+strategies and helpers.
 
-Currently supported methods:
 
-- page caching:
-- action caching
-- fragment caching
-- object caching
 
-Implemented cache stores:
+Tutorial
+==========
 
-- memory
-- memcache
-- file
-- database (sequel, datamapper, activerecord)
+Stores usually set up in application init file
+(init.rb) or environment specific init file (so you can
+use different stores for production, staging and development
+environment if you need to).
 
-== Quick intro
-  With fragment caching, you can mix dynamic and static content.
+# create a fundamental memcache store named :memcached for localhost
 
-  With action caching, the whole template is cached
-  but the before filters are still processed.
-
-  With page caching, the whole template is put in html files in a special
-  directory in order to be handled directly without triggering Merb.
-
-== Quick API
-
-=== Merb::Controller class methods
-  cache_action(action, expiration)
-  cache_actions(action, [action, expiration], ...)
-  cache_page(action, expiration)
-  cache_pages(action, [action, expiration], ...)
-
-=== Merb::Controller instance methods
-  expire_page(key)
-  cached_page?(key)
-  expire_all_pages()
-
-  expire_action(key)
-  cached_action?(key)
-
-  cached?(key)
-  cache_get(key)
-  cache_set(key, data, expiration)
-  expire(key)
-  expire_all()
-
-=== Inside your template
-  cache(key, expiration) do ... end
-
-  # expiration is given in minutes
-
-  # key can be a string or a hash
-  # possible keys when it's a hash:
-  # :key (full key)
-  # :params (array of params to be added to the key)
-  # :action, :controller
-  # :match (true or partial key)
-
-  # Don't forget to look at the specs !!
-
-== Specs
-  $ rake specs:<cache_store>
-  example:
-  $ rake specs:memory
-  $ rake specs:file
-  or just:
-  $ cd spec
-  $ STORE=<cache_store> spec merb-cache_spec.rb
-  # cache_store can be:
-  #   memory, memcache, file, sequel, datamapper, activerecord
-
-== Sample configuration
-
-  Merb::Plugins.config[:merb_cache] = {
-    :cache_html_directory => Merb.dir_for(:public) / "cache",
-
-    #:store => "database",
-    #:table_name => "merb_cache",
-
-    #:disable => "development", # disable merb-cache in development
-    #:disable => true, # disable merb-cache in all environments
-
-    :store => "file",
-    :cache_directory => Merb.root_path("tmp/cache"),
-
-    #:store => "memcache",
-    #:host => "127.0.0.1:11211",
-    #:namespace => "merb_cache",
-    #:no_tracking => false,
-
-    #:store => "memory",
-    # store could be: file, memcache, memory, database, dummy, ...
-  }
-
-
-== Quick Example
-
-==== controller part
-  class Users < Merb::Controller
-    cache_page :action_name
-    # this will cache the action in public/cache/something.html
-    # this cache entry will never expire (no expiration provided)
-    # for permanent caching you could set your lighty/nginx so as to handle
-    # the .html file directly
-    # for multiple page caching:
-    # cache_pages :action_name, [:another_action, 5], :some_action
-
-    cache_action :another_action, 10
-    # this will cache the action using the cache store
-    # this cache entry will expire in 10 minutes
-    # for multiple action caching:
-    # cache_actions :action_name, [:another_action, 5], :some_action
-
-    def list
-      unless @users = cache_get("active_users")
-        @users = User.all(:active => true)
-        cache_set("active_users", @users)
-        # object caching can be used to avoid pulling huge amounts of data
-        # from the database.
-        # you could have calle cache_set with an expiration time as well:
-        # cache_set("active_users", @users, 10)
-      end
-      render
-    end
+Merb::Cache.setup do
+  register(:memcached, MemcachedStore, :namespace => "my_app", :servers => ["127.0.0.1:11211"])
+end
 
-    def some_action_that_invalidates_cache
-      expire_page(:action_name)
-      expire_action(:another_action)
-      render
-    end
+# a default FileStore
+Merb::Cache.setup do
+  register(FileStore)
+end
 
-    def delete
-      expire("active_users")
-      render
-    end
+# another FileStore
+Merb::Cache.setup do
+  register(:tmp_cache, FileStore, :dir => "/tmp")
+end
+
+Now lets see how we can use stores in the application:
 
-    def archives
-      @archives = User.archives unless cached?("users_archives")
-      render
+class Tag
+  def find(parameters = {})
+    # poor man's identity map
+
+    if Merb::Cache[:memcached].exists?("tags", parameters)
+      Merb::Cache[:memcached].read("tags", parameters)
+    else
+      results = super(parameters)
+      Merb::Cache[:memcached].write("tags", results, parameters)
+
+      results
     end
+  end
 
-    def index
-      render
+  def popularity_rating
+    # lets keep the popularity rating cached for 30 seconds
+    # merb-cache will create a key from the model's id & the interval parameter
+
+    Merb::Cache[:memcached].fetch(self.id, :interval => Time.now.to_i / 30) do
+      self.run_long_popularity_rating_query
     end
   end
+end
+
+
+Or, if you want to use memcache’s built in expire option:
+
+# expire a cache entry for "bar" (identified by the key "foo" and
+# parameters {:baz => :bay}) in two hours
+Merb::Cache[:memcached].write("foo", "bar", {:baz => :bay}, :expire_in => 2.hours)
+
+# this will fail, because FileStore cannot expire cache entries
+Merb::Cache[:default].write("foo", "bar", {:baz => :bay}, :expire_in => 2.hours)
+
+# writing to the FileStore will fail, but the MemcachedStore will succeed
+Merb::Cache[:default, :memcached].write("foo", "bar", {:baz => :bay}, :expire_in => 2.hours)
 
+# this will fail
+Merb::Cache[:default, :memcached].write_all("foo", "bar", {:baz => :bay}, :expire_in => 2.hours)
 
-====views/users/index.html.erb
-  # this entry will expire in 10 minutes
-  <%- cache "users_index", 10 do %>
-   <div>some big template</div>
-  <% end -%>
 
-====views/users/archive.html.erb
-  <%- cache "users_archives" do %>
-   <div>some big template</div>
-  <% end -%>
+Setting up strategy stores is very similar to fundamental stores:
+
+Merb::Cache.setup do
+
+  # wraps the :memcached store we setup earlier
+  register(:zipped, GzipStore[:memcached])
+
+  # wrap a strategy store
+  register(:sha_and_zip, SHA1Store[:zipped])
+
+  # you can even use unnamed fundamental stores
+  register(:zipped_images, GzipStore[FileStore],
+            :dir => Merb.root / "public" / "images")
+
+  # or a combination or strategy & fundamental stores
+  register(:secured, SHA1Store[GzipStore[FileStore], FileStore],
+            :dir => Merb.root / "private")
+end
+
+
+You can use these strategy stores exactly like fundamental stores in your app code.
+
+Action & Page Caching
+Action & page caching have been implemented in strategy stores. So instead of manually specifying which type of caching you want for each action, you simply ask merb-cache to cache your action, and it will use the fastest cache available.
+
+First, let’s setup our page & action stores:
+
+config/environments/development.rb
+ 
+  Merb::Cache.setup do
+ 
+    # the order that stores are setup is important 
+    # faster stores should be setup first 
+ 
+    # page cache to the public dir
+    register(:page_store, PageStore[FileStore], 
+                      :dir => Merb.root / "public") 
+ 
+    # action cache to memcache 
+    register(:action_store, ActionStore[:sha_and_zip]) 
+ 
+    # sets up the ordering of stores when attempting to read/write cache entries 
+    register(:default, AdhocStore[:page_store, :action_store])
+  
+  end
+
+And now in our controller:
+class Tags < Merb::Controller 
+
+  # index & show will be page cached to the public dir. The index 
+  # action has no parameters, and the show parameter's are part of 
+  # the URL, making them both page-cache'able 
+  cache :index, :show 
+
+  def index 
+    render 
+  end 
+
+  def show(:slug) 
+    display Tag.first(:slug => slug) 
+  end 
+end 
+
+Our controller now page caches but the index & show action. Furthermore,
+the show action is cached separately for each slug parameter automatically.
+
+ 
+class Tags < Merb::Controller 
+
+  # the term is a route param, while the page & per_page params are part of the query string. 
+  # If only the term param is supplied, the request can be page cached, but if the page and/or 
+  # per_page param is part of the query string, the request will action cache. 
+  cache :catalog 
+
+  def catalog(term = 'a', page = 1, per_page = 20) 
+    @tags = Tag.for_term(term).paginate(page, per_page) 
+
+    display @tags 
+  end 
+end 
+
+Because the specific type of caching is not specified, the same action can either
+be page cached or action cached depending on the context of the request.
+
+
+Keeping a “Hot” Cache
+=====================
+
+Cache expiration is a constant problem for developers. When should content
+be expired? Should we “sweep” stale content? How do we balance serving fresh
+content and maintaining fast response times? These are difficult questions
+for developers, and are usually answered with ugly code added across our
+models, views, and controllers. Instead of designing an elaborate
+caching and expiring system, an alternate approach is to keep a “hot” cache.
+
+So what is a “hot” cache? A hot cache is what you get when you ignore
+trying to manually expire content, and instead focus on replacing old
+content with fresh data as soon as it becomes stale. Keeping a hot
+cache means no difficult expiration logic spread out across your
+app, and will all but eliminate cache misses.
+
+The problem until now with this approach has been the impact on
+response times. If the request has to wait on any pages that
+it has made stale to render the fresh version, it can slow down
+the response time dramatically. Thankfully, Merb has the run_later
+method which allows the fresh content to render after the
+response has been sent to the browser.
+It’s the best of both worlds. Here’s an example.
+
+ 
+class Tags &lt; Merb::Controller 
+
+  cache :index 
+  eager_cache :create, :index 
+
+  def index 
+    display Tag.all 
+  end 
+
+  def create(slug) 
+    @tag = Tag.new(slug) 
+
+    # redirect them back to the index action 
+    redirect url(:tags) 
+  end 
+end 
+
+The controller will eager_cache the index action whenever the create action
+is successfully called. If the client were to post a new tag to the
+create action, they would be redirect back to the index action.
+Right after the response had been sent to the client, the index action
+would be rendered with the newly created tag included and replaced
+in the cache. So when the user requests for the index action gets
+to the server, the freshest version is already in the cache, and
+the cache miss is avoided. This works regardless of the way
+the index action is cached.
+
+Hot cache helps fight dog pile effect
+(http://highscalability.com/strategy-break-memcache-dog-pile) but
+should be used with caution. It's great when you want to eagerly cache
+some page that user is not going to see immediately after
+creating/updating something because hot cache in current implementation
+uses worker queue (knows as run_later) and it does not guarantee that
+before redirect hits the action data is gonna be already cached.
+
+A good use case of eager caching is front end page of
+some newspaper site when staff updates site content, and
+is not redirected to page that uses new cache values immediately,
+but other users access it frequently.

data/Rakefile

@@ -2,6 +2,7 @@ require 'rubygems'
 require 'rake/gempackagetask'
 require "extlib"
 require 'merb-core/tasks/merb_rake_helper'
+require "spec/rake/spectask"
 
 ##############################################################################
 # Package && release
@@ -11,12 +12,12 @@ PROJECT_URL         = "http://merbivore.com"
 PROJECT_SUMMARY     = "Merb plugin that provides caching (page, action, fragment, object)"
 PROJECT_DESCRIPTION = PROJECT_SUMMARY
 
-GEM_AUTHOR = "Alex Boussinet"
-GEM_EMAIL  = "alex.boussinet@gmail.com"
+GEM_AUTHOR = "Ben Burkert"
+GEM_EMAIL  = "ben@benburkert.com"
 
 GEM_NAME    = "merb-cache"
 PKG_BUILD   = ENV['PKG_BUILD'] ? '.' + ENV['PKG_BUILD'] : ''
-GEM_VERSION = (Merb::MORE_VERSION rescue "0.9.7") + PKG_BUILD
+GEM_VERSION = (Merb::MORE_VERSION rescue "0.9.8") + PKG_BUILD
 
 RELEASE_NAME    = "REL #{GEM_VERSION}"
 
@@ -34,7 +35,7 @@ spec = Gem::Specification.new do |s|
   s.author = GEM_AUTHOR
   s.email = GEM_EMAIL
   s.homepage = PROJECT_URL
-  s.add_dependency('merb-core', '>= 0.9.7')
+  s.add_dependency('merb-core', '>= 0.9.8')
   s.require_path = 'lib'
   s.files = %w(LICENSE README Rakefile TODO) + Dir.glob("{lib,spec}/**/*")
 end
@@ -44,15 +45,59 @@ Rake::GemPackageTask.new(spec) do |pkg|
 end
 
 desc "Install the gem"
-task :install => [:package] do
-  sh install_command(GEM_NAME, GEM_VERSION)
+task :install do
+  Merb::RakeHelper.install(GEM_NAME, :version => GEM_VERSION)
 end
 
-namespace :jruby do
+desc "Uninstall the gem"
+task :uninstall do
+  Merb::RakeHelper.uninstall(GEM_NAME, :version => GEM_VERSION)
+end
 
-  desc "Run :package and install the resulting .gem with jruby"
-  task :install => :package do
-    sh jinstall_command(GEM_NAME, GEM_VERSION)
+desc "Create a gemspec file"
+task :gemspec do
+  File.open("#{GEM_NAME}.gemspec", "w") do |file|
+    file.puts spec.to_ruby
   end
+end
 
+desc "Run all examples (or a specific spec with TASK=xxxx)"
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_opts  = ["-cfs"]
+  t.spec_files = begin
+    if ENV["TASK"] 
+      ENV["TASK"].split(',').map { |task| "spec/**/#{task}_spec.rb" }
+    else
+      FileList['spec/**/*_spec.rb']
+    end
+  end
 end
+
+desc 'Default: run spec examples'
+task :default => 'spec'
+
+##############################################################################
+# memcached
+##############################################################################
+MEMCACHED_PORTS = 43042..43043
+
+namespace :memcached do
+  desc "Start the memcached instances for specs"
+  task :start do
+    log = "/tmp/memcached.log"
+    system ">#{log}"
+
+    verbosity = (ENV['DEBUG'] ? "-vv" : "")
+
+    (MEMCACHED_PORTS).each do |port|
+      system "memcached #{verbosity} -p #{port} >> #{log} 2>&1 &"
+    end
+  end
+
+  desc "Kill the memcached instances"
+  task :kill do
+    `ps awx`.split("\n").grep(/#{MEMCACHED_PORTS.to_a.join('|')}/).map do |process| 
+      system("kill -9 #{process.to_i}") rescue nil
+    end
+  end
+end

data/TODO

@@ -1,2 +0,0 @@
-capture_#{engine} and concat_#{engine} are required for cache()
-implement other cache store ?

data/lib/merb-cache/cache.rb

@@ -0,0 +1,84 @@
+module Merb
+  # A convinient way to get at Merb::Cache
+  def self.cache
+    Merb::Cache
+  end
+
+  module Cache
+
+    def self.setup(&blk)
+      instance_eval(&blk) unless blk.nil?
+    end
+
+    # autoload is used so that gem dependencies can be required only when needed by
+    # adding the require statement in the store file.
+    autoload :AbstractStore,    "merb-cache" / "stores" / "fundamental" / "abstract_store"
+    autoload :FileStore,        "merb-cache" / "stores" / "fundamental" / "file_store"
+    autoload :MemcachedStore,   "merb-cache" / "stores" / "fundamental" / "memcached_store"
+    
+    autoload :AbstractStrategyStore,  "merb-cache" / "stores" / "strategy" / "abstract_strategy_store"
+    autoload :ActionStore,            "merb-cache" / "stores" / "strategy" / "action_store"
+    autoload :AdhocStore,             "merb-cache" / "stores" / "strategy" / "adhoc_store"
+    autoload :GzipStore,              "merb-cache" / "stores" / "strategy" / "gzip_store"
+    autoload :PageStore,              "merb-cache" / "stores" / "strategy" / "page_store"
+    autoload :SHA1Store,              "merb-cache" / "stores" / "strategy" / "sha1_store"
+
+    
+    class << self
+      attr_accessor :stores
+    end
+
+    self.stores = {}
+
+    # Cache store lookup
+    # name<Symbol> : The name of a registered store
+    # Returns<Nil AbstractStore> : A thread-safe copy of the store
+    def self.[](*names)
+      if names.size == 1
+        Thread.current[:'merb-cache'] ||= {}
+        (Thread.current[:'merb-cache'][names.first] ||= stores[names.first].clone)
+      else
+        AdhocStore[*names]
+      end
+    rescue TypeError
+      raise(StoreNotFound, "Could not find the :#{names.first} store")
+    end
+
+    # Clones the cache stores for the current thread
+    def self.clone_stores
+      @stores.inject({}) {|h, (k, s)| h[k] = s.clone; h}
+    end
+
+    # Registers the cache store name with a type & options
+    # name<Symbol> : An optional symbol to give the cache.  :default is used if no name is given.
+    # klass<Class> : A store type.
+    # opts<Hash> : A hash to pass through to the store for configuration.
+    def self.register(name, klass = nil, opts = {})
+      klass, opts = nil, klass if klass.is_a? Hash
+      name, klass = default_store_name, name if klass.nil?
+
+      raise StoreExists, "#{name} store already setup" if @stores.has_key?(name)
+
+      @stores[name] = (AdhocStore === klass) ? klass : klass.new(opts)
+    end
+    
+    # Checks to see if a given store exists already.
+    def self.exists?(name)
+      return true if self[name]
+    rescue StoreNotFound
+      return false
+    end
+
+    # Default store name is :default.
+    def self.default_store_name
+      :default
+    end
+
+    class NotSupportedError < Exception; end
+    
+    class StoreExists < Exception; end
+
+    # Raised when requested store cannot be found on the list of registered.
+    class StoreNotFound < Exception; end
+  end #Cache
+end #Merb

data/lib/merb-cache/core_ext/enumerable.rb

@@ -0,0 +1,9 @@
+module Enumerable
+  def capture_first
+    each do |o|
+      return yield(o) || next
+    end
+
+    nil
+  end
+end

data/lib/merb-cache/core_ext/hash.rb

@@ -0,0 +1,20 @@
+require 'digest'
+
+class Hash
+  
+  def to_sha2
+    string = ""
+    keys.sort_by{|k| k.to_s}.each do |k| 
+      case self[k]
+      when Array
+        string << self[k].join
+      when Hash
+        string << self[k].to_sha2
+      else
+        string << self[k].to_s
+      end
+    end
+    Digest::SHA2.hexdigest(string)
+  end
+  
+end