benschwarz-merb-cache 1.0.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Ben Burkert, Ben Schwarz, Daniel Neighman 
+
+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,224 @@
+merb-cache
+==========
+
+A plugin for the Merb framework that provides caching stores,
+strategies and helpers.
+
+
+
+Tutorial
+==========
+
+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).
+
+# create a fundamental memcache store named :memcached for localhost
+
+Merb::Cache.setup do
+  register(:memcached, MemcachedStore, :namespace => "my_app", :servers => ["127.0.0.1:11211"])
+end
+
+# a default FileStore
+Merb::Cache.setup do
+  register(FileStore)
+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:
+
+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 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)
+
+
+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

@@ -0,0 +1,17 @@
+require 'rake'
+require 'spec/rake/spectask'
+
+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'

data/lib/merb-cache.rb

@@ -0,0 +1,15 @@
+# make sure we're running inside Merb
+if defined?(Merb::Plugins)
+  require "merb-cache" / "cache"
+  require "merb-cache" / "core_ext" / "enumerable"
+  require "merb-cache" / "core_ext" / "hash"
+  require "merb-cache" / "merb_ext" / "controller" / "class_methods"
+  require "merb-cache" / "merb_ext" / "controller" / "instance_methods"
+  require "merb-cache" / "cache_request"
+
+  class Merb::Controller 
+    extend Merb::Cache::Controller::ClassMethods
+  end
+  
+  Merb::Controller.send(:include, Merb::Cache::Controller::InstanceMethods)
+end

data/lib/merb-cache/cache.rb

@@ -0,0 +1,91 @@
+module Merb
+  # A convinient way to get at Merb::Cache
+  def self.cache
+    Merb::Cache
+  end
+
+  module Cache
+
+    def self.setup(&blk)
+      if Merb::BootLoader.finished?(Merb::BootLoader::BeforeAppLoads)
+        instance_eval(&blk) unless blk.nil?
+      else
+        Merb::BootLoader.before_app_loads do
+          instance_eval(&blk) unless blk.nil?
+        end
+      end
+    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"
+    autoload :MintCacheStore,         "merb-cache" / "stores" / "strategy" / "mintcache_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)
+      names = names.first if names.first.is_a? Array
+      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/cache_request.rb

@@ -0,0 +1,48 @@
+module Merb
+  module Cache
+    class CacheRequest < Merb::Request
+      
+      attr_accessor :params
+
+      def initialize(uri = "", params = {}, env = {})
+        if uri || !env[Merb::Const::REQUEST_URI]
+          uri = URI(uri || '/')        
+          env[Merb::Const::REQUEST_URI]  = uri.respond_to?(:request_uri) ? uri.request_uri : uri.to_s
+          env[Merb::Const::HTTP_HOST]    = uri.host + (uri.port != 80 ? ":#{uri.port}" : '') if uri.host
+          env[Merb::Const::SERVER_PORT]  = uri.port.to_s   if uri.port
+          env[Merb::Const::QUERY_STRING] = uri.query.to_s  if uri.query
+          env[Merb::Const::REQUEST_PATH] = env[Merb::Const::PATH_INFO] = uri.path
+        end
+        
+        env[Merb::Const::REQUEST_METHOD] = env[:method] ? env.delete(:method).to_s.upcase : 'GET'
+        
+        super(DEFAULT_ENV.merge(env))
+        
+       
+        @params = params || {}
+      end
+
+      DEFAULT_ENV = Mash.new({
+        'SERVER_NAME' => 'localhost',
+        'HTTP_ACCEPT_ENCODING' => 'gzip,deflate',
+        'HTTP_USER_AGENT' => 'Ruby/Merb (ver: ' + Merb::VERSION + ') merb-cache',
+        'SCRIPT_NAME' => '/',
+        'SERVER_PROTOCOL' => 'HTTP/1.1',
+        'HTTP_CACHE_CONTROL' => 'max-age=0',
+        'HTTP_ACCEPT_LANGUAGE' => 'en,ja;q=0.9,fr;q=0.9,de;q=0.8,es;q=0.7,it;q=0.7,nl;q=0.6,sv;q=0.5,nb;q=0.5,da;q=0.4,fi;q=0.3,pt;q=0.3,zh-Hans;q=0.2,zh-Hant;q=0.1,ko;q=0.1',
+        'HTTP_HOST' => 'localhost',
+        'REMOTE_ADDR' => '127.0.0.1',
+        'SERVER_SOFTWARE' => 'Mongrel 1.1',
+        'HTTP_KEEP_ALIVE' => '300',
+        'HTTP_REFERER' => 'http://localhost/',
+        'HTTP_ACCEPT_CHARSET' => 'ISO-8859-1,utf-8;q=0.7,*;q=0.7',
+        'HTTP_VERSION' => 'HTTP/1.1',
+        'REQUEST_METHOD' => 'GET',
+        'SERVER_PORT' => '80',
+        'GATEWAY_INTERFACE' => 'CGI/1.2',
+        'HTTP_ACCEPT' => 'text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5',
+        'HTTP_CONNECTION' => 'keep-alive'
+      }) unless defined?(DEFAULT_ENV)
+    end
+  end
+end

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,21 @@
+require 'digest'
+
+class Hash
+  
+  def to_sha2
+    string = ""
+    keys.sort_by{|k| k.to_s}.each do |k| 
+      string << "&#{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