opensearch-ruby 3.4.0 → 4.0.0.pre.beta.2

data/lib/opensearch/api/utils.rb

@@ -3,96 +3,56 @@
 # 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.
+
+# This file is generated from the OpenSearch REST API spec.
+# Do not modify it by hand. Instead, modify the generator or the spec
+
+# frozen_string_literal: true
+
+require 'cgi'
 
 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 == '*'
-
-        CGI.escape(string.to_s)
+      NON_URL_ARGS = Set.new(%w[body headers]).freeze
+      BULK_OPERATIONS = Set.new(%w[index create delete update]).freeze
+
+      # @return a new hash with all keys converted to strings and url param values escaped
+      # @param [Hash] args
+      def self.clone_and_normalize_arguments(args)
+        args.each_with_object({}) do |(k, v), acc|
+          k = k.to_s
+          acc[k] = NON_URL_ARGS.include?(k) ? v : normalize_value(v)
+        end
       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 : {}
+      # @param [Hash] params the query params to validate
+      # @param [Set<String>] valid_param_names the list of valid params names for the api method
+      def self.validate_query_params!(params, valid_param_names = nil)
+        return if OpenSearch::API.settings[:skip_parameter_validation]
+        params.each_key do |k|
+          next if valid_param_names&.include?(k)
+          next if GLOBAL_QUERY_PARAMS.include?(k)
+          raise ArgumentError, "URL parameter '#{k}' is not supported"
+        end
+      end
 
-        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(',')
+      # @return the value escaped for URL unless it is a Hash
+      def self.normalize_value(value)
+        return value.clone if value.is_a? Hash
+        value = value.to_s.strip unless value.is_a? Enumerable
+        value = value.split(',') if value.is_a? String
+        value.map { |v| CGI.escape(v.to_s) }.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('/')
+      def self.build_url(*parts)
+        parts.compact.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
+      # or the convenient "combined" format where data is passed along with the header
       # in a single item.
       #
       #     OpenSearch::API::Utils.__bulkify [
@@ -104,13 +64,13 @@ module OpenSearch
       #     # => {"title":"Test"}
       #     # => {"update":{"_index":"myindexB","_id":"2"}}
       #     # => {"doc":{"title":"Update"}}
-      #
-      def __bulkify(payload)
-        operations = %w[index create delete update]
+      # TODO: refactor this method to be more readable
+      def self.bulkify(payload)
+        return payload unless payload.is_a?(Array)
 
         # Hashes with `:data`
         if payload.any? do |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'])
+             d.is_a?(Hash) && d.values.first.is_a?(Hash) && BULK_OPERATIONS.include?(d.keys.first.to_s) && (d.values.first[:data] || d.values.first['data'])
            end
           payload = payload
                     .each_with_object([]) do |item, sum|
@@ -134,163 +94,8 @@ module OpenSearch
           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
+        payload.join("\n")
       end
-
-      def __extract_params(arguments, params = [], options = {})
-        result = arguments.select { |k, _v| COMMON_QUERY_PARAMS.include?(k) || params.include?(k) }
-        result = result.to_h unless result.is_a?(Hash) # Normalize Ruby 1.8 and Ruby 1.9 Hash#select behaviour
-        result.map { |k, v| v.is_a?(Array) ? [k, __listify(v, options)] : [k, v] }.to_h # Listify Arrays
-      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 = arguments.select { |k, _v| valid_parts.include?(k) }.to_h
-        parts = parts.reduce([]) do |sum, item|
-          k, v = item
-          sum << (v.is_a?(TrueClass) ? k.to_s : v)
-        end
-
-        arguments.delete_if { |k, _v| valid_parts.include? k }
-        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
-        yield
-      rescue StandardError => e
-        raise e unless e.class.to_s =~ /NotFound/ || e.message =~ /Not\s*Found/i
-        false
-      end
-
-      def __report_unsupported_parameters(arguments, params = [])
-        messages = []
-        unsupported_params = params.select do |d|
-          d.is_a?(Hash) ? arguments.include?(d.keys.first) : arguments.include?(d)
-        end
-
-        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::VERSION}, and will be removed in the next release."
-                        end
-
-          message = "[!] You are using unsupported parameter [:#{name}]"
-
-          if (source = caller&.last)
-            message += " in `#{source}`"
-          end
-
-          message += explanation
-
-          messages << message
-        end
-
-        return if 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
-
-      def __report_unsupported_method(name)
-        message = "[!] You are using unsupported method [#{name}]"
-        if (source = caller&.last)
-          message += " in `#{source}`"
-        end
-
-        message += ". This method is not supported in the version you're using: #{OpenSearch::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.rb

@@ -3,100 +3,28 @@
 # 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.
 
-# This code was generated from OpenSearch API Spec.
-# Update the code generation logic instead of modifying this file directly.
+# This file is generated from the OpenSearch REST API spec.
+# Do not modify it by hand. Instead, modify the generator or the spec.
 
 # frozen_string_literal: true
 
-require 'opensearch/api/namespace/common'
-require 'opensearch/api/utils'
-require 'opensearch/api/actions/params_registry'
-
-Dir[File.expand_path('api/actions/**/params_registry.rb', __dir__)].sort.each   { |f| require f }
-Dir[File.expand_path('api/actions/**/*.rb', __dir__)].sort.each   { |f| require f }
-Dir[File.expand_path('api/namespace/**/*.rb', __dir__)].sort.each { |f| require f }
-
 module OpenSearch
   module API
-    DEFAULT_SERIALIZER = MultiJson
+    GLOBAL_QUERY_PARAMS = Set.new([
+      'pretty',         # Whether to pretty format the returned JSON response.
+      'human',          # Whether to return human readable values for statistics.
+      'error_trace',    # Whether to include the stack trace of returned errors.
+      'source',         # The URL-encoded request definition. Useful for libraries that do not accept a request body for non-POST requests.
+      'filter_path'     # Used to reduce the response. This parameter takes a comma-separated list of filters. It supports using wildcards to match any field or part of a field’s name. You can also exclude fields with "-".
+    ]).freeze
 
-    COMMON_PARAMS = [
-      :ignore,                        # Client specific parameters
-      :index, :id,                    # :index/: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'
-    HTTP_HEAD         = 'HEAD'
-    HTTP_PATCH        = 'PATCH'
-    HTTP_POST         = 'POST'
-    HTTP_PUT          = 'PUT'
-    HTTP_DELETE       = 'DELETE'
-
-    UNDERSCORE_SEARCH = '_search'
-    UNDERSCORE_ALL    = '_all'
-    DEFAULT_DOC       = '_doc'
-
-    # Auto-include all namespaces in the receiver
-    def self.included(base)
-      base.send :include,
-                OpenSearch::API::Common,
-                OpenSearch::API::Actions,
-                OpenSearch::API::Cat,
-                OpenSearch::API::Cluster,
-                OpenSearch::API::DanglingIndices,
-                OpenSearch::API::Features,
-                OpenSearch::API::Http,
-                OpenSearch::API::Indices,
-                OpenSearch::API::Ingest,
-                OpenSearch::API::Nodes,
-                OpenSearch::API::Remote,
-                OpenSearch::API::RemoteStore,
-                OpenSearch::API::Security,
-                OpenSearch::API::Shutdown,
-                OpenSearch::API::Snapshot,
-                OpenSearch::API::Tasks
-    end
+    DEFAULT_SERIALIZER = MultiJson
 
-    # The serializer class
     def self.serializer
       settings[:serializer] || DEFAULT_SERIALIZER
     end
 
-    # Access the module settings
     def self.settings
       @settings ||= {}
     end

data/lib/opensearch/dsl/search.rb

@@ -51,8 +51,8 @@ module OpenSearch
       #     # => {:query=>{:match=>{:title=>"test"}}}
       #
       #
-      def search(*args, &block)
-        Search.new(*args, &block)
+      def search(...)
+        Search.new(...)
       end
 
       extend self

data/lib/opensearch/dsl.rb

@@ -36,9 +36,9 @@ require 'opensearch/dsl/search/sort'
 require 'opensearch/dsl/search/options'
 require 'opensearch/dsl/search/suggest'
 
-Dir[File.expand_path('dsl/search/queries/**/*.rb', __dir__)].sort.each        { |f| require f }
-Dir[File.expand_path('dsl/search/filters/**/*.rb', __dir__)].sort.each        { |f| require f }
-Dir[File.expand_path('dsl/search/aggregations/**/*.rb', __dir__)].sort.each   { |f| require f }
+Dir[File.expand_path('dsl/search/queries/**/*.rb', __dir__)].each        { |f| require f }
+Dir[File.expand_path('dsl/search/filters/**/*.rb', __dir__)].each        { |f| require f }
+Dir[File.expand_path('dsl/search/aggregations/**/*.rb', __dir__)].each   { |f| require f }
 
 require 'opensearch/dsl/search'
 

data/lib/opensearch/transport/client.rb

@@ -101,6 +101,8 @@ module OpenSearch
       #
       # @option arguments [Boolean] :reload_on_failure Reload connections after failure (false by default)
       #
+      # @option arguments [Boolean] :ignore_404_on_delete Whether to ignore 404/NotFound error on http DELETE (false by default)
+      #
       # @option arguments [Integer] :request_timeout The request timeout to be passed to transport in options
       #
       # @option arguments [Symbol] :adapter A specific adapter for Faraday (e.g. `:patron`)
@@ -134,7 +136,7 @@ module OpenSearch
       #
       def initialize(arguments = {}, &block)
         @options = arguments.transform_keys(&:to_sym)
-        @arguments = @options
+        @arguments = @options.clone
         @arguments[:logger] ||= @arguments[:log]   ? DEFAULT_LOGGER.call : nil
         @arguments[:tracer] ||= @arguments[:trace] ? DEFAULT_TRACER.call : nil
         @arguments[:reload_connections] ||= false
@@ -144,6 +146,7 @@ module OpenSearch
         @arguments[:transport_options]  ||= {}
         @arguments[:http]               ||= {}
         @options[:http]                 ||= {}
+        @options[:ignore_404_on_delete] ||= false
 
         set_api_key if (@api_key = @arguments[:api_key])
         set_compatibility_header if ENV['ELASTIC_CLIENT_APIVERSIONING']
@@ -180,7 +183,6 @@ module OpenSearch
       end
 
       # Performs a request through delegation to {#transport}.
-      #
       def perform_request(method, path, params = {}, body = nil, headers = nil)
         method = @send_get_body_as if method == 'GET' && body
         if (opaque_id = params.delete(:opaque_id))
@@ -191,6 +193,32 @@ module OpenSearch
         transport.perform_request(method, path, params, body, headers)
       end
 
+      def perform_ping_request(*args)
+        perform_request(*args).status == 200
+      rescue StandardError => e
+        return false if e.class.to_s =~ /NotFound|ConnectionFailed/
+        return false if e.message =~ /Not *Found|404|ConnectionFailed/i
+        raise e
+      end
+
+      def perform_head_request(*args)
+        perform_request(*args).status == 200
+      rescue StandardError => e
+        return false if e.class.to_s =~ /NotFound/
+        return false if e.message =~ /Not\s*Found/i
+        raise e
+      end
+
+      def perform_delete_request(*args)
+        perform_request(*args).body
+      rescue StandardError => e
+        if @options[:ignore_404_on_delete]
+          return false if e.class.to_s =~ /NotFound/
+          return false if e.message =~ /Not\s*Found/i
+        end
+        raise e
+      end
+
       private
 
       def set_api_key

data/lib/opensearch/transport/transport/base.rb

@@ -282,8 +282,6 @@ module OpenSearch
 
           params = params.clone
 
-          ignore = Array(params.delete(:ignore)).compact.map(&:to_i)
-
           begin
             tries     += 1
             connection = get_connection or raise(Error, 'Cannot get new connection from pool.')
@@ -343,10 +341,9 @@ module OpenSearch
                       duration
             end
 
-            # Log the failure only when `ignore` doesn't match the response status
-            log_fatal "[#{response.status}] #{response.body}" unless ignore.include?(response.status.to_i)
+            log_fatal "[#{response.status}] #{response.body}"
 
-            __raise_transport_error response unless ignore.include?(response.status.to_i)
+            __raise_transport_error response
           end
 
           if response.body && !response.body.empty? && response.headers && response.headers['content-type'] =~ /json/
@@ -358,9 +355,7 @@ module OpenSearch
             'n/a'
           end
 
-          unless ignore.include?(response.status.to_i)
-            __log_response method, path, params, body, url, response, json, took, duration
-          end
+          __log_response method, path, params, body, url, response, json, took, duration
 
           if tracer
             __trace method, path, params, connection.connection.headers, body, url, response, nil, 'N/A',

data/lib/opensearch/transport/transport/http/faraday.rb

@@ -24,6 +24,8 @@
 # specific language governing permissions and limitations
 # under the License.
 
+require 'opensearch/version'
+
 module OpenSearch
   module Transport
     module Transport
@@ -91,7 +93,7 @@ module OpenSearch
                 meta << "#{RbConfig::CONFIG['host_os'].split('_').first[/[a-z]+/i].downcase} #{RbConfig::CONFIG['target_cpu']}"
               end
               meta << client.headers[USER_AGENT_STR].to_s
-              "opensearch-ruby/#{VERSION} (#{meta.join('; ')})"
+              "opensearch-ruby/#{OpenSearch::VERSION} (#{meta.join('; ')})"
             end
           end
         end

data/lib/opensearch/version.rb

@@ -25,5 +25,5 @@
 # under the License.
 
 module OpenSearch
-  VERSION = '3.4.0'.freeze
+  VERSION = '4.0.0-beta.2'.freeze
 end