merb-cache 0.9.2

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Alex Boussinet
+
+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

@@ -0,0 +1,160 @@
+= merb-cache
+
+A plugin for the Merb framework that provides caching
+
+Currently supported methods:
+
+- page caching:
+- action caching
+- fragment caching
+- object caching
+
+Implemented cache stores:
+
+- memory
+- memcache
+- file
+- database (sequel, datamapper, activerecord)
+
+== Quick intro
+  With fragment caching, you can mix dynamic and static content.
+
+  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
+
+    def some_action_that_invalidates_cache
+      expire_page(:action_name)
+      expire_action(:another_action)
+      render
+    end
+
+    def delete
+      expire("active_users")
+      render
+    end
+
+    def archives
+      @archives = User.archives unless cached?("users_archives")
+      render
+    end
+
+    def index
+      render
+    end
+  end
+
+
+====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 -%>

data/Rakefile

@@ -0,0 +1,77 @@
+require 'rubygems'
+require "rake/rdoctask"
+require 'rake/gempackagetask'
+require "spec/rake/spectask"
+
+PLUGIN = "merb-cache"
+NAME = "merb-cache"
+MERB_CACHE_VERSION = Merb::MORE_VERSION rescue "0.9.2"
+AUTHOR = "Alex Boussinet"
+EMAIL = "alex.boussinet@gmail.com"
+HOMEPAGE = "http://www.merbivore.com"
+SUMMARY = "Merb plugin that provides caching (page, action, fragment, object)"
+
+spec = Gem::Specification.new do |s|
+  s.name = NAME
+  s.version = MERB_CACHE_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README", "LICENSE", 'TODO']
+  s.summary = SUMMARY
+  s.description = s.summary
+  s.author = AUTHOR
+  s.email = EMAIL
+  s.homepage = HOMEPAGE
+  s.add_dependency('merb-core', '>= 0.9.2')
+  s.require_path = 'lib'
+  s.autorequire = PLUGIN
+  s.files = %w(LICENSE README Rakefile TODO) + Dir.glob("{lib,specs}/**/*")
+
+  # rdoc
+  s.has_rdoc         = true
+  s.extra_rdoc_files = %w( README LICENSE TODO )
+end
+
+namespace :specs do
+  ["file", "memory", "memcache", "sequel", "datamapper", "activerecord"].each do |store|
+    desc "Run spec with the \"#{store}\" cache store"
+    task "#{store}" do
+      cwd = Dir.getwd
+      Dir.chdir(File.dirname(__FILE__) + "/spec")
+      ENV["STORE"] = store
+      system("spec --format specdoc --colour merb-cache_spec.rb")
+      Dir.chdir(cwd)
+    end
+  end
+end
+
+namespace :doc do
+  Rake::RDocTask.new do |rdoc|
+    files = ["README", "LICENSE", "lib/**/*.rb"]
+    rdoc.rdoc_files.add(files)
+    rdoc.main = "README"
+    rdoc.title = "merb-cache docs"
+    if File.file?("../../merb-core/tools/allison-2.0.2/lib/allison.rb")
+      rdoc.template = "../../merb-core/tools/allison-2.0.2/lib/allison.rb"
+    end
+    rdoc.rdoc_dir = "doc/rdoc"
+    rdoc.options << "--line-numbers" << "--inline-source"
+  end
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+task :install => [:package] do
+  sh %{sudo gem install pkg/#{NAME}-#{MERB_CACHE_VERSION} --no-update-sources}
+end
+
+namespace :jruby do
+
+  desc "Run :package and install the resulting .gem with jruby"
+  task :install => :package do
+    sh %{#{SUDO} jruby -S gem install pkg/#{NAME}-#{Merb::VERSION}.gem --no-rdoc --no-ri}
+  end
+  
+end

data/TODO

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

data/lib/merb-cache/cache-action.rb

@@ -0,0 +1,132 @@
+class Merb::Cache
+  cattr_accessor :cached_actions
+  self.cached_actions = {}
+end
+
+module Merb::Cache::ControllerClassMethods
+  # Mixed in Merb::Controller. Provides methods related to action caching
+
+  # Register the action for action caching
+  #
+  # ==== Parameters
+  # action<Symbol>:: The name of the action to register
+  # from_now<~minutes>::
+  #   The number of minutes (from now) the cache should persist
+  #
+  # ==== Examples
+  #   cache_action :mostly_static
+  #   cache_action :barely_dynamic, 10
+  def cache_action(action, from_now = nil)
+    cache_actions([action, from_now])
+  end
+
+  # Register actions for action caching (before and after filters)
+  #
+  # ==== Parameter
+  # actions<Symbol,Array[Symbol,~minutes]>:: See #cache_action
+  #
+  # ==== Example
+  #   cache_actions :mostly_static, [:barely_dynamic, 10]
+  def cache_actions(*actions)
+    if actions.any? && Merb::Cache.cached_actions.empty?
+      before(:cache_action_before)
+      after(:cache_action_after)
+    end
+    actions.each do |action, from_now| 
+      _actions = Merb::Cache.cached_actions[controller_name] ||= {}
+      _actions[action] = from_now
+    end
+    true
+  end
+end
+
+module Merb::Cache::ControllerInstanceMethods
+  # Mixed in Merb::Controller. Provides methods related to action caching
+
+  # Checks whether a cache entry exists
+  #
+  # ==== Parameter
+  # options<String,Hash>:: The options that will be passed to #key_for
+  #
+  # ==== Returns
+  # true if the cache entry exists, false otherwise
+  #
+  # ==== Example
+  #   cached_action?(:action => 'show', :params => [params[:page]])
+  def cached_action?(options)
+    key = Merb::Controller._cache.key_for(options, controller_name, true)
+    Merb::Controller._cache.store.cached?(key)
+  end
+
+  # Expires the action identified by the key computed after the parameters
+  #
+  # ==== Parameter
+  # options<String,Hash>:: The options that will be passed to #expire_key_for
+  #
+  # ==== Examples
+  #   expire_action(:action => 'show', :controller => 'news')
+  #   expire_action(:action => 'show', :match => true)
+  def expire_action(options)
+    Merb::Controller._cache.expire_key_for(options, controller_name, true) do |key, match|
+      if match
+        Merb::Controller._cache.store.expire_match(key)
+      else
+        Merb::Controller._cache.store.expire(key)
+      end
+    end
+    true
+  end
+
+  # You can call this method if you need to prevent caching the action
+  # after it has been rendered.
+  def abort_cache_action
+    @capture_action = false
+  end
+
+  private
+
+  # Called by the before and after filters. Stores or recalls a cache entry.
+  # The key is based on the result of request.path
+  # If the key with "/" then it is removed
+  # If the key is "/" then it will be replaced by "index"
+  #
+  # ==== Parameters
+  # data<String>:: the data to put in cache using the cache store
+  #
+  # ==== Examples
+  #   If request.path is "/", the key will be "index"
+  #   If request.path is "/news/show/1", the key will be "/news/show/1"
+  #   If request.path is "/news/show/", the key will be "/news/show"
+  def _cache_action(data = nil)
+    controller = controller_name
+    action = action_name.to_sym
+    actions = Merb::Controller._cache.cached_actions[controller]
+    return unless actions && actions.key?(action)
+    path = request.path.chomp("/")
+    path = "index" if path.empty?
+    if data
+      from_now = Merb::Controller._cache.cached_actions[controller][action]
+      Merb::Controller._cache.store.cache_set(path, data, from_now)
+    else
+      @capture_action = false
+      _data = Merb::Controller._cache.store.cache_get(path)
+      throw(:halt, _data) unless _data.nil?
+      @capture_action = true
+    end
+    true
+  end
+
+  # before filter
+  def cache_action_before
+    # recalls a cached entry or set @capture_action to true in order
+    # to grab the response in the after filter
+    _cache_action
+  end
+
+  # after filter
+  def cache_action_after
+    # takes the body of the response and put it in cache
+    # if the cache entry expired, if it doesn't exist or status is 200
+    _cache_action(body) if @capture_action && status == 200
+  end
+end

data/lib/merb-cache/cache-fragment.rb

@@ -0,0 +1,95 @@
+module Merb::Cache::ControllerInstanceMethods
+  # Mixed in Merb::Controller. Provides methods related to fragment caching
+
+  # Checks whether a cache entry exists
+  #
+  # ==== Parameter
+  # options<String,Hash>:: The options that will be passed to #key_for
+  #
+  # ==== Returns
+  # true if the cache entry exists, false otherwise
+  #
+  # ==== Example
+  #   cached_action?("my_key")
+  def cached?(options)
+    key = Merb::Controller._cache.key_for(options, controller_name)
+    Merb::Controller._cache.store.cached?(key)
+  end
+
+  # ==== Example
+  #   In your view:
+  #   <%- cache("my_key") do -%>
+  #     <%= partial :test, :collection => @test %>
+  #   <%- end -%>
+  def cache(options, from_now = nil, &block)
+    key = Merb::Controller._cache.key_for(options, controller_name)
+    Merb::Controller._cache.store.cache(self, key, from_now, &block)
+  end
+
+  # Fetch data from cache
+  #
+  # ==== Parameter
+  # options<String,Hash>:: The options that will be passed to #key_for
+  #
+  # ==== Returns
+  # data<Object,NilClass>::
+  #   nil is returned if the cache entry is not found
+  #
+  # ==== Example
+  #   if cache_data = cache_get("my_key")
+  #     @var1, @var2 = *cache_data
+  #   else
+  #     @var1 = MyModel.big_query1
+  #     @var2 = MyModel.big_query2
+  #     cache_set("my_key", nil, [@var1, @var2])
+  #   end
+  def cache_get(options)
+    key = Merb::Controller._cache.key_for(options, controller_name)
+    Merb::Controller._cache.store.cache_get(key)
+  end
+
+  # Store data to cache
+  #
+  # ==== Parameter
+  # options<String,Hash>:: The options that will be passed to #key_for
+  # object<Object>:: The object(s) to put in cache
+  # from_now<~minutes>::
+  #   The number of minutes (from now) the cache should persist
+  #
+  # ==== Returns
+  # data<Object,NilClass>::
+  #   nil is returned if the cache entry is not found
+  #
+  # ==== Example
+  #   if cache_data = cache_get("my_key")
+  #     @var1, @var2 = *cache_data
+  #   else
+  #     @var1 = MyModel.big_query1
+  #     @var2 = MyModel.big_query2
+  #     cache_set("my_key", nil, [@var1, @var2])
+  #   end
+  def cache_set(options, object, from_now = nil)
+    key = Merb::Controller._cache.key_for(options, controller_name)
+    Merb::Controller._cache.store.cache_set(key, object, from_now)
+  end
+
+  # Expires the entry identified by the key computed after the parameters
+  #
+  # ==== Parameter
+  # options<String,Hash>:: The options that will be passed to #key_for
+  #
+  # ==== Examples
+  #   expire("my_key")
+  #   expire(:key => "my_", :match => true)
+  #   expire(:key => "my_key", :params => [session[:me], params[:ref]])
+  def expire(options)
+    Merb::Controller._cache.expire_key_for(options, controller_name) do |key, match|
+      if match
+        Merb::Controller._cache.store.expire_match(key)
+      else
+        Merb::Controller._cache.store.expire(key)
+      end
+    end
+    true
+  end
+end

data/lib/merb-cache/cache-page.rb

@@ -0,0 +1,184 @@
+class Merb::Cache
+  cattr_accessor :cached_pages
+  self.cached_pages = {}
+end
+
+module Merb::Cache::ControllerClassMethods
+  # Mixed in Merb::Controller. Provides class methods related to page caching
+  # Page caching is mostly action caching with file backend using its own output directory of .html files
+
+  # Register the action for page caching
+  #
+  # ==== Parameters
+  # action<Symbol>:: The name of the action to register
+  # from_now<~minutes>::
+  #   The number of minutes (from now) the cache should persist
+  #
+  # ==== Examples
+  #   cache_page :mostly_static
+  #   cache_page :barely_dynamic, 10
+  def cache_page(action, from_now = nil)
+    cache_pages([action, from_now])
+  end
+
+  # Register actions for page caching (before and after filters)
+  #
+  # ==== Parameter
+  # pages<Symbol,Array[Symbol,~minutes]>:: See #cache_page
+  #
+  # ==== Example
+  #   cache_pages :mostly_static, [:barely_dynamic, 10]
+  def cache_pages(*pages)
+    if pages.any? && Merb::Cache.cached_pages.empty?
+      before(:cache_page_before)
+      after(:cache_page_after)
+    end
+    pages.each do |action, from_now| 
+      _pages = Merb::Cache.cached_pages[controller_name] ||= {}
+      _pages[action] = [from_now, 0]
+    end
+    true
+  end
+end
+
+module Merb::Cache::ControllerInstanceMethods
+  # Mixed in Merb::Controller. Provides methods related to page caching
+
+  # Checks whether a cache entry exists
+  #
+  # ==== Parameter
+  # options<String,Hash>:: The options that will be passed to #key_for
+  #
+  # ==== Returns
+  # true if the cache entry exists, false otherwise
+  #
+  # ==== Example
+  #   cached_page?(:action => 'show', :params => [params[:page]])
+  def cached_page?(options)
+    key = Merb::Controller._cache.key_for(options, controller_name, true)
+    File.file?(Merb::Controller._cache.config[:cache_html_directory] / "#{key}.html")
+  end
+
+  # Expires the page identified by the key computed after the parameters
+  #
+  # ==== Parameter
+  # options<String,Hash>:: The options that will be passed to #expire_key_for
+  #
+  # ==== Examples
+  #   expire_page(:action => 'show', :controller => 'news')
+  #   expire_page(:action => 'show', :match => true)
+  def expire_page(options)
+    config_dir = Merb::Controller._cache.config[:cache_html_directory]
+    Merb::Controller._cache.expire_key_for(options, controller_name, true) do |key, match|
+      if match
+        files = Dir.glob(config_dir / "#{key}*")
+      else
+        files = config_dir / "#{key}.html"
+      end
+      FileUtils.rm_rf(files)
+    end
+    true
+  end
+
+  # Expires all the pages stored in config[:cache_html_directory]
+  def expire_all_pages
+    FileUtils.rm_rf(Dir.glob(Merb::Controller._cache.config[:cache_html_directory] / "*"))
+  end
+
+  # You can call this method if you need to prevent caching the page
+  # after it has been rendered.
+  def abort_cache_page
+    @capture_page = false
+  end
+
+  private
+
+  # Called by the before and after filters. Stores or recalls a cache entry.
+  # The name used for the cache file is based on request.path
+  # If the name ends with "/" then it is removed
+  # If the name is "/" then it will be replaced by "index"
+  #
+  # ==== Parameters
+  # data<String>:: the data to put in cache
+  #
+  # ==== Examples
+  #   All the file are written to config[:cache_html_directory]
+  #   If request.path is "/", the name will be "/index.html"
+  #   If request.path is "/news/show/1", the name will be "/news/show/1.html"
+  #   If request.path is "/news/show/", the name will be "/news/show.html"
+  def _cache_page(data = nil)
+    controller = controller_name
+    action = action_name.to_sym
+    pages = Merb::Controller._cache.cached_pages[controller]
+    return unless pages && pages.key?(action)
+    path = request.path.chomp("/")
+    path = "index" if path.empty?
+    cache_file = Merb::Controller._cache.config[:cache_html_directory] / "#{path}.html"
+    if data
+      cache_directory = File.dirname(cache_file)
+      FileUtils.mkdir_p(cache_directory)
+      _expire_in = pages[action][0]
+      pages[action][1] = _expire_in.minutes.from_now unless _expire_in.nil?
+      cache_write_page(cache_file, data)
+      Merb.logger.info("cache: set (#{path})")
+    else
+      @capture_page = false
+      if File.file?(cache_file)
+        _data = cache_read_page(cache_file)
+        _expire_in, _expire_at = pages[action]
+        if _expire_in.nil? || Time.now < _expire_at
+          Merb.logger.info("cache: hit (#{path})")
+          throw(:halt, _data)
+        end
+        FileUtils.rm_f(cache_file)
+      end
+      @capture_page = true
+    end
+    true
+  end
+
+  # Read data from a file using exclusive lock
+  #
+  # ==== Parameters
+  # cache_file<String>:: the full path to the file
+  #
+  # ==== Returns
+  # data<String>:: the data that has been read from the file
+  def cache_read_page(cache_file)
+    _data = nil
+    File.open(cache_file, "r") do |cache_data|
+      cache_data.flock(File::LOCK_EX)
+      _data = cache_data.read
+      cache_data.flock(File::LOCK_UN)
+    end
+    _data
+  end
+
+  # Write data to a file using exclusive lock
+  #
+  # ==== Parameters
+  # cache_file<String>:: the full path to the file
+  # data<String>:: the data that will be written to the file
+  def cache_write_page(cache_file, data)
+    File.open(cache_file, "w+") do |cache_data|
+      cache_data.flock(File::LOCK_EX)
+      cache_data.write(data)
+      cache_data.flock(File::LOCK_UN)
+    end
+    true
+  end
+
+  # before filter
+  def cache_page_before
+    # recalls a cached entry or set @capture_page to true in order
+    # to grab the response in the after filter
+    _cache_page
+  end
+
+  # after filter
+  def cache_page_after
+    # takes the body of the response
+    # if the cache entry expired, if it doesn't exist or status is 200
+    _cache_page(body) if @capture_page && status == 200
+  end
+end