merb-cache/lib/merb-cache/cache.rb merb-cache/lib/merb-cache/core_ext/enumerable.rb merb-cache/lib/merb-cache/core_ext/hash.rb merb-cache/lib/merb-cache/merb_ext/controller.rb merb-cache/lib/merb-cache/stores/fundamental/abstract_store.rb merb-cache/lib/merb-cache/stores/fundamental/file_store.rb merb-cache/lib/merb-cache/stores/fundamental/memcached_store.rb merb-cache/lib/merb-cache/stores/strategy/abstract_strategy_store.rb merb-cache/lib/merb-cache/stores/strategy/action_store.rb merb-cache/lib/merb-cache/stores/strategy/adhoc_store.rb merb-cache/lib/merb-cache/stores/strategy/gzip_store.rb merb-cache/lib/merb-cache/stores/strategy/page_store.rb merb-cache/lib/merb-cache/stores/strategy/sha1_store.rb merb-cache/spec/merb-cache/cache_spec.rb merb-cache/spec/merb-cache/core_ext/enumerable_spec.rb merb-cache/spec/merb-cache/core_ext/hash_spec.rb merb-cache/spec/merb-cache/merb_ext/controller_spec.rb merb-cache/spec/merb-cache/stores/fundamental/abstract_store_spec.rb merb-cache/spec/merb-cache/stores/fundamental/file_store_spec.rb merb-cache/spec/merb-cache/stores/fundamental/memcached_store_spec.rb merb-cache/spec/merb-cache/stores/strategy/abstract_strategy_store_spec.rb merb-cache/spec/merb-cache/stores/strategy/action_store_spec.rb merb-cache/spec/merb-cache/stores/strategy/adhoc_store_spec.rb merb-cache/spec/merb-cache/stores/strategy/gzip_store_spec.rb merb-cache/spec/merb-cache/stores/strategy/page_store_spec.rb merb-cache/spec/merb-cache/stores/strategy/sha1_store_spec.rb @@ -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. \ No newline at end of file merb-cache/LICENSE @@ -1,160 +1,218 @@ -= 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 +Merb::Cache.setup(:memcached, Merb::Cache::MemcachedStore, { + :namespace => "my_app", + :servers => ["127.0.0.1:11211"] +} - 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 +# a default FileStore +Merb::Cache.setup(Merb::Cache::FileStore) - def some_action_that_invalidates_cache - expire_page(:action_name) - expire_action(:another_action) - render - end +# another FileStore +Merb::Cache.setup(:tmp_cache, Merb::Cache::FileStore, :dir => "/tmp") - def delete - expire("active_users") - render - end - def archives - @archives = User.archives unless cached?("users_archives") - render +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 - def index - render + 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: + +# wraps the :memcached store we setup earlier +Merb::Cache.setup(:zipped, Merb::Cache::GzipStore[:memcached]) + +# wrap a strategy store +Merb::Cache.setup(:sha_and_zip, Merb::Cache::SHA1Store[:zipped]) + +# you can even use unnamed fundamental stores +Merb::Cache.setup(:zipped_images, Merb::Cache::GzipStore[Merb::Cache::FileStore], + :dir => Merb.root / "public" / "images") + +# or a combination or strategy & fundamental stores +module Merb::Cache #makes things a bit shorter + + setup(: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 + + # the order that stores are setup is important + # faster stores should be setup first + + # page cache to the public dir + Merb::Cache.setup(:page_store, Merb::Cache::PageStore[FileStore], + :dir => Merb.root / "public") + + # action cache to memcache + Merb::Cache.setup(:action_store, Merb::Cache::ActionStore[:sha_and_zip]) + + # sets up the ordering of stores when attempting to read/write cache entries + Merb::Cache.setup(:default, Merb::Cache::AdhocStore[:page_store, :action_store]) + + +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 +===================== -====views/users/index.html.erb - # this entry will expire in 10 minutes - <%- cache "users_index", 10 do %> - <div>some big template</div> - <% end -%> +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. -====views/users/archive.html.erb - <%- cache "users_archives" do %> - <div>some big template</div> - <% end -%> +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. \ No newline at end of file merb-cache/README @@ -12,8 +12,8 @@ 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'] : '' @@ -45,27 +45,50 @@ Rake::GemPackageTask.new(spec) do |pkg| end desc "Install the gem" -task :install do - Merb::RakeHelper.install(GEM_NAME, :version => GEM_VERSION) +task :install => [:package] do + sh install_command(GEM_NAME, GEM_VERSION) end -desc "Uninstall the gem" -task :uninstall do - Merb::RakeHelper.uninstall(GEM_NAME, :version => GEM_VERSION) -end +namespace :jruby do -desc "Create a gemspec file" -task :gemspec do - File.open("#{GEM_NAME}.gemspec", "w") do |file| - file.puts spec.to_ruby + desc "Run :package and install the resulting .gem with jruby" + task :install => :package do + sh jinstall_command(GEM_NAME, GEM_VERSION) end + +end + +desc "Run all specs" +Spec::Rake::SpecTask.new("spec") do |t| + t.spec_opts = ["--format", "specdoc", "--colour"] + t.spec_files = Dir["spec/**/*_spec.rb"].sort end -desc "Run all examples" -Spec::Rake::SpecTask.new('spec') do |t| - t.spec_opts = ["-cfs"] - t.spec_files = FileList['spec/**/*_spec.rb'] +############################################################################## +# 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 desc 'Default: run spec examples' -task :default => 'spec' +task :default => 'spec' \ No newline at end of file merb-cache/Rakefile @@ -1,2 +0,0 @@ -capture_#{engine} and concat_#{engine} are required for cache() -implement other cache store ? merb-cache/TODO @@ -1,10 +1,11 @@ +# make sure we're running inside Merb if defined?(Merb::Plugins) - Merb::Plugins.add_rakefiles "merb-cache/merbtasks" - unless 1.respond_to? :minutes - class Numeric - def minutes; self * 60; end - def from_now(now = Time.now); now + self; end - end + require "merb-cache" / "cache" + require "merb-cache" / "core_ext" / "enumerable" + require "merb-cache" / "core_ext" / "hash" + require "merb-cache" / "merb_ext" / "controller" + + class Merb::Controller + include Merb::Cache::CacheMixin end - require "merb-cache/merb-cache" end merb-cache/lib/merb-cache.rb @@ -1,94 +1,82 @@ $TESTING=true -$:.unshift File.join(File.dirname(__FILE__), '..', 'lib') -require "rubygems" -require "merb-core" +$:.push File.join(File.dirname(__FILE__), '..', 'lib') -require "merb-cache" -require File.dirname(__FILE__) / "controller" +# Deps +require 'rubygems' +require 'merb-core' +require 'merb-action-args' +require File.join(File.dirname(__FILE__), '..', 'lib', 'merb-cache') -require "merb-haml" +# We want logging! +Merb.logger = Merb::Logger.new(File.join(File.dirname(__FILE__), '..', 'log', 'merb_test.log')) -def set_database_adapter(adapter) - config_file = File.dirname(__FILE__) / "config/database.yml" - config = IO.read(config_file) - config.gsub!(/:adapter:\s+.*$/, ":adapter: #{adapter}") - File.open(config_file, "w+") do |c| c.write(config) end +Merb.start :environment => "test", :adapter => "runner" + +require "merb-core/test" +Spec::Runner.configure do |config| + config.include Merb::Test::Helpers + #config.include Merb::Test::ControllerHelper + config.include Merb::Test::RouteHelper end -def use_cache_store(store, orm = nil) - Merb::Plugins.config[:merb_cache] = { - :store => store, - :cache_directory => File.dirname(__FILE__) / "tmp/cache", - :cache_html_directory => File.dirname(__FILE__) / "tmp/html", - :no_tracking => false - } - FileUtils.rm_rf(Dir.glob(File.dirname(__FILE__) / "/tmp")) - case store - when "dummy" - when "file" - when "memory" - when "memcache" - require "memcache" - when "database" - case orm - when "datamapper" - Merb.environment = "test" - Merb.logger = Merb::Logger.new("log/merb_test.log") - set_database_adapter("sqlite3") - require "merb_datamapper" - when "activerecord" - Merb.logger = Merb::Logger.new("log/merb_test.log") - set_database_adapter("sqlite3") - require "merb_activerecord" - when "sequel" - set_database_adapter("sqlite") - require "merb_sequel" - else - raise "Unknown orm: #{orm}" +class DummyStore < Merb::Cache::AbstractStore + cattr_accessor :vault + attr_accessor :options + + def initialize(config = {}) + super(config) + @options = config + @@vault = {} + end + + def writable?(*args) + true + end + + def read(key, parameters = {}) + + if @@vault.keys.include?(key) + @@vault[key].find {|data, timestamp, conditions, params| params == parameters} end - else - raise "Unknown cache store: #{store}" end -end -store = "file" -case ENV["STORE"] || store -when "file" - use_cache_store "file" -when "memory" - use_cache_store "memory" -when "memcache" - use_cache_store "memcache" -when "datamapper" - use_cache_store "database", "datamapper" -when "sequel" - use_cache_store "database", "sequel" -when "activerecord" - use_cache_store "database", "activerecord" -when "dummy" - use_cache_store "dummy" -else - puts "Invalid cache store: #{ENV["store"]}" - exit -end + def data(key, parameters = {}) + read(key, parameters)[0] if read(key, parameters) + end -require "fileutils" -FileUtils.mkdir_p(Merb::Plugins.config[:merb_cache][:cache_html_directory]) -FileUtils.mkdir_p(Merb::Plugins.config[:merb_cache][:cache_directory]) + def time(key, parameters = {}) + read(key, parameters)[1] if read(key, parameters) + end -Merb.start :environment => "test", :adapter => "runner" + def conditions(key, parameters = {}) + read(key, parameters)[2] if read(key, parameters) + end -require "merb-core/test" + def write(key, data = nil, parameters = {}, conditions = {}) + (@@vault[key] ||= []) << [data, Time.now, conditions, parameters] + true + end -CACHE = CacheController.new(Merb::Test::RequestHelper::FakeRequest.new) -CACHE.expire_all + def fetch(key, parameters = {}, conditions = {}, &blk) + @@vault[[key, parameters]] ||= blk.call + end -Spec::Runner.configure do |config| - config.include Merb::Test::RequestHelper - config.before(:each) do - Merb::Router.prepare do |r| - r.default_routes - r.match("/").to(:controller => "cache_controller", :action =>"index") - end + def exists?(key, parameters = {}) + @@vault.has_key? [key, parameters] + end + + def delete(key, parameters = {}) + @@vault.delete([key, parameters]) unless @@vault[[key, parameters]].nil? + end + + def delete_all + @@vault = {} end end + +#TODO change this to a work queue per class called in an after aspect +class Merb::Controller + def run_later + yield + end +end \ No newline at end of file merb-cache/spec/spec_helper.rb merb-cache/lib/merb-cache/cache-action.rb merb-cache/lib/merb-cache/cache-fragment.rb merb-cache/lib/merb-cache/cache-page.rb merb-cache/lib/merb-cache/cache-store/database-activerecord.rb merb-cache/lib/merb-cache/cache-store/database-datamapper.rb merb-cache/lib/merb-cache/cache-store/database-sequel.rb merb-cache/lib/merb-cache/cache-store/database.rb merb-cache/lib/merb-cache/cache-store/dummy.rb merb-cache/lib/merb-cache/cache-store/file.rb merb-cache/lib/merb-cache/cache-store/memcache.rb merb-cache/lib/merb-cache/cache-store/memory.rb merb-cache/lib/merb-cache/merb-cache.rb merb-cache/lib/merb-cache/merbtasks.rb merb-cache/spec/config/database.yml merb-cache/spec/controller.rb merb-cache/spec/merb-cache-action_spec.rb merb-cache/spec/merb-cache-fragment_spec.rb merb-cache/spec/merb-cache-page_spec.rb merb-cache/spec/views/cache_controller/action1.html.erb merb-cache/spec/views/cache_controller/action2.html.haml f117c96be4b6b4903c92744a20a1280540bf7b7f Michael S. Klishin michael@novemberain.com http://github.com/wycats/merb/commit/a4d4025ce23900aa4366eb6e338a1e890aaa6328 a4d4025ce23900aa4366eb6e338a1e890aaa6328 2008-09-28T00:38:10-07:00 2008-09-28T00:38:10-07:00 Replace merb-cache with new implmentation. 48efa3e2290e4aeb1fc50945b6ef82df421c30ec Michael S. Klishin michael@novemberain.com