benschwarz-merb-cache 1.0.0

data/lib/merb-cache/merb_ext/controller/class_methods.rb

@@ -0,0 +1,244 @@
+module Merb::Cache::Controller
+  module ClassMethods
+    def self.extended(base)
+      base.send :class_inheritable_accessor, :_cache
+      base._cache = {}
+    end
+    
+    
+    def cache!(conditions = {})
+      before(:_cache_before, conditions.only(:if, :unless).merge(:with => conditions))
+      after(:_cache_after, conditions.only(:if, :unless).merge(:with => conditions))
+    end
+
+    # cache is an alias to cache_action, it will take multiple :actions and pass the conditions hash for each action
+    #
+    # @param *actions<Array[Symbol]> actions to cache
+    #
+    # @param options<Hash> Conditions passed to the store and two options specific to cache
+    # 
+    # @note
+    #   Specific options for cache:
+    #     - :store (or :stores) use the specified store
+    #     - :params list of params to pass to the store (see _parameters_and_conditions)
+    #
+    # @example cache :index, :show, :expire_in => 30 # caches the index and show action for 30 seconds
+    # @example cache :index, :store => :page_store   # caches the index action using the page store
+    # @example cache :index, :params => [:page, :q], :store => :action_store # caches the index action using the action store and passing the :page and :q params to the action store (NB. :params => <Array> has no effect on the page store)
+    #
+    # @api public
+    def cache(*actions)
+      options = extract_options_from_args!(actions) || {}
+      actions.each {|a| cache_action(a, options)}
+    end
+    
+    # cache action will cache the action
+    # Parameters are the same as cache but only one action is allowed
+    #
+    # @api private
+    def cache_action(action, conditions = {})
+      self._cache[action] = conditions
+      before("_cache_#{action}_before", conditions.only(:if, :unless).merge(:with => [conditions], :only => action))
+      after("_cache_#{action}_after", conditions.only(:if, :unless).merge(:with => [conditions], :only => action))
+      alias_method "_cache_#{action}_before", :_cache_before
+      alias_method "_cache_#{action}_after",  :_cache_after
+    end
+  
+    # Checks if the action called with a certain request would be cached or not. Usefull for troubleshooting problems
+    #
+    # @param action<String> action to check
+    # 
+    # @param request_hash<Hash> The params that the request would have. :uri and :method are also supported to indicate the :uri and :method of the request. :store and :stores indicate the cache store to use.
+    #
+    # @note
+    #   if not specified, the default http method is :get and the default uri is '/'
+    #
+    # @return <TrueClass, FalseClass>
+    #   True if such a request would be cached
+    #
+    # @example Project.caches? :index, :uri => '/projects', :params => {:q => 'test'}, :method => :get
+    # @example Project.caches? :show, :uri => url(:project, @project), :params => {:id => @project.id}
+    #
+    # @api public
+    def caches?(action, params = {})
+      controller, conditions = _controller_and_conditions(action, params)
+      Merb::Cache[controller._lookup_store(conditions)].writable?(controller, *controller._parameters_and_conditions(conditions))
+    end
+    
+    # Checks if the action called with a certain request has been cached or not.
+    #
+    # @param action<String> action to check
+    # 
+    # @param request_hash<Hash> The params that the request would have. :uri and :method are also supported to indicate the :uri and :method of the request. :store and :stores indicate the cache store to use.
+    #
+    # @note
+    #   if not specified, the default http method is :get and the default uri is '/'
+    #
+    # @return <TrueClass, FalseClass>
+    #   True if such a request has been cached
+    #
+    # @example Project.caches? :index, :uri => '/projects', :params => {:q => 'test'}, :method => :get
+    #
+    # @api public    
+    def cached?(action, params = {})
+      controller, conditions = _controller_and_conditions(action, params)
+      Merb::Cache[controller._lookup_store(conditions)].exists?(controller, *controller._parameters_and_conditions(conditions))
+    end
+
+    # Returns the cache for the action with the given request
+    #
+    # @param action<String> action to check
+    # 
+    # @param request_hash<Hash> The params that the request would have. :uri and :method are also supported to indicate the :uri and :method of the request. :store and :stores indicate the cache store to use.
+    #
+    # @note
+    #   if not specified, the default http method is :get and the default uri is '/'
+    #
+    # @return <Object>
+    #   The content of the cache if available, else nil
+    #
+    # @example Project.cache_for :index, :uri => '/projects', :params => {:q => 'test'}, :method => :get
+    #
+    # @api public  
+    def cache_for(action, params = {})
+      controller, conditions = _controller_and_conditions(action, params)
+      Merb::Cache[controller._lookup_store(conditions)].read(controller, *controller._parameters_and_conditions(conditions).first)      
+    end
+    
+    # Deletes the cache for the action with the given request
+    #
+    # @param action<String> action
+    # 
+    # @param request_hash<Hash> The params that the request would have. :uri and :method are also supported to indicate the :uri and :method of the request. :store and :stores indicate the cache store to use.
+    #
+    # @note
+    #   if not specified, the default http method is :get and the default uri is '/'
+    #
+    #
+    # @example Project.delete_cache_for :index, :uri => '/projects', :params => {:q => 'test'}, :method => :get
+    #
+    # @api public
+    def delete_cache_for(action, params = {})
+      controller, conditions = _controller_and_conditions(action, params)
+      Merb::Cache[controller._lookup_store(conditions)].delete(controller, *controller._parameters_and_conditions(conditions).first)      
+    end
+  
+    # Caches specified with eager_cache will be run after #trigger_action has been run
+    # without holding some poor user up generating the cache (through run_later)
+    # 
+    # @param trigger_action<Symbol, Array[*Symbol]> The actions that will trigger the eager caching
+    # @param target<Array[Controller,Symbol], Symbol> the target option to cache (if no controller is given, the current controller is used)
+    # @param opts<Hash>  Request options. See note for details.
+    # @param blk<Block> Block run to generate the request or controller used for eager caching after trigger_action has run
+    #
+    # @note
+    #   Valid request options are:
+    #     - :uri the uri of the resource you want to eager cache (needed by the page store but can be provided instead by a block)
+    #     - :method http method used (defaults to :get)
+    #
+    # @example eager_cache :update, :index, :uri => '/articles' # When the update action is completed, a get request to :index with '/articles' uri will be cached (if you use the page store, this will be stored in '/articles.html')
+    # @example eager_cache :create, :index # Same after the create action but since no uri is given, the current uri is used with the default http method (:get). Useful default for resource controllers
+    # @example eager_cache(:create, [Timeline, :index]) {{ :uri => build_url(:timelines)}} 
+    #
+    # @api public
+    def eager_cache(trigger_actions, target = nil, opts = {}, &blk)
+      trigger_actions = [*trigger_actions]
+      target, conditions = nil, target if target.is_a? Hash
+  
+      trigger_actions.each do |trigger_action|
+
+        if target.is_a? Array
+          target_controller, target_action = *target
+        else
+          target_controller, target_action = self, (target || trigger_action)
+        end
+
+        after("_eager_cache_#{trigger_action}_to_#{target_controller.name.snake_case}__#{target_action}_after", opts.only(:if, :unless).merge(:with => [target_controller, target_action, opts, blk], :only => trigger_action))
+        alias_method "_eager_cache_#{trigger_action}_to_#{target_controller.name.snake_case}__#{target_action}_after", :_eager_cache_after
+      end
+    end
+  
+    # Dispatches eager caches to a worker process
+    #
+    # @param action<String> The actiont to dispatch
+    # @param params<Hash> params of the request (passed to the block)
+    # @param env<Hash> environment variables of the request (passed to the block)
+    # @param blk<Block> block used to build the request (should return a hash, request or a controller)
+    #
+    # @api private
+    def eager_dispatch(action, params = {}, env = {}, blk = nil)
+      kontroller = if blk.nil?
+        new(build_request(env))
+      else
+        result = case blk.arity
+          when 0  then  blk[]
+          when 1  then  blk[params]
+          else          blk[*[params, env]]
+        end
+
+        case result
+        when NilClass         then new(build_request(env))
+        when Hash, Mash       then new(build_request(result))
+        when Merb::Request    then new(result)
+        when Merb::Controller then result
+        else raise ArgumentError, "Block to eager_cache must return nil, the env Hash, a Request object, or a Controller object"
+        end
+      end
+
+      kontroller.force_cache!
+
+      kontroller._dispatch(action)
+
+      kontroller
+    end
+  
+    # Builds a request that will be sent to the merb worker process to be
+    # cached without holding some poor user up generating the cache (through run_later)
+    #
+    # @param request_hash<Hash> hash used to describe the request
+    #
+    # @note Acceptable options for the request hash
+    #   - :uri The uri of the request
+    #   - :method The http method (defaults to :get)
+    #   - :params The params
+    #   - any env variable you may need
+    #
+    # @return <Request>
+    #   A request for the given arguments
+    #
+    # @example build_request(:params => {:id => @article.id}, :method => :put, :uri => build_url(:article, @article)}) # a request corresponding to the update action of a resourceful controller
+    #
+    # @api public
+    def build_request(request_hash = {})
+      Merb::Cache::CacheRequest.new(request_hash.delete(:uri), request_hash.delete(:params), request_hash)
+    end
+
+    # @see Router.url
+    def build_url(*args)
+      Merb::Router.url(*args)
+    end
+    
+    # Used by cache?, cached?, cache_for and delete_cache_for to generate the controller from the given parameters.
+    #
+    # @param action<String> the cached action
+    # @param request_hash<Hash> params from the request.
+    #
+    # @note
+    #   in the request hash, :params, :uri and :method are supported. Additionally :store and :stores specify which store to use. 
+    #
+    # @return <Array[Controller, Hash]>
+    #   the controller built using the request corresponding to params
+    #   the conditions for the cached action
+    #
+    # @api private
+    def _controller_and_conditions(action, request_hash)
+      conditions = self._cache[action]
+      conditions.merge!(request_hash.only(:store, :stores))
+      request_hash.extract!(:store, :stores)
+      controller = new(build_request(request_hash))
+      controller.action_name = action
+
+      [controller, conditions]
+    end
+  end
+end

data/lib/merb-cache/merb_ext/controller/instance_methods.rb

@@ -0,0 +1,163 @@
+module Merb::Cache::Controller
+  module InstanceMethods
+    # Partial / fragment caches are written / retrieved using fetch_partial
+    #
+    # @params template<String, Symbol> The path to the template, relative to the current controller or the template root
+    # @params opts<Hash> Options for the partial (@see Merb::RenderMixin#partial)
+    # @params conditions<Hash> conditions for the store (also accept :store for specifying the store)
+    #
+    # @note
+    #   The opts hash supports :params_for_cache which can be used to specify which parameters will be passed to the store.
+    #   If you call `fetch_partial` with parameters that are instance of model it will fail, so you need to use :params_for_cache in this case
+    #
+    # @example fetch_partial :bar
+    # @example fetch_partial :foo, :with => @foo, :params_for_cache => {:foo => @foo.id}
+    # @example fetch_partial :store, :with => @items, :params_for_cache => {:store_version => @store.version, :store_id => @store.id} 
+    def fetch_partial(template, opts={}, conditions = {})
+      template_id = template.to_s
+      if template_id =~ %r{^/}
+        template_path = File.dirname(template_id) / "_#{File.basename(template_id)}"
+      else
+        kontroller = (m = template_id.match(/.*(?=\/)/)) ? m[0] : controller_name
+        template_id = "_#{File.basename(template_id)}"
+      end
+
+      unused, template_key = _template_for(template_id, opts.delete(:format) || content_type, kontroller, template_path)
+      template_key.gsub!(File.expand_path(Merb.root),'')
+
+      fetch_proc = lambda { partial(template, opts) }
+      params_for_cache = opts.delete(:params_for_cache) || opts.dup
+
+      concat(Merb::Cache[_lookup_store(conditions)].fetch(template_key, params_for_cache, conditions, &fetch_proc), fetch_proc.binding)
+    end
+
+
+
+    # Used to cache the result of a long running block
+    #
+    # @params opts<Hash> options (only uses :cache_key to define the key used)
+    # @params conditions<Hash> conditions passed to the store (also accept :store for specifying the store)
+    # @params &proc<Block> block generating the result to cache
+    #
+    # @example fetch_fragment { #stuff to do}
+    #
+    # @api public
+    def fetch_fragment(opts = {}, conditions = {}, &proc)
+      if opts[:cache_key].blank?
+        file, line = proc.to_s.scan(%r{^#<Proc:0x\w+@(.+):(\d+)>$}).first
+        fragment_key = "#{file}[#{line}]"
+      else
+        fragment_key = opts.delete(:cache_key)
+      end
+      
+      concat(Merb::Cache[_lookup_store(conditions)].fetch(fragment_key, opts, conditions) { capture(&proc) }, proc.binding)
+    end
+
+    def _cache_before(conditions = {})
+      unless @_force_cache
+        if @_skip_cache.nil? && data = Merb::Cache[_lookup_store(conditions)].read(self, _parameters_and_conditions(conditions).first)
+          throw(:halt, data)
+          @_cached = true
+        else
+          @_cached = false
+        end
+      end
+    end
+
+    def _cache_after(conditions = {})
+      if @_cached == false
+        if Merb::Cache[_lookup_store(conditions)].write(self, nil, *_parameters_and_conditions(conditions))
+          @_cache_write = true
+        end
+      end
+    end
+
+    def _eager_cache_after(klass, action, options = {}, blk = nil)
+      unless @skip_cache
+        run_later do
+          env = request.env.dup
+          env.merge!(options.only(:method, :uri))
+
+          controller = klass.eager_dispatch(action, request.params.dup, env, blk)
+          conditions = self.class._cache[action]
+          
+          Merb::Cache[controller._lookup_store(conditions)].write(controller, nil, *controller._parameters_and_conditions(conditions))
+        end
+      end
+    end
+
+    # After the request has finished, cache the action without holding some poor user up generating the cache (through run_later)
+    # 
+    # @param action<Array[Controller,Symbol], Symbol> the target option to cache (if no controller is given, the current controller is used)
+    # @param options<Hash> Request options. See note for details
+    # @param env<Hash>  request environment variables
+    # @param blk<Block> Block run to generate the request or controller used for eager caching after trigger_action has run
+    #
+    # @note
+    #   There are a number of options specific to eager_cache in the conditions hash
+    #     - :uri the uri of the resource you want to eager cache (needed by the page store but can be provided instead by a block)
+    #     - :method http method used (defaults to :get)
+    #     - :params hash of params to use when sending the request to cache
+    #
+    # @example eager_cache  :index, :uri => '/articles' # When the update action is completed, a get request to :index with '/articles' uri will be cached (if you use the page store, this will be stored in '/articles.html')
+    # @example eager_cache :index # Same after the create action but since no uri is given, the current uri is used with the default http method (:get). Useful default for resource controllers
+    # @example eager_cache([Timeline, :index]) :uri => url(:timelines)}} 
+    #
+    # @api public
+    def eager_cache(action, options = {}, env = request.env.dup, &blk)
+      unless @_skip_cache
+        if action.is_a?(Array)
+          klass, action = *action
+        else
+          klass = self.class
+        end
+
+        run_later do
+          env = request.env.dup
+          env.merge!(options.only(:method, :uri, :params))
+          controller = klass.eager_dispatch(action, {}, env, blk)
+        end
+      end
+    end
+
+    def skip_cache!; @_skip_cache = true; end
+    def force_cache!; @_force_cache = true; end
+
+    def _lookup_store(conditions = {})
+      conditions[:store] || conditions[:stores] || default_cache_store
+    end
+
+    # Overwrite this in your controller to change the default store for a given controller
+    def default_cache_store
+      Merb::Cache.default_store_name
+    end
+
+    #ugly, please make me purdy'er
+    def _parameters_and_conditions(conditions)
+      parameters = {}
+
+      if self.class.respond_to? :action_argument_list
+        arguments, defaults = self.class.action_argument_list[action_name]
+        arguments.inject(parameters) do |parameters, arg|
+          if defaults.include?(arg.first)
+            parameters[arg.first] = self.params[arg.first] || arg.last
+          else
+            parameters[arg.first] = self.params[arg.first]
+          end
+          parameters
+        end
+      end
+
+      case conditions[:params]
+      when Symbol
+        parameters[conditions[:params]] = self.params[conditions[:params]]
+      when Array
+        conditions[:params].each do |param|
+          parameters[param] = self.params[param]
+        end
+      end
+
+      return parameters, conditions.except(:params, :store, :stores, :method, :uri)
+    end
+  end
+end

data/lib/merb-cache/stores/fundamental/abstract_store.rb

@@ -0,0 +1,101 @@
+class Merb::Cache::AbstractStore
+
+  def initialize(config = {}); end
+
+  # determines if the store is able to persist data identified by the key & parameters
+  # with the given conditions.
+  #
+  # @param [#to_s] key the key used to identify an entry
+  # @param [Hash] parameters optional parameters used to identify an entry
+  # @param [Hash] conditions optional conditions that place constraints or detail instructions for storing an entry
+  # @return [TrueClass] the ability of the store to write an entry based on the key, parameters, and conditions
+  # @raise [NotImplementedError] API method has not been implemented
+  def writable?(key, parameters = {}, conditions = {})
+    raise NotImplementedError
+  end
+
+  # gets the data from the store identified by the key & parameters.
+  # return nil if the entry does not exist.
+  #
+  # @param [#to_s] key the key used to identify an entry
+  # @param [Hash] parameters optional parameters used to identify an entry
+  # @return [Object, NilClass] the match entry, or nil if no entry exists matching the key and parameters
+  # @raise [NotImplementedError] API method has not been implemented
+  def read(key, parameters = {})
+    raise NotImplementedError
+  end
+
+  # persists the data so that it can be retrieved by the key & parameters.
+  # returns nil if it is unable to persist the data.
+  # returns true if successful.
+  #
+  # @param [#to_s] key the key used to identify an entry
+  # @param data the object to persist as an entry
+  # @param [Hash] parameters optional parameters used to identify an entry
+  # @param [Hash] conditions optional conditions that place constraints or detail instructions for storing an entry
+  # @return [TrueClass, NilClass] true if the entry was successfully written, otherwise nil
+  # @raise [NotImplementedError] API method has not been implemented
+  def write(key, data = nil, parameters = {}, conditions = {})
+    raise NotImplementedError
+  end
+
+  # @param [#to_s] key the key used to identify an entry
+  # @param data the object to persist as an entry
+  # @param [Hash] parameters optional parameters used to identify an entry
+  # @param [Hash] conditions optional conditions that place constraints or detail instructions for storing an entry
+  # @return [TrueClass, NilClass] true if the entry was successfully written, otherwise nil
+  # @raise [NotImplementedError] API method has not been implemented
+  def write_all(key, data = nil, parameters = {}, conditions = {})
+    write(key, data, parameters, conditions)
+  end
+
+  # tries to read the data from the store.  If that fails, it calls
+  # the block parameter and persists the result.
+  #
+  # @param [#to_s] key the key used to identify an entry
+  # @param [Hash] parameters optional parameters used to identify an entry
+  # @param [Hash] conditions optional conditions that place constraints or detail instructions for storing an entry
+  # @return [Object, NilClass] the match entry or the result of the block call, or nil if the entry is not successfully written
+  # @raise [NotImplementedError] API method has not been implemented
+  def fetch(key, parameters = {}, conditions = {}, &blk)
+    raise NotImplementedError
+  end
+
+  # returns true/false based on if data identified by the key & parameters
+  # is persisted in the store.
+  #
+  # @param [#to_s] key the key used to identify an entry
+  # @param [Hash] parameters optional parameters used to identify an entry
+  # @return [TrueClass] true if the key and parameters match an entry in the store, false otherwise
+  # @raise [NotImplementedError] API method has not been implemented
+  def exists?(key, parameters = {})
+    raise NotImplementedError
+  end
+
+  # deletes the entry for the key & parameter from the store.
+  #
+  # @param [#to_s] key the key used to identify an entry
+  # @param [Hash] parameters optional parameters used to identify an entry
+  # @raise [TrueClass] true if the an entry matching the key and parameters is successfully deleted, false otherwise
+  # @raise [NotImplementedError] API method has not been implemented
+  def delete(key, parameters = {})
+    raise NotImplementedError
+  end
+
+  # deletes all entries for the key & parameters for the store.
+  #
+  # @return [TrueClass] true if all entries in the store are erased, false otherwise
+  # @raise [NotImplementedError] API method has not been implemented
+  def delete_all
+    raise NotImplementedError
+  end
+
+  # dangerous version of delete_all.  Used by strategy stores, which may delete entries not associated with the strategy
+  # store making the call.
+  #
+  # @return [TrueClass] true if all entries in the store are erased, false otherwise
+  # @raise [NotImplementedError] API method has not been implemented
+  def delete_all!
+    delete_all
+  end
+end