hot_tub 0.0.4 → 0.1.0

data/Gemfile

@@ -1,17 +1,16 @@
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in http_hot_tub.gemspec
 gemspec
 
 group :development do
   platform :ruby do
+  	gem 'debugger'
     gem 'eventmachine'
     gem 'em-http-request', '~> 1.0', :require => 'em-http'
     gem 'em-synchrony', '~> 1.0', :require => ['em-synchrony', 'em-synchrony/em-http']
-    gem "excon"
   end
   platform :jruby do
     gem 'jruby-openssl'
-    gem 'jruby-httpclient'
   end
 end

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2010 Joshua T. Mckinney
+Copyright (c) 2010-2013 Joshua T. Mckinney
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,6 +1,8 @@
 # HotTub
-A simple thread-safe pooling gem to use with your preferred http library that support
-keep-alive.
+A simple thread-safe connection pooling gem. Supports [HTTPClient](https://github.com/nahi/httpclient) (default) and
+[EM-Http-Requests](https://github.com/igrigorik/em-http-request) via [EM-Synchrony](https://github.com/igrigorik/em-synchrony). 
+There are a couple Ruby connection pool libraries out there but HotTub differs from most in that its connections are lazy 
+(created only when necessary), accomidates libraries that do not clean their dirty connections automatically, and manages unexpected usage increases by opening new connections rather than just blocking or throwings exception (never_block), although never_block can be disabled. 
 
 ## Installation
 
@@ -8,16 +10,86 @@ HotTub is available through [Rubygems](https://rubygems.org/gems/hot_tub) and ca
 
     $ gem install hot_tub
 
-## Setup 
+## Usage 
+
+### Default (HTTPClient)
+
+    class MyClass
+      @@url = "http://test12345.com"
+      @@pool = HotTub::Pool.new({:size => 10})
+      def self.fetch_results(url,query={})
+        @@pool.run |connection|
+          connection.get(@@url,query).body
+        end
+      end
+    end
+    MyClass.fetch_results({:foo => "goo"}) # => "Some reponse"
+
+### EM-Http-Request
+
+    require "em-synchrony"
+    require "em-synchrony/em-http"
+    class EMClass
+      @@pool = HotTub::Pool.new(:size => 12) { EM::HttpRequest.new("http://somewebservice.com") }
+      def async_post_results(query = {})
+        @@pool.run do |connection|    
+          connection.aget(:query => results, :keepalive => true)
+        end
+      end
+    end
+
+    EM.synchrony do {
+      EMClass.async_fetch_results({:foo => "goo"})
+      EM.stop
+    }
+
+### Other
+ You can use any libary you want. Close and clean can be defined at initialization with
+ lambdas, if they are not defined they are ignored.
+
     class MyClass
-      @@pool = HotTub::Session.new(HotTub::ExconClient.new('https://google.com'),{:size => 2, :never_block => true})
+      @@url = "http://test12345.com"
+      @@pool = HotTub::Pool.new({:size => 10, :close => lambda {|clnt| clnt.close}}) { MyHttpLib.new }
+      def self.fetch_results(url,query={})
+        @@pool.run |connection|
+          connection.get(@@url,query).body
+        end
+      end
+    end
+
+    MyClass.fetch_results({:foo => "goo"}) # => "Some reponse"
 
-      def self.fetch_results(query)
-        @@pool.get(:query => query) # keepalive has be defaulted to true in the client
+## Sessions
+
+HTTPClient has a built in thread-safe sessions feature that allows a single client to access multiple domains. 
+Not all clients have a sessions feature, Em-Http-Request clients are initialized to a single domain and while you
+can change paths the client domain cannot change. HotTub::Session allows you create a session object that initializes
+seperate pools for you various domains based on URI.
+
+    # Assuming EM is running
+    require 'hot_tub/clients/em_http_request_client'
+    class EMClass
+      @@sessons = HotTub::Sessions.new {|url| HotTub::EmHttpRequestClient.new(url,{:connect_timeout => 5}) }
+      def async_post_results(query = {})
+        @@sessons.run("http://somewebservice.com") do |connection|    
+          puts connection.get(:query => results).response_header.status
+        end
+        @@sessons.run("https://someotherwebservice.com") do |connection|    
+          puts connection.get(:query => results).response_header.status
+        end
       end
     end
 
-    MyClass.fetch_results({:foo => "goo"})
+## Related
+
+* [HTTPClient](https://github.com/nahi/httpclient)
+* [EM-Http-Request](https://github.com/igrigorik/em-http-request)
+* [EM-Synchrony](https://github.com/igrigorik/em-synchrony)
+
+## Other Pooling Gem
+
+* [ConnectionPool](https://github.com/mperham/connection_pool)
+* [EM-Synchrony](https://github.com/igrigorik/em-synchrony) has a connection pool feature
 
 ## Contributing to HotTub
  

data/http_hot_tub.gemspec

@@ -8,14 +8,17 @@ Gem::Specification.new do |s|
   s.authors     = ["Joshua Mckinney"]
   s.email       = ["joshmckin@gmail.com"]
   s.homepage    = "https://github.com/JoshMcKin/hot_tub"
-  s.summary     = %q{A very simple ruby pool gem}
-  s.description = %q{A very simple ruby pool gem}
+  s.license     = "MIT"
+  s.summary     = %q{A simple thread-safe http connection pooling gem.}
+  s.description = %q{A simple thread-safe http connection pooling gem. Http client options include HTTPClient and EM-Http-Request}
 
-  s.rubyforge_project = "hot_tub"
 
+  s.rubyforge_project = "hot_tub"
+  s.add_runtime_dependency "httpclient"
+  s.add_development_dependency "rspec"
+  
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
-  s.add_development_dependency "rspec"
 end

data/lib/hot_tub.rb

@@ -2,20 +2,24 @@ require 'thread'
 require 'timeout'
 require 'logger'
 require "hot_tub/version"
+require "hot_tub/pool"
 require "hot_tub/session"
-require "hot_tub/clients/client"
-require "hot_tub/clients/em_synchrony_client"
-require "hot_tub/clients/excon_client"
-require "hot_tub/clients/http_client_client" if RUBY_VERSION < '1.9' or (defined? RUBY_ENGINE and 'jruby' == RUBY_ENGINE)
 
 module HotTub
- @@logger = Logger.new(STDOUT)
+  @@logger = Logger.new(STDOUT)
   def self.logger
     @@logger
   end
-  
+
   def self.logger=logger
     @@logger = logger
   end
-end
 
+  def self.em?
+    (defined?(EM) && EM::reactor_running?)
+  end
+
+  def self.jruby?
+    (defined?(JRUBY_VERSION))
+  end
+end

data/lib/hot_tub/pool.rb

@@ -0,0 +1,188 @@
+require 'httpclient'
+module HotTub
+  class Pool
+    attr_reader :current_size
+    KNOWN_CLIENTS = {
+      "HTTPClient" => {
+        :close => lambda { |clnt|
+          sessions = clnt.instance_variable_get(:@session_manager)
+          sessions.reset_all if sessions
+        }
+      },
+      'EventMachine::HttpConnection' => {
+        :close => lambda { |clnt|
+          if clnt.conn
+            clnt.conn.close_connection
+            clnt.instance_variable_set(:@deferred, true)
+          end
+        },
+        :clean => lambda { |clnt|
+          if clnt.conn && clnt.conn.error?
+            HotTub.logger.info "Sanitizing connection : #{EventMachine::report_connection_error_status(clnt.conn.instance_variable_get(:@signature))}"
+            clnt.conn.close_connection
+            clnt.instance_variable_set(:@deferred, true)
+          end
+          clnt
+        }
+      }
+    }
+
+    # Generic lazy connection pool of HTTP clients
+    # The default client is HTTPClient.
+    # Clients must respond to :clean, :close, and :run
+    #
+    # == Example (HTTPClient)
+    #     pool = HotTub::Pool.new(:size => 25)
+    #     pool.run {|clnt| clnt.get('http://test.com').body }
+    #
+    # == Example with different client
+    #     pool = HotTub::Pool.new { EM::HttpRequest.new("http://somewebservice.com") }
+    #     pool.run {|clnt| clnt.get(:keepalive => true).body }
+    #
+    # HotTub::Pool defaults never_block to true, which means if run out of
+    # connections simply create a new client to continue operations.
+    # The pool size will remain consistent and extra connections will be closed
+    # as they are pushed back. If you would like to throw an exception rather than
+    # add new connections set :never_block to false; blocking_timeout defaults to 10 seconds.
+    #
+    # == Example without #never_block (will BlockingTimeout exception)
+    #     pool = HotTub::Pool.new(:size => 1, :never_block => false, :blocking_timeout => 0.5)
+    #
+    #     begin
+    #       pool.run {|clnt| clnt.get('http://test.com').body }
+    #     rescue HotTub::BlockingTimeout => e
+    #       puts "Our pool ran out: {e}"
+    #     end
+    #
+    def initialize(options={},&client_block)
+      @client_block = (block_given? ? client_block : lambda { HTTPClient.new })
+      @options = {
+        :size => 5,
+        :never_block => true,
+        :blocking_timeout => 10,
+        :close => nil,
+        :clean => nil
+      }.merge(options)
+      @pool = []
+      @current_size = 0
+      @clients = []
+      @mutex = (HotTub.em? ? EM::Synchrony::Thread::Mutex.new : Mutex.new)
+      @blocking_timeout = @options[:blocking_timeout]
+      @never_block = @options[:never_block]
+      @size = @options[:size]
+    end
+
+    # Hand off to client.run
+    def run(&block)
+      clnt = client
+      if block_given?
+        return block.call(clnt) if clnt
+      else
+        raise ArgumentError, 'Run requires a block.'
+      end
+    ensure
+      push(clnt) if clnt
+    end
+
+    # Calls close on all connections and reset the pools
+    def close_all
+      @mutex.synchronize do
+        while clnt = @clients.pop
+          begin
+            close_client(clnt)
+          rescue => e
+            HotTub.logger.error "There was an error close one of your HotTub::Pool connections: #{e}"
+          end
+          @pool.delete(clnt)
+        end
+        @current_size = 0
+      end
+    end
+
+    private
+
+    # Returns an instance of the client for this pool.
+    def client
+      clnt = nil
+      alarm = (Time.now + @blocking_timeout)
+      # block until we get an available client or raise Timeout::Error
+      while clnt.nil?
+        raise_alarm if alarm <= Time.now
+        clnt = pop
+      end
+      clean_client(clnt)
+      clnt
+    end
+
+    # Attempts to clean the provided client, checking the options first for a clean block
+    # then checking the known clients
+    def clean_client(clnt)
+      return @options[:clean].call(clnt) if @options[:clean] if @options[:clean].is_a?(Proc)
+      if settings = KNOWN_CLIENTS[clnt.class.name]
+        settings[:clean].call(clnt) if settings[:clean].is_a?(Proc)
+      end
+    end
+
+
+    # Attempts to close the provided client, checking the options first for a close block
+    # then checking the known clients
+    def close_client(clnt)
+      return @options[:close].call(clnt) if @options[:close] if @options[:close].is_a?(Proc)
+      if settings = KNOWN_CLIENTS[clnt.class.name]
+        settings[:close].call(clnt) if settings[:close].is_a?(Proc)
+      end
+    end
+
+    def raise_alarm
+      message = "Could not fetch a free client in time. Consider increasing your pool size for #{@client.class.name}."
+      HotTub.logger.error message
+      raise BlockingTimeout, message
+    end
+
+    # Safely add client back to pool
+    def push(clnt)
+      @mutex.synchronize do
+        if @pool.length < @size
+          @pool << clnt
+        else
+          @clients.delete(clnt)
+          close_client(clnt)
+        end
+      end
+      nil # make sure never return the pool
+    end
+
+    # Safely pull client from pool, adding if allowed
+    def pop
+      @mutex.synchronize do
+        add if add?
+        clnt = @pool.pop
+        if (clnt.nil? && @never_block)
+          HotTub.logger.info "Adding never_block client for #{@client.class.name}."
+          clnt = new_client
+        end
+        clnt
+      end
+    end
+
+    # create a new client from base client
+    def new_client
+      clnt = @client_block.call
+      @clients << clnt
+      clnt
+    end
+
+    # Only want to add a client if the pool is empty in keeping with
+    # a lazy model.
+    def add?
+      (@pool.length == 0 && @current_size <= @size)
+    end
+
+    def add
+      HotTub.logger.info "Adding HotTub client: #{@client.class.name} to pool"
+      @current_size += 1
+      @pool << new_client
+    end
+  end
+  class BlockingTimeout < StandardError;end
+end

data/lib/hot_tub/session.rb

@@ -1,129 +1,70 @@
+require 'uri'
 module HotTub
   class Session
-   
-    # OPTIONS
-    # * :size - number of clients/connections for each pool
-    # * :inactivity_timeout - number of seconds to wait before disconnecting, setting to 0 means the connection will not be closed
-    # * :pool_timeout - the amount of seconds to block waiting for an available client, 
-    # because this is blocking it should be an extremely short amount of 
-    # time default to 0.5 seconds, if you need more consider enlarging your pool
-    # instead of raising this number
-    # :never_block - if set to true, a client will always be returned, 
-    # but the pool size will never grow past that :size option, extra clients are closed
-    def initialize(client,options={})     
-      @options = {
-        :size => 5,
-        :never_block => false,
-        :blocking_timeout => 0.5
-      }.merge(options || {})
-      @pool = []
-      @pool_data = {:current_size => 0}   
-      @client = client
-      @mutex = (@client.respond_to?(:mutex) ? @client.mutex : Mutex.new)  
-    end
-    
-    # The synchronized pool for all our clients.
+
+    # A HotTub::Session is a synchronized hash used to separate HotTub::Pools by their domain.
+    # EmHttpRequest clients are initialized to a specific domain, so we sometimes need a way to
+    # manage multiple pools like when a process need to connect to various AWS resources. Sessions
+    # are unnecessary for HTTPClient because the client has its own threads safe sessions object.
+    # Example:
     #
-    def pool(client=nil)
-      @mutex.synchronize do
-        if client
-          return_client(client)
-        else   
-          add_client if add_client?
-       end
-        @pool
-      end
-    end
-    
-    # Run the block on the retrieved client. Good for ensure the same client
-    # is used for multiple requests. For HTTP requests make sure you request has
-    # keep-alive properly set for your client
-    # EX:
-    #   @pool = HotTub.new(HotTub::ExconClient.new("https://some_web_site.com"))
-    #   results = []
-    #   @pool.run do |client|
-    #     results.push  (client.get(:query => {:foo => "bar"}))
-    #     results.push  (client.get(:query => {:bar => "foo"})) # reuse client
+    #   sessions = HotTub::Session.new(:client_options => {:connect_timeout => 10})
+    #
+    #   sessions.run("https://wwww.yahoo.com") do |conn|
+    #     p conn.head.response_header.status
     #   end
     #
-    def run(&block)
-      client = fetch     
-      if block_given?
-        block.call(client)
-      else
-        raise ArgumentError, 'Run requires a block.'
-      end
-    ensure
-      pool(client) if client
-    end
-   
-
-    # Let pool instance respond to client methods. For HTTP request make sure you 
-    # requests has keep-alive properly set for your client
-    # EX: 
-    #   @pool = HotTub.new(HotTub::ExconClient.new("https://some_web_site.com"))
-    #   r1 = @pool.get(:query => {:foo => "bar"})
-    #   r2 = @pool.get(:query => {:bar => "foo"}) # uses a different client
+    #   sessions.run("https://wwww.google.com") do |conn|
+    #     p conn.head.response_header.status
+    #   end
     #
-    def method_missing(method, *args, &blk)
-      client = fetch
-      client.send(method,*args,&blk)
-    ensure
-      pool(client) if client
-    end
-    
-    private
-    
-    def add_client?
-      (@pool.empty? && (@pool_data[:current_size] < @options[:size]))
-    end
-             
-    def new_client
-      @client.dup
-    end 
-        
-    def add_client
-      HotTub.logger.info "Adding HotTub client: #{@client.class.name} to pool"
-      @pool_data[:current_size] += 1
-      @pool << new_client         
-      @pool
-    end
-    
-    # return a client to the pool
-    def return_client(client)
-      if @pool.length < @options[:size]
-        @pool << client
-      else
-        HotTub.logger.info "Closed extra client for #{@client.class.name}."
-        client.close # Too hot in the hot tub...
-      end
+    # Other client classes
+    # If you have your own client class you can use sessions but your client class must initialize similar to
+    # EmHttpRequest, accepting a URI and options see: hot_tub/clients/em_http_request_client.rb
+    # Example Custom Client:
+    #
+    #   sessions = HotTub::Session.new(:client_class => MyClient, :client_options => {:connect_timeout => 10})
+    #
+    #   sessions.run("https://wwww.yahoo.com") do |conn|
+    #     p conn.head.response_header.status # => create pool for "https://wwww.yahoo.com"
+    #   end
+    #
+    #   sessions.run("https://wwww.google.com") do |conn|
+    #     p conn.head.response_header.status # => create separate pool for "https://wwww.google.com"
+    #   end
+    def initialize(options={},&client_block)
+      raise ArgumentError, "HotTub::Sessions requre a block on initialization that accepts a single argument" unless block_given?
+      @client_block = client_block
+      @options = {
+        :size => 5,
+        :never_block => true,
+        :blocking_timeout => 10,
+        :client_class => nil, # EmHttpRequestClient
+        :client_options => {}
+      }.merge(options || {})
+      @sessions = Hash.new
+      @mutex = (HotTub.em? ? EM::Synchrony::Thread::Mutex.new : Mutex.new)
     end
-    
-    # Fetches an available client from the pool.
-    # Hot tubs are not always clean... Make sure we have a good client. The client
-    # should respond to clean, which checks to make sure the client is still 
-    # viable, and reset if necessary.
-    def fetch        
-      client = nil
-      alarm = (Time.now + @options[:blocking_timeout])       
-      # block until we get an available client or raise Timeout::Error     
-      while client.nil?
-        raise_alarm if alarm <= Time.now
-        client = pool.shift
-        if client.nil? && (@options[:never_block])
-          HotTub.logger.info "Adding never_block client for #{@client.class.name}."
-          client = new_client
-          client.mark_temporary
+
+    # Synchronize access to our key hash
+    # expects a url string or URI
+    def sessions(url)
+      @mutex.synchronize do
+        if url.is_a?(String)
+          uri = URI(url)
+        elsif url.is_a?(URI)
+          uri = url
+        else
+          raise ArgumentError, "you must pass a string or a URI object"
         end
+        @sessions["#{uri.scheme}-#{uri.host}"] ||= HotTub::Pool.new(@options) { @client_block.call(url) }
       end
-      client.clean
-      client
     end
- 
-    def raise_alarm
-      message = "Could not fetch a free client in time. Consider increasing your pool size for #{@client.class.name}."
-      HotTub.logger.error message
-      raise Timeout::Error, message    
+
+    # Hand off to pool.run
+    def run(url,&block)
+      pool = sessions(url)
+      pool.run(&block) if pool
     end
   end
-end
+end