faraday-stack 0.1.0

data/README.md

@@ -0,0 +1,61 @@
+# Über Stack
+
+[Faraday][] is an HTTP client lib that provides a common interface over many adapters (such as Net::HTTP) and embraces the concept of Rack middleware when processing the request/response cycle.
+
+*“Faraday Stack”* is an add-on library that implements several middleware (such as JSON and XML parsers) and helps you build an awesome stack that covers most of your API-consuming needs.
+
+Boring example:
+
+    require 'faraday_stack'
+    
+    response = FaradayStack.get 'http://google.com'
+    
+    response.headers['content-type']  #=> "text/html; charset=UTF-8"
+    response.headers['location']      #=> "http://www.google.com/"
+    puts response.body
+
+Awesome example:
+
+    conn = FaradayStack.build 'http://github.com/api/v2'
+    
+    # JSON resource
+    resp = conn.get 'json/repos/show/mislav/faraday-stack'
+    resp.body
+    #=> {"repository"=>{"language"=>"Ruby", "fork"=>false, ...}}
+    
+    # XML resource
+    resp = conn.get 'xml/repos/show/mislav/faraday-stack'
+    resp.body.class
+    #=> Nokogiri::XML::Document
+    
+    # 404
+    conn.get 'zomg/wrong/url'
+    #=> raises Faraday::Error::ResourceNotFound
+
+## Features
+
+* parses JSON, XML & HTML
+* raises exceptions on 4xx, 5xx responses
+* follows redirects
+
+Optional features:
+
+* encode POST/PUT bodies as JSON:
+      
+        conn.post(path, payload, :content_type => 'application/json')
+
+* add `Instrumentation` middleware to instrument requests with ActiveSupport
+      
+        conn.builder.insert_after Faraday::Response::RaiseError, FaradayStack::Instrumentation
+
+* add `Caching` middleware to have GET responses cached
+      
+        conn.builder.insert_before FaradayStack::ResponseJSON, FaradayStack::Caching do
+          ActiveSupport::Cache::FileStore.new 'tmp/cache',
+            :namespace => 'faraday', :expires_in => 3600
+        end
+
+To see how the default stack is built, see "[faraday_stack.rb][source]".
+
+[faraday]: https://github.com/technoweenie/faraday
+[source]: https://github.com/mislav/faraday-stack/blob/master/lib/faraday_stack.rb

data/lib/faraday-stack.rb

@@ -0,0 +1 @@
+require 'faraday_stack'

data/lib/faraday_stack/addressable_patch.rb

@@ -0,0 +1,18 @@
+require 'addressable/uri'
+
+# fix `normalized_query` by sorting query key-value pairs
+# (rejected: https://github.com/sporkmonger/addressable/issues/28)
+class Addressable::URI
+  class << self
+    alias old_normalize_component normalize_component
+    
+    def normalize_component(component, character_class = CharacterClasses::RESERVED + CharacterClasses::UNRESERVED)
+      normalized = old_normalize_component(component, character_class)
+      if character_class == Addressable::URI::CharacterClasses::QUERY
+        pairs = normalized.split('&').sort_by { |pair| pair[0, pair.index('=') || pair.length] }
+        normalized = pairs.join('&')
+      end
+      normalized
+    end
+  end
+end

data/lib/faraday_stack/caching.rb

@@ -0,0 +1,58 @@
+module FaradayStack
+  class Caching < Faraday::Middleware
+    attr_reader :cache
+    
+    def initialize(app, cache = nil, options = {})
+      super(app)
+      @cache = cache || Proc.new.call
+      @options = options
+    end
+    
+    def call(env)
+      if :get == env[:method]
+        if env[:parallel_manager]
+          # callback mode
+          cache_on_complete(env)
+        else
+          # synchronous mode
+          response = cache.fetch(cache_key(env)) { @app.call(env) }
+          finalize_response(response, env)
+        end
+      else
+        @app.call(env)
+      end
+    end
+    
+    def cache_key(env)
+      url = env[:url]
+      if params_to_strip.any?
+        url = url.dup
+        url.query_values = url.query_values.reject { |k,| params_to_strip.include? k }
+        url.normalize!
+      else
+        url = url.normalize
+      end
+      url.request_uri
+    end
+    
+    def params_to_strip
+      @params_to_strip ||= Array(@options[:strip_params]).map { |p| p.to_s }
+    end
+    
+    def cache_on_complete(env)
+      key = cache_key(env)
+      if cached_response = cache.read(key)
+        finalize_response(cached_response, env)
+      else
+        response = @app.call(env)
+        response.on_complete { cache.write(key, response) }
+      end
+    end
+    
+    def finalize_response(response, env)
+      response = env[:response] = response.dup if response.frozen?
+      response.apply_request env unless response.env[:method]
+      response
+    end
+  end
+end

data/lib/faraday_stack/follow_redirects.rb

@@ -0,0 +1,43 @@
+module FaradayStack
+  class RedirectLimitReached < Faraday::Error::ClientError
+    attr_reader :response
+    
+    def initialize(response)
+      super "too many redirects; last one to: #{response['location']}"
+      @response = response
+    end
+  end
+  
+  class FollowRedirects < Faraday::Middleware
+    # TODO: 307
+    REDIRECTS = [301, 302, 303]
+    # default value for max redirects followed
+    FOLLOW_LIMIT = 3
+    
+    def initialize(app, options = {})
+      super(app)
+      @options = options
+      @follow_limit = options[:limit] || FOLLOW_LIMIT
+    end
+    
+    def call(env)
+      process_response(@app.call(env), @follow_limit)
+    end
+    
+    def process_response(response, follows)
+      response.on_complete do |env|
+        if redirect? response
+          raise RedirectLimitReached, response if follows.zero?
+          env[:url] += response['location']
+          env[:method] = :get
+          response = process_response(@app.call(env), follows - 1)
+        end
+      end
+      response
+    end
+    
+    def redirect?(response)
+      REDIRECTS.include? response.status
+    end
+  end
+end

data/lib/faraday_stack/instrumentation.rb

@@ -0,0 +1,26 @@
+module FaradayStack
+  # Measures request time only in synchronous request mode.
+  # Sample subscriber:
+  #
+  #   ActiveSupport::Notifications.subscribe('request.faraday') do |name, start_time, end_time, _, env|
+  #     url = env[:url]
+  #     http_method = env[:method].to_s.upcase
+  #     duration = end_time - start_time
+  #     $stderr.puts '[%s] %s %s (%.3f s)' % [url.host, http_method, url.request_uri, duration]
+  #   end
+  class Instrumentation < Faraday::Middleware
+    dependency 'active_support/notifications'
+    
+    def initialize(app, options = {})
+      super(app)
+      @options = options
+      @name = options[:name] || 'request.faraday'
+    end
+    
+    def call(env)
+      ActiveSupport::Notifications.instrument(@name, env) do
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/faraday_stack/rack_compatible.rb

@@ -0,0 +1,76 @@
+require 'stringio'
+
+module FaradayStack
+  # Wraps a handler originally written for Rack to make it compatible with Faraday.
+  #
+  # Experimental. Only handles changes in request headers.
+  class RackCompatible
+    def initialize(app, rack_handler, *args)
+      # tiny middleware that decomposes a Faraday::Response to standard Rack
+      # array: [status, headers, body]
+      compatible_app = lambda do |env|
+        restore_env(env)
+        response = app.call(env)
+        [response.status, response.headers, Array(response.body)]
+      end
+      @rack = rack_handler.new(compatible_app, *args)
+    end
+    
+    def call(env)
+      prepare_env(env)
+      rack_response = @rack.call(env)
+      finalize_response(env, rack_response)
+    end
+    
+    NonPrefixedHeaders = %w[CONTENT_LENGTH CONTENT_TYPE]
+    
+    # faraday to rack-compatible
+    def prepare_env(env)
+      env[:request_headers].each do |name, value|
+        name = name.upcase.tr('-', '_')
+        name = "HTTP_#{name}" unless NonPrefixedHeaders.include? name
+        env[name] = value
+      end
+      
+      url = env[:url]
+      env['rack.url_scheme'] = url.scheme
+      env['PATH_INFO'] = url.path
+      env['SERVER_PORT'] = url.inferred_port
+      env['QUERY_STRING'] = url.query
+      env['REQUEST_METHOD'] = env[:method].to_s.upcase
+      
+      env['rack.errors'] ||= StringIO.new
+      
+      env
+    end
+    
+    # rack to faraday-compatible
+    def restore_env(env)
+      headers = env[:request_headers]
+      headers.clear
+      
+      env.each do |name, value|
+        next unless String === name
+        if NonPrefixedHeaders.include? name or name.index('HTTP_') == 0
+          name = name.sub(/^HTTP_/).downcase.tr('_', '-')
+          headers[name] = value
+        end
+      end
+      
+      env[:method] = env['REQUEST_METHOD'].downcase.to_sym
+      env
+    end
+    
+    def finalize_response(env, rack_response)
+      status, headers, body = rack_response
+      body = body.inject('') { |str, part| str << part }
+      headers = Faraday::Utils::Headers.new(headers) unless Faraday::Utils::Headers === headers
+      
+      response_env = { :status => status, :body => body, :response_headers => headers }
+      
+      env[:response] ||= Faraday::Response.new({})
+      env[:response].env.update(response_env)
+      env[:response]
+    end
+  end
+end

data/lib/faraday_stack/response_html.rb

@@ -0,0 +1,12 @@
+module FaradayStack
+  class ResponseHTML < ResponseMiddleware
+    dependency do
+      require 'nokogiri'
+      Nokogiri::HTML
+    end
+    
+    define_parser do |body|
+      Nokogiri::HTML body
+    end
+  end
+end

data/lib/faraday_stack/response_json.rb

@@ -0,0 +1,32 @@
+module FaradayStack
+  class ResponseJSON < ResponseMiddleware
+    adapter_name = nil
+
+    # loads the JSON decoder either from yajl-ruby or activesupport
+    dependency do
+      require 'yajl'
+      adapter_name = Yajl::Parser.name
+    end
+
+    dependency do
+      require 'active_support/json/decoding'
+      adapter_name = ActiveSupport::JSON.name
+    end unless loaded?
+
+    # defines a parser block depending on which adapter has loaded
+    case adapter_name
+    when 'Yajl::Parser'
+      define_parser do |body|
+        Yajl::Parser.parse(body)
+      end
+    when 'ActiveSupport::JSON'
+      define_parser do |body|
+        unless body.nil? or body.empty?
+          result = ActiveSupport::JSON.decode(body)
+          raise ActiveSupport::JSON.backend::ParseError if String === result
+          result
+        end
+      end
+    end
+  end
+end

data/lib/faraday_stack/response_middleware.rb

@@ -0,0 +1,64 @@
+module FaradayStack
+  # A base class for middleware that parses responses
+  class ResponseMiddleware < Faraday::Response::Middleware
+    CONTENT_TYPE = 'Content-Type'.freeze
+
+    class << self
+      attr_accessor :parser
+    end
+
+    # Stores a block that receives the body and should return a parsed result
+    def self.define_parser(&block)
+      @parser = block
+    end
+
+    def self.inherited(subclass)
+      super
+      subclass.load_error = self.load_error
+      subclass.parser = self.parser
+    end
+
+    def initialize(app = nil, options = {})
+      super(app)
+      @options = options
+      @content_types = Array(options[:content_type])
+    end
+
+    # Override this to modify the environment after the response has finished.
+    def on_complete(env)
+      if process_response_type?(response_type(env)) and parse_response?(env)
+        env[:body] = parse(env[:body])
+      end
+    end
+
+    # Parses the response body and returns the result.
+    # Instead of overriding this method, consider using `define_parser`
+    def parse(body)
+      if self.class.parser
+        begin
+          self.class.parser.call(body)
+        rescue
+          raise Faraday::Error::ParsingError, $!
+        end
+      else
+        body
+      end
+    end
+
+    def response_type(env)
+      type = env[:response_headers][CONTENT_TYPE].to_s
+      type = type.split(';', 2).first if type.index(';')
+      type
+    end
+    
+    def process_response_type?(type)
+      @content_types.empty? or @content_types.any? { |pattern|
+        Regexp === pattern ? type =~ pattern : type == pattern
+      }
+    end
+    
+    def parse_response?(env)
+      env[:body].respond_to? :to_str
+    end
+  end
+end

data/lib/faraday_stack/response_xml.rb

@@ -0,0 +1,12 @@
+module FaradayStack
+  class ResponseXML < ResponseMiddleware
+    dependency do
+      require 'nokogiri'
+      Nokogiri::XML
+    end
+    
+    define_parser do |body|
+      Nokogiri::XML body
+    end
+  end
+end

data/lib/faraday_stack.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+require 'faraday'
+require 'forwardable'
+require 'faraday_stack/addressable_patch'
+
+module FaradayStack
+  extend Faraday::AutoloadHelper
+  
+  autoload_all 'faraday_stack',
+    :ResponseMiddleware => 'response_middleware',
+    :ResponseJSON => 'response_json',
+    :ResponseXML => 'response_xml',
+    :ResponseHTML => 'response_html',
+    :Instrumentation => 'instrumentation',
+    :Caching => 'caching',
+    :FollowRedirects => 'follow_redirects',
+    :RackCompatible => 'rack_compatible'
+  
+  # THE ÜBER STACK
+  def self.default_connection
+    @default_connection ||= self.build
+  end
+  
+  class << self
+    extend Forwardable
+    attr_writer :default_connection
+    def_delegators :default_connection, :get, :post, :put, :head, :delete
+  end
+  
+  def self.build(url = nil, options = {})
+    Faraday::Connection.new(url, options) do |builder|
+      builder.request :url_encoded
+      builder.request :json
+      yield builder if block_given?
+      builder.use ResponseXML,  :content_type => /[+\/]xml$/
+      builder.use ResponseHTML, :content_type => 'text/html'
+      builder.use ResponseJSON, :content_type => 'application/json'
+      builder.use FollowRedirects
+      builder.response :raise_error
+      builder.adapter Faraday.default_adapter
+    end
+  end
+end

data/test/caching_test.rb

@@ -0,0 +1,120 @@
+require 'test_helper'
+require 'forwardable'
+require 'fileutils'
+require 'rack/cache'
+
+class CachingTest < Test::Unit::TestCase
+  class TestCache < Hash
+    def read(key)
+      if cached = self[key]
+        Marshal.load(cached)
+      end
+    end
+    
+    def write(key, data)
+      self[key] = Marshal.dump(data)
+    end
+    
+    def fetch(key)
+      read(key) || yield.tap { |data| write(key, data) }
+    end
+  end
+  
+  def setup
+    @cache = TestCache.new
+    
+    request_count = 0
+    response = lambda { |env|
+      [200, {'Content-Type' => 'text/plain'}, "request:#{request_count+=1}"]
+    }
+    
+    @conn = Faraday.new do |b|
+      b.use FaradayStack::Caching, @cache
+      b.adapter :test do |stub|
+        stub.get('/', &response)
+        stub.get('/?foo=bar', &response)
+        stub.post('/', &response)
+        stub.get('/other', &response)
+      end
+    end
+  end
+
+  extend Forwardable
+  def_delegators :@conn, :get, :post
+  
+  def test_cache_get
+    assert_equal 'request:1', get('/').body
+    assert_equal 'request:1', get('/').body
+    assert_equal 'request:2', get('/other').body
+    assert_equal 'request:2', get('/other').body
+  end
+  
+  def test_response_has_request_params
+    get('/') # make cache
+    response = get('/')
+    assert_equal :get, response.env[:method]
+    assert_equal '/', response.env[:url].to_s
+  end
+  
+  def test_cache_query_params
+    assert_equal 'request:1', get('/').body
+    assert_equal 'request:2', get('/?foo=bar').body
+    assert_equal 'request:2', get('/?foo=bar').body
+    assert_equal 'request:1', get('/').body
+  end
+  
+  def test_doesnt_cache_post
+    assert_equal 'request:1', post('/').body
+    assert_equal 'request:2', post('/').body
+    assert_equal 'request:3', post('/').body
+  end
+end
+
+# RackCompatible + Rack::Cache
+class HttpCachingTest < Test::Unit::TestCase
+  include FileUtils
+  
+  CACHE_DIR = File.expand_path('../cache', __FILE__)
+  
+  def setup
+    rm_r CACHE_DIR if File.exists? CACHE_DIR
+
+    request_count = 0
+    response = lambda { |env|
+      [200, { 'Content-Type' => 'text/plain',
+              'Cache-Control' => 'public, max-age=900',
+            },
+            "request:#{request_count+=1}"]
+    }
+    
+    @conn = Faraday.new do |b|
+      b.use FaradayStack::RackCompatible, Rack::Cache::Context,
+        :metastore   => "file:#{CACHE_DIR}/rack/meta",
+        :entitystore => "file:#{CACHE_DIR}/rack/body",
+        :verbose     => true
+
+      b.adapter :test do |stub|
+        stub.get('/', &response)
+        stub.post('/', &response)
+      end
+    end
+  end
+
+  extend Forwardable
+  def_delegators :@conn, :get, :post
+  
+  def test_cache_get
+    assert_equal 'request:1', get('/').body
+    response = get('/')
+    assert_equal 'request:1', response.body
+    assert_equal 'text/plain', response['content-type']
+    
+    assert_equal 'request:2', post('/').body
+  end
+  
+  def test_doesnt_cache_post
+    assert_equal 'request:1', get('/').body
+    assert_equal 'request:2', post('/').body
+    assert_equal 'request:3', post('/').body
+  end
+end

data/test/follow_redirects_test.rb

@@ -0,0 +1,33 @@
+require 'test_helper'
+require 'forwardable'
+
+class FollowRedirectsTest < Test::Unit::TestCase
+  def setup
+    @conn = Faraday.new do |b|
+      b.use FaradayStack::FollowRedirects
+      b.adapter :test do |stub|
+        stub.get('/')        { [301, {'Location' => '/found'}, ''] }
+        stub.post('/create') { [302, {'Location' => '/'}, ''] }
+        stub.get('/found')   { [200, {'Content-Type' => 'text/plain'}, 'fin'] }
+        stub.get('/loop')    { [302, {'Location' => '/loop'}, ''] }
+      end
+    end
+  end
+
+  extend Forwardable
+  def_delegators :@conn, :get, :post
+  
+  def test_redirected
+    assert_equal 'fin', get('/').body
+  end
+  
+  def test_redirected_twice
+    assert_equal 'fin', post('/create').body
+  end
+  
+  def test_redirect_limit
+    assert_raises FaradayStack::RedirectLimitReached do
+      get('/loop')
+    end
+  end
+end

data/test/response_middleware_test.rb

@@ -0,0 +1,72 @@
+require 'test_helper'
+
+class ResponseMiddlewareTest < Test::Unit::TestCase
+  def setup
+    @json_handler = FaradayStack::ResponseJSON
+    @conn = Faraday.new do |b|
+      b.use @json_handler
+      b.adapter :test do |stub|
+        stub.get('json')      { [200, {'Content-Type' => 'application/json; charset=utf-8'}, "[1,2,3]"] }
+        stub.get('blank')     { [200, {'Content-Type' => 'application/json'}, ''] }
+        stub.get('nil')       { [200, {'Content-Type' => 'application/json'}, nil] }
+        stub.get('bad_json')  { [200, {'Content-Type' => 'application/json'}, '<body></body>']}
+        stub.get('non_json')  { [200, {'Content-Type' => 'text/html'}, '<body></body>']}
+      end
+    end
+  end
+
+  def process_only(*types)
+    @conn.builder.swap @json_handler, @json_handler, :content_type => types
+  end
+
+  def test_uses_json_to_parse_json_content
+    response = @conn.get('json')
+    assert response.success?
+    assert_equal [1,2,3], response.body
+  end
+
+  def test_uses_json_to_parse_json_content_conditional
+    process_only('application/json')
+    response = @conn.get('json')
+    assert response.success?
+    assert_equal [1,2,3], response.body
+  end
+
+  def test_uses_json_to_parse_json_content_conditional_with_regexp
+    process_only(%r{/(x-)?json$})
+    response = @conn.get('json')
+    assert response.success?
+    assert_equal [1,2,3], response.body
+  end
+
+  def test_uses_json_to_skip_blank_content
+    response = @conn.get('blank')
+    assert response.success?
+    assert_nil response.body
+  end
+
+  def test_uses_json_to_skip_nil_content
+    response = @conn.get('nil')
+    assert response.success?
+    assert_nil response.body
+  end
+
+  def test_uses_json_to_raise_Faraday_Error_Parsing_with_no_json_content
+    assert_raises Faraday::Error::ParsingError do
+      @conn.get('bad_json')
+    end
+  end
+  
+  def test_non_json_response
+    assert_raises Faraday::Error::ParsingError do
+      @conn.get('non_json')
+    end
+  end
+  
+  def test_non_json_response_conditional
+    process_only('application/json')
+    response = @conn.get('non_json')
+    assert_equal 'text/html', response.headers['Content-Type']
+    assert_equal '<body></body>', response.body
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,2 @@
+require 'test/unit'
+require 'faraday_stack'

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: faraday-stack
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Mislav Marohnić
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-04-01 00:00:00.000000000 +02:00
+default_executable: 
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: &2164745380 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2164745380
+description: 
+email: mislav.marohnic@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/faraday-stack.rb
+- lib/faraday_stack/addressable_patch.rb
+- lib/faraday_stack/caching.rb
+- lib/faraday_stack/follow_redirects.rb
+- lib/faraday_stack/instrumentation.rb
+- lib/faraday_stack/rack_compatible.rb
+- lib/faraday_stack/response_html.rb
+- lib/faraday_stack/response_json.rb
+- lib/faraday_stack/response_middleware.rb
+- lib/faraday_stack/response_xml.rb
+- lib/faraday_stack.rb
+- test/caching_test.rb
+- test/follow_redirects_test.rb
+- test/response_middleware_test.rb
+- test/test_helper.rb
+- README.md
+has_rdoc: false
+homepage: https://github.com/mislav/faraday-stack
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.5.3
+signing_key: 
+specification_version: 3
+summary: Great Faraday stack for consuming all kinds of APIs
+test_files: []