Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 128 lines (88 sloc) 4.833 kB
6cdcd42 @rtomayko Revise configuration doc for event/language removal
authored
1 Configuration
2 =============
5b59ea2 @rtomayko documentation system + documentation
authored
3
d10192e @rtomayko finish up config machinery doc (for now)
authored
4 __Rack::Cache__ includes a configuration system that can be used to specify
5 fairly sophisticated cache policy on a global or per-request basis.
5b59ea2 @rtomayko documentation system + documentation
authored
6
d10192e @rtomayko finish up config machinery doc (for now)
authored
7 <a id='setopt'></a>
5b59ea2 @rtomayko documentation system + documentation
authored
8
d10192e @rtomayko finish up config machinery doc (for now)
authored
9 Setting Cache Options
10 ---------------------
5b59ea2 @rtomayko documentation system + documentation
authored
11
6cdcd42 @rtomayko Revise configuration doc for event/language removal
authored
12 Cache options can be set when the __Rack::Cache__ object is created,
13 or by setting a `rack-cache.<option>` variable in __Rack__'s
14 __Environment__.
5b59ea2 @rtomayko documentation system + documentation
authored
15
d10192e @rtomayko finish up config machinery doc (for now)
authored
16 When the __Rack::Cache__ object is instantiated:
5b59ea2 @rtomayko documentation system + documentation
authored
17
d10192e @rtomayko finish up config machinery doc (for now)
authored
18 use Rack::Cache,
d268152 @rtomayko Disable client reload and revalidate requests by default
authored
19 :verbose => true,
20 :metastore => 'memcached://localhost:11211/',
d10192e @rtomayko finish up config machinery doc (for now)
authored
21 :entitystore => 'file:/var/cache/rack'
5b59ea2 @rtomayko documentation system + documentation
authored
22
d10192e @rtomayko finish up config machinery doc (for now)
authored
23 Using __Rack__'s __Environment__:
5b59ea2 @rtomayko documentation system + documentation
authored
24
d10192e @rtomayko finish up config machinery doc (for now)
authored
25 env.merge!(
26 'rack-cache.verbose' => true,
27 'rack-cache.metastore' => 'memcached://localhost:11211/',
28 'rack-cache.entitystore' => 'file:/var/cache/rack'
29 )
30
31 <a id='options'></a>
32
33 Cache Option Reference
34 ----------------------
5b59ea2 @rtomayko documentation system + documentation
authored
35
d10192e @rtomayko finish up config machinery doc (for now)
authored
36 Use the following options to customize __Rack::Cache__:
37
38 ### `verbose`
39
40 Boolean specifying whether verbose trace logging is enabled. This option is
41 currently enabled (`true`) by default but is likely to be disabled (`false`) in
42 a future release. All log output is written to the `rack.errors` stream, which
43 is typically set to `STDERR`.
44
45 The `trace`, `info`, `warn`, and `error` methods can be used within the
46 configuration context to write messages to the errors stream.
47
48 ### `default_ttl`
49
50 An integer specifying the number of seconds a cached object should be considered
51 "fresh" when no explicit freshness information is provided in a response.
52 Explicit `Cache-Control` or `Expires` response headers always override this
53 value. The `default_ttl` option defaults to `0`, meaning responses without
54 explicit freshness information are considered immediately "stale" and will not
55 be served from cache without validation.
56
57 ### `metastore`
58
59 A URI specifying the __MetaStore__ implementation used to store request/response
5b59ea2 @rtomayko documentation system + documentation
authored
60 meta information. See the [Rack::Cache Storage Documentation](storage.html)
61 for detailed information on different storage implementations.
62
d10192e @rtomayko finish up config machinery doc (for now)
authored
63 If no metastore is specified, the `heap:/` store is assumed. This implementation
5b59ea2 @rtomayko documentation system + documentation
authored
64 has significant draw-backs so explicit configuration is recommended.
65
d10192e @rtomayko finish up config machinery doc (for now)
authored
66 ### `entitystore`
5b59ea2 @rtomayko documentation system + documentation
authored
67
d10192e @rtomayko finish up config machinery doc (for now)
authored
68 A URI specifying the __EntityStore__ implementation used to store
5b59ea2 @rtomayko documentation system + documentation
authored
69 response bodies. See the [Rack::Cache Storage Documentation](storage.html)
70 for detailed information on different storage implementations.
71
d10192e @rtomayko finish up config machinery doc (for now)
authored
72 If no entitystore is specified, the `heap:/` store is assumed. This
5b59ea2 @rtomayko documentation system + documentation
authored
73 implementation has significant draw-backs so explicit configuration is
74 recommended.
75
dcc66ab @rtomayko proper support for private/public Cache-Control directives
authored
76 ### `private_headers`
77
78 An array of request header names that cause the response to be treated with
79 private cache control semantics. The default value is `['Authorization', 'Cookie']`.
80 If any of these headers are present in the request, the response is considered
81 private and will not be cached _unless_ the response is explicitly marked public
82 (e.g., `Cache-Control: public`).
83
d268152 @rtomayko Disable client reload and revalidate requests by default
authored
84 ### `allow_reload`
85
86 A boolean specifying whether reload requests sent by the client should be
87 honored by the cache. When this option is enabled (`rack-cache.allow_reload`
88 is `true`), requests that include a `Cache-Control: no-cache` header cause
89 the cache to discard anything it has stored for the request and ask that the
90 response be fully generated.
91
92 Most browsers include a `Cache-Control: no-cache` header when the user performs
93 a "hard refresh" (e.g., holding `Shift` while clicking the "Refresh" button).
94
95 *IMPORTANT: Enabling this option globally allows all clients to break your cache.*
96
97 ### `allow_revalidate`
98
99 A boolean specifying whether revalidate requests sent by the client should be
100 honored by the cache. When this option is enabled (`rack-cache.allow_revalidate`
101 is `true`), requests that include a `Cache-Control: max-age=0` header cause the
102 cache to assume its copy of the response is stale, resulting in a conditional
103 GET / validation request to be sent to the server.
104
105 Most browsers include a `Cache-Control: max-age=0` header when the user performs
106 a refresh (e.g., clicking the "Refresh" button).
107
108 *IMPORTANT: Enabling this option globally allows all clients to break your cache.*
109
6cdcd42 @rtomayko Revise configuration doc for event/language removal
authored
110 ### `cache_key`
d10192e @rtomayko finish up config machinery doc (for now)
authored
111
61da6ec @hexgnu Adding documentation for cache_key and adding Gemfile for development
hexgnu authored
112 A custom cache key generator, which can be anything that responds to :call.
113 By default, this is the `Rack::Cache::Key` class, but you can implement your own
114 generator. A cache key generator gets passed a `Rack::Request` object and generates
115 the appropriate cache key.
116
117 The `Rack::Cache::Key` class by default returns the fully qualified url of the request.
118
119 In addition to setting the generator to an object, you can just pass a block instead,
120 which will act as the cache key generator:
121
122 set :cache_key do |request|
123 request.fullpath.replace(/\//, '-')
124 end
125
126 For more options see the [Rack::Request documentation](http://rack.rubyforge.org/doc/classes/Rack/Request.html)
127
Something went wrong with that request. Please try again.