sphinx 0.9.10 → 0.9.10.2043

data/.gitignore

@@ -1,2 +1,2 @@
-doc
-pkg
+rdoc
+pkg

data/Rakefile

@@ -31,6 +31,6 @@ Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title    = 'Sphinx Client API'
   rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('README.rdoc')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end

data/VERSION.yml

@@ -2,3 +2,4 @@
 :major: 0
 :minor: 9
 :patch: 10
+:build: 2043

data/lib/sphinx.rb

@@ -1,6 +1,12 @@
+require 'socket'
+require 'net/protocol'
+
+module Sphinx
+end
+
 require File.dirname(__FILE__) + '/sphinx/request'
 require File.dirname(__FILE__) + '/sphinx/response'
+require File.dirname(__FILE__) + '/sphinx/timeout'
+require File.dirname(__FILE__) + '/sphinx/buffered_io'
+require File.dirname(__FILE__) + '/sphinx/server'
 require File.dirname(__FILE__) + '/sphinx/client'
-
-module Sphinx
-end

data/lib/sphinx/buffered_io.rb

@@ -0,0 +1,22 @@
+class Sphinx::BufferedIO < Net::BufferedIO # :nodoc:
+  BUFSIZE = 1024 * 16
+
+  if RUBY_VERSION < '1.9.1'
+    def rbuf_fill
+      begin
+        @rbuf << @io.read_nonblock(BUFSIZE)
+      rescue Errno::EWOULDBLOCK
+        retry unless @read_timeout
+        if IO.select([@io], nil, nil, @read_timeout)
+          retry
+        else
+          raise Timeout::Error, 'IO timeout'
+        end
+      end
+    end
+  end
+
+  def setsockopt(*args)
+    @io.setsockopt(*args)
+  end
+end

data/lib/sphinx/client.rb

@@ -24,13 +24,10 @@
 #   docs = posts.map(&:body)
 #   excerpts = sphinx.BuildExcerpts(docs, 'index', 'test')
 
-require 'socket'
-
 module Sphinx
   # :stopdoc:
 
   class SphinxError < StandardError; end
-  class SphinxArgumentError < SphinxError; end
   class SphinxConnectError < SphinxError; end
   class SphinxResponseError < SphinxError; end
   class SphinxInternalError < SphinxError; end
@@ -40,7 +37,6 @@ module Sphinx
   # :startdoc:
 
   class Client
-  
     # :stopdoc:
   
     # Known searchd commands
@@ -91,6 +87,12 @@ module Sphinx
     SEARCHD_RETRY   = 2
     # general success, warning message and command-specific reply follow 
     SEARCHD_WARNING = 3    
+
+    attr_reader :servers
+    attr_reader :timeout
+    attr_reader :retries
+    attr_reader :reqtimeout
+    attr_reader :reqretries
     
     # :startdoc:
   
@@ -191,12 +193,6 @@ module Sphinx
     
     # Constructs the <tt>Sphinx::Client</tt> object and sets options to their default values. 
     def initialize
-      # per-client-object settings
-      @host          = 'localhost'             # searchd host (default is "localhost")
-      @port          = 3312                    # searchd port (default is 3312)
-      @path          = false
-      @socket        = false
-      
       # per-query settings
       @offset        = 0                       # how many records to seek from result-set start (default is 0)
       @limit         = 20                      # how many records to return from result-set starting at offset (default is 20)
@@ -231,56 +227,204 @@ module Sphinx
       @reqs          = []                      # requests storage (for multi-query case)
       @mbenc         = ''                      # stored mbstring encoding
       @timeout       = 0                       # connect timeout
+      @retries       = 1                       # number of connect retries in case of emergency
+      @reqtimeout    = 0                       # request timeout
+      @reqretries    = 1                       # number of request retries in case of emergency
+
+      # per-client-object settings
+      # searchd servers list
+      @servers       = [Sphinx::Server.new(self, 'localhost', 3312, false)].freeze
+      @lastserver    = -1
     end
   
-    # Get last error message.
+    # Returns last error message, as a string, in human readable format. If there
+    # were no errors during the previous API call, empty string is returned.
+    #
+    # You should call it when any other function (such as +Query+) fails (typically,
+    # the failing function returns false). The returned string will contain the
+    # error description.
+    #
+    # The error message is not reset by this call; so you can safely call it
+    # several times if needed.
+    #
     def GetLastError
       @error
     end
     
-    # Get last warning message.
+    # Returns last warning message, as a string, in human readable format. If there
+    # were no warnings during the previous API call, empty string is returned.
+    #
+    # You should call it to verify whether your request (such as +Query+) was
+    # completed but with warnings. For instance, search query against a distributed
+    # index might complete succesfully even if several remote agents timed out.
+    # In that case, a warning message would be produced.
+    # 
+    # The warning message is not reset by this call; so you can safely call it
+    # several times if needed.
+    #
     def GetLastWarning
       @warning
     end
     
-    # Get last error flag (to tell network connection errors from
-    # searchd errors or broken responses)
+    # Checks whether the last error was a network error on API side, or a
+    # remote error reported by searchd. Returns true if the last connection
+    # attempt to searchd failed on API side, false otherwise (if the error
+    # was remote, or there were no connection attempts at all).
+    #
     def IsConnectError
-      @connerror
+      @connerror || false
     end
     
-    # Set searchd host name (string) and port (integer).
+    # Sets searchd host name and TCP port. All subsequent requests will
+    # use the new host and port settings. Default +host+ and +port+ are
+    # 'localhost' and 3312, respectively.
+    #
+    # Also, you can specify an absolute path to Sphinx's UNIX socket as +host+,
+    # in this case pass port as +0+ or +nil+.
+    #
     def SetServer(host, port)
-      assert { host.instance_of? String }
+      raise ArgumentError, '"host" argument must be String' unless host.kind_of?(String)
       
+      path = nil
+      # Check if UNIX socket should be used
       if host[0] == ?/
-        @path = host
-        return
+        path = host
       elsif host[0, 7] == 'unix://'
-        @path = host[7..-1]
+        path = host[7..-1]
+      else
+        raise ArgumentError, '"port" argument must be Integer' unless port.respond_to?(:integer?) and port.integer?
       end
+
+      host = port = nil unless path.nil?
+
+      @servers = [Sphinx::Server.new(self, host, port, path)].freeze
+    end
+
+    # Sets the list of searchd servers. Each subsequent request will use next
+    # server in list (round-robin). In case of one server failure, request could
+    # be retried on another server (see +SetConnectTimeout+ and +SetRequestTimeout+).
+    #
+    # Method accepts an +Array+ of +Hash+es, each of them should have :host
+    # and :port (to connect to searchd through network) or :path (an absolute path
+    # to UNIX socket) specified.
+    #
+    def SetServers(servers)
+      raise ArgumentError, '"servers" argument must be Array'     unless servers.kind_of?(Array)
+      raise ArgumentError, '"servers" argument must be not empty' if servers.empty?
       
-      assert { port.instance_of? Fixnum }
+      @servers = servers.map do |server|
+        raise ArgumentError, '"servers" argument must be Array of Hashes' unless server.kind_of?(Hash)
+
+        host = server[:path] || server['path'] || server[:host] || server['host']
+        port = server[:port] || server['port']
+        path = nil
+        raise ArgumentError, '"host" argument must be String' unless host.kind_of?(String)
+
+        # Check if UNIX socket should be used
+        if host[0] == ?/
+          path = host
+        elsif host[0, 7] == 'unix://'
+          path = host[7..-1]
+        else
+          raise ArgumentError, '"port" argument must be Integer' unless port.respond_to?(:integer?) and port.integer?
+        end
 
-      @host = host
-      @port = port
+        host = port = nil unless path.nil?
+        
+        Sphinx::Server.new(self, host, port, path)
+      end.freeze
     end
     
-    def SetConnectTimeout(timeout)
-      assert { timeout.instance_of? Fixnum }
+    # Sets the time allowed to spend connecting to the server before giving up
+    # and number of retries to perform.
+    #
+    # In the event of a failure to connect, an appropriate error code should
+    # be returned back to the application in order for application-level error
+    # handling to advise the user.
+    #
+    # When multiple servers configured through +SetServers+ method, and +retries+
+    # number is greater than 1, library will try to connect to another server.
+    # In case of single server configured, it will try to reconnect +retries+
+    # times.
+    #
+    # Please note, this timeout will only be used for connection establishing, not
+    # for regular API requests.
+    #
+    def SetConnectTimeout(timeout, retries = 1)
+      raise ArgumentError, '"timeout" argument must be Integer'        unless timeout.respond_to?(:integer?) and timeout.integer?
+      raise ArgumentError, '"retries" argument must be Integer'        unless retries.respond_to?(:integer?) and retries.integer?
+      raise ArgumentError, '"retries" argument must be greater than 0' unless retries > 0
       
       @timeout = timeout
+      @retries = retries
+    end
+    
+    # Sets the time allowed to spend performing request to the server before giving up
+    # and number of retries to perform.
+    #
+    # In the event of a failure to do request, an appropriate error code should
+    # be returned back to the application in order for application-level error
+    # handling to advise the user.
+    #
+    # When multiple servers configured through +SetServers+ method, and +retries+
+    # number is greater than 1, library will try to do another try with this server
+    # (with full reconnect). If connection would fail, behavior depends on
+    # +SetConnectTimeout+ settings.
+    #
+    # Please note, this timeout will only be used for request performing, not
+    # for connection establishing.
+    #
+    def SetRequestTimeout(timeout, retries = 1)
+      raise ArgumentError, '"timeout" argument must be Integer'        unless timeout.respond_to?(:integer?) and timeout.integer?
+      raise ArgumentError, '"retries" argument must be Integer'        unless retries.respond_to?(:integer?) and retries.integer?
+      raise ArgumentError, '"retries" argument must be greater than 0' unless retries > 0
+      
+      @reqtimeout = timeout
+      @reqretries = retries
     end
    
-    # Set offset and count into result set,
-    # and optionally set max-matches and cutoff limits.
+    # Sets offset into server-side result set (+offset+) and amount of matches to
+    # return to client starting from that offset (+limit+). Can additionally control
+    # maximum server-side result set size for current query (+max_matches+) and the
+    # threshold amount of matches to stop searching at (+cutoff+). All parameters
+    # must be non-negative integers.
+    #
+    # First two parameters to +SetLimits+ are identical in behavior to MySQL LIMIT
+    # clause. They instruct searchd to return at most +limit+ matches starting from
+    # match number +offset+. The default offset and limit settings are +0+ and +20+,
+    # that is, to return first +20+ matches.
+    # 
+    # +max_matches+ setting controls how much matches searchd will keep in RAM
+    # while searching. All matching documents will be normally processed, ranked,
+    # filtered, and sorted even if max_matches is set to +1+. But only best +N+
+    # documents are stored in memory at any given moment for performance and RAM
+    # usage reasons, and this setting controls that N. Note that there are two
+    # places where max_matches limit is enforced. Per-query limit is controlled
+    # by this API call, but there also is per-server limit controlled by +max_matches+
+    # setting in the config file. To prevent RAM usage abuse, server will not
+    # allow to set per-query limit higher than the per-server limit.
+    #
+    # You can't retrieve more than +max_matches+ matches to the client application.
+    # The default limit is set to +1000+. Normally, you must not have to go over
+    # this limit. One thousand records is enough to present to the end user.
+    # And if you're thinking about pulling the results to application for further
+    # sorting or filtering, that would be much more efficient if performed on
+    # Sphinx side.
+    #
+    # +cutoff+ setting is intended for advanced performance control. It tells
+    # searchd to forcibly stop search query once $cutoff matches had been found
+    # and processed.
+    #
     def SetLimits(offset, limit, max = 0, cutoff = 0)
-      assert { offset.instance_of? Fixnum }
-      assert { limit.instance_of? Fixnum }
-      assert { max.instance_of? Fixnum }
-      assert { offset >= 0 }
-      assert { limit > 0 }
-      assert { max >= 0 }
+      raise ArgumentError, '"offset" argument must be Integer' unless offset.respond_to?(:integer?) and offset.integer?
+      raise ArgumentError, '"limit" argument must be Integer'  unless limit.respond_to?(:integer?)  and limit.integer?
+      raise ArgumentError, '"max" argument must be Integer'    unless max.respond_to?(:integer?)    and max.integer?
+      raise ArgumentError, '"cutoff" argument must be Integer' unless cutoff.respond_to?(:integer?) and cutoff.integer?
+      
+      raise ArgumentError, '"offset" argument should be greater or equal to zero' unless offset >= 0
+      raise ArgumentError, '"limit" argument should be greater to zero'           unless limit > 0
+      raise ArgumentError, '"max" argument should be greater or equal to zero'    unless max >= 0
+      raise ArgumentError, '"cutoff" argument should be greater or equal to zero' unless cutoff >= 0
 
       @offset = offset
       @limit = limit
@@ -288,51 +432,92 @@ module Sphinx
       @cutoff = cutoff if cutoff > 0
     end
     
-    # Set maximum query time, in milliseconds, per-index,
-    # integer, 0 means "do not limit"
+    # Sets maximum search query time, in milliseconds. Parameter must be a
+    # non-negative integer. Default valus is +0+ which means "do not limit".
+    #
+    # Similar to +cutoff+ setting from +SetLimits+, but limits elapsed query
+    # time instead of processed matches count. Local search queries will be
+    # stopped once that much time has elapsed. Note that if you're performing
+    # a search which queries several local indexes, this limit applies to each
+    # index separately.
+    #
     def SetMaxQueryTime(max)
-      assert { max.instance_of? Fixnum }
-      assert { max >= 0 }
+      raise ArgumentError, '"max" argument must be Integer' unless max.respond_to?(:integer?) and max.integer?
+      raise ArgumentError, '"max" argument should be greater or equal to zero' unless max >= 0
+
       @maxquerytime = max
     end
     
-    # Set matching mode.
+    # Sets full-text query matching mode.
+    #
+    # Parameter must be a +Fixnum+ constant specifying one of the known modes
+    # (+SPH_MATCH_ALL+, +SPH_MATCH_ANY+, etc), +String+ with identifier (<tt>"all"</tt>,
+    # <tt>"any"</tt>, etc), or a +Symbol+ (<tt>:all</tt>, <tt>:any</tt>, etc).
+    #
+    # Corresponding sections in Sphinx reference manual:
+    # * {Section 4.1, "Matching modes"}[http://www.sphinxsearch.com/docs/current.html#matching-modes] for details.
+    # * {Section 6.3.1, "SetMatchMode"}[http://www.sphinxsearch.com/docs/current.html#api-func-setmatchmode] for details.
+    #
     def SetMatchMode(mode)
-      assert { mode == SPH_MATCH_ALL \
-            || mode == SPH_MATCH_ANY \
-            || mode == SPH_MATCH_PHRASE \
-            || mode == SPH_MATCH_BOOLEAN \
-            || mode == SPH_MATCH_EXTENDED \
-            || mode == SPH_MATCH_FULLSCAN \
-            || mode == SPH_MATCH_EXTENDED2 }
+      case mode
+        when String, Symbol
+          begin
+            mode = self.class.const_get("SPH_MATCH_#{mode.to_s.upcase}")
+          rescue NameError
+            raise ArgumentError, "\"mode\" argument value \"#{mode}\" is invalid"
+          end
+        when Fixnum
+          raise ArgumentError, "\"mode\" argument value \"#{mode}\" is invalid" unless (SPH_MATCH_ALL..SPH_MATCH_EXTENDED2).include?(mode)
+        else
+          raise ArgumentError, '"mode" argument must be Fixnum, String, or Symbol'
+      end
 
       @mode = mode
     end
     
     # Set ranking mode.
+    #
+    # You can specify ranking mode as String ("proximity_bm25", "bm25", etc),
+    # Symbol (:proximity_bm25, :bm25, etc), or
+    # Fixnum constant (SPH_RANK_PROXIMITY_BM25, SPH_RANK_BM25, etc).
     def SetRankingMode(ranker)
-      assert { ranker == SPH_RANK_PROXIMITY_BM25 \
-            || ranker == SPH_RANK_BM25 \
-            || ranker == SPH_RANK_NONE \
-            || ranker == SPH_RANK_WORDCOUNT \
-            || ranker == SPH_RANK_PROXIMITY \
-            || ranker == SPH_RANK_MATCHANY \
-            || ranker == SPH_RANK_FIELDMASK \
-            || ranker == SPH_RANK_SPH04 }
+      case ranker
+        when String, Symbol
+          begin
+            ranker = self.class.const_get("SPH_RANK_#{ranker.to_s.upcase}")
+          rescue NameError
+            raise ArgumentError, "\"ranker\" argument value \"#{ranker}\" is invalid"
+          end
+        when Fixnum
+          raise ArgumentError, "\"ranker\" argument value \"#{ranker}\" is invalid" unless (SPH_RANK_PROXIMITY_BM25..SPH_RANK_SPH04).include?(ranker)
+        else
+          raise ArgumentError, '"ranker" argument must be Fixnum, String, or Symbol'
+      end
 
       @ranker = ranker
     end
     
     # Set matches sorting mode.
+    #
+    # You can specify sorting mode as String ("relevance", "attr_desc", etc),
+    # Symbol (:relevance, :attr_desc, etc), or
+    # Fixnum constant (SPH_SORT_RELEVANCE, SPH_SORT_ATTR_DESC, etc).
     def SetSortMode(mode, sortby = '')
-      assert { mode == SPH_SORT_RELEVANCE \
-            || mode == SPH_SORT_ATTR_DESC \
-            || mode == SPH_SORT_ATTR_ASC \
-            || mode == SPH_SORT_TIME_SEGMENTS \
-            || mode == SPH_SORT_EXTENDED \
-            || mode == SPH_SORT_EXPR }
-      assert { sortby.instance_of? String }
-      assert { mode == SPH_SORT_RELEVANCE || !sortby.empty? }
+      case mode
+        when String, Symbol
+          begin
+            mode = self.class.const_get("SPH_SORT_#{mode.to_s.upcase}")
+          rescue NameError
+            raise ArgumentError, "\"mode\" argument value \"#{mode}\" is invalid"
+          end
+        when Fixnum
+          raise ArgumentError, "\"mode\" argument value \"#{mode}\" is invalid" unless (SPH_SORT_RELEVANCE..SPH_SORT_EXPR).include?(mode)
+        else
+          raise ArgumentError, '"mode" argument must be Fixnum, String, or Symbol'
+      end
+
+      raise ArgumentError, '"sortby" argument must be String' unless sortby.kind_of?(String)
+      raise ArgumentError, '"sortby" should not be empty unless mode is SPH_SORT_RELEVANCE' unless mode == SPH_SORT_RELEVANCE or !sortby.empty?
 
       @sort = mode
       @sortby = sortby
@@ -342,9 +527,9 @@ module Sphinx
     #
     # DEPRECATED; use SetFieldWeights() instead.
     def SetWeights(weights)
-      assert { weights.instance_of? Array }
+      raise ArgumentError, '"weights" argument must be Array' unless weights.kind_of?(Array)
       weights.each do |weight|
-        assert { weight.instance_of? Fixnum }
+        raise ArgumentError, '"weights" argument must be Array of integers' unless weight.respond_to?(:integer?) and weight.integer?
       end
 
       @weights = weights
@@ -352,15 +537,16 @@ module Sphinx
 
     # Bind per-field weights by name.
     #
-    # Takes string (field name) to integer name (field weight) hash as an argument.
+    # Takes string (field name) to integer (field weight) hash as an argument.
     # * Takes precedence over SetWeights().
     # * Unknown names will be silently ignored.
     # * Unbound fields will be silently given a weight of 1.
     def SetFieldWeights(weights)
-      assert { weights.instance_of? Hash }
+      raise ArgumentError, '"weights" argument must be Hash' unless weights.kind_of?(Hash)
       weights.each do |name, weight|
-        assert { name.instance_of? String }
-        assert { weight.instance_of? Fixnum }
+        unless (name.kind_of?(String) or name.kind_of?(Symbol)) and (weight.respond_to?(:integer?) and weight.integer?)
+          raise ArgumentError, '"weights" argument must be Hash map of strings to integers'
+        end
       end
 
       @fieldweights = weights
@@ -368,10 +554,11 @@ module Sphinx
     
     # Bind per-index weights by name.
     def SetIndexWeights(weights)
-      assert { weights.instance_of? Hash }
+      raise ArgumentError, '"weights" argument must be Hash' unless weights.kind_of?(Hash)
       weights.each do |index, weight|
-        assert { index.instance_of? String }
-        assert { weight.instance_of? Fixnum }
+        unless (index.kind_of?(String) or index.kind_of?(Symbol)) and (weight.respond_to?(:integer?) and weight.integer?)
+          raise ArgumentError, '"weights" argument must be Hash map of strings to integers'
+        end
       end
       
       @indexweights = weights
@@ -381,9 +568,9 @@ module Sphinx
     # 
     # Only match records if document ID is beetwen <tt>min_id</tt> and <tt>max_id</tt> (inclusive). 
     def SetIDRange(min, max)
-      assert { min.instance_of?(Fixnum) or min.instance_of?(Bignum) }
-      assert { max.instance_of?(Fixnum) or max.instance_of?(Bignum) }
-      assert { min <= max }
+      raise ArgumentError, '"min" argument must be Integer' unless min.respond_to?(:integer?) and min.integer?
+      raise ArgumentError, '"max" argument must be Integer' unless max.respond_to?(:integer?) and max.integer?
+      raise ArgumentError, '"max" argument greater or equal to "min"' unless min <= max
 
       @min_id = min
       @max_id = max
@@ -394,17 +581,16 @@ module Sphinx
     # Only match those records where <tt>attribute</tt> column values
     # are in specified set.
     def SetFilter(attribute, values, exclude = false)
-      assert { attribute.instance_of? String }
-      assert { values.instance_of? Array }
-      assert { !values.empty? }
+      raise ArgumentError, '"attribute" argument must be String or Symbol' unless attribute.kind_of?(String) or attribute.kind_of?(Symbol)
+      raise ArgumentError, '"values" argument must be Array'               unless values.kind_of?(Array)
+      raise ArgumentError, '"values" argument must not be empty'           if values.empty?
+      raise ArgumentError, '"exclude" argument must be Boolean'            unless exclude.kind_of?(TrueClass) or exclude.kind_of?(FalseClass)
 
-      if values.instance_of?(Array) && values.size > 0
-        values.each do |value|
-          assert { value.instance_of? Fixnum }
-        end
-      
-        @filters << { 'type' => SPH_FILTER_VALUES, 'attr' => attribute, 'exclude' => exclude, 'values' => values }
+      values.each do |value|
+        raise ArgumentError, '"values" argument must be Array of Integer' unless value.respond_to?(:integer?) and value.integer?
       end
+    
+      @filters << { 'type' => SPH_FILTER_VALUES, 'attr' => attribute.to_s, 'exclude' => exclude, 'values' => values }
     end
     
     # Set range filter.
@@ -412,12 +598,13 @@ module Sphinx
     # Only match those records where <tt>attribute</tt> column value
     # is beetwen <tt>min</tt> and <tt>max</tt> (including <tt>min</tt> and <tt>max</tt>).
     def SetFilterRange(attribute, min, max, exclude = false)
-      assert { attribute.instance_of? String }
-      assert { min.instance_of? Fixnum or min.instance_of? Bignum }
-      assert { max.instance_of? Fixnum or max.instance_of? Bignum }
-      assert { min <= max }
+      raise ArgumentError, '"attribute" argument must be String or Symbol' unless attribute.kind_of?(String) or attribute.kind_of?(Symbol)
+      raise ArgumentError, '"min" argument must be Integer'                unless min.respond_to?(:integer?) and min.integer?
+      raise ArgumentError, '"max" argument must be Integer'                unless max.respond_to?(:integer?) and max.integer?
+      raise ArgumentError, '"max" argument greater or equal to "min"'      unless min <= max
+      raise ArgumentError, '"exclude" argument must be Boolean'            unless exclude.kind_of?(TrueClass) or exclude.kind_of?(FalseClass)
     
-      @filters << { 'type' => SPH_FILTER_RANGE, 'attr' => attribute, 'exclude' => exclude, 'min' => min, 'max' => max }
+      @filters << { 'type' => SPH_FILTER_RANGE, 'attr' => attribute.to_s, 'exclude' => exclude, 'min' => min, 'max' => max }
     end
     
     # Set float range filter.
@@ -425,12 +612,13 @@ module Sphinx
     # Only match those records where <tt>attribute</tt> column value
     # is beetwen <tt>min</tt> and <tt>max</tt> (including <tt>min</tt> and <tt>max</tt>).
     def SetFilterFloatRange(attribute, min, max, exclude = false)
-      assert { attribute.instance_of? String }
-      assert { min.instance_of? Float }
-      assert { max.instance_of? Float }
-      assert { min <= max }
+      raise ArgumentError, '"attribute" argument must be String or Symbol' unless attribute.kind_of?(String) or attribute.kind_of?(Symbol)
+      raise ArgumentError, '"min" argument must be Float or Integer'       unless min.kind_of?(Float) or (min.respond_to?(:integer?) and min.integer?)
+      raise ArgumentError, '"max" argument must be Float or Integer'       unless max.kind_of?(Float) or (max.respond_to?(:integer?) and max.integer?)
+      raise ArgumentError, '"max" argument greater or equal to "min"'      unless min <= max
+      raise ArgumentError, '"exclude" argument must be Boolean'            unless exclude.kind_of?(TrueClass) or exclude.kind_of?(FalseClass)
     
-      @filters << { 'type' => SPH_FILTER_FLOATRANGE, 'attr' => attribute, 'exclude' => exclude, 'min' => min, 'max' => max }
+      @filters << { 'type' => SPH_FILTER_FLOATRANGE, 'attr' => attribute.to_s, 'exclude' => exclude, 'min' => min.to_f, 'max' => max.to_f }
     end
     
     # Setup anchor point for geosphere distance calculations.
@@ -444,12 +632,12 @@ module Sphinx
     # * <tt>lat</tt> -- is anchor point latitude, in radians
     # * <tt>long</tt> -- is anchor point longitude, in radians
     def SetGeoAnchor(attrlat, attrlong, lat, long)
-      assert { attrlat.instance_of? String }
-      assert { attrlong.instance_of? String }
-      assert { lat.instance_of? Float }
-      assert { long.instance_of? Float }
+      raise ArgumentError, '"attrlat" argument must be String or Symbol'  unless attrlat.kind_of?(String)  or attrlat.kind_of?(Symbol)
+      raise ArgumentError, '"attrlong" argument must be String or Symbol' unless attrlong.kind_of?(String) or attrlong.kind_of?(Symbol)
+      raise ArgumentError, '"lat" argument must be Float or Integer'      unless lat.kind_of?(Float)  or (lat.respond_to?(:integer?)  and lat.integer?)
+      raise ArgumentError, '"long" argument must be Float or Integer'     unless long.kind_of?(Float) or (long.respond_to?(:integer?) and long.integer?)
 
-      @anchor = { 'attrlat' => attrlat, 'attrlong' => attrlong, 'lat' => lat, 'long' => long }
+      @anchor = { 'attrlat' => attrlat.to_s, 'attrlong' => attrlong.to_s, 'lat' => lat.to_f, 'long' => long.to_f }
     end
     
     # Set grouping attribute and function.
@@ -489,60 +677,167 @@ module Sphinx
     # matches published, with day number and per-day match count attached,
     # and sorted by day number in descending order (ie. recent days first).
     def SetGroupBy(attribute, func, groupsort = '@group desc')
-      assert { attribute.instance_of? String }
-      assert { groupsort.instance_of? String }
-      assert { func == SPH_GROUPBY_DAY \
-            || func == SPH_GROUPBY_WEEK \
-            || func == SPH_GROUPBY_MONTH \
-            || func == SPH_GROUPBY_YEAR \
-            || func == SPH_GROUPBY_ATTR \
-            || func == SPH_GROUPBY_ATTRPAIR }
+      raise ArgumentError, '"attribute" argument must be String or Symbol' unless attribute.kind_of?(String)  or attribute.kind_of?(Symbol)
+      raise ArgumentError, '"groupsort" argument must be String'           unless groupsort.kind_of?(String)
+
+      case func
+        when String, Symbol
+          begin
+            func = self.class.const_get("SPH_GROUPBY_#{func.to_s.upcase}")
+          rescue NameError
+            raise ArgumentError, "\"func\" argument value \"#{func}\" is invalid"
+          end
+        when Fixnum
+          raise ArgumentError, "\"func\" argument value \"#{func}\" is invalid" unless (SPH_GROUPBY_DAY..SPH_GROUPBY_ATTRPAIR).include?(func)
+        else
+          raise ArgumentError, '"func" argument must be Fixnum, String, or Symbol'
+      end
 
-      @groupby = attribute
+      @groupby = attribute.to_s
       @groupfunc = func
       @groupsort = groupsort
     end
     
     # Set count-distinct attribute for group-by queries.
     def SetGroupDistinct(attribute)
-      assert { attribute.instance_of? String }
-      @groupdistinct = attribute
+      raise ArgumentError, '"attribute" argument must be String or Symbol' unless attribute.kind_of?(String)  or attribute.kind_of?(Symbol)
+
+      @groupdistinct = attribute.to_s
     end
     
-    # Set distributed retries count and delay.
+    # Sets distributed retry count and delay.
+    #
+    # On temporary failures searchd will attempt up to +count+ retries per
+    # agent. +delay+ is the delay between the retries, in milliseconds. Retries
+    # are disabled by default. Note that this call will not make the API itself
+    # retry on temporary failure; it only tells searchd to do so. Currently,
+    # the list of temporary failures includes all kinds of +connect+
+    # failures and maxed out (too busy) remote agents.
+    #
     def SetRetries(count, delay = 0)
-      assert { count.instance_of? Fixnum }
-      assert { delay.instance_of? Fixnum }
+      raise ArgumentError, '"count" argument must be Integer' unless count.respond_to?(:integer?) and count.integer?
+      raise ArgumentError, '"delay" argument must be Integer' unless delay.respond_to?(:integer?) and delay.integer?
       
       @retrycount = count
       @retrydelay = delay
     end
     
-    # Set attribute values override
+    # Sets temporary (per-query) per-document attribute value overrides. Only
+    # supports scalar attributes. +values+ must be a +Hash+ that maps document
+    # IDs to overridden attribute values.
+    #
+    # Override feature lets you "temporary" update attribute values for some
+    # documents within a single query, leaving all other queries unaffected.
+    # This might be useful for personalized data. For example, assume you're
+    # implementing a personalized search function that wants to boost the posts
+    # that the user's friends recommend. Such data is not just dynamic, but
+    # also personal; so you can't simply put it in the index because you don't
+    # want everyone's searches affected. Overrides, on the other hand, are local
+    # to a single query and invisible to everyone else. So you can, say, setup
+    # a "friends_weight" value for every document, defaulting to 0, then
+    # temporary override it with 1 for documents 123, 456 and 789 (recommended
+    # by exactly the friends of current user), and use that value when ranking.
     #
-    # There can be only one override per attribute.
-    # +values+ must be a hash that maps document IDs to attribute values.
     def SetOverride(attrname, attrtype, values)
-      assert { attrname.instance_of? String }
-      assert { [SPH_ATTR_INTEGER, SPH_ATTR_TIMESTAMP, SPH_ATTR_BOOL, SPH_ATTR_FLOAT, SPH_ATTR_BIGINT].include?(attrtype) }
-      assert { values.instance_of? Hash }
+      raise ArgumentError, '"attrname" argument must be String or Symbol' unless attrname.kind_of?(String) or attrname.kind_of?(Symbol)
+
+      case attrtype
+        when String, Symbol
+          begin
+            attrtype = self.class.const_get("SPH_ATTR_#{attrtype.to_s.upcase}")
+          rescue NameError
+            raise ArgumentError, "\"attrtype\" argument value \"#{attrtype}\" is invalid"
+          end
+        when Fixnum
+          raise ArgumentError, "\"attrtype\" argument value \"#{attrtype}\" is invalid" unless (SPH_ATTR_INTEGER..SPH_ATTR_BIGINT).include?(attrtype)
+        else
+          raise ArgumentError, '"attrtype" argument must be Fixnum, String, or Symbol'
+      end
 
-      @overrides << { 'attr' => attrname, 'type' => attrtype, 'values' => values }
+      raise ArgumentError, '"values" argument must be Hash' unless values.kind_of?(Hash)
+      
+      values.each do |id, value|
+        raise ArgumentError, '"values" argument must be Hash map of Integer to Integer or Time' unless id.respond_to?(:integer?) and id.integer?
+        case attrtype
+          when SPH_ATTR_TIMESTAMP
+            raise ArgumentError, '"values" argument must be Hash map of Integer to Integer or Time' unless (value.respond_to?(:integer?) and value.integer?) or value.kind_of?(Time)
+          when SPH_ATTR_FLOAT
+            raise ArgumentError, '"values" argument must be Hash map of Integer to Float or Integer' unless value.kind_of?(Float) or (value.respond_to?(:integer?) and value.integer?)
+          else
+            # SPH_ATTR_INTEGER, SPH_ATTR_ORDINAL, SPH_ATTR_BOOL, SPH_ATTR_BIGINT
+            raise ArgumentError, '"values" argument must be Hash map of Integer to Integer' unless value.respond_to?(:integer?) and value.integer?
+        end
+      end
+
+      @overrides << { 'attr' => attrname.to_s, 'type' => attrtype, 'values' => values }
     end
 
-    # Set select-list (attributes or expressions), SQL-like syntax.
+    # Sets the select clause, listing specific attributes to fetch, and
+    # expressions to compute and fetch. Clause syntax mimics SQL.
+    #
+    # +SetSelect+ is very similar to the part of a typical SQL query between
+    # +SELECT+ and +FROM+. It lets you choose what attributes (columns) to
+    # fetch, and also what expressions over the columns to compute and fetch.
+    # A certain difference from SQL is that expressions must always be aliased
+    # to a correct identifier (consisting of letters and digits) using +AS+
+    # keyword. SQL also lets you do that but does not require to. Sphinx enforces
+    # aliases so that the computation results can always be returned under a
+    #{ }"normal" name in the result set, used in other clauses, etc.
+    #
+    # Everything else is basically identical to SQL. Star ('*') is supported.
+    # Functions are supported. Arbitrary amount of expressions is supported.
+    # Computed expressions can be used for sorting, filtering, and grouping,
+    # just as the regular attributes.
+    #
+    # Starting with version 0.9.9-rc2, aggregate functions (<tt>AVG()</tt>,
+    # <tt>MIN()</tt>, <tt>MAX()</tt>, <tt>SUM()</tt>) are supported when using
+    # <tt>GROUP BY</tt>.
+    #
+    # Expression sorting (Section 4.5, “SPH_SORT_EXPR mode”) and geodistance
+    # functions (+SetGeoAnchor+) are now internally implemented
+    # using this computed expressions mechanism, using magic names '<tt>@expr</tt>'
+    # and '<tt>@geodist</tt>' respectively.
+    #
+    # Usage example:
+    #
+    #   sphinx.SetSelect('*, @weight+(user_karma+ln(pageviews))*0.1 AS myweight')
+    #   sphinx.SetSelect('exp_years, salary_gbp*{$gbp_usd_rate} AS salary_usd, IF(age>40,1,0) AS over40')
+    #   sphinx.SetSelect('*, AVG(price) AS avgprice')
+    #
     def SetSelect(select)
-      assert { select.instance_of? String }
+      raise ArgumentError, '"select" argument must be String' unless select.kind_of?(String)
+
       @select = select
     end
     
-    # Clear all filters (for multi-queries).
+    # Clears all currently set filters.
+    #
+    # This call is only normally required when using multi-queries. You might want
+    # to set different filters for different queries in the batch. To do that,
+    # you should call +ResetFilters+ and add new filters using the respective calls.
+    #
+    # Usage example:
+    #
+    #   sphinx.ResetFilters
+    #
     def ResetFilters
       @filters = []
       @anchor = []
     end
     
-    # Clear groupby settings (for multi-queries).
+    # Clears all currently group-by settings, and disables group-by.
+    #
+    # This call is only normally required when using multi-queries. You can
+    # change individual group-by settings using +SetGroupBy+ and +SetGroupDistinct+
+    # calls, but you can not disable group-by using those calls. +ResetGroupBy+
+    # fully resets previous group-by settings and disables group-by mode in the
+    # current state, so that subsequent +AddQuery+ calls can perform non-grouping
+    # searches.
+    #
+    # Usage example:
+    #
+    #   sphinx.ResetGroupBy
+    #
     def ResetGroupBy
       @groupby       = ''
       @groupfunc     = SPH_GROUPBY_DAY
@@ -582,7 +877,6 @@ module Sphinx
     # * <tt>'time'</tt> -- search time
     # * <tt>'words'</tt> -- hash which maps query terms (stemmed!) to ('docs', 'hits') hash
     def Query(query, index = '*', comment = '')
-      assert { @reqs.empty? }
       @reqs = []
       
       self.AddQuery(query, index, comment)
@@ -667,7 +961,7 @@ module Sphinx
       # per-index weights
       request.put_int @indexweights.length
       @indexweights.each do |idx, weight|
-        request.put_string idx
+        request.put_string idx.to_s
         request.put_int weight
       end
       
@@ -677,7 +971,7 @@ module Sphinx
       # per-field weights
       request.put_int @fieldweights.length
       @fieldweights.each do |field, weight|
-        request.put_string field
+        request.put_string field.to_s
         request.put_int weight
       end
       
@@ -690,17 +984,14 @@ module Sphinx
         request.put_string entry['attr']
         request.put_int entry['type'], entry['values'].size
         entry['values'].each do |id, val|
-          assert { id.instance_of?(Fixnum) || id.instance_of?(Bignum) }
-          assert { val.instance_of?(Fixnum) || val.instance_of?(Bignum) || val.instance_of?(Float) }
-          
           request.put_int64 id
           case entry['type']
             when SPH_ATTR_FLOAT
-              request.put_float val
+              request.put_float val.to_f
             when SPH_ATTR_BIGINT
-              request.put_int64 val
+              request.put_int64 val.to_i
             else
-              request.put_int val
+              request.put_int val.to_i
           end
         end
       end
@@ -723,6 +1014,7 @@ module Sphinx
     #
     # * <tt>'error'</tt> -- search error for this query
     # * <tt>'words'</tt> -- hash which maps query terms (stemmed!) to ( "docs", "hits" ) hash
+    #
     def RunQueries
       if @reqs.empty?
         @error = 'No queries defined, issue AddQuery() first'
@@ -732,7 +1024,7 @@ module Sphinx
       req = @reqs.join('')
       nreqs = @reqs.length
       @reqs = []
-      response = PerformRequest(:search, req, nreqs)
+      response = perform_request(:search, req, nreqs)
      
       # parse response
       begin
@@ -868,23 +1160,28 @@ module Sphinx
     #
     # Returns false on failure.
     # Returns an array of string excerpts on success.
+    #
     def BuildExcerpts(docs, index, words, opts = {})
-      assert { docs.instance_of? Array }
-      assert { index.instance_of? String }
-      assert { words.instance_of? String }
-      assert { opts.instance_of? Hash }
+      raise ArgumentError, '"docs" argument must be Array'   unless docs.kind_of?(Array)
+      raise ArgumentError, '"index" argument must be String' unless index.kind_of?(String) or index.kind_of?(Symbol)
+      raise ArgumentError, '"words" argument must be String' unless words.kind_of?(String)
+      raise ArgumentError, '"opts" argument must be Hash'    unless opts.kind_of?(Hash)
+
+      docs.each do |doc|
+        raise ArgumentError, '"docs" argument must be Array of Strings' unless doc.kind_of?(String)
+      end
 
       # fixup options
-      opts['before_match'] ||= '<b>';
-      opts['after_match'] ||= '</b>';
-      opts['chunk_separator'] ||= ' ... ';
-      opts['limit'] ||= 256;
-      opts['around'] ||= 5;
-      opts['exact_phrase'] ||= false
-      opts['single_passage'] ||= false
-      opts['use_boundaries'] ||= false
-      opts['weight_order'] ||= false
-      opts['query_mode'] ||= false
+      opts['before_match']    ||= opts[:before_match]    || '<b>';
+      opts['after_match']     ||= opts[:after_match]     || '</b>';
+      opts['chunk_separator'] ||= opts[:chunk_separator] || ' ... ';
+      opts['limit']           ||= opts[:limit]           || 256;
+      opts['around']          ||= opts[:around]          || 5;
+      opts['exact_phrase']    ||= opts[:exact_phrase]    || false
+      opts['single_passage']  ||= opts[:single_passage]  || false
+      opts['use_boundaries']  ||= opts[:use_boundaries]  || false
+      opts['weight_order']    ||= opts[:weight_order]    || false
+      opts['query_mode']      ||= opts[:query_mode]      || false
       
       # build request
       
@@ -899,7 +1196,7 @@ module Sphinx
       request = Request.new
       request.put_int 0, flags # mode=0, flags=1 (remove spaces)
       # req index
-      request.put_string index
+      request.put_string index.to_s
       # req words
       request.put_string words
   
@@ -911,13 +1208,9 @@ module Sphinx
       
       # documents
       request.put_int docs.size
-      docs.each do |doc|
-        assert { doc.instance_of? String }
-
-        request.put_string doc
-      end
+      request.put_string(*docs)
       
-      response = PerformRequest(:excerpt, request)
+      response = perform_request(:excerpt, request)
       
       # parse response
       begin
@@ -936,9 +1229,9 @@ module Sphinx
     #
     # Returns an array of words on success.
     def BuildKeywords(query, index, hits)
-      assert { query.instance_of? String }
-      assert { index.instance_of? String }
-      assert { hits.instance_of?(TrueClass) || hits.instance_of?(FalseClass) }
+      raise ArgumentError, '"query" argument must be String' unless query.kind_of?(String)
+      raise ArgumentError, '"index" argument must be String' unless index.kind_of?(String) or index.kind_of?(Symbol)
+      raise ArgumentError, '"hits" argument must be Boolean' unless hits.kind_of?(TrueClass) or hits.kind_of?(FalseClass)
       
       # build request
       request = Request.new
@@ -947,7 +1240,7 @@ module Sphinx
       request.put_string index # req index
       request.put_int hits ? 1 : 0
 
-      response = PerformRequest(:keywords, request)
+      response = perform_request(:keywords, request)
       
       # parse response
       begin
@@ -983,27 +1276,31 @@ module Sphinx
     #
     # Usage example:
     #    sphinx.UpdateAttributes('test1', ['group_id'], { 1 => [456] })
+    #    sphinx.UpdateAttributes('test1', ['group_id'], { 1 => [[456, 789]] }, true)
+    #
     def UpdateAttributes(index, attrs, values, mva = false)
       # verify everything
-      assert { index.instance_of? String }
-      assert { mva.instance_of?(TrueClass) || mva.instance_of?(FalseClass) }
+      raise ArgumentError, '"index" argument must be String' unless index.kind_of?(String) or index.kind_of?(Symbol)
+      raise ArgumentError, '"mva" argument must be Boolean'  unless mva.kind_of?(TrueClass) or mva.kind_of?(FalseClass)
       
-      assert { attrs.instance_of? Array }
+      raise ArgumentError, '"attrs" argument must be Array' unless attrs.kind_of?(Array)
       attrs.each do |attr|
-        assert { attr.instance_of? String }
+        raise ArgumentError, '"attrs" argument must be Array of Strings' unless attr.kind_of?(String) or attr.kind_of?(Symbol)
       end
       
-      assert { values.instance_of? Hash }
+      raise ArgumentError, '"values" argument must be Hash' unless values.kind_of?(Hash)
       values.each do |id, entry|
-        assert { id.instance_of? Fixnum }
-        assert { entry.instance_of? Array }
-        assert { entry.length == attrs.length }
+        raise ArgumentError, '"values" argument must be Hash map of Integer to Array' unless id.respond_to?(:integer?) and id.integer?
+        raise ArgumentError, '"values" argument must be Hash map of Integer to Array' unless entry.kind_of?(Array)
+        raise ArgumentError, "\"values\" argument Hash values Array must have #{attrs.length} elements" unless entry.length == attrs.length
         entry.each do |v|
           if mva
-            assert { v.instance_of? Array }
-            v.each { |vv| assert { vv.instance_of? Fixnum } }
+            raise ArgumentError, '"values" argument must be Hash map of Integer to Array of Arrays' unless v.kind_of?(Array)
+            v.each do |vv|
+              raise ArgumentError, '"values" argument must be Hash map of Integer to Array of Arrays of Integers' unless vv.respond_to?(:integer?) and vv.integer?
+            end
           else
-            assert { v.instance_of? Fixnum }
+            raise ArgumentError, '"values" argument must be Hash map of Integer to Array of Integers' unless v.respond_to?(:integer?) and v.integer?
           end
         end
       end
@@ -1028,7 +1325,7 @@ module Sphinx
         end
       end
       
-      response = PerformRequest(:update, request)
+      response = perform_request(:update, request)
       
       # parse response
       begin
@@ -1041,35 +1338,57 @@ module Sphinx
     
     # persistent connections
     
+    # Opens persistent connection to the server.
+    #
     def Open
-      unless @socket === false
-        @error = 'already connected'
+      if @servers.size > 1
+        @error = 'too many servers. persistent socket allowed only for a single server.'
         return false
       end
       
+      if @servers.first.persistent?
+        @error = 'already connected'
+        return false;
+      end
+      
       request = Request.new
       request.put_int(1)
-      @socket = PerformRequest(:persist, request, nil, true)
+
+      perform_request(:persist, request, nil) do |server, socket|
+        server.make_persistent!(socket)
+      end
 
       true
     end
     
+    # Closes previously opened persistent connection.
+    #
     def Close
-      if @socket === false
+      if @servers.size > 1
+        @error = 'too many servers. persistent socket allowed only for a single server.'
+        return false
+      end
+      
+      unless @servers.first.persistent?
         @error = 'not connected'
         return false;
       end
       
-      @socket.close
-      @socket = false
-      
-      true
+      @servers.first.close_persistent!
     end
     
+    # Queries searchd status, and returns an array of status variable name
+    # and value pairs.
+    #
+    # Usage example:
+    #
+    #   status = sphinx.Status
+    #   puts status.map { |key, value| "#{key.rjust(20)}: #{value}" }
+    #
     def Status
       request = Request.new
       request.put_int(1)
-      response = PerformRequest(:status, request)
+      response = perform_request(:status, request)
 
       # parse response
       begin
@@ -1092,7 +1411,7 @@ module Sphinx
     
     def FlushAttrs
       request = Request.new
-      response = PerformRequest(:flushattrs, request)
+      response = perform_request(:flushattrs, request)
 
       # parse response
       begin
@@ -1103,74 +1422,76 @@ module Sphinx
     end
   
     protected
-    
-      # Connect to searchd server.
-      def Connect
-        return @socket unless @socket === false
-        
-        begin
-          if @path
-            sock = UNIXSocket.new(@path)
-          else
-            sock = TCPSocket.new(@host, @port)
-          end
-        rescue => e
-          location = @path || "#{@host}:#{@port}"
-          @error = "connection to #{location} failed ("
-          if e.kind_of?(SystemCallError)
-            @error << "errno=#{e.class::Errno}, "
-          end
-          @error << "msg=#{e.message})"
-          @connerror = true
-          raise SphinxConnectError, @error
-        end
+      
+      # Connect, send query, get response.
+      #
+      # Use this method to communicate with Sphinx server. It ensures connection
+      # will be instantiated properly, all headers will be generated properly, etc.
+      #
+      # Parameters:
+      # * +command+ -- searchd command to perform (<tt>:search</tt>, <tt>:excerpt</tt>,
+      #   <tt>:update</tt>, <tt>:keywords</tt>, <tt>:persist</tt>, <tt>:status</tt>,
+      #   <tt>:query</tt>, <tt>:flushattrs</tt>. See <tt>SEARCHD_COMMAND_*</tt> for details).
+      # * +request+ -- an instance of <tt>Sphinx::Request</tt> class. Contains request body.
+      # * +additional+ -- additional integer data to be placed between header and body.
+      # * +block+ -- if given, response will not be parsed, plain socket will be
+      #   passed instead. this is special mode used for persistent connections,
+      #   do not use for other tasks.
+      #
+      def perform_request(command, request, additional = nil, &block)
+        with_server do |server|
+          cmd = command.to_s.upcase
+          command_id = Sphinx::Client.const_get("SEARCHD_COMMAND_#{cmd}")
+          command_ver = Sphinx::Client.const_get("VER_COMMAND_#{cmd}")
 
-        # send my version
-        # this is a subtle part. we must do it before (!) reading back from searchd.
-        # because otherwise under some conditions (reported on FreeBSD for instance)
-        # TCP stack could throttle write-write-read pattern because of Nagle.
-        sock.send([1].pack('N'), 0)
-        
-        v = sock.recv(4).unpack('N*').first
-        if v < 1
-          sock.close
-          @error = "expected searchd protocol version 1+, got version '#{v}'"
-          raise SphinxConnectError, @error
+          with_socket(server) do |socket|
+            len = request.to_s.length + (additional.nil? ? 0 : 4)
+            header = [command_id, command_ver, len].pack('nnN')
+            header << [additional].pack('N') unless additional.nil?
+
+            socket.write(header + request.to_s)
+
+            if block_given?
+              yield server, socket
+            else
+              parse_response(socket, command_ver)
+            end
+          end
         end
-        
-        sock
       end
-      
-      # Get and check response packet from searchd server.
-      def GetResponse(sock, client_version)
+
+      # This is internal method which gets and parses response packet from
+      # searchd server.
+      #
+      # There are several exceptions which could be thrown in this method:
+      #
+      # * various network errors -- should be handled by caller (see +with_socket+).
+      # * +SphinxResponseError+ -- incomplete reply from searchd.
+      # * +SphinxInternalError+ -- searchd error.
+      # * +SphinxTemporaryError+ -- temporary searchd error.
+      # * +SphinxUnknownError+ -- unknows searchd error.
+      #
+      # Method returns an instance of <tt>Sphinx::Response</tt> class, which
+      # could be used for context-based parsing of reply from the server.
+      #
+      def parse_response(socket, client_version)
         response = ''
-        len = 0
+        status = ver = len = 0
         
-        header = sock.recv(8)
+        # Read server reply from server. All exceptions are handled by +with_socket+.
+        header = socket.read(8)
         if header.length == 8
           status, ver, len = header.unpack('n2N')
-          left = len.to_i
-          while left > 0 do
-            begin
-              chunk = sock.recv(left)
-              if chunk
-                response << chunk
-                left -= chunk.length
-              end
-            rescue EOFError
-              break
-            end
-          end
+          response = socket.read(len) if len > 0
         end
-        sock.close if @socket === false
     
         # check response
         read = response.length
         if response.empty? or read != len.to_i
-          @error = len \
+          error = len > 0 \
             ? "failed to read searchd response (status=#{status}, ver=#{ver}, len=#{len}, read=#{read})" \
             : 'received zero-sized searchd response'
-          raise SphinxResponseError, @error
+          raise SphinxResponseError, error
         end
         
         # check status
@@ -1181,18 +1502,18 @@ module Sphinx
         end
 
         if status == SEARCHD_ERROR
-          @error = 'searchd error: ' + response[4, response.length - 4]
-          raise SphinxInternalError, @error
+          error = 'searchd error: ' + response[4, response.length - 4]
+          raise SphinxInternalError, error
         end
     
         if status == SEARCHD_RETRY
-          @error = 'temporary searchd error: ' + response[4, response.length - 4]
-          raise SphinxTemporaryError, @error
+          error = 'temporary searchd error: ' + response[4, response.length - 4]
+          raise SphinxTemporaryError, error
         end
     
         unless status == SEARCHD_OK
-          @error = "unknown status code: '#{status}'"
-          raise SphinxUnknownError, @error
+          error = "unknown status code: '#{status}'"
+          raise SphinxUnknownError, error
         end
         
         # check version
@@ -1201,30 +1522,111 @@ module Sphinx
             "v.#{client_version >> 8}.#{client_version & 0xff}, some options might not work"
         end
         
-        return response
+        Response.new(response)
       end
       
-      # Connect, send query, get response.
-      def PerformRequest(command, request, additional = nil, skip_response = false)
-        cmd = command.to_s.upcase
-        command_id = Sphinx::Client.const_get('SEARCHD_COMMAND_' + cmd)
-        command_ver = Sphinx::Client.const_get('VER_COMMAND_' + cmd)
-        
-        sock = self.Connect
-        len = request.to_s.length + (additional != nil ? 4 : 0)
-        header = [command_id, command_ver, len].pack('nnN')
-        header << [additional].pack('N') if additional != nil
-        sock.send(header + request.to_s, 0)
-        
-        return sock if skip_response
-        response = self.GetResponse(sock, command_ver)
-        return Response.new(response)
+      # This is internal method which selects next server (round-robin)
+      # and yields it to the block passed.
+      #
+      # In case of connection error, it will try next server several times
+      # (see +SetConnectionTimeout+ method details). If all servers are down,
+      # it will set +error+ attribute value with the last exception message,
+      # and <tt>connection_timeout?</tt> method will return true. Also,
+      # +SphinxConnectErorr+ exception will be raised.
+      #
+      def with_server
+        attempts = @retries
+        begin
+          # Get the next server
+          @lastserver = (@lastserver + 1) % @servers.size
+          server = @servers[@lastserver]
+          yield server
+        rescue SphinxConnectError => e
+          # Connection error! Do we need to try it again?
+          attempts -= 1
+          retry if attempts > 0
+
+          # Re-raise original exception
+          @error = e.message
+          @connerror = true
+          raise
+        end
       end
       
-      # :stopdoc:
-      def assert
-        raise 'Assertion failed!' unless yield if $DEBUG
+      # This is internal method which retrieves socket for a given server,
+      # initiates Sphinx session, and yields this socket to a block passed.
+      #
+      # In case of any problems with session initiation, +SphinxConnectError+
+      # will be raised, because this is part of connection establishing. See
+      # +with_server+ method details to get more infromation about how this
+      # exception is handled.
+      #
+      # Socket retrieving routine is wrapped in a block with it's own
+      # timeout value (see +SetConnectTimeout+). This is done in
+      # <tt>Server#get_socket</tt> method, so check it for details.
+      #
+      # Request execution is wrapped with block with another timeout
+      # (see +SetRequestTimeout+). This ensures no Sphinx request will
+      # take unreasonable time.
+      #
+      # In case of any Sphinx error (incomplete reply, internal or temporary
+      # error), connection to the server will be re-established, and request
+      # will be retried (see +SetRequestTimeout+). Of course, if connection
+      # could not be established, next server will be selected (see explanation
+      # above).
+      #
+      def with_socket(server)
+        attempts = @reqretries
+        socket = nil
+
+        begin
+          s = server.get_socket do |sock|
+            # Remember socket to close it in case of emergency
+            socket = sock
+
+            # send my version
+            # this is a subtle part. we must do it before (!) reading back from searchd.
+            # because otherwise under some conditions (reported on FreeBSD for instance)
+            # TCP stack could throttle write-write-read pattern because of Nagle.
+            sock.write([1].pack('N'))
+            v = sock.read(4).unpack('N*').first
+
+            # Ouch, invalid protocol!
+            if v < 1
+              raise SphinxConnectError, "expected searchd protocol version 1+, got version '#{v}'"
+            end
+          end
+
+          Sphinx::safe_execute(@reqtimeout) do
+            yield s
+          end
+        rescue SocketError, SystemCallError, IOError, ::Errno::EPIPE => e
+          # Ouch, communication problem, will be treated as a connection problem.
+          raise SphinxConnectError, "failed to read searchd response (msg=#{e.message})"
+        rescue SphinxResponseError, SphinxInternalError, SphinxTemporaryError, SphinxUnknownError, ::Timeout::Error, EOFError => e
+          # EOFError should not occur in ideal world, because we compare response length
+          # with a value passed by Sphinx. But we want to ensure that client will not
+          # fail with unexpected error when Sphinx implementation has bugs, aren't we?
+          if e.kind_of?(EOFError) or e.kind_of?(::Timeout::Error)
+            new_e = SphinxResponseError.new("failed to read searchd response (msg=#{e.message})")
+            new_e.set_backtrace(e.backtrace)
+            e = new_e
+          end
+        
+          # Close previously opened socket (in case of it has been really opened)
+          server.free_socket(socket)
+
+          # Request error! Do we need to try it again?
+          attempts -= 1
+          retry if attempts > 0
+        
+          # Re-raise original exception
+          @error = e.message
+          raise e
+        ensure
+          # Close previously opened socket on any other error
+          server.free_socket(socket)
+        end
       end
-      # :startdoc:
   end
 end