cims-configurationserver/vendor/bundle/ruby/1.9.1/gems/rack-cache-1.2/doc/configuration.markdown

Configuration

Rack::Cache includes a configuration system that can be used to specify fairly sophisticated cache policy on a global or per-request basis.

Setting Cache Options

Cache options can be set when the Rack::Cache object is created, or by setting a rack-cache.<option> variable in Rack's Environment.

When the Rack::Cache object is instantiated:

use Rack::Cache,
  :verbose     => true,
  :metastore   => 'memcached://localhost:11211/',
  :entitystore => 'file:/var/cache/rack'

Using Rack's Environment:

env.merge!(
  'rack-cache.verbose' => true,
  'rack-cache.metastore' => 'memcached://localhost:11211/',
  'rack-cache.entitystore' => 'file:/var/cache/rack'
)

Cache Option Reference

Use the following options to customize Rack::Cache:

verbose

Boolean specifying whether verbose trace logging is enabled. This option is currently enabled (true) by default but is likely to be disabled (false) in a future release. All log output is written to the rack.errors stream, which is typically set to STDERR.

The trace, info, warn, and error methods can be used within the configuration context to write messages to the errors stream.

default_ttl

An integer specifying the number of seconds a cached object should be considered "fresh" when no explicit freshness information is provided in a response. Explicit Cache-Control or Expires response headers always override this value. The default_ttl option defaults to 0, meaning responses without explicit freshness information are considered immediately "stale" and will not be served from cache without validation.

metastore

A URI specifying the MetaStore implementation used to store request/response meta information. See the Rack::Cache Storage Documentation for detailed information on different storage implementations.

If no metastore is specified, the heap:/ store is assumed. This implementation has significant draw-backs so explicit configuration is recommended.

entitystore

A URI specifying the EntityStore implementation used to store response bodies. See the Rack::Cache Storage Documentation for detailed information on different storage implementations.

If no entitystore is specified, the heap:/ store is assumed. This implementation has significant draw-backs so explicit configuration is recommended.

private_headers

An array of request header names that cause the response to be treated with private cache control semantics. The default value is ['Authorization', 'Cookie']. If any of these headers are present in the request, the response is considered private and will not be cached unless the response is explicitly marked public (e.g., Cache-Control: public).

allow_reload

A boolean specifying whether reload requests sent by the client should be honored by the cache. When this option is enabled (rack-cache.allow_reload is true), requests that include a Cache-Control: no-cache header cause the cache to discard anything it has stored for the request and ask that the response be fully generated.

Most browsers include a Cache-Control: no-cache header when the user performs a "hard refresh" (e.g., holding Shift while clicking the "Refresh" button).

IMPORTANT: Enabling this option globally allows all clients to break your cache.

allow_revalidate

A boolean specifying whether revalidate requests sent by the client should be honored by the cache. When this option is enabled (rack-cache.allow_revalidate is true), requests that include a Cache-Control: max-age=0 header cause the cache to assume its copy of the response is stale, resulting in a conditional GET / validation request to be sent to the server.

Most browsers include a Cache-Control: max-age=0 header when the user performs a refresh (e.g., clicking the "Refresh" button).

IMPORTANT: Enabling this option globally allows all clients to break your cache.

cache_key

A custom cache key generator, which can be anything that responds to :call. By default, this is the Rack::Cache::Key class, but you can implement your own generator. A cache key generator gets passed a Rack::Request object and generates the appropriate cache key.

The Rack::Cache::Key class by default returns the fully qualified url of the request.

In addition to setting the generator to an object, you can just pass a block instead, which will act as the cache key generator:

set :cache_key do |request|
    request.fullpath.replace(/\//, '-')
end

For more options see the Rack::Request documentation