1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
Configuration
=============
__Rack::Cache__ includes a configuration system that can be used to specify
fairly sophisticated cache policy on a global or per-request basis.
<a id='setopt'></a>
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'
)
<a id='options'></a>
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](storage.html)
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](storage.html)
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.
If you're using `Rack::Cache::Key` and would like to omit parts of the query string
from the key (e.g. tracking with UTM parameters), you can set a `Proc` on
`Rack::Cache::Key` like so:
Rack::Cache::Key.query_string_ignore = proc { |k, v| k =~ /^(trk|utm)_/ }
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](https://www.rubydoc.info/gems/rack/Rack/Request).
### `use_native_ttl`
Passes on the expiration timestamp to cache stores that support it, like
Memcache and Redis. This may be necessary with some stores to keep them from
filling up, e.g. if using a Redis backend and the `volatile-ttl` expiration
policy.
If using `memcached`, it will speed up misses slightly as the middleware won't
need to fetch metadata and check timestamps.
### `fault_tolerant`
Boolean specifying whether fault tolerant caching is enabled. When this option
is enabled (`rack-cache.fault_tolerant`is `true`), stale cached results can be
returned if the downstream service is unavailable.
|
