stretcher 1.12.0 → 1.13.0

data/README.md

@@ -10,11 +10,12 @@ A concise, fast ElasticSearch client designed to reflect the actual elastic sear
 # Features
 
 * Cleanly matches up to elastic search's JSON api
-* Efficiently re-uses connections on a per-server object basis (via net/http/persistent)
+* Efficiently re-uses connections on a per-server object basis (via excon)
 * Supports efficient bulk indexing operations
 * Returns most responses in convenient Hashie::Mash form
 * Configurable logging
 * Pure, threadsafe, ruby
+* Easily swap HTTP clients via Faraday
 
 ## Installation
 
@@ -80,15 +81,15 @@ docs = [{"_type" => "tweet", "_id" => 91011, "text" => "Bulked"}]
 server.index(:foo).bulk_index(docs)
 ```
 
+### Full Documentation
+
+This README documents only part of stretcher's API. The full documentation for stretcher is available in its [full rdocs](http://rdoc.info/github/PoseBiz/stretcher/master/frames).
+
 ### Rails Integration
 
 Stretcher is a low level-client, but it was built as a part of a full suite of Rails integration tools.
 While not yet open-sourced, you can read our detailed blog post: [integrating Stretcher with Rails](http://blog.andrewvc.com/elasticsearch-rails-stretcher-at-pose).
 
-### Full Documentation
-
-This README documents only part of stretcher's API. The full documentation for stretcher is available in its [full rdocs](http://rdoc.info/github/PoseBiz/stretcher/master/frames).
-
 ## Running Specs
 
 Running the specs requires an operational Elastic Search server on http://localhost:9200.
@@ -102,6 +103,7 @@ Specs may be run with `rake spec`
 * [@aq1018](https://github.com/aq1018)
 * [@akahn](https://github.com/akahn)
 * [@psynix](https://github.com/psynix)
+* [@cmaitchison](https://github.com/cmaitchison)
 * [@fmardini](https://github.com/fmardini)
 * [@chatgris](https://github.com/chatgris)
 * [@alpinegizmo](https://github.com/alpinegizmo)

data/lib/stretcher/index_type.rb

@@ -11,16 +11,30 @@ module Stretcher
       @logger = options[:logger] || index.logger
     end
 
-    # Retrieves the document by ID
-    # Normally this returns the contents of _source, however, the 'raw' flag is passed in, it will return the full response hash
-    # Returns nil if the document does not exist
+    # Retrieves the document by ID.
+    # Normally this returns the contents of _source, however, if the 'raw' flag is passed in, it will return the full response hash.
+    # Returns nil if the document does not exist.
+    # 
+    # The :fields argument can either be a csv String or an Array. e.g. [:field1,'field2] or "field1,field2".
+    # If the fields parameter is passed in those fields are returned instead of _source.
+    #
+    # If, you include _source as a field, along with other fields you MUST set the raw flag to true to 
+    # receive both fields and _source. Otherwise, only _source will be returned
     def get(id, options={}, raw=false)
       if options == true || options == false # Support raw as second argument, legacy API
         raw = true
         options = {}
       end
+      
+      # If fields is passed in as an array, properly encode it
+      arg_fields = options[:fields]
+      if arg_fields.is_a?(Array)
+        # no #merge! we don't want to mutate args
+        options = options.merge(:fields => arg_fields.join(","))
+      end
+      
       res = request(:get, id, options)
-      raw ? res : res["_source"]
+      raw ? res : (res["_source"] || res["fields"])
     end
 
     # Retrieves multiple documents of the index type by ID

data/lib/stretcher/server.rb

@@ -2,6 +2,52 @@ module Stretcher
   class Server < EsComponent
     attr_reader :uri, :http, :logger
 
+    # Internal use only.
+    # Returns a properly configured HTTP client when initializing an instance
+    def self.build_client(uri, options={})
+      http = Faraday.new(:url => uri) do |builder|
+        builder.response :mashify
+        builder.response :json, :content_type => /\bjson$/
+
+        builder.request :json
+
+        builder.options[:read_timeout] = 4 || options[:read_timeout]
+        builder.options[:open_timeout] = 2 || options[:open_timeout]
+
+        if faraday_configurator = options[:faraday_configurator]
+          faraday_configurator.call(builder)
+        else
+          builder.adapter :excon
+        end
+      end
+
+      uri_components = URI.parse(uri)
+      if uri_components.user || uri_components.password
+        http.basic_auth(uri_components.user, uri_components.password)
+      end
+      
+      http
+    end
+    
+    # Internal use only.
+    # Builds a logger when initializing an instance
+    def self.build_logger(options)
+      logger = nil
+      
+      if options[:logger]
+        logger = options[:logger]
+      else
+        logger = Logger.new(STDOUT)
+        logger.level = Logger::WARN
+      end
+
+      logger.formatter = proc do |severity, datetime, progname, msg|
+        "[Stretcher][#{severity}]: #{msg}\n"
+      end
+      
+      logger
+    end
+
     # Instantiate a new instance in a manner convenient for using the block syntax.
     # Can be used interchangably with +Stretcher::Server.new+ but will return the value
     # of the block if present. See the regular constructor for full options.
@@ -27,38 +73,8 @@ module Stretcher
     def initialize(uri='http://localhost:9200', options={})
       @request_mtx = Mutex.new
       @uri = uri
-
-      @http = Faraday.new(:url => @uri) do |builder|
-        builder.response :mashify
-        builder.response :json, :content_type => /\bjson$/
-
-        builder.request :json
-
-        builder.options[:read_timeout] = 4 || options[:read_timeout]
-        builder.options[:open_timeout] = 2 || options[:open_timeout]
-
-        if faraday_configurator = options[:faraday_configurator]
-          faraday_configurator.call(builder)
-        else
-          builder.adapter :excon
-        end
-      end
-
-      uri_components = URI.parse(@uri)
-      if uri_components.user || uri_components.password
-        @http.basic_auth(uri_components.user, uri_components.password)
-      end
-
-      if options[:logger]
-        @logger = options[:logger]
-      else
-        @logger = Logger.new(STDOUT)
-        @logger.level = Logger::WARN
-      end
-
-      @logger.formatter = proc do |severity, datetime, progname, msg|
-        "[Stretcher][#{severity}]: #{msg}\n"
-      end
+      @http = self.class.build_client(@uri, options)
+      @logger = self.class.build_logger(options)
     end
 
     # Returns a Stretcher::Index object for the index +name+.
@@ -71,7 +87,9 @@ module Stretcher
       idx = Index.new(self, name, :logger => logger)
       block ? block.call(idx) : idx
     end
-
+    
+    # Perform a raw bulk operation. You probably want to use Stretcher::Index#bulk_index
+    # which properly formats a bulk index request.
     def bulk(data)
       request(:post, path_uri("/_bulk")) do |req|
         req.body = data
@@ -169,19 +187,22 @@ module Stretcher
       logger.info { "Stretcher: Issuing Request #{method.to_s.upcase}, #{Util.qurl(url,query_opts)}" }
       
       # Our default client is threadsafe, but some others might not be
-      res = nil
-      @request_mtx.synchronize {
-        res = if block
-                http.send(method, url, query_opts, *args) do |req|
-                  # Elastic search does mostly deal with JSON
-                  req.headers["Content-Type"] = 'application/json'
-                  block.call(req)
-                end
-              else
-                http.send(method, url, query_opts, *args)
-              end
-      }
-
+      check_response(@request_mtx.synchronize {
+        if block
+          http.send(method, url, query_opts, *args) do |req|
+            # Default content type to json, the block can change this of course
+            req.headers["Content-Type"] = 'application/json' unless req.headers
+            block.call(req)
+          end
+        else
+          http.send(method, url, query_opts, *args)
+        end
+      })
+    end
+    
+    # Internal use only
+    # Check response codes from request
+    def check_response(res)
       if res.status >= 200 && res.status <= 299
         res.body
       elsif [404, 410].include? res.status

data/lib/stretcher/version.rb

@@ -1,3 +1,3 @@
 module Stretcher
-  VERSION = "1.12.0"
+  VERSION = "1.13.0"
 end

data/spec/lib/stretcher_index_type_spec.rb

@@ -69,55 +69,71 @@ describe Stretcher::IndexType do
     end
   end
 
-  describe "put/get/delete/explain" do
+  describe "ops on individual docs" do
     before do
       @doc = {:message => "hello!", :_timestamp => 1366420401}
       @put_res = type.put(987, @doc)
     end
-
-    it "should put correctly" do
-      @put_res.should_not be_nil
-    end
-
-    it "should post correctly" do
-      type.post(@doc).should_not be_nil
-    end
-
-    it "should get individual documents correctly" do
-      type.get(987).message.should == @doc[:message]
-    end
-
-    it "should return nil when retrieving non-extant docs" do
-      lambda {
-        type.get(898323329)
-      }.should raise_exception(Stretcher::RequestError::NotFound)
-    end
-
-    it "should get individual, passing through additional options" do
-      res = type.get(987, {:fields => ['_timestamp']})
-      res._timestamp.should == @doc[:_timestamp]
-      res.message == nil
-    end
-
-    it "should get individual raw documents correctly" do
-      res = type.get(987, {}, true)
-      res["_id"].should == "987"
-      res["_source"].message.should == @doc[:message]
-    end
-
-    it "should get individual raw documents correctly with legacy API" do
-      res = type.get(987, true)
-      res["_id"].should == "987"
-      res["_source"].message.should == @doc[:message]
-    end
-
+    
+    describe "put" do
+      it "should put correctly" do
+        @put_res.should_not be_nil
+      end
+
+      it "should post correctly" do
+        type.post(@doc).should_not be_nil
+      end
+    end
+
+    describe "get" do
+      it "should get individual documents correctly" do
+        type.get(987).message.should == @doc[:message]
+      end
+
+      it "should return nil when retrieving non-extant docs" do
+        lambda {
+          type.get(898323329)
+        }.should raise_exception(Stretcher::RequestError::NotFound)
+      end
+
+      it "should get individual fields given a String, passing through additional options" do
+        res = type.get(987, {:fields => '_timestamp'})
+        res._timestamp.should == @doc[:_timestamp]
+        res.message.should == nil
+      end
+
+      it "should get individual fields given an Array, passing through additional options" do
+        res = type.get(987, {:fields => ['_timestamp']})
+        res._timestamp.should == @doc[:_timestamp]
+        res.message.should == nil
+      end
+
+      it "should have source and other fields accessible when raw=true" do
+        res = type.get(987, {:fields => ['_timestamp', '_source']}, true)
+        res._source.message == @doc[:message]
+        res.fields._timestamp.should == @doc[:_timestamp]
+      end
+
+      it "should get individual raw documents correctly" do
+        res = type.get(987, {}, true)
+        res["_id"].should == "987"
+        res["_source"].message.should == @doc[:message]
+      end
+
+      it "should get individual raw documents correctly with legacy API" do
+        res = type.get(987, true)
+        res["_id"].should == "987"
+        res["_source"].message.should == @doc[:message]
+      end
+    end
+    
     it "should explain a query" do
       type.exists?(987).should be_true
       index.refresh
       res = type.explain(987, {:query => {:match_all => {}}})
       res.should have_key('explanation')
     end
-
+    
     it "should update individual docs correctly" do
       type.update(987, :script => "ctx._source.message = 'Updated!'")
       type.get(987).message.should == 'Updated!'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stretcher
 version: !ruby/object:Gem::Version
-  version: 1.12.0
+  version: 1.13.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-29 00:00:00.000000000 Z
+date: 2013-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday