elasticsearch-api 8.12.2 → 8.13.0

data/spec/spec_helper.rb

@@ -22,7 +22,7 @@ end
 if defined?(JRUBY_VERSION)
   require 'pry-nav'
 else
-  require 'pry-byebug'
+  require 'debug'
 end
 require 'yaml'
 require 'active_support/isolated_execution_state' unless RUBY_VERSION < '2.7.0'
@@ -59,8 +59,12 @@ end
 RSpec.configure do |config|
   config.include(HelperModule)
   config.add_formatter('documentation')
-  config.add_formatter('RspecJunitFormatter', "tmp/elasticsearch-#{ENV['TEST_SUITE']}-#{RUBY_VERSION}-junit.xml")
-  config.add_formatter('RSpec::Core::Formatters::HtmlFormatter', "tmp/elasticsearch-#{ENV['TEST_SUITE']}-#{RUBY_VERSION}.html")
+  if defined?(JRUBY_VERSION)
+    config.add_formatter('RSpec::Core::Formatters::HtmlFormatter', "tmp/elasticsearch-#{ENV['TEST_SUITE']}-jruby-#{JRUBY_VERSION}.html")
+  else
+    config.add_formatter('RSpec::Core::Formatters::HtmlFormatter', "tmp/elasticsearch-#{ENV['TEST_SUITE']}-#{RUBY_VERSION}.html")
+  end
+  config.example_status_persistence_file_path  = "tmp/#{ENV['TEST_SUITE']}-#{RUBY_VERSION}.txt"
   config.color_mode = :on
 end
 

data/utils/Gemfile

@@ -17,8 +17,8 @@
 
 source 'https://rubygems.org'
 
-gem 'byebug' unless defined?(JRUBY_VERSION)
 gem 'coderay'
+gem 'debug' unless defined?(JRUBY_VERSION)
 gem 'json'
 gem 'multi_json'
 gem 'pry'

data/utils/{endpoint_spec.rb → thor/endpoint_spec.rb}

@@ -32,7 +32,7 @@ module Elasticsearch
 
         full_namespace = parse_full_namespace
         @namespace_depth = full_namespace.size > 0 ? full_namespace.size - 1 : 0
-        @module_namespace = full_namespace[0, namespace_depth]
+        @module_namespace = full_namespace[0, @namespace_depth]
         @method_name = full_namespace.last
 
         @path_parts = parse_endpoint_parts(@spec)
@@ -56,7 +56,6 @@ module Elasticsearch
                   :http_path,
                   :required_parts,
                   :http_method,
-                  :namespace_depth,
                   :path_params,
                   :perform_request_opts
 

data/utils/{endpoint_specifics.rb → thor/endpoint_specifics.rb}

@@ -136,11 +136,11 @@ module Elasticsearch
 
       def bulk_body_helper
         <<~SRC
-          if body.is_a? Array
-            payload = Elasticsearch::API::Utils.__bulkify(body)
-          else
-            payload = body
-          end
+          payload = if body.is_a? Array
+                      Elasticsearch::API::Utils.__bulkify(body)
+                    else
+                      body
+                    end
         SRC
       end
 

data/utils/thor/generate_source.rb

@@ -22,8 +22,10 @@ require 'pathname'
 require 'multi_json'
 require 'coderay'
 require 'pry'
+require_relative 'generator/build_hash_helper'
+require_relative 'generator/docs_helper'
 require_relative 'generator/files_helper'
-require_relative '../endpoint_spec'
+require_relative './endpoint_spec'
 
 module Elasticsearch
   module API
@@ -41,20 +43,17 @@ module Elasticsearch
       namespace 'code'
       include Thor::Actions
       include EndpointSpecifics
+      include DocsHelper
 
       desc 'generate', 'Generate source code and tests from the REST API JSON specification'
       method_option :verbose, type: :boolean, default: false,  desc: 'Output more information'
       method_option :tests,   type: :boolean, default: false,  desc: 'Generate test files'
 
       def generate
-        @build_hash = if ENV['BUILD_HASH']
-                        File.read(File.expand_path('../../../tmp/rest-api-spec/build_hash',__dir__))
-                      else
-                        original_build_hash
-                      end
-
+        @build_hash = BuildHashHelper.build_hash
         self.class.source_root File.expand_path(__dir__)
         generate_source
+
         # -- Tree output
         print_tree if options[:verbose]
       end
@@ -68,101 +67,22 @@ module Elasticsearch
         FilesHelper.files.each do |filepath|
           @spec = EndpointSpec.new(filepath)
           say_status 'json', @spec.path, :yellow
-
           # Don't generate code for internal APIs:
           next if @spec.module_namespace.flatten.first == '_internal'
 
           path_to_file = output.join(@spec.module_namespace.join('/')).join("#{@spec.method_name}.rb")
           dir = output.join(@spec.module_namespace.join('/'))
-
           empty_directory(dir, verbose: false)
 
           # Write the file with the ERB template:
           template('templates/method.erb', path_to_file, force: true)
 
+          # Optionals:
           print_source_code(path_to_file) if options[:verbose]
-
           generate_tests if options[:tests]
-
-          puts
         end
-
         run_rubocop
-        add_hash
-      end
-
-      def add_hash
-        Dir.glob("#{FilesHelper.output_dir}/**/*.rb").each do |file|
-          content = File.read(file)
-          new_content = content.gsub(/(^#\sunder\sthe\sLicense.\n#)/) do |_|
-            match = Regexp.last_match
-            "#{match[1]}\n#{build_hash_comment}"
-          end
-          File.open(file, 'w') { |f| f.puts new_content }
-        end
-      end
-
-      def build_hash_comment
-        [
-          "Auto generated from build hash #{@build_hash}",
-          '@see https://github.com/elastic/elasticsearch/tree/main/rest-api-spec',
-          ''
-        ].map { |b| "# #{b}" }.join("\n").strip
-      end
-
-      def original_build_hash
-        content = File.read("#{FilesHelper.output_dir}/info.rb")
-        return unless (match = content.match(/Auto generated from build hash ([a-f0-9]+)/))
-
-        match[1]
-      end
-
-      # Create the hierarchy of directories based on API namespaces
-      #
-      def create_directories(key, value)
-        return if value['documentation']
-
-        empty_directory @output.join(key)
-        create_directory_hierarchy * value.to_a.first
-      end
-
-      def docs_helper(name, info)
-        info['type'] = 'String' if info['type'] == 'enum' # Rename 'enums' to 'strings'
-        info['type'] = 'Integer' if info['type'] == 'int' # Rename 'int' to 'Integer'
-        tipo = info['type'] ? info['type'].capitalize : 'String'
-        description = info['description'] ? info['description'].strip : '[TODO]'
-        options = info['options'] ? "(options: #{info['options'].join(', ').strip})" : nil
-        required = info['required'] ? '(*Required*)' : ''
-        deprecated = info['deprecated'] ? '*Deprecated*' : ''
-        optionals = [required, deprecated, options].join(' ').strip
-
-        "# @option arguments [#{tipo}] :#{name} #{description} #{optionals}\n"
-      end
-
-      def stability_doc_helper(stability)
-        return if stability == 'stable'
-
-        if stability == 'experimental'
-          <<~MSG
-            # This functionality is Experimental and may be changed or removed
-            # completely in a future release. Elastic will take a best effort approach
-            # to fix any issues, but experimental features are not subject to the
-            # support SLA of official GA features.
-          MSG
-        elsif stability == 'beta'
-          <<~MSG
-            # This functionality is in Beta and is subject to change. The design and
-            # code is less mature than official GA features and is being provided
-            # as-is with no warranties. Beta features are not subject to the support
-            # SLA of official GA features.
-          MSG
-        else
-          <<~MSG
-            # This functionality is subject to potential breaking changes within a
-            # minor version, meaning that your referencing code may break when this
-            # library is upgraded.
-          MSG
-        end
+        BuildHashHelper.add_hash(@build_hash)
       end
 
       def generate_tests
@@ -200,7 +120,7 @@ module Elasticsearch
       end
 
       def run_rubocop
-        system("rubocop -c ./thor/.rubocop.yml --format autogenconf -x #{FilesHelper::output_dir}")
+        system("rubocop -c ./thor/.rubocop.yml --format autogenconf -a #{FilesHelper::output_dir}")
       end
     end
   end

data/utils/thor/generator/build_hash_helper.rb

@@ -0,0 +1,64 @@
+# 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 Elasticsearch
+  module API
+    # Helper for the Elasticsearch build hash in source code docs
+    module BuildHashHelper
+      class << self
+        def build_hash
+          if ENV['BUILD_HASH']
+            File.read(File.expand_path('../../../tmp/rest-api-spec/build_hash',__dir__))
+          else
+            original_build_hash
+          end
+        end
+
+        def add_hash(build_hash)
+          Dir.glob("#{FilesHelper.output_dir}/**/*.rb").each do |file|
+            content = File.read(file)
+            new_content = content.gsub(/(^#\sunder\sthe\sLicense.\n#)/) do |_|
+              match = Regexp.last_match
+              "#{match[1]}\n#{build_hash_comment(build_hash)}"
+            end
+            File.open(file, 'w') { |f| f.puts new_content }
+          end
+        end
+
+        def build_hash_comment(build_hash)
+          [
+            "Auto generated from build hash #{build_hash}",
+            '@see https://github.com/elastic/elasticsearch/tree/main/rest-api-spec',
+            ''
+          ].map { |b| "# #{b}" }.join("\n").strip
+        end
+
+        private
+
+        def original_build_hash
+          content = File.read("#{FilesHelper.output_dir}/info.rb")
+
+          return unless (match = content.match(/Auto generated from build hash ([a-f0-9]+)/))
+
+          match[1]
+        rescue
+          return 'Unavailable'
+        end
+      end
+    end
+  end
+end

data/utils/thor/generator/docs_helper.rb

@@ -0,0 +1,62 @@
+# 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 Elasticsearch
+  module API
+    # Helper with file related methods for code generation
+    module DocsHelper
+      def docs(name, info)
+        info['type'] = 'String' if info['type'] == 'enum' # Rename 'enums' to 'strings'
+        info['type'] = 'Integer' if info['type'] == 'int' # Rename 'int' to 'Integer'
+        tipo = info['type'] ? info['type'].capitalize : 'String'
+        description = info['description'] ? info['description'].strip : '[TODO]'
+        options = info['options'] ? "(options: #{info['options'].join(', ').strip})" : nil
+        required = info['required'] ? '(*Required*)' : ''
+        deprecated = info['deprecated'] ? '*Deprecated*' : ''
+        optionals = [required, deprecated, options].join(' ').strip
+
+        "# @option arguments [#{tipo}] :#{name} #{description} #{optionals}\n"
+      end
+
+      def stability_doc_helper(stability)
+        return if stability == 'stable'
+
+        if stability == 'experimental'
+          <<~MSG
+            # This functionality is Experimental and may be changed or removed
+            # completely in a future release. Elastic will take a best effort approach
+            # to fix any issues, but experimental features are not subject to the
+            # support SLA of official GA features.
+          MSG
+        elsif stability == 'beta'
+          <<~MSG
+            # This functionality is in Beta and is subject to change. The design and
+            # code is less mature than official GA features and is being provided
+            # as-is with no warranties. Beta features are not subject to the support
+            # SLA of official GA features.
+          MSG
+        else
+          <<~MSG
+            # This functionality is subject to potential breaking changes within a
+            # minor version, meaning that your referencing code may break when this
+            # library is upgraded.
+          MSG
+        end
+      end
+    end
+  end
+end

data/utils/thor/generator/files_helper.rb

@@ -22,37 +22,40 @@ module Elasticsearch
   module API
     # Helper with file related methods for code generation
     module FilesHelper
+
       PROJECT_PATH = File.join(File.dirname(__FILE__), '..')
       SRC_PATH   = File.join(PROJECT_PATH, '..', '..', '..', 'tmp/rest-api-spec/api/')
       OUTPUT_DIR = '../../elasticsearch-api/lib/elasticsearch/api/actions'.freeze
       TESTS_DIRECTORY = "#{PROJECT_PATH}/../../../tmp/rest-api-spec/test/free".freeze
 
-      # Only get JSON files and remove hidden files
-      def self.files
-        json_files = Dir.entries(SRC_PATH)
+      class << self
+        # Only get JSON files and remove hidden files
+        def files
+          json_files = Dir.entries(SRC_PATH)
 
-        json_files.reject do |file|
-          File.extname(file) != '.json' ||
-            File.basename(file) == '_common.json'
-        end.map { |file| "#{SRC_PATH}#{file}" }
-      end
+          json_files.reject do |file|
+            File.extname(file) != '.json' ||
+              File.basename(file) == '_common.json'
+          end.map { |file| "#{SRC_PATH}#{file}" }
+        end
 
-      # Path to directory to copy generated files
-      def self.output_dir
-        Pathname(OUTPUT_DIR)
-      end
+        # Path to directory to copy generated files
+        def output_dir
+          Pathname(OUTPUT_DIR)
+        end
 
-      def self.documentation_url(documentation_url)
-        branch = `git rev-parse --abbrev-ref HEAD`
-        return documentation_url.gsub(/\/(master|main)\//, "/current/") if branch == "main\n"
+        def documentation_url(documentation_url)
+          branch = `git rev-parse --abbrev-ref HEAD`
+          return documentation_url.gsub(/\/(master|main)\//, "/current/") if branch == "main\n"
 
-        regex = /([0-9]{1,2}\.[0-9x]{1,2})/
-        version = Elasticsearch::API::VERSION.match(regex)[0]
-        # TODO - How do we fix this so it doesn't depend on which branch we're running from
-        if ENV['IGNORE_VERSION']
-          documentation_url.gsub(/\/(master|main)\//, "/current/")
-        else
-          documentation_url.gsub(/\/(current|master|main)\//, "/#{version}/")
+          regex = /([0-9]{1,2}\.[0-9x]{1,2})/
+          version = Elasticsearch::API::VERSION.match(regex)[0]
+          # TODO - How do we fix this so it doesn't depend on which branch we're running from
+          if ENV['IGNORE_VERSION']
+            documentation_url.gsub(/\/(master|main)\//, "/current/")
+          else
+            documentation_url.gsub(/\/(current|master|main)\//, "/#{version}/")
+          end
         end
       end
 

data/utils/thor/templates/_body.erb

@@ -30,5 +30,5 @@ when 'mtermvectors'
 <%- when 'ml.find_file_structure' %>
   body = Utils.__bulkify(arguments.delete(:body))
 <%- else -%>
-  <%= '  '*(@spec.namespace_depth+3) %>body   = <%= @spec.body.nil? ? 'nil' : 'arguments.delete(:body)' %>
+  body   = <%= @spec.body.nil? ? 'nil' : 'arguments.delete(:body)' %>
 <%- end -%>

data/utils/thor/templates/_documentation_top.erb

@@ -17,30 +17,29 @@
 # under the License.
 %>
 <%- if @spec.documentation['description'] -%>
-  <%= '  '*(@spec.namespace_depth+3) %># <%= @spec.documentation['description'] .gsub("\n", "\n#{'  '*(@spec.namespace_depth+3)}# ") -%>
+  # <%= @spec.documentation['description'].gsub("\n", "\n  # ") -%>
 <%- else %>
-  <%= '  '*(@spec.namespace_depth+3) %># TODO: Description
+  # TODO: Description
 <%- end %>
 <%= stability_doc_helper(@spec.stability) -%>
-<%= '  '*(@spec.namespace_depth+3) %>#
+#
 <%- unless @spec.path_parts.nil? || @spec.path_parts.empty? %><%# URL parts -%>
   <%- @spec.path_parts.each do |name, info| -%>
-    <%= docs_helper(name, info) -%>
+    <%= docs(name, info) -%>
   <%- end -%>
 <%- end -%><%# Body -%>
 <%# URL parameters -%>
 <%- @spec.params.each do |name, info| -%>
-  <%= docs_helper(name, info) unless (!@spec.path_parts.empty? && @spec.path_parts.keys.include?(name)) -%>
+  <%= docs(name, info) unless (!@spec.path_parts.empty? && @spec.path_parts.keys.include?(name)) -%>
 <%- end -%>
 # @option arguments [Hash] :headers Custom HTTP headers
 <%- if @spec.body -%>
   <%- if @spec.method_name == 'bulk' -%>
     <%= bulk_doc_helper(@spec.body['description']) -%>
   <%- else -%>
-    <%= '  '*(@spec.namespace_depth+1) +
-    '# @option arguments [Hash] :body ' + (@spec.body['description'] ?
-                                           @spec.body['description'].strip : 'TODO: Description') +
-                                           (@spec.body['required'] ? ' (*Required*)' : '') + "\n"
+    <%= '# @option arguments [Hash] :body ' + (@spec.body['description'] ?
+                                               @spec.body['description'].strip : 'TODO: Description') +
+                                              (@spec.body['required'] ? ' (*Required*)' : '') + "\n"
     -%>
   <%- end -%>
 <%- end -%>
@@ -51,7 +50,7 @@
   # Deprecated since version <%=  @spec.deprecation_note['version'] %>
   #
 <% end -%>
-<%= '  '*(@spec.namespace_depth+3) -%>#
+#
 <%# Documentation link -%>
-<%=  '  '*(@spec.namespace_depth+3) %># @see <%= @spec.documentation['url'] ? Elasticsearch::API::FilesHelper.documentation_url(@spec.documentation['url']) : "[TODO]" %>
-<%= '  '*(@spec.namespace_depth+3) %>#
+# @see <%= @spec.documentation['url'] ? Elasticsearch::API::FilesHelper.documentation_url(@spec.documentation['url']) : "[TODO]" %>
+#

data/utils/thor/templates/_method_setup.erb

@@ -18,19 +18,19 @@
 %>
 <%- @spec.path_parts.each do |name, _| %>
   <%- unless @spec.method_name == 'get_field_mapping' && name == 'fields' %>
-    <%= '  '*(@spec.namespace_depth+3) + "_#{name}" %> = arguments.delete(:<%=name %>)
+    <%= "_#{name}" %> = arguments.delete(:<%=name %>)
   <%- end -%>
 <%- end -%>
 
-<%= '  '*(@spec.namespace_depth+4) %>method = <%= @spec.http_method %>
+method = <%= @spec.http_method %>
 <%- if @spec.method_name == 'termvectors' %>
-  endpoint = arguments.delete(:endpoint) || '_termvectors'
+  arguments.delete(:endpoint)
 <%- end -%>
-<%= '  '*(@spec.namespace_depth+4) %>path   = <%= @spec.http_path %>
+path   = <%= @spec.http_path %>
 <%- if !@spec.params.empty? || needs_ignore_404?(@spec.endpoint_name) || needs_complex_ignore_404?(@spec.endpoint_name)-%>
-  <%= '  '*(@spec.namespace_depth+4) %>params = Utils.process_params(arguments)
+  params = Utils.process_params(arguments)
 <%- else -%>
-  <%= '  '*(@spec.namespace_depth+4) %>params = {}
+  params = {}
 <%- end -%>
 <%- @spec.specific_params.each do |param| -%>
   <%= param %>

data/utils/thor/templates/_perform_request.erb

@@ -47,4 +47,4 @@
     )
   <%- end -%>
 <%- end -%>
-<%= '  '*(@spec.namespace_depth+3) %>end
+end

data/utils/thor/templates/method.erb

@@ -16,14 +16,14 @@
 # under the License.
 #
 module Elasticsearch
-<%= '  '*(@spec.namespace_depth) %>module API
+module API
 <%- @spec.module_namespace.each_with_index do |name, i| -%>
   <%= '  '*i %>module <%= module_name_helper(name) %>
 <%- end -%>
-<%= '  '*(@spec.namespace_depth+2) %>module Actions
+module Actions
 <%= ERB.new(File.new("./thor/templates/_documentation_top.erb").read, trim_mode: '-').result(binding) -%>
 <%# Method definition -%>
-<%= '  '*(@spec.namespace_depth+3) -%>def <%= @spec.method_name %>(arguments = {})
+def <%= @spec.method_name %>(arguments = {})
   request_opts = { endpoint: arguments[:endpoint] || "<%= @spec.endpoint_name %>" }
 <%- unless @spec.path_params.empty? %>
   defined_params =<%=  @spec.path_params %>.inject({}) do |set_variables, variable|
@@ -34,12 +34,12 @@ module Elasticsearch
 <%- end %>
 <%-    %>
 <%- if @spec.endpoint_name == 'create' -%>
-  <%= '  '*(@spec.namespace_depth+3) %>if arguments[:id]
-  <%= '  '*(@spec.namespace_depth+3) %>  index arguments.update op_type: 'create'
-  <%= '  '*(@spec.namespace_depth+3) %>else
-  <%= '  '*(@spec.namespace_depth+3) %>  index arguments
-  <%= '  '*(@spec.namespace_depth+3) %>end
-  <%= '  '*(@spec.namespace_depth+2) %>end
+if arguments[:id]
+  index arguments.update op_type: 'create'
+else
+  index arguments
+end
+end
 <%- else -%>
   <%- if @spec.method_name == 'get_field_mapping' %>
     arguments = arguments.clone
@@ -47,7 +47,7 @@ module Elasticsearch
     raise ArgumentError, "Required argument 'field' missing" unless _fields
   <%- else -%>
     <%- @spec.required_parts.each do |required| %><%# Arguments -%>
-      <%= '  '*(@spec.namespace_depth+3) + "raise ArgumentError, \"Required argument '#{required}' missing\" unless arguments[:#{required}]" + "\n" -%>
+      <%= "raise ArgumentError, \"Required argument '#{required}' missing\" unless arguments[:#{required}]" + "\n" -%>
     <%- end -%>
     arguments = arguments.clone
     <%- end -%>
@@ -63,17 +63,17 @@ module Elasticsearch
   alias_method :<%= @spec.method_name %>?, :<%= @spec.method_name %>
 <%- end -%>
 <%- if @spec.method_name == 'termvectors' %>
-
   # Deprecated: Use the plural version, {#termvectors}
   #
   def termvector(arguments={})
-    termvectors(arguments.merge endpoint: '_termvector')
+    warn "[DEPRECATION] `termvector` is deprecated. Please use the plural version, `termvectors` instead."
+    termvectors(arguments.merge(endpoint: '_termvector'))
   end
 <%- end -%>
-
 <%- @spec.namespace_depth.downto(1) do |i| -%>
-<%= '  '*(i-1) %>end
+  <%= '  '*(i-1) %>end
 <%- end if @spec.namespace_depth > 0 -%>
+
     end
   end
 end