elasticsearch-api 8.18.0 → 9.0.1

data/utils/thor/endpoint_specifics.rb

@@ -1,158 +0,0 @@
-# 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
-    # Handles specific exceptional parameters and code snippets that need to be
-    # included in the generated code. This module is included in SourceGenerator
-    # so its methods can be used from the ERB template (method.erb). This will
-    # potentially be refactored into different templates.
-    module EndpointSpecifics
-      # Endpoints that need Utils.__rescue_from_not_found
-      IGNORE_404 = %w[
-        exists
-        indices.exists
-        indices.exists_alias
-        indices.exists_template
-      ].freeze
-
-      # Endpoints that need Utils.__rescue_from_not_found if the ignore
-      # parameter is included
-      COMPLEX_IGNORE_404 = %w[
-        clear_scroll
-        delete
-        get
-        indices.delete
-        indices.delete_template
-        indices.flush_synced
-        query_rules.delete_ruleset
-        security.get_role
-        security.get_user
-        snapshot.delete
-        snapshot.delete_repository
-        snapshot.get
-        snapshot.get_repository
-        snapshot.status
-        update
-        watcher.delete_watch
-      ].freeze
-
-      # Endpoints that need params[:h] listified
-      H_PARAMS = %w[aliases allocation count health indices nodes pending_tasks
-                    recovery shards thread_pool].freeze
-
-      # Function that adds the listified h param code
-      def specific_params(namespace, method_name)
-        params = []
-        if H_PARAMS.include?(method_name) && namespace == 'cat'
-          if method_name == 'nodes'
-            params << 'params[:h] = Utils.__listify(params[:h], escape: false) if params[:h]'
-          else
-            params << 'params[:h] = Utils.__listify(params[:h]) if params[:h]'
-          end
-        end
-        params
-      end
-
-      def needs_ignore_404?(endpoint)
-        IGNORE_404.include? endpoint
-      end
-
-      def needs_complex_ignore_404?(endpoint)
-        COMPLEX_IGNORE_404.include? endpoint
-      end
-
-      def module_name_helper(name)
-        return name.upcase if %w[sql ssl].include? name
-
-        name.split('_').map(&:capitalize).map{ |n| n == 'Xpack' ? 'XPack' : n }.join
-      end
-
-      def ping_perform_request
-        <<~SRC
-          begin
-            perform_request(method, path, params, body, headers, request_opts).status == 200 ? true : false
-          rescue Exception => e
-            if e.class.to_s =~ /NotFound|ConnectionFailed/ || e.message =~ /Not\s*Found|404|ConnectionFailed/i
-              false
-            else
-              raise e
-            end
-          end
-        SRC
-      end
-
-      def msearch_body_helper
-        <<~SRC
-          case
-          when body.is_a?(Array) && body.any? { |d| d.has_key? :search }
-            payload = body.inject([]) do |sum, item|
-                meta = item
-                data = meta.delete(:search)
-
-                sum << meta
-                sum << data
-                sum
-              end.map { |item| Elasticsearch::API.serializer.dump(item) }
-            payload << "" unless payload.empty?
-            payload = payload.join("\\n")
-          when body.is_a?(Array)
-            payload = body.map { |d| d.is_a?(String) ? d : Elasticsearch::API.serializer.dump(d) }
-            payload << "" unless payload.empty?
-            payload = payload.join("\\n")
-          else
-            payload = body
-          end
-        SRC
-      end
-
-      def msearch_template_body_helper
-        <<~SRC
-          case
-          when body.is_a?(Array)
-            payload = body.map { |d| d.is_a?(String) ? d : Elasticsearch::API.serializer.dump(d) }
-            payload << "" unless payload.empty?
-            payload = payload.join("\n")
-          else
-            payload = body
-          end
-        SRC
-      end
-
-      def bulk_body_helper
-        <<~SRC
-          payload = if body.is_a? Array
-                      Elasticsearch::API::Utils.__bulkify(body)
-                    else
-                      body
-                    end
-        SRC
-      end
-
-      def find_structure_body_helper
-        bulk_body_helper
-      end
-
-      def bulk_doc_helper(info)
-        <<~SRC
-          # @option arguments [String|Array] :body #{info}. Array of Strings, Header/Data pairs,
-          # or the conveniency "combined" format can be passed, refer to Elasticsearch::API::Utils.__bulkify documentation.
-        SRC
-      end
-    end
-  end
-end

data/utils/thor/generate_source.rb

@@ -1,127 +0,0 @@
-# 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.
-
-# encoding: UTF-8
-
-require 'thor'
-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'
-
-module Elasticsearch
-  module API
-    # A command line application based on [Thor](https://github.com/wycats/thor),
-    # which will read the JSON API spec file(s), and generate
-    # the Ruby source code (one file per API endpoint) with correct
-    # module namespace, method names, and RDoc documentation,
-    # as well as test files for each endpoint.
-    #
-    # Specific exceptions and code snippets that need to be included are written
-    # in EndpointSpecifics (generator/endpoint_specifics) and the module is included
-    # here.
-    #
-    class SourceGenerator < Thor
-      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 = BuildHashHelper.build_hash
-        self.class.source_root File.expand_path(__dir__)
-        generate_source
-
-        # -- Tree output
-        print_tree if options[:verbose]
-      end
-
-      private
-
-      def generate_source
-        output = FilesHelper.output_dir
-        cleanup_directory!(output)
-
-        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.skippable?
-
-          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]
-        end
-        run_rubocop
-        BuildHashHelper.add_hash(@build_hash)
-      end
-
-      def generate_tests
-        copy_file 'templates/test_helper.rb', @output.join('test').join('test_helper.rb')
-
-        @test_directory = @output.join('test/api').join(@module_namespace.join('/'))
-        @test_file      = @test_directory.join("#{@method_name}_test.rb")
-
-        empty_directory @test_directory
-        template 'templates/test.erb', @test_file
-
-        print_source_code(@test_file) if options[:verbose]
-      end
-
-      def print_source_code(path_to_file)
-        colorized_output = CodeRay.scan_file(path_to_file, :ruby).terminal
-        lines            = colorized_output.split("\n")
-        formatted        = lines.first + "\n" + lines[1, lines.size].map { |l| ' ' * 14 + l }.join("\n")
-
-        say_status('ruby', formatted, :yellow)
-      end
-
-      def print_tree
-        return unless `which tree > /dev/null 2>&1; echo $?`.to_i < 1
-
-        lines = `tree #{@output}`.split("\n")
-        say_status('tree', lines.first + "\n" + lines[1, lines.size].map { |l| ' ' * 14 + l }.join("\n"))
-      end
-
-      def cleanup_directory!(output)
-        Dir["#{output}/**/*.rb"].each do |file|
-          # file = File.join(@output, f)
-          File.delete(file) unless (['.', '..'].include? file) || Pathname(file).directory?
-        end
-      end
-
-      def run_rubocop
-        system("rubocop -c ./thor/.rubocop.yml --format autogenconf -a #{FilesHelper::output_dir}")
-      end
-    end
-  end
-end

data/utils/thor/generator/build_hash_helper.rb

@@ -1,64 +0,0 @@
-# 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

@@ -1,62 +0,0 @@
-# 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

@@ -1,68 +0,0 @@
-# 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 'pathname'
-require_relative '../../../lib/elasticsearch/api/version.rb'
-
-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
-
-      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
-
-        # Path to directory to copy generated files
-        def output_dir
-          Pathname(OUTPUT_DIR)
-        end
-
-        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}/")
-          end
-        end
-      end
-
-      def cleanup_output_dir!
-        FileUtils.remove_dir(OUTPUT_DIR)
-        Dir.mkdir(OUTPUT_DIR)
-      end
-    end
-  end
-end

data/utils/thor/lister.rb

@@ -1,57 +0,0 @@
-# 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.
-
-# encoding: UTF-8
-
-require 'thor'
-
-require 'pathname'
-
-module Elasticsearch
-  module API
-    class Lister < Thor
-      namespace 'api'
-
-      DEFAULT_PATH = '../../tmp/elasticsearch/rest-api-spec/src/main/resources/rest-api-spec/api/'.freeze
-
-      desc "list <PATH DIRECTORY WITH JSON SPEC FILES>", "List all the REST API endpoints from the JSON specification"
-      method_option :verbose,  type: :boolean, default: false, desc: 'Output more information'
-      method_option :format,   default: 'text', desc: 'Output format (text, json)'
-      def list(directory = DEFAULT_PATH)
-        input = Pathname(directory).join('*.json')
-        apis = Dir[input.to_s].map do |f|
-          File.basename(f, '.json')
-        end.sort
-
-        if options[:verbose]
-          say_status 'Count', apis.size
-          say '▬'*terminal_width
-        end
-
-        case options[:format]
-          when 'text'
-            apis.each { |a| puts "* #{a}" }
-          when 'json'
-            puts apis.inspect
-          else
-            puts "[!] ERROR: Unknown output format '#{options[:format]}'"
-            exit(1)
-        end
-      end
-    end
-  end
-end

data/utils/thor/templates/_body.erb

@@ -1,34 +0,0 @@
-<%#
-# 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.
-%>
-<%-
-case @spec.endpoint_name
-when 'mtermvectors'
--%>
-  body = if(ids = arguments.delete(:ids))
-    { :ids => ids }
-  else
-    arguments.delete(:body)
-  end
-<%- when 'cluster.reroute', 'cluster.put_settings' %>
-  body = arguments.delete(:body) || {}
-<%- when 'ml.find_file_structure' %>
-  body = Utils.__bulkify(arguments.delete(:body))
-<%- else -%>
-  body   = <%= @spec.body.nil? ? 'nil' : 'arguments.delete(:body)' %>
-<%- end -%>

data/utils/thor/templates/_documentation_top.erb

@@ -1,56 +0,0 @@
-<%#
-# 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.
-%>
-<%- if @spec.documentation['description'] -%>
-  # <%= @spec.documentation['description'].gsub("\n", "\n  # ") -%>
-<%- else %>
-  # TODO: Description
-<%- end %>
-<%= stability_doc_helper(@spec.stability) -%>
-#
-<%- unless @spec.path_parts.nil? || @spec.path_parts.empty? %><%# URL parts -%>
-  <%- @spec.path_parts.each do |name, info| -%>
-    <%= docs(name, info) -%>
-  <%- end -%>
-<%- end -%><%# Body -%>
-<%# URL parameters -%>
-<%- @spec.params.each do |name, info| -%>
-  <%= 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 -%>
-    <%= '# @option arguments [Hash] :body ' + (@spec.body['description'] ?
-                                               @spec.body['description'].strip : 'TODO: Description') +
-                                              (@spec.body['required'] ? ' (*Required*)' : '') + "\n"
-    -%>
-  <%- end -%>
-<%- end -%>
-<% if @spec.deprecation_note -%>
-  #
-  # *Deprecation notice*:
-  # <%=  @spec.deprecation_note['description'] %>
-  # Deprecated since version <%=  @spec.deprecation_note['version'] %>
-  #
-<% end -%>
-#
-<%# Documentation link -%>
-# @see <%= @spec.documentation['url'] ? Elasticsearch::API::FilesHelper.documentation_url(@spec.documentation['url']) : "[TODO]" %>
-#

data/utils/thor/templates/_method_setup.erb

@@ -1,37 +0,0 @@
-<%#
-# 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.
-%>
-<%- @spec.path_parts.each do |name, _| %>
-  <%- unless @spec.method_name == 'get_field_mapping' && name == 'fields' %>
-    <%= "_#{name}" %> = arguments.delete(:<%=name %>)
-  <%- end -%>
-<%- end -%>
-
-method = <%= @spec.http_method %>
-<%- if @spec.method_name == 'termvectors' %>
-  arguments.delete(:endpoint)
-<%- end -%>
-path   = <%= @spec.http_path %>
-<%- if !@spec.params.empty? || needs_ignore_404?(@spec.endpoint_name) || needs_complex_ignore_404?(@spec.endpoint_name)-%>
-  params = Utils.process_params(arguments)
-<%- else -%>
-  params = {}
-<%- end -%>
-<%- @spec.specific_params.each do |param| -%>
-  <%= param %>
-<%- end -%>