padrino-cache 0.9.24 → 0.9.25

data/README.rdoc

@@ -1,7 +1,337 @@
 = Painless Page and Fragment Caching (padrino-cache)
 
-Not documented yet.
+== Overview
+
+This component enables caching of an application's response contents on
+both page- and fragment-levels. Output cached in this manner is
+persisted, until it expires or is actively expired, in a configurable store
+of your choosing. Several common caching stores are supported out of the box.
+
+== Caching Quickstart
+
+Padrino-cache can reduce the processing load on your site very effectively
+with minimal configuration.
+
+By default, the component caches pages in a file store at <tt>tmp/cache</tt>
+within your project root. Entries in this store correspond directly
+to the request issued to your server. In other words, responses are
+cached based on request URL, with one cache entry per URL.
+
+This behavior is referred to as "page-level caching." If this strategy meets
+your needs, you can enable it very easily:
+
+  # Basic, page-level caching
+  class SimpleApp < Padrino::Application
+    register Padrino::Cache
+    enable :caching
+
+    get '/foo', :cache => true do
+      expires_in 30 # expire cached version at least every 30 seconds
+      'Hello world'
+    end
+  end
+
+You can also cache on a controller-wide basis:
+
+  # Controller-wide caching example
+  class SimpleApp < Padrino::Application
+    register Padrino::Cache
+    enable :caching
+
+    get '/' do
+      'Hello world'
+    end
+
+    # Requests to routes within '/admin'
+    controller '/admin', :cache => true do
+      expires_in 60
+
+      get '/foo' do
+        'Url is /admin/foo'
+      end
+
+      get '/bar' do
+        'Url is /admin/bar'
+      end
+
+      post '/baz' do # We cache only GET and HEAD request
+        'This will not be cached'
+      end
+    end
+  end
+
+You can also provide a custom <tt>cache_key</tt> in any route:
+
+  class SimpleApp < Padrino::Application
+    register Padrino::Cache
+    enable :caching
+
+    get '/post/:id', :cache => true do
+      @post = Post.find(params[:id])
+      cache_key :my_name
+    end
+  end
+
+In this way you can manually expire cache with CachedApp.cache.delete(:my_name)
+for example from the Post model after an update.
+
+If you specify <tt>:cache => true</tt> but do not invoke <tt>expires_in</tt>,
+the response will be cached indefinitely. Most of the time, you will want to
+specify the expiry of a cache entry by <tt>expires_in</tt>. Even a relatively
+low value--1 or 2 seconds--can greatly increase application efficiency, especially
+when enabled on a very active part of your domain.
+
+== Helpers
+
+When an application registers padrino-cache, it gains access to several helper
+methods. These methods are used according to your caching strategy, so they are
+explained here likewise--by functionality.
+
+As with all code optimization, you may want to start simply (at "page level"),
+and continue if necessary into sub-page (or "fragment level" ) caching. There
+is no one way to approach caching, but it's always good to avoid complexity
+until you need it. Start at the page level and see if it works for you.
+
+The padrino-cache helpers are made available to your application thusly:
+
+  # Enable caching
+  class CachedApp < Padrino::Application
+    register Padrino::Cache  # includes helpers
+    enable :caching          # turns on caching
+
+    # ... controllers/routes ...
+  end
+
+=== Page Caching
+
+As described above in the "Caching Quickstart" section, page caching is very
+easy to integrate into your application. To turn it on, simply provide the
+<tt>:cache => true</tt> option on either a controller or one of its routes.
+By default, cached content is persisted with a "file store"--that is, in a
+subdirectory of your application root.
+
+==== <tt>expires_in( seconds )</tt>
+
+This helper is used within a controller or route to indicate how often cached
+<em>page-level</em> content should persist in the cache.
+
+After <tt>seconds</tt> seconds have passed, content previously cached will
+be discarded and re-rendered. Code associated with that route will <em>not</em>
+be executed; rather, its previous output will be sent to the client with a
+200 OK status code.
+
+  # Setting content expiry time
+  class CachedApp < Padrino::Application
+    register Padrino::Cache  # includes helpers
+    enable :caching          # turns on caching
+
+    controller '/blog', :cache => true do
+      expires_in 15
+
+      get '/entries' do
+        'just broke up eating twinkies lol'
+      end
+    end
+  end
+
+Note that the "latest" method call to <tt>expires_in</tt> determines its value: if
+called within a route, as opposed to a controller definition, the route's
+value will be assumed.
+
+=== Fragment Caching
+
+Whereas page-level caching, described in the first section of this document, works by
+grabbing the entire output of a route, fragment caching gives the developer fine-grained
+control of what gets cached. This type of caching occurs at whatever level you choose.
+
+Possible uses for fragment caching might include:
+
+* a 'feed' of some items on a page
+* output fetched (by proxy) from an API on a third-party site
+* parts of your page which are largely static/do not need re-rendering every request
+* any output which is expensive to render
+
+==== <tt>cache( key, opts, &block )</tt>
+
+This helper is used anywhere in your application you would like to associate a fragment
+to be cached. It can be used in within a route:
+
+  # Caching a fragment
+  class MyTweets < Padrino::Application
+    register Padrino::Cache  # includes helpers
+    enable :caching          # turns on caching
+
+    controller '/tweets' do
+      get :feed, :map => '/:username' do
+        username = params[:username]
+
+        @feed = cache( "feed_for_#{username}", :expires_in => 3 ) do
+          @tweets = Tweet.all( :username => username )
+          render 'partials/feedcontent'
+        end
+
+        # Below outputs @feed somewhere in its markup
+        render 'feeds/show'
+      end
+    end
+  end
+
+This example adds a key to the cache of format <tt>feed_for_#{username}</tt> which
+contains the contents of that user's feed. Any subsequent action within the next 3 seconds
+will fetch the pre-rendered version of <tt>feed_for_#{username}</tt> from the cache
+instead of re-rendering it. The rest of the page code will, however, be re-executed.
+
+Note that any other action will reference the same content if it uses the same key:
+
+  # Multiple routes sharing the same cached fragment
+  class MyTweets < Padrino::Application
+    register Padrino::Cache  # includes helpers
+    enable :caching          # turns on caching
+
+    controller :tweets do
+      get :feed, :map => '/:username' do
+        username = params[:username]
+
+        @feed = cache( "feed_for_#{username}", :expires_in => 3 ) do
+          @tweets = Tweet.all( :username => username )
+          render 'partials/feedcontent'
+        end
+
+        # Below outputs @feed somewhere in its markup
+        render 'feeds/show'
+      end
+
+      get :mobile_feed, :map => '/:username.iphone' do
+        username = params[:username]
+
+        @feed = cache( "feed_for_#{username}", :expires_in => 3 ) do
+          @tweets = Tweet.all( :username => username )
+          render 'partials/feedcontent'
+        end
+
+        render 'feeds/show.iphone'
+      end
+    end
+  end
+
+The <tt>opts</tt> argument is actually passed to the underlying store. All stores included with Padrino support the <tt>:expires_in</tt> option out of the box.
+
+Finally, to DRY up things a bit, we might do:
+
+  # Multiple routes sharing the same cached fragment
+  class MyTweets < Padrino::Application
+    register Padrino::Cache  # includes helpers
+    enable :caching          # turns on caching
+
+    controller :tweets do
+      # This works because all routes in this controller specify :username
+      before do
+        @feed = cache( "feed_for_#{params[:username]}", :expires_in => 3 ) do
+          @tweets = Tweet.all( :username => params[:username] )
+          render 'partials/feedcontent'
+        end
+      end
+
+      get :feed, :map => '/:username' do
+        render 'feeds/show'
+      end
+
+      get :mobile_feed, :map => '/:username.iphone' do
+        render 'feeds/show.iphone'
+      end
+    end
+  end
+
+Of course, this example assumes the markup generated by rendering
+<tt>partials/feedcontent</tt> would be suitable for both feed formats. This may or
+may not be the case in your application, but the principle applies: fragments
+are shared between all code which accesses the cache using the same key.
+
+== Caching Store
+
+You can set a global caching option or a per app caching options.
+
+=== Global Caching Options
+
+  Padrino.cache = Padrino::Cache::Store::Memcache.new(::Memcached.new('127.0.0.1:11211', :exception_retry_limit => 1))
+  Padrino.cache = Padrino::Cache::Store::Memcache.new(::Dalli::Client.new('127.0.0.1:11211', :exception_retry_limit => 1))
+  Padrino.cache = Padrino::Cache::Store::Redis.new(::Redis.new(:host => '127.0.0.1', :port => 6379, :db => 0))
+  Padrino.cache = Padrino::Cache::Store::Memory.new(50)
+  Padrino.cache = Padrino::Cache::Store::File.new(/my/cache/path)
+
+You can manage your cache from anywhere in your app:
+
+  Padrino.cache.set('val', 'test')
+  Padrino.cache.get('val') # => 'test'
+  Padrino.cache.delete('val')
+  Padrino.cache.flush
+
+==== Application Caching Options
+
+  set :cache, Padrino::Cache::Store::Memcache.new(::Memcached.new('127.0.0.1:11211', :exception_retry_limit => 1))
+  set :cache, Padrino::Cache::Store::Memcache.new(::Dalli::Client.new('127.0.0.1:11211', :exception_retry_limit => 1))
+  set :cache, Padrino::Cache::Store::Redis.new(::Redis.new(:host => '127.0.0.1', :port => 6379, :db => 0))
+  set :cache, Padrino::Cache::Store::Memory.new(50)
+  set :cache, Padrino::Cache::Store::File.new(Padrino.root('tmp', app_name, 'cache') # default choice
+
+You can manage your cache from anywhere in your app:
+
+  MyApp.cache.set('val', 'test')
+  MyApp.cache.get('val') # => 'test'
+  MyApp.cache.delete('val')
+  MyApp.cache.flush
+
+== Expiring Cached Content
+
+In certain circumstances, cached content becomes stale. The  <tt>expire</tt>
+helper removes content associated with a key or keys, which your app is then
+free to re-generate.
+
+=== <tt>expire( *key )</tt>
+
+==== Fragment-level expiration
+
+Using the example above of a tweet server, let's suppose our users have a
+tendency to post things they quickly regret. When we query our database
+for new tweets, let's check to see if any have been deleted. If so, we'll
+do our user a favor and instantly re-render the feed.
+
+  # Expiring fragment-level cached content
+  class MyTweets < Padrino::Application
+    register Padrino::Cache # includes helpers
+    enable :caching         # turns on caching
+    enable :session         # we'll use this to store last time visited
+
+    COMPANY_FOUNDING = Time.utc( 2010, "April" )
+
+    controller :tweets do
+      get :feed, :map => '/:username' do
+        last_visit = session[:last_visit] || params[:since] || COMPANY_FOUNDING
+
+        username = params[:username]
+        @tweets = Tweet.since( last_visit, :username => username ).limit( 100 )
+
+        expire( "feed since #{last_visit}" ) if @tweets.any? { |t| t.deleted_since?( last_visit ) }
+
+        session[:last_visit] = Time.now
+        @feed = cache( "feed since #{last_visit}", :expires_in => 60 ) do
+          @tweets = @tweets.find_all { |t| !t.deleted? }
+          render 'partials/feedcontent'
+        end
+
+        render 'feeds/show'
+      end
+    end
+  end
+
+Normally, this example will only re-cache feed content every 60 seconds,
+but it will do so immediately if any tweets have been deleted.
+
+==== Page-level expiration
+
+Page-level expiration works exactly like the example above--by using
+<tt>expire</tt> in your controller. The key is typically <tt>env['PATH_INFO']</tt>.
 
 == Copyright
 
-Copyright (c) 2011 Padrino. See LICENSE for details.
+Copyright (c) 2011 Padrino. See LICENSE for details.

data/lib/padrino-cache.rb

@@ -4,31 +4,93 @@ require 'padrino-helpers'
 FileSet.glob_require('padrino-cache/{helpers}/*.rb', __FILE__)
 
 module Padrino
-  module Cache
+  class << self
     ##
-    # Register these helpers:
+    # Returns the caching engine
+    #
+    # ==== Examples
+    #   # with: Padrino.cache = Padrino::Cache::Store::File.new(/my/cache/path)
+    #   Padrino.cache.set('val', 'test')
+    #   Padrino.cache.get('val') # => 'test'
+    #   Padrino.cache.delete('val')
+    #   Padrino.cache.flush
     #
-    #   Padrino::Cache::FragmentHelpers
-    #   Padrino::Cache::PageHelpers
+    def cache
+      @_cache
+    end
+
+    ##
+    # Set the caching engine
     #
-    # for Padrino::Application
+    # === Examples
+    #   Padrino.cache = Padrino::Cache::Store::Memcache.new(::Memcached.new('127.0.0.1:11211', :exception_retry_limit => 1))
+    #   Padrino.cache = Padrino::Cache::Store::Memcache.new(::Dalli::Client.new('127.0.0.1:11211', :exception_retry_limit => 1))
+    #   Padrino.cache = Padrino::Cache::Store::Redis.new(::Redis.new(:host => '127.0.0.1', :port => 6379, :db => 0))
+    #   Padrino.cache = Padrino::Cache::Store::Memory.new(50)
+    #   Padrino.cache = Padrino::Cache::Store::File.new(/my/cache/path)
     #
+    # You can manage your cache from anywhere in your app:
+    #
+    #   Padrino.cache.set('val', 'test')
+    #   Padrino.cache.get('val') # => 'test'
+    #   Padrino.cache.delete('val')
+    #   Padrino.cache.flush
+    #
+    def cache=(value)
+      @_cache = value
+    end
+  end # self
 
+  ##
+  # This component enables caching of an application's response contents on
+  # both page- and fragment-levels. Output cached in this manner is
+  # persisted, until it expires or is actively expired, in a configurable store
+  # of your choosing. Several common caching stores are supported out of the box.
+  #
+  module Cache
     autoload :Store, 'padrino-cache/store'
 
     class << self
+      ##
+      # Register these helpers:
+      #
+      #   Padrino::Cache::Helpers::CacheStore
+      #   Padrino::Cache::Helpers::Fragment
+      #   Padrino::Cache::Helpers::Page
+      #
+      # for Padrino::Application.
+      #
+      # By default we use FileStore as showed below:
+      #
+      #   set :cache, Padrino::Cache::Store::File.new(File.join(app.root, 'tmp', 'cache'))
+      #
+      # However, you can also change the file store easiily in your app.rb:
+      #
+      #   set :cache, Padrino::Cache::Store::Memcache.new(::Memcached.new('127.0.0.1:11211', :exception_retry_limit => 1))
+      #   set :cache, Padrino::Cache::Store::Memcache.new(::Dalli::Client.new('127.0.0.1:11211', :exception_retry_limit => 1))
+      #   set :cache, Padrino::Cache::Store::Redis.new(::Redis.new(:host => '127.0.0.1', :port => 6379, :db => 0))
+      #   set :cache, Padrino::Cache::Store::Memory.new(50)
+      #   set :cache, Padrino::Cache::Store::File.new(Padrino.root('tmp', app_name.to_s, 'cache')) # default choice
+      #
+      # You can manage your cache from anywhere in your app:
+      #
+      #   MyApp.cache.set('val', 'test')
+      #   MyApp.cache.get('val') # => 'test'
+      #   MyApp.cache.delete('val')
+      #   MyApp.cache.flush
+      #
       def registered(app)
         app.helpers Padrino::Cache::Helpers::CacheStore
         app.helpers Padrino::Cache::Helpers::Fragment
         app.helpers Padrino::Cache::Helpers::Page
-        app.set :cache_store, Padrino::Cache::Store::File.new(File.join(app.root, 'tmp', 'cache'))
+        app.set :cache, Padrino::Cache::Store::File.new(Padrino.root('tmp', app.app_name.to_s ,'cache'))
         app.disable :caching
       end
       alias :included :registered
 
-      def padrino_route_added(route, verb, path, args, options, block)
+      def padrino_route_added(route, verb, path, args, options, block) #:nodoc
         Padrino::Cache::Helpers::Page.padrino_route_added(route, verb, path, args, options, block)
       end
     end
-  end # Helpers
+  end # Cache
 end # Padrino

data/lib/padrino-cache/helpers/cache_store.rb

@@ -1,12 +1,12 @@
 module Padrino
   module Cache
     module Helpers
-      module CacheStore
+      module CacheStore #:nodoc:
         def expire(*key)
           if key.size == 1 and key.first.is_a?(String)
-            self.class.cache_store.delete(key)
+            settings.cache.delete(key)
           else
-            self.class.cache_store.delete(self.class.url(*key))
+            settings.cache.delete(self.class.url(*key))
           end
         end
       end # CacheStore

data/lib/padrino-cache/helpers/fragment.rb

@@ -1,16 +1,55 @@
 module Padrino
   module Cache
     module Helpers
+      ##
+      # Whereas page-level caching, described in the first section of this document, works by
+      # grabbing the entire output of a route, fragment caching gives the developer fine-grained
+      # control of what gets cached. This type of caching occurs at whatever level you choose.
+      #
+      # Possible uses for fragment caching might include:
+      #
+      # * a 'feed' of some items on a page
+      # * output fetched (by proxy) from an API on a third-party site
+      # * parts of your page which are largely static/do not need re-rendering every request
+      # * any output which is expensive to render
+      #
       module Fragment
         include Padrino::Helpers::OutputHelpers
 
+        ##
+        # This helper is used anywhere in your application you would like to associate a fragment
+        # to be cached. It can be used in within a route:
+        #
+        # ==== Examples
+        #   # Caching a fragment
+        #   class MyTweets < Padrino::Application
+        #     enable :caching          # turns on caching mechanism
+        #
+        #     controller '/tweets' do
+        #       get :feed, :map => '/:username' do
+        #         username = params[:username]
+        #
+        #         @feed = cache( "feed_for_#{username}", :expires_in => 3 ) do
+        #           @tweets = Tweet.all( :username => username )
+        #           render 'partials/feedcontent'
+        #         end
+        #
+        #         # Below outputs @feed somewhere in its markup
+        #         render 'feeds/show'
+        #       end
+        #     end
+        #   end
+        #
         def cache(key, opts = nil, &block)
-          if self.class.caching?
-            if value = self.class.cache_store.get(key)
+          if settings.caching?
+            began_at = Time.now
+            if value = settings.cache.get(key.to_s)
+              logger.debug "GET Fragment (%0.4fms) %s" % [Time.now-began_at, key.to_s] if defined?(logger)
               concat_content(value)
             else
               value = capture_html(&block)
-              self.class.cache_store.set(key, value, opts)
+              settings.cache.set(key.to_s, value, opts)
+              logger.debug "SET Fragment (%0.4fms) %s" % [Time.now-began_at, key.to_s] if defined?(logger)
               concat_content(value)
             end
           end

data/lib/padrino-cache/helpers/page.rb

@@ -1,27 +1,81 @@
 module Padrino
   module Cache
     module Helpers
+      ##
+      # Page caching is easy to integrate into your application. To turn it on, simply provide the
+      # <tt>:cache => true</tt> option on either a controller or one of its routes.
+      # By default, cached content is persisted with a "file store"--that is, in a
+      # subdirectory of your application root.
+      #
+      # ==== Examples
+      #   # Setting content expiry time
+      #   class CachedApp < Padrino::Application
+      #     enable :caching          # turns on caching mechanism
+      #
+      #     controller '/blog', :cache => true do
+      #       expires_in 15
+      #
+      #       get '/entries' do
+      #         # expires_in 15 => can also be defined inside a single route
+      #         'just broke up eating twinkies lol'
+      #       end
+      #
+      #       get '/post/:id' do
+      #         cache_key :my_name
+      #         @post = Post.find(params[:id])
+      #       end
+      #     end
+      #   end
+      #
+      # You can manually expire cache with CachedApp.cache.delete(:my_name)
+      #
+      # Note that the "latest" method call to <tt>expires_in</tt> determines its value: if
+      # called within a route, as opposed to a controller definition, the route's
+      # value will be assumed.
+      #
       module Page
+        ##
+        # This helper is used within a controller or route to indicate how often content
+        # should persist in the cache.
+        #
+        # After <tt>seconds</tt> seconds have passed, content previously cached will
+        # be discarded and re-rendered. Code associated with that route will <em>not</em>
+        # be executed; rather, its previous output will be sent to the client with a
+        # 200 OK status code.
+        #
         def expires_in(time)
           @_last_expires_in = time
         end
 
-        def self.padrino_route_added(route, verb, path, args, options, block)
+        ##
+        # This helper is used within a route or route to indicate the name in the cache.
+        #
+        def cache_key(name)
+          @_cache_key = name
+        end
+
+        def self.padrino_route_added(route, verb, path, args, options, block) #:nodoc:
           if route.cache and %w(GET HEAD).include?(verb)
             route.add_before_filter(Proc.new {
-              if self.class.caching?
-                value = self.class.cache_store.get(route.cache.respond_to?(:call) ? route.cache.call(request) : env['PATH_INFO'])
+              if settings.caching?
+                began_at = Time.now
+                value = settings.cache.get(@_cache_key || env['PATH_INFO'])
+                @_cache_key = nil
+                logger.debug "GET Cache (%0.4fms) %s" % [Time.now-began_at, env['PATH_INFO']] if defined?(logger) && value
                 halt 200, value if value
               end
             })
             route.add_after_filter(Proc.new { |something|
-              if self.class.caching?
+              if settings.caching?
+                began_at = Time.now
                 if @_last_expires_in
-                  self.class.cache_store.set(route.cache.respond_to?(:call) ? route.cache.call(request) : env['PATH_INFO'], @_response_buffer, :expires_in => @_last_expires_in)
+                  settings.cache.set(@_cache_key || env['PATH_INFO'], @_response_buffer, :expires_in => @_last_expires_in)
                   @_last_expires_in = nil
                 else
-                  self.class.cache_store.set(route.cache.respond_to?(:call) ? route.cache.call(request) : env['PATH_INFO'], @_response_buffer)
+                  settings.cache.set(@_cache_key || env['PATH_INFO'], @_response_buffer)
                 end
+                @_cache_key = nil
+                logger.debug "SET Cache (%0.4fms) %s" % [Time.now-began_at, env['PATH_INFO']] if defined?(logger)
               end
             })
           end

data/lib/padrino-cache/store.rb

@@ -9,4 +9,4 @@ module Padrino
       autoload :Redis,    'padrino-cache/store/redis'
     end # Store
   end # Cache
-end # Padrino
+end # Padrino

data/lib/padrino-cache/store/file.rb

@@ -1,11 +1,29 @@
 module Padrino
   module Cache
     module Store
+      ##
+      # File based Cache Store
+      #
       class File
+        ##
+        # Initialize File store with File root
+        #
+        # ==== Examples
+        #   Padrino.cache = Padrino::Cache::Store::File.new("path/to")
+        #   # or from your app
+        #   set :cache, Padrino::Cache::Store::File.new("path/to")
+        #
         def initialize(root)
           @root = root
         end
 
+        ##
+        # Return the a value for the given key
+        #
+        # ==== Examples
+        #   # with MyApp.cache.set('records', records)
+        #   MyApp.cache.get('records')
+        #
         def get(key)
           init
           if ::File.exist?(path_for_key(key))
@@ -13,7 +31,7 @@ module Padrino
             expires_in, body = contents.split("\n", 2)
             expires_in = expires_in.to_i
             if expires_in == -1 or Time.new.to_i < expires_in
-              body
+              Marshal.load(body) if body
             else
               delete(key)
               nil
@@ -23,6 +41,14 @@ module Padrino
           end
         end
 
+        ##
+        # Set the value for a given key and optionally with an expire time
+        # Default expiry time is 86400.
+        #
+        # ==== Examples
+        #   MyApp.cache.set('records', records)
+        #   MyApp.cache.set('records', records, :expires_in => 30) # => 30 seconds
+        #
         def set(key, value, opts = nil)
           init
           if opts && opts[:expires_in]
@@ -31,30 +57,42 @@ module Padrino
           else
             expires_in = -1
           end
-          ::File.open(path_for_key(key), 'w') { |f| f << expires_in.to_s << "\n" << value.to_s } if value
+          value = Marshal.dump(value) if value
+          ::File.open(path_for_key(key), 'w') { |f| f << expires_in.to_s << "\n" << value } if value
         end
 
+        ##
+        # Delete the value for a given key
+        #
+        # ==== Examples
+        #   # with: MyApp.cache.set('records', records)
+        #   MyApp.cache.delete('records')
+        #
         def delete(key)
           init
           Array(key).each { |k| FileUtils.rm_rf(path_for_key(k)) }
         end
 
+        ##
+        # Reinitialize your cache
+        #
+        # ==== Examples
+        #   # with: MyApp.cache.set('records', records)
+        #   MyApp.cache.flush
+        #   MyApp.cache.get('records') # => nil
+        #
         def flush
           FileUtils.rm_rf(@root)
         end
 
         private
-        def path_for_key(key)
-          ::File.join(@root, Rack::Utils.escape(key.to_s))
-        end
+          def path_for_key(key)
+            ::File.join(@root, Rack::Utils.escape(key.to_s))
+          end
 
-        def init
-          unless @init
-            FileUtils.rm_rf(@root)
-            FileUtils.mkdir_p(@root)
-            @init = true
+          def init
+            FileUtils.mkdir_p(@root) unless ::File.exist?(@root)
           end
-        end
       end # File
     end # Store
   end # Cache

data/lib/padrino-cache/store/memcache.rb

@@ -1,25 +1,47 @@
-begin
-  require 'memcached'
-rescue LoadError
-  raise "You must install memecached to use the Memecache cache store backend"
-end
-
 module Padrino
   module Cache
     module Store
+      ##
+      # Memcache Cache Store
+      #
       class Memcache
-        def initialize(*args)
-          @backend = Memcached.new(*args)
+        ##
+        # Initialize Memcache store with client connection.
+        #
+        # ==== Examples
+        #   Padrino.cache = Padrino::Cache::Store::Memcache.new(::Memcached.new('127.0.0.1:11211'))
+        #   Padrino.cache = Padrino::Cache::Store::Memcache.new(::Memcached.new('127.0.0.1:11211', :exception_retry_limit => 1))
+        #   # or from your app
+        #   set :cache, Padrino::Cache::Store::Memcache.new(::Memcached.new('127.0.0.1:11211'))
+        #   set :cache, Padrino::Cache::Store::Memcache.new(::Memcached.new('127.0.0.1:11211', :exception_retry_limit => 1))
+        #
+        def initialize(client)
+          @backend = client
         rescue
           raise
         end
 
+        ##
+        # Return the a value for the given key
+        #
+        # ==== Examples
+        #   # with MyApp.cache.set('records', records)
+        #   MyApp.cache.get('records')
+        #
         def get(key)
           @backend.get(key)
         rescue Memcached::NotFound
           nil
         end
 
+        ##
+        # Set the value for a given key and optionally with an expire time
+        # Default expiry time is 86400.
+        #
+        # ==== Examples
+        #   MyApp.cache.set('records', records)
+        #   MyApp.cache.set('records', records, :expires_in => 30) # => 30 seconds
+        #
         def set(key, value, opts = nil)
           if opts && opts[:expires_in]
             expires_in = opts[:expires_in].to_i
@@ -30,10 +52,25 @@ module Padrino
           end
         end
 
+        ##
+        # Delete the value for a given key
+        #
+        # ==== Examples
+        #   # with: MyApp.cache.set('records', records)
+        #   MyApp.cache.delete('records')
+        #
         def delete(key)
           @backend.delete(key)
         end
 
+        ##
+        # Reinitialize your cache
+        #
+        # ==== Examples
+        #   # with: MyApp.cache.set('records', records)
+        #   MyApp.cache.flush
+        #   MyApp.cache.get('records') # => nil
+        #
         def flush
           @backend.flush
         end

data/lib/padrino-cache/store/memory.rb

@@ -1,11 +1,29 @@
 module Padrino
   module Cache
     module Store
+      ##
+      # Memory Cache Store
+      #
       class Memory
+        ##
+        # Initialize Memory Store with memory size
+        #
+        # ==== Examples
+        #   Padrino.cache = Padrino::Cache::Store::Memory.new(10000)
+        #   # or from your app
+        #   set :cache, Padrino::Cache::Store::Memory.new(10000)
+        #
         def initialize(size = 5000)
           @size, @entries, @index = size, [], {}
         end
 
+        ##
+        # Return the a value for the given key
+        #
+        # ==== Examples
+        #   # with MyApp.cache.set('records', records)
+        #   MyApp.cache.get('records')
+        #
         def get(key)
           if @index.key?(key) and value = @index[key]
             expires_in, body = value
@@ -21,6 +39,14 @@ module Padrino
           end
         end
 
+        ##
+        # Set the value for a given key and optionally with an expire time.
+        # Default expiry is 86400.
+        #
+        # ==== Examples
+        #   MyApp.cache.set('records', records)
+        #   MyApp.cache.set('records', records, :expires_in => 30) # => 30 seconds
+        #
         def set(key, value, opts = nil)
           delete(key) if @index.key?(key)
           if opts && opts[:expires_in]
@@ -37,10 +63,25 @@ module Padrino
           end
         end
 
+        ##
+        # Delete the value for a given key
+        #
+        # ==== Examples
+        #   # with: MyApp.cache.set('records', records)
+        #   MyApp.cache.delete('records')
+        #
         def delete(key)
           @index.delete(key)
         end
 
+        ##
+        # Reinitialize your cache
+        #
+        # ==== Examples
+        #   # with: MyApp.cache.set('records', records)
+        #   MyApp.cache.flush
+        #   MyApp.cache.get('records') # => nil
+        #
         def flush
           @index = Hash.new
         end

data/lib/padrino-cache/store/redis.rb

@@ -1,34 +1,72 @@
-begin
-  require 'redis'
-rescue LoadError
-  raise "You must install redis to use the Redis cache store backend"
-end
-
 module Padrino
   module Cache
     module Store
+      ##
+      # Redis Cache Store
+      #
       class Redis
-        def initialize(*args)
-          @backend = ::Redis.new(*args)
+        ##
+        # Initialize Redis store with client connection.
+        #
+        # ==== Examples
+        #   Padrino.cache = Padrino::Cache::Store::Redis.new(::Redis.new(:host => '127.0.0.1', :port => 6379, :db => 0))
+        #   # or from your app
+        #   set :cache, Padrino::Cache::Store::Redis.new(::Redis.new(:host => '127.0.0.1', :port => 6379, :db => 0))
+        #
+        def initialize(client)
+          @backend = client
         end
 
+        ##
+        # Return the a value for the given key
+        #
+        # ==== Examples
+        #   # with MyApp.cache.set('records', records)
+        #   MyApp.cache.get('records')
+        #
         def get(key)
-          @backend.get(key)
+          code = @backend.get(key)
+          Marshal.load(code) if code.present?
         end
 
+        ##
+        # Set the value for a given key and optionally with an expire time
+        # Default expiry is 86400.
+        #
+        # ==== Examples
+        #   MyApp.cache.set('records', records)
+        #   MyApp.cache.set('records', records, :expires_in => 30) # => 30 seconds
+        #
         def set(key, value, opts = nil)
+          value = Marshal.dump(value) if value
           if opts && opts[:expires_in]
             expires_in = opts[:expires_in].to_i
+            expires_in = expires_in if expires_in < EXPIRES_EDGE
             @backend.setex(key, expires_in, value)
           else
             @backend.set(key, value)
           end
         end
 
+        ##
+        # Delete the value for a given key
+        #
+        # ==== Examples
+        #   # with: MyApp.cache.set('records', records)
+        #   MyApp.cache.delete('records')
+        #
         def delete(key)
           @backend.del(key)
         end
 
+        ##
+        # Reinitialize your cache
+        #
+        # ==== Examples
+        #   # with: MyApp.cache.set('records', records)
+        #   MyApp.cache.flush
+        #   MyApp.cache.get('records') # => nil
+        #
         def flush
           @backend.flushdb
         end

data/test/helper.rb

@@ -1,5 +1,5 @@
 ENV['PADRINO_ENV'] = 'test'
-PADRINO_ROOT = File.dirname(__FILE__) unless defined? PADRINO_ROOT
+PADRINO_ROOT = File.dirname(__FILE__) unless defined?(PADRINO_ROOT)
 
 require File.expand_path('../../../load_paths', __FILE__)
 require File.join(File.dirname(__FILE__), '..', '..', 'padrino-core', 'test', 'helper')

data/test/test_padrino_cache.rb

@@ -55,15 +55,17 @@ class TestPadrinoCache < Test::Unit::TestCase
     mock_app do
       register Padrino::Cache
       enable :caching
-      get('/foo', :cache => proc{|req| "cached"}){ 'test' }
-      get('/bar', :cache => proc{|req| "cached"}){ halt 500 }
+      get('/foo', :cache => true){ cache_key :foo; 'foo' }
+      get('/bar', :cache => true){ cache_key :bar; 'bar' }
     end
     get "/foo"
     assert_equal 200, status
-    assert_equal 'test', body
+    assert_equal 'foo', body
+    assert_equal 'foo', @app.cache.get(:foo)
     get "/bar"
     assert_equal 200, status
-    assert_equal 'test', body
+    assert_equal 'bar', body
+    assert_equal 'bar', @app.cache.get(:bar)
   end
 
   should 'delete based on urls' do

data/test/test_stores.rb

@@ -1,61 +1,97 @@
 require File.expand_path(File.dirname(__FILE__) + '/helper')
 
+class Foo
+  def bar; "bar"; end
+end
+
 COMMON_TESTS = <<-HERE_DOC
-should 'set and get a value' do
-  @cache.set('val', 'test')
-  assert_equal 'test', @cache.get('val')
+should 'set and get an object' do
+  Padrino.cache.set('val', Foo.new)
+  assert_equal "bar", Padrino.cache.get('val').bar
+end
+
+should 'set ang get a nil value' do
+  Padrino.cache.set('val', nil)
+  assert_equal nil, Padrino.cache.get('val')
+end
+
+should 'set and get a raw value' do
+  Padrino.cache.set('val', 'foo')
+  assert_equal 'foo', Padrino.cache.get('val')
 end
 
 should "return nil trying to get a value that doesn't exist" do
-  assert_equal nil, @cache.get('test')
+  assert_equal nil, Padrino.cache.get('test')
 end
 
 should "set a value that expires" do
-  @cache.set('val', 'test', :expires_in => 1)
-  assert_equal 'test', @cache.get('val')
+  Padrino.cache.set('val', 'test', :expires_in => 1)
+  assert_equal 'test', Padrino.cache.get('val')
   sleep 2
-  assert_equal nil, @cache.get('val')
+  assert_equal nil, Padrino.cache.get('val')
 end
 
 should 'delete a value' do
-  @cache.set('val', 'test')
-  assert_equal 'test', @cache.get('val')
-  @cache.delete('val')
-  assert_equal nil, @cache.get('val')
+  Padrino.cache.set('val', 'test')
+  assert_equal 'test', Padrino.cache.get('val')
+  Padrino.cache.delete('val')
+  assert_equal nil, Padrino.cache.get('val')
 end
 HERE_DOC
 
 begin
+  require 'memcached'
   # we're just going to assume memcached is running on the default port
-  Padrino::Cache::Store::Memcache.new('127.0.0.1:11211', :exception_retry_limit => 1).set('ping','alive')
+  Padrino::Cache::Store::Memcache.new(::Memcached.new('127.0.0.1:11211', :exception_retry_limit => 1)).set('ping','alive')
 
   class TestMemcacheStore < Test::Unit::TestCase
     def setup
-      @cache = Padrino::Cache::Store::Memcache.new('127.0.0.1:11211', :exception_retry_limit => 1)
-      @cache.flush
+      Padrino.cache = Padrino::Cache::Store::Memcache.new(::Memcached.new('127.0.0.1:11211', :exception_retry_limit => 1))
+      Padrino.cache.flush
     end
 
     def teardown
-      @cache.flush
+      Padrino.cache.flush
     end
 
     eval COMMON_TESTS
   end
-rescue
-  warn "Skipping memcached tests"
+rescue LoadError
+  warn "Skipping memcached with memcached library tests"
 end
 
+begin
+  require 'dalli'
+  # we're just going to assume memcached is running on the default port
+  Padrino::Cache::Store::Memcache.new(::Dalli::Client.new('127.0.0.1:11211', :exception_retry_limit => 1).set('ping','alive'))
+
+  class TestMemcacheWithDalliStore < Test::Unit::TestCase
+    def setup
+      Padrino.cache = Padrino::Cache::Store::Memcache.new(::Dalli::Client.new('127.0.0.1:11211', :exception_retry_limit => 1))
+      Padrino.cache.flush
+    end
+
+    def teardown
+      Padrino.cache.flush
+    end
+
+    eval COMMON_TESTS
+  end
+rescue LoadError
+  warn "Skipping memcached with dalli library tests"
+end
 
 begin
-  Padrino::Cache::Store::Redis.new(:host => '127.0.0.1', :port => 6379, :db => 0).set('ping','alive')
+  require 'redis'
+  Padrino::Cache::Store::Redis.new(::Redis.new(:host => '127.0.0.1', :port => 6379, :db => 0).set('ping','alive'))
   class TestRedisStore < Test::Unit::TestCase
     def setup
-      @cache = Padrino::Cache::Store::Redis.new(:host => '127.0.0.1', :port => 6379, :db => 0)
-      @cache.flush
+      Padrino.cache = Padrino::Cache::Store::Redis.new(::Redis.new(:host => '127.0.0.1', :port => 6379, :db => 0))
+      Padrino.cache.flush
     end
 
     def teardown
-      @cache.flush
+      Padrino.cache.flush
     end
 
     eval COMMON_TESTS
@@ -68,11 +104,11 @@ class TestFileStore < Test::Unit::TestCase
   def setup
     @apptmp = "#{Dir.tmpdir}/padrino-tests/#{UUID.new.generate}"
     FileUtils.mkdir_p(@apptmp)
-    @cache = Padrino::Cache::Store::File.new(@apptmp)
+    Padrino.cache = Padrino::Cache::Store::File.new(@apptmp)
   end
 
   def teardown
-    @cache.flush
+    Padrino.cache.flush
   end
 
   eval COMMON_TESTS
@@ -80,18 +116,18 @@ end
 
 class TestInMemoryStore < Test::Unit::TestCase
   def setup
-    @cache = Padrino::Cache::Store::Memory.new(50)
+    Padrino.cache = Padrino::Cache::Store::Memory.new(50)
   end
 
   def teardown
-    @cache.flush
+    Padrino.cache.flush
   end
 
   eval COMMON_TESTS
 
   should "only store 50 entries" do
-    51.times { |i| @cache.set(i.to_s, i.to_s) }
-    assert_equal nil, @cache.get('0')
-    assert_equal '1', @cache.get('1')
+    51.times { |i| Padrino.cache.set(i.to_s, i.to_s) }
+    assert_equal nil, Padrino.cache.get('0')
+    assert_equal '1', Padrino.cache.get('1')
   end
-end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: padrino-cache
 version: !ruby/object:Gem::Version 
-  hash: 11
+  hash: 9
   prerelease: 
   segments: 
   - 0
   - 9
-  - 24
-  version: 0.9.24
+  - 25
+  version: 0.9.25
 platform: ruby
 authors: 
 - Padrino Team
@@ -18,7 +18,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-28 00:00:00 +02:00
+date: 2011-04-27 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -29,12 +29,12 @@ dependencies:
     requirements: 
     - - "="
       - !ruby/object:Gem::Version 
-        hash: 11
+        hash: 9
         segments: 
         - 0
         - 9
-        - 24
-        version: 0.9.24
+        - 25
+        version: 0.9.25
   type: :runtime
   version_requirements: *id001
 description: Caching support for memcached, page and fragment
@@ -82,7 +82,6 @@ files:
 - test/tmp/#<class:0x0000010086b838>/cache/%2Ffoo
 - test/tmp/#<class:0x0000010086e588>/cache/%2Ffoo
 - test/tmp/#<class:0x00000100871918>/cache/%2Ffoo
-- test/tmp/#<class:0x00000100882218>/cache/%2Ffoo
 - test/tmp/#<class:0x0000010089b560>/cache/%2Ffoo
 - test/tmp/#<class:0x000001008c3dd0>/cache/test
 - test/tmp/#<class:0x000001009036d8>/cache/%2Ffoo
@@ -94,7 +93,6 @@ files:
 - test/tmp/#<class:0x00000100954b00>/cache/bar
 - test/tmp/#<class:0x00000100954b00>/cache/foo
 - test/tmp/#<class:0x0000010095f5a0>/cache/%2Ffoo%2F12
-- test/tmp/#<class:0x00000100961058>/cache/%2Ffoo%2F12
 - test/tmp/#<class:0x00000100967ae8>/cache/test
 - test/tmp/#<class:0x0000010096afe0>/cache/%2Ffoo
 - test/tmp/#<class:0x00000100973ff0>/cache/test
@@ -124,7 +122,6 @@ files:
 - test/tmp/#<class:0x00000100b458d8>/cache/%2Ffoo
 - test/tmp/#<class:0x00000100b480d8>/cache/%2Ffoo
 - test/tmp/#<class:0x00000100b53b68>/cache/%2Ffoo%2F12
-- test/tmp/#<class:0x00000100b66fd8>/cache/%2Ffoo
 - test/tmp/#<class:0x00000100b6d130>/cache/test
 - test/tmp/#<class:0x00000100b7bd70>/cache/test
 - test/tmp/#<class:0x00000100b7ebb0>/cache/test
@@ -178,27 +175,21 @@ files:
 - test/tmp/#<class:0x000001011812b0>/cache/foo
 - test/tmp/#<class:0x000001011868f0>/cache/%2Ffoo%2F12
 - test/tmp/#<class:0x000001011d55b8>/cache/%2Ffoo
-- test/tmp/#<class:0x000001011f4e68>/cache/bar
-- test/tmp/#<class:0x000001011f4e68>/cache/foo
 - test/tmp/#<class:0x000001011fbf88>/cache/%2Ffoo
 - test/tmp/#<class:0x0000010121ec40>/cache/test
 - test/tmp/#<class:0x000001012285b0>/cache/test
 - test/tmp/#<class:0x0000010126c6c0>/cache/test
 - test/tmp/#<class:0x00000101294378>/cache/%2Ffoo
-- test/tmp/#<class:0x000001012ac7c0>/cache/%2Ffoo
 - test/tmp/#<class:0x000001012fb2a8>/cache/%2Ffoo
 - test/tmp/#<class:0x00000101300000>/cache/test
 - test/tmp/#<class:0x000001013029b8>/cache/%2Ffoo
 - test/tmp/#<class:0x000001013225b0>/cache/%2Ffoo
 - test/tmp/#<class:0x00000101348bc0>/cache/test
-- test/tmp/#<class:0x00000101363448>/cache/test
 - test/tmp/#<class:0x000001013c8cf8>/cache/test
 - test/tmp/#<class:0x000001013f3b38>/cache/test
 - test/tmp/#<class:0x00000101400a40>/cache/%2Ffoo
 - test/tmp/#<class:0x000001014130f0>/cache/%2Ffoo
-- test/tmp/#<class:0x000001014a5540>/cache/%2Ffoo
 - test/tmp/#<class:0x000001014d8f08>/cache/test
-- test/tmp/#<class:0x00000101588070>/cache/test
 - test/tmp/#<class:0x00000101815e50>/cache/%2Ffoo
 - test/tmp/#<class:0x0000010185bc70>/cache/test
 - test/tmp/#<class:0x0000010186eca8>/cache/cached
@@ -329,8 +320,6 @@ files:
 - test/tmp/#<class:0x107ddff76>/cache/test
 - test/tmp/#<class:0x108a77250>/cache/%2Ffoo
 - test/tmp/#<class:0x108aac748>/cache/test
-- test/tmp/#<class:0x108aacd38>/cache/bar
-- test/tmp/#<class:0x108aacd38>/cache/foo
 - test/tmp/#<class:0x108aeb0b0>/cache/test
 - test/tmp/#<class:0x108af8850>/cache/test
 - test/tmp/#<class:0x108b0a320>/cache/%2Ffoo
@@ -346,13 +335,11 @@ files:
 - test/tmp/#<class:0x108b21de0>/cache/foo
 - test/tmp/#<class:0x108b35778>/cache/%2Ffoo
 - test/tmp/#<class:0x108b374d8>/cache/%2Ffoo
-- test/tmp/#<class:0x108b39a30>/cache/%2Ffoo
 - test/tmp/#<class:0x108b3a908>/cache/%2Ffoo
 - test/tmp/#<class:0x108b3b4e8>/cache/%2Ffoo
 - test/tmp/#<class:0x108b3b588>/cache/%2Ffoo
 - test/tmp/#<class:0x108b3b718>/cache/%2Ffoo
 - test/tmp/#<class:0x108b46640>/cache/test
-- test/tmp/#<class:0x108b51e00>/cache/%2Ffoo
 - test/tmp/#<class:0x108b5fdc0>/cache/test
 - test/tmp/#<class:0x108b60c98>/cache/bar
 - test/tmp/#<class:0x108b60c98>/cache/foo
@@ -372,7 +359,6 @@ files:
 - test/tmp/#<class:0x108b9c798>/cache/%2Ffoo
 - test/tmp/#<class:0x108b9c838>/cache/%2Ffoo
 - test/tmp/#<class:0x108b9c9c8>/cache/%2Ffoo
-- test/tmp/#<class:0x108b9f4c0>/cache/%2Ffoo%2F12
 - test/tmp/#<class:0x108ba3598>/cache/%2Ffoo
 - test/tmp/#<class:0x108ba8750>/cache/%2Ffoo
 - test/tmp/#<class:0x108ba8930>/cache/test
@@ -393,7 +379,6 @@ files:
 - test/tmp/#<class:0x108bd1e48>/cache/test
 - test/tmp/#<class:0x108bd1ee8>/cache/test
 - test/tmp/#<class:0x108bd2078>/cache/test
-- test/tmp/#<class:0x108bd6330>/cache/%2Ffoo
 - test/tmp/#<class:0x108bd8720>/cache/%2Ffoo
 - test/tmp/#<class:0x108bd9210>/cache/%2Ffoo
 - test/tmp/#<class:0x108bd9cb0>/cache/%2Ffoo
@@ -422,7 +407,6 @@ files:
 - test/tmp/#<class:0x108c14ec8>/cache/test
 - test/tmp/#<class:0x108c166b0>/cache/test
 - test/tmp/#<class:0x108c16cc8>/cache/test
-- test/tmp/#<class:0x108c20ac0>/cache/test
 - test/tmp/#<class:0x108c23b30>/cache/test
 - test/tmp/#<class:0x108c24008>/cache/test
 - test/tmp/#<class:0x108c24ff8>/cache/%2Ffoo
@@ -443,7 +427,6 @@ files:
 - test/tmp/#<class:0x108c73a68>/cache/test
 - test/tmp/#<class:0x108c74b70>/cache/%2Ffoo%2F12
 - test/tmp/#<class:0x108c75430>/cache/test
-- test/tmp/#<class:0x108c84e30>/cache/%2Ffoo
 - test/tmp/#<class:0x108c85e20>/cache/bar
 - test/tmp/#<class:0x108c85e20>/cache/foo
 - test/tmp/#<class:0x108c87310>/cache/bar
@@ -477,7 +460,6 @@ files:
 - test/tmp/#<class:0x108cd5100>/cache/%2Ffoo
 - test/tmp/#<class:0x108cd6e10>/cache/%2Ffoo
 - test/tmp/#<class:0x108cd7798>/cache/%2Ffoo
-- test/tmp/#<class:0x108ced9d0>/cache/test
 - test/tmp/#<class:0x108cf3c68>/cache/%2Ffoo
 - test/tmp/#<class:0x108cf5b58>/cache/test
 - test/tmp/#<class:0x114dee6e2>/cache/%2Ffoo