opensearch-api 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 120d26d2c00900982e0318694e71ac6ad804b2f19ffe11539005b69eadf9775f
-  data.tar.gz: 5beaf8317d9f30aedf3b05765f518cd7d2bb853192c0d7fc7ab86747fd1e8aad
+  metadata.gz: 832f3792a1ba90a36107ed481ce4a8d312788f0cc6d2499010fbb83f75310b3f
+  data.tar.gz: 8cd92be697d977c3e7dbb8e968f89c5e65c72d8780b825db470ae902a0a8fa4e
 SHA512:
-  metadata.gz: daea96255b4d9a9ae424b03bb6ee49e1d6a62bc1a11e4cffcf50359e640350b22f37f0aa37ff5ed1fe069c1c5a313c2504e4b077308c6b19af3c34a4bff8898b
-  data.tar.gz: e2aff66e8cfad49e553e708a5f77e0ad100e1d601006f4a9987901782ddb22e586c06cb125b14db9ca65defdfa50cd903c935b5d0a7abe6420408544d5bcb353
+  metadata.gz: 9af645120326fb0d4a4b3afe5dd063356c54eb02b4a813c2d3a86a6ffa4add32ec7c31291ade794d1fa4a229a6294d0882b58b92310746a783d170bd07c5147e
+  data.tar.gz: 65efd59ac74703fd6d6daf9ff04744e46cd962111821a6d9ede0653308c4563aa9171b0d6afb36e050e33a0bc56b8aff78358a1311d0743a1701ff661cfedc99

data/.gitignore

@@ -3,6 +3,7 @@
 .bundle
 .config
 .yardoc
+.ruby-version
 Gemfile.lock
 InstalledFiles
 _yardoc

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# CHANGELOG
+Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+
+## [Unreleased]
+### Added
+### Changed
+### Deprecated
+### Removed
+### Fixed
+### Security
+
+## [2.2.0]
+### Added
+- Added Point-In-Time API ([#136](https://github.com/opensearch-project/opensearch-ruby/issues/136))
+### Changed
+### Deprecated
+### Removed
+- Removed Legacy X-Pack Point-In-Time API ([#136](https://github.com/opensearch-project/opensearch-ruby/issues/136))
+### Fixed
+### Security
+
+## 2.1.0
+### Changed
+- Update comments around deprecated and inclusive naming ([#112](https://github.com/opensearch-project/opensearch-ruby/pull/112))
+### Removed
+- Remove deprecated escape_utils ([#74](https://github.com/opensearch-project/opensearch-ruby/pull/74))
+### Fixed
+- Fixing tests related to escape utils latest version ([#73](https://github.com/opensearch-project/opensearch-ruby/pull/73))

data/README.md

@@ -1,193 +1,23 @@
-# OpenSearch::API
-
-**This library is part of the [`opensearch-ruby`](https://github.com/opensearch-project/opensearch-ruby/) package;
-please refer to it, unless you want to use this library standalone.**
-
-----
-
-The `opensearch-api` library provides a Ruby implementation of
-the [OpenSearch](http://opensearch.com) REST API.
-
-It does not provide an OpenSearch client; see the
-[`opensearch-transport`](https://github.com/opensearch-project/opensearch-ruby/tree/main/opensearch-transport) library.
-
-The library is compatible with Ruby 1.9 and higher.
-
-It is compatible with OpenSearch's API versions from 1.0.0 till current.
-
-## Installation
-
-Install the package from [Rubygems](https://rubygems.org):
-
-    gem install opensearch-api
-
-To use an unreleased version, either add it to your `Gemfile` for [Bundler](http://gembundler.com):
-
-    gem 'opensearch-api', git: 'git://github.com/opensearch-project/opensearch-ruby.git'
-
-or install it from a source code checkout:
-
-    git clone https://github.com/opensearch-project/opensearch-ruby
-    cd opensearch-ruby/opensearch-api
-    bundle install
-    rake install
-
-## Usage
-
-The library is designed as a group of standalone Ruby modules, which can be mixed into a class
-providing connection to OpenSearch -- an OpenSearch client.
-
-### Usage with the `opensearch` gem
-
-**When you use the client from the [`opensearch-ruby`](https://github.com/opensearch-project/opensearch-ruby/) package,
-the library modules have been already included**, so you just call the API methods:
-
-```ruby
-require 'opensearch'
-
-client = OpenSearch::Client.new(log: true)
-
-client.index(index: 'myindex', id: 1, body: { title: 'Test' })
-# => {"_index"=>"myindex", ... "created"=>true}
-
-client.search(index: 'myindex', body: { query: { match: { title: 'test' } } })
-# => {"took"=>2, ..., "hits"=>{"total":5, ...}}
-```
-
-### Usage with a custom client
-
-When you want to mix the library into your own client, it must conform to a following _contract_:
-
-* It responds to a `perform_request(method, path, params, body, headers)` method,
-* the method returns an object with `status`, `body` and `headers` methods.
+- [OpenSearch::API](#opensearchapi)
+  - [Compatibility](#compatibility)
+  - [User Guide](#user-guide)
+  - [License](#license)
 
-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 'opensearch/api'
-require 'active_support'
-
-class MySimpleClient
-  include OpenSearch::API
-
-  CONNECTION = ::Faraday::Connection.new url: 'http://localhost:9200'
-
-  def perform_request(method, path, params, body, headers = nil)
-    puts "--> #{method.upcase} #{path} #{params} #{body} #{headers}"
-
-    CONNECTION.run_request \
-      method.downcase.to_sym,
-      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
-
-p client.cluster.health
-# --> GET _cluster/health {}
-# => "{"cluster_name":"opensearch" ... }"
-
-p client.index index: 'myindex', id: 'custom', body: { title: "Indexing from my client" }
-# --> PUT myindex/mytype/custom {} {:title=>"Indexing from my client"}
-# => "{"ok":true, ... }"
-```
-
-### Using JSON Builders
-
-Instead of passing the `:body` argument as a Ruby _Hash_, you can pass it as a _String_, potentially
-taking advantage of JSON builders such as [JBuilder](https://github.com/rails/jbuilder) or
-[Jsonify](https://github.com/bsiggelkow/jsonify):
-
-```ruby
-require 'jbuilder'
-
-query = Jbuilder.encode do |json|
-  json.query do
-    json.match do
-      json.title do
-        json.query    'test 1'
-        json.operator 'and'
-      end
-    end
-  end
-end
-
-client.search index: 'myindex', body: query
-
-# 2013-06-25 09:56:05 +0200: GET http://localhost:9200/myindex/_search [status:200, request:0.015s, query:0.011s]
-# 2013-06-25 09:56:05 +0200: > {"query":{"match":{"title":{"query":"test 1","operator":"and"}}}}
-# ...
-# => {"took"=>21, ..., "hits"=>{"total"=>1, "hits"=>[{ "_source"=>{"title"=>"Test 1", ...}}]}}
-```
-
-### Using Hash Wrappers
-
-For a more comfortable access to response properties, you may wrap it in one of the _Hash_ "object access"
-wrappers, such as [`Hashie::Mash`](https://github.com/intridea/hashie):
-
-```ruby
-require 'hashie'
-
-response = client.search index: 'myindex',
-                         body: {
-                           query: { match: { title: 'test' } },
-                           aggregations: { tags: { terms: { field: 'tags' } } }
-                         }
-
-mash = Hashie::Mash.new response
-
-mash.hits.hits.first._source.title
-# => 'Test'
-
-mash.aggregations.tags.terms.first
-# => #<Hashie::Mash count=3 term="z">
-```
-
-### Using a Custom JSON Serializer
-
-The library uses the [MultiJson](https://rubygems.org/gems/multi_json/) gem by default,
-but allows you to set a custom JSON library, provided it uses the standard `load/dump`
-interface:
+# OpenSearch::API
 
-```ruby
-OpenSearch::API.settings[:serializer] = JrJackson::Json
-OpenSearch::API.serializer.dump({foo: 'bar'})
-# => {"foo":"bar"}
-```
+**This library is part of the [`opensearch-ruby`](https://github.com/opensearch-project/opensearch-ruby/) package; please refer to the [USER_GUIDE](../USER_GUIDE.md), unless you want to use this library standalone.**
 
-## Development
+The `opensearch-api` library provides a Ruby implementation of the OpenSearch REST APIs.
 
-To work on the code, clone and bootstrap the main repository first -- please see instructions in the main [README](../README.md#development).
+It does not provide an OpenSearch client; see the [`opensearch-transport`](https://github.com/opensearch-project/opensearch-ruby/tree/main/opensearch-transport) library.
 
-To run tests, launch a testing cluster -- again, see instructions in the main [README](../README.md#development) -- and use the Rake tasks:
+## Compatibility
 
-```
-time rake test:unit
-time rake test:integration
-```
+See [COMPATIBILITY](../COMPATIBILITY.md).
 
-We run the test suite for OpenSearch's Rest API tests.
+## User Guide
 
-The `rest_api` needs the test files from OpenSearch. 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 OpenSearch to use and test against. `TEST_OPENSEARCH_SERVER=http://localhost:9200 rake opensearch:download_artifacts`. This will download the necessary files used for the integration tests to `./tmp`.
+See [USER_GUIDE](USER_GUIDE.md).
 
 ## License
 

data/Rakefile

@@ -88,7 +88,7 @@ namespace :test do
     filename = 'tmp/artifacts.json'
     `curl -s <placeholder_opensearch_artifact_url> -o #{filename}`
 
-    unless File.exists?("./#{filename}")
+    unless File.exist?("./#{filename}")
       STDERR.puts '[!] Couldn\'t download artifacts file'
       exit 1
     end
@@ -105,7 +105,7 @@ namespace :test do
     puts 'Downloading zip file:'
     `curl -s #{zip_url} -o tmp/#{filename}`
 
-    unless File.exists?("./tmp/#{filename}")
+    unless File.exist?("./tmp/#{filename}")
       STDERR.puts '[!] Couldn\'t download artifact'
       exit 1
     end

data/USER_GUIDE.md

@@ -0,0 +1,155 @@
+- [User Guide](#user-guide)
+  - [Installation](#installation)
+  - [Usage](#usage)
+    - [Usage with a custom client](#usage-with-a-custom-client)
+    - [Using JSON Builders](#using-json-builders)
+    - [Using Hash Wrappers](#using-hash-wrappers)
+    - [Using a Custom JSON Serializer](#using-a-custom-json-serializer)
+  - [Development](#development)
+
+# User Guide
+## Installation
+
+To add the gem to your project, install it using [RubyGems](https://rubygems.org/):
+
+```
+gem install opensearch-api
+```
+
+or add it to your Gemfile:
+```
+gem opensearch-api
+```
+and run:
+```
+bundle install
+```
+
+## Usage
+
+The library is designed as a group of standalone Ruby modules, which can be mixed into a class providing connection to OpenSearch -- an OpenSearch client.
+
+### Usage with a custom client
+
+To use the library with a custom client, it must conform to a following _contract_:
+
+* 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 (_with a dependency on `active_support` to parse the query params_):
+
+```ruby
+require 'multi_json'
+require 'faraday'
+require 'opensearch/api'
+require 'active_support'
+
+class MySimpleClient
+  include OpenSearch::API
+
+  CONNECTION = ::Faraday::Connection.new url: 'http://localhost:9200'
+
+  def perform_request(method, path, params, body, headers = nil)
+    puts "--> #{method.upcase} #{path} #{params} #{body} #{headers}"
+
+    CONNECTION.run_request \
+      method.downcase.to_sym,
+      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
+
+p client.cluster.health
+
+p client.index index: 'myindex', id: 'custom', body: { title: "Indexing from my client" }
+```
+
+### Using JSON Builders
+
+Instead of passing the `:body` argument as a Ruby _Hash_, you can pass it as a _String_, potentially taking advantage of JSON builders such as [JBuilder](https://github.com/rails/jbuilder) or [Jsonify](https://github.com/bsiggelkow/jsonify):
+
+```ruby
+require 'jbuilder'
+
+query = Jbuilder.encode do |json|
+  json.query do
+    json.match do
+      json.title do
+        json.query    'test 1'
+        json.operator 'and'
+      end
+    end
+  end
+end
+
+client.search index: 'myindex', body: query
+# 2013-06-25 09:56:05 +0200: GET http://localhost:9200/myindex/_search [status:200, request:0.015s, query:0.011s]
+# 2013-06-25 09:56:05 +0200: > {"query":{"match":{"title":{"query":"test 1","operator":"and"}}}}
+# ...
+# => {"took"=>21, ..., "hits"=>{"total"=>1, "hits"=>[{ "_source"=>{"title"=>"Test 1", ...}}]}}
+```
+
+### Using Hash Wrappers
+
+For a more comfortable access to response properties, you may wrap it in one of the _Hash_ "object access" wrappers, such as [`Hashie::Mash`](https://github.com/intridea/hashie):
+
+```ruby
+require 'hashie'
+
+response = client.search index: 'myindex',
+                         body: {
+                           query: { match: { title: 'test' } },
+                           aggregations: { tags: { terms: { field: 'tags' } } }
+                         }
+
+mash = Hashie::Mash.new response
+
+mash.hits.hits.first._source.title
+# => 'test'
+
+mash.aggregations.tags.terms.first
+# => #<Hashie::Mash count=3 term="z">
+```
+
+### Using a Custom JSON Serializer
+
+The library uses the [MultiJson](https://rubygems.org/gems/multi_json/) gem by default, but allows you to set a custom JSON library, provided it uses the standard `load/dump` interface:
+
+```ruby
+OpenSearch::API.settings[:serializer] = JrJackson::Json
+OpenSearch::API.serializer.dump({foo: 'bar'})
+# => {"foo":"bar"}
+```
+
+## Development
+
+To work on the code, clone and bootstrap the main repository first -- please see instructions in the main [DEVELOPER_GUIDE](../DEVELOPER_GUIDE.md).
+
+To run tests:
+
+```
+time rake test:unit
+time rake test:integration
+```
+
+We run the test suite for OpenSearch's Rest API tests.
+
+The `rest_api` needs the test files from OpenSearch. 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 OpenSearch to use and test against. `TEST_OPENSEARCH_SERVER=http://localhost:9200 rake opensearch:download_artifacts`. This will download the necessary files used for the integration tests to `./tmp`.

data/lib/opensearch/api/actions/cat/all_pit_segments.rb

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# The OpenSearch Contributors require contributions made to
+# this file be licensed under the Apache-2.0 license or a
+# compatible open source license.
+#
+# Modifications Copyright OpenSearch Contributors. See
+# GitHub history for details.
+
+module OpenSearch
+  module API
+    module Cat
+      module Actions
+        # Retrieves info of all PIT segments
+        #
+        # @option arguments [String] :format a short version of the Accept header, e.g. json, yaml
+        # @option arguments [List] :h Comma-separated list of column names to display
+        # @option arguments [Boolean] :help Return help information
+        # @option arguments [List] :s Comma-separated list of column names or column aliases to sort by
+        # @option arguments [Boolean] :v Verbose mode. Display column headers
+        # @option arguments [Hash] :headers Custom HTTP headers
+        def all_pit_segments(arguments = {})
+          arguments = arguments.clone
+          headers = arguments.delete(:headers) || {}
+
+
+          method = OpenSearch::API::HTTP_GET
+          path   = '_cat/pit_segments/_all'
+          params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
+          params[:h] = Utils.__listify(params[:h]) if params[:h]
+
+          body = nil
+          perform_request(method, path, params, body, headers).body
+        end
+
+        ParamsRegistry.register(:all_pit_segments, [
+          :format,
+          :h,
+          :help,
+          :s,
+          :v
+        ].freeze)
+      end
+    end
+  end
+end

data/lib/opensearch/api/actions/cat/pit_segments.rb

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# The OpenSearch Contributors require contributions made to
+# this file be licensed under the Apache-2.0 license or a
+# compatible open source license.
+#
+# Modifications Copyright OpenSearch Contributors. See
+# GitHub history for details.
+
+module OpenSearch
+  module API
+    module Cat
+      module Actions
+        # Retrieves info of certain PIT segments
+        #
+        # @option arguments [Hash] body: Must include `pit_id`, which is an array of PIT IDs. (required)
+        # @option arguments [String] :format a short version of the Accept header, e.g. json, yaml
+        # @option arguments [List] :h Comma-separated list of column names to display
+        # @option arguments [Boolean] :help Return help information
+        # @option arguments [List] :s Comma-separated list of column names or column aliases to sort by
+        # @option arguments [Boolean] :v Verbose mode. Display column headers
+        # @option arguments [Hash] :headers Custom HTTP headers
+        def pit_segments(arguments = {})
+          raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]
+
+          arguments = arguments.clone
+          headers = arguments.delete(:headers) || {}
+
+
+          method = OpenSearch::API::HTTP_GET
+          path   = '_cat/pit_segments'
+          params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
+          params[:h] = Utils.__listify(params[:h]) if params[:h]
+
+          body = arguments[:body]
+          perform_request(method, path, params, body, headers).body
+        end
+
+        ParamsRegistry.register(:pit_segments, [
+          :format,
+          :h,
+          :help,
+          :s,
+          :v
+        ].freeze)
+      end
+    end
+  end
+end

data/lib/opensearch/api/actions/create_pit.rb

@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# The OpenSearch Contributors require contributions made to
+# this file be licensed under the Apache-2.0 license or a
+# compatible open source license.
+#
+# Modifications Copyright OpenSearch Contributors. See
+# GitHub history for details.
+
+module OpenSearch
+  module API
+    module Actions
+      # Creates a point in time.
+      #
+      # @option arguments [String] :index The name(s) of the target index(es) for the PIT. May contain a comma-separated list or a wildcard index pattern. (required)
+      # @option arguments [String] :keep_alive The amount of time to keep the PIT. (required)
+      # @option arguments [String] :preference The node or the shard used to perform the search. (default: random)
+      # @option arguments [String] :routing Specifies to route search requests to a specific shard.
+      # @option arguments [String] :expand_wildcards The type of index that can match the wildcard pattern. Supports comma-separated values. (default: open)
+      # @option arguments [String] :allow_partial_pit_creation Specifies whether to create a PIT with partial failures. (default: false)
+      def create_pit(arguments = {})
+        raise ArgumentError, "Required argument 'index' missing" unless arguments[:index]
+        raise ArgumentError, "Required argument 'keep_alive' missing" unless arguments[:keep_alive]
+
+        arguments = arguments.clone
+        _index = arguments.delete(:index)
+
+        method = OpenSearch::API::HTTP_POST
+        path = "#{Utils.__listify(_index)}/_search/point_in_time"
+        params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
+        body = nil
+
+        perform_request(method, path, params, body).body
+      end
+
+      ParamsRegistry.register(:create_pit, [
+        :keep_alive,
+        :preference,
+        :routing,
+        :expand_wildcards,
+        :allow_partial_pit_creation
+      ].freeze)
+    end
+  end
+end

data/lib/opensearch/api/actions/delete_all_pits.rb

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# The OpenSearch Contributors require contributions made to
+# this file be licensed under the Apache-2.0 license or a
+# compatible open source license.
+#
+# Modifications Copyright OpenSearch Contributors. See
+# GitHub history for details.
+
+module OpenSearch
+  module API
+    module Actions
+      # Deletes all PITs.
+      def delete_all_pits(arguments = {})
+        method = OpenSearch::API::HTTP_DELETE
+        path = "_search/point_in_time/_all"
+        params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
+        body = nil
+
+        perform_request(method, path, params, body).body
+      end
+
+      ParamsRegistry.register(:delete_all_pits, [].freeze)
+    end
+  end
+end

data/lib/opensearch/api/actions/delete_pit.rb

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# The OpenSearch Contributors require contributions made to
+# this file be licensed under the Apache-2.0 license or a
+# compatible open source license.
+#
+# Modifications Copyright OpenSearch Contributors. See
+# GitHub history for details.
+
+module OpenSearch
+  module API
+    module Actions
+      # Deletes one or several PITs.
+      #
+      # @option arguments [Hash] body: Must include `pit_id`, which is an array of PIT IDs to be deleted. (required)
+      def delete_pit(arguments = {})
+        raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]
+
+        method = OpenSearch::API::HTTP_DELETE
+        path = "_search/point_in_time"
+        params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
+        body = arguments[:body]
+
+        perform_request(method, path, params, body).body
+      end
+
+      ParamsRegistry.register(:delete_pit, [].freeze)
+    end
+  end
+end

data/lib/opensearch/api/actions/get_all_pits.rb

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# The OpenSearch Contributors require contributions made to
+# this file be licensed under the Apache-2.0 license or a
+# compatible open source license.
+#
+# Modifications Copyright OpenSearch Contributors. See
+# GitHub history for details.
+
+module OpenSearch
+  module API
+    module Actions
+      # Gets all PITs.
+      def get_all_pits(arguments = {})
+        method = OpenSearch::API::HTTP_GET
+        path = "_search/point_in_time/_all"
+        params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
+        body = nil
+
+        perform_request(method, path, params, body).body
+      end
+
+      ParamsRegistry.register(:get_all_pits, [].freeze)
+    end
+  end
+end

data/lib/opensearch/api/version.rb

@@ -26,6 +26,6 @@
 
 module OpenSearch
   module API
-    VERSION = '2.1.0'.freeze
+    VERSION = '2.2.0'.freeze
   end
 end