httpadapter 0.2.1 → 1.0.0

data/CHANGELOG

@@ -1,3 +1,7 @@
+== 1.0.0
+
+* rewrite to expose important implementation-specific configuration stuff
+
 == 0.2.1
 
 * added mock adapter for testing

data/README.md

@@ -0,0 +1,48 @@
+# HTTPAdapter
+
+<dl>
+  <dt>Homepage</dt><dd><a href="http://httpadapter.rubyforge.org/">httpadapter.rubyforge.org</a></dd>
+  <dt>Author</dt><dd><a href="mailto:bobaman@google.com">Bob Aman</a></dd>
+  <dt>Copyright</dt><dd>Copyright © 2010 Google, Inc.</dd>
+  <dt>License</dt><dd>Apache 2.0</dd>
+</dl>
+
+# Description
+
+A library for translating HTTP request and response objects for various clients
+into a common representation.
+
+# Reference
+
+- {HTTPAdapter}
+
+# Adapters
+
+- {HTTPAdapter::NetHTTPAdapter}
+- {HTTPAdapter::RackAdapter}
+- {HTTPAdapter::TyphoeusAdapter}
+
+# Example Usage
+
+    adapter = HTTPAdapter::NetHTTPAdapter.new
+    response = Net::HTTP.start('www.google.com', 80) { |http| http.get('/') }
+    # => #<Net::HTTPOK 200 OK readbody=true>
+    result = adapter.adapt_response(response)
+    # => [
+    #   200,
+    #   [
+    #     ["Expires", "-1"],
+    #     ["Content-Type", "text/html; charset=ISO-8859-1"],
+    #     ["X-Xss-Protection", "1; mode=block"],
+    #     ["Server", "gws"],
+    #     ["Date", "Thu, 26 Aug 2010 22:13:03 GMT"],
+    #     ["Set-Cookie", "<snip>"],
+    #     ["Cache-Control", "private, max-age=0"],
+    #     ["Transfer-Encoding", "chunked"]
+    #   ],
+    #   ["<snip>"]
+    # ]
+
+# Install
+
+* sudo gem install httpadapter

data/lib/httpadapter.rb

@@ -15,83 +15,100 @@
 require 'httpadapter/version'
 require 'httpadapter/connection'
 
-module HTTPAdapter #:nodoc:
+##
+# A module which provides methods to aid in conversion of HTTP request and
+# response objects.  It uses tuples as a generic intermediary format.
+#
+# @example
+#   class StubAdapter
+#     include HTTPAdapter
+#   
+#     def convert_request_to_a(request_obj)
+#       return ['GET', '/', [], [""]] # Stubbed request tuple
+#     end
+#   
+#     def convert_request_from_a(request_ary)
+#       return Object.new # Stubbed request object
+#     end
+#   
+#     def convert_response_to_a(response_obj)
+#       return [200, [], ['']] # Stubbed response tuple
+#     end
+# 
+#     def convert_response_from_a(response_ary)
+#       return Object.new # Stubbed response object
+#     end
+# 
+#     def fetch_resource(request_ary, connection=nil)
+#       return [200, [], ['']] # Stubbed response tuple from server
+#     end
+#   end
+module HTTPAdapter
   ##
   # Converts an HTTP request object to a simple tuple.
   #
-  # @param [Object, #to_ary] request
-  #   The request object to be converted.  The request may either implement
-  #   the <code>#to_ary</code> method directly or alternately, an optional
-  #   adapter class may be provided.  The adapter must accept the request
-  #   object as a parameter and provide the <code>#to_ary</code> method.
+  # @param [Object] request
+  #   The request object to be converted.  The adapter must implement
+  #   the <code>#convert_request_to_a</code> method, which takes the request
+  #   object as a parameter.
   #
   # @return [Array] The tuple that the request was converted to.
-  def self.adapt_request(request, adapter=nil)
-    # Temporarily wrap the request if there's an adapter
-    request = adapter.new(request) if adapter
-    if request.respond_to?(:to_ary)
-      converted_request = request.to_ary
+  def adapt_request(request_obj)
+    if self.respond_to?(:convert_request_to_a)
+      converted_request = self.convert_request_to_a(request_obj)
     else
-      # Can't use #to_a because some versions of Ruby define #to_a on Object
       raise TypeError,
-        "Expected adapter or request to implement #to_ary."
+        'Expected adapter to implement #convert_request_to_a.'
     end
-    return self.verified_request(converted_request)
-  end
-
-  ##
-  # Converts an HTTP response object to a simple tuple.
-  #
-  # @param [Object, #to_ary] response
-  #   The response object to be converted.  The response may either implement
-  #   the <code>#to_ary</code> method directly or alternately, an optional
-  #   adapter class may be provided.  The adapter must accept the response
-  #   object as a parameter and provide the <code>#to_ary</code> method.
-  #
-  # @return [Array] The tuple that the reponse was converted to.
-  def self.adapt_response(response, adapter=nil)
-    # Temporarily wrap the response if there's an adapter
-    response = adapter.new(response) if adapter
-    if response.respond_to?(:to_ary)
-      converted_response = response.to_ary
-    else
-      # Can't use #to_a because some versions of Ruby define #to_a on Object
-      raise TypeError,
-        "Expected adapter or response to implement #to_ary."
-    end
-    return self.verified_response(converted_response)
+    return HTTPAdapter.verified_request(converted_request)
   end
 
   ##
   # Converts a tuple to a specific HTTP implementation's request format.
   #
-  # @param [Array] request
-  #   The request object to be converted.  The request object must be a tuple
+  # @param [Array] request_ary
+  #   The request array to be converted.  The request array must be a tuple
   #   with a length of 4.  The first element must be the request method.
   #   The second element must be the URI.  The URI may be relative.  The third
   #   element contains the headers.  It must respond to <code>#each</code> and
   #   iterate over the header names and values.  The fourth element must be
   #   the body.  It must respond to <code>#each</code> but may not be a
   #   <code>String</code>.  It should emit <code>String</code> objects.
-  # @param [#from_ary] adapter
-  #   The adapter object that will convert to a tuple.  It must respond to
-  #   <code>#from_ary</code>.  Typically a reference to a class is used.
   #
   # @return [Array] The implementation-specific request object.
-  def self.specialize_request(request, adapter)
-    request = self.verified_request(request)
-    if adapter.respond_to?(:from_ary)
-      return adapter.from_ary(request)
+  def specialize_request(request_ary)
+    request = HTTPAdapter.verified_request(request_ary)
+    if self.respond_to?(:convert_request_from_a)
+      return self.convert_request_from_a(request)
+    else
+      raise TypeError,
+        'Expected adapter to implement #convert_request_from_a.'
+    end
+  end
+
+  ##
+  # Converts an HTTP response object to a simple tuple.
+  #
+  # @param [Object] response
+  #   The response object to be converted.  The adapter must implement
+  #   the <code>#convert_response_to_a</code> method, which takes the response
+  #   object as a parameter.
+  #
+  # @return [Array] The tuple that the reponse was converted to.
+  def adapt_response(response_obj)
+    if self.respond_to?(:convert_response_to_a)
+      converted_response = self.convert_response_to_a(response_obj)
     else
       raise TypeError,
-        "Expected adapter to implement .from_ary."
+        'Expected adapter to implement #convert_response_to_a.'
     end
+    return HTTPAdapter.verified_response(converted_response)
   end
 
   ##
   # Converts a tuple to a specific HTTP implementation's response format.
   #
-  # @param [Array] response
+  # @param [Array] response_ary
   #   The response object to be converted.  The response object must be a
   #   tuple with a length of 3.  The first element must be the HTTP status
   #   code.  The second element contains the headers.  It must respond to
@@ -100,47 +117,41 @@ module HTTPAdapter #:nodoc:
   #   but may not be a <code>String</code>.  It should emit
   #   <code>String</code> objects. This is essentially the same format that
   #   Rack uses.
-  # @param [#from_ary] adapter
-  #   The adapter object that will convert to a tuple.  It must respond to
-  #   <code>#from_ary</code>.  Typically a reference to a class is used.
   #
   # @return [Array] The implementation-specific response object.
-  def self.specialize_response(response, adapter)
-    response = self.verified_response(response)
-    if adapter.respond_to?(:from_ary)
-      return adapter.from_ary(response)
+  def specialize_response(response_ary)
+    response_ary = HTTPAdapter.verified_response(response_ary)
+    if self.respond_to?(:convert_response_from_a)
+      return self.convert_response_from_a(response_ary)
     else
-      raise TypeError, 'Expected adapter to implement .from_ary.'
+      raise TypeError,
+        'Expected adapter to implement #convert_response_from_a.'
     end
   end
 
   ##
   # Transmits a request.
   #
-  # @param [Array] request
-  #   The request that will be sent.
-  # @param [#transmit] adapter
-  #   The adapter object that will perform the transmission of the HTTP
-  #   request.  It must respond to <code>#transmit</code>.  Typically a
-  #   reference to a class is used.
+  # @param [Array] request_ary
+  #   The request tuple that will be sent.
   # @param [HTTPAdapter::Connection] connection
   #   An object representing a connection.  This object represents an open
   #   HTTP connection that is used to make multiple HTTP requests.
   # @return [Array]
   #   The response given by the server.
   #
-  # @return [Array] The implementation-specific response object.
-  def self.transmit(request, adapter, connection=nil)
-    request = self.verified_request(request)
+  # @return [Array] A tuple representing the response from the server.
+  def transmit(request_ary, connection=nil)
+    request_ary = HTTPAdapter.verified_request(request_ary)
     if connection && !connection.kind_of?(HTTPAdapter::Connection)
       raise TypeError,
         "Expected HTTPAdapter::Connection, got #{connection.class}."
     end
-    if adapter.respond_to?(:transmit)
-      response = adapter.transmit(request, connection)
-      return self.verified_response(response)
+    if self.respond_to?(:fetch_resource)
+      response_ary = self.fetch_resource(request_ary, connection)
+      return HTTPAdapter.verified_response(response_ary)
     else
-      raise TypeError, 'Expected adapter to implement .transmit.'
+      raise TypeError, 'Expected adapter to implement .fetch_resource.'
     end
   end
 
@@ -187,7 +198,7 @@ module HTTPAdapter #:nodoc:
           headers << [header, value]
         end
       else
-        raise TypeError, "Expected headers to respond to #each."
+        raise TypeError, 'Expected headers to respond to #each.'
       end
       if body.kind_of?(String)
         raise TypeError,
@@ -197,11 +208,12 @@ module HTTPAdapter #:nodoc:
       # Can't verify that all chunks are Strings because #each may be
       # effectively destructive.
       if !body.respond_to?(:each)
-        raise TypeError, "Expected body to respond to #each."
+        raise TypeError, 'Expected body to respond to #each.'
       end
     else
       raise TypeError,
-        "Expected tuple of [method, uri, headers, body]."
+        "Expected tuple of [method, uri, headers, body], " +
+        "got #{request.inspect}."
     end
     return [method, uri, headers, body]
   end
@@ -240,7 +252,7 @@ module HTTPAdapter #:nodoc:
           headers << [header, value]
         end
       else
-        raise TypeError, "Expected headers to respond to #each."
+        raise TypeError, 'Expected headers to respond to #each.'
       end
       if body.kind_of?(String)
         raise TypeError,
@@ -250,11 +262,11 @@ module HTTPAdapter #:nodoc:
       # Can't verify that all chunks are Strings because #each may be
       # effectively destructive.
       if !body.respond_to?(:each)
-        raise TypeError, "Expected body to respond to #each."
+        raise TypeError, 'Expected body to respond to #each.'
       end
     else
       raise TypeError,
-        "Expected tuple of [status, headers, body]."
+        "Expected tuple of [status, headers, body], got #{response.inspect}."
     end
     return [status, headers, body]
   end

data/lib/httpadapter/adapters/mock.rb

@@ -14,22 +14,24 @@
 
 require 'httpadapter'
 
-module HTTPAdapter #:nodoc:
+module HTTPAdapter
   ##
   # A simple module for mocking the transmit method on an adapter.
   #
   # @example
   #   # Using RSpec, verify that the request being sent includes a user agent.
-  #   adapter = HTTPAdapter::MockAdapter.request_adapter do |req, conn|
-  #     method, uri, headers, body = req
+  #   adapter = HTTPAdapter::MockAdapter.create do |request_ary, connection|
+  #     method, uri, headers, body = request_ary
   #     headers.should be_any { |k, v| k.downcase == 'user-agent' }
   #   end
   module MockAdapter
-    def self.request_adapter(&block)
-      return Class.new do
+    def self.create(&block)
+      adapter = Class.new do
+        include HTTPAdapter
+
         @@block = block
 
-        def self.transmit(*params)
+        def fetch_resource(*params)
           response = @@block.call(*params)
           if response.respond_to?(:each)
             return response
@@ -38,6 +40,7 @@ module HTTPAdapter #:nodoc:
           end
         end
       end
+      return adapter.new
     end
   end
 end

data/lib/httpadapter/adapters/net_http.rb

@@ -18,7 +18,9 @@ require 'net/http'
 require 'addressable/uri'
 
 module HTTPAdapter #:nodoc:
-  class NetHTTPRequestAdapter
+  class NetHTTPAdapter
+    include HTTPAdapter
+
     METHOD_MAPPING = {
       # RFC 2616
       'OPTIONS' => Net::HTTP::Options,
@@ -38,116 +40,6 @@ module HTTPAdapter #:nodoc:
       'UNLOCK' => Net::HTTP::Unlock
     }
 
-    def initialize(request, options={})
-      unless request.kind_of?(Net::HTTPRequest)
-        raise TypeError, "Expected Net::HTTPRequest, got #{request.class}."
-      end
-      @request = request
-      @uri = Addressable::URI.parse(options[:uri] || request.path || "")
-      if !@uri.host && options[:host]
-        @uri.host = options[:host]
-        if !@uri.scheme && options[:scheme]
-          @uri.scheme = options[:scheme]
-        elsif !@uri.scheme
-          @uri.scheme = 'http'
-        end
-        if !@uri.port && options[:port]
-          @uri.port = options[:port]
-        end
-        @uri.scheme = @uri.normalized_scheme
-        @uri.authority = @uri.normalized_authority
-      end
-    end
-
-    def to_ary
-      method = @request.method.to_s.upcase
-      uri = @uri.to_str
-      headers = []
-      @request.canonical_each do |header, value|
-        headers << [header, value]
-      end
-      body = @request.body || ""
-      return [method, uri, headers, [body]]
-    end
-
-    def self.from_ary(array)
-      method, uri, headers, body = array
-      method = method.to_s.upcase
-      uri = Addressable::URI.parse(uri)
-      request_class = METHOD_MAPPING[method]
-      unless request_class
-        raise ArgumentError, "Unknown HTTP method: #{method}"
-      end
-      request = request_class.new(uri.request_uri)
-      headers.each do |header, value|
-        request[header] = value
-        if header.downcase == 'Content-Type'.downcase
-          request.content_type = value
-        end
-      end
-      merged_body = ""
-      body.each do |chunk|
-        merged_body += chunk
-      end
-      if merged_body.length > 0
-        request.body = merged_body
-      elsif ['POST', 'PUT'].include?(method)
-        request.content_length = 0
-      end
-      return request
-    end
-
-    def self.transmit(request, connection=nil)
-      method, uri, headers, body = request
-      uri = Addressable::URI.parse(uri)
-      net_http_request = self.from_ary([method, uri, headers, body])
-      net_http_response = nil
-      unless connection
-        http = Net::HTTP.new(uri.host, uri.inferred_port)
-        if uri.normalized_scheme == 'https'
-          require 'net/https'
-          http.use_ssl = true
-          if http.respond_to?(:enable_post_connection_check=)
-            http.enable_post_connection_check = true
-          end
-          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
-          store = OpenSSL::X509::Store.new
-          store.set_default_paths
-          http.cert_store = store
-          context = http.instance_variable_get('@ssl_context')
-          if context && context.respond_to?(:tmp_dh_callback) &&
-              context.tmp_dh_callback == nil
-            context.tmp_dh_callback = lambda do |*args|
-              tmp_dh_key_file = File.expand_path(
-                ENV['TMP_DH_KEY_FILE'] || "~/.dhparams.pem"
-              )
-              if File.exists?(tmp_dh_key_file)
-                OpenSSL::PKey::DH.new(File.read(tmp_dh_key_file))
-              else
-                # Slow, fix with `openssl dhparam -out ~/.dhparams.pem 2048`
-                OpenSSL::PKey::DH.new(512)
-              end
-            end
-          end
-        end
-        http.start
-        connection = HTTPAdapter::Connection.new(
-          uri.host, uri.inferred_port, http,
-          :open => [:start, [], nil],
-          :close => [:finish, [], nil]
-        )
-      else
-        http = nil
-      end
-      net_http_response = connection.connection.request(net_http_request)
-      if http
-        connection.close
-      end
-      return NetHTTPResponseAdapter.new(net_http_response).to_ary
-    end
-  end
-
-  class NetHTTPResponseAdapter
     STATUS_MESSAGES = {
       100 => "Continue",
       101 => "Switching Protocols",
@@ -205,25 +97,87 @@ module HTTPAdapter #:nodoc:
     }
     STATUS_MAPPING = Net::HTTPResponse::CODE_TO_OBJ
 
-    def initialize(response)
-      unless response.kind_of?(Net::HTTPResponse)
-        raise TypeError, "Expected Net::HTTPResponse, got #{response.class}."
+    def initialize(&block)
+      @connection_config = block
+    end
+
+    def convert_request_to_a(request_obj)
+      unless request_obj.kind_of?(Net::HTTPRequest)
+        raise TypeError, "Expected Net::HTTPRequest, got #{request_obj.class}."
       end
-      @response = response
+      method = request_obj.method.to_s.upcase
+      host_from_header = nil
+      scheme_from_header = nil
+      headers = []
+      request_obj.canonical_each do |header, value|
+        if header.downcase == 'X-Forwarded-Proto'.downcase
+          scheme_from_header = value
+        elsif header.downcase == 'Host'.downcase
+          host_from_header = value
+        end
+        headers << [header, value]
+      end
+      uri = Addressable::URI.parse(request_obj.path || "")
+      uri.host ||= host_from_header
+      if uri.host
+        uri.scheme ||= scheme_from_header || 'http'
+        uri.scheme = uri.normalized_scheme
+        uri.authority = uri.normalized_authority
+      end
+      uri = uri.to_str
+      body = request_obj.body || ""
+      return [method, uri, headers, [body]]
     end
 
-    def to_ary
-      status = @response.code.to_i
+    def convert_request_from_a(request_ary)
+      method, uri, headers, body = request_ary
+      method = method.to_s.upcase
+      host_from_header = nil
+      uri = Addressable::URI.parse(uri)
+      request_class = METHOD_MAPPING[method]
+      unless request_class
+        raise ArgumentError, "Unknown HTTP method: #{method}"
+      end
+      request = request_class.new(uri.request_uri)
+      headers.each do |header, value|
+        request[header] = value
+        if header.downcase == 'Content-Type'.downcase
+          request.content_type = value
+        elsif header.downcase == 'Host'.downcase
+          host_from_header = value
+        end
+      end
+      if host_from_header == nil && uri.host
+        request['Host'] = uri.host
+      end
+      merged_body = ""
+      body.each do |chunk|
+        merged_body += chunk
+      end
+      if merged_body.length > 0
+        request.body = merged_body
+      elsif ['POST', 'PUT'].include?(method)
+        request.content_length = 0
+      end
+      return request
+    end
+
+    def convert_response_to_a(response_obj)
+      unless response_obj.kind_of?(Net::HTTPResponse)
+        raise TypeError,
+          "Expected Net::HTTPResponse, got #{response_obj.class}."
+      end
+      status = response_obj.code.to_i
       headers = []
-      @response.canonical_each do |header, value|
+      response_obj.canonical_each do |header, value|
         headers << [header, value]
       end
-      body = @response.body || ""
+      body = response_obj.body || ""
       return [status, headers, [body]]
     end
 
-    def self.from_ary(array)
-      status, headers, body = array
+    def convert_response_from_a(response_ary)
+      status, headers, body = response_ary
       message = STATUS_MESSAGES[status.to_i]
       response_class = STATUS_MAPPING[status.to_s]
       unless message && response_class
@@ -245,5 +199,55 @@ module HTTPAdapter #:nodoc:
 
       return response
     end
+
+    def fetch_resource(request_ary, connection=nil)
+      method, uri, headers, body = request_ary
+      uri = Addressable::URI.parse(uri)
+      net_http_request = self.convert_request_from_a(
+        [method, uri, headers, body]
+      )
+      net_http_response = nil
+      unless connection
+        http = Net::HTTP.new(uri.host, uri.inferred_port)
+        if uri.normalized_scheme == 'https'
+          require 'net/https'
+          http.use_ssl = true
+          if http.respond_to?(:enable_post_connection_check=)
+            http.enable_post_connection_check = true
+          end
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          ca_file = File.expand_path(ENV['CA_FILE'] || '~/.cacert.pem')
+          if File.exists?(ca_file)
+            http.ca_file = ca_file
+          end
+          store = OpenSSL::X509::Store.new
+          store.set_default_paths
+          http.cert_store = store
+          context = http.instance_variable_get('@ssl_context')
+          if context && context.respond_to?(:tmp_dh_callback)
+            # Fix for annoying warning
+            context.tmp_dh_callback ||= lambda {}
+          end
+        end
+        connection = HTTPAdapter::Connection.new(
+          uri.host, uri.inferred_port, http,
+          :open => [:start, [], nil],
+          :close => [:finish, [], nil]
+        )
+      else
+        http = nil
+      end
+      if @connection_config
+        @connection_config.call(connection)
+      end
+      if connection.connection && !connection.connection.active?
+        connection.connection.start
+      end
+      net_http_response = connection.connection.request(net_http_request)
+      if http
+        connection.close
+      end
+      return self.convert_response_to_a(net_http_response)
+    end
   end
 end