elasticsearch-transport 7.4.0 → 7.17.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f792f084ecb5b37684ed211a3ffc92db1bda2f7bf86bc6e24502d11eb4c3d01f
-  data.tar.gz: 3816c9f77491b8984b5041d4b83afb8a2fc64212f6fa3e3f9ea05058fe3d3910
+  metadata.gz: 9e0c37098be528ebc37efec244285f3601ba8251c355195d5d64b5d3d6146b01
+  data.tar.gz: 7dd46af46b3ae346e4f76a6f8cae669e27964cddd8cd9e91ca4329cf34f8fb74
 SHA512:
-  metadata.gz: 83232686c134cfb686d8ab8e9103da88f8b08a64661c103aeecede0c7cbfacdd80b668dfa67ad93b2b5f035865ce7ae125db0ce1e1ce6bd6a32ff7c9133d5c83
-  data.tar.gz: 59f44c2691078611f06b01593a74c61bbab87f055c4d7f3ae5249a7dfebd581fb37660babffb352c88db1d8bd6ffcefe6f73519019474e6d64037c09e42e421f
+  metadata.gz: 7c1d381899e45182eb000f45f1e014c2944741f817276424cefcbce05e26878da524ecc0c8d64c2dba3b290e755b30a7428b11fb6d65fd417528d92007418ed6
+  data.tar.gz: f2639368b74d2884376420cccb89e591dae6ecbfdc4632224d1f073ba34000ea54c498e5cb6256a60dda8f9a9a02a218158fbef64d62e1b6118b13b6912a2334

data/Gemfile

@@ -1,25 +1,42 @@
-# 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
+# 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.
 
 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', __dir__)
+  gem 'elasticsearch-api', path: File.expand_path('../elasticsearch-api', __dir__), 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/elasticsearch.gemspec', __dir__)
+  gem 'elasticsearch', path: File.expand_path('../elasticsearch', __dir__), require: false
 end
 
-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 'faraday-httpclient'
+  gem 'faraday-net_http_persistent'
+  gem 'faraday-patron' unless defined? JRUBY_VERSION
+  gem 'faraday-typhoeus'
   gem 'rspec'
-  gem 'pry-nav'
+  if defined?(JRUBY_VERSION)
+    gem 'pry-nav'
+  else
+    gem 'pry-byebug', '~> 3.9'
+  end
 end

data/Gemfile-faraday1.gemfile

@@ -0,0 +1,47 @@
+# 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.
+
+source 'https://rubygems.org'
+
+# Usage:
+#
+# $ BUNDLE_GEMFILE=./Gemfile-faraday1.gemfile bundle install
+# $ BUNDLE_GEMFILE=./Gemfile-faraday1.gemfile bundle exec rake test:faraday1:unit
+
+gem 'faraday', '~> 1'
+gemspec path: './'
+
+if File.exist? File.expand_path('../elasticsearch-api/elasticsearch-api.gemspec', __dir__)
+  gem 'elasticsearch-api', path: File.expand_path('../elasticsearch-api', __dir__), require: false
+end
+
+if File.exist? File.expand_path('../elasticsearch/elasticsearch.gemspec', __dir__)
+  gem 'elasticsearch', path: File.expand_path('../elasticsearch', __dir__), require: false
+end
+
+group :development, :test do
+  gem 'httpclient'
+  gem 'net-http-persistent'
+  gem 'patron' unless defined? JRUBY_VERSION
+  gem 'typhoeus'
+  gem 'rspec'
+  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.
 
@@ -115,7 +136,7 @@ Please see below for an exception to this when connecting using an Elastic Cloud
 
 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 9243 will be used.
+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.
@@ -144,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:
 
-    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
 
-    log = Logging.logger['elasticsearch']
-    log.add_appenders Logging.appenders.stdout
-    log.level = :info
+You can set a custom HTTP header on the client's initializer:
 
-    client = Elasticsearch::Client.new logger: log
+```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:
+
+```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
+```
+
+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
 
@@ -199,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
@@ -268,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:
 
@@ -308,44 +417,32 @@ 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/):
+You can use any standard Faraday middleware and plugins in the configuration block. You can also initialize the transport class yourself, and pass it to the client constructor as the `transport` argument:
 
-    require 'faraday_middleware/aws_signers_v4'
+```ruby
+require 'patron'
 
-    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 also initialize the transport class yourself, and pass it to the client constructor
-as the `transport` argument:
+transport_configuration = lambda do |f|
+  f.response :logger
+  f.adapter  :patron
+end
 
-    require 'typhoeus'
-    require 'typhoeus/adapters/faraday'
+transport = Elasticsearch::Transport::Transport::HTTP::Faraday.new \
+  hosts: [ { host: 'localhost', port: '9200' } ],
+  &transport_configuration
 
-    transport_configuration = lambda do |f|
-      f.response :logger
-      f.adapter  :typhoeus
-    end
-
-    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:
 
@@ -461,16 +558,14 @@ Github's pull requests and issues are used to communicate, send bug reports and
 To work on the code, clone and bootstrap the main repository first --
 please see instructions in the main [README](../README.md#development).
 
-To run tests, launch a testing cluster -- again, see instructions
-in the main [README](../README.md#development) -- and use the Rake tasks:
+To run tests, launch a testing cluster and use the Rake tasks:
 
 ```
 time rake test:unit
 time rake test:integration
 ```
 
-Unit tests have to use Ruby 1.8 compatible syntax, integration tests
-can use Ruby 2.x syntax and features.
+Use `COVERAGE=true` before running a test task to check coverage with Simplecov.
 
 ## License
 

data/Rakefile

@@ -1,6 +1,19 @@
-# 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
+# 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.
 
 require "bundler/gem_tasks"
 
@@ -12,40 +25,77 @@ task :test    => 'test:unit'
 
 require 'rake/testtask'
 require 'rspec/core/rake_task'
+FARADAY1_GEMFILE = 'Gemfile-faraday1.gemfile'.freeze
+GEMFILES = ['Gemfile', FARADAY1_GEMFILE].freeze
 
-namespace :test do
+task :install do
+  GEMFILES.each do |gemfile|
+    gemfile = File.expand_path("../#{gemfile}", __FILE__)
+    sh "bundle install --gemfile #{gemfile}"
+  end
+end
 
-  desc "Wait for Elasticsearch to be in a green state"
+namespace :test do
+  desc 'Wait for Elasticsearch to be in a green state'
   task :wait_for_green do
     sh '../scripts/wait-cluster.sh'
   end
 
-  task :spec => :wait_for_green
   RSpec::Core::RakeTask.new(:spec)
 
   Rake::TestTask.new(:unit) do |test|
     test.libs << 'lib' << 'test'
-    test.test_files = FileList["test/unit/**/*_test.rb"]
+    test.test_files = FileList['test/unit/**/*_test.rb']
     test.verbose = false
     test.warning = false
   end
 
   Rake::TestTask.new(:integration) do |test|
     test.libs << 'lib' << 'test'
-    test.test_files = FileList["test/integration/**/*_test.rb"]
-    test.deps = [ 'test:wait_for_green', 'test:spec' ]
+    test.test_files = FileList['test/integration/**/*_test.rb']
+    test.deps = ['test:wait_for_green', 'test:spec']
     test.verbose = false
     test.warning = false
   end
 
-  Rake::TestTask.new(:all) do |test|
-    test.libs << 'lib' << 'test'
-    test.test_files = FileList["test/unit/**/*_test.rb", "test/integration/**/*_test.rb"]
+  desc 'Run all tests'
+  task :all do
+    Rake::Task['test:unit'].invoke
+    Rake::Task['test:spec'].invoke
+    Rake::Task['test:integration'].invoke
   end
 
   Rake::TestTask.new(:profile) do |test|
     test.libs << 'lib' << 'test'
-    test.test_files = FileList["test/profile/**/*_test.rb"]
+    test.test_files = FileList['test/profile/**/*_test.rb']
+  end
+
+  namespace :faraday1 do
+    desc 'Faraday 1: Run RSpec with dependency on Faraday 1'
+    task :spec do
+      sh "BUNDLE_GEMFILE=#{FARADAY1_GEMFILE} bundle exec rspec"
+    end
+
+    desc 'Faraday 1: Run unit tests with dependency on Faraday 1'
+    task :unit do
+      Dir.glob('./test/unit/**/**.rb').each do |test|
+        sh "BUNDLE_GEMFILE=#{FARADAY1_GEMFILE} ruby -Ilib:test #{test}"
+      end
+    end
+
+    desc 'Faraday 1: Run integration tests with dependency on Faraday 1'
+    task :integration do
+      Dir.glob('./test/integration/**/**.rb').each do |test|
+        sh "BUNDLE_GEMFILE=#{FARADAY1_GEMFILE} ruby -Ilib:test #{test}"
+      end
+    end
+
+    desc 'Faraday 1: Run all tests'
+    task :all do
+      Rake::Task['test:faraday1:unit'].invoke
+      Rake::Task['test:faraday1:spec'].invoke
+      Rake::Task['test:faraday1:integration'].invoke
+    end
   end
 
   namespace :cluster do