sphinx 0.9.10.2091 → 0.9.10.2094

data/README.rdoc

@@ -158,6 +158,27 @@ It means that you can chain filtering methods:
               set_id_range(10, 1000).
               query('test')
 
+There is a handful ability to set query parameters directly in <tt>query</tt>
+call. If block does not accept any parameters, it will be eval'ed inside
+Sphinx::Client instance:
+
+  results = Sphinx::Client.new.query('test') do
+    match_mode :any
+    ranking_mode :bm25
+    id_range 10, 1000
+  end
+
+As you can see, in this case you can omit the <tt>set_</tt> prefix for
+this methods. If block accepts a parameter, sphinx instance will be
+passed into the block. In this case you should you full method names
+including the <tt>set_</tt> prefix:
+
+  results = Sphinx::Client.new.query('test') do |sphinx|
+    sphinx.set_match_mode :any
+    sphinx.set_ranking_mode :bm25
+    sphinx.set_id_range 10, 1000
+  end
+
 == Example
 
 This simple example illustrates base connection establishing,

data/VERSION.yml

@@ -2,4 +2,4 @@
 :major: 0
 :minor: 9
 :patch: 10
-:build: 2091
+:build: 2094

data/lib/sphinx.rb

@@ -11,10 +11,15 @@
 # You can freely distribute/modify this library.
 #
 module Sphinx
+  VERSION = begin
+    config = YAML.load(File.read(File.dirname(__FILE__) + '/../VERSION.yml'))
+    "#{config[:major]}.#{config[:minor]}.#{config[:patch]}.#{config[:build]}"
+  end
 end
 
-require 'socket'
 require 'net/protocol'
+require 'socket'
+require 'zlib'
 
 require File.dirname(__FILE__) + '/sphinx/request'
 require File.dirname(__FILE__) + '/sphinx/response'

data/lib/sphinx/client.rb

@@ -120,6 +120,9 @@ module Sphinx
     # Number of request retries.
     # @private
     attr_reader :reqretries
+    # Log debug/info/warn/error to the given Logger, defaults to nil.
+    # @private
+    attr_reader :logger
 
     #=================================================================
     # Known match modes
@@ -229,7 +232,7 @@ module Sphinx
     SPH_GROUPBY_ATTRPAIR = 5
 
     # Constructs the <tt>Sphinx::Client</tt> object and sets options to their default values.
-    def initialize
+    def initialize(logger = nil)
       # 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)
@@ -271,7 +274,41 @@ module Sphinx
       # per-client-object settings
       # searchd servers list
       @servers       = [Sphinx::Server.new(self, 'localhost', 9312, false)].freeze
-      @lastserver    = -1
+      @logger        = logger
+
+      logger.info { "[sphinx] version: #{VERSION}, #{@servers.inspect}" } if logger
+    end
+
+    # Returns a string representation of the sphinx client object.
+    #
+    def inspect
+      params = {
+        :error => @error,
+        :warning => @warning,
+        :connect_error => @connerror,
+        :servers => @servers,
+        :connect_timeout => { :timeout => @timeout, :retries => @retries },
+        :request_timeout => { :timeout => @reqtimeout, :retries => @reqretries },
+        :retries => { :count => @retrycount, :delay => @retrydelay },
+        :limits => { :offset => @offset, :limit => @limit, :max => @maxmatches, :cutoff => @cutoff },
+        :max_query_time => @maxquerytime,
+        :overrides => @overrides,
+        :select => @select,
+        :match_mode => @mode,
+        :ranking_mode => @ranker,
+        :sort_mode => { :mode => @sort, :sortby => @sortby },
+        :weights => @weights,
+        :field_weights => @fieldweights,
+        :index_weights => @indexweights,
+        :id_range => { :min => @min_id, :max => @max_id },
+        :filters => @filters,
+        :geo_anchor => @anchor,
+        :group_by => { :attribute => @groupby, :func => @groupfunc, :sort => @groupsort },
+        :group_distinct => @groupdistinct
+      }
+
+      "<Sphinx::Client: %d servers, params: %s>" %
+        [@servers.length, params.inspect]
     end
 
     #=================================================================
@@ -375,12 +412,13 @@ module Sphinx
       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?
+        raise ArgumentError, '"port" argument must be Integer' unless port.kind_of?(Integer)
       end
 
       host = port = nil unless path.nil?
 
       @servers = [Sphinx::Server.new(self, host, port, path)].freeze
+      logger.info { "[sphinx] servers now: #{@servers.inspect}" } if logger
       self
     end
     alias :SetServer :set_server
@@ -431,13 +469,14 @@ module Sphinx
         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?
+          raise ArgumentError, '"port" argument must be Integer' unless port.kind_of?(Integer)
         end
 
         host = port = nil unless path.nil?
 
         Sphinx::Server.new(self, host, port, path)
       end.freeze
+      logger.info { "[sphinx] servers now: #{@servers.inspect}" } if logger
       self
     end
     alias :SetServers :set_servers
@@ -470,8 +509,8 @@ module Sphinx
     # @see #set_request_timeout
     #
     def set_connect_timeout(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, '"timeout" argument must be Integer'        unless timeout.kind_of?(Integer)
+      raise ArgumentError, '"retries" argument must be Integer'        unless retries.kind_of?(Integer)
       raise ArgumentError, '"retries" argument must be greater than 0' unless retries > 0
 
       @timeout = timeout
@@ -508,8 +547,8 @@ module Sphinx
     # @see #set_connect_timeout
     #
     def set_request_timeout(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, '"timeout" argument must be Integer'        unless timeout.kind_of?(Integer)
+      raise ArgumentError, '"retries" argument must be Integer'        unless retries.kind_of?(Integer)
       raise ArgumentError, '"retries" argument must be greater than 0' unless retries > 0
 
       @reqtimeout = timeout
@@ -539,8 +578,8 @@ module Sphinx
     # @see #set_request_timeout
     #
     def set_retries(count, delay = 0)
-      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?
+      raise ArgumentError, '"count" argument must be Integer' unless count.kind_of?(Integer)
+      raise ArgumentError, '"delay" argument must be Integer' unless delay.kind_of?(Integer)
 
       @retrycount = count
       @retrydelay = delay
@@ -596,10 +635,10 @@ module Sphinx
     # @raise [ArgumentError] Occurred when parameters are invalid.
     #
     def set_limits(offset, limit, max = 0, cutoff = 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 must be Integer' unless offset.kind_of?(Integer)
+      raise ArgumentError, '"limit" argument must be Integer'  unless limit.kind_of?(Integer)
+      raise ArgumentError, '"max" argument must be Integer'    unless max.kind_of?(Integer)
+      raise ArgumentError, '"cutoff" argument must be Integer' unless cutoff.kind_of?(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
@@ -632,7 +671,7 @@ module Sphinx
     # @raise [ArgumentError] Occurred when parameters are invalid.
     #
     def set_max_query_time(max)
-      raise ArgumentError, '"max" argument must be Integer' unless max.respond_to?(:integer?) and max.integer?
+      raise ArgumentError, '"max" argument must be Integer' unless max.kind_of?(Integer)
       raise ArgumentError, '"max" argument should be greater or equal to zero' unless max >= 0
 
       @maxquerytime = max
@@ -691,15 +730,15 @@ module Sphinx
       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?
+        raise ArgumentError, '"values" argument must be Hash map of Integer to Integer or Time' unless id.kind_of?(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)
+            raise ArgumentError, '"values" argument must be Hash map of Integer to Numeric' unless value.kind_of?(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?)
+            raise ArgumentError, '"values" argument must be Hash map of Integer to Numeric' unless value.kind_of?(Numeric)
           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?
+            raise ArgumentError, '"values" argument must be Hash map of Integer to Integer' unless value.kind_of?(Integer)
         end
       end
 
@@ -900,7 +939,7 @@ module Sphinx
     def set_weights(weights)
       raise ArgumentError, '"weights" argument must be Array' unless weights.kind_of?(Array)
       weights.each do |weight|
-        raise ArgumentError, '"weights" argument must be Array of integers' unless weight.respond_to?(:integer?) and weight.integer?
+        raise ArgumentError, '"weights" argument must be Array of integers' unless weight.kind_of?(Integer)
       end
 
       @weights = weights
@@ -945,7 +984,7 @@ module Sphinx
     def set_field_weights(weights)
       raise ArgumentError, '"weights" argument must be Hash' unless weights.kind_of?(Hash)
       weights.each do |name, weight|
-        unless (name.kind_of?(String) or name.kind_of?(Symbol)) and (weight.respond_to?(:integer?) and weight.integer?)
+        unless (name.kind_of?(String) or name.kind_of?(Symbol)) and weight.kind_of?(Integer)
           raise ArgumentError, '"weights" argument must be Hash map of strings to integers'
         end
       end
@@ -991,7 +1030,7 @@ module Sphinx
     def set_index_weights(weights)
       raise ArgumentError, '"weights" argument must be Hash' unless weights.kind_of?(Hash)
       weights.each do |index, weight|
-        unless (index.kind_of?(String) or index.kind_of?(Symbol)) and (weight.respond_to?(:integer?) and weight.integer?)
+        unless (index.kind_of?(String) or index.kind_of?(Symbol)) and weight.kind_of?(Integer)
           raise ArgumentError, '"weights" argument must be Hash map of strings to integers'
         end
       end
@@ -1000,7 +1039,7 @@ module Sphinx
       self
     end
     alias :SetIndexWeights :set_index_weights
-    
+
     #=================================================================
     # Result set filtering settings
     #=================================================================
@@ -1024,8 +1063,8 @@ module Sphinx
     # @see http://www.sphinxsearch.com/docs/current.html#api-func-setidrange Section 6.4.1, "SetIDRange"
     #
     def set_id_range(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, '"min" argument must be Integer' unless min.kind_of?(Integer)
+      raise ArgumentError, '"max" argument must be Integer' unless max.kind_of?(Integer)
       raise ArgumentError, '"max" argument greater or equal to "min"' unless min <= max
 
       @min_id = min
@@ -1070,7 +1109,7 @@ module Sphinx
       raise ArgumentError, '"exclude" argument must be Boolean'            unless exclude.kind_of?(TrueClass) or exclude.kind_of?(FalseClass)
 
       values.each do |value|
-        raise ArgumentError, '"values" argument must be Array of Integer' unless value.respond_to?(:integer?) and value.integer?
+        raise ArgumentError, '"values" argument must be Array of Integer' unless value.kind_of?(Integer)
       end
 
       @filters << { 'type' => SPH_FILTER_VALUES, 'attr' => attribute.to_s, 'exclude' => exclude, 'values' => values }
@@ -1112,8 +1151,8 @@ module Sphinx
     #
     def set_filter_range(attribute, min, max, exclude = false)
       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, '"min" argument must be Integer'                unless min.kind_of?(Integer)
+      raise ArgumentError, '"max" argument must be Integer'                unless max.kind_of?(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)
 
@@ -1137,8 +1176,8 @@ module Sphinx
     # if +exclude+ is true).
     #
     # @param [String, Symbol] attribute an attribute name to filter by.
-    # @param [Integer, Float] min min value of the given attribute.
-    # @param [Integer, Float] max max value of the given attribute.
+    # @param [Numeric] min min value of the given attribute.
+    # @param [Numeric] max max value of the given attribute.
     # @param [Boolean] exclude indicating whether documents with given attribute
     #   matching specified boundaries should be excluded from search results.
     # @return [Sphinx::Client] self.
@@ -1155,8 +1194,8 @@ module Sphinx
     #
     def set_filter_float_range(attribute, min, max, exclude = false)
       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, '"min" argument must be Numeric'                unless min.kind_of?(Numeric)
+      raise ArgumentError, '"max" argument must be Numeric'                unless max.kind_of?(Numeric)
       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)
 
@@ -1185,8 +1224,8 @@ module Sphinx
     #
     # @param [String, Symbol] attrlat a name of latitude attribute.
     # @param [String, Symbol] attrlong a name of longitude attribute.
-    # @param [Integer, Float] lat an anchor point latitude, in radians.
-    # @param [Integer, Float] long an anchor point longitude, in radians.
+    # @param [Numeric] lat an anchor point latitude, in radians.
+    # @param [Numeric] long an anchor point longitude, in radians.
     # @return [Sphinx::Client] self.
     #
     # @example
@@ -1199,14 +1238,14 @@ module Sphinx
     def set_geo_anchor(attrlat, attrlong, lat, long)
       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?)
+      raise ArgumentError, '"lat" argument must be Numeric'               unless lat.kind_of?(Numeric)
+      raise ArgumentError, '"long" argument must be Numeric'              unless long.kind_of?(Numeric)
 
       @anchor = { 'attrlat' => attrlat.to_s, 'attrlong' => attrlong.to_s, 'lat' => lat.to_f, 'long' => long.to_f }
       self
     end
     alias :SetGeoAnchor :set_geo_anchor
-    
+
     #=================================================================
     # GROUP BY settings
     #=================================================================
@@ -1473,18 +1512,48 @@ module Sphinx
     # @param [String] index an index name (or names).
     # @param [String] comment a comment to be sent to the query log.
     # @return [Hash, false] result set described above or +false+ on error.
+    # @yield [Client] yields just before query performing. Useful to set
+    #   filters or sortings. When block does not accept any parameters, it
+    #   will be eval'ed inside {Client} instance itself. In this case you
+    #   can omit +set_+ prefix for configuration methods.
+    # @yieldparam [Client] sphinx self.
     #
-    # @example
+    # @example Regular query with previously set filters
     #   sphinx.query('some search text', '*', 'search page')
+    # @example Query with block
+    #   sphinx.query('test') do |sphinx|
+    #     sphinx.set_match_mode :all
+    #     sphinx.set_id_range 10, 100
+    #   end
+    # @example Query with instant filters configuring
+    #   sphinx.query('test') do
+    #     match_mode :all
+    #     id_range 10, 100
+    #   end
     #
     # @see http://www.sphinxsearch.com/docs/current.html#api-func-query Section 6.6.1, "Query"
     # @see #add_query
     # @see #run_queries
     #
-    def query(query, index = '*', comment = '')
+    def query(query, index = '*', comment = '', &block)
       @reqs = []
 
-      self.add_query(query, index, comment)
+      if block_given?
+        if block.arity > 0
+          yield self
+        else
+          begin
+            @inside_eval = true
+            instance_eval(&block)
+          ensure
+            @inside_eval = false
+          end
+        end
+      end
+
+      logger.debug { "[sphinx] query('#{query}', '#{index}', '#{comment}'), #{self.inspect}" } if logger
+
+      self.add_query(query, index, comment, false)
       results = self.run_queries
 
       # probably network error; error message should be already filled
@@ -1512,12 +1581,12 @@ module Sphinx
     # cases. They do not result in any additional overheads compared
     # to simple queries. Thus, if you run several different queries
     # from your web page, you should always consider using multi-queries.
-    # 
+    #
     # For instance, running the same full-text query but with different
     # sorting or group-by settings will enable searchd to perform
     # expensive full-text search and ranking operation only once, but
     # compute multiple group-by results from its output.
-    # 
+    #
     # This can be a big saver when you need to display not just plain
     # search results but also some per-category counts, such as the
     # amount of products grouped by vendor. Without multi-query, you
@@ -1526,21 +1595,21 @@ module Sphinx
     # sets differently. With multi-query, you simply pass all these
     # queries in a single batch and Sphinx optimizes the redundant
     # full-text search internally.
-    # 
+    #
     # {#add_query} internally saves full current settings state along
     # with the query, and you can safely change them afterwards for
     # subsequent {#add_query} calls. Already added queries will not
     # be affected; there's actually no way to change them at all.
     # Here's an example:
-    # 
+    #
     #   sphinx.set_sort_mode(:relevance)
     #   sphinx.add_query("hello world", "documents")
-    # 
+    #
     #   sphinx.set_sort_mode(:attr_desc, :price)
     #   sphinx.add_query("ipod", "products")
     #
     #   sphinx.add_query("harry potter", "books")
-    # 
+    #
     #   results = sphinx.run_queries
     #
     # With the code above, 1st query will search for "hello world"
@@ -1550,18 +1619,18 @@ module Sphinx
     # "books" index while still sorting by price. Note that 2nd
     # {#set_sort_mode} call does not affect the first query (because
     # it's already added) but affects both other subsequent queries.
-    # 
+    #
     # Additionally, any filters set up before an {#add_query} will
     # fall through to subsequent queries. So, if {#set_filter} is
     # called before the first query, the same filter will be in
     # place for the second (and subsequent) queries batched through
     # {#add_query} unless you call {#reset_filters} first. Alternatively,
     # you can add additional filters as well.
-    # 
+    #
     # This would also be true for grouping options and sorting options;
     # no current sorting, filtering, and grouping settings are affected
     # by this call; so subsequent queries will reuse current query settings.
-    # 
+    #
     # {#add_query} returns an index into an array of results that will
     # be returned from {#run_queries} call. It is simply a sequentially
     # increasing 0-based integer, ie. first call will return 0, second
@@ -1571,6 +1640,7 @@ module Sphinx
     # @param [String] query a query string.
     # @param [String] index an index name (or names).
     # @param [String] comment a comment to be sent to the query log.
+    # @param [Boolean] log indicating whether this call should be logged.
     # @return [Integer] an index into an array of results that will
     #   be returned from {#run_queries} call.
     #
@@ -1581,7 +1651,8 @@ module Sphinx
     # @see #query
     # @see #run_queries
     #
-    def add_query(query, index = '*', comment = '')
+    def add_query(query, index = '*', comment = '', log = true)
+      logger.debug { "[sphinx] add_query('#{query}', '#{index}', '#{comment}'), #{self.inspect}" } if log and logger
       # build request
 
       # mode and limits
@@ -1716,6 +1787,7 @@ module Sphinx
     # @see #add_query
     #
     def run_queries
+      logger.debug { "[sphinx] run_queries(#{@reqs.length} queries)" } if logger
       if @reqs.empty?
         @error = 'No queries defined, issue add_query() first'
         return false
@@ -1767,7 +1839,7 @@ module Sphinx
           end
 
           # This is a single result put in the result['matches'] array
-          match = { 'id' => doc, 'weight' => weight } 
+          match = { 'id' => doc, 'weight' => weight }
           match['attrs'] = attrs_names_in_order.inject({}) do |hash, name|
             hash[name] = case attrs[name]
               when SPH_ATTR_BIGINT
@@ -1806,7 +1878,7 @@ module Sphinx
       end
     end
     alias :RunQueries :run_queries
-    
+
     #=================================================================
     # Additional functionality
     #=================================================================
@@ -1983,18 +2055,18 @@ module Sphinx
     # Instantly updates given attribute values in given documents.
     # Returns number of actually updated documents (0 or more) on
     # success, or -1 on failure.
-    # 
+    #
     # +index+ is a name of the index (or indexes) to be updated.
     # +attrs+ is a plain array with string attribute names, listing
     # attributes that are updated. +values+ is a Hash where key is
     # document ID, and value is a plain array of new attribute values.
-    # 
+    #
     # +index+ can be either a single index name or a list, like in
     # {#query}. Unlike {#query}, wildcard is not allowed and all the
     # indexes to update must be specified explicitly. The list of
     # indexes can include distributed index names. Updates on
     # distributed indexes will be pushed to all agents.
-    # 
+    #
     # The updates only work with docinfo=extern storage strategy.
     # They are very fast because they're working fully in RAM, but
     # they can also be made persistent: updates are saved on disk
@@ -2009,7 +2081,7 @@ module Sphinx
     # stock to 5; for document 1002, the new price will be 37 and the
     # new amount will be 11; etc. The third one updates document 1
     # in index "test2", setting MVA attribute "group_id" to [456, 789].
-    # 
+    #
     # @example
     #   sphinx.update_attributes("test1", ["group_id"], { 1 => [456] });
     #   sphinx.update_attributes("products", ["price", "amount_in_stock"],
@@ -2040,17 +2112,17 @@ module Sphinx
 
       raise ArgumentError, '"values" argument must be Hash' unless values.kind_of?(Hash)
       values.each do |id, entry|
-        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 id.kind_of?(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
             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?
+              raise ArgumentError, '"values" argument must be Hash map of Integer to Array of Arrays of Integers' unless vv.kind_of?(Integer)
             end
           else
-            raise ArgumentError, '"values" argument must be Hash map of Integer to Array of Integers' unless v.respond_to?(:integer?) and v.integer?
+            raise ArgumentError, '"values" argument must be Hash map of Integer to Array of Integers' unless v.kind_of?(Integer)
           end
         end
       end
@@ -2085,22 +2157,52 @@ module Sphinx
     # Queries searchd status, and returns an array of status variable name
     # and value pairs.
     #
-    # @return [Array<Array>] a table containing searchd status information.
+    # @return [Array<Array>, Array<Hash>] a table containing searchd status information.
+    #   If there are more than one server configured ({#set_servers}), an
+    #   +Array+ of +Hash+es will be returned, one for each server. Hash will
+    #   contain <tt>:server</tt> element with string name of server (<tt>host:port</tt>)
+    #   and <tt>:status</tt> table just like one for a single server. In case of
+    #   any error, it will be stored in the <tt>:error</tt> key.
     #
-    # @example
+    # @example Single server
     #   status = sphinx.status
     #   puts status.map { |key, value| "#{key.rjust(20)}: #{value}" }
     #
+    # @example Multiple servers
+    #   sphinx.set_servers([
+    #     { :host => 'localhost' },
+    #     { :host => 'browse02.local' }
+    #   ])
+    #   sphinx.status.each do |report|
+    #     puts "=== #{report[:server]}"
+    #     if report[:error]
+    #       puts "Error: #{report[:error]}"
+    #     else
+    #       puts report[:status].map { |key, value| "#{key.rjust(20)}: #{value}" }
+    #     end
+    #   end
+    #
     def status
       request = Request.new
       request.put_int(1)
-      response = perform_request(:status, request)
 
       # parse response
-      rows, cols = response.get_ints(2)
-      (0...rows).map do
-        (0...cols).map { response.get_string }
+      results = @servers.map do |server|
+        begin
+          response = perform_request(:status, request, nil, server)
+          rows, cols = response.get_ints(2)
+          status = (0...rows).map do
+            (0...cols).map { response.get_string }
+          end
+          { :server => server.to_s, :status => status }
+        rescue SphinxError
+          # Re-raise error when a single server configured
+          raise if @servers.size == 1
+          { :server => server.to_s, :error => self.last_error}
+        end
       end
+
+      @servers.size > 1 ? results : results.first[:status]
     end
     alias :Status :status
 
@@ -2212,7 +2314,11 @@ module Sphinx
       #   <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).
       # @param [Sphinx::Request] request contains request body.
-      # @param [nil, Integer] additional additional integer data to be placed between header and body.
+      # @param [Integer] additional additional integer data to be placed between header and body.
+      # @param [Sphinx::Server] server where perform request on. This is special
+      #   parameter for internal usage. If specified, request will be performed
+      #   on specified server, and it will try to establish connection to this
+      #   server only once.
       #
       # @yield if block given, response will not be parsed, plain socket
       #   will be yielded instead. This is special mode used for
@@ -2223,8 +2329,24 @@ module Sphinx
       #
       # @see #parse_response
       #
-      def perform_request(command, request, additional = nil)
-        with_server do |server|
+      def perform_request(command, request, additional = nil, server = nil)
+        if server
+          attempts = 1
+        else
+          server = case request
+            when String
+              Zlib.crc32(request)
+            when Request
+              request.crc32
+            else
+              raise ArgumentError, "request argument must be String or Sphinx::Request"
+          end
+          attempts = nil
+        end
+
+        with_server(server, attempts) do |server|
+          logger.info { "[sphinx] #{command} on server #{server}" } if logger
+
           cmd = command.to_s.upcase
           command_id = Sphinx::Client.const_get("SEARCHD_COMMAND_#{cmd}")
           command_ver = Sphinx::Client.const_get("VER_COMMAND_#{cmd}")
@@ -2325,22 +2447,56 @@ module Sphinx
       # method will return true. Also, {SphinxConnectError} exception
       # will be raised.
       #
+      # @overload with_server(server_index)
+      #   Get the server based on some seed value (usually CRC32 of
+      #   request. In this case initial server will be choosed using
+      #   this seed value, in case of connetion failure next server
+      #   in servers list will be used).
+      #   @param [Integer] server_index server index, must be any
+      #     integer value (not necessarily less than number of servers.)
+      #   @param [Integer] attempts how many retries to perform. Use
+      #     +nil+ to perform retries configured with {#set_connect_timeout}.
+      # @overload with_server(server)
+      #   Get the server specified as a parameter. If specified, request
+      #   will be performed on specified server, and it will try to
+      #   establish connection to this server only once.
+      #   @param [Server] server server to perform request on.
+      #   @param [Integer] attempts how many retries to perform. Use
+      #     +nil+ to perform retries configured with {#set_connect_timeout}.
+      #
       # @yield a block which performs request on a given server.
       # @yieldparam [Sphinx::Server] server contains information
       #   about the server to perform request on.
       # @raise [SphinxConnectError] on any connection error.
       #
-      def with_server
-        attempts = @retries
+      def with_server(server = nil, attempts = nil)
+        case server
+          when Server
+            idx = @servers.index(server) || 0
+            s = server
+          when Integer
+            idx = server % @servers.size
+            s = @servers[idx]
+          when NilClass
+            idx = 0
+            s = @servers[idx]
+          else
+            raise ArgumentError, 'server argument must be Integer or Sphinx::Server'
+        end
+        attempts ||= @retries
         begin
-          # Get the next server
-          @lastserver = (@lastserver + 1) % @servers.size
-          server = @servers[@lastserver]
-          yield server
+          yield s
         rescue SphinxConnectError => e
+          logger.warn { "[sphinx] server failed: #{e.class.name}: #{e.message}" } if logger
           # Connection error! Do we need to try it again?
           attempts -= 1
-          retry if attempts > 0
+          if attempts > 0
+            logger.info { "[sphinx] connection to server #{s.inspect} DIED! Retrying operation..." } if logger
+            # Get the next server
+            idx = (idx + 1) % @servers.size
+            s = @servers[idx]
+            retry
+          end
 
           # Re-raise original exception
           @error = e.message
@@ -2407,6 +2563,7 @@ module Sphinx
             yield s
           end
         rescue SocketError, SystemCallError, IOError, ::Errno::EPIPE => e
+          logger.warn { "[sphinx] socket failure: #{e.message}" } if logger
           # 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
@@ -2418,6 +2575,7 @@ module Sphinx
             new_e.set_backtrace(e.backtrace)
             e = new_e
           end
+          logger.warn { "[sphinx] generic failure: #{e.class.name}: #{e.message}" } if logger
 
           # Close previously opened socket (in case of it has been really opened)
           server.free_socket(socket)
@@ -2434,5 +2592,21 @@ module Sphinx
           server.free_socket(socket)
         end
       end
+
+      # Enables ability to skip +set_+ prefix for methods inside {#query} block.
+      #
+      # @example
+      #   sphinx.query('test') do
+      #     match_mode :all
+      #     id_range 10, 100
+      #   end
+      #
+      def method_missing(method_id, *arguments, &block)
+        if @inside_eval and self.respond_to?("set_#{method_id}")
+          self.send("set_#{method_id}", *arguments)
+        else
+          super
+        end
+      end
   end
 end

data/lib/sphinx/request.rb

@@ -2,51 +2,120 @@ module Sphinx
   # Pack ints, floats, strings, and arrays to internal representation
   # needed by Sphinx search engine.
   #
-  # @private
   class Request
-    # Initialize new request.
+    # Initialize new empty request.
+    #
     def initialize
       @request = ''
     end
-    
+
     # Put int(s) to request.
+    #
+    # @param [Integer] ints one or more integers to put to the request.
+    # @return [Request] self.
+    #
+    # @example
+    #   request.put_int 10
+    #   request.put_int 10, 20, 30
+    #   request.put_int *[10, 20, 30]
+    #
     def put_int(*ints)
       ints.each { |i| @request << [i].pack('N') }
+      self
     end
 
     # Put 64-bit int(s) to request.
+    #
+    # @param [Integer] ints one or more 64-bit integers to put to the request.
+    # @return [Request] self.
+    #
+    # @example
+    #   request.put_int64 10
+    #   request.put_int64 10, 20, 30
+    #   request.put_int64 *[10, 20, 30]
+    #
     def put_int64(*ints)
       ints.each { |i| @request << [i].pack('q').reverse }#[i >> 32, i & ((1 << 32) - 1)].pack('NN') }
+      self
     end
 
-    # Put string(s) to request (first length, then the string itself).
+    # Put strings to request.
+    #
+    # @param [String] strings one or more strings to put to the request.
+    # @return [Request] self.
+    #
+    # @example
+    #   request.put_string 'str1'
+    #   request.put_string 'str1', 'str2', 'str3'
+    #   request.put_string *['str1', 'str2', 'str3']
+    #
     def put_string(*strings)
       strings.each { |s| @request << [s.length].pack('N') + s }
+      self
     end
-    
+
     # Put float(s) to request.
+    #
+    # @param [Integer, Float] floats one or more floats to put to the request.
+    # @return [Request] self.
+    #
+    # @example
+    #   request.put_float 10
+    #   request.put_float 10, 20, 30
+    #   request.put_float *[10, 20, 30]
+    #
     def put_float(*floats)
       floats.each do |f|
-        t1 = [f].pack('f') # machine order
+        t1 = [f.to_f].pack('f') # machine order
         t2 = t1.unpack('L*').first # int in machine order
         @request << [t2].pack('N')
       end
+      self
     end
-    
-    # Put array of ints to request (first length, then the array itself)
+
+    # Put array of ints to request.
+    #
+    # @param [Array<Integer>] arr an array of integers to put to the request.
+    # @return [Request] self.
+    #
+    # @example
+    #   request.put_int_array [10]
+    #   request.put_int_array [10, 20, 30]
+    #
     def put_int_array(arr)
       put_int arr.length, *arr
+      self
     end
 
-    # Put array of 64-bit ints to request (first length, then the array itself)
+    # Put array of 64-bit ints to request.
+    #
+    # @param [Array<Integer>] arr an array of integers to put to the request.
+    # @return [Request] self.
+    #
+    # @example
+    #   request.put_int64_array [10]
+    #   request.put_int64_array [10, 20, 30]
+    #
     def put_int64_array(arr)
-      put_int arr.length
+      put_int(arr.length)
       put_int64(*arr)
+      self
     end
-    
-    # Returns the entire message
+
+    # Returns the serialized request.
+    #
+    # @return [String] serialized request.
+    #
     def to_s
       @request
     end
+
+    # Returns CRC32 of the serialized request.
+    #
+    # @return [Integer] CRC32 of the serialized request.
+    #
+    def crc32
+      Zlib.crc32(@request)
+    end
   end
 end

data/lib/sphinx/server.rb

@@ -10,7 +10,7 @@ class Sphinx::Server
 
   # The path to UNIX socket where Sphinx server is running on
   attr_reader :path
-  
+
   # Creates a new instance of +Server+.
   #
   # Parameters:
@@ -24,16 +24,10 @@ class Sphinx::Server
     @host = host
     @port = port
     @path = path
-    
-    @timeout = @sphinx.timeout
-    @retries = @sphinx.retries
-    
-    @reqtimeout = @sphinx.reqtimeout
-    @reqretries = @sphinx.reqretries
-    
+
     @socket = nil
   end
-  
+
   # Gets the opened socket to the server.
   #
   # You can pass a block to make any connection establishing related things,
@@ -51,7 +45,7 @@ class Sphinx::Server
       @socket
     else
       socket = nil
-      Sphinx::safe_execute(@timeout) do
+      Sphinx::safe_execute(@sphinx.timeout) do
         socket = establish_connection
 
         # Do custom initialization
@@ -62,26 +56,25 @@ class Sphinx::Server
   rescue SocketError, SystemCallError, IOError, EOFError, ::Timeout::Error, ::Errno::EPIPE => e
     # Close previously opened socket (in case of it has been really opened)
     free_socket(socket, true)
-    
-    location = @path || "#{@host}:#{@port}"
-    error = "connection to #{location} failed ("
+
+    error = "connection to #{to_s} failed ("
     if e.kind_of?(SystemCallError)
       error << "errno=#{e.class::Errno}, "
     end
     error << "msg=#{e.message})"
     raise Sphinx::SphinxConnectError, error
   end
-  
+
   # Closes previously opened socket.
   #
   # Pass socket retrieved with +get_socket+ method when finished work. It does
   # not close persistent sockets, but if really you need to do it, pass +true+
   # as +force+ parameter value.
-  # 
+  #
   def free_socket(socket, force = false)
     # Socket has not been open
     return false if socket.nil?
-    
+
     # Do we try to close persistent socket?
     if socket == @socket
       # do not close it if not forced
@@ -98,40 +91,49 @@ class Sphinx::Server
       true
     end
   end
-  
+
   # Makes specified socket persistent.
   #
   # Previous persistent socket will be closed as well.
   def make_persistent!(socket)
-    free_socket(@socket)
-    @socket = socket
+    unless socket == @socket
+      close_persistent!
+      @socket = socket
+    end
+    @socket
   end
-  
+
   # Closes persistent socket.
   def close_persistent!
-    if @socket
-      @socket.close unless @socket.closed?
-      @socket = nil
-      true
-    else
-      false
-    end
+    free_socket(@socket, true)
   end
-  
+
   # Gets a value indicating whether server has persistent socket associated.
   def persistent?
     !@socket.nil?
   end
-  
+
+  # Returns a string representation of the sphinx server object.
+  #
+  def to_s
+    @path || "#{@host}:#{@port}"
+  end
+
+  # Returns a string representation of the sphinx server object.
+  #
+  def inspect
+    "<Sphinx::Server: %s%s>" % [to_s, @socket ? '; persistent' : '']
+  end
+
   private
-  
+
     # This is internal method which establishes a connection to a configured server.
     #
     # Method configures various socket options (like TCP_NODELAY), and
     # sets socket timeouts.
     #
     # It does not close socket on any failure, please do it from calling code!
-    # 
+    #
     def establish_connection
       if @path
         sock = UNIXSocket.new(@path)
@@ -141,30 +143,28 @@ class Sphinx::Server
 
       io = Sphinx::BufferedIO.new(sock)
       io.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
-      if @reqtimeout > 0
-        io.read_timeout = @reqtimeout
-    
+      if @sphinx.reqtimeout > 0
+        io.read_timeout = @sphinx.reqtimeout
+
         # This is a part of memcache-client library.
         #
         # Getting reports from several customers, including 37signals,
         # that the non-blocking timeouts in 1.7.5 don't seem to be reliable.
         # It can't hurt to set the underlying socket timeout also, if possible.
-        if timeout
-          secs = Integer(timeout)
-          usecs = Integer((timeout - secs) * 1_000_000)
-          optval = [secs, usecs].pack("l_2")
-          begin
-            io.setsockopt Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, optval
-            io.setsockopt Socket::SOL_SOCKET, Socket::SO_SNDTIMEO, optval
-          rescue Exception => ex
-            # Solaris, for one, does not like/support socket timeouts.
-            @warning = "Unable to use raw socket timeouts: #{ex.class.name}: #{ex.message}"
-          end
+        secs = Integer(@sphinx.reqtimeout)
+        usecs = Integer((@sphinx.reqtimeout - secs) * 1_000_000)
+        optval = [secs, usecs].pack("l_2")
+        begin
+          io.setsockopt Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, optval
+          io.setsockopt Socket::SOL_SOCKET, Socket::SO_SNDTIMEO, optval
+        rescue Exception => ex
+          # Solaris, for one, does not like/support socket timeouts.
+          @sphinx.logger.warn { "[sphinx] Unable to use raw socket timeouts: #{ex.class.name}: #{ex.message}" } if @sphinx.logger
         end
       else
         io.read_timeout = false
       end
-      
+
       io
     end
 end

data/spec/client_spec.rb

@@ -26,35 +26,26 @@ describe Sphinx::Client, 'disconnected' do
         end
       end
 
-      it 'should round-robin servers on each call' do
+      it 'should select server based on index' do
         @sphinx.SetServers(@servers)
         cnt = 0
-        @sphinx.send(:with_server) { |server| cnt += 1; server.should == @sphinx.servers[0] }
+        @sphinx.send(:with_server, 0) { |server| cnt += 1; server.should == @sphinx.servers[0] }
         cnt.should == 1
         cnt = 0
-        @sphinx.send(:with_server) { |server| cnt += 1; server.should == @sphinx.servers[1] }
+        @sphinx.send(:with_server, 1) { |server| cnt += 1; server.should == @sphinx.servers[1] }
         cnt.should == 1
         cnt = 0
-        @sphinx.send(:with_server) { |server| cnt += 1; server.should == @sphinx.servers[0] }
+        @sphinx.send(:with_server, 2) { |server| cnt += 1; server.should == @sphinx.servers[0] }
         cnt.should == 1
       end
 
-      it 'should round-robin servers and raise an exception on error' do
+      it 'should select given server' do
         @sphinx.SetServers(@servers)
         cnt = 0
-        expect {
-          @sphinx.send(:with_server) { |server| cnt += 1; server.should == @sphinx.servers[0]; raise Sphinx::SphinxConnectError }
-        }.to raise_error(Sphinx::SphinxConnectError)
-        cnt.should == 1
-        cnt = 0
-        expect {
-          @sphinx.send(:with_server) { |server| cnt += 1; server.should == @sphinx.servers[1]; raise Sphinx::SphinxConnectError }
-        }.to raise_error(Sphinx::SphinxConnectError)
+        @sphinx.send(:with_server, @sphinx.servers[0]) { |server| cnt += 1; server.should == @sphinx.servers[0] }
         cnt.should == 1
         cnt = 0
-        expect {
-          @sphinx.send(:with_server) { |server| cnt += 1; server.should == @sphinx.servers[0]; raise Sphinx::SphinxConnectError }
-        }.to raise_error(Sphinx::SphinxConnectError)
+        @sphinx.send(:with_server, @sphinx.servers[1]) { |server| cnt += 1; server.should == @sphinx.servers[1] }
         cnt.should == 1
       end
     end
@@ -80,6 +71,24 @@ describe Sphinx::Client, 'disconnected' do
         }.to raise_error(Sphinx::SphinxConnectError)
         cnt.should == 3
       end
+
+      it 'should round-robin servers with respect to passed index and raise an exception on error' do
+        @sphinx.SetServers(@servers)
+        cnt = 0
+        expect {
+          @sphinx.send(:with_server, 1) { |server| cnt += 1; server.should == @sphinx.servers[cnt % 2]; raise Sphinx::SphinxConnectError }
+        }.to raise_error(Sphinx::SphinxConnectError)
+        cnt.should == 3
+      end
+
+      it 'should round-robin with respect to attempts number passed' do
+        @sphinx.SetServers(@servers)
+        cnt = 0
+        expect {
+          @sphinx.send(:with_server, 0, 5) { |server| cnt += 1; server.should == @sphinx.servers[(cnt - 1) % 2]; raise Sphinx::SphinxConnectError }
+        }.to raise_error(Sphinx::SphinxConnectError)
+        cnt.should == 5
+      end
     end
   end
   

data/sphinx.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{sphinx}
-  s.version = "0.9.10.2091"
+  s.version = "0.9.10.2094"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Dmytro Shteflyuk"]
-  s.date = %q{2009-11-20}
+  s.date = %q{2009-11-23}
   s.description = %q{An easy interface to Sphinx standalone full-text search engine. It is implemented as plugin for Ruby on Rails, but can be easily used as standalone library.}
   s.email = %q{kpumuk@kpumuk.info}
   s.extra_rdoc_files = [

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: sphinx
 version: !ruby/object:Gem::Version 
-  version: 0.9.10.2091
+  version: 0.9.10.2094
 platform: ruby
 authors: 
 - Dmytro Shteflyuk
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-20 00:00:00 +02:00
+date: 2009-11-23 00:00:00 +02:00
 default_executable: 
 dependencies: []