rack-cache 0.2.0

data/doc/storage.markdown

@@ -0,0 +1,162 @@
+Storage
+=======
+
+__Rack::Cache__ runs within each of your backend application processes and does not
+rely on a single intermediary process like most types of proxy cache
+implementations. Because of this, the storage subsystem has implications on not
+only where cache data is stored but whether the cache is properly distributed
+between multiple backend processes. It is highly recommended that you read and
+understand the following before choosing a storage implementation.
+
+Storage Areas
+-------------
+
+__Rack::Cache__ stores cache entries in two separate configurable storage
+areas: a _MetaStore_ and an _EntityStore_.
+
+The _MetaStore_ keeps high level information about each cache entry, including
+the request/response headers and other status information. When a request is
+received, the core caching logic uses this meta information to determine whether
+a fresh cache entry exists that can satisfy the request.
+
+The _EntityStore_ is where the actual response body content is stored. When a
+response is entered into the cache, a SHA1 digest of the response body content
+is calculated and used as a key. The entries stored in the MetaStore reference
+their response bodies using this SHA1 key.
+
+Separating request/response meta-data from response content has a few important
+advantages:
+
+  * Different storage types can be used for meta and entity storage. For
+    example, it may be desirable to use memcached to store meta information
+    while using the filesystem for entity storage.
+
+  * Cache entry meta-data may be retrieved quickly without also retrieving
+    response bodies. This avoids significant overhead when the cache misses
+    or only requires validation.
+
+  * Multiple different responses may include the same exact response body. In
+    these cases, the actual body content is stored once and referenced from
+    each of the meta store entries.
+
+You should consider how the meta and entity stores differ when choosing a storage
+implementation. The MetaStore does not require nearly as much memory as the
+EntityStore and is accessed much more frequently. The EntityStore can grow quite
+large and raw performance is less of a concern. Using a memory based storage
+implementation (`heap` or `memcached`) for the MetaStore is strongly advised,
+while a disk based storage implementation (`file`) is often satisfactory for
+the EntityStore and uses much less memory.
+
+Storage Configuration
+---------------------
+
+The MetaStore and EntityStore used for a particular request is determined by
+inspecting the `rack-cache.metastore` and `rack-cache.entitystore` Rack env
+variables. The value of these variables is a URI that identifies the storage
+type and location (URI formats are documented in the following section).
+
+The `heap:/` storage is assumed if either storage type is not explicitly
+provided. This storage type has significant drawbacks for most types of
+deployments so explicit configuration is advised.
+
+The default metastore and entitystore values can be specified when the
+__Rack::Cache__ object is added to the Rack middleware pipeline as follows:
+
+    use Rack::Cache do
+      set :metastore, 'file:/var/cache/rack/meta'
+      set :entitystore, 'file:/var/cache/rack/body'
+    end
+
+Alternatively, the `rack-cache.metastore` and `rack-cache.entitystore`
+variables may be set in the Rack environment by an upstream component.
+
+Storage Implementations
+-----------------------
+
+__Rack::Cache__ includes meta and entity storage implementations backed by local
+process memory ("heap storage"), the file system ("disk storage"), and
+memcached. This section includes information on configuring __Rack::Cache__ to
+use a specific storage implementation as well as pros and cons of each.
+
+### Heap Storage
+
+Uses local process memory to store cached entries.
+
+    set :metastore,   'heap:/'
+    set :entitystore, 'heap:/'
+
+The heap storage backend is simple, fast, and mostly useless. All cache
+information is stored in each backend application's local process memory (using
+a normal Hash, in fact), which means that data cached under one backend is
+invisible to all other backends. This leads to low cache hit rates and excessive
+memory use, the magnitude of which is a function of the number of backends in
+use. Further, the heap storage provides no mechanism for purging unused entries
+so memory use is guaranteed to exceed that available, given enough time and
+utilization.
+
+Use of heap storage is recommended only for testing purposes or for very
+simple/single-backend deployment scenarios where the number of resources served
+is small and well understood.
+
+### Disk Storage
+
+Stores cached entries on the filesystem.
+
+    set :metastore,   'file:/var/cache/rack/meta'
+    set :entitystore, 'file:/var/cache/rack/body'
+
+The URI may specify an absolute, relative, or home-rooted path:
+
+  * `file:/storage/path` - absolute path to storage directory.
+  * `file:storage/path` - relative path to storage directory, rooted at the
+    process's current working directory (`Dir.pwd`).
+  * `file:~user/storage/path` - path to storage directory, rooted at the
+    specified user's home directory.
+  * `file:~/storage/path` - path to storage directory, rooted at the current
+    user's home directory.
+
+File system storage is simple, requires no special daemons or libraries, has a
+tiny memory footprint, and allows multiple backends to share a single cache; it
+is one of the slower storage implementations, however. Its use is recommended in
+cases where memory is limited or in environments where more complex storage
+backends (i.e., memcached) are not available. In many cases, it may be
+acceptable (and even optimal) to use file system storage for the entitystore and
+a more performant storage implementation (i.e. memcached) for the metastore.
+
+__NOTE:__ When both the metastore and entitystore are configured to use file
+system storage, they should be set to different paths to prevent any chance of
+collision.
+
+### Memcached Storage
+
+Stores cached entries in a remote [memcached](http://www.danga.com/memcached/)
+instance.
+
+    set :metastore,   'memcached://localhost:11211/meta'
+    set :entitystore, 'memcached://localhost:11211/body'
+
+The URI must specify the host and port of a remote memcached daemon. The path
+portion is an optional (but recommended) namespace that is prepended to each
+cache key.
+
+The memcached storage backend requires [Evan Weaver's memcached client library][e].
+This is a [fast][f] client implementation built on the SWIG/[libmemcached][l] C
+library. The library may be installed from Gem as follows:
+
+    sudo gem install memcached --no-rdoc --no-ri
+
+Memcached storage is reasonably fast and allows multiple backends to share a
+single cache. It is also the only storage implementation that allows the cache
+to reside somewhere other than the local machine. The memcached daemon stores
+all data in local process memory so using it for the entitystore can result in
+heavy memory usage. It is by far the best option for the metastore in
+deployments with multiple backend application processes since it allows the
+cache to be properly distributed and provides fast access to the
+meta-information required to perform cache logic. Memcached is considerably more
+complex than the other storage implementations, requiring a separate daemon
+process and extra libraries. Still, its use is recommended in all cases where
+you can get away with it.
+
+[e]: http://blog.evanweaver.com/files/doc/fauna/memcached/files/README.html
+[f]: http://blog.evanweaver.com/articles/2008/01/21/b-the-fastest-u-can-b-memcached/
+[l]: http://tangent.org/552/libmemcached.html

data/lib/rack/cache.rb

@@ -0,0 +1,51 @@
+require 'fileutils'
+require 'time'
+require 'rack'
+
+module Rack #:nodoc:
+end
+
+# = HTTP Caching For Rack
+#
+# Rack::Cache is suitable as a quick, drop-in component to enable HTTP caching
+# for Rack-enabled applications that produce freshness (+Expires+, +Cache-Control+)
+# and/or validation (+Last-Modified+, +ETag+) information.
+#
+# * Standards-based (RFC 2616 compliance)
+# * Freshness/expiration based caching and validation
+# * Supports HTTP Vary
+# * Portable: 100% Ruby / works with any Rack-enabled framework
+# * VCL-like configuration language for advanced caching policies
+# * Disk, memcached, and heap memory storage backends
+#
+# === Usage
+#
+# Create with default options:
+#   require 'rack/cache'
+#   Rack::Cache.new(app, :verbose => true, :entitystore => 'file:cache')
+#
+# Within a rackup file (or with Rack::Builder):
+#   require 'rack/cache'
+#   use Rack::Cache do
+#     set :verbose, true
+#     set :metastore, 'memcached://localhost:11211/meta'
+#     set :entitystore, 'file:/var/cache/rack'
+#   end
+#   run app
+#
+module Rack::Cache
+  require 'rack/cache/request'
+  require 'rack/cache/response'
+  require 'rack/cache/context'
+  require 'rack/cache/storage'
+
+  # Create a new Rack::Cache middleware component that fetches resources from
+  # the specified backend application. The +options+ Hash can be used to
+  # specify default configuration values (see attributes defined in
+  # Rack::Cache::Options for possible key/values). When a block is given, it
+  # is executed within the context of the newly create Rack::Cache::Context
+  # object.
+  def self.new(backend, options={}, &b)
+    Context.new(backend, options, &b)
+  end
+end

data/lib/rack/cache/config.rb

@@ -0,0 +1,65 @@
+require 'set'
+
+module Rack::Cache
+  # Provides cache configuration methods. This module is included in the cache
+  # context object.
+
+  module Config
+    # Evaluate a block of configuration code within the scope of receiver.
+    def configure(&block)
+      instance_eval(&block) if block_given?
+    end
+
+    # Import the configuration file specified. This has the same basic semantics
+    # as Ruby's built-in +require+ statement but always evaluates the source
+    # file within the scope of the receiver. The file may exist anywhere on the
+    # $LOAD_PATH.
+    def import(file)
+      return false if imported_features.include?(file)
+      path = add_file_extension(file, 'rb')
+      if path = locate_file_on_load_path(path)
+        source = File.read(path)
+        imported_features.add(file)
+        instance_eval source, path, 1
+        true
+      else
+        raise LoadError, 'no such file to load -- %s' % [file]
+      end
+    end
+
+  private
+    # Load the default configuration and evaluate the block provided within
+    # the scope of the receiver.
+    def initialize_config(&block)
+      import 'rack/cache/config/default'
+      configure(&block)
+    end
+
+    # Set of files that have been imported.
+    def imported_features
+      @imported_features ||= Set.new
+    end
+
+    # Attempt to expand +file+ to a full path by possibly adding an .rb
+    # extension and traversing the $LOAD_PATH looking for matches.
+    def locate_file_on_load_path(file)
+      if file[0,1] == '/'
+        file if File.exist?(file)
+      else
+        $LOAD_PATH.
+          map { |base| File.join(base, file) }.
+          detect { |p| File.exist?(p) }
+      end
+    end
+
+    # Add an extension to the filename provided if the file doesn't
+    # already have extension.
+    def add_file_extension(file, extension='rb')
+      if file =~ /\.\w+$/
+        file
+      else
+        "#{file}.#{extension}"
+      end
+    end
+  end
+end

data/lib/rack/cache/config/busters.rb

@@ -0,0 +1,16 @@
+# Adds a very long max-age response header when the requested url
+# looks like it includes a cache busting timestamp. Cache busting
+# URLs look like this:
+#   http://HOST/PATH?DIGITS
+#
+# DIGITS is typically the number of seconds since some epoch but
+# this can theoretically be any set of digits. Example:
+#   http://example.com/css/foo.css?7894387283
+#
+on :fetch do
+  next if response.freshness_information?
+  if request.url =~ /\?\d+$/
+    trace 'adding huge max-age to response for cache busting URL'
+    response.ttl = 100000000000000
+  end
+end

data/lib/rack/cache/config/default.rb

@@ -0,0 +1,134 @@
+# Called at the beginning of request processing, after the complete
+# request has been fully received. Its purpose is to decide whether or
+# not to serve the request and how to do it.
+#
+# The request should not be modified.
+#
+# Possible transitions from receive:
+#
+#   * pass! - pass the request to the backend the response upstream,
+#     bypassing all caching features.
+#
+#   * lookup! - attempt to locate the entry in the cache. Control will
+#     pass to the +hit+, +miss+, or +fetch+ event based on the result of
+#     the cache lookup.
+#
+#   * error! - return the error code specified, abandoning the request.
+#
+on :receive do
+  pass! unless request.method? 'GET', 'HEAD'
+  pass! if request.header? 'Cookie', 'Authorization', 'Expect'
+  lookup!
+end
+
+# Called upon entering pass mode. The request is sent to the backend,
+# and the backend's response is sent to the client, but is not entered
+# into the cache. The event is triggered immediately after the response
+# is received from the backend but before the it has been sent upstream.
+#
+# Possible transitions from pass:
+#
+#   * finish! - deliver the response upstream.
+#
+#   * error! - return the error code specified, abandoning the request.
+#
+on :pass do
+  finish!
+end
+
+# Called after a cache lookup when no matching entry is found in the
+# cache. Its purpose is to decide whether or not to attempt to retrieve
+# the response from the backend and in what manner.
+#
+# Possible transitions from miss:
+#
+#   * fetch! - retrieve the requested document from the backend with
+#     caching features enabled.
+#
+#   * pass! - pass the request to the backend and the response upstream,
+#     bypassing all caching features.
+#
+#   * error! - return the error code specified and abandon request.
+#
+# The default configuration transfers control to the fetch event.
+on :miss do
+  fetch!
+end
+
+# Called after a cache lookup when the requested document is found in
+# the cache and is fresh.
+#
+# Possible transitions from hit:
+#
+#   * deliver! - transfer control to the deliver event, sending the cached
+#     response upstream.
+#
+#   * pass! - abandon the cache entry and transfer to pass mode. The
+#     original request is sent to the backend and the response sent
+#     upstream, bypassing all caching features.
+#
+#   * error! - return the error code specified and abandon request.
+#
+on :hit do
+  deliver!
+end
+
+# Called after a document is successfully retrieved from the backend
+# application or after a cache entry is validated with the backend.
+# During validation, the original request is used as a template for a
+# conditional GET request with the backend. The +original_response+
+# object contains the response as received from the backend and +entry+
+# is set to the cached response that triggered validation.
+#
+# Possible transitions from fetch:
+#
+#   * store! - store the fetched response in the cache or, when
+#     validating, update the cached response with validated results.
+#
+#   * deliver! - deliver the response upstream without entering it
+#     into the cache.
+#
+#   * error! return the error code specified and abandon request.
+#
+on :fetch do
+  store! if response.cacheable?
+  deliver!
+end
+
+# Called immediately before an entry is written to the underlying
+# cache. The +entry+ object may be modified.
+#
+# Possible transitions from store:
+#
+#   * persist! - commit the object to cache and transfer control to
+#     the deliver event.
+#
+#   * deliver! - transfer control to the deliver event without committing
+#     the object to cache.
+#
+#   * error! - return the error code specified and abandon request.
+#
+on :store do
+  entry.ttl = default_ttl if entry.ttl.nil?
+  trace 'store backend response in cache (ttl: %ds)', entry.ttl
+  persist!
+end
+
+# Called immediately before +response+ is delivered upstream. +response+
+# may be modified at this point but the changes will not effect the
+# cache since the entry has already been persisted.
+#
+#   * finish! - complete processing and send the response upstream
+#
+#   * error! - return the error code specified and abandon request.
+#
+on :deliver do
+  finish!
+end
+
+# Called when an error! transition is triggered. The +response+ has the
+# error code, headers, and body that will be delivered to upstream and
+# may be modified if needed.
+on :error do
+  finish!
+end

data/lib/rack/cache/config/no-cache.rb

@@ -0,0 +1,13 @@
+# The default configuration ignores the `Cache-Control: no-cache` directive on
+# requests. Per RFC 2616, the presence of the no-cache directive should cause
+# intermediaries to process requests as if no cached version were available.
+# However, this directive is most often targetted at shared proxy caches, not
+# gateway caches, and so we've chosen to break with the spec in our default
+# configuration.
+#
+# Import 'rack/cache/config/no-cache' to enable standards-based
+# processing.
+
+on :receive do
+  pass! if request.header['Cache-Control'] =~ /no-cache/
+end