` variable in __Rack__'s
14 | __Environment__.
15 |
16 | When the __Rack::Cache__ object is instantiated:
17 |
18 | use Rack::Cache,
19 | :verbose => true,
20 | :metastore => 'memcached://localhost:11211/',
21 | :entitystore => 'file:/var/cache/rack'
22 |
23 | Using __Rack__'s __Environment__:
24 |
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 |
5 | NOTE: This is a work in progress. Please send questions, comments, or
6 | suggestions to r@tomayko.com .
7 |
8 |
9 | General
10 | -------
11 |
12 |
13 | #
14 |
15 | ### Q: Can I use Rack::Cache with Rails?
16 |
17 | Rack::Cache can be used with Rails 2.3 or above. Documentation and a
18 | sample application is forthcoming; in the mean time, see
19 | [this example of using Rack::Cache with Rails 2.3](http://snippets.aktagon.com/snippets/302-How-to-setup-and-use-Rack-Cache-with-Rails-2-3-0-RC-1).
20 |
21 | #
22 |
23 | ### Q: Why Rack::Cache? Why not Squid, Varnish, Perlbol, etc.?
24 |
25 | __Rack::Cache__ is often easier to setup as part of your existing Ruby
26 | application than a separate caching system. __Rack::Cache__ runs entirely inside
27 | your backend application processes - no separate / external process is required.
28 | This lets __Rack::Cache__ scale down to development environments and simple
29 | deployments very easily while not sacrificing the benefits of a standards-based
30 | approach to caching.
31 |
32 |
33 | #
34 |
35 | ### Q: Why Rack::Cache? Why not use Rails/Merb/FrameworkX's caching system?
36 |
37 | __Rack::Cache__ takes a standards-based approach to caching that provides some
38 | benefits over framework-integrated systems. It uses standard HTTP headers
39 | (`expires`, `cache-control`, `etag`, `last-modified`, etc.) to determine
40 | what/when to cache. Designing applications to support these standard HTTP
41 | mechanisms gives the benefit of being able to switch to a different HTTP
42 | cache implementation in the future.
43 |
44 | In addition, using a standards-based approach to caching creates a clear
45 | separation between application and caching logic. The application need only
46 | specify a basic set of information about the response and all decisions
47 | regarding how and when to cache is moved into the caching layer.
48 |
49 |
50 | #
51 |
52 | ### Q: Will Rack::Cache make my app scale?
53 |
54 | No. Your design is the only thing that can make your app scale.
55 |
56 | Also, __Rack::Cache__ is not overly optimized for performance. The main goal of
57 | the project is to provide a portable, easy-to-configure, and standards-based
58 | caching solution for small to medium sized deployments. More sophisticated /
59 | performant caching systems (e.g., [Varnish][v], [Squid][s],
60 | [httpd/mod-cache][h]) may be more appropriate for large deployments with
61 | crazy-land throughput requirements.
62 |
63 | [v]: http://varnish.projects.linpro.no/
64 | [s]: http://www.squid-cache.org/
65 | [h]: http://httpd.apache.org/docs/2.0/mod/mod_cache.html
66 |
67 |
68 | Features
69 | --------
70 |
71 |
72 | #
73 |
74 | ### Q: Does Rack::Cache support validation?
75 |
76 | Yes. Both freshness and validation-based caching is supported. A response
77 | will be cached if it has a freshness lifetime (e.g., `expires` or
78 | `cache-control: max-age=N` headers) and/or includes a validator (e.g.,
79 | `last-modified` or `etag` headers). When the cache hits and the response is
80 | fresh, it's delivered immediately without talking to the backend application;
81 | when the cache is stale, the cached response is validated using a conditional
82 | GET request.
83 |
84 |
85 | #
86 |
87 | ### Q: Does Rack::Cache support fragment caching?
88 |
89 | Not really. __Rack::Cache__ deals with entire responses and doesn't know
90 | anything about how your application constructs them.
91 |
92 | However, something like [ESI](http://www.w3.org/TR/esi-lang) may be implemented
93 | in the future (likely as a separate Rack middleware component that could be
94 | situated upstream from Rack::Cache), which would allow applications to compose
95 | responses based on several "fragment resources". Each fragment would have its
96 | own cache policy.
97 |
98 |
99 | #
100 |
101 | ### Q: How do I manually purge or expire a cached entry?
102 |
103 | Although planned, there is currently no mechanism for manually purging
104 | an entry stored in the cache.
105 |
106 | Note that using an `expires` or `cache-control: max-age=N` header and relying on
107 | manual purge to invalidate cached entry can often be implemented more simply
108 | using efficient validation based caching (`last-modified`, `etag`). Many web
109 | frameworks are based entirely on manual purge and do not support validation at
110 | the cache level.
111 |
112 |
113 | #
114 |
115 | ### Q: How do I bypass rack-cache on a per-request basis?
116 |
117 | Set the `rack-cache.force-pass` variable in the rack environment to `true`.
118 |
119 |
120 | #
121 |
122 | ### Q: What does "Efficient Validation" mean?
123 |
124 | It means that your application performs only the processing necessary to
125 | determine if a response is valid before sending a `304 Not Modified` in response
126 | to a conditional GET request. Many applications that perform validation do so
127 | only after the entire response has been generated, which provides bandwidth
128 | savings but results in no CPU/IO savings. Implementing validation efficiently
129 | can increase backend application throughput significantly when fronted by a
130 | validating caching system (like __Rack::Cache__).
131 |
132 | [Here's an example Rack application](http://gist.github.com/9395) that performs
133 | efficient validation.
134 |
135 |
136 | #
137 |
138 | ### Q: Did you just make that up?
139 |
140 | Yes.
141 |
142 |
143 | #
144 |
145 | ### Q: Can I do HTTPS with Rack::Cache?
146 |
147 | Sure. HTTPS is typically managed by a front-end web server so this isn't really
148 | relevant to Rack::Cache.
149 |
--------------------------------------------------------------------------------
/doc/index.markdown:
--------------------------------------------------------------------------------
1 | __Rack::Cache__ is suitable as a quick drop-in component to enable HTTP caching
2 | for [Rack][]-based applications that produce freshness (`expires`,
3 | `cache-control`) and/or validation (`last-modified`, `etag`) information.
4 |
5 | * Standards-based (see [RFC 2616][rfc] / [Section 13][s13]).
6 | * Freshness/expiration based caching
7 | * Validation
8 | * `vary` support
9 | * Portable: 100% Ruby / works with any [Rack][]-enabled framework.
10 | * Disk, memcached, and heap memory [storage backends][storage].
11 |
12 | News
13 | ----
14 |
15 | * Rack::Cache 1.0 was released on December 24, 2010. See the
16 | [`CHANGES`](http://github.com/rtomayko/rack-cache/blob/1.0/CHANGES) file
17 | for details.
18 | * [How to use Rack::Cache with Rails 2.3](http://snippets.aktagon.com/snippets/302-How-to-setup-and-use-Rack-Cache-with-Rails-2-3-0-RC-1) - it's really easy.
19 | * [RailsLab's Advanced HTTP Caching Screencast](https://youtu.be/2UvpMhzkktw)
20 | is a really great review of HTTP caching concepts and shows how to
21 | use Rack::Cache with Rails.
22 |
23 | Installation
24 | ------------
25 |
26 | $ sudo gem install rack-cache
27 |
28 | Or, from a local working copy:
29 |
30 | $ git clone https://github.com/rack/rack-cache.git
31 | $ rake package && sudo rake install
32 |
33 | Basic Usage
34 | -----------
35 |
36 | __Rack::Cache__ is implemented as a piece of [Rack][] middleware and can be used
37 | with any __Rack__-based application. If your application includes a rackup
38 | (`.ru`) file or uses __Rack::Builder__ to construct the application pipeline,
39 | simply `require` and `use` as follows:
40 |
41 | require 'rack/cache'
42 |
43 | use Rack::Cache,
44 | :verbose => true,
45 | :metastore => 'file:/var/cache/rack/meta',
46 | :entitystore => 'file:/var/cache/rack/body'
47 |
48 | run app
49 |
50 | Assuming you've designed your backend application to take advantage of HTTP's
51 | caching features, no further code or configuration is required for basic
52 | caching.
53 |
54 | More
55 | ----
56 |
57 | * [Configuration Options][config] - how to set cache options.
58 |
59 | * [Cache Storage Documentation][storage] - detailed information on the various
60 | storage implementations available in __Rack::Cache__ and how to choose the one
61 | that's best for your application.
62 |
63 | * [Things Caches Do][things] - an illustrated guide to how HTTP gateway
64 | caches work with pointers to other useful resources on HTTP caching.
65 |
66 | * [GitHub Repository](http://github.com/rack/rack-cache/) - get your
67 | fork on.
68 |
69 | * [Mailing List](http://groups.google.com/group/rack-cache) - for hackers
70 | and users (`rack-cache@groups.google.com`).
71 |
72 | * [FAQ](./faq) - Frequently Asked Questions about __Rack::Cache__.
73 |
74 | * [RDoc API Documentation](./api/) - Mostly worthless if you just want to use
75 | __Rack::Cache__ in your application but mildly insightful if you'd like to
76 | get a feel for how the system has been put together; I recommend
77 | [reading the source](http://github.com/rack/rack-cache/tree/main/lib/rack/cache).
78 |
79 |
80 | See Also
81 | --------
82 |
83 | The overall design of __Rack::Cache__ is based largely on the work of the
84 | internet standards community. The following resources provide a good starting
85 | point for exploring the basic concepts of HTTP caching:
86 |
87 | * Mark Nottingham's [Caching Tutorial](http://www.mnot.net/cache_docs/),
88 | especially the short section on
89 | [How Web Caches Work](http://www.mnot.net/cache_docs/#WORK)
90 |
91 | * Joe Gregorio's [Doing HTTP Caching Right](https://www.xml.com/pub/a/2006/02/01/doing-http-caching-right-introducing-httplib2.html)
92 |
93 | * [RFC 2616](http://www.ietf.org/rfc/rfc2616.txt), especially
94 | [Section 13, "Caching in HTTP"](http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html)
95 |
96 | __Rack::Cache__ takes (_liberally_) various concepts from
97 | [Varnish](http://varnish.projects.linpro.no/) and
98 | [Django's cache framework](http://docs.djangoproject.com/en/dev/topics/cache/).
99 |
100 | License
101 | -------
102 |
103 | __Rack::Cache__ is Copyright © 2008
104 | by [Ryan Tomayko](http://tomayko.com/about)
105 | and is provided under [the MIT license](./license)
106 |
107 | [config]: ./configuration "Rack::Cache Configuration Language Documentation"
108 | [storage]: ./storage "Rack::Cache Storage Documentation"
109 | [things]: http://tomayko.com/writings/things-caches-do
110 |
111 | [rfc]: http://tools.ietf.org/html/rfc2616
112 | "RFC 2616 - Hypertext Transfer Protocol -- HTTP/1.1 [ietf.org]"
113 |
114 | [s13]: http://tools.ietf.org/html/rfc2616#section-13
115 | "RFC 2616 / Section 13 Caching in HTTP"
116 |
117 | [rack]: https://github.com/rack/rack
118 | "Rack: a Ruby Webserver Interface"
119 |
120 | [vcl]: http://tomayko.com/man/vcl
121 | "VCL(7) -- Varnish Configuration Language Manual Page"
122 |
--------------------------------------------------------------------------------
/doc/layout.html.erb:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Rack::Cache
6 |
10 |
20 |
<%= content %>
21 |
30 |
8 | Permission is hereby granted, free of charge, to any person obtaining a copy
9 | of this software and associated documentation files (the "Software"), to
10 | deal in the Software without restriction, including without limitation the
11 | rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
12 | sell copies of the Software, and to permit persons to whom the Software is
13 | furnished to do so, subject to the following conditions:
14 |
15 | The above copyright notice and this permission notice shall be included in
16 | all copies or substantial portions of the Software.
17 |
18 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
21 | THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
22 | IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
23 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
24 |
25 |
--------------------------------------------------------------------------------
/doc/rack-cache.css:
--------------------------------------------------------------------------------
1 | /* rack-cache.css
2 | *---------------------------------------------------------------------------
3 | * Copyright (C) 2005-08 Ryan Tomayko
4 | */
5 |
6 |
7 | /* 18px base font size / 25px baseline */
8 | body {
9 | font-size:112.5%; /* 18px (probably) */
10 | line-height:1.3888; /* 25px */
11 | letter-spacing:-0.02em;
12 | margin:0 10px;
13 | font-family: 'lucida sans unicode', 'lucida grande',
14 | helvetica, 'bitstream vera sans', sans-serif;
15 | color:#556;
16 | background-color:#fff;
17 | }
18 |
19 | #container {
20 | max-width:45em;
21 | margin:0 auto;
22 | }
23 |
24 | h1, h2, h3 {
25 | font-family:georgia, 'bitstream vera sans serif', 'lucida grande',
26 | helvetica, verdana, sans-serif;
27 | font-weight:normal;
28 | letter-spacing:-0.05em;
29 | color:#000;
30 | }
31 | i, em {
32 | font-style:italic;
33 | }
34 | b, strong {
35 | font-weight:normal;
36 | color:#000;
37 | }
38 | blockquote {
39 | color:#555;
40 | }
41 | blockquote em {
42 | color:#333;
43 | font-style:italic;
44 | }
45 | blockquote strong {
46 | color:#333;
47 | font-weight: normal;
48 | }
49 | dt {
50 | font-weight:bold;
51 | color:#000;
52 | }
53 | tt, pre, code, samp, kbd {
54 | font-family: consolas, 'lucida console', 'bitstream vera sans mono',
55 | 'courier new', monospace;
56 | color: #000;
57 | }
58 | pre {
59 | color:#333;
60 | background-color:#f9f9f9;
61 | }
62 | code {
63 | color:#007A00;
64 | }
65 | pre code {
66 | color:#333;
67 | }
68 | pre.license {
69 | border:0;
70 | background:#fff;
71 | padding:0;
72 | font-size:1.1em;
73 | }
74 | a, a:link {
75 | color:#023;
76 | background:#eef;
77 | }
78 | a:visited {
79 | color:#345;
80 | background:#fff;
81 | }
82 | a:hover {
83 | background:#ccf;
84 | color:#000;
85 | text-decoration:none;
86 | }
87 |
88 |
89 | /* TYPOGRAPHY */
90 |
91 | p, ul, ol, dl, pre, blockquote, table, form {
92 | margin:1em 0;
93 | }
94 | dl {
95 | margin-left:2em;
96 | }
97 | hr {
98 | color:#eee;
99 | background-color:#ccc;
100 | border:0;
101 | height:1px;
102 | margin:1.5em 0;
103 | }
104 | blockquote {
105 | font-size:0.83333em; /* 15px */
106 | line-height:1.66666; /* 25px */
107 | margin:1.2em 3em;
108 | padding:0;
109 | }
110 | tt, pre, code, samp, kbd {
111 | font-size: 16px;
112 | line-height:1.1;
113 | }
114 | pre {
115 | margin:1.5em 0;
116 | padding:6px 4px 4px 6px;
117 | border:1px solid #eee;
118 | border-left-width:20px;
119 | overflow:auto;
120 | }
121 | h1 {
122 | font-size:2.3333em; /* 42px */
123 | line-height:1.1904; /* 50px */
124 | margin:0.5952em 0; /* 25px */
125 | }
126 | h2 {
127 | font-size:1.66666667em; /* 30px */
128 | line-height:1.2; /* 36px */
129 | margin:1em 0;
130 | }
131 | h3 {
132 | font-size:1.33333333em; /* 22px */
133 | line-height:1.13636363; /* 25px */
134 | margin:1em 0;
135 | }
136 | h3 code{
137 | font-size:0.95em;
138 | color:#000;
139 | }
140 | h4 {
141 | font-size:1em;
142 | font-weight:bold;
143 | line-height:1.5;
144 | margin:1em 0;
145 | }
146 | p small {
147 | font-size:0.8333; /* 15px */
148 | line-height:1.2;
149 | }
150 |
151 | /* Tables
152 | --------------------------------------------------------------------------- */
153 |
154 | table {
155 | width:100%;
156 | border-style:none;
157 | border-color:#ddd;
158 | padding:0;
159 | }
160 |
161 | th, td {
162 | padding: 4px 10px 4px 5px;
163 | border-style:solid;
164 | border-color:#fff;
165 | }
166 |
167 | th {
168 | font-weight: bold;
169 | background: #eef;
170 | }
171 |
172 | td {
173 | background: #f9f9f9;
174 | }
175 |
176 | tfoot {
177 | font-style: italic;
178 | }
179 |
180 | caption {
181 | background: #eee;
182 | }
183 |
184 | /* Header / Titling
185 | --------------------------------------------------------------------------- */
186 |
187 | #header {
188 | text-align:left;
189 | margin:1.5em auto 2em;
190 | float:left;
191 | width:100%;
192 | padding-bottom:1.5em;
193 | border-bottom:1px solid #777;
194 | }
195 | #header h1 {
196 | font-family: 'lucida sans unicode', 'lucida grande',
197 | helvetica, 'bitstream vera sans', sans-serif;
198 | font-size:5em;
199 | font-weight:bold;
200 | line-height:1;
201 | margin:0;
202 | float:left;
203 | color:#000;
204 | letter-spacing:-0.08em;
205 | }
206 | #header h1 a, #header h1 a:link, #header h1 a:visited, #header h1 a:hover {
207 | color:#000;
208 | text-decoration:none;
209 | background:transparent;
210 | }
211 | #header p {
212 | margin: 0;
213 | line-height:1.8;
214 | color: #777;
215 | text-transform:capitalize;
216 | font-variant:small-caps;
217 | float:right;
218 | }
219 | #header a, #header a:link, #header a:visited {
220 | color:#445;
221 | background:#fff;
222 | }
223 | #header a:hover {
224 | background:#ccf;
225 | color:#000;
226 | text-decoration:none;
227 | }
228 | #content {
229 | clear:both;
230 | }
231 |
232 | /* FOOTER */
233 |
234 | #footer {
235 | clear:both;
236 | color:#555;
237 | font-size:0.88888888em;
238 | line-height:1.5625;
239 | border-top:1px solid #ddd;
240 | padding:19px 0 0 0;
241 | margin:40px 0 20px 0;
242 | text-align:center;
243 | }
244 | #footer p {
245 | margin:0;
246 | }
247 | #footer form {
248 | float:right;
249 | }
250 | #footer input{
251 | font-size:10px;
252 | }
253 |
254 | /* MISC HELPER STYLES */
255 |
256 | ul.clean, ol.clean {
257 | list-style-type: none;
258 | padding-left: 0;
259 | }
260 | .caps {
261 | font-variant:small-caps;
262 | }
263 | .clear {
264 | clear:both;
265 | }
266 | .left{
267 | float:left;
268 | }
269 | .right{
270 | float:right;
271 | }
272 | .center{
273 | text-align:center;
274 | }
275 | .intro {
276 | font-size:0.833333em; /* 15px */
277 | line-height:1.666667; /* 25px */
278 | border:1px solid #ccc;
279 | padding:0.5em;
280 | font-style:italic;
281 | color:#555;
282 | }
283 | a.hash,
284 | a.hash:link,
285 | a.hash:visited {
286 | display:block;
287 | float:right;
288 | background:#fff;
289 | font-size:0.8em;
290 | text-decoration:none;
291 | line-height:2;
292 | color:#999;
293 | }
294 | a.hash:hover {
295 | color:MediumOrchid;
296 | }
297 |
298 | /* PRINT */
299 |
300 | @media print {
301 | html, body, #container {
302 | margin:0;
303 | }
304 | #container {
305 | width:100%;
306 | max-width:100%;
307 | }
308 | #header {
309 | margin-top:0;
310 | }
311 | #header p {
312 | display:none;
313 | }
314 | #footer {
315 | display:none;
316 | }
317 | a, a:link, a:visited {
318 | color:#000;
319 | background:#fff;
320 | text-decoration:none;
321 | }
322 | pre.license {
323 | font-size:0.95em;
324 | }
325 | @page {
326 | size:8.5in 11in;
327 | }
328 | }
329 |
330 | /* PRETTIFICATION OF SOURCE CODE */
331 |
332 | .str { color: #181; font-style:italic; }
333 | .kwd { color: #369; }
334 | .com { color: #666; }
335 | .typ { color: #c40; }
336 | .lit { color: #900; }
337 | .pun { color: #000; font-weight: bold; }
338 | .pln { color: #333; }
339 | .tag { color: #369; font-weight: bold; }
340 | .atn { color: #939; font-weight: bold }
341 | .atv { color: #181; }
342 | .dec { color: #606; }
343 |
344 | @media print {
345 | .str { color: #060; }
346 | .kwd { color: #006; font-weight: bold; }
347 | .com { color: #600; font-style: italic; }
348 | .typ { color: #404; font-weight: bold; }
349 | .lit { color: #044; }
350 | .pun { color: #440; }
351 | .pln { color: #000; }
352 | .tag { color: #006; font-weight: bold; }
353 | .atn { color: #404; }
354 | .atv { color: #060; }
355 | }
356 |
357 | /* FUCKING IE */
358 |
359 | * html body{width:40em}
360 | * html div.index{width:34.5em}
361 |
362 | /* vim: set ft=css ts=4 sw=4 noexpandtab: */
363 |
--------------------------------------------------------------------------------
/doc/server.ru:
--------------------------------------------------------------------------------
1 | # Rackup config that serves the contents of Rack::Cache's
2 | # doc directory. The documentation is rebuilt on each request.
3 |
4 | # Rewrites URLs like conventional web server configs.
5 | class Rewriter < Struct.new(:app)
6 | def call(env)
7 | if env['PATH_INFO'] =~ /\/$/
8 | env['PATH_INFO'] += 'index.html'
9 | elsif env['PATH_INFO'] !~ /\.\w+$/
10 | env['PATH_INFO'] += '.html'
11 | end
12 | app.call(env)
13 | end
14 | end
15 |
16 | # Rebuilds documentation on each request.
17 | class DocBuilder < Struct.new(:app)
18 | def call(env)
19 | if env['PATH_INFO'] !~ /\.(css|js|gif|jpg|png|ico)$/
20 | env['rack.errors'] << "*** rebuilding documentation (rake -s doc)\n"
21 | system "rake -s doc"
22 | end
23 | app.call(env)
24 | end
25 | end
26 |
27 | use Rack::CommonLogger
28 | use DocBuilder
29 | use Rewriter
30 | use Rack::Static, :root => File.dirname(__FILE__), :urls => ["/"]
31 |
32 | run(lambda{|env| [404,{},'Not Found ']})
33 |
34 | # vim: ft=ruby
35 |
--------------------------------------------------------------------------------
/doc/storage.markdown:
--------------------------------------------------------------------------------
1 | Storage
2 | =======
3 |
4 | __Rack::Cache__ runs within each of your backend application processes and does not
5 | rely on a single intermediary process like most types of proxy cache
6 | implementations. Because of this, the storage subsystem has implications on not
7 | only where cache data is stored but whether the cache is properly distributed
8 | between multiple backend processes. It is highly recommended that you read and
9 | understand the following before choosing a storage implementation.
10 |
11 | Storage Areas
12 | -------------
13 |
14 | __Rack::Cache__ stores cache entries in two separate configurable storage
15 | areas: a _MetaStore_ and an _EntityStore_.
16 |
17 | The _MetaStore_ keeps high level information about each cache entry, including
18 | the request/response headers and other status information. When a request is
19 | received, the core caching logic uses this meta information to determine whether
20 | a fresh cache entry exists that can satisfy the request.
21 |
22 | The _EntityStore_ is where the actual response body content is stored. When a
23 | response is entered into the cache, a SHA1 digest of the response body content
24 | is calculated and used as a key. The entries stored in the MetaStore reference
25 | their response bodies using this SHA1 key.
26 |
27 | Separating request/response meta-data from response content has a few important
28 | advantages:
29 |
30 | * Different storage types can be used for meta and entity storage. For
31 | example, it may be desirable to use memcached to store meta information
32 | while using the filesystem for entity storage.
33 |
34 | * Cache entry meta-data may be retrieved quickly without also retrieving
35 | response bodies. This avoids significant overhead when the cache misses
36 | or only requires validation.
37 |
38 | * Multiple different responses may include the same exact response body. In
39 | these cases, the actual body content is stored once and referenced from
40 | each of the meta store entries.
41 |
42 | You should consider how the meta and entity stores differ when choosing a storage
43 | implementation. The MetaStore does not require nearly as much memory as the
44 | EntityStore and is accessed much more frequently. The EntityStore can grow quite
45 | large and raw performance is less of a concern. Using a memory based storage
46 | implementation (`heap` or `memcached`) for the MetaStore is strongly advised,
47 | while a disk based storage implementation (`file`) is often satisfactory for
48 | the EntityStore and uses much less memory.
49 |
50 | Storage Configuration
51 | ---------------------
52 |
53 | The MetaStore and EntityStore used for a particular request is determined by
54 | inspecting the `rack-cache.metastore` and `rack-cache.entitystore` Rack env
55 | variables. The value of these variables is a URI that identifies the storage
56 | type and location (URI formats are documented in the following section).
57 |
58 | The `heap:/` storage is assumed if either storage type is not explicitly
59 | provided. This storage type has significant drawbacks for most types of
60 | deployments so explicit configuration is advised.
61 |
62 | The default metastore and entitystore values can be specified when the
63 | __Rack::Cache__ object is added to the Rack middleware pipeline as follows:
64 |
65 | use Rack::Cache,
66 | :metastore => 'file:/var/cache/rack/meta',
67 | :entitystore => 'file:/var/cache/rack/body'
68 |
69 | Alternatively, the `rack-cache.metastore` and `rack-cache.entitystore`
70 | variables may be set in the Rack environment by an upstream component.
71 |
72 | Storage Implementations
73 | -----------------------
74 |
75 | __Rack::Cache__ includes meta and entity storage implementations backed by local
76 | process memory ("heap storage"), the file system ("disk storage"), and
77 | memcached. This section includes information on configuring __Rack::Cache__ to
78 | use a specific storage implementation as well as pros and cons of each.
79 |
80 | ### Heap Storage
81 |
82 | Uses local process memory to store cached entries.
83 |
84 | use Rack::Cache,
85 | :metastore => 'heap:/',
86 | :entitystore => 'heap:/'
87 |
88 | The heap storage backend is simple, fast, and mostly useless. All cache
89 | information is stored in each backend application's local process memory (using
90 | a normal Hash, in fact), which means that data cached under one backend is
91 | invisible to all other backends. This leads to low cache hit rates and excessive
92 | memory use, the magnitude of which is a function of the number of backends in
93 | use. Further, the heap storage provides no mechanism for purging unused entries
94 | so memory use is guaranteed to exceed that available, given enough time and
95 | utilization.
96 |
97 | Use of heap storage is recommended only for testing purposes or for very
98 | simple/single-backend deployment scenarios where the number of resources served
99 | is small and well understood.
100 |
101 | ### Disk Storage
102 |
103 | Stores cached entries on the filesystem.
104 |
105 | use Rack::Cache,
106 | :metastore => 'file:/var/cache/rack/meta',
107 | :entitystore => 'file:/var/cache/rack/body'
108 |
109 | The URI may specify an absolute, relative, or home-rooted path:
110 |
111 | * `file:/storage/path` - absolute path to storage directory.
112 | * `file:storage/path` - relative path to storage directory, rooted at the
113 | process's current working directory (`Dir.pwd`).
114 | * `file:~user/storage/path` - path to storage directory, rooted at the
115 | specified user's home directory.
116 | * `file:~/storage/path` - path to storage directory, rooted at the current
117 | user's home directory.
118 |
119 | File system storage is simple, requires no special daemons or libraries, has a
120 | tiny memory footprint, and allows multiple backends to share a single cache; it
121 | is one of the slower storage implementations, however. Its use is recommended in
122 | cases where memory is limited or in environments where more complex storage
123 | backends (i.e., memcached) are not available. In many cases, it may be
124 | acceptable (and even optimal) to use file system storage for the entitystore and
125 | a more performant storage implementation (i.e. memcached) for the metastore.
126 |
127 | __NOTE:__ When both the metastore and entitystore are configured to use file
128 | system storage, they should be set to different paths to prevent any chance of
129 | collision.
130 |
131 | ### Memcached Storage
132 |
133 | Stores cached entries in a remote [memcached](http://www.danga.com/memcached/)
134 | instance.
135 |
136 | use Rack::Cache,
137 | :metastore => 'memcached://localhost:11211/meta',
138 | :entitystore => 'memcached://localhost:11211/body'
139 |
140 | The URI must specify the host and port of a remote memcached daemon. The path
141 | portion is an optional (but recommended) namespace that is prepended to each
142 | cache key.
143 |
144 | The memcached storage backend requires either the `dalli` or `memcached`
145 | libraries. By default, the `dalli` library is used; require the `memcached`
146 | library explicitly to use it instead.
147 |
148 | gem install dalli
149 |
150 | Memcached storage is reasonably fast and allows multiple backends to share a
151 | single cache. It is also the only storage implementation that allows the cache
152 | to reside somewhere other than the local machine. The memcached daemon stores
153 | all data in local process memory so using it for the entitystore can result in
154 | heavy memory usage. It is by far the best option for the metastore in
155 | deployments with multiple backend application processes since it allows the
156 | cache to be properly distributed and provides fast access to the
157 | meta-information required to perform cache logic. Memcached is considerably more
158 | complex than the other storage implementations, requiring a separate daemon
159 | process and extra libraries. Still, its use is recommended in all cases where
160 | you can get away with it.
161 |
162 | [e]: http://blog.evanweaver.com/files/doc/fauna/memcached/files/README.html
163 | [f]: http://blog.evanweaver.com/articles/2008/01/21/b-the-fastest-u-can-b-memcached/
164 | [l]: http://tangent.org/552/libmemcached.html
165 |
--------------------------------------------------------------------------------
/example/sinatra/app.rb:
--------------------------------------------------------------------------------
1 | require 'sinatra'
2 | require 'rack/cache'
3 |
4 | use Rack::Cache do
5 | set :verbose, true
6 | set :metastore, 'heap:/'
7 | set :entitystore, 'heap:/'
8 | end
9 |
10 | before do
11 | last_modified $updated_at ||= Time.now
12 | end
13 |
14 | get '/' do
15 | erb :index
16 | end
17 |
18 | put '/' do
19 | $updated_at = nil
20 | redirect '/'
21 | end
22 |
--------------------------------------------------------------------------------
/example/sinatra/views/index.erb:
--------------------------------------------------------------------------------
1 |
2 |
3 | Sample Rack::Cache Sinatra app
4 |
20 |
21 |
22 | Last updated at: <%= $updated_at.strftime('%l:%m:%S%P') %>
23 |
24 |
25 |
29 |
30 |
31 |
43 |
44 |
45 |
--------------------------------------------------------------------------------
/gems.rb:
--------------------------------------------------------------------------------
1 | source "https://rubygems.org"
2 |
3 | gemspec
4 |
5 | group :maintenance, optional: true do
6 | gem "bake"
7 | gem "bake-gem"
8 | end
9 |
--------------------------------------------------------------------------------
/gems/rack_v2-1.rb:
--------------------------------------------------------------------------------
1 | # frozen_string_literal: true
2 |
3 | source 'https://rubygems.org'
4 |
5 | gemspec path: "../"
6 |
7 | gem 'rack', '~> 2.1.0'
8 |
--------------------------------------------------------------------------------
/gems/rack_v2.rb:
--------------------------------------------------------------------------------
1 | # frozen_string_literal: true
2 |
3 | source 'https://rubygems.org'
4 |
5 | gemspec path: "../"
6 |
7 | gem 'rack', '~> 2.0'
8 |
--------------------------------------------------------------------------------
/gems/rack_v3.rb:
--------------------------------------------------------------------------------
1 | # frozen_string_literal: true
2 |
3 | source 'https://rubygems.org'
4 |
5 | gemspec path: "../"
6 |
7 | gem 'rack', '~> 3.0'
8 |
--------------------------------------------------------------------------------
/lib/rack-cache.rb:
--------------------------------------------------------------------------------
1 | require 'rack/cache'
2 |
--------------------------------------------------------------------------------
/lib/rack/cache.rb:
--------------------------------------------------------------------------------
1 | require 'rack'
2 |
3 | # = HTTP Caching For Rack
4 | #
5 | # Rack::Cache is suitable as a quick, drop-in component to enable HTTP caching
6 | # for Rack-enabled applications that produce freshness (+expires+, +cache-control+)
7 | # and/or validation (+last-modified+, +etag+) information.
8 | #
9 | # * Standards-based (RFC 2616 compliance)
10 | # * Freshness/expiration based caching and validation
11 | # * Supports HTTP Vary
12 | # * Portable: 100% Ruby / works with any Rack-enabled framework
13 | # * Disk, memcached, and heap memory storage backends
14 | #
15 | # === Usage
16 | #
17 | # Create with default options:
18 | # require 'rack/cache'
19 | # Rack::Cache.new(app, :verbose => true, :entitystore => 'file:cache')
20 | #
21 | # Within a rackup file (or with Rack::Builder):
22 | # require 'rack/cache'
23 | # use Rack::Cache do
24 | # set :verbose, true
25 | # set :metastore, 'memcached://localhost:11211/meta'
26 | # set :entitystore, 'file:/var/cache/rack'
27 | # end
28 | # run app
29 | module Rack::Cache
30 | autoload :Request, 'rack/cache/request'
31 | autoload :Response, 'rack/cache/response'
32 | autoload :Context, 'rack/cache/context'
33 | autoload :Storage, 'rack/cache/storage'
34 | autoload :CacheControl, 'rack/cache/cache_control'
35 |
36 | # Create a new Rack::Cache middleware component that fetches resources from
37 | # the specified backend application. The +options+ Hash can be used to
38 | # specify default configuration values (see attributes defined in
39 | # Rack::Cache::Options for possible key/values). When a block is given, it
40 | # is executed within the context of the newly create Rack::Cache::Context
41 | # object.
42 | def self.new(backend, options={}, &b)
43 | Context.new(backend, options, &b)
44 | end
45 | end
46 |
--------------------------------------------------------------------------------
/lib/rack/cache/app_engine.rb:
--------------------------------------------------------------------------------
1 | require 'base64'
2 |
3 | module Rack::Cache::AppEngine
4 | module MC
5 | require 'java'
6 |
7 | import com.google.appengine.api.memcache.Expiration;
8 | import com.google.appengine.api.memcache.MemcacheService;
9 | import com.google.appengine.api.memcache.MemcacheServiceFactory;
10 | import com.google.appengine.api.memcache.Stats;
11 |
12 | Service = MemcacheServiceFactory.getMemcacheService
13 | end unless defined?(Rack::Cache::AppEngine::MC)
14 |
15 | class MemCache
16 | def initialize(options = {})
17 | @cache = MC::Service
18 | @cache.namespace = options[:namespace] if options[:namespace]
19 | end
20 |
21 | def contains?(key)
22 | MC::Service.contains(key)
23 | end
24 |
25 | def get(key)
26 | value = MC::Service.get(key)
27 | Marshal.load(Base64.decode64(value)) if value
28 | end
29 |
30 | def put(key, value, ttl = nil)
31 | expiration = ttl ? MC::Expiration.byDeltaSeconds(ttl) : nil
32 | value = Base64.encode64(Marshal.dump(value)).gsub(/\n/, '')
33 | MC::Service.put(key, value, expiration)
34 | end
35 |
36 | def namespace
37 | MC::Service.getNamespace
38 | end
39 |
40 | def namespace=(value)
41 | MC::Service.setNamespace(value.to_s)
42 | end
43 |
44 | def delete(key)
45 | MC::Service.delete(key)
46 | end
47 | end
48 | end
49 |
--------------------------------------------------------------------------------
/lib/rack/cache/appengine.rb:
--------------------------------------------------------------------------------
1 | warn "use require 'rack/cache/app_engine'"
2 | require 'rack/cache/app_engine'
3 |
--------------------------------------------------------------------------------
/lib/rack/cache/cache_control.rb:
--------------------------------------------------------------------------------
1 | module Rack
2 | module Cache
3 |
4 | # Parses a cache-control header and exposes the directives as a Hash.
5 | # Directives that do not have values are set to +true+.
6 | class CacheControl < Hash
7 | def initialize(value=nil)
8 | parse(value)
9 | end
10 |
11 | # Indicates that the response MAY be cached by any cache, even if it
12 | # would normally be non-cacheable or cacheable only within a non-
13 | # shared cache.
14 | #
15 | # A response may be considered public without this directive if the
16 | # private directive is not set and the request does not include an
17 | # Authorization header.
18 | def public?
19 | self['public']
20 | end
21 |
22 | # Indicates that all or part of the response message is intended for
23 | # a single user and MUST NOT be cached by a shared cache. This
24 | # allows an origin server to state that the specified parts of the
25 | # response are intended for only one user and are not a valid
26 | # response for requests by other users. A private (non-shared) cache
27 | # MAY cache the response.
28 | #
29 | # Note: This usage of the word private only controls where the
30 | # response may be cached, and cannot ensure the privacy of the
31 | # message content.
32 | def private?
33 | self['private']
34 | end
35 |
36 | # When set in a response, a cache MUST NOT use the response to satisfy a
37 | # subsequent request without successful revalidation with the origin
38 | # server. This allows an origin server to prevent caching even by caches
39 | # that have been configured to return stale responses to client requests.
40 | #
41 | # Note that this does not necessary imply that the response may not be
42 | # stored by the cache, only that the cache cannot serve it without first
43 | # making a conditional GET request with the origin server.
44 | #
45 | # When set in a request, the server MUST NOT use a cached copy for its
46 | # response. This has quite different semantics compared to the no-cache
47 | # directive on responses. When the client specifies no-cache, it causes
48 | # an end-to-end reload, forcing each cache to update their cached copies.
49 | def no_cache?
50 | self['no-cache']
51 | end
52 |
53 | # Indicates that the response MUST NOT be stored under any circumstances.
54 | #
55 | # The purpose of the no-store directive is to prevent the
56 | # inadvertent release or retention of sensitive information (for
57 | # example, on backup tapes). The no-store directive applies to the
58 | # entire message, and MAY be sent either in a response or in a
59 | # request. If sent in a request, a cache MUST NOT store any part of
60 | # either this request or any response to it. If sent in a response,
61 | # a cache MUST NOT store any part of either this response or the
62 | # request that elicited it. This directive applies to both non-
63 | # shared and shared caches. "MUST NOT store" in this context means
64 | # that the cache MUST NOT intentionally store the information in
65 | # non-volatile storage, and MUST make a best-effort attempt to
66 | # remove the information from volatile storage as promptly as
67 | # possible after forwarding it.
68 | #
69 | # The purpose of this directive is to meet the stated requirements
70 | # of certain users and service authors who are concerned about
71 | # accidental releases of information via unanticipated accesses to
72 | # cache data structures. While the use of this directive might
73 | # improve privacy in some cases, we caution that it is NOT in any
74 | # way a reliable or sufficient mechanism for ensuring privacy. In
75 | # particular, malicious or compromised caches might not recognize or
76 | # obey this directive, and communications networks might be
77 | # vulnerable to eavesdropping.
78 | def no_store?
79 | self['no-store']
80 | end
81 |
82 | # The expiration time of an entity MAY be specified by the origin
83 | # server using the expires header (see section 14.21). Alternatively,
84 | # it MAY be specified using the max-age directive in a response. When
85 | # the max-age cache-control directive is present in a cached response,
86 | # the response is stale if its current age is greater than the age
87 | # value given (in seconds) at the time of a new request for that
88 | # resource. The max-age directive on a response implies that the
89 | # response is cacheable (i.e., "public") unless some other, more
90 | # restrictive cache directive is also present.
91 | #
92 | # If a response includes both an expires header and a max-age
93 | # directive, the max-age directive overrides the expires header, even
94 | # if the expires header is more restrictive. This rule allows an origin
95 | # server to provide, for a given response, a longer expiration time to
96 | # an HTTP/1.1 (or later) cache than to an HTTP/1.0 cache. This might be
97 | # useful if certain HTTP/1.0 caches improperly calculate ages or
98 | # expiration times, perhaps due to desynchronized clocks.
99 | #
100 | # Many HTTP/1.0 cache implementations will treat an expires value that
101 | # is less than or equal to the response Date value as being equivalent
102 | # to the cache-control response directive "no-cache". If an HTTP/1.1
103 | # cache receives such a response, and the response does not include a
104 | # cache-control header field, it SHOULD consider the response to be
105 | # non-cacheable in order to retain compatibility with HTTP/1.0 servers.
106 | #
107 | # When the max-age directive is included in the request, it indicates
108 | # that the client is willing to accept a response whose age is no
109 | # greater than the specified time in seconds.
110 | def max_age
111 | self['max-age'].to_i if key?('max-age')
112 | end
113 |
114 | # If a response includes an s-maxage directive, then for a shared
115 | # cache (but not for a private cache), the maximum age specified by
116 | # this directive overrides the maximum age specified by either the
117 | # max-age directive or the expires header. The s-maxage directive
118 | # also implies the semantics of the proxy-revalidate directive. i.e.,
119 | # that the shared cache must not use the entry after it becomes stale
120 | # to respond to a subsequent request without first revalidating it with
121 | # the origin server. The s-maxage directive is always ignored by a
122 | # private cache.
123 | def shared_max_age
124 | self['s-maxage'].to_i if key?('s-maxage')
125 | end
126 | alias_method :s_maxage, :shared_max_age
127 |
128 | # If a response includes a r-maxage directive, then for a reverse cache
129 | # (but not for a private or proxy cache), the maximum age specified by
130 | # this directive overrides the maximum age specified by either the max-age
131 | # directive, the s-maxage directive, or the expires header. The r-maxage
132 | # directive also implies the semantics of the proxy-revalidate directive.
133 | # i.e., that the reverse cache must not use the entry after it becomes
134 | # stale to respond to a subsequent request without first revalidating it
135 | # with the origin server. The r-maxage directive is always ignored by
136 | # private and proxy caches.
137 | def reverse_max_age
138 | self['r-maxage'].to_i if key?('r-maxage')
139 | end
140 | alias_method :r_maxage, :reverse_max_age
141 |
142 | # Because a cache MAY be configured to ignore a server's specified
143 | # expiration time, and because a client request MAY include a max-
144 | # stale directive (which has a similar effect), the protocol also
145 | # includes a mechanism for the origin server to require revalidation
146 | # of a cache entry on any subsequent use. When the must-revalidate
147 | # directive is present in a response received by a cache, that cache
148 | # MUST NOT use the entry after it becomes stale to respond to a
149 | # subsequent request without first revalidating it with the origin
150 | # server. (I.e., the cache MUST do an end-to-end revalidation every
151 | # time, if, based solely on the origin server's expires or max-age
152 | # value, the cached response is stale.)
153 | #
154 | # The must-revalidate directive is necessary to support reliable
155 | # operation for certain protocol features. In all circumstances an
156 | # HTTP/1.1 cache MUST obey the must-revalidate directive; in
157 | # particular, if the cache cannot reach the origin server for any
158 | # reason, it MUST generate a 504 (Gateway Timeout) response.
159 | #
160 | # Servers SHOULD send the must-revalidate directive if and only if
161 | # failure to revalidate a request on the entity could result in
162 | # incorrect operation, such as a silently unexecuted financial
163 | # transaction. Recipients MUST NOT take any automated action that
164 | # violates this directive, and MUST NOT automatically provide an
165 | # unvalidated copy of the entity if revalidation fails.
166 | def must_revalidate?
167 | self['must-revalidate']
168 | end
169 |
170 | # The proxy-revalidate directive has the same meaning as the must-
171 | # revalidate directive, except that it does not apply to non-shared
172 | # user agent caches. It can be used on a response to an
173 | # authenticated request to permit the user's cache to store and
174 | # later return the response without needing to revalidate it (since
175 | # it has already been authenticated once by that user), while still
176 | # requiring proxies that service many users to revalidate each time
177 | # (in order to make sure that each user has been authenticated).
178 | # Note that such authenticated responses also need the public cache
179 | # control directive in order to allow them to be cached at all.
180 | def proxy_revalidate?
181 | self['proxy-revalidate']
182 | end
183 |
184 | def to_s
185 | bools, vals = [], []
186 | each do |key,value|
187 | if value == true
188 | bools << key
189 | elsif value
190 | vals << "#{key}=#{value}"
191 | end
192 | end
193 | (bools.sort + vals.sort).join(', ')
194 | end
195 |
196 | private
197 |
198 | def parse(value)
199 | return if value.nil? || value.empty?
200 | value.delete(' ').split(',').each do |part|
201 | next if part.empty?
202 | name, value = part.split('=', 2)
203 | self[name.downcase] = (value || true) unless name.empty?
204 | end
205 | self
206 | end
207 | end
208 | end
209 | end
210 |
--------------------------------------------------------------------------------
/lib/rack/cache/cachecontrol.rb:
--------------------------------------------------------------------------------
1 | warn "use require 'rack/cache/cache_control'"
2 | require 'rack/cache/cache_control'
3 |
--------------------------------------------------------------------------------
/lib/rack/cache/context.rb:
--------------------------------------------------------------------------------
1 | require 'rack/cache/options'
2 | require 'rack/cache/request'
3 | require 'rack/cache/response'
4 | require 'rack/cache/storage'
5 |
6 | module Rack::Cache
7 | # Implements Rack's middleware interface and provides the context for all
8 | # cache logic, including the core logic engine.
9 | class Context
10 | include Rack::Cache::Options
11 |
12 | # Array of trace Symbols
13 | attr_reader :trace
14 |
15 | # The Rack application object immediately downstream.
16 | attr_reader :backend
17 |
18 | def initialize(backend, options={})
19 | @backend = backend
20 | @trace = []
21 | @env = nil
22 | @options = options
23 |
24 | initialize_options options
25 | yield self if block_given?
26 |
27 | @private_header_keys =
28 | private_headers.map { |name| "HTTP_#{name.upcase.tr('-', '_')}" }
29 | end
30 |
31 | # The configured MetaStore instance. Changing the rack-cache.metastore
32 | # value effects the result of this method immediately.
33 | def metastore
34 | uri = options['rack-cache.metastore']
35 | storage.resolve_metastore_uri(uri, @options)
36 | end
37 |
38 | # The configured EntityStore instance. Changing the rack-cache.entitystore
39 | # value effects the result of this method immediately.
40 | def entitystore
41 | uri = options['rack-cache.entitystore']
42 | storage.resolve_entitystore_uri(uri, @options)
43 | end
44 |
45 | # The Rack call interface. The receiver acts as a prototype and runs
46 | # each request in a dup object unless the +rack.run_once+ variable is
47 | # set in the environment.
48 | def call(env)
49 | if env['rack.run_once'] && !env['rack.multithread']
50 | call! env
51 | else
52 | clone.call! env
53 | end
54 | end
55 |
56 | # The real Rack call interface. The caching logic is performed within
57 | # the context of the receiver.
58 | def call!(env)
59 | @trace = []
60 | @default_options.each { |k,v| env[k] ||= v }
61 | @env = env
62 | @request = Request.new(@env.dup.freeze)
63 |
64 | response =
65 | if @request.get? || @request.head?
66 | if !@env['HTTP_EXPECT'] && !@env['rack-cache.force-pass']
67 | lookup
68 | else
69 | pass
70 | end
71 | else
72 | if @request.options?
73 | pass
74 | else
75 | invalidate
76 | end
77 | end
78 |
79 | # log trace and set x-rack-cache tracing header
80 | trace = @trace.join(', ')
81 | response.headers['x-rack-cache'] = trace
82 |
83 | # write log message to rack.errors
84 | if verbose?
85 | message = "cache: [%s %s] %s\n" %
86 | [@request.request_method, @request.fullpath, trace]
87 | log_info(message)
88 | end
89 |
90 | # tidy up response a bit
91 | if (@request.get? || @request.head?) && not_modified?(response)
92 | response.not_modified!
93 | end
94 |
95 | if @request.head?
96 | response.body.close if response.body.respond_to?(:close)
97 | response.body = []
98 | end
99 | response.to_a
100 | end
101 |
102 | private
103 |
104 | # Record that an event took place.
105 | def record(event)
106 | @trace << event
107 | end
108 |
109 | # Does the request include authorization or other sensitive information
110 | # that should cause the response to be considered private by default?
111 | # Private responses are not stored in the cache.
112 | def private_request?
113 | @private_header_keys.any? { |key| @env.key?(key) }
114 | end
115 |
116 | # Determine if the #response validators (etag, last-modified) matches
117 | # a conditional value specified in #request.
118 | def not_modified?(response)
119 | last_modified = @request.env['HTTP_IF_MODIFIED_SINCE']
120 | if etags = @request.env['HTTP_IF_NONE_MATCH']
121 | etags = etags.split(/\s*,\s*/)
122 | (etags.include?(response.etag) || etags.include?('*')) && (!last_modified || response.last_modified == last_modified)
123 | elsif last_modified
124 | response.last_modified == last_modified
125 | end
126 | end
127 |
128 | # Whether the cache entry is "fresh enough" to satisfy the request.
129 | def fresh_enough?(entry)
130 | if entry.fresh?
131 | if allow_revalidate? && max_age = @request.cache_control.max_age
132 | max_age > 0 && max_age >= entry.age
133 | else
134 | true
135 | end
136 | end
137 | end
138 |
139 | # Delegate the request to the backend and create the response.
140 | def forward
141 | Response.new(*backend.call(@env))
142 | end
143 |
144 | # The request is sent to the backend, and the backend's response is sent
145 | # to the client, but is not entered into the cache.
146 | def pass
147 | record :pass
148 | forward
149 | end
150 |
151 | # Invalidate POST, PUT, DELETE and all methods not understood by this cache
152 | # See RFC2616 13.10
153 | def invalidate
154 | metastore.invalidate(@request, entitystore)
155 | rescue => e
156 | log_error(e)
157 | pass
158 | else
159 | record :invalidate
160 | pass
161 | end
162 |
163 | # Try to serve the response from cache. When a matching cache entry is
164 | # found and is fresh, use it as the response without forwarding any request
165 | # to the backend. When a matching cache entry is found but is stale, attempt
166 | # to #validate the entry with the backend using conditional GET.
167 | # If validation raises an exception and fault tolerant caching is enabled,
168 | # serve the stale cache entry.
169 | # When no matching cache entry is found, trigger miss processing.
170 | def lookup
171 | if @request.no_cache? && allow_reload?
172 | record :reload
173 | fetch
174 | else
175 | begin
176 | entry = metastore.lookup(@request, entitystore)
177 | rescue => e
178 | log_error(e)
179 | return pass
180 | end
181 | if entry
182 | if fresh_enough?(entry)
183 | record :fresh
184 | entry.headers['age'] = entry.age.to_s
185 | entry
186 | else
187 | record :stale
188 | if fault_tolerant?
189 | validate_with_stale_cache_failover(entry)
190 | else
191 | validate(entry)
192 | end
193 | end
194 | else
195 | record :miss
196 | fetch
197 | end
198 | end
199 | end
200 |
201 | # Returns stale cache on exception.
202 | def validate_with_stale_cache_failover(entry)
203 | validate(entry)
204 | rescue => e
205 | record :connnection_failed
206 | age = entry.age.to_s
207 | entry.headers['age'] = age
208 | record "Fail-over to stale cache data with age #{age} due to #{e.class.name}: #{e}"
209 | entry
210 | end
211 |
212 | # Validate that the cache entry is fresh. The original request is used
213 | # as a template for a conditional GET request with the backend.
214 | def validate(entry)
215 | # send no head requests because we want content
216 | convert_head_to_get!
217 |
218 | # add our cached last-modified validator to the environment
219 | @env['HTTP_IF_MODIFIED_SINCE'] = entry.last_modified
220 |
221 | # Add our cached etag validator to the environment.
222 | # We keep the etags from the client to handle the case when the client
223 | # has a different private valid entry which is not cached here.
224 | cached_etags = entry.etag.to_s.split(/\s*,\s*/)
225 | request_etags = @request.env['HTTP_IF_NONE_MATCH'].to_s.split(/\s*,\s*/)
226 | etags = (cached_etags + request_etags).uniq
227 | @env['HTTP_IF_NONE_MATCH'] = etags.empty? ? nil : etags.join(', ')
228 |
229 | response = forward
230 |
231 | if response.status == 304
232 | record :valid
233 |
234 | # Check if the response validated which is not cached here
235 | etag = response.headers['etag']
236 | return response if etag && request_etags.include?(etag) && !cached_etags.include?(etag)
237 |
238 | entry = entry.dup
239 | entry.headers.delete('date')
240 | %w[Date expires cache-control etag last-modified].each do |name|
241 | next unless value = response.headers[name]
242 | entry.headers[name] = value
243 | end
244 |
245 | # even though it's empty, be sure to close the response body from upstream
246 | # because middleware use close to signal end of response
247 | response.body.close if response.body.respond_to?(:close)
248 |
249 | response = entry
250 | else
251 | record :invalid
252 | end
253 |
254 | store(response) if response.cacheable?
255 |
256 | response
257 | end
258 |
259 | # The cache missed or a reload is required. Forward the request to the
260 | # backend and determine whether the response should be stored. This allows
261 | # conditional / validation requests through to the backend but performs no
262 | # caching of the response when the backend returns a 304.
263 | def fetch
264 | # send no head requests because we want content
265 | convert_head_to_get!
266 |
267 | response = forward
268 |
269 | # Mark the response as explicitly private if any of the private
270 | # request headers are present and the response was not explicitly
271 | # declared public.
272 | if private_request? && !response.cache_control.public?
273 | response.private = true
274 | elsif default_ttl > 0 && response.ttl.nil? && !response.cache_control.must_revalidate?
275 | # assign a default TTL for the cache entry if none was specified in
276 | # the response; the must-revalidate cache control directive disables
277 | # default ttl assigment.
278 | response.ttl = default_ttl
279 | end
280 |
281 | store(response) if response.cacheable?
282 |
283 | response
284 | end
285 |
286 | # Write the response to the cache.
287 | def store(response)
288 | strip_ignore_headers(response)
289 | metastore.store(@request, response, entitystore)
290 | response.headers['age'] = response.age.to_s
291 | rescue => e
292 | log_error(e)
293 | nil
294 | else
295 | record :store
296 | end
297 |
298 | # Remove all ignored response headers before writing to the cache.
299 | def strip_ignore_headers(response)
300 | stripped_values = ignore_headers.map { |name| response.headers.delete(name) }
301 | record :ignore if stripped_values.any?
302 | end
303 |
304 | def log_error(exception)
305 | message = "cache error: #{exception.message}\n#{exception.backtrace.join("\n")}\n"
306 | log(:error, message)
307 | end
308 |
309 | def log_info(message)
310 | log(:info, message)
311 | end
312 |
313 | def log(level, message)
314 | if @env['rack.logger']
315 | @env['rack.logger'].send(level, message)
316 | else
317 | @env['rack.errors'].write(message)
318 | end
319 | end
320 |
321 | # send no head requests because we want content
322 | def convert_head_to_get!
323 | if @env['REQUEST_METHOD'] == 'HEAD'
324 | @env['REQUEST_METHOD'] = 'GET'
325 | @env['rack.methodoverride.original_method'] = 'HEAD'
326 | end
327 | end
328 | end
329 | end
330 |
--------------------------------------------------------------------------------
/lib/rack/cache/entity_store.rb:
--------------------------------------------------------------------------------
1 | require 'digest/sha1'
2 |
3 | module Rack::Cache
4 |
5 | # Entity stores are used to cache response bodies across requests. All
6 | # Implementations are required to calculate a SHA checksum of the data written
7 | # which becomes the response body's key.
8 | class EntityStore
9 |
10 | # Read body calculating the SHA1 checksum and size while
11 | # yielding each chunk to the block. If the body responds to close,
12 | # call it after iteration is complete. Return a two-tuple of the form:
13 | # [ hexdigest, size ].
14 | def slurp(body)
15 | digest, size = Digest::SHA1.new, 0
16 | body.each do |part|
17 | size += bytesize(part)
18 | digest << part
19 | yield part
20 | end
21 | body.close if body.respond_to? :close
22 | [digest.hexdigest, size]
23 | end
24 |
25 | if ''.respond_to?(:bytesize)
26 | def bytesize(string); string.bytesize; end
27 | else
28 | def bytesize(string); string.size; end
29 | end
30 |
31 | private :slurp, :bytesize
32 |
33 |
34 | # Stores entity bodies on the heap using a Hash object.
35 | class Heap < EntityStore
36 | # Create the store with the specified backing Hash.
37 | def initialize(hash={}, options = {})
38 | @hash = hash
39 | @options = options
40 | end
41 |
42 | # Determine whether the response body with the specified key (SHA1)
43 | # exists in the store.
44 | def exist?(key)
45 | @hash.include?(key)
46 | end
47 |
48 | # Return an object suitable for use as a Rack response body for the
49 | # specified key.
50 | def open(key)
51 | (body = @hash[key]) && body.dup
52 | end
53 |
54 | # Read all data associated with the given key and return as a single
55 | # String.
56 | def read(key)
57 | (body = @hash[key]) && body.join
58 | end
59 |
60 | # Write the Rack response body immediately and return the SHA1 key.
61 | def write(body, ttl=nil)
62 | buf = []
63 | key, size = slurp(body) { |part| buf << part }
64 | @hash[key] = buf
65 | [key, size]
66 | end
67 |
68 | # Remove the body corresponding to key; return nil.
69 | def purge(key)
70 | @hash.delete(key)
71 | nil
72 | end
73 |
74 | def self.resolve(uri, options = {})
75 | new({}, options)
76 | end
77 | end
78 |
79 | HEAP = Heap
80 | MEM = Heap
81 |
82 | # Stores entity bodies on disk at the specified path.
83 | class Disk < EntityStore
84 |
85 | # Path where entities should be stored. This directory is
86 | # created the first time the store is instansiated if it does not
87 | # already exist.
88 | attr_reader :root
89 |
90 | def initialize(root)
91 | @root = root
92 | FileUtils.mkdir_p root, :mode => 0755
93 | end
94 |
95 | def exist?(key)
96 | File.exist?(body_path(key))
97 | end
98 |
99 | def read(key)
100 | File.open(body_path(key), 'rb') { |f| f.read }
101 | rescue Errno::ENOENT
102 | nil
103 | end
104 |
105 | class Body < ::File #:nodoc:
106 | def each
107 | while part = read(8192)
108 | yield part
109 | end
110 | end
111 | alias_method :to_path, :path
112 | end
113 |
114 | # Open the entity body and return an IO object. The IO object's
115 | # each method is overridden to read 8K chunks instead of lines.
116 | def open(key)
117 | Body.open(body_path(key), 'rb')
118 | rescue Errno::ENOENT
119 | nil
120 | end
121 |
122 | def write(body, ttl=nil)
123 | filename = ['buf', $$, Thread.current.object_id].join('-')
124 | temp_file = storage_path(filename)
125 | key, size =
126 | File.open(temp_file, 'wb') { |dest|
127 | slurp(body) { |part| dest.write(part) }
128 | }
129 |
130 | path = body_path(key)
131 | if File.exist?(path)
132 | File.unlink temp_file
133 | else
134 | FileUtils.mkdir_p File.dirname(path), :mode => 0755
135 | FileUtils.mv temp_file, path
136 | end
137 | [key, size]
138 | end
139 |
140 | def purge(key)
141 | File.unlink body_path(key)
142 | nil
143 | rescue Errno::ENOENT
144 | nil
145 | end
146 |
147 | protected
148 | def storage_path(stem)
149 | File.join root, stem
150 | end
151 |
152 | def spread(key)
153 | key = key.dup
154 | key[2,0] = '/'
155 | key
156 | end
157 |
158 | def body_path(key)
159 | storage_path spread(key)
160 | end
161 |
162 | def self.resolve(uri)
163 | path = File.expand_path(uri.opaque || uri.path)
164 | new path
165 | end
166 | end
167 |
168 | DISK = Disk
169 | FILE = Disk
170 |
171 | # Base class for memcached entity stores.
172 | class MemCacheBase < EntityStore
173 | # The underlying Memcached instance used to communicate with the
174 | # memcached daemon.
175 | attr_reader :cache
176 |
177 | extend Rack::Utils
178 |
179 | def open(key)
180 | data = read(key)
181 | data && [data]
182 | end
183 |
184 | def self.resolve(uri)
185 | if uri.respond_to?(:scheme)
186 | server = "#{uri.host}:#{uri.port || '11211'}"
187 | options = parse_query(uri.query)
188 | options.keys.each do |key|
189 | value =
190 | case value = options.delete(key)
191 | when 'true' ; true
192 | when 'false' ; false
193 | else value.to_sym
194 | end
195 | options[key.to_sym] = value
196 | end
197 | options[:namespace] = uri.path.sub(/^\//, '')
198 | new server, options
199 | else
200 | # if the object provided is not a URI, pass it straight through
201 | # to the underlying implementation.
202 | new uri
203 | end
204 | end
205 | end
206 |
207 | # Uses the Dalli ruby library. This is the default unless
208 | # the memcached library has already been required.
209 | class Dalli < MemCacheBase
210 | def initialize(server="localhost:11211", options={})
211 | @cache =
212 | if server.respond_to?(:stats)
213 | server
214 | else
215 | require 'dalli'
216 | ::Dalli::Client.new(server, options)
217 | end
218 | end
219 |
220 | def exist?(key)
221 | !cache.get(key).nil?
222 | end
223 |
224 | def read(key)
225 | data = cache.get(key)
226 | data.force_encoding('BINARY') if data.respond_to?(:force_encoding)
227 | data
228 | end
229 |
230 | def write(body, ttl=nil)
231 | buf = StringIO.new
232 | key, size = slurp(body){|part| buf.write(part) }
233 | [key, size] if cache.set(key, buf.string, ttl)
234 | end
235 |
236 | def purge(key)
237 | cache.delete(key)
238 | nil
239 | end
240 | end
241 |
242 | # Uses the memcached client library. The ruby based memcache-client is used
243 | # in preference to this store unless the memcached library has already been
244 | # required.
245 | class MemCached < MemCacheBase
246 | def initialize(server="localhost:11211", options={})
247 | options[:prefix_key] ||= options.delete(:namespace) if options.key?(:namespace)
248 | @cache =
249 | if server.respond_to?(:stats)
250 | server
251 | else
252 | require 'memcached'
253 | ::Memcached.new(server, options)
254 | end
255 | end
256 |
257 | def exist?(key)
258 | cache.append(key, '')
259 | true
260 | rescue ::Memcached::NotStored
261 | false
262 | end
263 |
264 | def read(key)
265 | cache.get(key, false)
266 | rescue ::Memcached::NotFound
267 | nil
268 | end
269 |
270 | def write(body, ttl=0)
271 | buf = StringIO.new
272 | key, size = slurp(body){|part| buf.write(part) }
273 | cache.set(key, buf.string, ttl, false)
274 | [key, size]
275 | end
276 |
277 | def purge(key)
278 | cache.delete(key)
279 | nil
280 | rescue ::Memcached::NotFound
281 | nil
282 | end
283 | end
284 |
285 | MEMCACHE = Dalli
286 | MEMCACHED = MEMCACHE
287 |
288 | class GAEStore < EntityStore
289 | attr_reader :cache
290 |
291 | def initialize(options = {})
292 | require 'rack/cache/app_engine'
293 | @cache = Rack::Cache::AppEngine::MemCache.new(options)
294 | end
295 |
296 | def exist?(key)
297 | cache.contains?(key)
298 | end
299 |
300 | def read(key)
301 | cache.get(key)
302 | end
303 |
304 | def open(key)
305 | if data = read(key)
306 | [data]
307 | else
308 | nil
309 | end
310 | end
311 |
312 | def write(body, ttl=nil)
313 | buf = StringIO.new
314 | key, size = slurp(body){|part| buf.write(part) }
315 | cache.put(key, buf.string, ttl)
316 | [key, size]
317 | end
318 |
319 | def purge(key)
320 | cache.delete(key)
321 | nil
322 | end
323 |
324 | def self.resolve(uri)
325 | self.new(:namespace => uri.host)
326 | end
327 |
328 | end
329 |
330 | GAECACHE = GAEStore
331 | GAE = GAEStore
332 |
333 | # Noop Entity Store backend.
334 | #
335 | # Set `entitystore` to 'noop:/'.
336 | # Does not persist response bodies (no disk/memory used).
337 | # Responses from the cache will have an empty body.
338 | # Clients must ignore these empty cached response (check for x-rack-cache response header).
339 | # Atm cannot handle streamed responses, patch needed.
340 | #
341 | class Noop < EntityStore
342 | def exist?(key)
343 | true
344 | end
345 |
346 | def read(key)
347 | ''
348 | end
349 |
350 | def open(key)
351 | []
352 | end
353 |
354 | def write(body, ttl=nil)
355 | key, size = slurp(body) { |part| part }
356 | [key, size]
357 | end
358 |
359 | def purge(key)
360 | nil
361 | end
362 |
363 | def self.resolve(uri)
364 | new
365 | end
366 | end
367 |
368 | NOOP = Noop
369 | end
370 |
371 | end
372 |
--------------------------------------------------------------------------------
/lib/rack/cache/entitystore.rb:
--------------------------------------------------------------------------------
1 | warn "use require 'rack/cache/entity_store'"
2 | require 'rack/cache/entity_store'
3 |
--------------------------------------------------------------------------------
/lib/rack/cache/headers.rb:
--------------------------------------------------------------------------------
1 | module Rack::Cache
2 | begin
3 | # For `Rack::Headers` (Rack 3+):
4 | require "rack/headers"
5 | Headers = ::Rack::Headers
6 | def self.Headers(headers)
7 | Headers[headers]
8 | end
9 | rescue LoadError
10 | # For `Rack::Utils::HeaderHash`:
11 | require "rack/utils"
12 | Headers = ::Rack::Utils::HeaderHash
13 | def self.Headers(headers)
14 | if headers.is_a?(Headers) && !headers.frozen?
15 | return headers
16 | else
17 | return Headers.new(headers)
18 | end
19 | end
20 | end
21 | end
22 |
--------------------------------------------------------------------------------
/lib/rack/cache/key.rb:
--------------------------------------------------------------------------------
1 | require 'rack/utils'
2 |
3 | module Rack::Cache
4 | class Key
5 | include Rack::Utils
6 |
7 | # A proc for ignoring parts of query strings when generating a key. This is
8 | # useful when you have parameters like `utm` or `trk` that don't affect the
9 | # content on the page and are unique per-visitor or campaign. Parameters
10 | # like these will be part of the key and cause a lot of churn.
11 | #
12 | # The block will be passed a key and value which are the name and value of
13 | # that parameter.
14 | #
15 | # Example:
16 | # `Rack::Cache::Key.query_string_ignore = proc { |k, v| k =~ /^(trk|utm)_/ }`
17 | #
18 | class << self
19 | attr_accessor :query_string_ignore
20 | end
21 |
22 | # Implement .call, since it seems like the "Rack-y" thing to do. Plus, it
23 | # opens the door for cache key generators to just be blocks.
24 | def self.call(request)
25 | new(request).generate
26 | end
27 |
28 | def initialize(request)
29 | @request = request
30 | end
31 |
32 | # Generate a normalized cache key for the request.
33 | def generate
34 | parts = []
35 | parts << @request.scheme << "://"
36 | parts << @request.host
37 |
38 | if @request.scheme == "https" && @request.port != 443 ||
39 | @request.scheme == "http" && @request.port != 80
40 | parts << ":" << @request.port.to_s
41 | end
42 |
43 | parts << @request.script_name
44 | parts << @request.path_info
45 |
46 | if qs = query_string
47 | parts << "?"
48 | parts << qs
49 | end
50 |
51 | parts.join
52 | end
53 |
54 | private
55 | # Build a normalized query string by alphabetizing all keys/values
56 | # and applying consistent escaping.
57 | def query_string
58 | return nil if @request.query_string.to_s.empty?
59 |
60 | parts = @request.query_string.split(/[&;] */n)
61 | parts.map! { |p| p.split('=', 2).map!{ |s| unescape(s) } }
62 | parts.sort!
63 | parts.reject!(&self.class.query_string_ignore)
64 | parts.map! { |k,v| "#{escape(k)}=#{escape(v)}" }
65 | parts.empty? ? nil : parts.join('&')
66 | end
67 | end
68 | end
69 |
--------------------------------------------------------------------------------
/lib/rack/cache/meta_store.rb:
--------------------------------------------------------------------------------
1 | require 'fileutils'
2 | require 'digest/sha1'
3 | require 'rack/utils'
4 | require 'rack/cache/key'
5 |
6 | module Rack::Cache
7 |
8 | # The MetaStore is responsible for storing meta information about a
9 | # request/response pair keyed by the request's URL.
10 | #
11 | # The meta store keeps a list of request/response pairs for each canonical
12 | # request URL. A request/response pair is a two element Array of the form:
13 | # [request, response]
14 | #
15 | # The +request+ element is a Hash of Rack environment keys. Only protocol
16 | # keys (i.e., those that start with "HTTP_") are stored. The +response+
17 | # element is a Hash of cached HTTP response headers for the paired request.
18 | #
19 | # The MetaStore class is abstract and should not be instanstiated
20 | # directly. Concrete subclasses should implement the protected #read,
21 | # #write, and #purge methods. Care has been taken to keep these low-level
22 | # methods dumb and straight-forward to implement.
23 | class MetaStore
24 |
25 | # Locate a cached response for the request provided. Returns a
26 | # Rack::Cache::Response object if the cache hits or nil if no cache entry
27 | # was found.
28 | def lookup(request, entity_store)
29 | key = cache_key(request)
30 | entries = read(key)
31 |
32 | # bail out if we have nothing cached
33 | return nil if entries.empty?
34 |
35 | # find a cached entry that matches the request.
36 | env = request.env
37 | match = entries.detect{ |req,res| requests_match?((res['vary'] || res['vary']), env, req) }
38 | return nil if match.nil?
39 |
40 | _, res = match
41 | entity_key = res['x-content-digest']
42 | if entity_key && body = entity_store.open(entity_key)
43 | restore_response(res, body)
44 | else
45 | # the metastore referenced an entity that doesn't exist in
46 | # the entitystore, purge the entry from the meta-store
47 | begin
48 | purge(key)
49 | rescue NotImplementedError
50 | @@warned_on_purge ||= begin
51 | warn "WARNING: Future releases may require purge implementation for #{self.class.name}"
52 | true
53 | end
54 | nil
55 | end
56 | end
57 | end
58 |
59 | # Write a cache entry to the store under the given key. Existing
60 | # entries are read and any that match the response are removed.
61 | # This method calls #write with the new list of cache entries.
62 | def store(request, response, entity_store)
63 | key = cache_key(request)
64 | stored_env = persist_request(request)
65 |
66 | # write the response body to the entity store if this is the
67 | # original response.
68 | if response.headers['x-content-digest'].nil?
69 | if request.env['rack-cache.use_native_ttl'] && response.fresh?
70 | digest, size = entity_store.write(response.body, response.ttl)
71 | else
72 | digest, size = entity_store.write(response.body)
73 | end
74 | response.headers['x-content-digest'] = digest
75 | response.headers['content-length'] = size.to_s unless response.headers['Transfer-Encoding']
76 |
77 | # If the entitystore backend is a Noop, do not try to read the body from the backend, it always returns an empty array
78 | unless entity_store.is_a? Rack::Cache::EntityStore::Noop
79 | # A stream body can only be read once and is currently closed by #write.
80 | # (To avoid having to keep giant objects in memory when writing to disk cache
81 | # the body is never converted to a single string)
82 | # We cannot always reply on body to be re-readable,
83 | # so we have to read it from the cache.
84 | # BUG: if the cache was unable to store a stream, the stream will be closed
85 | # and rack will try to read it again, resulting in hard to track down exception
86 | response.body = entity_store.open(digest) || response.body
87 | end
88 | end
89 |
90 | # read existing cache entries, remove non-varying, and add this one to
91 | # the list
92 | vary = response.vary
93 | entries =
94 | read(key).reject do |env, res|
95 | (vary == (res['vary'])) &&
96 | requests_match?(vary, env, stored_env)
97 | end
98 |
99 | headers = persist_response(response)
100 | headers.delete('age')
101 |
102 | entries.unshift [stored_env, headers]
103 | if request.env['rack-cache.use_native_ttl'] && response.fresh?
104 | write key, entries, response.ttl
105 | else
106 | write key, entries
107 | end
108 | key
109 | end
110 |
111 | # Generate a cache key for the request.
112 | def cache_key(request)
113 | keygen = request.env['rack-cache.cache_key'] || Key
114 | keygen.call(request)
115 | end
116 |
117 | # Invalidate all cache entries that match the request.
118 | def invalidate(request, entity_store)
119 | modified = false
120 | key = cache_key(request)
121 | entries =
122 | read(key).map do |req, res|
123 | response = restore_response(res)
124 | if response.fresh?
125 | response.expire!
126 | modified = true
127 | end
128 | [req, persist_response(response)]
129 | end
130 | write key, entries if modified
131 | end
132 |
133 | private
134 |
135 | # Extract the environment Hash from +request+ while making any
136 | # necessary modifications in preparation for persistence. The Hash
137 | # returned must be marshalable.
138 | def persist_request(request)
139 | env = request.env.dup
140 | env.reject! { |key,val| key =~ /[^0-9A-Z_]/ || !val.respond_to?(:to_str) }
141 | env
142 | end
143 |
144 | # Converts a stored response hash into a Response object. The caller
145 | # is responsible for loading and passing the body if needed.
146 | def restore_response(hash, body=[])
147 | status = hash.delete('x-status').to_i
148 | Rack::Cache::Response.new(status, hash, body)
149 | end
150 |
151 | def persist_response(response)
152 | hash = response.headers.dup
153 | hash['x-status'] = response.status.to_s
154 | hash
155 | end
156 |
157 | # Determine whether the two environment hashes are non-varying based on
158 | # the vary response header value provided.
159 | def requests_match?(vary, env1, env2)
160 | return true if vary.nil? || vary == ''
161 | vary.split(/[\s,]+/).all? do |header|
162 | key = "HTTP_#{header.upcase.tr('-', '_')}"
163 | env1[key] == env2[key]
164 | end
165 | end
166 |
167 | protected
168 | # Locate all cached request/response pairs that match the specified
169 | # URL key. The result must be an Array of all cached request/response
170 | # pairs. An empty Array must be returned if nothing is cached for
171 | # the specified key.
172 | def read(key)
173 | raise NotImplementedError
174 | end
175 |
176 | # Store an Array of request/response pairs for the given key. Concrete
177 | # implementations should not attempt to filter or concatenate the
178 | # list in any way.
179 | def write(key, negotiations, ttl = nil)
180 | raise NotImplementedError
181 | end
182 |
183 | # Remove all cached entries at the key specified. No error is raised
184 | # when the key does not exist.
185 | def purge(key)
186 | raise NotImplementedError
187 | end
188 |
189 | private
190 | # Generate a SHA1 hex digest for the specified string. This is a
191 | # simple utility method for meta store implementations.
192 | def hexdigest(data)
193 | Digest::SHA1.hexdigest(data)
194 | end
195 |
196 | public
197 | # Concrete MetaStore implementation that uses a simple Hash to store
198 | # request/response pairs on the heap.
199 | class Heap < MetaStore
200 | def initialize(hash={}, options = {})
201 | @hash = hash
202 | @options = options
203 | end
204 |
205 | def read(key)
206 | if data = @hash[key]
207 | Marshal.load(data)
208 | else
209 | []
210 | end
211 | end
212 |
213 | def write(key, entries, ttl = nil)
214 | @hash[key] = Marshal.dump(entries)
215 | end
216 |
217 | def purge(key)
218 | @hash.delete(key)
219 | nil
220 | end
221 |
222 | def to_hash
223 | @hash
224 | end
225 |
226 | def self.resolve(uri, options = {})
227 | new({}, options)
228 | end
229 | end
230 |
231 | HEAP = Heap
232 | MEM = HEAP
233 |
234 | # Concrete MetaStore implementation that stores request/response
235 | # pairs on disk.
236 | class Disk < MetaStore
237 | attr_reader :root
238 |
239 | def initialize(root="/tmp/rack-cache/meta-#{ARGV[0]}")
240 | @root = File.expand_path(root)
241 | FileUtils.mkdir_p(root, :mode => 0755)
242 | end
243 |
244 | def read(key)
245 | path = key_path(key)
246 | File.open(path, 'rb') { |io| Marshal.load(io) }
247 | rescue Errno::ENOENT, IOError
248 | []
249 | end
250 |
251 | def write(key, entries, ttl = nil)
252 | tries = 0
253 | begin
254 | path = key_path(key)
255 | File.open(path, 'wb') { |io| Marshal.dump(entries, io, -1) }
256 | rescue Errno::ENOENT, IOError
257 | Dir.mkdir(File.dirname(path), 0755)
258 | retry if (tries += 1) == 1
259 | end
260 | end
261 |
262 | def purge(key)
263 | path = key_path(key)
264 | File.unlink(path)
265 | nil
266 | rescue Errno::ENOENT, IOError
267 | nil
268 | end
269 |
270 | private
271 | def key_path(key)
272 | File.join(root, spread(hexdigest(key)))
273 | end
274 |
275 | def spread(sha, n=2)
276 | sha = sha.dup
277 | sha[n,0] = '/'
278 | sha
279 | end
280 |
281 | public
282 | def self.resolve(uri)
283 | path = File.expand_path(uri.opaque || uri.path)
284 | new path
285 | end
286 |
287 | end
288 |
289 | DISK = Disk
290 | FILE = Disk
291 |
292 | # Stores request/response pairs in memcached. Keys are not stored
293 | # directly since memcached has a 250-byte limit on key names. Instead,
294 | # the SHA1 hexdigest of the key is used.
295 | class MemCacheBase < MetaStore
296 | extend Rack::Utils
297 |
298 | # The MemCache object used to communicated with the memcached
299 | # daemon.
300 | attr_reader :cache
301 |
302 | # Create MemCache store for the given URI. The URI must specify
303 | # a host and may specify a port, namespace, and options:
304 | #
305 | # memcached://example.com:11211/namespace?opt1=val1&opt2=val2
306 | #
307 | # Query parameter names and values are documented with the memcached
308 | # library: http://tinyurl.com/4upqnd
309 | def self.resolve(uri)
310 | if uri.respond_to?(:scheme)
311 | server = "#{uri.host}:#{uri.port || '11211'}"
312 | options = parse_query(uri.query)
313 | options.keys.each do |key|
314 | value =
315 | case value = options.delete(key)
316 | when 'true' ; true
317 | when 'false' ; false
318 | else value.to_sym
319 | end
320 | options[key.to_sym] = value
321 | end
322 |
323 | options[:namespace] = uri.path.to_s.sub(/^\//, '')
324 |
325 | new server, options
326 | else
327 | # if the object provided is not a URI, pass it straight through
328 | # to the underlying implementation.
329 | new uri
330 | end
331 | end
332 | end
333 |
334 | class Dalli < MemCacheBase
335 | def initialize(server="localhost:11211", options={})
336 | @cache =
337 | if server.respond_to?(:stats)
338 | server
339 | else
340 | require 'dalli'
341 | ::Dalli::Client.new(server, options)
342 | end
343 | end
344 |
345 | def read(key)
346 | key = hexdigest(key)
347 | cache.get(key) || []
348 | end
349 |
350 | # Default TTL to zero, interpreted as "don't expire" by Memcached.
351 | def write(key, entries, ttl = 0)
352 | key = hexdigest(key)
353 | cache.set(key, entries, ttl)
354 | end
355 |
356 | def purge(key)
357 | cache.delete(hexdigest(key))
358 | nil
359 | end
360 | end
361 |
362 | class MemCached < MemCacheBase
363 | # The Memcached instance used to communicated with the memcached
364 | # daemon.
365 | attr_reader :cache
366 |
367 | def initialize(server="localhost:11211", options={})
368 | options[:prefix_key] ||= options.delete(:namespace) if options.key?(:namespace)
369 | @cache =
370 | if server.respond_to?(:stats)
371 | server
372 | else
373 | require 'memcached'
374 | Memcached.new(server, options)
375 | end
376 | end
377 |
378 | def read(key)
379 | key = hexdigest(key)
380 | cache.get(key)
381 | rescue Memcached::NotFound
382 | []
383 | end
384 |
385 | # Default TTL to zero, interpreted as "don't expire" by Memcached.
386 | def write(key, entries, ttl = 0)
387 | key = hexdigest(key)
388 | cache.set(key, entries, ttl)
389 | end
390 |
391 | def purge(key)
392 | key = hexdigest(key)
393 | cache.delete(key)
394 | nil
395 | rescue Memcached::NotFound
396 | nil
397 | end
398 | end
399 |
400 | MEMCACHE =
401 | if defined?(::Memcached)
402 | MemCached
403 | else
404 | Dalli
405 | end
406 | MEMCACHED = MEMCACHE
407 |
408 | class GAEStore < MetaStore
409 | attr_reader :cache
410 |
411 | def initialize(options = {})
412 | require 'rack/cache/app_engine'
413 | @cache = Rack::Cache::AppEngine::MemCache.new(options)
414 | end
415 |
416 | def read(key)
417 | key = hexdigest(key)
418 | cache.get(key) || []
419 | end
420 |
421 | def write(key, entries)
422 | key = hexdigest(key)
423 | cache.put(key, entries)
424 | end
425 |
426 | def purge(key)
427 | key = hexdigest(key)
428 | cache.delete(key)
429 | nil
430 | end
431 |
432 | def self.resolve(uri)
433 | self.new(:namespace => uri.host)
434 | end
435 |
436 | end
437 |
438 | GAECACHE = GAEStore
439 | GAE = GAEStore
440 |
441 | end
442 |
443 | end
444 |
--------------------------------------------------------------------------------
/lib/rack/cache/metastore.rb:
--------------------------------------------------------------------------------
1 | warn "use require 'rack/cache/meta_store'"
2 | require 'rack/cache/meta_store'
3 |
--------------------------------------------------------------------------------
/lib/rack/cache/options.rb:
--------------------------------------------------------------------------------
1 | require 'rack/cache/key'
2 | require 'rack/cache/storage'
3 |
4 | module Rack::Cache
5 |
6 | # Configuration options and utility methods for option access. Rack::Cache
7 | # uses the Rack Environment to store option values. All options documented
8 | # below are stored in the Rack Environment as "rack-cache.", where
9 | # is the option name.
10 | module Options
11 | extend self
12 |
13 | def self.option_accessor(key)
14 | name = option_name(key)
15 | define_method(key) { || options[name] }
16 | define_method("#{key}=") { |value| options[name] = value }
17 | define_method("#{key}?") { || !! options[name] }
18 | end
19 |
20 | def option_name(key)
21 | case key
22 | when Symbol ; "rack-cache.#{key}"
23 | when String ; key
24 | else raise ArgumentError
25 | end
26 | end
27 | module_function :option_name
28 |
29 | # Enable verbose trace logging. This option is currently enabled by
30 | # default but is likely to be disabled in a future release.
31 | option_accessor :verbose
32 |
33 | # The storage resolver. Defaults to the Rack::Cache.storage singleton instance
34 | # of Rack::Cache::Storage. This object is responsible for resolving metastore
35 | # and entitystore URIs to an implementation instances.
36 | option_accessor :storage
37 |
38 | # A URI specifying the meta-store implementation that should be used to store
39 | # request/response meta information. The following URIs schemes are
40 | # supported:
41 | #
42 | # * heap:/
43 | # * file:/absolute/path or file:relative/path
44 | # * memcached://localhost:11211[/namespace]
45 | #
46 | # If no meta store is specified the 'heap:/' store is assumed. This
47 | # implementation has significant draw-backs so explicit configuration is
48 | # recommended.
49 | option_accessor :metastore
50 |
51 | # A custom cache key generator, which can be anything that responds to :call.
52 | # By default, this is the Rack::Cache::Key class, but you can implement your
53 | # own generator. A cache key generator gets passed a request and generates the
54 | # appropriate cache key.
55 | #
56 | # In addition to setting the generator to an object, you can just pass a block
57 | # instead, which will act as the cache key generator:
58 | #
59 | # set :cache_key do |request|
60 | # request.fullpath.replace(/\//, '-')
61 | # end
62 | option_accessor :cache_key
63 |
64 | # A URI specifying the entity-store implementation that should be used to
65 | # store response bodies. See the metastore option for information on
66 | # supported URI schemes.
67 | #
68 | # If no entity store is specified the 'heap:/' store is assumed. This
69 | # implementation has significant draw-backs so explicit configuration is
70 | # recommended.
71 | option_accessor :entitystore
72 |
73 | # The number of seconds that a cache entry should be considered
74 | # "fresh" when no explicit freshness information is provided in
75 | # a response. Explicit cache-control or expires headers
76 | # override this value.
77 | #
78 | # Default: 0
79 | option_accessor :default_ttl
80 |
81 | # Set of response headers that are removed before storing them in the
82 | # cache. These headers are only removed for cacheable responses. For
83 | # example, in most cases, it makes sense to prevent cookies from being
84 | # stored in the cache.
85 | #
86 | # Default: ['set-cookie']
87 | option_accessor :ignore_headers
88 |
89 | # Set of request headers that trigger "private" cache-control behavior
90 | # on responses that don't explicitly state whether the response is
91 | # public or private via a cache-control directive. Applications that use
92 | # cookies for authorization may need to add the 'Cookie' header to this
93 | # list.
94 | #
95 | # Default: ['Authorization', 'Cookie']
96 | option_accessor :private_headers
97 |
98 | # Specifies whether a client can force cache reload by including a
99 | # cache-control "no-cache" directive in the request. Disabled by default.
100 | option_accessor :allow_reload
101 |
102 | # Specifies whether a client can force cache revalidate by including a
103 | # cache-control "max-age=0" directive in the request. Disabled by default.
104 | option_accessor :allow_revalidate
105 |
106 | # Specifies whether the underlying entity store's native expiration should
107 | # be used.
108 | option_accessor :use_native_ttl
109 |
110 | # Specifies whether to serve a request from a stale cache entry if
111 | # the attempt to revalidate the cache entry raises an exception.
112 | option_accessor :fault_tolerant
113 |
114 | # The underlying options Hash. During initialization (or outside of a
115 | # request), this is a default values Hash. During a request, this is the
116 | # Rack environment Hash. The default values Hash is merged in underneath
117 | # the Rack environment before each request is processed.
118 | def options
119 | @env || @default_options
120 | end
121 |
122 | # Set multiple options.
123 | def options=(hash={})
124 | hash.each { |key,value| write_option(key, value) }
125 | end
126 |
127 | # Set an option. When +option+ is a Symbol, it is set in the Rack
128 | # Environment as "rack-cache.option". When +option+ is a String, it
129 | # exactly as specified. The +option+ argument may also be a Hash in
130 | # which case each key/value pair is merged into the environment as if
131 | # the #set method were called on each.
132 | def set(option, value=self, &block)
133 | if block_given?
134 | write_option option, block
135 | elsif value == self
136 | self.options = option.to_hash
137 | else
138 | write_option option, value
139 | end
140 | end
141 |
142 | private
143 | def initialize_options(options={})
144 | @default_options = {
145 | 'rack-cache.cache_key' => Key,
146 | 'rack-cache.verbose' => true,
147 | 'rack-cache.storage' => Rack::Cache::Storage.instance,
148 | 'rack-cache.metastore' => 'heap:/',
149 | 'rack-cache.entitystore' => 'heap:/',
150 | 'rack-cache.default_ttl' => 0,
151 | 'rack-cache.ignore_headers' => ['set-cookie'],
152 | 'rack-cache.private_headers' => ['Authorization', 'Cookie'],
153 | 'rack-cache.allow_reload' => false,
154 | 'rack-cache.allow_revalidate' => false,
155 | 'rack-cache.use_native_ttl' => false,
156 | 'rack-cache.fault_tolerant' => false,
157 | }
158 | self.options = options
159 | end
160 |
161 | def read_option(key)
162 | options[option_name(key)]
163 | end
164 |
165 | def write_option(key, value)
166 | options[option_name(key)] = value
167 | end
168 | end
169 | end
170 |
--------------------------------------------------------------------------------
/lib/rack/cache/request.rb:
--------------------------------------------------------------------------------
1 | require 'rack/request'
2 | require 'rack/cache/cache_control'
3 |
4 | module Rack::Cache
5 |
6 | # Provides access to the HTTP request. The +request+ and +original_request+
7 | # objects exposed by the Core caching engine are instances of this class.
8 | #
9 | # Request objects respond to a variety of convenience methods, including
10 | # everything defined by Rack::Request as well as the Headers and
11 | # RequestHeaders modules.
12 | class Request < Rack::Request
13 | # The HTTP request method. This is the standard implementation of this
14 | # method but is respecified here due to libraries that attempt to modify
15 | # the behavior to respect POST tunnel method specifiers. We always want
16 | # the real request method.
17 | def request_method
18 | @env['REQUEST_METHOD']
19 | end
20 |
21 | # A CacheControl instance based on the request's cache-control header.
22 | def cache_control
23 | @cache_control ||= CacheControl.new(env['HTTP_CACHE_CONTROL'])
24 | end
25 |
26 | # True when the cache-control/no-cache directive is present or the
27 | # Pragma header is set to no-cache.
28 | def no_cache?
29 | cache_control['no-cache'] ||
30 | env['HTTP_PRAGMA'] == 'no-cache'
31 | end
32 | end
33 | end
34 |
--------------------------------------------------------------------------------
/lib/rack/cache/response.rb:
--------------------------------------------------------------------------------
1 | require 'time'
2 | require 'set'
3 | require 'rack/response'
4 | require 'rack/cache/cache_control'
5 |
6 | require_relative 'headers'
7 |
8 | module Rack::Cache
9 | # Provides access to the response generated by the downstream application. The
10 | # +response+, +original_response+, and +entry+ objects exposed by the Core
11 | # caching engine are instances of this class.
12 | #
13 | # Response objects respond to a variety of convenience methods, including
14 | # those defined in Rack::Response::Helpers, Rack::Cache::Headers,
15 | # and Rack::Cache::ResponseHeaders.
16 | #
17 | # Note that Rack::Cache::Response is not a subclass of Rack::Response and does
18 | # not perform many of the same initialization and finalization tasks. For
19 | # example, the body is not slurped during initialization and there are no
20 | # facilities for generating response output.
21 | class Response
22 | include Rack::Response::Helpers
23 |
24 | # Rack response tuple accessors.
25 | attr_accessor :status, :headers, :body
26 |
27 | # The time when the Response object was instantiated.
28 | attr_reader :now
29 |
30 | # Create a Response instance given the response status code, header hash,
31 | # and body.
32 | def initialize(status, headers, body)
33 | @status = status.to_i
34 | @headers = Rack::Cache::Headers(headers)
35 | @body = body
36 | @now = Time.now
37 | @headers['date'] ||= @now.httpdate
38 | end
39 |
40 | def initialize_copy(other)
41 | super
42 | @headers = other.headers.dup
43 | @cache_control = nil
44 | end
45 |
46 | # Return the status, headers, and body in a three-tuple.
47 | def to_a
48 | [status, headers.to_hash, body]
49 | end
50 |
51 | # Status codes of responses that MAY be stored by a cache or used in reply
52 | # to a subsequent request.
53 | #
54 | # http://tools.ietf.org/html/rfc2616#section-13.4
55 | CACHEABLE_RESPONSE_CODES = [
56 | 200, # OK
57 | 203, # Non-Authoritative Information
58 | 300, # Multiple Choices
59 | 301, # Moved Permanently
60 | 302, # Found
61 | 404, # Not Found
62 | 410 # Gone
63 | ].to_set
64 |
65 | # A Hash of name=value pairs that correspond to the cache-control header.
66 | # Valueless parameters (e.g., must-revalidate, no-store) have a Hash value
67 | # of true. This method always returns a Hash, empty if no cache-control
68 | # header is present.
69 | def cache_control
70 | @cache_control ||= CacheControl.new(headers['cache-control'])
71 | end
72 |
73 | # Set the cache-control header to the values specified by the Hash. See
74 | # the #cache_control method for information on expected Hash structure.
75 | def cache_control=(value)
76 | if value.respond_to? :to_hash
77 | cache_control.clear
78 | cache_control.merge!(value)
79 | value = cache_control.to_s
80 | end
81 |
82 | if value.nil? || value.empty?
83 | headers.delete('cache-control')
84 | else
85 | headers['cache-control'] = value
86 | end
87 | end
88 |
89 | # Determine if the response is "fresh". Fresh responses may be served from
90 | # cache without any interaction with the origin. A response is considered
91 | # fresh when it includes a cache-control/max-age indicator or Expiration
92 | # header and the calculated age is less than the freshness lifetime.
93 | def fresh?
94 | ttl && ttl > 0
95 | end
96 |
97 | # Determine if the response is worth caching under any circumstance. Responses
98 | # marked "private" with an explicit cache-control directive are considered
99 | # uncacheable
100 | #
101 | # Responses with neither a freshness lifetime (expires, max-age) nor cache
102 | # validator (last-modified, etag) are considered uncacheable.
103 | def cacheable?
104 | return false unless CACHEABLE_RESPONSE_CODES.include?(status)
105 | return false if cache_control.no_store? || cache_control.private?
106 | validateable? || fresh?
107 | end
108 |
109 | # Determine if the response includes headers that can be used to validate
110 | # the response with the origin using a conditional GET request.
111 | def validateable?
112 | headers.key?('last-modified') || headers.key?('etag')
113 | end
114 |
115 | # Mark the response "private", making it ineligible for serving other
116 | # clients.
117 | def private=(value)
118 | value = value ? true : nil
119 | self.cache_control = cache_control.
120 | merge('public' => !value, 'private' => value)
121 | end
122 |
123 | # Indicates that the cache must not serve a stale response in any
124 | # circumstance without first revalidating with the origin. When present,
125 | # the TTL of the response should not be overriden to be greater than the
126 | # value provided by the origin.
127 | def must_revalidate?
128 | cache_control.must_revalidate || cache_control.proxy_revalidate
129 | end
130 |
131 | # Mark the response stale by setting the Age header to be equal to the
132 | # maximum age of the response.
133 | def expire!
134 | headers['age'] = max_age.to_s if fresh?
135 | end
136 |
137 | # The date, as specified by the Date header. When no Date header is present
138 | # or is unparseable, set the Date header to Time.now and return.
139 | def date
140 | if date = headers['date']
141 | Time.httpdate(date)
142 | else
143 | headers['date'] = now.httpdate unless headers.frozen?
144 | now
145 | end
146 | rescue ArgumentError
147 | headers['date'] = now.httpdate unless headers.frozen?
148 | now
149 | end
150 |
151 | # The age of the response.
152 | def age
153 | (headers['age'] || [(now - date).to_i, 0].max).to_i
154 | end
155 |
156 | # The number of seconds after the time specified in the response's Date
157 | # header when the the response should no longer be considered fresh. First
158 | # check for a r-maxage directive, then a s-maxage directive, then a max-age
159 | # directive, and then fall back on an expires header; return nil when no
160 | # maximum age can be established.
161 | def max_age
162 | cache_control.reverse_max_age ||
163 | cache_control.shared_max_age ||
164 | cache_control.max_age ||
165 | (expires && (expires - date))
166 | end
167 |
168 | # The value of the expires header as a Time object.
169 | def expires
170 | headers['expires'] && Time.httpdate(headers['expires'])
171 | rescue ArgumentError
172 | nil
173 | end
174 |
175 | # The number of seconds after which the response should no longer
176 | # be considered fresh. Sets the cache-control max-age directive.
177 | def max_age=(value)
178 | self.cache_control = cache_control.merge('max-age' => value.to_s)
179 | end
180 |
181 | # Like #max_age= but sets the s-maxage directive, which applies only
182 | # to shared caches.
183 | def shared_max_age=(value)
184 | self.cache_control = cache_control.merge('s-maxage' => value.to_s)
185 | end
186 |
187 | # Like #shared_max_age= but sets the r-maxage directive, which applies only
188 | # to reverse caches.
189 | def reverse_max_age=(value)
190 | self.cache_control = cache_control.merge('r-maxage' => value.to_s)
191 | end
192 |
193 | # The response's time-to-live in seconds, or nil when no freshness
194 | # information is present in the response. When the responses #ttl
195 | # is <= 0, the response may not be served from cache without first
196 | # revalidating with the origin.
197 | def ttl
198 | max_age - age if max_age
199 | end
200 |
201 | # Set the response's time-to-live for shared caches to the specified number
202 | # of seconds. This adjusts the cache-control/s-maxage directive.
203 | def ttl=(seconds)
204 | self.shared_max_age = age + seconds
205 | end
206 |
207 | # Set the response's time-to-live for private/client caches. This adjusts
208 | # the cache-control/max-age directive.
209 | def client_ttl=(seconds)
210 | self.max_age = age + seconds
211 | end
212 |
213 | # The String value of the last-modified header exactly as it appears
214 | # in the response (i.e., no date parsing / conversion is performed).
215 | def last_modified
216 | headers['last-modified']
217 | end
218 |
219 | # The literal value of etag HTTP header or nil if no etag is specified.
220 | def etag
221 | headers['etag']
222 | end
223 |
224 | # Headers that MUST NOT be included with 304 Not Modified responses.
225 | #
226 | # http://tools.ietf.org/html/rfc2616#section-10.3.5
227 | NOT_MODIFIED_OMIT_HEADERS = %w[
228 | allow
229 | content-encoding
230 | content-language
231 | content-length
232 | content-md5
233 | content-type
234 | last-modified
235 | ].to_set
236 |
237 | # Modify the response so that it conforms to the rules defined for
238 | # '304 Not Modified'. This sets the status, removes the body, and
239 | # discards any headers that MUST NOT be included in 304 responses.
240 | #
241 | # http://tools.ietf.org/html/rfc2616#section-10.3.5
242 | def not_modified!
243 | body.close if body.respond_to?(:close)
244 | self.status = 304
245 | self.body = []
246 | NOT_MODIFIED_OMIT_HEADERS.each { |name| headers.delete(name) }
247 | nil
248 | end
249 |
250 | # The literal value of the vary header, or nil when no header is present.
251 | def vary
252 | headers['vary']
253 | end
254 |
255 | # Does the response include a vary header?
256 | def vary?
257 | ! vary.nil?
258 | end
259 |
260 | # An array of header names given in the vary header or an empty
261 | # array when no vary header is present.
262 | def vary_header_names
263 | return [] unless vary = headers['vary']
264 | vary.split(/[\s,]+/)
265 | end
266 |
267 | end
268 | end
269 |
--------------------------------------------------------------------------------
/lib/rack/cache/storage.rb:
--------------------------------------------------------------------------------
1 | require 'uri'
2 | require 'rack/cache/meta_store'
3 | require 'rack/cache/entity_store'
4 |
5 | module Rack::Cache
6 |
7 | # Maintains a collection of MetaStore and EntityStore instances keyed by
8 | # URI. A single instance of this class can be used across a single process
9 | # to ensure that only a single instance of a backing store is created per
10 | # unique storage URI.
11 | class Storage
12 | def initialize
13 | @metastores = {}
14 | @entitystores = {}
15 | end
16 |
17 | def resolve_metastore_uri(uri, options = {})
18 | @metastores[uri.to_s] ||= create_store(MetaStore, uri, options)
19 | end
20 |
21 | def resolve_entitystore_uri(uri, options = {})
22 | @entitystores[uri.to_s] ||= create_store(EntityStore, uri, options)
23 | end
24 |
25 | def clear
26 | @metastores.clear
27 | @entitystores.clear
28 | nil
29 | end
30 |
31 | private
32 |
33 | def create_store(type, uri, options = {})
34 | if uri.respond_to?(:scheme) || uri.respond_to?(:to_str)
35 | uri = URI.parse(uri) unless uri.respond_to?(:scheme)
36 | if type.const_defined?(uri.scheme.upcase)
37 | klass = type.const_get(uri.scheme.upcase)
38 | return klass.resolve(uri) if klass.method(:resolve).arity == 1
39 | klass.resolve(uri, options)
40 | else
41 | fail "Unknown storage provider: #{uri.to_s}"
42 | end
43 | else
44 | # hack in support for passing a Dalli::Client or Memcached object
45 | # as the storage URI.
46 | case
47 | when defined?(::Dalli) && uri.kind_of?(::Dalli::Client)
48 | type.const_get(:Dalli).resolve(uri)
49 | when defined?(::Memcached) && uri.respond_to?(:stats)
50 | type.const_get(:MemCached).resolve(uri)
51 | else
52 | fail "Unknown storage provider: #{uri.to_s}"
53 | end
54 | end
55 | end
56 |
57 | public
58 |
59 | @@singleton_instance = new
60 | def self.instance
61 | @@singleton_instance
62 | end
63 | end
64 |
65 | end
66 |
--------------------------------------------------------------------------------
/lib/rack/cache/version.rb:
--------------------------------------------------------------------------------
1 | module Rack
2 | module Cache
3 | VERSION = '1.17.0'
4 | end
5 | end
6 |
--------------------------------------------------------------------------------
/rack-cache.gemspec:
--------------------------------------------------------------------------------
1 | require_relative 'lib/rack/cache/version'
2 |
3 | Gem::Specification.new do |s|
4 | s.name = "rack-cache"
5 | s.version = Rack::Cache::VERSION
6 |
7 | s.summary = "HTTP Caching for Rack"
8 | s.description = "Rack::Cache is suitable as a quick drop-in component to enable HTTP caching for Rack-based applications that produce freshness (expires, cache-control) and/or validation (last-modified, etag) information."
9 | s.required_ruby_version = '>= 2.7.7'
10 |
11 | s.authors = ["Ryan Tomayko"]
12 | s.email = "r@tomayko.com"
13 |
14 | s.files = `git ls-files lib/ README.md MIT-LICENSE`.split("\n")
15 | s.extra_rdoc_files = %w[README.md MIT-LICENSE CHANGES]
16 |
17 | s.add_dependency 'rack', '>= 0.4'
18 |
19 | s.add_development_dependency 'maxitest'
20 | s.add_development_dependency 'mocha'
21 | s.add_development_dependency 'mutex_m'
22 | s.add_development_dependency 'dalli'
23 | s.add_development_dependency 'bump'
24 | s.add_development_dependency 'rake'
25 | s.add_development_dependency 'hanna-nouveau'
26 |
27 | s.license = "MIT"
28 | s.homepage = "https://github.com/rack/rack-cache"
29 | s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Rack::Cache", "--main", "Rack::Cache"]
30 | end
31 |
--------------------------------------------------------------------------------
/test/cache_control_test.rb:
--------------------------------------------------------------------------------
1 | require_relative 'test_helper'
2 | require 'rack/cache/cache_control'
3 | require 'rack/cache/meta_store'
4 |
5 | describe Rack::Cache::CacheControl do
6 | it 'takes no args and initializes with an empty set of values' do
7 | cache_control = Rack::Cache::CacheControl.new
8 | assert cache_control.empty?
9 | cache_control.to_s.must_equal ''
10 | end
11 |
12 | it 'takes a String and parses it into a Hash when created' do
13 | cache_control = Rack::Cache::CacheControl.new('max-age=600, foo')
14 | cache_control['max-age'].must_equal '600'
15 | cache_control['foo'].must_equal true
16 | end
17 |
18 | it 'takes a String with a single name=value pair' do
19 | cache_control = Rack::Cache::CacheControl.new('max-age=600')
20 | cache_control['max-age'].must_equal '600'
21 | end
22 |
23 | it 'takes a String with multiple name=value pairs' do
24 | cache_control = Rack::Cache::CacheControl.new('max-age=600, max-stale=300, min-fresh=570')
25 | cache_control['max-age'].must_equal '600'
26 | cache_control['max-stale'].must_equal '300'
27 | cache_control['min-fresh'].must_equal '570'
28 | end
29 |
30 | it 'takes a String with a single flag value' do
31 | cache_control = Rack::Cache::CacheControl.new('no-cache')
32 | cache_control.must_include 'no-cache'
33 | cache_control['no-cache'].must_equal true
34 | end
35 |
36 | it 'takes a String with a bunch of all kinds of stuff' do
37 | cache_control =
38 | Rack::Cache::CacheControl.new('max-age=600,must-revalidate,min-fresh=3000,foo=bar,baz')
39 | cache_control['max-age'].must_equal '600'
40 | cache_control['must-revalidate'].must_equal true
41 | cache_control['min-fresh'].must_equal '3000'
42 | cache_control['foo'].must_equal 'bar'
43 | cache_control['baz'].must_equal true
44 | end
45 |
46 | it 'strips leading and trailing spaces from header value' do
47 | cache_control = Rack::Cache::CacheControl.new(' public, max-age = 600 ')
48 | cache_control.must_include 'public'
49 | cache_control.must_include 'max-age'
50 | cache_control['max-age'].must_equal '600'
51 | end
52 |
53 | it 'strips blank segments' do
54 | cache_control = Rack::Cache::CacheControl.new('max-age=600,,max-stale=300')
55 | cache_control['max-age'].must_equal '600'
56 | cache_control['max-stale'].must_equal '300'
57 | end
58 |
59 | it 'removes all directives with #clear' do
60 | cache_control = Rack::Cache::CacheControl.new('max-age=600, must-revalidate')
61 | cache_control.clear
62 | assert cache_control.empty?
63 | end
64 |
65 | it 'converts self into header String with #to_s' do
66 | cache_control = Rack::Cache::CacheControl.new
67 | cache_control['public'] = true
68 | cache_control['max-age'] = '600'
69 | cache_control.to_s.split(', ').sort.must_equal ['max-age=600', 'public']
70 | end
71 |
72 | it 'sorts alphabetically with boolean directives before value directives' do
73 | cache_control = Rack::Cache::CacheControl.new('foo=bar, z, x, y, bling=baz, zoom=zib, b, a')
74 | cache_control.to_s.must_equal 'a, b, x, y, z, bling=baz, foo=bar, zoom=zib'
75 | end
76 |
77 | it 'responds to #max_age with an integer when max-age directive present' do
78 | cache_control = Rack::Cache::CacheControl.new('public, max-age=600')
79 | cache_control.max_age.must_equal 600
80 | end
81 |
82 | it 'responds to #max_age with nil when no max-age directive present' do
83 | cache_control = Rack::Cache::CacheControl.new('public')
84 | cache_control.max_age.must_be_nil
85 | end
86 |
87 | it 'responds to #shared_max_age with an integer when s-maxage directive present' do
88 | cache_control = Rack::Cache::CacheControl.new('public, s-maxage=600')
89 | cache_control.shared_max_age.must_equal 600
90 | end
91 |
92 | it 'responds to #shared_max_age with nil when no s-maxage directive present' do
93 | cache_control = Rack::Cache::CacheControl.new('public')
94 | cache_control.shared_max_age.must_be_nil
95 | end
96 |
97 | it 'responds to #reverse_max_age with an integer when r-maxage directive present' do
98 | cache_control = Rack::Cache::CacheControl.new('public, r-maxage=600')
99 | cache_control.reverse_max_age.must_equal 600
100 | end
101 |
102 | it 'responds to #reverse_max_age with nil when no r-maxage directive present' do
103 | cache_control = Rack::Cache::CacheControl.new('public')
104 | cache_control.reverse_max_age.must_be_nil
105 | end
106 |
107 | it 'responds to #public? truthfully when public directive present' do
108 | cache_control = Rack::Cache::CacheControl.new('public')
109 | assert cache_control.public?
110 | end
111 |
112 | it 'responds to #public? non-truthfully when no public directive present' do
113 | cache_control = Rack::Cache::CacheControl.new('private')
114 | refute cache_control.public?
115 | end
116 |
117 | it 'responds to #private? truthfully when private directive present' do
118 | cache_control = Rack::Cache::CacheControl.new('private')
119 | assert cache_control.private?
120 | end
121 |
122 | it 'responds to #private? non-truthfully when no private directive present' do
123 | cache_control = Rack::Cache::CacheControl.new('public')
124 | refute cache_control.private?
125 | end
126 |
127 | it 'responds to #no_cache? truthfully when no-cache directive present' do
128 | cache_control = Rack::Cache::CacheControl.new('no-cache')
129 | assert cache_control.no_cache?
130 | end
131 |
132 | it 'responds to #no_cache? non-truthfully when no no-cache directive present' do
133 | cache_control = Rack::Cache::CacheControl.new('max-age=600')
134 | refute cache_control.no_cache?
135 | end
136 |
137 | it 'responds to #must_revalidate? truthfully when must-revalidate directive present' do
138 | cache_control = Rack::Cache::CacheControl.new('must-revalidate')
139 | assert cache_control.must_revalidate?
140 | end
141 |
142 | it 'responds to #must_revalidate? non-truthfully when no must-revalidate directive present' do
143 | cache_control = Rack::Cache::CacheControl.new('max-age=600')
144 | refute cache_control.no_cache?
145 | end
146 |
147 | it 'responds to #proxy_revalidate? truthfully when proxy-revalidate directive present' do
148 | cache_control = Rack::Cache::CacheControl.new('proxy-revalidate')
149 | assert cache_control.proxy_revalidate?
150 | end
151 |
152 | it 'responds to #proxy_revalidate? non-truthfully when no proxy-revalidate directive present' do
153 | cache_control = Rack::Cache::CacheControl.new('max-age=600')
154 | refute cache_control.no_cache?
155 | end
156 | end
157 |
--------------------------------------------------------------------------------
/test/cache_test.rb:
--------------------------------------------------------------------------------
1 | require_relative 'test_helper'
2 |
3 | describe Rack::Cache do
4 | def dumb_app(_env)
5 | body = block_given? ? [yield] : ['Hi']
6 | [ 200, {'content-type' => 'text/plain'}, body ]
7 | end
8 |
9 | before { @app = method(:dumb_app) }
10 |
11 | it 'takes a backend and returns a middleware component' do
12 | assert Rack::Cache.new(@app).respond_to? :call
13 | end
14 |
15 | it 'takes an options Hash' do
16 | Rack::Cache.new(@app, {})
17 | end
18 |
19 | it 'sets options provided in the options Hash' do
20 | object = Rack::Cache.new(@app, :foo => 'bar', 'foo.bar' => 'bling')
21 | object.options['foo.bar'].must_equal 'bling'
22 | object.options['rack-cache.foo'].must_equal 'bar'
23 | end
24 |
25 | it 'takes a block; executes it during initialization' do
26 | state, object = 'not invoked', nil
27 | instance =
28 | Rack::Cache.new @app do |cache|
29 | object = cache
30 | state = 'invoked'
31 | assert cache.respond_to? :set
32 | end
33 | state.must_equal 'invoked'
34 | object.must_equal instance
35 | end
36 | end
37 |
--------------------------------------------------------------------------------
/test/entity_store_test.rb:
--------------------------------------------------------------------------------
1 | # coding: utf-8
2 | require_relative 'test_helper'
3 | require 'rack/cache/entity_store'
4 | require 'rack/cache/meta_store'
5 |
6 | module RackCacheEntityStoreImplementation
7 | def self.included(base)
8 | base.class_eval do
9 | it 'responds to all required messages' do
10 | %w[read open write exist?].each do |message|
11 | assert @store.respond_to? message
12 | end
13 | end
14 |
15 | it 'stores bodies with #write' do
16 | key, size = @store.write(['My wild love went riding,'])
17 | assert_sha_like key
18 |
19 | data = @store.read(key)
20 | data.must_equal 'My wild love went riding,'
21 | end
22 |
23 | it 'takes a ttl parameter for #write' do
24 | key, size = @store.write(['My wild love went riding,'], 0)
25 | assert_sha_like key
26 |
27 | data = @store.read(key)
28 | data.must_equal 'My wild love went riding,'
29 | end
30 |
31 | it 'correctly determines whether cached body exists for key with #exist?' do
32 | key, size = @store.write(['She rode to the devil,'])
33 | assert @store.exist? key
34 | refute @store.exist? '938jasddj83jasdh4438021ksdfjsdfjsdsf'
35 | end
36 |
37 | it 'can read data written with #write' do
38 | key, size = @store.write(['And asked him to pay.'])
39 | data = @store.read(key)
40 | data.must_equal 'And asked him to pay.'
41 | end
42 |
43 | it 'gives a 40 character SHA1 hex digest from #write' do
44 | key, size = @store.write(['she rode to the sea;'])
45 | refute key.nil?
46 | key.length.must_equal 40
47 | key.must_match /^[0-9a-z]+$/
48 | key.must_equal '90a4c84d51a277f3dafc34693ca264531b9f51b6'
49 | end
50 |
51 | it 'returns the entire body as a String from #read' do
52 | key, size = @store.write(['She gathered together'])
53 | @store.read(key).must_equal 'She gathered together'
54 | end
55 |
56 | it 'returns nil from #read when key does not exist' do
57 | @store.read('87fe0a1ae82a518592f6b12b0183e950b4541c62').must_be_nil
58 | end
59 |
60 | it 'returns a Rack compatible body from #open' do
61 | key, size = @store.write(['Some shells for her hair.'])
62 | body = @store.open(key)
63 | assert body.respond_to? :each
64 | buf = ''
65 | body.each { |part| buf << part }
66 | buf.must_equal 'Some shells for her hair.'
67 | end
68 |
69 | it 'returns nil from #open when key does not exist' do
70 | @store.open('87fe0a1ae82a518592f6b12b0183e950b4541c62').must_be_nil
71 | end
72 |
73 | it 'can store largish bodies with binary data' do
74 | pony = File.open(File.dirname(__FILE__) + '/pony.jpg', 'rb') { |f| f.read }
75 | key, size = @store.write([pony])
76 | key.must_equal 'd0f30d8659b4d268c5c64385d9790024c2d78deb'
77 | data = @store.read(key)
78 | data.length.must_equal pony.length
79 | data.hash.must_equal pony.hash
80 | end
81 |
82 | it 'deletes stored entries with #purge' do
83 | key, size = @store.write(['My wild love went riding,'])
84 | @store.purge(key).must_be_nil
85 | @store.read(key).must_be_nil
86 | end
87 | end
88 | end
89 | end
90 |
91 | describe Rack::Cache::EntityStore do
92 | def assert_sha_like(object)
93 | assert object
94 | object.length.must_equal 40
95 | object.must_match /^[0-9a-z]+$/
96 | end
97 |
98 | describe 'Heap' do
99 | before { @store = Rack::Cache::EntityStore::Heap.new }
100 |
101 | include RackCacheEntityStoreImplementation
102 |
103 | it 'takes a Hash to ::new' do
104 | @store = Rack::Cache::EntityStore::Heap.new('foo' => ['bar'])
105 | @store.read('foo').must_equal 'bar'
106 | end
107 |
108 | it 'uses its own Hash with no args to ::new' do
109 | @store.read('foo').must_be_nil
110 | end
111 | end
112 |
113 | describe 'Disk' do
114 | before do
115 | @temp_dir = create_temp_directory
116 | @store = Rack::Cache::EntityStore::Disk.new(@temp_dir)
117 | end
118 |
119 | after do
120 | @store = nil
121 | remove_entry_secure @temp_dir
122 | end
123 | include RackCacheEntityStoreImplementation
124 |
125 | it 'takes a path to ::new and creates the directory' do
126 | path = @temp_dir + '/foo'
127 | @store = Rack::Cache::EntityStore::Disk.new(path)
128 | assert File.directory? path
129 | end
130 |
131 | it 'produces a body that responds to #to_path' do
132 | key, size = @store.write(['Some shells for her hair.'])
133 | body = @store.open(key)
134 | assert body.respond_to? :to_path
135 | path = "#{@temp_dir}/#{key[0..1]}/#{key[2..-1]}"
136 | body.to_path.must_equal path
137 | end
138 |
139 | it 'spreads data over a 36² hash radius' do
140 | (<<-PROSE).each_line { |line| assert_sha_like @store.write([line]).first }
141 | My wild love went riding,
142 | She rode all the day;
143 | She rode to the devil,
144 | And asked him to pay.
145 |
146 | The devil was wiser
147 | It's time to repent;
148 | He asked her to give back
149 | The money she spent
150 |
151 | My wild love went riding,
152 | She rode to sea;
153 | She gathered together
154 | Some shells for her hair
155 |
156 | She rode on to Christmas,
157 | She rode to the farm;
158 | She rode to Japan
159 | And re-entered a town
160 |
161 | My wild love is crazy
162 | She screams like a bird;
163 | She moans like a cat
164 | When she wants to be heard
165 |
166 | She rode and she rode on
167 | She rode for a while,
168 | Then stopped for an evening
169 | And laid her head down
170 |
171 | By this time the weather
172 | Had changed one degree,
173 | She asked for the people
174 | To let her go free
175 |
176 | My wild love went riding,
177 | She rode for an hour;
178 | She rode and she rested,
179 | And then she rode on
180 | My wild love went riding,
181 | PROSE
182 | subdirs = Dir["#{@temp_dir}/*"]
183 | subdirs.each do |subdir|
184 | File.basename(subdir).must_match /^[0-9a-z]{2}$/
185 | files = Dir["#{subdir}/*"]
186 | files.each do |filename|
187 | File.basename(filename).must_match /^[0-9a-z]{38}$/
188 | end
189 | files.length.must_be :>, 0
190 | end
191 | subdirs.length.must_equal 28
192 | end
193 | end
194 |
195 | need_memcached 'entity store tests' do
196 | describe 'MemCached' do
197 | before do
198 | @store = Rack::Cache::EntityStore::MemCached.new($memcached)
199 | end
200 | after do
201 | @store = nil
202 | end
203 | include RackCacheEntityStoreImplementation
204 | end
205 |
206 | describe 'options parsing' do
207 | before do
208 | uri = URI.parse("memcached://#{ENV['MEMCACHED']}/obj_ns1?show_backtraces=true")
209 | @memcached_metastore = Rack::Cache::MetaStore::MemCached.resolve uri
210 | end
211 |
212 | it 'passes options from uri' do
213 | @memcached_metastore.cache.instance_variable_get(:@options)[:show_backtraces].must_equal true
214 | end
215 |
216 | it 'takes namespace into account' do
217 | @memcached_metastore.cache.instance_variable_get(:@options)[:prefix_key].must_equal 'obj_ns1'
218 | end
219 | end
220 | end
221 |
222 | need_dalli 'entity store tests' do
223 | describe 'Dalli' do
224 | before do
225 | $dalli.flush_all
226 | @store = Rack::Cache::EntityStore::Dalli.new($dalli)
227 | end
228 | after do
229 | @store = nil
230 | end
231 | include RackCacheEntityStoreImplementation
232 | end
233 |
234 | describe 'options parsing' do
235 | before do
236 | uri = URI.parse("memcached://#{ENV['MEMCACHED']}/obj_ns1?show_backtraces=true")
237 | @dalli_metastore = Rack::Cache::MetaStore::Dalli.resolve uri
238 | end
239 |
240 | it 'passes options from uri' do
241 | @dalli_metastore.cache.instance_variable_get(:@options)[:show_backtraces].must_equal true
242 | end
243 |
244 | it 'takes namespace into account' do
245 | @dalli_metastore.cache.instance_variable_get(:@options)[:namespace].must_equal 'obj_ns1'
246 | end
247 | end
248 | end
249 |
250 | need_java 'entity store testing' do
251 | module Rack::Cache::AppEngine
252 | module MC
253 | class << (Service = {})
254 | def contains(key); include?(key); end
255 | def get(key); self[key]; end;
256 | def put(key, value, ttl = nil)
257 | self[key] = value
258 | end
259 | end
260 |
261 | end
262 | end
263 |
264 | describe 'GAEStore' do
265 | before do
266 | puts Rack::Cache::AppEngine::MC::Service.inspect
267 | @store = Rack::Cache::EntityStore::GAEStore.new
268 | end
269 | after do
270 | @store = nil
271 | end
272 | include RackCacheEntityStoreImplementation
273 | end
274 |
275 | end
276 |
277 | describe 'Noop' do
278 | before {@store = Rack::Cache::EntityStore::Noop.new}
279 |
280 | it 'responds to all required messages' do
281 | %w[read open write exist?].each do |message|
282 | assert @store.respond_to? message
283 | end
284 | end
285 |
286 | it 'accepts bodies with #write' do
287 | key, size = @store.write(['My wild love went riding,'])
288 | refute key.nil?
289 | assert key.length == 40 && key =~ /^[0-9a-z]+$/
290 | end
291 |
292 | it 'takes a ttl parameter for #write' do
293 | key, size = @store.write(['My wild love went riding,'], 0)
294 | refute key.nil?
295 | assert key.length == 40 && key =~ /^[0-9a-z]+$/
296 | end
297 |
298 | it 'always responds to #exist? with true, regardless of the content having been saved before' do
299 | key, size = @store.write(['She rode to the devil,'])
300 | assert @store.exist? key
301 | assert @store.exist? '938jasddj83jasdh4438021ksdfjsdfjsdsf'
302 | end
303 |
304 | it 'always responds to #read with an empty String' do
305 | key, size = @store.write(['And asked him to pay.'])
306 | data = @store.read(key)
307 | data.must_equal ''
308 | data = @store.read('938jasddj83jasdh4438021ksdfjsdfjsdsf')
309 | data.must_equal ''
310 | end
311 |
312 | it 'gives a 40 character SHA1 hex digest from #write' do
313 | key, size = @store.write(['she rode to the sea;'])
314 | refute key.nil?
315 | key.length.must_equal 40
316 | key.must_match /^[0-9a-z]+$/
317 | key.must_equal '90a4c84d51a277f3dafc34693ca264531b9f51b6'
318 | end
319 |
320 | it 'always responds to #open with empty array' do
321 | key, size = @store.write(['And asked him to pay.'])
322 | data = @store.open(key)
323 | data.must_equal []
324 | data = @store.open('938jasddj83jasdh4438021ksdfjsdfjsdsf')
325 | data.must_equal []
326 | end
327 |
328 | it 'returns a Rack compatible body from #open' do
329 | key, size = @store.write(['Some shells for her hair.'])
330 | body = @store.open(key)
331 | assert body.respond_to? :each
332 | body.must_equal []
333 | end
334 |
335 | it 'responds to #purge and returns nil' do
336 | key, size = @store.write(['My wild love went riding,'])
337 | @store.purge(key).must_be_nil
338 | end
339 | end
340 | end
341 |
--------------------------------------------------------------------------------
/test/key_test.rb:
--------------------------------------------------------------------------------
1 | require_relative 'test_helper'
2 | require 'rack/cache/key'
3 |
4 | describe Rack::Cache::Key do
5 | def mock_request(*args)
6 | uri, opts = args
7 | env = Rack::MockRequest.env_for(uri, opts || {})
8 | Rack::Cache::Request.new(env)
9 | end
10 |
11 | def new_key(request)
12 | Rack::Cache::Key.call(request)
13 | end
14 |
15 | def with_query_string_ignore(proc)
16 | Rack::Cache::Key.query_string_ignore = proc
17 | yield
18 | ensure
19 | Rack::Cache::Key.query_string_ignore = nil
20 | end
21 |
22 | it "sorts params" do
23 | request = mock_request('/test?z=last&a=first')
24 | new_key(request).must_include('a=first&z=last')
25 | end
26 |
27 | it "handles badly encoded params" do
28 | request = mock_request('/test?%D0%BA=%D1')
29 | new_key(request).must_include('%D0%BA=%D1')
30 | end
31 |
32 | it "doesn't confuse encoded equals sign with query string separator" do
33 | request = mock_request('/test?weird%3Dkey=whatever')
34 | new_key(request).must_include('weird%3Dkey=whatever')
35 | end
36 |
37 | it "includes the scheme" do
38 | request = mock_request(
39 | '/test',
40 | 'rack.url_scheme' => 'https',
41 | 'HTTP_HOST' => 'www2.example.org'
42 | )
43 | new_key(request).must_include('https://')
44 | end
45 |
46 | it "includes host" do
47 | request = mock_request('/test', "HTTP_HOST" => 'www2.example.org')
48 | new_key(request).must_include('www2.example.org')
49 | end
50 |
51 | it "includes path" do
52 | request = mock_request('/test')
53 | new_key(request).must_include('/test')
54 | end
55 |
56 | it "does not include question mark if there is no query string" do
57 | request = mock_request('/test')
58 | new_key(request).wont_include('?')
59 | end
60 |
61 | it "sorts the query string by key/value after decoding" do
62 | request = mock_request('/test?x=q&a=b&%78=c')
63 | new_key(request).must_match(/\?a=b&x=c&x=q$/)
64 | end
65 |
66 | it "is in order of scheme, host, path, params" do
67 | request = mock_request('/test?x=y', "HTTP_HOST" => 'www2.example.org')
68 | new_key(request).must_equal "http://www2.example.org/test?x=y"
69 | end
70 |
71 | it "ignores params based on configuration" do
72 | with_query_string_ignore proc { |k, _v| k == 'a' } do
73 | request = mock_request('/test?a=first&z=last')
74 | new_key(request).wont_include('a=first')
75 | new_key(request).must_include('z=last')
76 | end
77 | end
78 |
79 | it "does not include query when all params are ignored" do
80 | with_query_string_ignore proc { |k, _v| k == 'a' } do
81 | request = mock_request('/test?a=a')
82 | new_key(request).wont_include('?')
83 | end
84 | end
85 | end
86 |
--------------------------------------------------------------------------------
/test/meta_store_test.rb:
--------------------------------------------------------------------------------
1 | require_relative 'test_helper'
2 | require 'rack/cache/meta_store'
3 | require 'rack/cache/entity_store'
4 |
5 | module RackCacheMetaStoreImplementation
6 | def self.included(base)
7 | base.class_eval do
8 |
9 | ###
10 | # Helpers
11 | def mock_request(uri, opts)
12 | env = Rack::MockRequest.env_for(uri, opts || {})
13 | Rack::Cache::Request.new(env)
14 | end
15 |
16 | def mock_response(status, headers, body)
17 | headers ||= {}
18 | Rack::Cache::Response.new(status, headers, body)
19 | end
20 |
21 | def slurp(body)
22 | buf = ''
23 | body.each { |part| buf << part }
24 | buf
25 | end
26 |
27 | # Stores an entry for the given request args, returns a url encoded cache key
28 | # for the request.
29 | def store_simple_entry(path=nil, headers=nil, body=['test'])
30 | @request = mock_request(path || '/test', headers || {})
31 | @response = mock_response(200, {'cache-control' => 'max-age=420'}, body)
32 | body = @response.body
33 | cache_key = @store.store(@request, @response, @entity_store)
34 |
35 | # atm we always read back the body from the cache, this is a workaround to deal with
36 | # bodies that can only be read once
37 | @response.body.object_id.wont_equal body.object_id
38 |
39 | cache_key
40 | end
41 |
42 | before do
43 | @request = mock_request('/', {})
44 | @response = mock_response(200, {}, ['hello world'])
45 | end
46 |
47 | after do
48 | @store = nil
49 | @entity_store = nil
50 | end
51 |
52 | # Low-level implementation methods ===========================================
53 |
54 | it 'writes a list of negotation tuples with #write' do
55 | @store.write('/test', [[{}, {}]])
56 | end
57 |
58 | it 'reads a list of negotation tuples with #read' do
59 | @store.write('/test', [[{},{}],[{},{}]])
60 | tuples = @store.read('/test')
61 | tuples.must_equal [ [{},{}], [{},{}] ]
62 | end
63 |
64 | it 'reads an empty list with #read when nothing cached at key' do
65 | assert @store.read('/nothing').empty?
66 | end
67 |
68 | it 'removes entries for key with #purge' do
69 | @store.write('/test', [[{},{}]])
70 | refute @store.read('/test').empty?
71 |
72 | @store.purge('/test')
73 | assert @store.read('/test').empty?
74 | end
75 |
76 | it 'succeeds when purging non-existing entries' do
77 | assert @store.read('/test').empty?
78 | @store.purge('/test')
79 | end
80 |
81 | it 'returns nil from #purge' do
82 | @store.write('/test', [[{},{}]])
83 | @store.purge('/test').must_be_nil
84 | @store.read('/test').must_equal []
85 | end
86 |
87 | %w[/test http://example.com:8080/ /test?x=y /test?x=y&p=q].each do |key|
88 | it "can read and write key: '#{key}'" do
89 | @store.write(key, [[{},{}]])
90 | @store.read(key).must_equal [[{},{}]]
91 | end
92 | end
93 |
94 | it "can read and write fairly large keys" do
95 | key = "b" * 4096
96 | @store.write(key, [[{},{}]])
97 | @store.read(key).must_equal [[{},{}]]
98 | end
99 |
100 | it "allows custom cache keys from block" do
101 | request = mock_request('/test', {})
102 | request.env['rack-cache.cache_key'] =
103 | lambda { |request| request.path_info.reverse }
104 | @store.cache_key(request).must_equal 'tset/'
105 | end
106 |
107 | it "allows custom cache keys from class" do
108 | request = mock_request('/test', {})
109 | request.env['rack-cache.cache_key'] = Class.new do
110 | def self.call(request); request.path_info.reverse end
111 | end
112 | @store.cache_key(request).must_equal 'tset/'
113 | end
114 |
115 | it 'does not blow up when given a non-marhsalable object with an ALL_CAPS key' do
116 | store_simple_entry('/bad', { 'SOME_THING' => Proc.new {} })
117 | end
118 |
119 | it 'supports a ttl parameter for #write' do
120 | @store.write('/test', [[{},{}],[{},{}]], 0)
121 | tuples = @store.read('/test')
122 | tuples.must_equal [ [{},{}], [{},{}] ]
123 | end
124 |
125 | # Abstract methods ===========================================================
126 |
127 | it 'stores a cache entry' do
128 | cache_key = store_simple_entry
129 | refute @store.read(cache_key).empty?
130 | end
131 |
132 | it 'can handle objects that can only be read once' do
133 | io = StringIO.new("TEST")
134 | store_simple_entry nil, nil, io
135 |
136 | # was stored correctly in entity store
137 | key = @response.headers.fetch('x-content-digest')
138 | @entity_store.read(key).must_equal "TEST"
139 |
140 | # io is closed, so that file descriptors are released
141 | assert io.closed?
142 |
143 | # rendered body is the same content as the cache
144 | @response.body.to_a.must_equal ["TEST"]
145 | end
146 |
147 | it 'sets the x-content-digest response header before storing' do
148 | cache_key = store_simple_entry
149 | req, res = @store.read(cache_key).first
150 | res['x-content-digest'].must_equal 'a94a8fe5ccb19ba61c4c0873d391e987982fbbd3'
151 | end
152 |
153 | it 'finds a stored entry with #lookup' do
154 | store_simple_entry
155 | response = @store.lookup(@request, @entity_store)
156 | refute response.nil?
157 | response.class.must_equal Rack::Cache::Response
158 | end
159 |
160 | it 'does not find an entry with #lookup when none exists' do
161 | req = mock_request('/test', {'HTTP_FOO' => 'Foo', 'HTTP_BAR' => 'Bar'})
162 | @store.lookup(req, @entity_store).must_be_nil
163 | end
164 |
165 | it "canonizes urls for cache keys" do
166 | store_simple_entry(path='/test?x=y&p=q')
167 |
168 | hits_req = mock_request(path, {})
169 | miss_req = mock_request('/test?p=x', {})
170 |
171 | @store.lookup(hits_req, @entity_store).wont_equal nil
172 | @store.lookup(miss_req, @entity_store).must_be_nil
173 | end
174 |
175 | it 'does not find an entry with #lookup when the body does not exist' do
176 | store_simple_entry
177 | refute @response.headers['x-content-digest'].nil?
178 | @entity_store.purge(@response.headers['x-content-digest'])
179 | @store.lookup(@request, @entity_store).must_be_nil
180 | end
181 |
182 | it 'purges meta store entry when the body does not exist' do
183 | store_simple_entry
184 | @entity_store.purge(@response.headers['x-content-digest'])
185 | mock = Minitest::Mock.new
186 | mock.expect :call, nil, [@store.cache_key(@request)]
187 | @store.stub(:purge, mock) do
188 | @store.lookup(@request, @entity_store)
189 | end
190 | mock.verify
191 | end
192 |
193 | it 'purges meta store entry when the entry does not contain the digest header' do
194 | cache_key = store_simple_entry
195 | meta_entry = @store.read(cache_key)
196 | meta_entry.grep(Array).flatten.each { |h| h.is_a?(Hash) && h.delete('x-content-digest') }
197 | @store.write(cache_key, meta_entry)
198 | mock = Minitest::Mock.new
199 | mock.expect :call, nil, [@store.cache_key(@request)]
200 | @store.stub(:purge, mock) do
201 | @store.lookup(@request, nil)
202 | end
203 | mock.verify
204 | end
205 |
206 | it 'warns once if purge is not implemented' do
207 | store_simple_entry
208 | assert @response.headers['x-content-digest']
209 | @entity_store.purge(@response.headers['x-content-digest'])
210 | def @store.purge(key); raise NotImplementedError; end
211 | @store.lookup(@request, @entity_store).must_be_nil
212 | @store.lookup(@request, @entity_store).must_be_nil
213 | end
214 |
215 | it 'restores response headers properly with #lookup' do
216 | store_simple_entry
217 | response = @store.lookup(@request, @entity_store)
218 | response.headers.
219 | must_equal @response.headers.merge('content-length' => '4')
220 | end
221 |
222 | it 'restores response body from entity store with #lookup' do
223 | store_simple_entry
224 | response = @store.lookup(@request, @entity_store)
225 | body = '' ; response.body.each {|p| body << p}
226 | body.must_equal 'test'
227 | end
228 |
229 | it 'invalidates meta and entity store entries with #invalidate' do
230 | store_simple_entry
231 | @store.invalidate(@request, @entity_store)
232 | response = @store.lookup(@request, @entity_store)
233 | response.class.must_equal Rack::Cache::Response
234 | refute response.fresh?
235 | end
236 |
237 | it 'succeeds quietly when #invalidate called with no matching entries' do
238 | req = mock_request('/test', {})
239 | @store.invalidate(req, @entity_store)
240 | @store.lookup(@request, @entity_store).must_be_nil
241 | end
242 |
243 | it 'does not remove response x-status with #invalidate' do
244 | request = mock_request('/test', {})
245 | # non-fresh response
246 | response = mock_response(200, {'Expires' => (Time.now - 3600).httpdate, 'vary' => 'Foo'}, ['test'])
247 | cache_key = @store.store(request, response, @entity_store)
248 | # fresh response
249 | response = mock_response(200, {'Expires' => (Time.now + 3600).httpdate, 'vary' => 'Bar'}, ['test'])
250 | @store.store(request, response, @entity_store)
251 |
252 | @store.invalidate(request, @entity_store)
253 | @store.read(cache_key).each do |_, res|
254 | res.must_include 'x-status'
255 | end
256 | end
257 |
258 | it 'gracefully degrades if the cache store stops working' do
259 | @store = Class.new(Rack::Cache::MetaStore) do
260 | def purge(*args); nil end
261 | def read(*args); [] end
262 | def write(*args); nil end
263 | end.new
264 | @entity_store = Class.new(Rack::Cache::EntityStore) do
265 | def exists?(*args); false end
266 | def open(*args); nil end
267 | def read(*args); nil end
268 | def write(*args); nil end
269 | def purge(*args); nil end
270 | end.new
271 |
272 | request = mock_request('/test', {})
273 | response = mock_response(200, {}, ['test'])
274 | @store.store(request, response, @entity_store)
275 | response.body.must_equal ['test']
276 | end
277 |
278 | # Vary =======================================================================
279 |
280 | %w[Vary vary].each do |vary|
281 | it 'does not return entries that Vary with #lookup' do
282 | req1 = mock_request('/test', {'HTTP_FOO' => 'Foo', 'HTTP_BAR' => 'Bar'})
283 | req2 = mock_request('/test', {'HTTP_FOO' => 'Bling', 'HTTP_BAR' => 'Bam'})
284 | res = mock_response(200, {vary => 'Foo Bar'}, ['test'])
285 | @store.store(req1, res, @entity_store)
286 |
287 | @store.lookup(req2, @entity_store).must_be_nil
288 | end
289 |
290 | it 'stores multiple responses for each Vary combination' do
291 | req1 = mock_request('/test', {'HTTP_FOO' => 'Foo', 'HTTP_BAR' => 'Bar'})
292 | res1 = mock_response(200, {vary => 'Foo Bar'}, ['test 1'])
293 | key = @store.store(req1, res1, @entity_store)
294 |
295 | req2 = mock_request('/test', {'HTTP_FOO' => 'Bling', 'HTTP_BAR' => 'Bam'})
296 | res2 = mock_response(200, {vary => 'Foo Bar'}, ['test 2'])
297 | @store.store(req2, res2, @entity_store)
298 |
299 | req3 = mock_request('/test', {'HTTP_FOO' => 'Baz', 'HTTP_BAR' => 'Boom'})
300 | res3 = mock_response(200, {vary => 'Foo Bar'}, ['test 3'])
301 | @store.store(req3, res3, @entity_store)
302 |
303 | slurp(@store.lookup(req3, @entity_store).body).must_equal 'test 3'
304 | slurp(@store.lookup(req1, @entity_store).body).must_equal 'test 1'
305 | slurp(@store.lookup(req2, @entity_store).body).must_equal 'test 2'
306 |
307 | @store.read(key).length.must_equal 3
308 | end
309 |
310 | it 'overwrites non-varying responses with #store' do
311 | req1 = mock_request('/test', {'HTTP_FOO' => 'Foo', 'HTTP_BAR' => 'Bar'})
312 | res1 = mock_response(200, {vary => 'Foo Bar'}, ['test 1'])
313 | key = @store.store(req1, res1, @entity_store)
314 | slurp(@store.lookup(req1, @entity_store).body).must_equal 'test 1'
315 |
316 | req2 = mock_request('/test', {'HTTP_FOO' => 'Bling', 'HTTP_BAR' => 'Bam'})
317 | res2 = mock_response(200, {vary => 'Foo Bar'}, ['test 2'])
318 | @store.store(req2, res2, @entity_store)
319 | slurp(@store.lookup(req2, @entity_store).body).must_equal 'test 2'
320 |
321 | req3 = mock_request('/test', {'HTTP_FOO' => 'Foo', 'HTTP_BAR' => 'Bar'})
322 | res3 = mock_response(200, {vary => 'Foo Bar'}, ['test 3'])
323 | @store.store(req3, res3, @entity_store)
324 | slurp(@store.lookup(req1, @entity_store).body).must_equal 'test 3'
325 |
326 | @store.read(key).length.must_equal 2
327 | end
328 | end
329 |
330 | # Age ====================================================================
331 |
332 | %w[Age age].each do |age|
333 | it 'removes the Age response header before storing' do
334 | response = mock_response(200, {age => "100"}, ['foo'])
335 | @store.store(@request, response, @entity_store)
336 | @store.lookup(@request, @entity_store).headers['age'].must_be_nil
337 | end
338 | end
339 |
340 | # TTL ====================================================================
341 |
342 | context 'logging writes' do
343 | it 'passes a TTL to the stores is use_native_ttl is truthy' do
344 | request = mock_request('/test', { 'rack-cache.use_native_ttl' => true })
345 | response = mock_response(200, {'cache-control' => 'max-age=42'}, ['foo'])
346 |
347 | @entity_store.expects(:write).with(['foo'], 42).returns ['foobar']
348 | @store.expects(:write).with(anything, anything, 42).returns ['foobar']
349 |
350 | @store.store(request, response, @entity_store)
351 | end
352 | end
353 | end
354 | end
355 | end
356 |
357 | describe Rack::Cache::MetaStore do
358 | {read: [1], write: [1,2], purge: [1]}.each do |method, args|
359 | it "has not implemented #{method}" do
360 | assert_raises NotImplementedError do
361 | Rack::Cache::MetaStore.new.send(method, *args)
362 | end
363 | end
364 | end
365 |
366 | describe 'Heap' do
367 | before do
368 | @store = Rack::Cache::MetaStore::Heap.new
369 | @entity_store = Rack::Cache::EntityStore::Heap.new
370 | end
371 | include RackCacheMetaStoreImplementation
372 | end
373 |
374 | describe 'Disk' do
375 | before do
376 | @temp_dir = create_temp_directory
377 | @store = Rack::Cache::MetaStore::Disk.new("#{@temp_dir}/meta")
378 | @entity_store = Rack::Cache::EntityStore::Disk.new("#{@temp_dir}/entity")
379 | end
380 | after do
381 | remove_entry_secure @temp_dir
382 | end
383 | include RackCacheMetaStoreImplementation
384 | end
385 |
386 | need_memcached 'metastore tests' do
387 | describe 'MemCached' do
388 | before do
389 | @temp_dir = create_temp_directory
390 | $memcached.flush
391 | @store = Rack::Cache::MetaStore::MemCached.new($memcached)
392 | @entity_store = Rack::Cache::EntityStore::Heap.new
393 | end
394 | include RackCacheMetaStoreImplementation
395 | end
396 |
397 | describe 'options parsing' do
398 | before do
399 | uri = URI.parse("memcached://#{ENV['MEMCACHED']}/meta_ns1?show_backtraces=true")
400 | @memcached_metastore = Rack::Cache::MetaStore::MemCached.resolve uri
401 | end
402 |
403 | it 'passes options from uri' do
404 | @memcached_metastore.cache.instance_variable_get(:@options)[:show_backtraces].must_equal true
405 | end
406 |
407 | it 'takes namespace into account' do
408 | @memcached_metastore.cache.instance_variable_get(:@options)[:prefix_key].must_equal 'meta_ns1'
409 | end
410 | end
411 | end
412 |
413 | need_dalli 'metastore tests' do
414 | describe 'Dalli' do
415 | before do
416 | @temp_dir = create_temp_directory
417 | $dalli.flush_all
418 | @store = Rack::Cache::MetaStore::Dalli.new($dalli)
419 | @entity_store = Rack::Cache::EntityStore::Heap.new
420 | end
421 | include RackCacheMetaStoreImplementation
422 | end
423 |
424 | describe 'options parsing' do
425 | before do
426 | uri = URI.parse("memcached://#{ENV['MEMCACHED']}/meta_ns1?show_backtraces=true")
427 | @dalli_metastore = Rack::Cache::MetaStore::Dalli.resolve uri
428 | end
429 |
430 | it 'passes options from uri' do
431 | @dalli_metastore.cache.instance_variable_get(:@options)[:show_backtraces].must_equal true
432 | end
433 |
434 | it 'takes namespace into account' do
435 | @dalli_metastore.cache.instance_variable_get(:@options)[:namespace].must_equal 'meta_ns1'
436 | end
437 | end
438 | end
439 |
440 | need_java 'entity store testing' do
441 | module Rack::Cache::AppEngine
442 | module MC
443 | class << (Service = {})
444 | def contains(key); include?(key); end
445 | def get(key); self[key]; end;
446 | def put(key, value, ttl = nil)
447 | self[key] = value
448 | end
449 | end
450 | end
451 | end
452 |
453 | describe 'GAEStore' do
454 | before :each do
455 | Rack::Cache::AppEngine::MC::Service.clear
456 | @store = Rack::Cache::MetaStore::GAEStore.new
457 | @entity_store = Rack::Cache::EntityStore::Heap.new
458 | end
459 | include RackCacheMetaStoreImplementation
460 | end
461 | end
462 | end
463 |
--------------------------------------------------------------------------------
/test/options_test.rb:
--------------------------------------------------------------------------------
1 | require_relative 'test_helper'
2 | require 'rack/cache/options'
3 |
4 | module Rack::Cache::Options
5 | option_accessor :foo
6 | end
7 |
8 | class MockOptions
9 | include Rack::Cache::Options
10 | def initialize
11 | @env = nil
12 | initialize_options
13 | end
14 | end
15 |
16 | describe Rack::Cache::Options do
17 | before { @options = MockOptions.new }
18 |
19 | describe '#set' do
20 | it 'sets a Symbol option as rack-cache.symbol' do
21 | @options.set :bar, 'baz'
22 | @options.options['rack-cache.bar'].must_equal 'baz'
23 | end
24 |
25 | it 'sets a String option as string' do
26 | @options.set 'foo.bar', 'bling'
27 | @options.options['foo.bar'].must_equal 'bling'
28 | end
29 |
30 | it 'sets all key/value pairs when given a Hash' do
31 | @options.set :foo => 'bar', :bar => 'baz', 'foo.bar' => 'bling'
32 | @options.foo.must_equal 'bar'
33 | @options.options['rack-cache.bar'].must_equal 'baz'
34 | @options.options['foo.bar'].must_equal 'bling'
35 | end
36 | end
37 |
38 | it 'makes options declared with option_accessor available as attributes' do
39 | @options.set :foo, 'bar'
40 | @options.foo.must_equal 'bar'
41 | end
42 |
43 | it 'allows setting multiple options via assignment' do
44 | @options.options = { :foo => 'bar', :bar => 'baz', 'foo.bar' => 'bling' }
45 | @options.foo.must_equal 'bar'
46 | @options.options['foo.bar'].must_equal 'bling'
47 | @options.options['rack-cache.bar'].must_equal 'baz'
48 | end
49 |
50 | it "allows storing the value as a block" do
51 | block = Proc.new { "bar block" }
52 | @options.set(:foo, &block)
53 | @options.options['rack-cache.foo'].must_equal block
54 | end
55 |
56 | it 'allows the cache key generator to be configured' do
57 | assert @options.respond_to? :cache_key
58 | assert @options.respond_to? :cache_key=
59 | end
60 |
61 | it 'allows the meta store to be configured' do
62 | assert @options.respond_to? :metastore
63 | assert @options.respond_to? :metastore=
64 | refute @options.metastore.nil?
65 | end
66 |
67 | it 'allows the entity store to be configured' do
68 | assert @options.respond_to? :entitystore
69 | assert @options.respond_to? :entitystore=
70 | refute @options.entitystore.nil?
71 | end
72 |
73 | it 'allows log verbosity to be configured' do
74 | assert @options.respond_to? :verbose
75 | assert @options.respond_to? :verbose=
76 | assert @options.respond_to? :verbose?
77 | refute @options.verbose.nil?
78 | end
79 | end
80 |
--------------------------------------------------------------------------------
/test/pony.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rack/rack-cache/5261d91b210735a5a79367ff9faebde2dea28788/test/pony.jpg
--------------------------------------------------------------------------------
/test/request_test.rb:
--------------------------------------------------------------------------------
1 | require_relative 'test_helper'
2 | require 'rack/cache/request'
3 |
4 | describe Rack::Cache::Request do
5 | it 'is marked as no_cache when the cache-control header includes the no-cache directive' do
6 | request = Rack::Cache::Request.new('HTTP_CACHE_CONTROL' => 'public, no-cache')
7 | assert request.no_cache?
8 | end
9 |
10 | it 'is marked as no_cache when request should not be loaded from cache' do
11 | request = Rack::Cache::Request.new('HTTP_PRAGMA' => 'no-cache')
12 | assert request.no_cache?
13 | end
14 |
15 | it 'is not marked as no_cache when neither no-cache directive is specified' do
16 | request = Rack::Cache::Request.new('HTTP_CACHE_CONTROL' => 'public')
17 | refute request.no_cache?
18 | end
19 | end
20 |
--------------------------------------------------------------------------------
/test/response_test.rb:
--------------------------------------------------------------------------------
1 | require_relative 'test_helper'
2 |
3 | describe Rack::Cache::Response do
4 | before do
5 | @now = Time.httpdate(Time.now.httpdate)
6 | @one_hour_ago = Time.httpdate((Time.now - (60**2)).httpdate)
7 | @one_hour_later = Time.httpdate((Time.now + (60**2)).httpdate)
8 | @res = Rack::Cache::Response.new(200, {'date' => @now.httpdate}, [])
9 | end
10 |
11 | after do
12 | @now, @res, @one_hour_ago = nil
13 | end
14 |
15 | it 'marks Rack tuples with string typed statuses as cacheable' do
16 | @res = Rack::Cache::Response.new('200',{'date' => @now.httpdate},[])
17 | @res.headers['expires'] = @one_hour_later.httpdate
18 | assert @res.cacheable?
19 | end
20 |
21 | it 'responds to #to_a with a Rack response tuple' do
22 | assert @res.respond_to? :to_a
23 | @res.to_a.must_equal [200, {'date' => @now.httpdate}, []]
24 | end
25 |
26 | describe '#cache_control' do
27 | it 'handles multiple name=value pairs' do
28 | @res.headers['cache-control'] = 'max-age=600, max-stale=300, min-fresh=570'
29 | @res.cache_control['max-age'].must_equal '600'
30 | @res.cache_control['max-stale'].must_equal '300'
31 | @res.cache_control['min-fresh'].must_equal '570'
32 | end
33 | it 'removes the header when given an empty hash' do
34 | @res.headers['cache-control'] = 'max-age=600, must-revalidate'
35 | @res.cache_control['max-age'].must_equal '600'
36 | @res.cache_control = {}
37 | @res.headers.wont_include 'cache-control'
38 | end
39 | end
40 |
41 | describe '#validateable?' do
42 | it 'is true when last-modified header present' do
43 | @res = Rack::Cache::Response.new(200, {'last-modified' => @one_hour_ago.httpdate}, [])
44 | assert @res.validateable?
45 | end
46 | it 'is true when etag header present' do
47 | @res = Rack::Cache::Response.new(200, {'etag' => '"12345"'}, [])
48 | assert @res.validateable?
49 | end
50 | it 'is false when no validator is present' do
51 | @res = Rack::Cache::Response.new(200, {}, [])
52 | refute @res.validateable?
53 | end
54 | end
55 |
56 | describe '#date' do
57 | it 'uses the Date header if present and parseable' do
58 | @res = Rack::Cache::Response.new(200, {'date' => @one_hour_ago.httpdate}, [])
59 | @res.date.must_equal @one_hour_ago
60 | end
61 | it 'returns the current time if present but not parseable' do
62 | @res = Rack::Cache::Response.new(200, {'date' => "Jun, 30 Mon 2014 20:10:46 GMT"}, [])
63 | @res.date.to_i.must_be_close_to Time.now.to_i, 1
64 | end
65 | it 'uses the current time when no Date header present' do
66 | @res = Rack::Cache::Response.new(200, {}, [])
67 | @res.date.to_i.must_be_close_to Time.now.to_i, 1
68 | end
69 | it 'returns the correct date when the header is modified directly' do
70 | @res = Rack::Cache::Response.new(200, { 'date' => @one_hour_ago.httpdate }, [])
71 | @res.date.must_equal @one_hour_ago
72 | @res.headers['date'] = @now.httpdate
73 | @res.date.must_equal @now
74 | end
75 | end
76 |
77 | describe '#max_age' do
78 | it 'uses r-maxage cache control directive when present' do
79 | @res.headers['cache-control'] = 's-maxage=600, max-age=0, r-maxage=100'
80 | @res.max_age.must_equal 100
81 | end
82 | it 'uses s-maxage cache control when no r-maxage directive present' do
83 | @res.headers['cache-control'] = 's-maxage=600, max-age=0'
84 | @res.max_age.must_equal 600
85 | end
86 | it 'falls back to max-age when no r/s-maxage directive present' do
87 | @res.headers['cache-control'] = 'max-age=600'
88 | @res.max_age.must_equal 600
89 | end
90 | it 'falls back to expires when no max-age or r/s-maxage directive present' do
91 | @res.headers['cache-control'] = 'must-revalidate'
92 | @res.headers['expires'] = @one_hour_later.httpdate
93 | @res.max_age.must_equal 60 ** 2
94 | end
95 | it 'gives a #max_age of nil when no freshness information available' do
96 | @res.max_age.must_be_nil
97 | end
98 | end
99 |
100 | describe '#private=' do
101 | it 'adds the private cache-control directive when set true' do
102 | @res.headers['cache-control'] = 'max-age=100'
103 | @res.private = true
104 | @res.headers['cache-control'].split(', ').sort.
105 | must_equal ['max-age=100', 'private']
106 | end
107 | it 'removes the public cache-control directive' do
108 | @res.headers['cache-control'] = 'public, max-age=100'
109 | @res.private = true
110 | @res.headers['cache-control'].split(', ').sort.
111 | must_equal ['max-age=100', 'private']
112 | end
113 | end
114 |
115 | describe '#expire!' do
116 | it 'sets the Age to be equal to the max-age' do
117 | @res.headers['cache-control'] = 'max-age=100'
118 | @res.expire!
119 | @res.headers['age'].must_equal '100'
120 | end
121 | it 'sets the Age to be equal to the r-maxage when the three max-age and r/s-maxage present' do
122 | @res.headers['cache-control'] = 'max-age=100, s-maxage=500, r-maxage=900'
123 | @res.expire!
124 | @res.headers['age'].must_equal '900'
125 | end
126 | it 'sets the Age to be equal to the s-maxage when both max-age and s-maxage present' do
127 | @res.headers['cache-control'] = 'max-age=100, s-maxage=500'
128 | @res.expire!
129 | @res.headers['age'].must_equal '500'
130 | end
131 | it 'does nothing when the response is already stale/expired' do
132 | @res.headers['cache-control'] = 'max-age=5, s-maxage=500'
133 | @res.headers['age'] = '1000'
134 | @res.expire!
135 | @res.headers['age'].must_equal '1000'
136 | end
137 | it 'does nothing when the response does not include freshness information' do
138 | @res.expire!
139 | @res.headers.wont_include 'age'
140 | end
141 | end
142 |
143 | describe '#ttl' do
144 | it 'is nil when no expires or cache-control headers present' do
145 | @res.ttl.must_be_nil
146 | end
147 | it 'uses the expires header when no max-age is present' do
148 | @res.headers['expires'] = (@res.now + (60**2)).httpdate
149 | @res.ttl.must_be_close_to(60**2, 1)
150 | end
151 | it 'returns negative values when expires is in part' do
152 | @res.ttl.must_be_nil
153 | @res.headers['expires'] = @one_hour_ago.httpdate
154 | @res.ttl.must_be :<, 0
155 | end
156 | it 'uses the cache-control max-age value when present' do
157 | @res.headers['cache-control'] = 'max-age=60'
158 | @res.ttl.must_be_close_to(60, 1)
159 | end
160 | end
161 |
162 | describe '#vary' do
163 | it 'is nil when no Vary header is present' do
164 | @res.vary.must_be_nil
165 | end
166 | it 'returns the literal value of the Vary header' do
167 | @res.headers['vary'] = 'Foo Bar Baz'
168 | @res.vary.must_equal 'Foo Bar Baz'
169 | end
170 | it 'can be checked for existence using the #vary? method' do
171 | assert @res.respond_to? :vary?
172 | refute @res.vary?
173 | @res.headers['vary'] = '*'
174 | assert @res.vary?
175 | end
176 | end
177 |
178 | describe '#vary_header_names' do
179 | it 'returns an empty Array when no Vary header is present' do
180 | assert @res.vary_header_names.empty?
181 | end
182 | it 'parses a single header name value' do
183 | @res.headers['vary'] = 'accept-language'
184 | @res.vary_header_names.must_equal ['accept-language']
185 | end
186 | it 'parses multiple header name values separated by spaces' do
187 | @res.headers['vary'] = 'accept-language user-agent x-foo'
188 | @res.vary_header_names.must_equal \
189 | ['accept-language', 'user-agent', 'x-foo']
190 | end
191 |
192 | it 'parses multiple header name values separated by commas' do
193 | @res.headers['vary'] = 'accept-language,user-agent, x-foo'
194 | @res.vary_header_names.must_equal \
195 | ['accept-language', 'user-agent', 'x-foo']
196 | end
197 | end
198 |
199 | describe '#expires' do
200 | it 'returns nil if there is no expires header' do
201 | @res.headers['expires'] = nil
202 | @res.expires.must_be_nil
203 | end
204 |
205 | it 'returns a Time if the expires header is parseable' do
206 | @res.headers['expires'] = "Mon, 30 Jun 2014 20:10:46 GMT"
207 | @res.expires.must_equal Time.at(1404159046)
208 | end
209 |
210 | it 'returns nil if the expires header is not parseable' do
211 | @res.headers['expires'] = "Jun, 30 Mon 2014 20:10:46 GMT"
212 | @res.expires.must_be_nil
213 | end
214 | end
215 | end
216 |
--------------------------------------------------------------------------------
/test/storage_test.rb:
--------------------------------------------------------------------------------
1 | require_relative 'test_helper'
2 | require 'rack/cache/storage'
3 |
4 | describe Rack::Cache::Storage do
5 | before do
6 | @storage = Rack::Cache::Storage.new
7 | end
8 |
9 | it "fails when an unknown URI scheme is provided" do
10 | lambda { @storage.resolve_metastore_uri('foo:/') }.must_raise
11 | end
12 |
13 | it "passes options to the underlying stores" do
14 | @storage
15 | .resolve_metastore_uri('heap:/', foo: 'bar')
16 | .instance_variable_get('@options')[:foo]
17 | .must_equal('bar')
18 | @storage
19 | .resolve_entitystore_uri('heap:/', foo: 'bar')
20 | .instance_variable_get('@options')[:foo]
21 | .must_equal('bar')
22 | end
23 |
24 | it "creates a new MetaStore for URI if none exists" do
25 | @storage.resolve_metastore_uri('heap:/').
26 | must_be_kind_of Rack::Cache::MetaStore
27 | end
28 |
29 | it "returns an existing MetaStore instance for URI that exists" do
30 | store = @storage.resolve_metastore_uri('heap:/')
31 | @storage.resolve_metastore_uri('heap:/').must_equal store
32 | end
33 |
34 | it "creates a new EntityStore for URI if none exists" do
35 | @storage.resolve_entitystore_uri('heap:/').
36 | must_be_kind_of Rack::Cache::EntityStore
37 | end
38 |
39 | it "returns an existing EntityStore instance for URI that exists" do
40 | store = @storage.resolve_entitystore_uri('heap:/')
41 | @storage.resolve_entitystore_uri('heap:/').must_equal store
42 | end
43 |
44 | it "clears all URI -> store mappings with #clear" do
45 | meta = @storage.resolve_metastore_uri('heap:/')
46 | entity = @storage.resolve_entitystore_uri('heap:/')
47 | @storage.clear
48 | @storage.resolve_metastore_uri('heap:/').object_id.wont_equal meta.object_id
49 | @storage.resolve_entitystore_uri('heap:/').object_id.wont_equal entity.object_id
50 | end
51 |
52 | describe 'Noop Store URIs' do
53 | it "resolves Noop meta store URIs" do
54 | @storage.resolve_entitystore_uri('noop:/').
55 | must_be_kind_of Rack::Cache::EntityStore::Noop
56 | end
57 | end
58 |
59 | describe 'Heap Store URIs' do
60 | %w[heap:/ mem:/].each do |uri|
61 | it "resolves #{uri} meta store URIs" do
62 | @storage.resolve_metastore_uri(uri).
63 | must_be_kind_of Rack::Cache::MetaStore
64 | end
65 | it "resolves #{uri} entity store URIs" do
66 | @storage.resolve_entitystore_uri(uri).
67 | must_be_kind_of Rack::Cache::EntityStore
68 | end
69 | end
70 | end
71 |
72 | describe 'Disk Store URIs' do
73 | before do
74 | @temp_dir = create_temp_directory
75 | end
76 |
77 | after do
78 | remove_entry_secure @temp_dir
79 | @temp_dir = nil
80 | end
81 |
82 | %w[file: disk:].each do |uri|
83 | it "resolves #{uri} meta store URIs" do
84 | @storage.resolve_metastore_uri(uri + @temp_dir).
85 | must_be_kind_of Rack::Cache::MetaStore
86 | end
87 |
88 | it "resolves #{uri} entity store URIs" do
89 | @storage.resolve_entitystore_uri(uri + @temp_dir).
90 | must_be_kind_of Rack::Cache::EntityStore
91 | end
92 | end
93 | end
94 |
95 | if have_memcached?
96 |
97 | describe 'MemCache Store URIs' do
98 | %w[memcache: memcached:].each do |scheme|
99 | it "resolves #{scheme} meta store URIs" do
100 | uri = scheme + '//' + ENV['MEMCACHED']
101 | @storage.resolve_metastore_uri(uri).
102 | must_be_kind_of Rack::Cache::MetaStore
103 | end
104 |
105 | it "resolves #{scheme} entity store URIs" do
106 | uri = scheme + '//' + ENV['MEMCACHED']
107 | @storage.resolve_entitystore_uri(uri).
108 | must_be_kind_of Rack::Cache::EntityStore
109 | end
110 | end
111 |
112 | it 'supports namespaces in memcached: URIs' do
113 | uri = "memcached://" + ENV['MEMCACHED'] + "/namespace"
114 | @storage.resolve_metastore_uri(uri).
115 | must_be_kind_of Rack::Cache::MetaStore
116 | end
117 | end
118 | end
119 | end
120 |
--------------------------------------------------------------------------------
/test/test_helper.rb:
--------------------------------------------------------------------------------
1 | require 'bundler/setup'
2 | require 'pp'
3 | require 'tmpdir'
4 | require 'stringio'
5 |
6 | [STDOUT, STDERR].each { |io| io.sync = true }
7 |
8 | require 'maxitest/global_must'
9 | require 'maxitest/autorun'
10 | require 'mocha/minitest'
11 |
12 | # Set the MEMCACHED environment variable as follows to enable testing
13 | # of the MemCached meta and entity stores.
14 | ENV['MEMCACHED'] ||= 'localhost:11211'
15 | $memcached = nil
16 | $dalli = nil
17 |
18 | def have_memcached?(server=ENV['MEMCACHED'])
19 | return $memcached unless $memcached.nil?
20 |
21 | # silence warnings from memcached
22 | begin
23 | v, $VERBOSE = $VERBOSE, nil
24 | require 'memcached'
25 | ensure
26 | $VERBOSE = v
27 | end
28 |
29 | $memcached = Memcached.new(server)
30 | $memcached.set('ping', '')
31 | true
32 | rescue LoadError => boom
33 | warn "memcached library not available. related tests will be skipped."
34 | $memcached = false
35 | false
36 | rescue => boom
37 | warn "memcached not working. related tests will be skipped."
38 | $memcached = false
39 | false
40 | end
41 |
42 | have_memcached?
43 |
44 | def have_dalli?(server=ENV['MEMCACHED'])
45 | return $dalli unless $dalli.nil?
46 | require 'dalli'
47 | $dalli = Dalli::Client.new(server)
48 | $dalli.set('ping', '')
49 | true
50 | rescue LoadError => boom
51 | warn "dalli library not available. related tests will be skipped."
52 | $dalli = false
53 | false
54 | rescue => boom
55 | warn "dalli not working. related tests will be skipped."
56 | $dalli = false
57 | false
58 | end
59 |
60 | have_dalli?
61 |
62 | def need_dalli(forwhat)
63 | yield if have_dalli?
64 | end
65 |
66 | def need_memcached(forwhat)
67 | yield if have_memcached?
68 | end
69 |
70 | def need_java(forwhat)
71 | yield if RUBY_PLATFORM =~ /java/
72 | end
73 |
74 | require 'rack/cache'
75 |
76 | # Methods for constructing downstream applications / response
77 | # generators.
78 | module CacheContextHelpers
79 | class FakeApp
80 | def initialize(status=200, headers={}, body=['Hello World'], bk)
81 | @status = status
82 | @headers = headers
83 | @body = body
84 | @bk = bk
85 | end
86 |
87 | def call(env)
88 | @called = true
89 | response = Rack::Response.new(@body, @status, @headers)
90 | request = Rack::Request.new(env)
91 | @bk.call(request, response) if @bk
92 | response.finish
93 | end
94 |
95 | def called?
96 | @called
97 | end
98 |
99 | def reset!
100 | @called = false
101 | end
102 | end
103 |
104 | # The Rack::Cache::Context instance used for the most recent
105 | # request.
106 | attr_reader :cache
107 |
108 | # An Array of Rack::Cache::Context instances used for each request, in
109 | # request order.
110 | attr_reader :caches
111 |
112 | # The Rack::Response instance result of the most recent request.
113 | attr_reader :response
114 |
115 | # An Array of Rack::Response instances for each request, in request order.
116 | attr_reader :responses
117 |
118 | # The backend application object.
119 | attr_reader :app
120 |
121 | def setup_cache_context
122 | # holds each Rack::Cache::Context
123 | @app = nil
124 |
125 | # each time a request is made, a clone of @cache_template is used
126 | # and appended to @caches.
127 | @cache_template = nil
128 | @cache = nil
129 | @caches = []
130 | @errors = StringIO.new
131 | @cache_config = nil
132 |
133 | @called = false
134 | @request = nil
135 | @response = nil
136 | @responses = []
137 |
138 | @storage = Rack::Cache::Storage.new
139 | end
140 |
141 | def teardown_cache_context
142 | @app, @cache_template, @cache, @caches, @called,
143 | @request, @response, @responses, @cache_config, @cache_prototype = nil
144 | end
145 |
146 | # A basic response with 200 status code and a tiny body.
147 | def respond_with(status=200, headers={}, body=['Hello World'], &bk)
148 | @app = FakeApp.new(status, headers, body, bk)
149 | end
150 |
151 | def cache_config(&block)
152 | @cache_config = block
153 | end
154 |
155 | def request(method, uri='/', opts={})
156 | opts = {
157 | 'rack.run_once' => true,
158 | 'rack.multithread' => false,
159 | 'rack.errors' => @errors,
160 | 'rack-cache.storage' => @storage
161 | }.merge(opts)
162 |
163 | fail 'response not specified (use respond_with)' if @app.nil?
164 | @app.reset! if @app.respond_to?(:reset!)
165 |
166 | @cache_prototype ||= Rack::Cache::Context.new(@app, &@cache_config)
167 | @cache = @cache_prototype.clone
168 | @caches << @cache
169 | @request = Rack::MockRequest.new(@cache)
170 | yield @cache if block_given?
171 | @response = @request.request(method.to_s.upcase, uri, opts)
172 | @responses << @response
173 | @response
174 | end
175 |
176 | def get(stem, env={}, &b)
177 | request(:get, stem, env, &b)
178 | end
179 |
180 | def head(stem, env={}, &b)
181 | request(:head, stem, env, &b)
182 | end
183 |
184 | def post(*args, &b)
185 | request(:post, *args, &b)
186 | end
187 | end
188 |
189 |
190 | module TestHelpers
191 | include FileUtils
192 | F = File
193 |
194 | @@temp_dir_count = 0
195 |
196 | def create_temp_directory
197 | @@temp_dir_count += 1
198 | path = F.join(Dir.tmpdir, "rack-cache-#{$$}-#{@@temp_dir_count}")
199 | mkdir_p path
200 | if block_given?
201 | yield path
202 | remove_entry_secure path
203 | end
204 | path
205 | end
206 |
207 | def create_temp_file(root, file, data='')
208 | path = F.join(root, file)
209 | mkdir_p F.dirname(path)
210 | F.open(path, 'w') { |io| io.write(data) }
211 | end
212 |
213 | end
214 |
215 | Minitest::Test.class_eval do
216 | include TestHelpers
217 | include CacheContextHelpers
218 | end
219 |
--------------------------------------------------------------------------------