josh-rack-cache 0.5.1

data/CHANGES

@@ -0,0 +1,167 @@
+## 0.6.0 / Unreleased
+
+  * Added support for memcached clusters and other advanced
+    configuration provided by the memcache-client and memcached
+    libraries. The "metastore" and "entitystore" options can now be
+    set to a MemCache object or Memcached object:
+
+    memcache = MemCache.new(['127.1.1.1', '127.1.1.2'], :namespace => "/foo")
+    use Rack::Cache,
+      :metastore => memcache,
+      :entitystore => memcache
+
+  * Fix "memcached://" metastore URL handling. The "memcached" variation
+    blew up, the "memcache" version was fine.
+
+## 0.5.0 / May 2009
+
+  * Added meta and entity store implementations based on the
+    memcache-client library. These are the default unless the memcached
+    library has already been required.
+
+  * The "allow_reload" and "allow_revalidate" options now default to
+    false instead of true. This means we break with RFC 2616 out of
+    the box but this is the expected configuration in a huge majority
+    of gateway cache scenarios. See the docs on configuration
+    options for more information on these options:
+    http://tomayko.com/src/rack-cache/configuration
+
+  * Added Google AppEngine memcache entity store and metastore
+    implementations. To use GAE's memcache with rack-cache, set the
+    "metastore" and "entitystore" options as follows:
+
+        use Rack::Cache,
+          :metastore   => 'gae://cache-meta',
+          :entitystore => 'gae://cache-body'
+
+    The 'cache-meta' and 'cache-body' parts are memcache namespace
+    prefixes and should be set to different values.
+
+## 0.4.0 / March 2009
+
+  * Ruby 1.9.1 / Rack 1.0 compatible.
+
+  * Invalidate cache entries that match the request URL on non-GET/HEAD
+    requests. i.e., POST, PUT, DELETE cause matching cache entries to
+    be invalidated. The cache entry is validated with the backend using
+    a conditional GET the next time it's requested.
+
+  * Implement "Cache-Control: max-age=N" request directive by forcing
+    validation when the max-age provided exceeds the age of the cache
+    entry. This can be disabled by setting the "allow_revalidate" option to
+    false.
+
+  * Properly implement "Cache-Control: no-cache" request directive by
+    performing a full reload. RFC 2616 states that when "no-cache" is
+    present in the request, the cache MUST NOT serve a stored response even
+    after successful validation. This is slightly different from the
+    "no-cache" directive in responses, which indicates that the cache must
+    first validate its entry with the origin. Previously, we implemented
+    "no-cache" on requests by passing so no new cache entry would be stored
+    based on the response. Now we treat it as a forced miss and enter the
+    response into the cache if it's cacheable. This can be disabled by
+    setting the "allow_reload" option to false.
+
+  * Assume identical semantics for the "Pragma: no-cache" request header
+    as the "Cache-Control: no-cache" directive described above.
+
+  * Less crazy logging. When the verbose option is set, a single log entry
+    is written with a comma separated list of trace events. For example, if
+    the cache was stale but validated, the following log entry would be
+    written: "cache: stale, valid, store". When the verbose option is false,
+    no logging occurs.
+
+  * Added "X-Rack-Cache" response header with the same comma separated trace
+    value as described above. This gives some visibility into how the cache
+    processed the request.
+
+  * Add support for canonicalized cache keys, as well as custom cache key
+    generators, which are specified in the options as :cache_key as either
+    any object that has a call() or as a block. Cache key generators get
+    passed a request object and return a cache key string.
+
+## 0.3.0 / December 2008
+
+  * Add support for public and private cache control directives. Responses
+    marked as explicitly public are cached even when the request includes
+    an Authorization or Cookie header. Responses marked as explicitly private
+    are considered uncacheable.
+
+  * Added a "private_headers" option that dictates which request headers
+    trigger default "private" cache control processing. By default, the
+    Cookie and Authorization headers are included. Headers may be added or
+    removed as necessary to change the default private logic.
+
+  * Adhere to must-revalidate/proxy-revalidate cache control directives by
+    not assigning the default_ttl to responses that don't include freshness
+    information. This should let us begin using default_ttl more liberally
+    since we can control it using the must-revalidate/proxy-revalidate directives.
+
+  * Use the s-maxage Cache-Control value in preference to max-age when
+    present. The ttl= method now sets the s-maxage value instead of max-age.
+    Code that used ttl= to control freshness at the client needs to change
+    to set the max-age directive explicitly.
+
+  * Enable support for X-Sendfile middleware by responding to #to_path on
+    bodies served from disk storage. Adding the Rack::Sendfile component
+    upstream from Rack::Cache will result in cached bodies being served
+    directly by the web server (instead of being read in Ruby).
+
+  * BUG: MetaStore hits but EntityStore misses. This would 500 previously; now
+    we detect it and act as if the MetaStore missed as well.
+
+  * Implement low level #purge method on all concrete entity store
+    classes -- removes the entity body corresponding to the SHA1 key
+    provided and returns nil.
+
+  * Basically sane handling of HEAD requests. A HEAD request is never passed
+    through to the backend except when transitioning with pass!. This means
+    that the cache responds to HEAD requests without invoking the backend at
+    all when the cached entry is fresh. When no cache entry exists, or the
+    cached entry is stale and can be validated, the backend is invoked with
+    a GET request and the HEAD is handled right before the response
+    is delivered upstream.
+
+  * BUG: The Age response header was not being set properly when a stale
+    entry was validated. This would result in Age values that exceeded
+    the freshness lifetime in responses.
+
+  * BUG: A cached entry in a heap meta store could be unintentionally
+    modified by request processing since the cached objects were being
+    returned directly. The result was typically missing/incorrect header
+    values (e.g., missing Content-Type header). [dkubb]
+
+  * BUG: 304 responses should not include entity headers (especially
+    Content-Length). This is causing Safari/WebKit weirdness on 304
+    responses.
+
+  * BUG: The If-None-Match header was being ignored, causing the cache
+    to send 200 responses to matching conditional GET requests.
+
+## 0.2.0 / 2008-10-24 / Initial Release
+
+  * Document events and transitions in `rack/cache/config/default.rb`
+  * Basic logging support (`trace`, `warn`, `info`, `error` from within Context)
+  * EntityStore: store entity bodies keyed by SHA
+  * MetaStore: store response headers keyed by URL
+  * Last-Modified/ETag validation
+  * Vary support
+  * Implement error! transition
+  * New Rack::Cache::Core
+  * memcached meta and entity store implementations
+  * URI based storage configuration
+  * Read options from Rack env if present (rack-cache.XXX keys)
+  * `object` is now `entry`
+  * Documentation framework and website
+  * Document storage areas and implementations
+  * Document configuration/events
+
+## 0.1.0 / 2008-07-21 / Proof of concept (unreleased)
+
+  * Basic core with event support
+  * `#import` method for bringing in config files
+  * Freshness based expiration
+  * RFC 2616 If-Modified-Since based validation
+  * A horribly shitty storage back-end (Hash in mem)
+  * Don't cache hop-by-hop headers: Connection, Keep-Alive, Proxy-Authenticate,
+    Proxy-Authorization, TE, Trailers, Transfer-Encoding, Upgrade

data/COPYING

@@ -0,0 +1,18 @@
+Copyright (c) 2008 Ryan Tomayko <http://tomayko.com/about>
+
+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.

data/README

@@ -0,0 +1,110 @@
+Rack::Cache
+===========
+
+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)
+  * Freshness/expiration based caching
+  * Validation (If-Modified-Since / If-None-Match)
+  * Vary support
+  * Cache-Control: public, private, max-age, s-maxage, must-revalidate,
+    and proxy-revalidate.
+  * Portable: 100% Ruby / works with any Rack-enabled framework
+  * Disk, memcached, and heap memory storage backends
+
+For more information about Rack::Cache features and usage, see:
+
+http://tomayko.com/src/rack-cache/
+
+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 /
+high-performance caching systems (e.g., Varnish, Squid, httpd/mod-cache) may be
+more appropriate for large deployments with significant throughput requirements.
+
+Installation
+------------
+
+From Gem:
+
+    $ sudo gem install rack-cache
+
+With 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,
+      :metastore   => 'file:/var/cache/rack/meta',
+      :entitystore => 'file:/var/cache/rack/body',
+      :verbose     => true
+
+    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.
+
+Using with Rails
+----------------
+
+Add this to your `config/environment.rb`:
+
+   config.middleware.use Rack::Cache,
+       :verbose => true,
+       :metastore   => 'file:/var/cache/rack/meta',
+       :entitystore => 'file:/var/cache/rack/body'
+
+You should now see `Rack::Cache` listed in the middleware pipeline:
+
+    rake middleware
+
+See the following for more information:
+
+    http://snippets.aktagon.com/snippets/302
+
+Links
+-----
+
+Documentation:
+    http://tomayko.com/src/rack-cache/
+
+Mailing List:
+    http://groups.google.com/group/rack-cache
+
+GitHub:
+    http://github.com/rtomayko/rack-cache/
+
+License
+-------
+
+Copyright (c) 2008 Ryan Tomayko <http://tomayko.com/about>
+
+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.

data/Rakefile

@@ -0,0 +1,137 @@
+require 'rake/clean'
+
+task :default => :test
+
+CLEAN.include %w[coverage/ doc/api tags]
+CLOBBER.include %w[dist]
+
+# load gemspec like github's gem builder to surface any SAFE issues.
+Thread.new do
+  require 'rubygems/specification'
+  $spec = eval("$SAFE=3\n#{File.read('rack-cache.gemspec')}")
+end.join
+
+# SPECS =====================================================================
+
+desc 'Run specs with story style output'
+task :spec do
+  sh 'specrb --specdox -Ilib:test test/*_test.rb'
+end
+
+desc 'Run specs with unit test style output'
+task :test => FileList['test/*_test.rb'] do |t|
+  suite = t.prerequisites
+  sh "specrb -Ilib:test #{suite.join(' ')}", :verbose => false
+end
+
+desc 'Generate test coverage report'
+task :rcov do
+  sh "rcov -Ilib:test test/*_test.rb"
+end
+
+# DOC =======================================================================
+desc 'Build all documentation'
+task :doc => %w[doc:api doc:markdown]
+
+# requires the hanna gem:
+#   gem install mislav-hanna --source=http://gems.github.com
+desc 'Build API documentation (doc/api)'
+task 'doc:api' => 'doc/api/index.html' 
+file 'doc/api/index.html' => FileList['lib/**/*.rb'] do |f|
+  rm_rf 'doc/api'
+  sh((<<-SH).gsub(/[\s\n]+/, ' ').strip)
+  hanna
+    --op doc/api
+    --promiscuous
+    --charset utf8
+    --fmt html
+    --inline-source
+    --line-numbers
+    --accessor option_accessor=RW
+    --main Rack::Cache
+    --title 'Rack::Cache API Documentation'
+    #{f.prerequisites.join(' ')}
+  SH
+end
+CLEAN.include 'doc/api'
+
+desc 'Build markdown documentation files'
+task 'doc:markdown'
+FileList['doc/*.markdown'].each do |source|
+  dest = "doc/#{File.basename(source, '.markdown')}.html"
+  file dest => [source, 'doc/layout.html.erb'] do |f|
+    puts "markdown: #{source} -> #{dest}" if verbose
+    require 'erb' unless defined? ERB
+    require 'rdiscount' unless defined? RDiscount
+    template = File.read(source)
+    content = Markdown.new(ERB.new(template, 0, "%<>").result(binding), :smart).to_html
+    title = content.match("<h1>(.*)</h1>")[1] rescue ''
+    layout = ERB.new(File.read("doc/layout.html.erb"), 0, "%<>")
+    output = layout.result(binding)
+    File.open(dest, 'w') { |io| io.write(output) }
+  end
+  task 'doc:markdown' => dest
+  CLEAN.include dest
+end
+
+desc 'Publish documentation'
+task 'doc:publish' => :doc do
+  sh 'rsync -avz doc/ gus@tomayko.com:/src/rack-cache'
+end
+
+desc 'Start the documentation development server (requires thin)'
+task 'doc:server' do
+  sh 'cd doc && thin --rackup server.ru --port 3035 start'
+end
+
+# PACKAGING =================================================================
+
+def package(ext='')
+  "dist/rack-cache-#{$spec.version}" + ext
+end
+
+desc 'Build packages'
+task :package => %w[.gem .tar.gz].map {|e| package(e)}
+
+desc 'Build and install as local gem'
+task :install => package('.gem') do
+  sh "gem install #{package('.gem')}"
+end
+
+directory 'dist/'
+
+file package('.gem') => %w[dist/ rack-cache.gemspec] + $spec.files do |f|
+  sh "gem build rack-cache.gemspec"
+  mv File.basename(f.name), f.name
+end
+
+file package('.tar.gz') => %w[dist/] + $spec.files do |f|
+  sh "git archive --format=tar HEAD | gzip > #{f.name}"
+end
+
+desc 'Upload gem and tar.gz distributables to rubyforge'
+task :release => [package('.gem'), package('.tar.gz')] do |t|
+  sh <<-SH
+    rubyforge add_release wink rack-cache #{$spec.version} #{package('.gem')} &&
+    rubyforge add_file    wink rack-cache #{$spec.version} #{package('.tar.gz')}
+  SH
+end
+
+# GEMSPEC ===================================================================
+
+file 'rack-cache.gemspec' => FileList['{lib,test}/**','Rakefile'] do |f|
+  # read spec file and split out manifest section
+  spec = File.read(f.name)
+  parts = spec.split("  # = MANIFEST =\n")
+  fail 'bad spec' if parts.length != 3
+  # determine file list from git ls-files
+  files = `git ls-files`.
+    split("\n").sort.reject{ |file| file =~ /^\./ }.
+    map{ |file| "    #{file}" }.join("\n")
+  # piece file back together and write...
+  parts[1] = "  s.files = %w[\n#{files}\n  ]\n"
+  spec = parts.join("  # = MANIFEST =\n")
+  spec.sub!(/s.date = '.*'/, "s.date = '#{Time.now.strftime("%Y-%m-%d")}'")
+  File.open(f.name, 'w') { |io| io.write(spec) }
+  puts "updated #{f.name}"
+end

data/TODO

@@ -0,0 +1,27 @@
+## 0.5
+
+  - Document allow_revalidate and allow_reload options.
+  - Support multiple memcache servers.
+  - Purge/invalidate everything
+  - Explicit expiration/invalidation based on response headers or via an
+    object interface passed in the rack env.
+  - Sample apps: Rack, Rails, Sinatra, Merb, etc.
+  - Move old breakers.rb configuration file into rack-contrib as a
+    middleware component.
+
+## Backlog
+
+  - Use Bacon instead of test/spec
+  - Fast path pass processing. We do a lot more than necessary just to determine
+    that the response should be passed through untouched.
+  - Invalidate at the URI of the Location or Content-Location response header
+    on POST, PUT, or DELETE that results in a redirect.
+  - Maximum size of cached entity
+  - Last-Modified factor: requests that have a Last-Modified header but no Expires
+    header have a TTL assigned based on the last modified age of the response:
+    TTL = (Age * Factor), or, 1h  = (10h * 0.1)
+  - Consider implementing ESI (http://www.w3.org/TR/esi-lang). This should
+    probably be implemented as a separate middleware component.
+  - stale-while-revalidate
+  - Serve cached copies when down (see: stale-if-error) - e.g., database
+    connection drops and the cache takes over what it can.