opensearch-api 1.0.0

data/lib/opensearch/api/utils.rb

@@ -0,0 +1,297 @@
+# 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.
+#
+# 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.
+
+module OpenSearch
+  module API
+
+    # Generic utility methods
+    #
+    module Utils
+
+      # URL-escape a string
+      #
+      # @example
+      #     __escape('foo/bar') # => 'foo%2Fbar'
+      #     __escape('bar^bam') # => 'bar%5Ebam'
+      #
+      # @api private
+      def __escape(string)
+        return string if string == '*'
+        defined?(EscapeUtils) ? EscapeUtils.escape_url(string.to_s) : CGI.escape(string.to_s)
+      end
+
+      # Create a "list" of values from arguments, ignoring nil values and encoding special characters.
+      #
+      # @example Create a list from array
+      #     __listify(['A','B']) # => 'A,B'
+      #
+      # @example Create a list from arguments
+      #     __listify('A','B') # => 'A,B'
+      #
+      # @example Escape values
+      #     __listify('foo','bar^bam') # => 'foo,bar%5Ebam'
+      #
+      # @example Do not escape the values
+      #     __listify('foo','bar^bam', escape: false) # => 'foo,bar^bam'
+      #
+      # @api private
+      def __listify(*list)
+        options = list.last.is_a?(Hash) ? list.pop : {}
+
+        escape = options[:escape]
+        Array(list).
+          flat_map { |e| e.respond_to?(:split) ? e.split(',') : e }.
+          flatten.
+          compact.
+          map { |e| escape == false ? e : __escape(e) }.
+          join(',')
+      end
+
+      # Create a path (URL part) from arguments, ignoring nil values and empty strings.
+      #
+      # @example Create a path from array
+      #     __pathify(['foo', '', nil, 'bar']) # => 'foo/bar'
+      #
+      # @example Create a path from arguments
+      #     __pathify('foo', '', nil, 'bar') # => 'foo/bar'
+      #
+      # # @example Encode special characters
+      #     __pathify(['foo', 'bar^bam']) # => 'foo/bar%5Ebam'
+      #
+      # @api private
+      def __pathify(*segments)
+        Array(segments).flatten.
+          compact.
+          reject { |s| s.to_s.strip.empty? }.
+          join('/').
+          squeeze('/')
+      end
+
+      # Convert an array of payloads into OpenSearch `header\ndata` format
+      #
+      # Supports various different formats of the payload: Array of Strings, Header/Data pairs,
+      # or the conveniency "combined" format where data is passed along with the header
+      # in a single item.
+      #
+      #     OpenSearch::API::Utils.__bulkify [
+      #       { :index =>  { :_index => 'myindexA', :_type => 'mytype', :_id => '1', :data => { :title => 'Test' } } },
+      #       { :update => { :_index => 'myindexB', :_type => 'mytype', :_id => '2', :data => { :doc => { :title => 'Update' } } } }
+      #     ]
+      #
+      #     # => {"index":{"_index":"myindexA","_type":"mytype","_id":"1"}}
+      #     # => {"title":"Test"}
+      #     # => {"update":{"_index":"myindexB","_type":"mytype","_id":"2"}}
+      #     # => {"doc":{"title":"Update"}}
+      #
+      def __bulkify(payload)
+        operations = %w[index create delete update]
+
+        case
+
+        # Hashes with `:data`
+        when payload.any? { |d| d.is_a?(Hash) && d.values.first.is_a?(Hash) && operations.include?(d.keys.first.to_s) && (d.values.first[:data] || d.values.first['data']) }
+          payload = payload.
+            inject([]) do |sum, item|
+              operation, meta = item.to_a.first
+              meta            = meta.clone
+              data            = meta.delete(:data) || meta.delete('data')
+
+              sum << { operation => meta }
+              sum << data if data
+              sum
+            end.
+            map { |item| OpenSearch::API.serializer.dump(item) }
+          payload << '' unless payload.empty?
+
+        # Array of strings
+        when payload.all? { |d| d.is_a? String }
+          payload << ''
+
+        # Header/Data pairs
+        else
+          payload = payload.map { |item| OpenSearch::API.serializer.dump(item) }
+          payload << ''
+        end
+
+        payload = payload.join("\n")
+      end
+
+      # Validates the argument Hash against common and valid API parameters
+      #
+      # @param arguments    [Hash]          Hash of arguments to verify and extract, **with symbolized keys**
+      # @param valid_params [Array<Symbol>] An array of symbols with valid keys
+      #
+      # @return [Hash]         Return whitelisted Hash
+      # @raise [ArgumentError] If the arguments Hash contains invalid keys
+      #
+      # @example Extract parameters
+      #   __validate_and_extract_params( { :foo => 'qux' }, [:foo, :bar] )
+      #   # => { :foo => 'qux' }
+      #
+      # @example Raise an exception for invalid parameters
+      #   __validate_and_extract_params( { :foo => 'qux', :bam => 'mux' }, [:foo, :bar] )
+      #   # ArgumentError: "URL parameter 'bam' is not supported"
+      #
+      # @example Skip validating parameters
+      #   __validate_and_extract_params( { :foo => 'q', :bam => 'm' }, [:foo, :bar], { skip_parameter_validation: true } )
+      #   # => { :foo => "q", :bam => "m" }
+      #
+      # @example Skip validating parameters when the module setting is set
+      #   OpenSearch::API.settings[:skip_parameter_validation] = true
+      #   __validate_and_extract_params( { :foo => 'q', :bam => 'm' }, [:foo, :bar] )
+      #   # => { :foo => "q", :bam => "m" }
+      #
+      # @api private
+      #
+      def __validate_and_extract_params(arguments, params=[], options={})
+        if options[:skip_parameter_validation] || OpenSearch::API.settings[:skip_parameter_validation]
+          arguments
+        else
+          __validate_params(arguments, params)
+          __extract_params(arguments, params, options.merge(:escape => false))
+        end
+      end
+
+      def __validate_params(arguments, valid_params=[])
+        arguments.each do |k,v|
+          raise ArgumentError, "URL parameter '#{k}' is not supported" \
+            unless COMMON_PARAMS.include?(k) || COMMON_QUERY_PARAMS.include?(k) || valid_params.include?(k)
+        end
+      end
+
+      def __extract_params(arguments, params=[], options={})
+        result = arguments.select { |k,v| COMMON_QUERY_PARAMS.include?(k) || params.include?(k) }
+        result = Hash[result] unless result.is_a?(Hash) # Normalize Ruby 1.8 and Ruby 1.9 Hash#select behaviour
+        result = Hash[result.map { |k,v| v.is_a?(Array) ? [k, __listify(v, options)] : [k,v]  }] # Listify Arrays
+        result
+      end
+
+      # Extracts the valid parts of the URL from the arguments
+      #
+      # @note Mutates the `arguments` argument, to prevent failures in `__validate_and_extract_params`.
+      #
+      # @param arguments   [Hash]          Hash of arguments to verify and extract, **with symbolized keys**
+      # @param valid_parts [Array<Symbol>] An array of symbol with valid keys
+      #
+      # @return [Array<String>]            Valid parts of the URL as an array of strings
+      #
+      # @example Extract parts
+      #   __extract_parts { :foo => true }, [:foo, :bar]
+      #   # => [:foo]
+      #
+      #
+      # @api private
+      #
+      def __extract_parts(arguments, valid_parts=[])
+        parts = Hash[arguments.select { |k,v| valid_parts.include?(k) }]
+        parts = parts.reduce([]) { |sum, item| k, v = item; v.is_a?(TrueClass) ? sum << k.to_s : sum << v  }
+
+        arguments.delete_if { |k,v| valid_parts.include? k }
+        return parts
+      end
+
+      # Calls the given block, rescuing from `StandardError`.
+      #
+      # Primary use case is the `:ignore` parameter for API calls.
+      #
+      # Returns `false` if exception contains NotFound in its class name or message,
+      # else re-raises the exception.
+      #
+      # @yield [block] A block of code to be executed with exception handling.
+      #
+      # @api private
+      #
+      def __rescue_from_not_found(&block)
+        yield
+      rescue StandardError => e
+        if e.class.to_s =~ /NotFound/ || e.message =~ /Not\s*Found/i
+          false
+        else
+          raise e
+        end
+      end
+
+      def __report_unsupported_parameters(arguments, params=[])
+        messages = []
+        unsupported_params = params.select {|d| d.is_a?(Hash) ? arguments.include?(d.keys.first) : arguments.include?(d) }
+
+        unsupported_params.each do |param|
+          name = case param
+          when Symbol
+            param
+          when Hash
+            param.keys.first
+          else
+            raise ArgumentError, "The param must be a Symbol or a Hash"
+          end
+
+          explanation = if param.is_a?(Hash)
+            ". #{param.values.first[:explanation]}."
+          else
+            ". This parameter is not supported in the version you're using: #{OpenSearch::API::VERSION}, and will be removed in the next release."
+          end
+
+          message = "[!] You are using unsupported parameter [:#{name}]"
+
+          if source = caller && caller.last
+            message += " in `#{source}`"
+          end
+
+          message += explanation
+
+          messages << message
+        end
+
+        unless messages.empty?
+          messages << "Suppress this warning by the `-WO` command line flag."
+
+          if STDERR.tty?
+            Kernel.warn messages.map { |m| "\e[31;1m#{m}\e[0m" }.join("\n")
+          else
+            Kernel.warn messages.join("\n")
+          end
+        end
+      end
+
+      def __report_unsupported_method(name)
+        message = "[!] You are using unsupported method [#{name}]"
+        if source = caller && caller.last
+          message += " in `#{source}`"
+        end
+
+        message += ". This method is not supported in the version you're using: #{OpenSearch::API::VERSION}, and will be removed in the next release. Suppress this warning by the `-WO` command line flag."
+
+        if STDERR.tty?
+          Kernel.warn "\e[31;1m#{message}\e[0m"
+        else
+          Kernel.warn message
+        end
+      end
+
+      extend self
+    end
+  end
+end

data/lib/opensearch/api/version.rb

@@ -0,0 +1,31 @@
+# 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.
+#
+# 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.
+
+module OpenSearch
+  module API
+    VERSION = '1.0.0'.freeze
+  end
+end

data/lib/opensearch/api.rb

@@ -0,0 +1,101 @@
+# 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.
+#
+# 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 "cgi"
+require "multi_json"
+
+require "opensearch/api/version"
+require "opensearch/api/namespace/common"
+require "opensearch/api/utils"
+require "opensearch/api/actions/params_registry"
+
+Dir[ File.expand_path('../api/actions/**/params_registry.rb', __FILE__) ].each   { |f| require f }
+Dir[ File.expand_path('../api/actions/**/*.rb', __FILE__) ].each   { |f| require f }
+Dir[ File.expand_path('../api/namespace/**/*.rb', __FILE__) ].each { |f| require f }
+
+module OpenSearch
+  module API
+    DEFAULT_SERIALIZER = MultiJson
+
+    COMMON_PARAMS = [
+      :ignore,                        # Client specific parameters
+      :index, :type, :id,             # :index/:type/:id
+      :body,                          # Request body
+      :node_id,                       # Cluster
+      :name,                          # Alias, template, settings, warmer, ...
+      :field                          # Get field mapping
+    ]
+
+    COMMON_QUERY_PARAMS = [
+      :ignore,                        # Client specific parameters
+      :format,                        # Search, Cat, ...
+      :pretty,                        # Pretty-print the response
+      :human,                         # Return numeric values in human readable format
+      :filter_path,                   # Filter the JSON response
+      :opaque_id                      # Use X-Opaque-Id
+    ]
+
+    HTTP_GET          = 'GET'.freeze
+    HTTP_HEAD         = 'HEAD'.freeze
+    HTTP_POST         = 'POST'.freeze
+    HTTP_PUT          = 'PUT'.freeze
+    HTTP_DELETE       = 'DELETE'.freeze
+    UNDERSCORE_SEARCH = '_search'.freeze
+    UNDERSCORE_ALL    = '_all'.freeze
+    DEFAULT_DOC       = '_doc'.freeze
+
+    # Auto-include all namespaces in the receiver
+    #
+    def self.included(base)
+      base.send :include,
+                OpenSearch::API::Common,
+                OpenSearch::API::Actions,
+                OpenSearch::API::Cluster,
+                OpenSearch::API::Nodes,
+                OpenSearch::API::Indices,
+                OpenSearch::API::Ingest,
+                OpenSearch::API::Snapshot,
+                OpenSearch::API::Tasks,
+                OpenSearch::API::Cat,
+                OpenSearch::API::Remote,
+                OpenSearch::API::DanglingIndices,
+                OpenSearch::API::Features,
+                OpenSearch::API::Shutdown
+    end
+
+    # The serializer class
+    #
+    def self.serializer
+      settings[:serializer] || DEFAULT_SERIALIZER
+    end
+
+    # Access the module settings
+    #
+    def self.settings
+      @settings ||= {}
+    end
+  end
+end

data/lib/opensearch-api.rb

@@ -0,0 +1,27 @@
+# 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.
+#
+# 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 'opensearch/api'

data/opensearch-api.gemspec

@@ -0,0 +1,92 @@
+# 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.
+#
+# 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.
+
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'opensearch/api/version'
+
+signing_key_path = File.expand_path("../gem-private_key.pem")
+
+Gem::Specification.new do |s|
+  s.name          = 'opensearch-api'
+  s.version       = OpenSearch::API::VERSION
+  s.authors       = ['Jayesh Hathila', 'Vamshi Vijay Nakkirtha', 'Vijayan Balasubramanian' , 'Yuvraj Jaiswal']
+  s.email         = ['jayehh@amazon.com', 'vamshin@amazon.com', 'balasvij@amazon.com', 'jaiyuvra@amazon.com']
+  s.summary       = 'Ruby API for OpenSearch.'
+  s.homepage      = 'https://opensearch.org/docs/latest/'
+  s.license       = 'Apache-2.0'
+  s.metadata = {
+    'homepage_uri' => 'https://opensearch.org/docs/latest/',
+    'source_code_uri' => 'https://github.com/opensearch-project/opensearch-ruby/tree/main/opensearch-api',
+    'bug_tracker_uri' => 'https://github.com/opensearch-project/opensearch-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)/})
+
+  if $PROGRAM_NAME.end_with?("gem") && ARGV == ["build", __FILE__] && File.exist?(signing_key_path)
+    s.signing_key = signing_key_path
+    s.cert_chain  = ['../certs/opensearch-rubygems.pem']
+  end
+
+  s.require_paths = ['lib']
+
+  s.extra_rdoc_files  = [ 'README.md', 'LICENSE' ]
+  s.rdoc_options      = [ '--charset=UTF-8' ]
+
+  s.required_ruby_version = '>= 2.4'
+
+  s.add_dependency 'multi_json'
+
+  s.add_development_dependency 'ansi'
+  s.add_development_dependency 'bundler'
+  s.add_development_dependency 'opensearch'
+  s.add_development_dependency 'opensearch-transport'
+  s.add_development_dependency 'minitest'
+  s.add_development_dependency 'minitest-reporters'
+  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 'yard'
+
+  # Gems for testing integrations
+  s.add_development_dependency 'jsonify'
+  s.add_development_dependency 'hashie'
+
+  s.add_development_dependency 'cane'
+  s.add_development_dependency 'escape_utils' unless defined? JRUBY_VERSION
+  s.add_development_dependency 'jbuilder'
+  s.add_development_dependency 'require-prof' unless defined?(JRUBY_VERSION) || defined?(Rubinius)
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'test-unit', '~> 2'
+  s.add_development_dependency 'ruby-prof' unless defined?(JRUBY_VERSION) || defined?(Rubinius)
+
+  s.description = <<-DESC.gsub(/^    /, '')
+    Ruby API for OpenSearch. See the `opensearch` gem for full integration.
+  DESC
+end

data/spec/opensearch/api/actions/abort_benchmark_spec.rb

@@ -0,0 +1,43 @@
+# 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.
+#
+# 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 'spec_helper'
+
+describe 'client#abort_benchmark' do
+
+  let(:expected_args) do
+    [
+      'POST',
+      '_bench/abort/foo',
+      {},
+      nil
+    ]
+  end
+
+  it 'performs the request' do
+    expect(client_double.abort_benchmark(name: 'foo'))
+  end
+end

data/spec/opensearch/api/actions/benchmark_spec.rb

@@ -0,0 +1,43 @@
+# 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.
+#
+# 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 'spec_helper'
+
+describe 'client#benchmark' do
+
+  let(:expected_args) do
+    [
+      'PUT',
+      '_bench',
+      {},
+      { name: 'foo' }
+    ]
+  end
+
+  it 'performs the request' do
+    expect(client_double.benchmark(body: { name: 'foo' }))
+  end
+end