cacheability 1.1.0

data/.gitignore

@@ -0,0 +1,3 @@
+*.sw?
+.DS_Store
+coverage

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Cyril Rohr
+
+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 OR COPYRIGHT HOLDERS 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,41 @@
+Cacheability
+============
+A gem that makes client-side caching of HTTP requests a no-brainer. It is built upon the Rack:Cache gem from Ryan Tomayko.
+
+Cached data can be stored in heap, file or memcached. See the Rack::Cache documentation (http://tomayko.com/src/rack-cache/) for more information.
+
+Installation
+============
+  gem install cryx-cacheability
+  
+Usage
+=====
+  require 'cacheability/restclient'
+  resource = RestClient::CacheableResource.new(  'http://some/cacheable/resource', 
+                                                  :cache => { :metastore => 'file:/tmp/cache/meta', 
+                                                              :entitystore => 'file:/tmp/cache/body' } 
+                                              )
+  resource.get # get from remote server, and cache if possible
+  # ...
+  resource.get # get from cache, if still fresh.
+  # ...
+  resource.get(:cache_control => 'no-cache') # explicitly tells to bypass the cache, requires rack-cache >= 0.4
+  # ...
+
+Do yourself a favor and read: 
+* the HTTP specification related to HTTP caching - http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html
+* Things Caches Do - http://tomayko.com/writings/things-caches-do
+
+
+Supported libraries
+===================
+* rest-client > 0.9
+
+Dependencies
+============
+* rack-cache
+
+COPYRIGHT
+=========
+
+Copyright (c) 2008 Cyril Rohr. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,79 @@
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "cacheability"
+    s.summary = %Q{A gem that makes client-side caching of HTTP requests a no-brainer. Replace your calls to RestClient::Resource.new with RestClient::CacheableResource.new and the caching is taken care of for you ! Supports heap, file and memcache storage.}
+    s.email = "cyril.rohr@irisa.fr"
+    s.homepage = "http://github.com/cryx/cacheability"
+    s.description = "Transparent caching for your HTTP requests (heap, file, memcache). Built-in support for RestClient. Built upon Rack::Cache."
+    s.authors = ["Cyril Rohr"]
+    s.add_dependency "rack-cache"
+    s.rubyforge_project = 'cacheability'
+  end
+  
+  Jeweler::RubyforgeTasks.new do |rubyforge|
+    rubyforge.doc_task = "rdoc"
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+
+begin
+  require 'rake/contrib/sshpublisher'
+  namespace :rubyforge do
+
+    desc "Release gem and RDoc documentation to RubyForge"
+    task :release => ["rubyforge:release:gem", "rubyforge:release:docs"]
+
+    namespace :release do
+      desc "Publish RDoc to RubyForge."
+      task :docs => [:rdoc] do
+        config = YAML.load(
+            File.read(File.expand_path('~/.rubyforge/user-config.yml'))
+        )
+
+        host = "#{config['username']}@rubyforge.org"
+        remote_dir = "/var/www/gforge-projects/cacheability/"
+        local_dir = 'rdoc'
+
+        Rake::SshDirPublisher.new(host, remote_dir, local_dir).upload
+      end
+    end
+  end
+rescue LoadError
+  puts "Rake SshDirPublisher is unavailable or your rubyforge environment is not configured."
+end
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = 'cacheability'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.libs << 'lib' << 'spec'
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |t|
+  t.libs << 'lib' << 'spec'
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.rcov = true
+end
+
+begin
+  require 'cucumber/rake/task'
+  Cucumber::Rake::Task.new(:features)
+rescue LoadError
+  puts "Cucumber is not available. In order to run features, you must: sudo gem install cucumber"
+end
+
+
+task :default => :spec

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 1
+:minor: 1
+:patch: 0

data/cacheability.gemspec

@@ -0,0 +1,55 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{cacheability}
+  s.version = "1.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Cyril Rohr"]
+  s.date = %q{2009-08-07}
+  s.description = %q{Transparent caching for your HTTP requests (heap, file, memcache). Built-in support for RestClient. Built upon Rack::Cache.}
+  s.email = %q{cyril.rohr@irisa.fr}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README"
+  ]
+  s.files = [
+    ".gitignore",
+     "LICENSE",
+     "README",
+     "Rakefile",
+     "VERSION.yml",
+     "cacheability.gemspec",
+     "lib/cacheability.rb",
+     "lib/cacheability/restclient.rb",
+     "spec/cacheability_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/cryx/cacheability}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{cacheability}
+  s.rubygems_version = %q{1.3.2}
+  s.summary = %q{A gem that makes client-side caching of HTTP requests a no-brainer. Replace your calls to RestClient::Resource.new with RestClient::CacheableResource.new and the caching is taken care of for you ! Supports heap, file and memcache storage.}
+  s.test_files = [
+    "spec/cacheability_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rack-cache>, [">= 0"])
+    else
+      s.add_dependency(%q<rack-cache>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rack-cache>, [">= 0"])
+  end
+end

data/lib/cacheability/restclient.rb

@@ -0,0 +1,92 @@
+require 'restclient'
+require 'rack/cache'
+
+module RestClient
+  # A class that mocks the behaviour of a Net::HTTPResponse class.
+  # It is required since RestClient::Response must be initialized with a class that responds to :code and :to_hash.
+  class MockHTTPResponse
+    attr_reader :code, :headers, :body
+    def initialize(rack_response)
+      @code, @headers, io = rack_response
+      @body = ""
+      io.each{|block| @body << block}
+      io.close if io.respond_to?(:close)
+    end
+    
+    def to_hash
+      @headers.inject({}) {|out, (key, value)|
+        # In Net::HTTP, headers values are arrays
+        out[key] = value.split(", ")
+        out
+      }
+    end    
+  end
+  
+  class CacheableResource < Resource
+    attr_reader :cache
+    CACHE_DEFAULT_OPTIONS = {:verbose => true}.freeze
+    
+    def initialize(*args)
+      super(*args)
+      # rack-cache creates a singleton, so that there is only one instance of the cache at any time
+      @cache = Rack::Cache.new(self, options[:cache] || CACHE_DEFAULT_OPTIONS)
+    end
+  
+    def get(additional_headers = {}, pass_through_cache = true)
+      if pass_through_cache && cache
+        uri = URI.parse(url)
+        uri_path_split = uri.path.split("/")
+        path_info = (last_part = uri_path_split.pop) ? "/"+last_part : ""
+        script_name = uri_path_split.join("/")
+        # minimal rack spec
+        env = { 
+          "REQUEST_METHOD" => 'GET',
+          "SCRIPT_NAME" => script_name,
+          "PATH_INFO" => path_info,
+          "QUERY_STRING" => uri.query,
+          "SERVER_NAME" => uri.host,
+          "SERVER_PORT" => uri.port.to_s,
+          "rack.version" => Rack::VERSION,
+          "rack.run_once" => false,
+          "rack.multithread" => true,
+          "rack.multiprocess" => true,
+          "rack.url_scheme" => uri.scheme,
+          "rack.input" => StringIO.new,
+          "rack.errors" => StringIO.new   # Rack-Cache writes errors into this field
+        }
+        debeautify_headers(additional_headers).each do |key, value|
+          env.merge!("HTTP_"+key.to_s.gsub("-", "_").upcase => value)
+        end
+        response = MockHTTPResponse.new(cache.call(env))
+        RestClient::Response.new(response.body, response)
+      else
+        super(additional_headers)
+      end
+    end
+  
+    def debeautify_headers(headers = {})
+      headers.inject({}) do |out, (key, value)|
+  			out[key.to_s.gsub(/_/, '-')] = value
+  			out
+  		end
+    end
+  
+    # Follows the SPEC of Rack 1.0: the returned body is always an array of string
+    #
+    def call(env)
+      http_headers = env.inject({}) do |out, (header, value)| 
+        if header =~ /HTTP_/
+          out[header.gsub("HTTP_", '')] = value unless value.nil? || value.empty?
+        end
+        out
+      end
+      response = get(debeautify_headers(http_headers), pass_through_cache=false)
+      response.headers.delete(:x_content_digest) # don't know why, but it seems to make the validation fail if kept...
+      [response.code, debeautify_headers( response.headers ), [response.to_s]]
+    rescue RestClient::NotModified => e
+      # e is a Net::HTTPResponse
+      response = RestClient::Response.new("", e.response)
+      [304, debeautify_headers( response.headers ), [response.to_s]]
+    end
+  end
+end

data/spec/cacheability_spec.rb

@@ -0,0 +1,69 @@
+require File.dirname(__FILE__) + '/spec_helper'
+require 'restclient'
+require File.dirname(__FILE__) + '/../lib/cacheability/restclient'
+
+
+describe RestClient::CacheableResource do
+  require File.dirname(__FILE__) + '/../lib/cacheability/restclient'
+  before do
+    @cache_options = {:metastore => 'file:/tmp/cache/meta', :entitystore => 'file:/tmp/cache/body'}
+  end
+  
+  it "should instantiate the cache at init" do
+    mock_cache = mock('rack-cache instance')    
+    Rack::Cache.should_receive(:new).with( 
+      RestClient::CacheableResource.new('http://domain.tld:8888/some/cacheable/resource', :cache => @cache_options), 
+      @cache_options
+    ).and_return(mock_cache)
+  end
+  
+  describe "correctly instantiated" do
+    before do
+      @mock_cache = mock('rack-cache singleton')
+      @mock_rack_errors = mock('string io')
+      @mock_304_net_http_response = mock('http response', :code => 304, :body => "", :to_hash => {'header1' => ['value1', 'value2']})
+      Rack::Cache.stub!(:new).and_return(@mock_cache)
+      @env = {
+        'REQUEST_METHOD' => 'GET',
+        "SCRIPT_NAME" => '/some/cacheable',
+        "PATH_INFO" => '/resource',
+        "QUERY_STRING" => 'q1=a&q2=b',
+        "SERVER_NAME" => 'domain.tld',
+        "SERVER_PORT" => '8888'
+      }
+      @resource = RestClient::CacheableResource.new('http://domain.tld:8888/some/cacheable/resource', :cache => @cache_options)
+    end
+    
+    it "should pass through the cache" do
+      @resource.cache.should_receive(:call).with( hash_including( @env.merge({'HTTP_ADDITIONAL_HEADER' => 'whatever'}) ) ).and_return([200, {}, "response body"])
+      @resource['/?q1=a&q2=b'].get(:additional_header => 'whatever')
+    end
+  
+    it "should bypass the cache if pass_through_cache argument is false" do
+      @resource = RestClient::CacheableResource.new('http://domain.tld:8888/some/cacheable/resource', :cache => @cache_options)
+      @resource.cache.should_not_receive(:call)
+      @resource.get({:additional_header => 'whatever'}, false) rescue nil # don't know how to spec the call to super()
+    end
+  
+    it "should call the backend (bypassing the cache) if the requested resource is not in the cache" do
+      @resource.should_receive(:get).with({'ADDITIONAL-HEADER' => 'whatever'}, false).and_return(mock('rest-client response', :headers => {}, :code => 200, :to_s => 'body'))
+      response = @resource.call(@env.merge({'HTTP_ADDITIONAL_HEADER' => 'whatever'}))
+      response.should == [200, {}, ["body"]]
+    end
+    
+    it "should return a 304 not modified response if the call to the backend returned a 304 not modified response" do
+      @resource.should_receive(:get).with({'ADDITIONAL-HEADER' => 'whatever'}, false).and_raise(RestClient::NotModified.new(@mock_304_net_http_response))
+      response = @resource.call(@env.merge({'HTTP_ADDITIONAL_HEADER' => 'whatever'}))
+      response.should == [304, {"header1"=>"value1"}, [""]]
+    end
+    
+    it "should render a RestClient::Response even when the data is coming from the cache" do
+      @resource.cache.should_receive(:call).and_return([200, {'ADDITIONAL_HEADER' => 'whatever'}, "body"])
+      response = @resource.get({'HTTP_ADDITIONAL_HEADER' => 'whatever'}, true)
+      response.should be_is_a(RestClient::Response)
+      response.code.should == 200
+      response.headers.should == {:ADDITIONAL_HEADER => 'whatever'}
+      response.to_s.should == "body"
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+require 'rubygems'
+require 'spec'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+
+
+Spec::Runner.configure do |config|
+  
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification 
+name: cacheability
+version: !ruby/object:Gem::Version 
+  version: 1.1.0
+platform: ruby
+authors: 
+- Cyril Rohr
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-08-07 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rack-cache
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Transparent caching for your HTTP requests (heap, file, memcache). Built-in support for RestClient. Built upon Rack::Cache.
+email: cyril.rohr@irisa.fr
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README
+files: 
+- .gitignore
+- LICENSE
+- README
+- Rakefile
+- VERSION.yml
+- cacheability.gemspec
+- lib/cacheability.rb
+- lib/cacheability/restclient.rb
+- spec/cacheability_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/cryx/cacheability
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: cacheability
+rubygems_version: 1.3.2
+signing_key: 
+specification_version: 3
+summary: A gem that makes client-side caching of HTTP requests a no-brainer. Replace your calls to RestClient::Resource.new with RestClient::CacheableResource.new and the caching is taken care of for you ! Supports heap, file and memcache storage.
+test_files: 
+- spec/cacheability_spec.rb
+- spec/spec_helper.rb