rack-cache 0.2.0

data/doc/events.dot

@@ -0,0 +1,27 @@
+digraph cache_logic {
+  nodesep=1.25;
+  center=true;
+
+  node[fontname="Lucida Sans Unicode",labelloc=c,margin=0.10,0.03]
+  edge[fontname="Lucida Sans Unicode",fontcolor="#444444",labeldistance=20];
+
+  receive -> pass[label="uncacheable request",color=grey];
+  receive -> lookup[label="cacheable request"];
+
+  pass -> deliver[label="",color=grey];
+
+  lookup -> hit[label="fresh"];
+  lookup -> fetch[label="stale (needs validation)"];
+  lookup -> miss[label="uncached"];
+
+  hit -> deliver[label="sizzling"];
+  hit -> pass[label="bailing...",color=grey];
+
+  miss -> fetch[label=""];
+  miss -> pass[color=grey];
+
+  fetch -> store[label="cacheable"];
+  fetch -> deliver[label="not cacheable",color=grey];
+
+  store -> deliver[label="KTHX"];
+}

data/doc/faq.markdown

@@ -0,0 +1,133 @@
+Frequently Asked Questions
+==========================
+
+<p class='intro'>
+<strong>NOTE:</strong> This is a work in progress. Please send questions, comments, or
+suggestions to <a href="mailto:r@tomayko.com">r@tomayko.com</a>.
+</p>
+
+General
+-------
+
+
+<a class='hash' id='why-not-squid' href='#why-not-squid'>#</a>
+
+### Q: Why Rack::Cache? Why not Squid, Varnish, Perlbol, etc.?
+
+__Rack::Cache__ is often easier to setup as part of your existing Ruby
+application than a separate caching system. __Rack::Cache__ runs entirely inside
+your backend application processes - no separate / external process is required.
+This lets __Rack::Cache__ scale down to development environments and simple
+deployments very easily while not sacrificing the benefits of a standards-based
+approach to caching.
+
+
+<a class='hash' id='why-not-rails' href='#why-not-rails'>#</a>
+
+### Q: Why Rack::Cache? Why not use Rails/Merb/FrameworkX's caching system?
+
+__Rack::Cache__ takes a standards-based approach to caching that provides some
+benefits over framework-integrated systems.  It uses standard HTTP headers
+(`Expires`, `Cache-Control`, `Etag`, `Last-Modified`, etc.) to determine
+what/when to cache. Designing applications to support these standard HTTP
+mechanisms gives the benefit of being able to switch to a different HTTP
+cache implementation in the future.
+
+In addition, using a standards-based approach to caching creates a clear
+separation between application and caching logic. The application need only
+specify a basic set of information about the response and all decisions
+regarding how and when to cache is moved into the caching layer.
+
+
+<a class='hash' id='scale' href='#scale'>#</a>
+
+### Q: Will Rack::Cache make my app scale?
+
+No. Your design is the only thing that can make your app scale.
+
+Also, __Rack::Cache__ is not overly optimized for performance. The main goal of
+the project is to provide a portable, easy-to-configure, and standards-based
+caching solution for small to medium sized deployments. More sophisticated /
+performant caching systems (e.g., [Varnish][v], [Squid][s],
+[httpd/mod-cache][h]) may be more appropriate for large deployments with
+crazy-land throughput requirements.
+
+[v]: http://varnish.projects.linpro.no/
+[s]: http://www.squid-cache.org/
+[h]: http://httpd.apache.org/docs/2.0/mod/mod_cache.html
+
+
+Features
+--------
+
+
+<a class='hash' id='validation' href='#validation'>#</a>
+
+### Q: Does Rack::Cache support validation?
+
+Yes. Both freshness and validation-based caching is supported. A response
+will be cached if it has a freshness lifetime (e.g., `Expires` or
+`Cache-Control: max-age=N` headers) and/or includes a validator (e.g.,
+`Last-Modified` or `ETag` headers). When the cache hits and the response is
+fresh, it's delivered immediately without talking to the backend application;
+when the cache is stale, the cached response is validated using a conditional
+GET request.
+
+
+<a class='hash' id='fragments' href='#fragments'>#</a>
+
+### Q: Does Rack::Cache support fragment caching?
+
+Not really. __Rack::Cache__ deals with entire responses and doesn't know
+anything about how your application constructs them.
+
+However, something like [ESI](http://www.w3.org/TR/esi-lang) may be implemented
+in the future (likely as a separate Rack middleware component that could be
+situated upstream from Rack::Cache), which would allow applications to compose
+responses based on several "fragment resources". Each fragment would have its
+own cache policy.
+
+
+<a class='hash' id='manual-purge' href='#manual-purge'>#</a>
+
+### Q: How do I manually purge or expire a cached entry?
+
+Although planned, there is currently no mechanism for manually purging
+an entry stored in the cache.
+
+Note that using an `Expires` or `Cache-Control: max-age=N` header and relying on
+manual purge to invalidate cached entry can often be implemented more simply
+using efficient validation based caching (`Last-Modified`, `Etag`). Many web
+frameworks are based entirely on manual purge and do not support validation at
+the cache level.
+
+
+<a class='hash' id='efficient-validation' href='#efficient-validation'>#</a>
+
+### Q: What does "Efficient Validation" mean?
+
+It means that your application performs only the processing necessary to
+determine if a response is valid before sending a `304 Not Modified` in response
+to a conditional GET request.  Many applications that perform validation do so
+only after the entire response has been generated, which provides bandwidth
+savings but results in no CPU/IO savings.  Implementing validation efficiently
+can increase backend application throughput significantly when fronted by a
+validating caching system (like __Rack::Cache__).
+
+[Here's an example Rack application](http://gist.github.com/9395) that performs
+efficient validation.
+
+
+<a class='hash' id='orly' href='#orly'>#</a>
+
+### Q: Did you just make that up?
+
+Yes.
+
+
+<a class='hash' id='https' href='#https'>#</a>
+
+### Q: Can I do HTTPS with Rack::Cache?
+
+Sure. HTTPS is typically managed by a front-end web server so this isn't really
+relevant to Rack::Cache.

data/doc/index.markdown

@@ -0,0 +1,113 @@
+__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.
+
+  * Standards-based ([RFC 2616][rfc] / [Section 13][s13]).
+  * Freshness/expiration based caching
+  * Validation
+  * Vary Support
+  * Portable: 100% Ruby / works with any [Rack][]-enabled framework.
+  * [Configuration language][config] for advanced caching policies.
+  * Disk, memcached, and heap memory [storage backends][storage].
+
+Status
+------
+
+__Rack::Cache__ is a young and experimental project that is likely to
+change substantially and may not be wholly functional, consistent,
+fast, or correct. The current focus is on reaching basic compliance
+with RFC 2616 and providing good documentation.
+
+Installation
+------------
+
+    $ sudo gem install rack-cache
+
+Or, from a local working copy:
+
+    $ git clone git://github.com/rtomayko/rack-cache.git
+    $ rake package && sudo rake install
+
+Basic Usage
+-----------
+
+__Rack::Cache__ is implemented as a piece of [Rack][] middleware and can be used
+with any __Rack__-based application. If your application includes a rackup
+(`.ru`) file or uses __Rack::Builder__ to construct the application pipeline,
+simply `require` and `use` as follows:
+
+    require 'rack/cache'
+
+    use Rack::Cache,
+      :verbose     => true,
+      :metastore   => 'file:/var/cache/rack/meta'
+      :entitystore => 'file:/var/cache/rack/body'
+
+    run app
+
+Assuming you've designed your backend application to take advantage of HTTP's
+caching features, no further code or configuration is required for basic
+caching. More sophisticated stuff is possible with [Rack::Cache's Configuration
+Language][config].
+
+Advanced Usage
+--------------
+
+  * [Configuration Language Documentation][config] - How to customize cache
+    policy using the simple event-based configuration system.
+
+  * [Cache Storage Documentation][storage] - Detailed information on the various
+    storage implementations available in __Rack::Cache__ and how to choose the one
+    that's best for your application.
+
+  * [FAQ](./faq) - Frequently Asked Questions about __Rack::Cache__.
+
+  * [GitHub Repository](http://github.com/rtomayko/rack-cache/) - Get your
+    fork on.
+
+  * [RDoc API Documentation](./api/) - Mostly worthless if you just want to use
+    __Rack::Cache__ in your application but mildly insightful if you'd like to
+    get a feel for how the system has been put together; I recommend
+    [reading the source](http://github.com/rtomayko/rack-cache/master/lib/rack/cache).
+
+See Also
+--------
+
+The overall design of __Rack::Cache__ is based largely on the work of the
+internet standards community. The following resources provide a good starting
+point for exploring the basic concepts of HTTP caching:
+
+  * Mark Nottingham's [Caching Tutorial](http://www.mnot.net/cache_docs/),
+    especially the short section on
+    [How Web Caches Work](http://www.mnot.net/cache_docs/#WORK)
+
+  * Joe Gregorio's [Doing HTTP Caching Right](http://www.xml.com/lpt/a/1642)
+
+  * [RFC 2616](http://www.ietf.org/rfc/rfc2616.txt), especially
+    [Section 13, "Caching in HTTP"](http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html)
+
+__Rack::Cache__ takes (_liberally_) various concepts from
+[Varnish](http://varnish.projects.linpro.no/) and
+[Django's cache framework](http://docs.djangoproject.com/en/dev/topics/cache/).
+
+License
+-------
+
+__Rack::Cache__ is Copyright © 2008
+by [Ryan Tomayko](http://tomayko.com/about)
+and is provided under [the MIT license](./license)
+
+[config]:  ./configuration "Rack::Cache Configuration Language Documentation"
+[storage]: ./storage       "Rack::Cache Storage Documentation"
+
+[rfc]: http://tools.ietf.org/html/rfc2616
+  "RFC 2616 - Hypertext Transfer Protocol -- HTTP/1.1 [ietf.org]"
+
+[s13]: http://tools.ietf.org/html/rfc2616#section-13
+  "RFC 2616 / Section 13 Caching in HTTP"
+
+[rack]: http://rack.rubyforge.org/
+  "Rack: a Ruby Webserver Interface"
+
+[vcl]: http://tomayko.com/man/vcl
+  "VCL(7) -- Varnish Configuration Language Manual Page"

data/doc/layout.html.erb

@@ -0,0 +1,33 @@
+<!DOCTYPE html>
+<html lang='en'>
+  <head>
+    <meta http-equiv='Content-Type' content='text/html;charset=utf-8'>
+    <title>Rack::Cache <%= title %></title>
+    <link rel='stylesheet' href='rack-cache.css' type='text/css' media='all'>
+    <script type='text/javascript' src='http://code.jquery.com/jquery-1.2.3.js'></script>
+    <script type='text/javascript' src='http://tomayko.com/js/tomayko.js'></script>
+  </head>
+  <body>
+    <div id='container'>
+      <div id='header'>
+        <h1><a href="./">rack-cache</a></h1>
+        <p>
+          <a href="./configuration" title='Configuration Language Documentation'>Config</a> |
+          <a href="./storage" title='Cache Storage Documentation'>Storage</a> |
+          <a href="./faq" title='Frequently Asked Questions'>FAQ</a> |
+          <a href="./api/" title='Fucking Sucks.'>RDoc</a>
+        </p>
+      </div>
+      <div id='content'><%= content %></div>
+      <div id='footer'>
+        <p class='rights'>
+          Copyright
+          <a href="./license" rel="license">&copy;</a>
+          2003-2008
+          by
+          <a href='http://tomayko.com/about' rel='me author'>Ryan Tomayko</a>
+        </p>
+      </div>
+    </div>
+  </body>
+</html>

data/doc/license.markdown

@@ -0,0 +1,24 @@
+License (MIT)
+=============
+
+__Rack::Cache__ is Copyright © 2008
+by [Ryan Tomayko](http://tomayko.com/about)
+
+<pre class='license'>
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+</pre>

data/doc/rack-cache.css

@@ -0,0 +1,362 @@
+/* rack-cache.css
+ *---------------------------------------------------------------------------
+ * Copyright (C) 2005-08 Ryan Tomayko <r@tomayko.com>
+ */
+
+
+/* 18px base font size / 25px baseline */
+body {
+	font-size:112.5%;   /* 18px (probably) */
+	line-height:1.3888; /* 25px */
+	letter-spacing:-0.02em;
+	margin:0 10px;
+	font-family: 'lucida sans unicode', 'lucida grande',
+		helvetica, 'bitstream vera sans', sans-serif;
+	color:#556;
+	background-color:#fff;
+}
+
+#container {
+	max-width:45em;
+	margin:0 auto;
+}
+
+h1, h2, h3 {
+	font-family:georgia, 'bitstream vera sans serif', 'lucida grande',
+		helvetica, verdana, sans-serif;
+	font-weight:normal;
+	letter-spacing:-0.05em;
+	color:#000;
+}
+i, em {
+	font-style:italic;
+}
+b, strong {
+	font-weight:normal;
+	color:#000;
+}
+blockquote {
+	color:#555;
+}
+blockquote em {
+	color:#333;
+	font-style:italic;
+}
+blockquote strong {
+	color:#333;
+	font-weight: normal;
+}
+dt {
+	font-weight:bold;
+	color:#000;
+}
+tt, pre, code, samp, kbd {
+	font-family: consolas, 'lucida console', 'bitstream vera sans mono',
+		'courier new', monospace;
+	color: #000;
+}
+pre {
+	color:#333;
+	background-color:#f9f9f9;
+}
+code {
+	color:#007A00;
+}
+pre code {
+	color:#333;
+}
+pre.license {
+	border:0;
+	background:#fff;
+	padding:0;
+	font-size:1.1em;
+}
+a, a:link {
+	color:#023;
+	background:#eef;
+}
+a:visited {
+	color:#345;
+	background:#fff;
+}
+a:hover {
+	background:#ccf;
+	color:#000;
+	text-decoration:none;
+}
+
+
+/* TYPOGRAPHY */
+
+p, ul, ol, dl, pre, blockquote, table, form {
+	margin:1em 0;
+}
+dl {
+	margin-left:2em;
+}
+hr {
+	color:#eee;
+	background-color:#ccc;
+	border:0;
+	height:1px;
+	margin:1.5em 0;
+}
+blockquote {
+	font-size:0.83333em;  /* 15px */
+	line-height:1.66666;   /* 25px */
+	margin:1.2em 3em;
+	padding:0;
+}
+tt, pre, code, samp, kbd {
+	font-size: 16px;
+	line-height:1.1;
+}
+pre {
+	margin:1.5em 0;
+	padding:6px 4px 4px 6px;
+	border:1px solid #eee;
+	border-left-width:20px;
+	overflow:auto;
+}
+h1 {
+	font-size:2.3333em;      /* 42px */
+	line-height:1.1904;      /* 50px */
+	margin:0.5952em 0;       /* 25px */
+}
+h2 {
+	font-size:1.66666667em;  /* 30px */
+	line-height:1.2;         /* 36px */
+	margin:1em 0;
+}
+h3 {
+	font-size:1.33333333em;  /* 22px */
+	line-height:1.13636363;  /* 25px */
+	margin:1em 0;
+}
+h3 code{
+	font-size:0.95em;
+	color:#000;
+}
+h4 {
+	font-size:1em;
+	font-weight:bold;
+	line-height:1.5;
+	margin:1em 0;
+}
+p small {
+	font-size:0.8333;       /* 15px */
+	line-height:1.2;
+}
+
+/* Tables
+--------------------------------------------------------------------------- */
+
+table {
+	width:100%;
+	border-style:none;
+	border-color:#ddd;
+	padding:0;
+}
+
+th, td {
+	padding: 4px 10px 4px 5px;
+	border-style:solid;
+	border-color:#fff;
+}
+
+th {
+	font-weight: bold;
+	background: #eef;
+}
+
+td {
+	background: #f9f9f9;
+}
+
+tfoot {
+	font-style: italic;
+}
+
+caption {
+	background: #eee;
+}
+
+/* Header / Titling
+--------------------------------------------------------------------------- */
+
+#header {
+	text-align:left;
+	margin:1.5em auto 2em;
+	float:left;
+	width:100%;
+	padding-bottom:1.5em;
+	border-bottom:1px solid #777;
+}
+#header h1 {
+	font-family: 'lucida sans unicode', 'lucida grande',
+		helvetica, 'bitstream vera sans', sans-serif;
+	font-size:5em;
+	font-weight:bold;
+	line-height:1;
+	margin:0;
+	float:left;
+	color:#000;
+	letter-spacing:-0.08em;
+}
+#header h1 a, #header h1 a:link, #header h1 a:visited, #header h1 a:hover {
+	color:#000;
+	text-decoration:none;
+	background:transparent;
+}
+#header p {
+	margin: 0;
+	line-height:1.8;
+	color: #777;
+	text-transform:capitalize;
+	font-variant:small-caps;
+	float:right;
+}
+#header a, #header a:link, #header a:visited {
+	color:#445;
+	background:#fff;
+}
+#header a:hover {
+	background:#ccf;
+	color:#000;
+	text-decoration:none;
+}
+#content {
+	clear:both;
+}
+
+/* FOOTER */
+
+#footer {
+	clear:both;
+	color:#555;
+	font-size:0.88888888em;
+	line-height:1.5625;
+	border-top:1px solid #ddd;
+	padding:19px 0 0 0;
+	margin:40px 0 20px 0;
+	text-align:center;
+}
+#footer p {
+	margin:0;
+}
+#footer form {
+	float:right;
+}
+#footer input{
+	font-size:10px;
+}
+
+/* MISC HELPER STYLES */
+
+ul.clean, ol.clean {
+	list-style-type: none;
+	padding-left: 0;
+}
+.caps {
+	font-variant:small-caps;
+}
+.clear {
+	clear:both;
+}
+.left{
+	float:left;
+}
+.right{
+	float:right;
+}
+.center{
+	text-align:center;
+}
+.intro {
+	font-size:0.833333em;  /* 15px */
+	line-height:1.666667;  /* 25px */
+	border:1px solid #ccc;
+	padding:0.5em;
+	font-style:italic;
+	color:#555;
+}
+a.hash,
+a.hash:link,
+a.hash:visited {
+	display:block;
+	float:right;
+	background:#fff;
+	font-size:0.8em;
+	text-decoration:none;
+	line-height:2;
+	color:#999;
+}
+a.hash:hover {
+	color:MediumOrchid;
+}
+
+/* PRINT */
+
+@media print {
+	html, body, #container {
+		margin:0;
+	}
+	#container {
+		width:100%;
+		max-width:100%;
+	}
+	#header {
+		margin-top:0;
+	}
+	#header p {
+		display:none;
+	}
+	#footer {
+		display:none;
+	}
+	a, a:link, a:visited {
+		color:#000;
+		background:#fff;
+		text-decoration:none;
+	}
+	pre.license {
+		font-size:0.95em;
+	}
+	@page {
+		size:8.5in 11in;
+	}
+}
+
+/* PRETTIFICATION OF SOURCE CODE */
+
+.str { color: #181; font-style:italic; }
+.kwd { color: #369; }
+.com { color: #666; }
+.typ { color: #c40; }
+.lit { color: #900; }
+.pun { color: #000; font-weight: bold; }
+.pln { color: #333; }
+.tag { color: #369; font-weight: bold; }
+.atn { color: #939; font-weight: bold }
+.atv { color: #181; }
+.dec { color: #606; }
+
+@media print {
+	.str { color: #060; }
+	.kwd { color: #006; font-weight: bold; }
+	.com { color: #600; font-style: italic; }
+	.typ { color: #404; font-weight: bold; }
+	.lit { color: #044; }
+	.pun { color: #440; }
+	.pln { color: #000; }
+	.tag { color: #006; font-weight: bold; }
+	.atn { color: #404; }
+	.atv { color: #060; }
+}
+
+/* FUCKING IE */
+
+* html body{width:40em}
+* html div.index{width:34.5em}
+
+/* vim: set ft=css ts=4 sw=4 noexpandtab: */