softwaregravy-net-http-persistent 2.6

data/.autotest

@@ -0,0 +1,7 @@
+# -*- ruby -*-
+
+require 'autotest/restart'
+
+Autotest.add_hook :initialize do |at|
+  at.testlib = 'minitest/unit'
+end

data/History.txt

@@ -0,0 +1,257 @@
+=== 2.6 / 2010-03-26
+
+* Minor enhancement
+  * Net::HTTP::Persistent#idle_timeout may be set to nil to disable expiration
+    of connections.  Pull Request #21 by Aaron Stone
+
+=== 2.5.2 / 2012-02-13
+
+* Bug fix
+  * Fix variable shadowing warning.
+
+=== 2.5.1 / 2012-02-10
+
+* Bug fix
+  * Reusing SSL connections with HTTP proxies now works.  Issue #15 by Paul
+    Ingham and mcrmfc
+
+=== 2.5 / 2012-02-07
+
+* Minor enhancements
+  * The proxy may be changed at any time.
+  * The allowed SSL version may now be set via #ssl_version.
+    Issue #16 by astera
+  * Added Net::HTTP::Persistent#override_headers which allows overriding
+  * Net::HTTP default headers like User-Agent.  See
+    Net::HTTP::Persistent@Headers for details.  Issue #17 by andkerosine
+
+* Bug fixes
+  * The ruby 1.8 speed monkeypatch now handles EAGAIN for windows users.
+    Issue #12 by Alwyn Schoeman
+  * Fixed POST example in README.  Submitted by injekt.
+  * Fixed various bugs in the shutdown of connections especially cross-thread
+    (which you shouldn't be doing anyways).
+
+=== 2.4.1 / 2012-02-03
+
+* Bug fixes
+  * When FakeWeb or WebMock are loaded SSL sessions will not be reused to
+    prevent breakage of testing frameworks.  Issue #13 by Matt Brictson, pull
+    request #14 by Zachary Scott
+  * SSL connections are reset when the SSL parameters change.
+    Mechanize issue #194 by dsisnero
+  * Last-use times are now cleaned up in #shutdown.
+
+=== 2.4 / 2012-01-31
+
+* Minor enhancement
+  * net-http-persistent now complains if OpenSSL::SSL::VERIFY_PEER is equal to
+    OpenSSL::SSL::VERIFY_NONE.  If you have a platform that is broken this way
+    you must define the constant:
+
+      I_KNOW_THAT_OPENSSL_VERIFY_PEER_EQUALS_VERIFY_NONE_IS_WRONG = nil
+
+    at the top level of your application to disable the warning.
+
+* Bug fix
+  * Fix persisting SSL sessions through HTTP proxies.  Mechanize issue #178 by
+    Robert Poor, net-http-persistent issues #10, #11.
+
+=== 2.3.2 / 2011-12-21
+
+* Bug fix
+  * Finish connections that were closed by Net::HTTP so they can be restarted.
+
+=== 2.3.1 / 2011-10-26
+
+* Bug fix
+  * If a request object already contains a Connection header it will no longer
+    be overridden.  This allows keep-alive connections to be disabled on a
+    per-request basis.
+
+=== 2.3 / 2011-10-25
+
+* Minor Enhancement
+  * The time since last use for a connection is now recorded in error
+    messages for the connection.
+
+=== 2.2 / 2011-10-24
+
+* Minor Enhancements
+  * Added timeouts for idle connections which are set through #idle_timeout.
+    The default timeout is 5 seconds.  Reducing the idle timeout is preferred
+    over setting #retry_change_requests to true if you wish to avoid the "too
+    many connection resets" error when POSTing data.
+  * Documented tunables and settings in one place in Net::HTTP::Persistent
+
+=== 2.1 / 2011-09-19
+
+* Minor Enhancement
+  * For HTTPS connections, SSL sessions are now reused avoiding the extra
+    round trips and computations of extra SSL handshakes.  If you have
+    problems with SSL session reuse it can be disabled by
+    Net::HTTP::Persistent#reuse_ssl_sessions
+
+* Bug Fixes
+  * The default certificate store is now used even if #verify_mode was not
+    set.  Issue #7, Pull Request #8 by Matthew M. Boedicker
+
+=== 2.0 / 2011-08-26
+
+* Incompatibility
+  * Net::HTTP::Persistent#verify_mode now defaults to
+    OpenSSL::SSL::VERIFY_PEER.  This may cause HTTPS request failures if your
+    default certificate store lacks the correct certificates.
+
+=== 1.9 / 2011-08-26
+
+* Minor Enhancement
+  * Added Net::HTTP::Persistent#cert_store to set an SSL certificate store
+    which defaults to the OpenSSL default certificate store.
+
+    HTTPS server certificates will be validated when this option is combined
+    with setting Net::HTTP::Persistent#verify_mode to
+    OpenSSL::SSL::VERIFY_PEER.
+
+=== 1.8.1 / 2011-08-08
+
+* Bug Fix
+  * Requests with OpenSSL errors are retried now.  Pull Request #5 by James
+    Tucker.
+
+=== 1.8 / 2011-06-27
+
+* Minor Enhancement
+  * Added Net::HTTP::Persistent#retry_change_requests which allows POST and
+    other non-idempotent requests to be retried automatically.  Take care when
+    enabling this option to ensure the server will handle multiple POSTs with
+    the same data in a sane manner.
+
+=== 1.7 / 2011-04-17
+
+* Minor Enhancement
+  * Added Net::HTTP::Persistent#pipeline which integrates with
+    net-http-pipeline when it is present.
+* Bug Fix
+  * Perform a case-insensitive check of the URI scheme for HTTPS URIs
+
+=== 1.6.1 / 2011-03-08
+
+* Bug Fix
+  * Net::HTTP::Persistent#request now handles Errno::EINVAL as a connection
+    reset and will be retried for idempotent requests.  Reported by Aaron
+    Qian.
+
+=== 1.6 / 2011-03-01
+
+* Minor Enhancement
+  * Added Net::HTTP::Persistent#socket_options to set multiple socket options
+    at socket startup.
+
+=== 1.5.2 / 2011-02-24
+
+* Bug Fix
+  * Only set TCP_NODELAY if the connection has an @socket.  Allows
+    net-http-persistent to be used with fake_web.  Reported by Sathish
+    Pasupunuri.
+
+=== 1.5.1 / 2011-02-10
+
+* Bug fix
+  * Only set TCP_NODELAY at connection start.  Reported by Brian Henderson.
+
+=== 1.5 / 2011-01-25
+
+* Minor Enhancements
+  * Set TCP_NODELAY on created socket if possible.  (This will only help for
+    requests that send bodies.)
+
+=== 1.4.1 / 2010-10-13
+
+* Bug Fixes
+  * Don't finish the connection when we're retrying, reset it.  Patch by James
+    Tucker.
+
+=== 1.4 / 2010-09-29
+
+* Minor Enhancements
+  * Added the very dangerous #shutdown_in_all_threads.  IT IS DANGEROUS!.
+    Patch by Torsten Schönebaum.
+
+=== 1.3.1 / 2010-09-13
+
+* Bug Fixes
+  * #connection_for no longer tries to ssl-enable an existing connection.
+    Patch by Joseph West.
+
+=== 1.3 / 2010-09-08
+
+* Minor Enhancements
+  * HTTP versions are now recorded.  This information is not currently used.
+
+* Bug Fixes
+  * #shutdown no longer fails when an unstarted HTTP connection is shut down.
+
+=== 1.2.5 / 2010-07-27
+
+* Bug Fixes
+  * Fix duplicated test name.  Noted by Peter Higgins.
+  * #shutdown now works even when no connections were made.
+
+=== 1.2.4 / 2010-07-26
+
+* Bug Fixes
+  * Actually have #request only finish a connection.  Somehow this got
+    missed.
+
+=== 1.2.3 / 2010-06-29
+
+* Bug Fixes
+  * Fix example code (pointed out by Alex Stahl)
+
+=== 1.2.2 / 2010-06-22
+
+* Bug Fixes
+  * #request only finishes a connection instead of restarting it.  This helps
+    prevents errors on non-idempotent HTTP requests after errors.
+  * #connection_for handles EHOSTDOWN like #reset
+
+=== 1.2.1 / 2010-05-25
+
+* Bug Fixes
+  * Don't alter Net::BufferedIO#rbuf_fill on 1.9+
+
+=== 1.2 / 2010-05-20
+
+* Minor Enhancements
+  * Net::HTTP#read_timeout is now supported
+  * Net::HTTP#open_timeout is now supported
+  * Net::HTTP::Persistent#request now supports a block like Net::HTTP#request
+
+=== 1.1 / 2010-05-18
+
+* Minor Enhancements
+  * Proxy support, see Net::HTTP::Persistent::new,
+    Net::HTTP::Persistent#proxy_from_env
+  * Added +name+ parameter to Net::HTTP::Persistent::new for separation of
+    connection pools.
+  * Added Net::HTTP::Persistent#shutdown so you can clean up after yourself
+  * Net::HTTP::Persistent now suppresses "peer certificate won't be verified
+    in this SSL session" warning.
+
+* Bug Fixes
+  * Net::HTTP::Persistent retries requests in accordance with RFC 2616.
+
+=== 1.0.1 / 2010-05-05
+
+* Minor Enhancements
+  * Added #debug_output
+  * Now uses Hoe minitest plugin
+* Bug Fixes
+  * Tests pass on 1.9
+
+=== 1.0.0 / 2010-05-04
+
+* Major Enhancements
+  * Birthday!
+

data/Manifest.txt

@@ -0,0 +1,11 @@
+.autotest
+.gemtest
+History.txt
+Manifest.txt
+README.rdoc
+Rakefile
+lib/net/http/faster.rb
+lib/net/http/persistent.rb
+lib/net/http/persistent/ssl_reuse.rb
+test/test_net_http_persistent.rb
+test/test_net_http_persistent_ssl_reuse.rb

data/README.rdoc

@@ -0,0 +1,82 @@
+= net-http-persistent
+
+* http://docs.seattlerb.org/net-http-persistent
+* https://github.com/drbrain/net-http-persistent
+
+== DESCRIPTION:
+
+Manages persistent connections using Net::HTTP plus a speed fix for Ruby 1.8.
+It's thread-safe too!
+
+Using persistent HTTP connections can dramatically increase the speed of HTTP.
+Creating a new HTTP connection for every request involves an extra TCP
+round-trip and causes TCP congestion avoidance negotiation to start over.
+
+Net::HTTP supports persistent connections with some API methods but does not
+handle reconnection gracefully.  Net::HTTP::Persistent supports reconnection
+and retry according to RFC 2616.
+
+== FEATURES/PROBLEMS:
+
+* Supports SSL
+* Thread-safe
+* Pure ruby
+* Timeout-less speed boost for Ruby 1.8 (by Aaron Patterson)
+
+== SYNOPSIS
+
+The following example will make two requests to the same server.  The
+connection is kept alive between requests:
+
+    require 'net/http/persistent'
+
+    uri = URI 'http://example.com/awesome/web/service'
+
+    http = Net::HTTP::Persistent.new 'my_app_name'
+
+    # perform a GET
+    response = http.request uri
+
+    # create a POST
+    post_uri = uri + 'create'
+    post = Net::HTTP::Post.new post_uri.path
+    post.set_form_data 'some' => 'cool data'
+
+    # perform the POST, the URI is always required
+    response = http.request post_uri, post
+
+    # if you are done making http requests, or won't make requests for several
+    # minutes
+    http.shutdown
+
+Please see the documentation on Net::HTTP::Persistent for more information,
+including SSL connection verification, header handling and tunable options.
+
+== INSTALL:
+
+  gem install net-http-persistent
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2010 Eric Hodel, Aaron Patterson
+
+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/Rakefile

@@ -0,0 +1,20 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+
+Hoe.plugin :git
+Hoe.plugin :minitest
+Hoe.plugin :travis
+
+Hoe.spec 'softwaregravy-net-http-persistent' do |p|
+  developer 'Eric Hodel', 'drbrain@segment7.net'
+
+  self.readme_file      = 'README.rdoc'
+  self.extra_rdoc_files += Dir['*.rdoc']
+
+  rdoc_locations <<
+    'docs.seattlerb.org:/data/www/docs.seattlerb.org/net-http-persistent/'
+end
+
+# vim: syntax=Ruby

data/lib/net/http/faster.rb

@@ -0,0 +1,27 @@
+require 'net/protocol'
+
+##
+# Aaron Patterson's monkeypatch (accepted into 1.9.1) to fix Net::HTTP's speed
+# problems.
+#
+# http://gist.github.com/251244
+
+class Net::BufferedIO #:nodoc:
+  alias :old_rbuf_fill :rbuf_fill
+
+  def rbuf_fill
+    if @io.respond_to? :read_nonblock then
+      begin
+        @rbuf << @io.read_nonblock(65536)
+      rescue Errno::EWOULDBLOCK, Errno::EAGAIN => e
+        retry if IO.select [@io], nil, nil, @read_timeout
+        raise Timeout::Error, e.message
+      end
+    else # SSL sockets do not have read_nonblock
+      timeout @read_timeout do
+        @rbuf << @io.sysread(65536)
+      end
+    end
+  end
+end if RUBY_VERSION < '1.9'
+

data/lib/net/http/persistent.rb

@@ -0,0 +1,998 @@
+require 'net/http'
+require 'net/https'
+require 'net/http/faster'
+require 'uri'
+require 'cgi' # for escaping
+
+begin
+  require 'net/http/pipeline'
+rescue LoadError
+end
+
+##
+# Persistent connections for Net::HTTP
+#
+# Net::HTTP::Persistent maintains persistent connections across all the
+# servers you wish to talk to.  For each host:port you communicate with a
+# single persistent connection is created.
+#
+# Multiple Net::HTTP::Persistent objects will share the same set of
+# connections.
+#
+# For each thread you start a new connection will be created.  A
+# Net::HTTP::Persistent connection will not be shared across threads.
+#
+# You can shut down the HTTP connections when done by calling #shutdown.  You
+# should name your Net::HTTP::Persistent object if you intend to call this
+# method.
+#
+# Example:
+#
+#   require 'net/http/persistent'
+#
+#   uri = URI 'http://example.com/awesome/web/service'
+#
+#   http = Net::HTTP::Persistent.new 'my_app_name'
+#
+#   # perform a GET
+#   response = http.request uri
+#
+#   # create a POST
+#   post_uri = uri + 'create'
+#   post = Net::HTTP::Post.new post_uri.path
+#   post.set_form_data 'some' => 'cool data'
+#
+#   # perform the POST, the URI is always required
+#   response http.request post_uri, post
+#
+# == SSL
+#
+# SSL connections are automatically created depending upon the scheme of the
+# URI.  SSL connections are automatically verified against the default
+# certificate store for your computer.  You can override this by changing
+# verify_mode or by specifying an alternate cert_store.
+#
+# Here are the SSL settings, see the individual methods for documentation:
+#
+# #certificate        :: This client's certificate
+# #ca_file            :: The certificate-authority
+# #cert_store         :: An SSL certificate store
+# #private_key        :: The client's SSL private key
+# #reuse_ssl_sessions :: Reuse a previously opened SSL session for a new
+#                        connection
+# #ssl_version        :: Which specific SSL version to use
+# #verify_callback    :: For server certificate verification
+# #verify_mode        :: How connections should be verified
+#
+# == Proxies
+#
+# A proxy can be set through #proxy= or at initialization time by providing a
+# second argument to ::new.  The proxy may be the URI of the proxy server or
+# <code>:ENV</code> which will consult environment variables.
+#
+# See #proxy= and #proxy_from_env for details.
+#
+# == Headers
+#
+# Headers may be specified for use in every request.  #headers are appended to
+# any headers on the request.  #override_headers replace existing headers on
+# the request.
+#
+# The difference between the two can be seen in setting the User-Agent.  Using
+# <code>http.headers['User-Agent'] = 'MyUserAgent'</code> will send "Ruby,
+# MyUserAgent" while <code>http.override_headers['User-Agent'] =
+# 'MyUserAgent'</code> will send "MyUserAgent".
+#
+# == Tuning
+#
+# === Segregation
+#
+# By providing an application name to ::new you can separate your connections
+# from the connections of other applications.
+#
+# === Idle Timeout
+#
+# If a connection hasn't been used for this number of seconds it will automatically be
+# reset upon the next use to avoid attempting to send to a closed connection.
+# The default value is 5 seconds. nil means no timeout. Set through #idle_timeout.
+#
+# Reducing this value may help avoid the "too many connection resets" error
+# when sending non-idempotent requests while increasing this value will cause
+# fewer round-trips.
+#
+# === Read Timeout
+#
+# The amount of time allowed between reading two chunks from the socket.  Set
+# through #read_timeout
+#
+# === Open Timeout
+#
+# The amount of time to wait for a connection to be opened.  Set through
+# #open_timeout.
+#
+# === Socket Options
+#
+# Socket options may be set on newly-created connections.  See #socket_options
+# for details.
+#
+# === Non-Idempotent Requests
+#
+# By default non-idempotent requests will not be retried per RFC 2616.  By
+# setting retry_change_requests to true requests will automatically be retried
+# once.
+#
+# Only do this when you know that retrying a POST or other non-idempotent
+# request is safe for your application and will not create duplicate
+# resources.
+#
+# The recommended way to handle non-idempotent requests is the following:
+#
+#   require 'net/http/persistent'
+#
+#   uri = URI 'http://example.com/awesome/web/service'
+#   post_uri = uri + 'create'
+#
+#   http = Net::HTTP::Persistent.new 'my_app_name'
+#
+#   post = Net::HTTP::Post.new post_uri.path
+#   # ... fill in POST request
+#
+#   begin
+#     response = http.request post_uri, post
+#   rescue Net::HTTP::Persistent::Error
+#
+#     # POST failed, make a new request to verify the server did not process
+#     # the request
+#     exists_uri = uri + '...'
+#     response = http.get exists_uri
+#
+#     # Retry if it failed
+#     retry if response.code == '404'
+#   end
+#
+# The method of determining if the resource was created or not is unique to
+# the particular service you are using.  Of course, you will want to add
+# protection from infinite looping.
+#
+# === Connection Termination
+#
+# If you are done using the Net::HTTP::Persistent instance you may shut down
+# all the connections in the current thread with #shutdown.  This is not
+# recommended for normal use, it should only be used when it will be several
+# minutes before you make another HTTP request.
+#
+# If you are using multiple threads, call #shutdown in each thread when the
+# thread is done making requests.  If you don't call shutdown, that's OK.
+# Ruby will automatically garbage collect and shutdown your HTTP connections
+# when the thread terminates.
+
+class Net::HTTP::Persistent
+
+  ##
+  # The beginning of Time
+
+  EPOCH = Time.at 0 # :nodoc:
+
+  ##
+  # The version of Net::HTTP::Persistent you are using
+
+  VERSION = '2.6'
+
+  ##
+  # Error class for errors raised by Net::HTTP::Persistent.  Various
+  # SystemCallErrors are re-raised with a human-readable message under this
+  # class.
+
+  class Error < StandardError; end
+
+  ##
+  # This client's OpenSSL::X509::Certificate
+
+  attr_reader :certificate
+
+  ##
+  # An SSL certificate authority.  Setting this will set verify_mode to
+  # VERIFY_PEER.
+
+  attr_reader :ca_file
+
+  ##
+  # An SSL certificate store.  Setting this will override the default
+  # certificate store.  See verify_mode for more information.
+
+  attr_reader :cert_store
+
+  ##
+  # Sends debug_output to this IO via Net::HTTP#set_debug_output.
+  #
+  # Never use this method in production code, it causes a serious security
+  # hole.
+
+  attr_accessor :debug_output
+
+  ##
+  # Current connection generation
+
+  attr_reader :generation # :nodoc:
+
+  ##
+  # Where this instance's connections live in the thread local variables
+
+  attr_reader :generation_key # :nodoc:
+
+  ##
+  # Headers that are added to every request using Net::HTTP#add_field
+
+  attr_reader :headers
+
+  ##
+  # Maps host:port to an HTTP version.  This allows us to enable version
+  # specific features.
+
+  attr_reader :http_versions
+
+  ##
+  # Maximum time an unused connection can remain idle before being
+  # automatically closed.
+
+  attr_accessor :idle_timeout
+
+  ##
+  # The value sent in the Keep-Alive header.  Defaults to 30.  Not needed for
+  # HTTP/1.1 servers.
+  #
+  # This may not work correctly for HTTP/1.0 servers
+  #
+  # This method may be removed in a future version as RFC 2616 does not
+  # require this header.
+
+  attr_accessor :keep_alive
+
+  ##
+  # A name for this connection.  Allows you to keep your connections apart
+  # from everybody else's.
+
+  attr_reader :name
+
+  ##
+  # Seconds to wait until a connection is opened.  See Net::HTTP#open_timeout
+
+  attr_accessor :open_timeout
+
+  ##
+  # Headers that are added to every request using Net::HTTP#[]=
+
+  attr_reader :override_headers
+
+  ##
+  # This client's SSL private key
+
+  attr_reader :private_key
+
+  ##
+  # The URL through which requests will be proxied
+
+  attr_reader :proxy_uri
+
+  ##
+  # Seconds to wait until reading one block.  See Net::HTTP#read_timeout
+
+  attr_accessor :read_timeout
+
+  ##
+  # Where this instance's request counts live in the thread local variables
+
+  attr_reader :request_key # :nodoc:
+
+  ##
+  # By default SSL sessions are reused to avoid extra SSL handshakes.  Set
+  # this to false if you have problems communicating with an HTTPS server
+  # like:
+  #
+  #   SSL_connect [...] read finished A: unexpected message (OpenSSL::SSL::SSLError)
+
+  attr_accessor :reuse_ssl_sessions
+
+  ##
+  # An array of options for Socket#setsockopt.
+  #
+  # By default the TCP_NODELAY option is set on sockets.
+  #
+  # To set additional options append them to this array:
+  #
+  #   http.socket_options << [Socket::SOL_SOCKET, Socket::SO_KEEPALIVE, 1]
+
+  attr_reader :socket_options
+
+  ##
+  # Current SSL connection generation
+
+  attr_reader :ssl_generation # :nodoc:
+
+  ##
+  # Where this instance's SSL connections live in the thread local variables
+
+  attr_reader :ssl_generation_key # :nodoc:
+
+  ##
+  # SSL version to use.
+  #
+  # By default, the version will be negotiated automatically between client
+  # and server.  Ruby 1.9 and newer only.
+
+  attr_reader :ssl_version if RUBY_VERSION > '1.9'
+
+  ##
+  # Where this instance's last-use times live in the thread local variables
+
+  attr_reader :timeout_key # :nodoc:
+
+  ##
+  # SSL verification callback.  Used when ca_file is set.
+
+  attr_reader :verify_callback
+
+  ##
+  # HTTPS verify mode.  Defaults to OpenSSL::SSL::VERIFY_PEER which verifies
+  # the server certificate.
+  #
+  # If no ca_file or cert_store is set the default system certificate store is
+  # used.
+  #
+  # You can use +verify_mode+ to override any default values.
+
+  attr_reader :verify_mode
+
+  ##
+  # Enable retries of non-idempotent requests that change data (e.g. POST
+  # requests) when the server has disconnected.
+  #
+  # This will in the worst case lead to multiple requests with the same data,
+  # but it may be useful for some applications.  Take care when enabling
+  # this option to ensure it is safe to POST or perform other non-idempotent
+  # requests to the server.
+
+  attr_accessor :retry_change_requests
+
+  ##
+  # Creates a new Net::HTTP::Persistent.
+  #
+  # Set +name+ to keep your connections apart from everybody else's.  Not
+  # required currently, but highly recommended.  Your library name should be
+  # good enough.  This parameter will be required in a future version.
+  #
+  # +proxy+ may be set to a URI::HTTP or :ENV to pick up proxy options from
+  # the environment.  See proxy_from_env for details.
+  #
+  # In order to use a URI for the proxy you may need to do some extra work
+  # beyond URI parsing if the proxy requires a password:
+  #
+  #   proxy = URI 'http://proxy.example'
+  #   proxy.user     = 'AzureDiamond'
+  #   proxy.password = 'hunter2'
+
+  def initialize name = nil, proxy = nil
+    @name = name
+
+    @debug_output     = nil
+    @proxy_uri        = nil
+    @headers          = {}
+    @override_headers = {}
+    @http_versions    = {}
+    @keep_alive       = 30
+    @open_timeout     = nil
+    @read_timeout     = nil
+    @idle_timeout     = 5
+    @socket_options   = []
+
+    @socket_options << [Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1] if
+      Socket.const_defined? :TCP_NODELAY
+
+    key = ['net_http_persistent', name].compact
+    @generation_key     = [key, 'generations'    ].join('_').intern
+    @ssl_generation_key = [key, 'ssl_generations'].join('_').intern
+    @request_key        = [key, 'requests'       ].join('_').intern
+    @timeout_key        = [key, 'timeouts'       ].join('_').intern
+
+    @certificate        = nil
+    @ca_file            = nil
+    @private_key        = nil
+    @ssl_version        = nil
+    @verify_callback    = nil
+    @verify_mode        = OpenSSL::SSL::VERIFY_PEER
+    @cert_store         = nil
+
+    @generation         = 0 # incremented when proxy URI changes
+    @ssl_generation     = 0 # incremented when SSL session variables change
+    @reuse_ssl_sessions = true
+
+    @retry_change_requests = false
+
+    self.proxy = proxy if proxy
+  end
+
+  ##
+  # Sets this client's OpenSSL::X509::Certificate
+
+  def certificate= certificate
+    @certificate = certificate
+
+    reconnect_ssl
+  end
+
+  ##
+  # Sets the SSL certificate authority file.
+
+  def ca_file= file
+    @ca_file = file
+
+    reconnect_ssl
+  end
+
+  ##
+  # Overrides the default SSL certificate store used for verifying
+  # connections.
+
+  def cert_store= store
+    @cert_store = store
+
+    reconnect_ssl
+  end
+
+  ##
+  # Finishes all connections on the given +thread+ that were created before
+  # the given +generation+ in the threads +generation_key+ list.
+  #
+  # See #shutdown for a bunch of scary warning about misusing this method.
+
+  def cleanup(generation, thread = Thread.current,
+              generation_key = @generation_key) # :nodoc:
+    timeouts = thread[@timeout_key]
+
+    (0...generation).each do |old_generation|
+      next unless thread[generation_key]
+
+      conns = thread[generation_key].delete old_generation
+
+      conns.each_value do |conn|
+        finish conn, thread
+
+        timeouts.delete conn.object_id if timeouts
+      end if conns
+    end
+  end
+
+  ##
+  # Creates a new connection for +uri+
+
+  def connection_for uri
+    Thread.current[@generation_key]     ||= Hash.new { |h,k| h[k] = {} }
+    Thread.current[@ssl_generation_key] ||= Hash.new { |h,k| h[k] = {} }
+    Thread.current[@request_key]        ||= Hash.new 0
+    Thread.current[@timeout_key]        ||= Hash.new EPOCH
+
+    use_ssl = uri.scheme.downcase == 'https'
+
+    if use_ssl then
+      ssl_generation = @ssl_generation
+
+      ssl_cleanup ssl_generation
+
+      connections = Thread.current[@ssl_generation_key][ssl_generation]
+    else
+      generation = @generation
+
+      cleanup generation
+
+      connections = Thread.current[@generation_key][generation]
+    end
+
+    net_http_args = [uri.host, uri.port]
+    connection_id = net_http_args.join ':'
+
+    if @proxy_uri then
+      connection_id << @proxy_connection_id
+      net_http_args.concat @proxy_args
+    end
+
+    connection = connections[connection_id]
+
+    unless connection = connections[connection_id] then
+      connections[connection_id] = http_class.new(*net_http_args)
+      connection = connections[connection_id]
+      ssl connection if use_ssl
+    else
+      reset connection if expired? connection
+    end
+
+    unless connection.started? then
+      connection.set_debug_output @debug_output if @debug_output
+      connection.open_timeout = @open_timeout if @open_timeout
+      connection.read_timeout = @read_timeout if @read_timeout
+
+      connection.start
+
+      socket = connection.instance_variable_get :@socket
+
+      if socket then # for fakeweb
+        @socket_options.each do |option|
+          socket.io.setsockopt(*option)
+        end
+      end
+    end
+
+    connection
+  rescue Errno::ECONNREFUSED
+    raise Error, "connection refused: #{connection.address}:#{connection.port}"
+  rescue Errno::EHOSTDOWN
+    raise Error, "host down: #{connection.address}:#{connection.port}"
+  end
+
+  ##
+  # Returns an error message containing the number of requests performed on
+  # this connection
+
+  def error_message connection
+    requests = Thread.current[@request_key][connection.object_id] - 1 # fixup
+    last_use = Thread.current[@timeout_key][connection.object_id]
+
+    age = Time.now - last_use
+
+    "after #{requests} requests on #{connection.object_id}, " \
+      "last used #{age} seconds ago"
+  end
+
+  ##
+  # URI::escape wrapper
+
+  def escape str
+    CGI.escape str if str
+  end
+
+  ##
+  # Returns true if the connection should be reset due to an idle timeout,
+  # false otherwise.
+
+  def expired? connection
+    return false unless @idle_timeout
+    return true  if     @idle_timeout.zero?
+
+    last_used = Thread.current[@timeout_key][connection.object_id]
+
+    Time.now - last_used > @idle_timeout
+  end
+
+  ##
+  # Finishes the Net::HTTP +connection+
+
+  def finish connection, thread = Thread.current
+    if requests = thread[@request_key] then
+      requests.delete connection.object_id
+    end
+
+    connection.finish
+  rescue IOError
+  end
+
+  def http_class # :nodoc:
+    if [:FakeWeb, :WebMock].any? { |klass| Object.const_defined?(klass) } or
+      not @reuse_ssl_sessions then
+        Net::HTTP
+    else
+      Net::HTTP::Persistent::SSLReuse
+    end
+  end
+
+  ##
+  # Returns the HTTP protocol version for +uri+
+
+  def http_version uri
+    @http_versions["#{uri.host}:#{uri.port}"]
+  end
+
+  ##
+  # Is +req+ idempotent according to RFC 2616?
+
+  def idempotent? req
+    case req
+    when Net::HTTP::Delete, Net::HTTP::Get, Net::HTTP::Head,
+         Net::HTTP::Options, Net::HTTP::Put, Net::HTTP::Trace then
+      true
+    end
+  end
+
+  ##
+  # Is the request idempotent or is retry_change_requests allowed
+
+  def can_retry? req
+    retry_change_requests or idempotent?(req)
+  end
+
+  if RUBY_VERSION > '1.9' then
+    ##
+    # Workaround for missing Net::HTTPHeader#connection_close? on Ruby 1.8
+
+    def connection_close? header
+      header.connection_close?
+    end
+
+    ##
+    # Workaround for missing Net::HTTPHeader#connection_keep_alive? on Ruby 1.8
+
+    def connection_keep_alive? header
+      header.connection_keep_alive?
+    end
+  else
+    ##
+    # Workaround for missing Net::HTTPRequest#connection_close? on Ruby 1.8
+
+    def connection_close? header
+      header['connection'] =~ /close/ or header['proxy-connection'] =~ /close/
+    end
+
+    ##
+    # Workaround for missing Net::HTTPRequest#connection_keep_alive? on Ruby
+    # 1.8
+
+    def connection_keep_alive? header
+      header['connection'] =~ /keep-alive/ or
+        header['proxy-connection'] =~ /keep-alive/
+    end
+  end
+
+  ##
+  # Deprecated in favor of #expired?
+
+  def max_age # :nodoc:
+    return Time.now + 1 unless @idle_timeout
+
+    Time.now - @idle_timeout
+  end
+
+  ##
+  # Adds "http://" to the String +uri+ if it is missing.
+
+  def normalize_uri uri
+    (uri =~ /^https?:/) ? uri : "http://#{uri}"
+  end
+
+  ##
+  # Pipelines +requests+ to the HTTP server at +uri+ yielding responses if a
+  # block is given.  Returns all responses recieved.
+  #
+  # See
+  # Net::HTTP::Pipeline[http://docs.seattlerb.org/net-http-pipeline/Net/HTTP/Pipeline.html]
+  # for further details.
+  #
+  # Only if <tt>net-http-pipeline</tt> was required before
+  # <tt>net-http-persistent</tt> #pipeline will be present.
+
+  def pipeline uri, requests, &block # :yields: responses
+    connection = connection_for uri
+
+    connection.pipeline requests, &block
+  end
+
+  ##
+  # Sets this client's SSL private key
+
+  def private_key= key
+    @private_key = key
+
+    reconnect_ssl
+  end
+
+  ##
+  # Sets the proxy server.  The +proxy+ may be the URI of the proxy server,
+  # the symbol +:ENV+ which will read the proxy from the environment or nil to
+  # disable use of a proxy.  See #proxy_from_env for details on setting the
+  # proxy from the environment.
+  #
+  # If the proxy URI is set after requests have been made, the next request
+  # will shut-down and re-open all connections.
+  #
+  # If you are making some requests through a proxy and others without a proxy
+  # use separate Net::Http::Persistent instances.
+
+  def proxy= proxy
+    @proxy_uri = case proxy
+                 when :ENV      then proxy_from_env
+                 when URI::HTTP then proxy
+                 when nil       then # ignore
+                 else raise ArgumentError, 'proxy must be :ENV or a URI::HTTP'
+                 end
+
+    if @proxy_uri then
+      @proxy_args = [
+        @proxy_uri.host,
+        @proxy_uri.port,
+        @proxy_uri.user,
+        @proxy_uri.password,
+      ]
+
+      @proxy_connection_id = [nil, *@proxy_args].join ':'
+    end
+
+    reconnect
+    reconnect_ssl
+  end
+
+  ##
+  # Creates a URI for an HTTP proxy server from ENV variables.
+  #
+  # If +HTTP_PROXY+ is set a proxy will be returned.
+  #
+  # If +HTTP_PROXY_USER+ or +HTTP_PROXY_PASS+ are set the URI is given the
+  # indicated user and password unless HTTP_PROXY contains either of these in
+  # the URI.
+  #
+  # For Windows users, lowercase ENV variables are preferred over uppercase ENV
+  # variables.
+
+  def proxy_from_env
+    env_proxy = ENV['http_proxy'] || ENV['HTTP_PROXY']
+
+    return nil if env_proxy.nil? or env_proxy.empty?
+
+    uri = URI normalize_uri env_proxy
+
+    unless uri.user or uri.password then
+      uri.user     = escape ENV['http_proxy_user'] || ENV['HTTP_PROXY_USER']
+      uri.password = escape ENV['http_proxy_pass'] || ENV['HTTP_PROXY_PASS']
+    end
+
+    uri
+  end
+
+  ##
+  # Forces reconnection of HTTP connections.
+
+  def reconnect
+    @generation += 1
+  end
+
+  ##
+  # Forces reconnection of SSL connections.
+
+  def reconnect_ssl
+    @ssl_generation += 1
+  end
+
+  ##
+  # Finishes then restarts the Net::HTTP +connection+
+
+  def reset connection
+    Thread.current[@request_key].delete connection.object_id
+    Thread.current[@timeout_key].delete connection.object_id
+
+    finish connection
+
+    connection.start
+  rescue Errno::ECONNREFUSED
+    raise Error, "connection refused: #{connection.address}:#{connection.port}"
+  rescue Errno::EHOSTDOWN
+    raise Error, "host down: #{connection.address}:#{connection.port}"
+  end
+
+  ##
+  # Makes a request on +uri+.  If +req+ is nil a Net::HTTP::Get is performed
+  # against +uri+.
+  #
+  # If a block is passed #request behaves like Net::HTTP#request (the body of
+  # the response will not have been read).
+  #
+  # +req+ must be a Net::HTTPRequest subclass (see Net::HTTP for a list).
+  #
+  # If there is an error and the request is idempontent according to RFC 2616
+  # it will be retried automatically.
+
+  def request uri, req = nil, &block
+    retried      = false
+    bad_response = false
+
+    req = Net::HTTP::Get.new uri.request_uri unless req
+
+    @headers.each do |pair|
+      req.add_field(*pair)
+    end
+
+    @override_headers.each do |name, value|
+      req[name] = value
+    end
+
+    unless req['Connection'] then
+      req.add_field 'Connection', 'keep-alive'
+      req.add_field 'Keep-Alive', @keep_alive
+    end
+
+    connection = connection_for uri
+    connection_id = connection.object_id
+
+    begin
+      Thread.current[@request_key][connection_id] += 1
+      response = connection.request req, &block
+
+      if connection_close?(req) or
+         (response.http_version <= '1.0' and
+          not connection_keep_alive?(response)) or
+         connection_close?(response) then
+        connection.finish
+      end
+    rescue Net::HTTPBadResponse => e
+      message = error_message connection
+
+      finish connection
+
+      raise Error, "too many bad responses #{message}" if
+        bad_response or not can_retry? req
+
+      bad_response = true
+      retry
+    rescue IOError, EOFError, Timeout::Error,
+           Errno::ECONNABORTED, Errno::ECONNRESET, Errno::EPIPE,
+           Errno::EINVAL, OpenSSL::SSL::SSLError => e
+
+      if retried or not can_retry? req
+        due_to = "(due to #{e.message} - #{e.class})"
+        message = error_message connection
+
+        finish connection
+
+        raise Error, "too many connection resets #{due_to} #{message}"
+      end
+
+      reset connection
+
+      retried = true
+      retry
+    ensure
+      Thread.current[@timeout_key][connection_id] = Time.now
+    end
+
+    @http_versions["#{uri.host}:#{uri.port}"] ||= response.http_version
+
+    response
+  end
+
+  ##
+  # Shuts down all connections for +thread+.
+  #
+  # Uses the current thread by default.
+  #
+  # If you've used Net::HTTP::Persistent across multiple threads you should
+  # call this in each thread when you're done making HTTP requests.
+  #
+  # *NOTE*: Calling shutdown for another thread can be dangerous!
+  #
+  # If the thread is still using the connection it may cause an error!  It is
+  # best to call #shutdown in the thread at the appropriate time instead!
+
+  def shutdown thread = Thread.current
+    generation = reconnect
+    cleanup generation, thread, @generation_key
+
+    ssl_generation = reconnect_ssl
+    cleanup ssl_generation, thread, @ssl_generation_key
+
+    thread[@request_key] = nil
+    thread[@timeout_key] = nil
+  end
+
+  ##
+  # Shuts down all connections in all threads
+  #
+  # *NOTE*: THIS METHOD IS VERY DANGEROUS!
+  #
+  # Do not call this method if other threads are still using their
+  # connections!  Call #shutdown at the appropriate time instead!
+  #
+  # Use this method only as a last resort!
+
+  def shutdown_in_all_threads
+    Thread.list.each do |thread|
+      shutdown thread
+    end
+
+    nil
+  end
+
+  ##
+  # Enables SSL on +connection+
+
+  def ssl connection
+    connection.use_ssl = true
+
+    connection.ssl_version = @ssl_version if @ssl_version
+
+    connection.verify_mode = @verify_mode
+
+    if OpenSSL::SSL::VERIFY_PEER == OpenSSL::SSL::VERIFY_NONE and
+       not Object.const_defined?(:I_KNOW_THAT_OPENSSL_VERIFY_PEER_EQUALS_VERIFY_NONE_IS_WRONG) then
+      warn <<-WARNING
+                             !!!SECURITY WARNING!!!
+
+The SSL HTTP connection to:
+
+  #{connection.address}:#{connection.port}
+
+                           !!!MAY NOT BE VERIFIED!!!
+
+On your platform your OpenSSL implementation is broken.
+
+There is no difference between the values of VERIFY_NONE and VERIFY_PEER.
+
+This means that attempting to verify the security of SSL connections may not
+work.  This exposes you to man-in-the-middle exploits, snooping on the
+contents of your connection and other dangers to the security of your data.
+
+To disable this warning define the following constant at top-level in your
+application:
+
+  I_KNOW_THAT_OPENSSL_VERIFY_PEER_EQUALS_VERIFY_NONE_IS_WRONG = nil
+
+      WARNING
+    end
+
+    if @ca_file then
+      connection.ca_file = @ca_file
+      connection.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      connection.verify_callback = @verify_callback if @verify_callback
+    end
+
+    if @certificate and @private_key then
+      connection.cert = @certificate
+      connection.key  = @private_key
+    end
+
+    connection.cert_store = if @cert_store then
+                              @cert_store
+                            else
+                              store = OpenSSL::X509::Store.new
+                              store.set_default_paths
+                              store
+                            end
+  end
+
+  ##
+  # Finishes all connections that existed before the given SSL parameter
+  # +generation+.
+
+  def ssl_cleanup generation # :nodoc:
+    cleanup generation, Thread.current, @ssl_generation_key
+  end
+
+  ##
+  # SSL version to use
+
+  def ssl_version= ssl_version
+    @ssl_version = ssl_version
+
+    reconnect_ssl
+  end if RUBY_VERSION > '1.9'
+
+  ##
+  # Sets the HTTPS verify mode.  Defaults to OpenSSL::SSL::VERIFY_PEER.
+  #
+  # Setting this to VERIFY_NONE is a VERY BAD IDEA and should NEVER be used.
+  # Securely transfer the correct certificate and update the default
+  # certificate store or set the ca file instead.
+
+  def verify_mode= verify_mode
+    @verify_mode = verify_mode
+
+    reconnect_ssl
+  end
+
+  ##
+  # SSL verification callback.
+
+  def verify_callback= callback
+    @verify_callback = callback
+
+    reconnect_ssl
+  end
+
+end
+
+require 'net/http/persistent/ssl_reuse'
+