elasticsearch-api 8.12.2 → 8.14.0

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