elasticsearch-transport 6.8.1 → 6.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf520599f6e46c395ff1fceef21ca8695054edcfef671b79c2da2899fb71addd
-  data.tar.gz: 45e976dc56a422aa28c4e88e25c640da7d344e73626a6fa2060a644c0110cc4b
+  metadata.gz: c036b32f60221fef3a8c617ddc30a55c50c916b4f3c235fe34f91917060c9ae4
+  data.tar.gz: 18d4582f2c6479fe2af5bf10a6f6cc97d6083172274be5de85d82a47f62b1a04
 SHA512:
-  metadata.gz: f0e09ba9f20e715741a8f0443d9c18517ce145dd428f345831a74f41cb6dd08355b2b653e9b945b2ed4101b5dc1635f062c0ff1d7e89e5996515de7a614e5765
-  data.tar.gz: 264296357a6866a21a86f268c919fea1309e7283e0c1be6f7fd2dc407350dfeaf16115072c82d021d0da43916db8c1832cfc842f9c72040df3c23360f58d480c
+  metadata.gz: a06a56942b78b094e562ef1fa4d6adfd9433a823aeb3e21e06296574c39bcb5c228b52a009fe3a375a8682a1d0e9c9d370ff74a5a84dce4d2800170ede4e3d5c
+  data.tar.gz: 8646819dd552fae0bbba12d03e0a2ed1c996f2d0493a0ad65c4f07bd5e2ae763d8067aefc66c8d52963def632d1a552c7271744233ba12a5b43945d281800d1c

data/README.md

@@ -28,12 +28,16 @@ Features overview:
 * Node reloading (based on cluster state) on errors or on demand
 
 For optimal performance, use a HTTP library which supports persistent ("keep-alive") connections,
-such as [Typhoeus](https://github.com/typhoeus/typhoeus).
-Just require the library (`require 'typhoeus'; require 'typhoeus/adapters/faraday'`) in your code,
-and it will be automatically used; currently these libraries will be automatically detected and used:
-[Patron](https://github.com/toland/patron),
-[HTTPClient](https://rubygems.org/gems/httpclient) and
-[Net::HTTP::Persistent](https://rubygems.org/gems/net-http-persistent).
+such as [patron](https://github.com/toland/patron).
+Just require the library (`require 'patron'`) in your code,
+and it will be automatically used.
+
+Currently these libraries will be automatically detected and used:
+- [Patron](https://github.com/toland/patron)
+- [HTTPClient](https://rubygems.org/gems/httpclient)
+- [Net::HTTP::Persistent](https://rubygems.org/gems/net-http-persistent)
+
+**Note on [Typhoeus](https://github.com/typhoeus/typhoeus)**: Typhoeus is compatible and will be automatically detected too. However, the latest release (v1.3.1 at the moment of writing this) is not compatible with Faraday 1.0. [It still uses the deprecated `Faraday::Error` namespace](https://github.com/typhoeus/typhoeus/blob/v1.3.1/lib/typhoeus/adapters/faraday.rb#L100). If you want to use it with this gem, we suggest getting `master` from GitHub, since this has been fixed for v1.4.0. We'll update this if/when v1.4.0 is released.a
 
 For detailed information, see example configurations [below](#transport-implementations).
 
@@ -69,6 +73,22 @@ Full documentation is available at <http://rubydoc.info/gems/elasticsearch-trans
 
 ## Configuration
 
+* [Setting Hosts](#setting-hosts)
+* [Default port](#default-port)
+* [Connect using an Elastic Cloud ID](#connect-using-an-elastic-cloud-id)
+* [Authentication](#authentication)
+* [Logging](#logging)
+* [Identifying running tasks with X-Opaque-Id](#identifying-running-tasks-with-x-opaque-id)
+* [Setting Timeouts](#setting-timeouts)
+* [Randomizing Hosts](#randomizing-hosts)
+* [Retrying on Failures](#retrying-on-failures)
+* [Reloading Hosts](#reloading-hosts)
+* [Connection Selector](#connection-selector)
+* [Transport Implementations](#transport-implementations)
+* [Serializer implementations](#serializer-implementations)
+* [Exception Handling](#exception-handling)
+* [Development and Community](#development-and-community)
+
 The client supports many configurations options for setting up and managing connections,
 configuring logging, customizing the transport library, etc.
 
@@ -128,6 +148,26 @@ use the `transport_options` option:
     Elasticsearch::Client.new url: 'https://username:password@example.com:9200',
                               transport_options: { ssl: { ca_file: '/path/to/cacert.pem' } }
 
+You can also use [**API Key authentication**](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html):
+
+``` ruby
+Elasticsearch::Client.new(
+  host: host,
+  transport_options: transport_options,
+  api_key: credentials
+)
+```
+
+Where credentials is either the base64 encoding of `id` and `api_key` joined by a colon or a hash with the `id` and `api_key`:
+
+``` ruby
+Elasticsearch::Client.new(
+  host: host,
+  transport_options: transport_options,
+  api_key: {id: 'my_id', api_key: 'my_api_key'}
+)
+```
+
 ### Logging
 
 To log requests and responses to standard output with the default logger (an instance of Ruby's {::Logger} class),
@@ -158,6 +198,29 @@ You can pass the client any conforming logger implementation:
 
     client = Elasticsearch::Client.new logger: log
 
+### Identifying running tasks with X-Opaque-Id
+
+The X-Opaque-Id header allows to track certain calls, or associate certain tasks with the client that started them ([more on the Elasticsearch docs](https://www.elastic.co/guide/en/elasticsearch/reference/master/tasks.html#_identifying_running_tasks)). To use this feature, you need to set an id for `opaque_id` on the client on each request. Example:
+
+```ruby
+client = Elasticsearch::Client.new
+client.search(index: 'myindex', q: 'title:test', opaque_id: '123456')
+```
+The search request will include the following HTTP Header:
+```
+X-Opaque-Id: 123456
+```
+
+You can also set a prefix for X-Opaque-Id when initializing the client. This will be prepended to the id you set before each request if you're using X-Opaque-Id. Example:
+```ruby
+client = Elasticsearch::Client.new(opaque_id_prefix: 'eu-west1')
+client.search(index: 'myindex', q: 'title:test', opaque_id: '123456')
+```
+The request will include the following HTTP Header:
+```
+X-Opaque-Id: eu-west1_123456
+```
+
 ### Setting Timeouts
 
 For many operations in Elasticsearch, the default timeouts of HTTP libraries are too low.
@@ -292,44 +355,35 @@ constructor, use the `transport_options` key:
 
 To configure the _Faraday_ instance directly, use a block:
 
-    require 'typhoeus'
-    require 'typhoeus/adapters/faraday'
+    require 'patron'
 
     client = Elasticsearch::Client.new(host: 'localhost', port: '9200') do |f|
       f.response :logger
-      f.adapter  :typhoeus
+      f.adapter  :patron
     end
 
-You can use any standard Faraday middleware and plugins in the configuration block,
-for example sign the requests for the [AWS Elasticsearch service](https://aws.amazon.com/elasticsearch-service/):
-
-    require 'faraday_middleware/aws_signers_v4'
-
-    client = Elasticsearch::Client.new url: 'https://search-my-cluster-abc123....es.amazonaws.com' do |f|
-      f.request :aws_signers_v4,
-                credentials: Aws::Credentials.new(ENV['AWS_ACCESS_KEY'], ENV['AWS_SECRET_ACCESS_KEY']),
-                service_name: 'es',
-                region: 'us-east-1'
-    end
+You can use any standard Faraday middleware and plugins in the configuration block, for example sign the requests for the [AWS Elasticsearch service](https://aws.amazon.com/elasticsearch-service/). See [the AWS documentation](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-request-signing.html#es-request-signing-ruby) for an example.
 
 You can also initialize the transport class yourself, and pass it to the client constructor
 as the `transport` argument:
 
-    require 'typhoeus'
-    require 'typhoeus/adapters/faraday'
+```ruby
+require 'patron'
 
-    transport_configuration = lambda do |f|
-      f.response :logger
-      f.adapter  :typhoeus
-    end
+transport_configuration = lambda do |f|
+  f.response :logger
+  f.adapter  :patron
+end
 
-    transport = Elasticsearch::Transport::Transport::HTTP::Faraday.new \
-      hosts: [ { host: 'localhost', port: '9200' } ],
-      &transport_configuration
+transport = Elasticsearch::Transport::Transport::HTTP::Faraday.new \
+  hosts: [ { host: 'localhost', port: '9200' } ],
+  &transport_configuration
+
+# Pass the transport to the client
+#
+client = Elasticsearch::Client.new transport: transport
+```
 
-    # Pass the transport to the client
-    #
-    client = Elasticsearch::Client.new transport: transport
 
 Instead of passing the transport to the constructor, you can inject it at run time:
 

data/elasticsearch-transport.gemspec

@@ -4,75 +4,55 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'elasticsearch/transport/version'
 
 Gem::Specification.new do |s|
-  s.name          = "elasticsearch-transport"
+  s.name          = 'elasticsearch-transport'
   s.version       = Elasticsearch::Transport::VERSION
-  s.authors       = ["Karel Minarik"]
-  s.email         = ["karel.minarik@elasticsearch.org"]
-  s.summary       = "Ruby client for Elasticsearch."
-  s.homepage      = "https://github.com/elasticsearch/elasticsearch-ruby/tree/master/elasticsearch-transport"
-  s.license       = "Apache-2.0"
-
+  s.authors       = ['Karel Minarik']
+  s.email         = ['karel.minarik@elasticsearch.org']
+  s.summary       = 'Ruby client for Elasticsearch.'
+  s.homepage      = 'https://www.elastic.co/guide/en/elasticsearch/client/ruby-api/current/index.html'
+  s.license       = 'Apache-2.0'
+  s.metadata = {
+    'homepage_uri' => 'https://www.elastic.co/guide/en/elasticsearch/client/ruby-api/current/index.html',
+    'changelog_uri' => 'https://github.com/elastic/elasticsearch-ruby/blob/6.x/CHANGELOG.md',
+    'source_code_uri' => 'https://github.com/elastic/elasticsearch-ruby/tree/6.x/elasticsearch-transport',
+    'bug_tracker_uri' => 'https://github.com/elastic/elasticsearch-ruby/issues'
+  }
   s.files         = `git ls-files`.split($/)
   s.executables   = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
   s.test_files    = s.files.grep(%r{^(test|spec|features)/})
-  s.require_paths = ["lib"]
-
-  s.extra_rdoc_files  = [ "README.md", "LICENSE.txt" ]
-  s.rdoc_options      = [ "--charset=UTF-8" ]
-
-  s.required_ruby_version = '>= 1.9'
-
-  s.add_dependency "multi_json"
-  s.add_dependency "faraday", '>= 0.14', "< 1"
-
-  if defined?(RUBY_VERSION) && RUBY_VERSION < '1.9'
-    s.add_dependency "system_timer"
-  end
-
-  s.add_development_dependency "bundler"
-
-  if defined?(RUBY_VERSION) && RUBY_VERSION > '1.9'
-    s.add_development_dependency "rake", "~> 11.1"
-  else
-    s.add_development_dependency "rake", "< 11.0"
-  end
-
-  if defined?(RUBY_VERSION) && RUBY_VERSION > '1.9'
-    s.add_development_dependency "elasticsearch-extensions"
-  end
-
-  s.add_development_dependency "ansi"
-  s.add_development_dependency "shoulda-context"
-  s.add_development_dependency "mocha"
-  s.add_development_dependency "turn"
-  s.add_development_dependency "yard"
-  s.add_development_dependency "pry"
-
+  s.require_paths = ['lib']
+
+  s.extra_rdoc_files  = ['README.md', 'LICENSE.txt']
+  s.rdoc_options      = ['--charset=UTF-8']
+
+  s.required_ruby_version = '>= 2.4'
+
+  s.add_dependency 'multi_json'
+  s.add_dependency 'faraday', '~> 1'
+  s.add_development_dependency 'ansi'
+  s.add_development_dependency 'bundler'
+  s.add_development_dependency 'elasticsearch-extensions'
+  s.add_development_dependency 'mocha'
+  s.add_development_dependency 'pry'
+  s.add_development_dependency 'rake', '~> 13'
+  s.add_development_dependency 'shoulda-context'
+  s.add_development_dependency 'turn'
+  s.add_development_dependency 'yard'
   # Gems for testing integrations
-  s.add_development_dependency "curb"   unless defined? JRUBY_VERSION
-  s.add_development_dependency "patron" unless defined? JRUBY_VERSION
-  s.add_development_dependency "typhoeus", '~> 0.6'
-  s.add_development_dependency "net-http-persistent"
-  s.add_development_dependency "manticore", '~> 0.5.2' if defined? JRUBY_VERSION
-  s.add_development_dependency "hashie"
-
-  # Prevent unit test failures on Ruby 1.8
-  if defined?(RUBY_VERSION) && RUBY_VERSION < '1.9'
-    s.add_development_dependency "test-unit", '~> 2'
-    s.add_development_dependency "json", '~> 1.8'
-  end
-
-  if defined?(RUBY_VERSION) && RUBY_VERSION > '1.9'
-    s.add_development_dependency "minitest", "~> 4.0"
-    s.add_development_dependency "ruby-prof"    unless defined?(JRUBY_VERSION) || defined?(Rubinius)
-    s.add_development_dependency "require-prof" unless defined?(JRUBY_VERSION) || defined?(Rubinius)
-    s.add_development_dependency "simplecov"
-    s.add_development_dependency "simplecov-rcov"
-    s.add_development_dependency "cane"
-  end
-
-  if defined?(RUBY_VERSION) && RUBY_VERSION > '2.2'
-    s.add_development_dependency "test-unit", '~> 2'
+  s.add_development_dependency 'cane'
+  s.add_development_dependency 'hashie'
+  s.add_development_dependency 'manticore', '~> 0.5.2' if defined? JRUBY_VERSION
+  s.add_development_dependency 'minitest', '~> 4.0'
+  s.add_development_dependency 'net-http-persistent'
+  s.add_development_dependency 'simplecov', '~> 0.17', '< 0.18'
+  s.add_development_dependency 'simplecov-rcov'
+  s.add_development_dependency 'test-unit', '~> 2'
+  s.add_development_dependency 'typhoeus', '~> 0.6'
+  unless defined?(JRUBY_VERSION) || defined?(Rubinius)
+    s.add_development_dependency 'curb'
+    s.add_development_dependency 'patron'
+    s.add_development_dependency 'require-prof'
+    s.add_development_dependency 'ruby-prof'
   end
 
   s.description = <<-DESC.gsub(/^    /, '')

data/lib/elasticsearch-transport.rb

@@ -1 +1,5 @@
+# Licensed to Elasticsearch B.V under one or more agreements.
+# Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+# See the LICENSE file in the project root for more information
+
 require 'elasticsearch/transport'

data/lib/elasticsearch/transport.rb

@@ -1,3 +1,7 @@
+# Licensed to Elasticsearch B.V under one or more agreements.
+# Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+# See the LICENSE file in the project root for more information
+
 require "uri"
 require "time"
 require "timeout"

data/lib/elasticsearch/transport/client.rb

@@ -1,3 +1,7 @@
+# Licensed to Elasticsearch B.V under one or more agreements.
+# Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+# See the LICENSE file in the project root for more information
+
 module Elasticsearch
   module Transport
 
@@ -85,6 +89,11 @@ module Elasticsearch
       # @option arguments [String] :send_get_body_as Specify the HTTP method to use for GET requests with a body.
       #                                              (Default: GET)
       #
+      # @option api_key [String, Hash] :api_key Use API Key Authentication, either the base64 encoding of `id` and `api_key`
+      #                                         joined by a colon as a String, or a hash with the `id` and `api_key` values.
+      # @option opaque_id_prefix [String] :opaque_id_prefix set a prefix for X-Opaque-Id when initializing the client. This
+      # will be prepended to the id you set before each request if you're using X-Opaque-Id
+      #
       # @yield [faraday] Access and configure the `Faraday::Connection` instance directly with a block
       #
       def initialize(arguments={}, &block)
@@ -100,7 +109,10 @@ module Elasticsearch
         @arguments[:http]               ||= {}
         @options[:http]                 ||= {}
 
-        @seeds = __extract_hosts(@arguments[:hosts] ||
+        set_api_key if (@api_key = @arguments[:api_key])
+
+
+        @seeds ||= __extract_hosts(@arguments[:hosts] ||
                                      @arguments[:host] ||
                                      @arguments[:url] ||
                                      @arguments[:urls] ||
@@ -108,9 +120,10 @@ module Elasticsearch
                                      DEFAULT_HOST)
 
         @send_get_body_as = @arguments[:send_get_body_as] || 'GET'
+        @opaque_id_prefix = @arguments[:opaque_id_prefix] || nil
 
         if @arguments[:request_timeout]
-          @arguments[:transport_options][:request] = { :timeout => @arguments[:request_timeout] }
+          @arguments[:transport_options][:request] = { timeout: @arguments[:request_timeout] }
         end
 
         @arguments[:transport_options][:headers] ||= {}
@@ -124,27 +137,41 @@ module Elasticsearch
         else
           transport_class  = @arguments[:transport_class] || DEFAULT_TRANSPORT_CLASS
           if transport_class == Transport::HTTP::Faraday
-            @transport = transport_class.new(:hosts => @seeds, :options => @arguments) do |faraday|
-              block.call faraday if block
-              unless (h = faraday.builder.handlers.last) && h.name.start_with?("Faraday::Adapter")
-                faraday.adapter(@arguments[:adapter] || __auto_detect_adapter)
-              end
+            @transport = transport_class.new(hosts: @seeds, options: @arguments) do |faraday|
+              faraday.adapter(@arguments[:adapter] || __auto_detect_adapter)
+              block&.call faraday
             end
           else
-            @transport = transport_class.new(:hosts => @seeds, :options => @arguments)
+            @transport = transport_class.new(hosts: @seeds, options: @arguments)
           end
         end
       end
 
       # Performs a request through delegation to {#transport}.
       #
-      def perform_request(method, path, params={}, body=nil, headers=nil)
+      def perform_request(method, path, params = {}, body = nil, headers = nil)
         method = @send_get_body_as if 'GET' == method && body
+        if (opaque_id = params.delete(:opaque_id))
+          headers = {} if headers.nil?
+          opaque_id = @opaque_id_prefix ? "#{@opaque_id_prefix}#{opaque_id}" : opaque_id
+          headers.merge!('X-Opaque-Id' => opaque_id)
+        end
         transport.perform_request(method, path, params, body, headers)
       end
 
       private
 
+      def set_api_key
+        @api_key = __encode(@api_key) if @api_key.is_a? Hash
+        headers = @arguments[:transport_options]&.[](:headers) || {}
+        headers.merge!('Authorization' => "ApiKey #{@api_key}")
+        @arguments[:transport_options].merge!(
+          headers: headers
+        )
+        @arguments.delete(:user)
+        @arguments.delete(:password)
+      end
+
       # Normalizes and returns hosts configuration.
       #
       # Arrayifies the `hosts_config` argument and extracts `host` and `port` info from strings.
@@ -202,8 +229,14 @@ module Elasticsearch
                        raise ArgumentError, "Please pass host as a String, URI or Hash -- #{host.class} given."
                      end
 
-        @options[:http][:user] ||= host_parts[:user]
-        @options[:http][:password] ||= host_parts[:password]
+        if @api_key
+          # Remove Basic Auth if using API KEY
+          host_parts.delete(:user)
+          host_parts.delete(:password)
+        else
+          @options[:http][:user] ||= host_parts[:user]
+          @options[:http][:password] ||= host_parts[:password]
+        end
 
         host_parts[:port] = host_parts[:port].to_i if host_parts[:port]
         host_parts[:path].chomp!('/') if host_parts[:path]
@@ -232,6 +265,13 @@ module Elasticsearch
           ::Faraday.default_adapter
         end
       end
+
+      # Encode credentials for the Authorization Header
+      # Credentials is the base64 encoding of id and api_key joined by a colon
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html
+      def __encode(api_key)
+        Base64.strict_encode64([api_key[:id], api_key[:api_key]].join(':'))
+      end
     end
   end
 end

data/lib/elasticsearch/transport/redacted.rb

@@ -1,3 +1,7 @@
+# Licensed to Elasticsearch B.V under one or more agreements.
+# Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+# See the LICENSE file in the project root for more information
+
 # Licensed to Elasticsearch B.V. under one or more contributor
 # license agreements. See the NOTICE file distributed with
 # this work for additional information regarding copyright

data/lib/elasticsearch/transport/transport/base.rb

@@ -1,3 +1,7 @@
+# Licensed to Elasticsearch B.V under one or more agreements.
+# Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+# See the LICENSE file in the project root for more information
+
 module Elasticsearch
   module Transport
     module Transport
@@ -16,7 +20,7 @@ module Elasticsearch
         attr_reader   :hosts, :options, :connections, :counter, :last_request_at, :protocol
         attr_accessor :serializer, :sniffer, :logger, :tracer,
                       :reload_connections, :reload_after,
-                      :resurrect_after, :max_retries
+                      :resurrect_after
 
         # Creates a new transport object
         #
@@ -52,7 +56,6 @@ module Elasticsearch
           @reload_connections = options[:reload_connections]
           @reload_after    = options[:reload_connections].is_a?(Integer) ? options[:reload_connections] : DEFAULT_RELOAD_AFTER
           @resurrect_after = options[:resurrect_after] || DEFAULT_RESURRECT_AFTER
-          @max_retries     = options[:retry_on_failure].is_a?(Integer)   ? options[:retry_on_failure]   : DEFAULT_MAX_RETRIES
           @retry_on_status = Array(options[:retry_on_status]).map { |d| d.to_i }
         end
 
@@ -244,10 +247,17 @@ module Elasticsearch
         # @raise  [ServerError]   If request failed on server
         # @raise  [Error]         If no connection is available
         #
-        def perform_request(method, path, params={}, body=nil, headers=nil, &block)
+        def perform_request(method, path, params={}, body=nil, headers=nil, opts={}, &block)
           raise NoMethodError, "Implement this method in your transport class" unless block_given?
           start = Time.now if logger || tracer
           tries = 0
+          reload_on_failure = opts.fetch(:reload_on_failure, @options[:reload_on_failure])
+
+          max_retries = if opts.key?(:retry_on_failure)
+            opts[:retry_on_failure] === true ? DEFAULT_MAX_RETRIES : opts[:retry_on_failure]
+          elsif options.key?(:retry_on_failure)
+            options[:retry_on_failure] === true ? DEFAULT_MAX_RETRIES : options[:retry_on_failure]
+          end
 
           params = params.clone
 
@@ -271,9 +281,9 @@ module Elasticsearch
             __raise_transport_error(response) if response.status.to_i >= 300 && @retry_on_status.include?(response.status.to_i)
 
           rescue Elasticsearch::Transport::Transport::ServerError => e
-            if @retry_on_status.include?(response.status)
+            if response && @retry_on_status.include?(response.status)
               logger.warn "[#{e.class}] Attempt #{tries} to get response from #{url}" if logger
-              if tries <= max_retries
+              if tries <= (max_retries || DEFAULT_MAX_RETRIES)
                 retry
               else
                 logger.fatal "[#{e.class}] Cannot get response from #{url} after #{tries} tries" if logger
@@ -288,12 +298,12 @@ module Elasticsearch
 
             connection.dead!
 
-            if @options[:reload_on_failure] and tries < connections.all.size
+            if reload_on_failure and tries < connections.all.size
               logger.warn "[#{e.class}] Reloading connections (attempt #{tries} of #{connections.all.size})" if logger
               reload_connections! and retry
             end
 
-            if @options[:retry_on_failure]
+            if max_retries
               logger.warn "[#{e.class}] Attempt #{tries} connecting to #{connection.host.inspect}" if logger
               if tries <= max_retries
                 retry