elasticsearch-transport 7.1.0 → 7.13.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14188a454b64314c13f7c9279741fc8df5f9f03ff9813f45aeca96abc8da7e39
-  data.tar.gz: dfcd7ac5fb8e0b2a0450b2939272f88a329581648c47b130d62e1fcead705b44
+  metadata.gz: a045f07e51e54095cdd4d050a786070b35eadc7356b5167c99da881738cf5607
+  data.tar.gz: 854f2d899cdbbb184ce945a6b6dfa0a1f7f463bcf3d818c4e7f66a28ca81a504
 SHA512:
-  metadata.gz: 36e9583f541ec75994cb27479c16f4624d7ea6a9e6f33360d7cac69541fe10a5c2ee2d7f20b2c1231b5fd07ab85cd32baefb236d6ab77ff11635bb23b1d9d801
-  data.tar.gz: 95faf1016519c04dcafcd6580356dcfb00c8eeb9ef3301bf2ff3c66a90cfcc8ebf676b638ec18f92f708acb5ef01ee2f7ee137f23ed6532774b371e47b02e11f
+  metadata.gz: 89c3b0674a119afb4aa397bacf6282bd301862ca4a5aa107b0789c93493644f678414587dd695e3210fdbe8afaed6bf9db8a10ee1a3597767211afb2fb4d4da4
+  data.tar.gz: 6706d0c3441f9eed32b7e930e2cd808774bb8de1083109a6681a1433929dc407f324e97bdbaf1bf3dce9c452fc527abc3cbd7ccd071cfbff46977a93af31ba5d

data/Gemfile

@@ -6,7 +6,7 @@
 # not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
-#	http://www.apache.org/licenses/LICENSE-2.0
+#   http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing,
 # software distributed under the License is distributed on an
@@ -20,19 +20,23 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in elasticsearch-transport.gemspec
 gemspec
 
-if File.exist? File.expand_path("../../elasticsearch-api/elasticsearch-api.gemspec", __FILE__)
-  gem 'elasticsearch-api', :path => File.expand_path("../../elasticsearch-api", __FILE__), :require => false
+if File.exist? File.expand_path('../../elasticsearch-api/elasticsearch-api.gemspec', __FILE__)
+  gem 'elasticsearch-api', path: File.expand_path('../../elasticsearch-api', __FILE__), require: false
 end
 
-if File.exist? File.expand_path("../../elasticsearch-extensions/elasticsearch-extensions.gemspec", __FILE__)
-  gem 'elasticsearch-extensions', :path => File.expand_path("../../elasticsearch-extensions", __FILE__), :require => false
+if File.exist? File.expand_path('../../elasticsearch-extensions/elasticsearch-extensions.gemspec', __FILE__)
+  gem 'elasticsearch-extensions', path: File.expand_path('../../elasticsearch-extensions', __FILE__), require: false
 end
 
-if File.exist? File.expand_path("../../elasticsearch/elasticsearch.gemspec", __FILE__)
-  gem 'elasticsearch', :path => File.expand_path("../../elasticsearch", __FILE__), :require => false
+if File.exist? File.expand_path('../../elasticsearch/elasticsearch.gemspec', __FILE__)
+  gem 'elasticsearch', path: File.expand_path('../../elasticsearch', __FILE__), require: false
 end
 
-group :development do
+group :development, :test do
   gem 'rspec'
-  gem 'pry-nav'
+  if defined?(JRUBY_VERSION)
+    gem 'pry-nav'
+  else
+    gem 'pry-byebug'
+  end
 end

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) or [Typhoeus](https://github.com/typhoeus/typhoeus).
+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)
+- [Typhoeus](https://github.com/typhoeus/typhoeus)
+- [HTTPClient](https://rubygems.org/gems/httpclient)
+- [Net::HTTP::Persistent](https://rubygems.org/gems/net-http-persistent)
+
+**Note on [Typhoeus](https://github.com/typhoeus/typhoeus)**: You need to use v1.4.0 or up since older versions are not compatible with Faraday 1.0.
 
 For detailed information, see example configurations [below](#transport-implementations).
 
@@ -69,6 +73,23 @@ 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)
+* [Custom HTTP Headers](#custom-http-headers)
+* [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.
 
@@ -106,6 +127,22 @@ Another way to configure the URL(s) is to export the `ELASTICSEARCH_URL` variabl
 The client will automatically round-robin across the hosts
 (unless you select or implement a different [connection selector](#connection-selector)).
 
+### Default port
+
+The default port is `9200`. Please specify a port for your host(s) if they differ from this default.
+Please see below for an exception to this when connecting using an Elastic Cloud ID.
+
+### Connect using an Elastic Cloud ID
+
+If you are using [Elastic Cloud](https://www.elastic.co/cloud), you can provide your cloud id to the client.
+You must supply your username and password separately, and optionally a port. If no port is supplied,
+port 443 will be used.
+
+Note: Do not enable sniffing when using Elastic Cloud. The nodes are behind a load balancer so
+Elastic Cloud will take care of everything for you.
+
+    Elasticsearch::Client.new(cloud_id: 'name:bG9jYWxob3N0JGFiY2QkZWZnaA==', user: 'elastic', password: 'changeme')
+
 ### Authentication
 
 You can pass the authentication credentials, scheme and port in the host configuration hash:
@@ -128,35 +165,114 @@ 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),
-set the `log` argument:
+To log requests and responses to standard output with the default logger (an instance of Ruby's {::Logger} class), set the `log` argument to true:
+
+```ruby
+Elasticsearch::Client.new(log: true)
+```
+
+You can also use [ecs-logging](https://github.com/elastic/ecs-logging-ruby). `ecs-logging` is a set of libraries that allows you to transform your application logs to structured logs that comply with the [Elastic Common Schema (ECS)](https://www.elastic.co/guide/en/ecs/current/ecs-reference.html):
+
+```ruby
+logger = EcsLogging::Logger.new($stdout)
+Elasticsearch::Client.new(logger: logger)
+```
 
-    Elasticsearch::Client.new log: true
 
 To trace requests and responses in the _Curl_ format, set the `trace` argument:
 
-    Elasticsearch::Client.new trace: true
+```ruby
+Elasticsearch::Client.new(trace: true)
+```
 
 You can customize the default logger or tracer:
 
+```ruby
     client.transport.logger.formatter = proc { |s, d, p, m| "#{s}: #{m}\n" }
     client.transport.logger.level = Logger::INFO
+```
 
-Or, you can use a custom {::Logger} instance:
+Or, you can use a custom `::Logger` instance:
 
-    Elasticsearch::Client.new logger: Logger.new(STDERR)
+```ruby
+Elasticsearch::Client.new(logger: Logger.new(STDERR))
+```
 
 You can pass the client any conforming logger implementation:
 
-    require 'logging' # https://github.com/TwP/logging/
+```ruby
+require 'logging' # https://github.com/TwP/logging/
+
+log = Logging.logger['elasticsearch']
+log.add_appenders Logging.appenders.stdout
+log.level = :info
+
+client = Elasticsearch::Client.new(logger: log)
+```
+
+### Custom HTTP Headers
+
+You can set a custom HTTP header on the client's initializer:
+
+```ruby
+client = Elasticsearch::Client.new(
+  transport_options: {
+    headers:
+      {user_agent: "My App"}
+  }
+)
+```
+
+You can also pass in `headers` as a parameter to any of the API Endpoints to set custom headers for the request:
 
-    log = Logging.logger['elasticsearch']
-    log.add_appenders Logging.appenders.stdout
-    log.level = :info
+```ruby
+client.search(index: 'myindex', q: 'title:test', headers: {user_agent: "My App"})
+```
+
+### 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
+```
 
-    client = Elasticsearch::Client.new logger: log
+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
 
@@ -183,11 +299,16 @@ on a different host:
 
     Elasticsearch::Client.new hosts: ['localhost:9200', 'localhost:9201'], retry_on_failure: true
 
-You can specify how many times should the client retry the request before it raises an exception
-(the default is 3 times):
+By default, the client will retry the request 3 times. You can specify how many times to retry before it raises an exception by passing a number to `retry_on_failure`:
 
     Elasticsearch::Client.new hosts: ['localhost:9200', 'localhost:9201'], retry_on_failure: 5
 
+These two parameters can also be used together:
+
+```ruby
+Elasticsearch::Client.new hosts: ['localhost:9200', 'localhost:9201'], retry_on_status: [502, 503], retry_on_failure: 10
+```
+
 ### Reloading Hosts
 
 Elasticsearch by default dynamically discovers new nodes in the cluster. You can leverage this
@@ -252,25 +373,29 @@ preferring HTTP clients with support for persistent connections.
 
 To use the [_Patron_](https://github.com/toland/patron) HTTP, for example, just require it:
 
-    require 'patron'
+```ruby
+require 'patron'
+```
 
 Then, create a new client, and the _Patron_  gem will be used as the "driver":
 
-    client = Elasticsearch::Client.new
+```ruby
+client = Elasticsearch::Client.new
 
-    client.transport.connections.first.connection.builder.handlers
-    # => [Faraday::Adapter::Patron]
+client.transport.connections.first.connection.builder.adapter
+# => Faraday::Adapter::Patron
 
-    10.times do
-      client.nodes.stats(metric: 'http')['nodes'].values.each do |n|
-        puts "#{n['name']} : #{n['http']['total_opened']}"
-      end
-    end
+10.times do
+  client.nodes.stats(metric: 'http')['nodes'].values.each do |n|
+    puts "#{n['name']} : #{n['http']['total_opened']}"
+  end
+end
 
-    # => Stiletoo : 24
-    # => Stiletoo : 24
-    # => Stiletoo : 24
-    # => ...
+# => Stiletoo : 24
+# => Stiletoo : 24
+# => Stiletoo : 24
+# => ...
+```
 
 To use a specific adapter for _Faraday_, pass it as the `adapter` argument:
 
@@ -292,44 +417,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:
 
@@ -458,21 +574,4 @@ can use Ruby 2.x syntax and features.
 
 ## License
 
-This software is licensed under the Apache 2 license, quoted below.
-
-    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
-    ownership. Elasticsearch B.V. licenses this file to you under
-    the Apache License, Version 2.0 (the "License"); you may
-    not use this file except in compliance with the License.
-    You may obtain a copy of the License at
-    
-    	http://www.apache.org/licenses/LICENSE-2.0
-    
-    Unless required by applicable law or agreed to in writing,
-    software distributed under the License is distributed on an
-    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-    KIND, either express or implied.  See the License for the
-    specific language governing permissions and limitations
-    under the License.
+This software is licensed under the [Apache 2 license](./LICENSE).

data/Rakefile

@@ -6,7 +6,7 @@
 # not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
-#	http://www.apache.org/licenses/LICENSE-2.0
+#   http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing,
 # software distributed under the License is distributed on an

data/elasticsearch-transport.gemspec

@@ -6,7 +6,7 @@
 # not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
-#	http://www.apache.org/licenses/LICENSE-2.0
+#   http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing,
 # software distributed under the License is distributed on an
@@ -21,73 +21,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/7.x/index.html'
+  s.license       = 'Apache-2.0'
+  s.metadata = {
+    'homepage_uri' => 'https://www.elastic.co/guide/en/elasticsearch/client/ruby-api/7.x/index.html',
+    'changelog_uri' => 'https://github.com/elastic/elasticsearch-ruby/blob/7.x/CHANGELOG.md',
+    'source_code_uri' => 'https://github.com/elastic/elasticsearch-ruby/tree/7.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"
-
-  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
-
-  s.add_development_dependency "ansi"
-  s.add_development_dependency "shoulda-context"
-  s.add_development_dependency "mocha"
-  s.add_development_dependency "yard"
-  s.add_development_dependency "pry"
+  s.require_paths = ['lib']
 
-  # 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.6' if defined? JRUBY_VERSION
-  s.add_development_dependency "hashie"
+  s.extra_rdoc_files  = [ 'README.md', 'LICENSE' ]
+  s.rdoc_options      = [ '--charset=UTF-8' ]
 
-  # 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
+  s.required_ruby_version = '>= 2.4'
 
-  if defined?(RUBY_VERSION) && RUBY_VERSION > '1.9'
-    s.add_development_dependency "minitest"
-    s.add_development_dependency "minitest-reporters"
-    s.add_development_dependency "elasticsearch-extensions"
-    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
+  s.add_dependency 'multi_json'
+  s.add_dependency 'faraday', '~> 1'
 
-  if defined?(RUBY_VERSION) && RUBY_VERSION > '2.2'
-    s.add_development_dependency "test-unit", '~> 2'
-  end
+  s.add_development_dependency 'cane'
+  s.add_development_dependency 'curb'   unless defined? JRUBY_VERSION
+  s.add_development_dependency 'elasticsearch-extensions'
+  s.add_development_dependency 'minitest'
+  s.add_development_dependency 'minitest-reporters'
+  s.add_development_dependency 'rake', '~> 13'
+  s.add_development_dependency 'require-prof' unless defined?(JRUBY_VERSION) || defined?(Rubinius)
+  s.add_development_dependency 'ruby-prof'    unless defined?(JRUBY_VERSION) || defined?(Rubinius)
+  s.add_development_dependency 'simplecov', '~> 0.17', '< 0.18'
+  s.add_development_dependency 'simplecov-rcov'
+  s.add_development_dependency 'ansi'
+  s.add_development_dependency 'hashie'
+  s.add_development_dependency 'httpclient'
+  s.add_development_dependency 'manticore', '~> 0.6' if defined? JRUBY_VERSION
+  s.add_development_dependency 'mocha'
+  s.add_development_dependency 'net-http-persistent'
+  s.add_development_dependency 'patron' unless defined? JRUBY_VERSION
+  s.add_development_dependency 'pry'
+  s.add_development_dependency 'shoulda-context'
+  s.add_development_dependency 'test-unit', '~> 2'
+  s.add_development_dependency 'typhoeus', '~> 1.4'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'bundler'
 
   s.description = <<-DESC.gsub(/^    /, '')
     Ruby client for Elasticsearch. See the `elasticsearch` gem for full integration.