elasticsearch-api 7.2.0 → 8.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3106c24df61c9a6eaaab2649d67ce9b79352a3630a005dce0632df24af432bac
-  data.tar.gz: e55d31a5e5927af455c3c9094e4d2eedbff32fe7330897f7b9e5c41cb3fb78e6
+  metadata.gz: 388aa9ff6dfb05fb34b5e43b2acb1d8ce87ac5550aee779c09aa1608418e77dd
+  data.tar.gz: 1303c8b91066b97bdb69bd31d984babe97db45643e1c197e58dfc3165ea87103
 SHA512:
-  metadata.gz: f57598b93eb448b9e8ec7cbbab502b0b22bf03886ed21ffb003b01a39420f6941109d73fc31e3f4d50a71ce844170d084b790e3121141b2d7140afb4774bcd0d
-  data.tar.gz: 8cff3ba9a927a9c9bb58f86ccd836469daaa8cf1207808b157dc2b78c012b3b8a5738fb5da1359baeeaa3f22cafe694a6ae27a0f47d8228ed7a71804dc3c927f
+  metadata.gz: 9f0feb4d867eb7df2cd4d2804f92a814c07443d6033d48d396d6bc77bb2386e7e4b13cc12f31c50d0244e039f1d07c00ffc8bf9597f7a1bee966c3646749c742
+  data.tar.gz: cabae881b3f1035137168e6323d992e641eef1a9c1c52ffa9c6772ca69e0b196b0aacd5bad8ece083443a36dbbeec7767c98f27867845913bb17001df083f711

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
@@ -21,19 +21,15 @@ source 'https://rubygems.org'
 gemspec
 
 if File.exist? File.expand_path("../../elasticsearch/elasticsearch.gemspec", __FILE__)
-  gem 'elasticsearch', :path => File.expand_path("../../elasticsearch", __FILE__), :require => false
+  gem 'elasticsearch', path: File.expand_path('../../elasticsearch', __FILE__), require: false
 end
 
-if File.exist? File.expand_path("../../elasticsearch-transport", __FILE__)
-  gem 'elasticsearch-transport', :path => File.expand_path("../../elasticsearch-transport", __FILE__), :require => true
-end
-
-if File.exist? File.expand_path("../../elasticsearch-extensions", __FILE__)
-  gem 'elasticsearch-extensions', :path => File.expand_path("../../elasticsearch-extensions", __FILE__), :require => false
-end
-
-
 group :development do
   gem 'rspec'
-  gem 'pry-nav'
+  gem 'rspec_junit_formatter'
+  if defined?(JRUBY_VERSION)
+    gem 'pry-nav'
+  else
+    gem 'pry-byebug'
+  end
 end

data/README.md

@@ -9,22 +9,11 @@ The `elasticsearch-api` library provides a Ruby implementation of
 the [Elasticsearch](http://elasticsearch.com) REST API.
 
 It does not provide an Elasticsearch client; see the
-[`elasticsearch-transport`](https://github.com/elasticsearch/elasticsearch-ruby/tree/master/elasticsearch-transport) library.
+[`elasticsearch-transport`](https://github.com/elasticsearch/elasticsearch-ruby/tree/main/elasticsearch-transport) library.
 
-The library is compatible with Ruby 1.9 and higher.
+We follow Ruby’s own maintenance policy and officially support all currently maintained versions per [Ruby Maintenance Branches](https://www.ruby-lang.org/en/downloads/branches/).
 
-It is compatible with Elasticsearch's API versions from 0.90 till current,
-just use a release matching major version of Elasticsearch.
-
-| Ruby          |   | Elasticsearch |
-|:-------------:|:-:| :-----------: |
-| 0.90          | → | 0.90          |
-| 1.x           | → | 1.x           |
-| 2.x           | → | 2.x           |
-| 5.x           | → | 5.x           |
-| 6.x           | → | 6.x           |
-| 7.x           | → | 7.x           |
-| master        | → | master        |
+Language clients are forward compatible; meaning that clients support communicating with greater minor versions of Elasticsearch. Elastic language clients are also backwards compatible with lesser supported minor Elasticsearch versions.
 
 ## Installation
 
@@ -56,12 +45,12 @@ the library modules have been already included**, so you just call the API metho
 ```ruby
 require 'elasticsearch'
 
-client = Elasticsearch::Client.new log: true
+client = Elasticsearch::Client.new(log: true)
 
-client.index  index: 'myindex', type: 'mytype', id: 1, body: { title: 'Test' }
+client.index(index: 'myindex', type: 'mytype', id: 1, body: { title: 'Test' })
 # => {"_index"=>"myindex", ... "created"=>true}
 
-client.search index: 'myindex', body: { query: { match: { title: 'test' } } }
+client.search(index: 'myindex', body: { query: { match: { title: 'test' } } })
 # => {"took"=>2, ..., "hits"=>{"total":5, ...}}
 ```
 
@@ -75,12 +64,13 @@ When you want to mix the library into your own client, it must conform to a foll
 * It responds to a `perform_request(method, path, params, body, headers)` method,
 * the method returns an object with `status`, `body` and `headers` methods.
 
-A simple client could look like this:
+A simple client could look like this (_with a dependency on `active_support` to parse the query params_):
 
 ```ruby
 require 'multi_json'
 require 'faraday'
 require 'elasticsearch/api'
+require 'active_support'
 
 class MySimpleClient
   include Elasticsearch::API
@@ -92,10 +82,25 @@ class MySimpleClient
 
     CONNECTION.run_request \
       method.downcase.to_sym,
-      path,
+      path_with_params(path, params),
       ( body ? MultiJson.dump(body): nil ),
       {'Content-Type' => 'application/json'}
   end
+  
+  private
+  
+  def path_with_params(path, params)
+    return path if params.blank?
+  
+    case params
+    when String
+      "#{path}?#{params}"
+    when Hash
+      "#{path}?#{params.to_query}"
+    else
+      raise ArgumentError, "Cannot parse params: '#{params}'"
+    end
+  end
 end
 
 client = MySimpleClient.new
@@ -174,37 +179,19 @@ Elasticsearch::API.serializer.dump({foo: 'bar'})
 
 ## Development
 
-To work on the code, clone and bootstrap the main repository first --
-please see instructions in the main [README](../README.md#development).
+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 -- again, see instructions in the main [README](../README.md#development) -- 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.
+We run the test suite for Elasticsearch's Rest API tests. You can read more about this in [the test runner README](https://github.com/elastic/elasticsearch-ruby/tree/main/api-spec-testing#rest-api-yaml-test-runner).
+
+The `rest_api` needs the test files from Elasticsearch. You can run the rake task to download the test artifacts in the root folder of the project. This task needs a running cluster to determine which version and build hash of Elasticsearch to use and test against. `TEST_ES_SERVER=http://localhost:9200 rake elasticsearch:download_artifacts`. This will download the necessary files used for the integration tests to `./tmp`.
 
 ## 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
@@ -15,18 +15,11 @@
 # specific language governing permissions and limitations
 # under the License.
 
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+require 'json'
 
-def __current__
-  Pathname( File.expand_path('..', __FILE__) )
-end
-
-def git_specs(command, options={})
-  sh "git --git-dir=#{__current__.join('../tmp/elasticsearch/.git')} --work-tree=#{__current__.join('../tmp/elasticsearch')} #{command}", options
-end
-
-task(:default) { system "rake --tasks" }
-task  :test    => 'test:unit'
+task(:default) { system 'rake --tasks' }
+task test: 'test:unit'
 
 # ----- Test tasks ------------------------------------------------------------
 
@@ -34,113 +27,50 @@ require 'rake/testtask'
 require 'rspec/core/rake_task'
 
 namespace :test do
-
-  desc "Wait for Elasticsearch to be in a green state"
+  desc 'Wait for Elasticsearch to be in a green state'
   task :wait_for_green do
     sh '../scripts/wait-cluster.sh'
   end
 
+  # Unit tests - rake test:unit
+  #
+  desc 'Run unit tests'
+  task unit: :spec
   RSpec::Core::RakeTask.new(:spec) do |t|
-    t.exclude_pattern = 'spec/**{,/*/**}/rest_api_yaml_spec.rb'
-  end
-
-  RSpec::Core::RakeTask.new(:rest_api) do |t|
-    t.pattern = 'spec/**{,/*/**}/rest_api_yaml_spec.rb'
+    t.exclude_pattern = 'spec/elasticsearch/api/rest_api_yaml_spec.rb'
   end
 
-  desc "Update the repository with YAML tests"
-  task :update do
-    git_specs "fetch origin", :verbose => true
-  end
-
-  Rake::TestTask.new(:unit) do |test|
-    test.libs << 'lib' << 'test'
-    test.test_files = FileList["test/unit/**/*_test.rb"]
-    test.deps = [ :spec ]
-    # test.verbose = true
-    # test.warning = true
-  end
-
-  desc "Run integration tests"
-  task :integration => :update do
-    require 'elasticsearch'
-
-    branches = `git --git-dir=#{__current__.join('../tmp/elasticsearch/.git')} --work-tree=#{__current__.join('../tmp/elasticsearch')} branch --no-color`
-
-    current_branch = branches.
-      split("\n").
-      select { |b| b =~ /^\*/ }.
-      reject { |b| b =~ /no branch|detached/ }.
-      map    { |b| b.gsub(/^\*\s*/, '') }.
-      first
-
-    unless current_branch
-      STDERR.puts "[!] Unable to determine current branch, defaulting to 'master'"
-      current_branch = 'master'
+  namespace :platinum do
+    desc 'Run Platinum Rest API Spec tests'
+    RSpec::Core::RakeTask.new(:api) do |t|
+      ENV['TEST_SUITE'] = 'platinum'
+      Rake::Task['test:rest_api'].invoke
     end
 
-    # Check if a test cluster is running
-    begin
-      url = ENV['TEST_CLUSTER_URL'] || ENV['TEST_ES_SERVER']
-      url = "http://localhost:#{ENV['TEST_CLUSTER_PORT'] || 9250}" unless url
-      client = Elasticsearch::Client.new :url => url
-      es_version_info = client.info['version']
-      build_hash      = es_version_info['build_hash']
-      cluster_running = true
-    rescue Faraday::Error::ConnectionFailed
-      STDERR.puts "[!] Test cluster not running?"
-      cluster_running = false
+    desc 'Run Platinum Unit tests - DEPRECATED: Will be migrated to RSpec'
+    Rake::TestTask.new(:unit) do |test|
+      test.libs << 'spec/unit_tests_platinum'
+      test.test_files = FileList['spec/unit_tests_platinum/unit/**/*_test.rb']
+      test.verbose = false
+      test.warning = false
     end
+  end
 
-    checkout_specs_version = ENV['TEST_NO_CHECKOUT'].nil? ? true : false
-    checkout_build_hash    = ENV['TEST_BUILD_REF'] || build_hash
-    ENV['TEST_BUILD_REF']  = checkout_build_hash
-
-    begin
-      unless checkout_specs_version
-        STDERR.puts '-'*80, "YAML tests: Not switching, TEST_NO_CHECKOUT=y", '-'*80
-      end
-
-      if checkout_specs_version && !checkout_build_hash
-        STDERR.puts "[!] Cannot determine checkout build hash -- server not running or TEST_BUILD_REF not specified"
-        exit(1)
-      end
-
-      if checkout_specs_version && checkout_build_hash
-        # Checkout the commit corresponding to the running server build, or passed TEST_BUILD_REF
-        name = ENV['CI'] ? checkout_build_hash : "[\e[1m#{checkout_build_hash}\e[0m]"
-        STDERR.puts '-'*80, "YAML tests: Switching to #{name} from #{current_branch}", '-'*80
-        git_specs "checkout #{checkout_build_hash} --force --quiet"
-      end
-
-      Rake::Task['test:rest_api'].invoke
+  desc 'Run Rest API Spec tests'
+  RSpec::Core::RakeTask.new(:rest_api) do |t|
+    t.pattern = 'spec/elasticsearch/api/rest_api_yaml_spec.rb'
+  end
 
-    ensure
-      git_specs "checkout #{current_branch} --force --quiet" if checkout_specs_version && current_branch
-    end
+  desc 'Run integration tests'
+  task :integration do
+    Rake::Task['test:rest_api'].invoke
   end
 
-  desc "Run unit and integration tests"
+  desc 'Run unit and integration tests'
   task :all do
     Rake::Task['test:unit'].invoke
     Rake::Task['test:integration'].invoke
   end
-
-  namespace :cluster do
-    desc "Start Elasticsearch nodes for tests"
-    task :start do
-      $LOAD_PATH << File.expand_path('../../elasticsearch-transport/lib', __FILE__) << File.expand_path('../test', __FILE__)
-      require 'elasticsearch/extensions/test/cluster'
-      Elasticsearch::Extensions::Test::Cluster.start
-    end
-
-    desc "Stop Elasticsearch nodes for tests"
-    task :stop do
-      $LOAD_PATH << File.expand_path('../../elasticsearch-transport/lib', __FILE__) << File.expand_path('../test', __FILE__)
-      require 'elasticsearch/extensions/test/cluster'
-      Elasticsearch::Extensions::Test::Cluster.stop
-    end
-  end
 end
 
 # ----- Documentation tasks ---------------------------------------------------
@@ -152,10 +82,8 @@ end
 
 # ----- Code analysis tasks ---------------------------------------------------
 
-if defined?(RUBY_VERSION) && RUBY_VERSION > '1.9'
-  require 'cane/rake_task'
-  Cane::RakeTask.new(:quality) do |cane|
-    cane.abc_max = 15
-    cane.no_style = true
-  end
+require 'cane/rake_task'
+Cane::RakeTask.new(:quality) do |cane|
+  cane.abc_max = 15
+  cane.no_style = true
 end

data/api-spec-testing/README.md

@@ -0,0 +1,118 @@
+# Rest API YAML Test Runner
+
+The specs in `elasticsearch-api` automatically run the tests from [Elasticsearch's REST API Spec tests](https://github.com/elastic/elasticsearch/tree/main/rest-api-spec/src/main/resources/rest-api-spec/test#test-suite). The test runner is defined in the `spec` folder, starting with the `rest_api_yaml_spec.rb` file.
+
+You can run the tests with Rake. The main task is `rake test:rest_api`. This task will evaluate the `TEST_SUITE` environment variable. It will run either the `free` or `platinum` tests suites depending on the value of `TEST_SUITE`. If you don't set this value, the task will run the `free` test suite by default. To run the `platinum` test suite use:
+```
+TEST_SUITE=platinum rake test:rest_api
+```
+
+Or the shortcut:
+```
+rake test:platinum:api
+```
+
+## REST API YAML Spec
+
+The file that traverses the yaml files and loads a **TestFile** object per each of them:
+`elasticsearch-api/spec/elasticsearch/api/rest_api_yaml_spec.rb`
+
+You can use the SINGLE_TEST env variable to run just one test or one test directory. E.g.:
+```
+$ cd elasticsearch-api && SINGLE_TEST=indices.resolve_index/10_basic_resolve_index.yml TEST_ES_SERVER='http://localhost:9200' be rake test:rest_api
+```
+And:
+```
+$ cd elasticsearch-api && SINGLE_TEST=indices.resolve_index TEST_ES_SERVER='http://localhost:9200' be rake test:rest_api
+```
+
+## Skipped tests
+
+We sometimes skip tests, generally due to limitations on how we run the CI server or for stuff that hasn't been completely implemented on the client yet. Skipped tests are located in `elasticsearch-api/spec/skipped_tests.yml`. You can run just the tests which are currently being skipped by running:
+```
+$ cd elasticsearch-api && TEST_SUITE=(free|platinum) RUN_SKIPPED_TESTS=true TEST_ES_SERVER='http://localhost:9200' be rake test:rest_api
+```
+
+## TestFile
+Class representing a single test file. Contains setup, teardown and tests.   
+`../api-spec-testing/test_file.rb`
+
+## Test
+Every single test in the test file is represented in the Test object.   
+`../api-spec-testing/test_file/test.rb`
+
+## TaskGroup
+
+Tests are ordered in task groups, an array of TaskGroup objects.  
+`../api-spec-testing/test_file/task_group.rb`
+
+Task Groups are a representation of a block of actions consisting of 'do' actions and their verifications. e.g.: 
+```yaml
+ - do:
+      index:
+          index:  test-index
+          id:     1
+          body:   { foo: bar }
+
+ - match:   { _index:   test-index }
+ - match:   { _id:      "1"}
+ - match:   { _version: 1}
+```
+
+**Before** each test, the spec runner runs `clear_data` on the test_file. This clears indices, index templates, snapshots and repositories. For platinum it also clears roles, users, privileges, datafeeds, ml_jobs and more.
+
+**After** each test, it runs the test file teardown and `clear_data` again.
+
+For each TaskGroup, it sees what's in the task group definition and runs an expectation test.
+
+## Action
+
+This file is where the action is executed, where we call the client with the method from the test and save the response which is then used in the task group.
+
+## Rest YAML tests Helper
+
+`elasticsearch-api/spec/rest_yaml_tests_helper.rb`
+
+- `ADMIN_CLIENT` is defined here.
+- `SINGLE_TEST` is defined here.
+- Skipped tests are listed here
+
+## Spec Helper
+
+- `DEFAULT_CLIENT` is defined here
+
+## Enable Logging
+
+To enable logging, set the environment `QUIET` to false before running the tests. In CI, this is located in the [Dockerfile](https://github.com/elastic/elasticsearch-ruby/blob/main/.ci/Dockerfile). The environment variable is evaluated in the Rest YAML tests Helper file.
+
+# Features
+
+## RSpec Matchers
+
+The tests use custom [RSpec Matchers](https://www.rubydoc.info/gems/rspec-expectations/RSpec/Matchers) defined in `api-spec-testing/rspec_matchers.rb`.
+
+From the [Rest API test docs](https://github.com/elastic/elasticsearch/tree/master/rest-api-spec/src/main/resources/rest-api-spec/test#do):
+
+## `catch`
+
+> If the arguments to `do` include `catch`, then we are expecting an error, which should be caught and tested.
+
+In `rest_api_yaml_spec`, there's a check for `catch_exception?` per task_group. This checks if the `do` definitions have any `catch` definitions. If there is a `catch`, it'll send the request and use the `match_error` RSpec custom matcher to validate the expected error.
+
+## `warnings`
+
+>If the arguments to `do` include `warnings` then we are expecting a Warning header to come back from the request. If the arguments don’t include a warnings argument then we don’t expect the response to include a Warning header. The warnings must match exactly. Using it looks like this:
+
+```
+- do:
+    warnings:
+        - '[index] is deprecated'
+        - quotes are not required because yaml
+        - but this argument is always a list, never a single string
+        - no matter how many warnings you expect
+    get:
+        index:    test
+        type:    test
+        id:        1
+```
+

data/api-spec-testing/logging.rb

@@ -0,0 +1,28 @@
+# 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 'logger'
+
+module Elasticsearch
+  module RestAPIYAMLTests
+    module Logging
+      def logger
+        @logger ||= Logger.new($stdout)
+      end
+    end
+  end
+end