@@ -17,8 +17,9 @@ * Get rid of default_entity_store * URL based storage configuration * Read options from Rack env if present (rack-cache.XXX keys) + - Rename `object` to `entry`. * Document storage areas and implementations - - Document configuration/events + * Document configuration/events - Document request, response, cached object - Website TODO @@ -1,15 +1,18 @@ -Configuration -============= +Configuration Language +====================== -__Rack::Cache__ includes a configuration system (inspired by [Varnish][var]'s -[VCL configuration language][vcl]) that can be used to specify fairly -sophisticated cache policy on a global or per-request basis. +__Rack::Cache__ includes a configuration system that can be used to specify +fairly sophisticated cache policy on a global or per-request basis. -[var]: http://varnish.projects.linpro.no/ - "Varnish HTTP accelerator" + - [Synopsis](#synopsis) + - [Setting Cache Options](#setopt) + - [Cache Option Reference](#options) + - [Configuration Machinery - Events and Transitions](#machinery) + - [Importing Configuration](#import) + - [Default Configuration Machinery](#default) + - [Notes](#notes) -[vcl]: http://tomayko.com/man/vcl - "VCL(7) -- Varnish Configuration Language Manual Page" +<a id='synopsis'></a> Synopsis -------- @@ -17,97 +20,205 @@ Synopsis use Rack::Cache do # set cache related options set :verbose, true - set :metastore, 'file:/var/cache/rack/meta' + set :metastore, 'memcached://localhost:11211' set :entitystore, 'file:/var/cache/rack/body' - # define event handlers + # override events / transitions on :receive do - pass! if request.url =~ %r|/uncacheable/| + pass! if request.url =~ %r|/dontcache/| error! 402 if request.referrer =~ /digg.com/ end + on :miss do trace 'missed: %s', request.url end - # bring in other configuration files + # bring in other configuration machinery import 'rack/cache/config/breakers' import 'mycacheconfig' end -Cache Options -------------- +<a id='setopt'></a> -The following +Setting Cache Options +--------------------- -### `rack-cache.verbose` +Cache options can be set when the __Rack::Cache__ object is created; or by using +the `set` method within a configuration block; or by setting a +`rack-cache.<option>` variable in __Rack__'s __Environment__. -Enable verbose trace logging. This option is currently enabled by -default but is likely to be disabled in a future release. +When the __Rack::Cache__ object is instantiated: -### `rack-cache.default_ttl` + use Rack::Cache, + :verbose => true, + :metastore => 'memcached://localhost:11211/', + :entitystore => 'file:/var/cache/rack' -The number of seconds that a cached object should be considered "fresh" when no -explicit freshness information is provided in a response. Explicit -`Cache-Control` or `Expires` header present in a response always override -this value. +Using the `set` method within __Rack::Cache__'s configuration context: -Default: 0 + use Rack::Cache do + set :verbose, true + set :metastore, 'memcached://localhost:11211/' + set :entitystore, 'file:/var/cache/rack' + end + +Using __Rack__'s __Environment__: -### `rack-cache.metastore` + env.merge!( + 'rack-cache.verbose' => true, + 'rack-cache.metastore' => 'memcached://localhost:11211/', + 'rack-cache.entitystore' => 'file:/var/cache/rack' + ) + +<a id='options'></a> + +Cache Option Reference +---------------------- -A URI specifying the metastore implementation used to store request/response +Use the following options to customize __Rack::Cache__: + +### `verbose` + +Boolean specifying whether verbose trace logging is enabled. This option is +currently enabled (`true`) by default but is likely to be disabled (`false`) in +a future release. All log output is written to the `rack.errors` stream, which +is typically set to `STDERR`. + +The `trace`, `info`, `warn`, and `error` methods can be used within the +configuration context to write messages to the errors stream. + +### `default_ttl` + +An integer specifying the number of seconds a cached object should be considered +"fresh" when no explicit freshness information is provided in a response. +Explicit `Cache-Control` or `Expires` response headers always override this +value. The `default_ttl` option defaults to `0`, meaning responses without +explicit freshness information are considered immediately "stale" and will not +be served from cache without validation. + +### `metastore` + +A URI specifying the __MetaStore__ implementation used to store request/response meta information. See the [Rack::Cache Storage Documentation](storage.html) for detailed information on different storage implementations. -If no metastore is specified the 'heap:/' store is assumed. This implementation +If no metastore is specified, the `heap:/` store is assumed. This implementation has significant draw-backs so explicit configuration is recommended. -### `rack-cache.entitystore` +### `entitystore` -A URI specifying the entity-store implementation used to store +A URI specifying the __EntityStore__ implementation used to store response bodies. See the [Rack::Cache Storage Documentation](storage.html) for detailed information on different storage implementations. -If no entitystore is specified the 'heap:/' store is assumed. This +If no entitystore is specified, the `heap:/` store is assumed. This implementation has significant draw-backs so explicit configuration is recommended. -Events and Transitions ----------------------- +<a id='machinery'></a> + +Configuration Machinery - Events and Transitions +------------------------------------------------ + +The configuration machinery is built around a series of interceptable events and +transitions controlled by a simple configuration language. The following diagram +shows each state (interceptable event) along with their possible transitions: + +<p class='center'> +<img src='events.png' alt='Events and Transitions Diagram' /> +</p> + +Custom logic can be layered onto the `receive`, `hit`, `miss`, `fetch`, `store`, +`deliver`, and `pass` events by passing a block to the `on` method: -The configuration language is built around a series of interceptable events and -transitions controlled by a simple configuration language. + on :fetch do + trace 'fetched %p from backend application', request.url + end + +Here, the `trace` method writes a message to the `rack.errors` stream when a +response is fetched from the backend application. The `request` object is a +[__Rack::Cache::Request__](./api/classes/Rack/Cache/Request) that can be +inspected (and modified) to determine what action should be taken next. + +Event blocks are capable of performing more interesting operations: + + * Transition to a different event or override default caching logic. + * Modify the request, response, cache entry, or Rack environment options. + * Set the `metastore` or `entitystore` options to select a different storage + mechanism / location dynamically. + * Collect statistics or log request/response/cache information. -Some statements are considered _transitioning_ in that they cause the current -event to halt processing. In the example above, both the `pass!` and `error!` -statements cause the `:receive` event to halt (the block is immediately exited -via `throw`), which causes the machine to begin transitioning to the subsequent -event. +When an event is triggered, the blocks associated with the event are executed in +reverse/FILO order (i.e., the block declared last runs first) until a +_transitioning statement_ is encountered. Transitioning statements are suffixed +with a bang character (e.g, `pass!`, `store!`, `error!`) and cause the current +event to halt and the machine to transition to the subsequent event; control +is not returned to the original event. -Caching policy can be layered. Event handlers are executed in last-on/first-off -(LOFO) order until a transitioning statement is executed. + on :fetch do + next if response.freshness_information? + + if request.url =~ /\/feed$/ + trace 'feed will expire in fifteen minutes' + response.ttl = 15 * 60 + end + end -Importing ---------- -This allows small bits of cache policy to be captured in separate files and -combined as needed: +<a id='import'></a> + +Importing Configuration +----------------------- + +Since caching logic can be layered, it's possible to separate various bits of +cache policy into files for organization and reuse. use Rack::Cache do - import 'rack/cache/config/accelerator' import 'rack/cache/config/breakers' + import 'mycacheconfig' + + # more stuff here end -The `breakers` and `accelerator` configuration files are normal Ruby source -files (i.e., with a ".rb" extension) on the `$LOAD_PATH`; `import` evaluates -their contents in the context of the configuration machinery as if their -contents were specified directly in the initialization block. +The `breakers` and `mycacheconfig` configuration files are normal Ruby source +files (i.e., they have a `.rb` extension) situated on the `$LOAD_PATH` - the +`import` statement works like Ruby's `require` statement but the contents of the +files are evaluated in the context of the configuration machinery, as if +specified directly in the configuration block. -Default Configuration ---------------------- +The `rack/cache/config/breakers.rb` file makes a good example. It hooks into the +`fetch` event and adds an impractically long expiration lifetime to any response +that includes a cache busting query string: + +<div> +<%= File.read('doc/config/breakers.rb.html') %> +</div> -The `rack/cache/config/default.rb` file is imported before any custom -configuration code is executed. Any custom event handlers defined in your -application are executed before the default event handlers. +<a id='default'></a> + +Default Configuration Machinery +------------------------------- + +The `rack/cache/config/default.rb` file is imported when the __Rack::Cache__ +object is instantiated and before any custom configuration code is executed. +It's useful to understand this configuration because it drives the default +transitioning logic. + +<div> <%= File.read('doc/config/default.rb.html') %> +</div> + +<a id='notes'></a> + +Notes +----- + +The configuration language was inspired by [Varnish][var]'s +[VCL configuration language][vcl]. + +[var]: http://varnish.projects.linpro.no/ + "Varnish HTTP accelerator" + +[vcl]: http://tomayko.com/man/vcl + "VCL(7) -- Varnish Configuration Language Manual Page" doc/configuration.markdown @@ -1,34 +1,27 @@ digraph cache_logic { - nodesep=1.0 + nodesep=1.25; + center=true; - node[fontname="Helvetica"] - edge[fontname="Helvetica"] + node[fontname="Lucida Sans Unicode",labelloc=c,margin=0.10,0.03] + edge[fontname="Lucida Sans Unicode",fontcolor="#444444",labeldistance=20]; - receive -> pass; - receive -> lookup; + receive -> pass[label="uncacheable request",color=grey]; + receive -> lookup[label="cacheable request"]; - pass -> finish; + pass -> deliver[label="",color=grey]; - lookup -> hit; - lookup -> validate; - lookup -> miss; + lookup -> hit[label="fresh"]; + lookup -> fetch[label="stale (needs validation)"]; + lookup -> miss[label="uncached"]; - hit -> deliver; - hit -> pass; + hit -> deliver[label="sizzling"]; + hit -> pass[label="bailing...",color=grey]; - miss -> fetch; - miss -> pass; + miss -> fetch[label=""]; + miss -> pass[color=grey]; - validate -> fetch; - validate -> deliver; + fetch -> store[label="cacheable"]; + fetch -> deliver[label="not cacheable",color=grey]; - fetch -> store; - fetch -> deliver; - - store -> persist; - store -> deliver; - - persist -> deliver; - - deliver -> finish; + store -> deliver[label="KTHX"]; } doc/events.dot @@ -8,11 +8,11 @@ body { font-size:112.5%; /* 18px (probably) */ line-height:1.3888; /* 25px */ - letter-spacing:-0.05em; + letter-spacing:-0.02em; margin:0 10px; font-family: 'lucida sans unicode', 'lucida grande', helvetica, 'bitstream vera sans', sans-serif; - color:#223; + color:#556; background-color:#fff; } @@ -22,7 +22,7 @@ body { } h1, h2, h3 { - font-family:georgia, 'bitstream vera sans serif', 'lucida grande' + font-family:georgia, 'bitstream vera sans serif', 'lucida grande', helvetica, verdana, sans-serif; font-weight:normal; letter-spacing:-0.05em; @@ -32,7 +32,7 @@ i, em { font-style:italic; } b, strong { - font-weight:bold; + font-weight:normal; color:#000; } blockquote { @@ -134,7 +134,8 @@ h3 { margin:1em 0; } h3 code{ - font-size:1em; + font-size:0.95em; + color:#000; } h4 { font-size:1em; @@ -268,6 +269,9 @@ ul.clean, ol.clean { .right{ float:right; } +.center{ + text-align:center; +} .intro { font-size:0.833333em; /* 15px */ line-height:1.666667; /* 25px */ doc/rack-cache.css 505932b53e419d79e4186869b64617187ff9f836 Ryan Tomayko rtomayko@gmail.com http://github.com/rtomayko/rack-cache/commit/d10192e72fda807c86b223e1d19e4cea99ede020 d10192e72fda807c86b223e1d19e4cea99ede020 2008-10-21T04:54:28-07:00 2008-10-21T04:54:09-07:00 finish up config machinery doc (for now) edce0aef9620b478fd1ae73d953b5201bdfbe4d8 Ryan Tomayko rtomayko@gmail.com