cachebar 1.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/CacheBar.gemspec

@@ -0,0 +1,93 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{CacheBar}
+  s.version = "1.0.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Brian Landau", "David Eisinger"]
+  s.date = %q{2011-11-17}
+  s.description = %q{A simple API caching layer built on top of HTTParty and Redis}
+  s.email = %q{brian.landau@viget.com}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    ".document",
+    "CacheBar.gemspec",
+    "Gemfile",
+    "HISTORY",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "lib/cachebar.rb",
+    "lib/httparty/httpcache.rb",
+    "test/fixtures/user_timeline.json",
+    "test/fixtures/vcr_cassettes/bad_response.yml",
+    "test/fixtures/vcr_cassettes/good_response.yml",
+    "test/fixtures/vcr_cassettes/status_update_post.yml",
+    "test/fixtures/vcr_cassettes/unparsable.yml",
+    "test/helper.rb",
+    "test/test_cachebar.rb",
+    "test/twitter_api.rb"
+  ]
+  s.homepage = %q{http://github.com/vigetlabs/cachebar}
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.6.2}
+  s.summary = %q{A simple API caching layer built on top of HTTParty and Redis}
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<redis>, [">= 0"])
+      s.add_runtime_dependency(%q<redis-namespace>, [">= 0"])
+      s.add_runtime_dependency(%q<httparty>, ["~> 0.7.7"])
+      s.add_runtime_dependency(%q<activesupport>, [">= 0"])
+      s.add_development_dependency(%q<shoulda>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.6"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+      s.add_development_dependency(%q<webmock>, [">= 0"])
+      s.add_development_dependency(%q<vcr>, [">= 0"])
+      s.add_development_dependency(%q<mocha>, [">= 0"])
+      s.add_development_dependency(%q<rake>, ["~> 0.8.7"])
+      s.add_development_dependency(%q<SystemTimer>, [">= 0"])
+    else
+      s.add_dependency(%q<redis>, [">= 0"])
+      s.add_dependency(%q<redis-namespace>, [">= 0"])
+      s.add_dependency(%q<httparty>, ["~> 0.7.7"])
+      s.add_dependency(%q<activesupport>, [">= 0"])
+      s.add_dependency(%q<shoulda>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.6"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+      s.add_dependency(%q<webmock>, [">= 0"])
+      s.add_dependency(%q<vcr>, [">= 0"])
+      s.add_dependency(%q<mocha>, [">= 0"])
+      s.add_dependency(%q<rake>, ["~> 0.8.7"])
+      s.add_dependency(%q<SystemTimer>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<redis>, [">= 0"])
+    s.add_dependency(%q<redis-namespace>, [">= 0"])
+    s.add_dependency(%q<httparty>, ["~> 0.7.7"])
+    s.add_dependency(%q<activesupport>, [">= 0"])
+    s.add_dependency(%q<shoulda>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.6"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+    s.add_dependency(%q<webmock>, [">= 0"])
+    s.add_dependency(%q<vcr>, [">= 0"])
+    s.add_dependency(%q<mocha>, [">= 0"])
+    s.add_dependency(%q<rake>, ["~> 0.8.7"])
+    s.add_dependency(%q<SystemTimer>, [">= 0"])
+  end
+end
+

data/Gemfile

@@ -0,0 +1,18 @@
+source "http://rubygems.org"
+
+gem "redis"
+gem "redis-namespace"
+gem 'httparty', '~> 0.8.3'
+gem 'activesupport'
+
+group :development do
+  gem "shoulda"
+  gem "bundler", "~> 1.0"
+  gem "jeweler", "~> 1.6"
+  gem "rcov"
+  gem "webmock"
+  gem 'vcr'
+  gem 'mocha'
+  gem 'rake', '~> 0.8.7'
+  gem 'SystemTimer', :platforms => :ruby_18
+end

data/HISTORY

@@ -0,0 +1,7 @@
+== 1.0.0 / 2011-05-26
+  * Cache API responses in Redis from HTTParty requests
+  * Only cache APIs that have been registered with CacheBar.
+  * Stores response body as Redis string data type that is set to expire.
+  * Store a backup of responses incase the API service goes down.
+  * If an exception or timeout occurs and there is no backup an exception is raised.
+  * If a bad response is received the backup will be used if available otherwise the bad response will be returned

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Brian Landau of Viget Labs
+
+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.md

@@ -0,0 +1,102 @@
+# CacheBar
+
+CacheBar is a simple API caching layer built on top of Redis and HTTParty.
+
+When a good request is made to the API through an HTTParty module or class configured to be cached, it caches the response body in Redis. The cache is set to expire in the configured length of time. All following identical requests use the cache in Redis. When the cache expires it will attempt to refill the cache with a new good response. If though the response that comes back is bad (there was timeout, a 404, or some other problem), then CacheBar will fetch a backup response we also store in Redis (in a separate non-expiring hash). When it pulls this backup response out it inserts it into the standard cache and sets it to expire in 5 minutes. This way we won't look for a new good response for another 5 minutes.
+
+Using this gem does not mean that all your HTTParty modules and requests will be automatically cached. You will have to configure them on a case by case basis. This means you can have some APIs that are cached and others that aren't.
+
+## Install
+
+    gem install cachebar
+
+If you're on Ruby 1.8 it is recommended that you also install the SystemTimer gem:
+
+    gem install SystemTimer
+
+### Inside a Rails/Rack app:
+
+Add this to your Gemfile:
+
+    gem 'SystemTimer', :platforms => :ruby_18
+    gem 'cachebar'
+
+Follow the instructions below for configuring CacheBar.
+
+## Usage
+
+Although you can use CacheBar in any type of application, the examples provided will be for using it inside a Rails application.
+
+### 1. Configuring CacheBar
+
+There's a few configuration options to CacheBar, the first is specifying a Redis connection to use.
+
+If you have an initializer for defining your Redis connection already like this:
+
+    REDIS_CONFIG = YAML.load_file(Rails.root+'config/redis.yml')[Rails.env].freeze
+    redis = Redis.new(:host => REDIS_CONFIG['host'], :port => REDIS_CONFIG['port'],
+      :thread_safe => true, :db => REDIS_CONFIG['db'])
+    $redis = Redis::Namespace.new(REDIS_CONFIG['namespace'], :redis => redis)
+
+Then you can just add this:
+
+    HTTParty::HTTPCache.redis = $redis
+
+You'll then also want to turn on caching in the appropriate environments. For instance you'll want to add this to `config/environments/production.rb`:
+
+    HTTParty::HTTPCache.perform_caching = true
+
+CacheBar can also log useful information to your log file if you configure a logger for it:
+
+    HTTParty::HTTPCache.logger = Rails.logger
+
+By default we use a timeout of 5 seconds on all requests, this can be configured like so:
+
+    HTTParty::HTTPCache.timeout_length = 10 # seconds
+
+By default when we fallback to using a backup response, we then hold off looking for a new fresh response for 5 minutes, this can be configured like so:
+
+    HTTParty::HTTPCache.cache_stale_backup_time = 120 # 2 minutes
+
+### 2. Configuring an HTTParty module or class
+
+If you already have HTTParty included then you just need to use the `caches_api_responses` method to register that API for caching, and your done. The `caches_api_responses` takes a hash of options:
+
+* `host`* *optional*:
+  * This is used internally to decide which requests to try to cache responses for.
+    If you've defined `base_uri` on the class/module that HTTParty is included into then this option is not needed.
+* `key_name`:
+  * This is the name used in Redis to create a part of the cache key to easily differentiate it from other API caches.
+* `expire_in`:
+  * This determines how long the good API responses are cached for.
+
+Here's an example using Twitter:
+
+    module TwitterAPI
+      include HTTParty
+      base_uri 'https://api.twitter.com/1'
+      format :json
+
+      caches_api_responses :key_name => "twitter", :expire_in => 3600
+    end
+
+After that all Twitter API calls will be cached for an hour.
+
+If you want to cache an API that uses HTTParty but never includes HTTParty into a class or module, you can register the API like this:
+
+    CacheBar.register_api_to_cache('api.example.com', {:key_name => "example", :expire_in => 7200})
+
+
+## Contributing to CacheBar
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+## Copyright
+
+Copyright (c) 2011 Brian Landau. See LICENSE.txt for further details.

data/Rakefile

@@ -0,0 +1,45 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "cachebar"
+  gem.homepage = "http://github.com/vigetlabs/cachebar"
+  gem.license = "MIT"
+  gem.summary = %Q{A simple API caching layer built on top of HTTParty and Redis}
+  gem.description = %Q{A simple API caching layer built on top of HTTParty and Redis}
+  gem.email = "brian.landau@viget.com"
+  gem.authors = ["Brian Landau", "David Eisinger"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+  test.rcov_opts << '--exclude "gems/*"'
+  test.rcov_opts << '--sort coverage'
+  test.rcov_opts << '--only-uncovered'
+end
+
+task :default => :test

data/VERSION

@@ -0,0 +1 @@
+1.1.0

data/lib/cachebar.rb

@@ -0,0 +1,43 @@
+require 'ostruct'
+require 'httparty'
+require 'digest/md5'
+require 'active_support'
+require 'active_support/core_ext/module/aliasing'
+require 'active_support/core_ext/module/attribute_accessors'
+require 'active_support/core_ext/object/blank'
+if RUBY_VERSION.split('.')[1].to_i < 9
+  begin
+    require 'system_timer'
+  rescue LoadError
+    $stderr.puts "When running a Ruby version before 1.9 you should consider using SystemTimer with CacheBar"
+  end
+end
+require 'httparty/httpcache'
+
+module CacheBar
+  def self.register_api_to_cache(host, options)
+    raise ArgumentError, "You must provide a host that you are caching API responses for." if host.blank?
+
+    missing_options = ([:expire_in, :key_name] - options.keys)
+    if missing_options.present?
+      raise(ArgumentError, "Missing some required options: #{missing_options.join(", ")}")
+    end
+
+    HTTParty::HTTPCache.apis[host] = options
+  end
+
+  module ClassMethods
+    def caches_api_responses(options)
+      host = if base_uri.present?
+        URI.parse(base_uri).host
+      else
+        options.delete(:host)
+      end
+      CacheBar.register_api_to_cache(host, options)
+    end
+  end
+
+end
+
+HTTParty::ClassMethods.send(:include, CacheBar::ClassMethods)
+HTTParty::Request.send(:include, HTTParty::HTTPCache)

data/lib/httparty/httpcache.rb

@@ -0,0 +1,149 @@
+module HTTParty
+  module HTTPCache
+    class NoResponseError < StandardError; end
+
+    mattr_accessor  :perform_caching, 
+                    :apis,
+                    :logger, 
+                    :redis,
+                    :timeout_length, 
+                    :cache_stale_backup_time
+
+    self.perform_caching = false
+    self.apis = {}
+    self.timeout_length = 5 # 5 seconds
+    self.cache_stale_backup_time = 300 # 5 minutes
+
+    def self.included(base)
+      base.class_eval do
+        alias_method_chain :perform, :caching
+      end
+    end
+
+    def perform_with_caching
+      if cacheable?
+        if response_in_cache?
+          log_message("Retrieving response from cache")
+          response_from(response_body_from_cache)
+        else
+          validate
+          begin
+            httparty_response = timeout(timeout_length) do
+              perform_without_caching
+            end
+            httparty_response.parsed_response
+            if httparty_response.response.is_a?(Net::HTTPSuccess)
+              log_message("Storing good response in cache")
+              store_in_cache(httparty_response.body)
+              store_backup(httparty_response.body)
+              httparty_response
+            else
+              retrieve_and_store_backup(httparty_response)
+            end
+          rescue *exceptions
+            retrieve_and_store_backup
+          end
+        end
+      else
+        log_message("Caching off")
+        perform_without_caching
+      end
+    end
+
+    protected
+    
+    def cacheable?
+      HTTPCache.perform_caching && HTTPCache.apis.keys.include?(uri.host) &&
+        http_method == Net::HTTP::Get
+    end
+
+    def response_from(response_body)
+      HTTParty::Response.new(self, OpenStruct.new(:body => response_body), lambda {parse_response(response_body)})
+    end
+
+    def retrieve_and_store_backup(httparty_response = nil)
+      if backup_exists?
+        log_message('using backup')
+        response_body = backup_response
+        store_in_cache(response_body, cache_stale_backup_time)
+        response_from(response_body)
+      elsif httparty_response
+        httparty_response
+      else
+        log_message('No backup and bad response')
+        raise NoResponseError, 'Bad response from API server or timeout occured and no backup was in the cache'
+      end
+    end
+
+    def normalized_uri
+      return @normalized_uri if @normalized_uri
+      normalized_uri = uri.dup
+      normalized_uri.query = sort_query_params(normalized_uri.query)
+      normalized_uri.path.chop! if (normalized_uri.path =~ /\/$/)
+      normalized_uri.scheme = normalized_uri.scheme.downcase
+      @normalized_uri = normalized_uri.normalize.to_s
+    end
+
+    def sort_query_params(query)
+      query.split('&').sort.join('&') unless query.blank?
+    end
+
+    def cache_key_name
+      @cache_key_name ||= "api-cache:#{HTTPCache.apis[uri.host][:key_name]}:#{uri_hash}"
+    end
+
+    def uri_hash
+      @uri_hash ||= Digest::MD5.hexdigest(normalized_uri)
+    end
+
+    def response_in_cache?
+      redis.exists(cache_key_name)
+    end
+
+    def backup_key
+      "api-cache:#{HTTPCache.apis[uri.host][:key_name]}"
+    end
+
+    def backup_response
+      redis.hget(backup_key, uri_hash)
+    end
+
+    def backup_exists?
+      redis.exists(backup_key) && redis.hexists(backup_key, uri_hash)
+    end
+
+    def response_body_from_cache
+      redis.get(cache_key_name)
+    end
+
+    def store_in_cache(response_body, expires = nil)
+      redis.set(cache_key_name, response_body)
+      redis.expire(cache_key_name, (expires || HTTPCache.apis[uri.host][:expire_in]))
+    end
+
+    def store_backup(response_body)
+      redis.hset(backup_key, uri_hash, response_body)
+    end
+
+    def log_message(message)
+      logger.info("[HTTPCache]: #{message} for #{normalized_uri} - #{uri_hash.inspect}") if logger
+    end
+
+    def timeout(seconds, &block)
+      if defined?(SystemTimer)
+        SystemTimer.timeout_after(seconds, &block)
+      else
+        options[:timeout] = seconds
+        yield
+      end
+    end
+
+    def exceptions
+      if (RUBY_VERSION.split('.')[1].to_i >= 9) && defined?(Psych::SyntaxError)
+        [StandardError, Timeout::Error, Psych::SyntaxError]
+      else
+        [StandardError, Timeout::Error]
+      end
+    end
+  end
+end