aws-sdk-code-generator 0.1.0.pre → 0.2.4.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: cd7b6eb0cfae166558e734fdb8e7c9236f7f14d6
-  data.tar.gz: 8cad3f3e2213a13d558259216831b08e1e4d5323
+SHA256:
+  metadata.gz: 0cd62265104fa228849cca4ee26d749025e7ba94a0ff446885abc045a17a91cf
+  data.tar.gz: 537442139442f772fecb3e829a9a584a07bf6795757c01b90032f78c5b4fde99
 SHA512:
-  metadata.gz: c970544cd6c87e3794260f4dda931f717c9e7ef9dfb43693b35c0d22f0a3b1ec850b3ff281b7e9e825591905a2a45b19168337521c8039c2e648db3e66b1d525
-  data.tar.gz: 6a927656fc80f7df13cc27c03f1675a81fb3f000bcec4b6fb3ba6d672ad1e37a74296ccaff8b37137e3ce4912780bf1a1818f4b7c03e13ca3b8781f9a7375ade
+  metadata.gz: 7dd69754c3ad489c192c4db3986fc79376dbd34316f5d6d79694e5807824d36de9333762d49727a4e92525bbea4b0190803474641282499e116afd7955d6a162
+  data.tar.gz: a44c6a9fd0a8778bbe4d00c73dcc07584b1beac9c278671f006c349c7e7f0a36d6e8fa18084ebd61984769496abde3faf9037b85d09e40ce7c86d9f823030923

data/lib/aws-sdk-code-generator/api.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module AwsSdkCodeGenerator
+  module Api
+    class << self
+
+      # @param [Hash, String] shape_or_shape_ref
+      # @param [Hash, String] api
+      # @return [String, nil]
+      def docstring(shape_or_shape_ref, api)
+        ref, shape = resolve(shape_or_shape_ref, api)
+        # APIG models, downcase shape name in origin or "__" prefix in origin
+        # code-gen shape name might have been changed (upcased_first/lstrip_prefix/both),
+        # when shape cannot be located with current shape name, try to resolve shape with
+        # (downcase_fist/apig_prefix/both) original names
+        if shape.nil?
+          ref, shape = resolve(AwsSdkCodeGenerator::Helper.downcase_first(shape_or_shape_ref), api)
+          if shape.nil?
+            ref, shape = resolve(AwsSdkCodeGenerator::Helper.apig_prefix(shape_or_shape_ref), api)
+            if shape.nil?
+              ref, shape = resolve(AwsSdkCodeGenerator::Helper.apig_prefix(downcase_first(shape_or_shape_ref)), api)
+            end
+          end
+        end
+        ref['documentation'] || shape['documentation']
+      end
+
+      # @param [Hash, String] shape_or_shape_ref
+      # @param [Hash, String] api
+      # @return [Hash<ShapeRef>, Hash<Shape>]
+      def resolve(shape_or_shape_ref, api)
+        if String === shape_or_shape_ref
+          [{}, api['shapes'][shape_or_shape_ref]]
+        elsif shape_or_shape_ref['type']
+          [{}, shape_or_shape_ref]
+        else
+          [shape_or_shape_ref, api['shapes'][shape_or_shape_ref['shape']]]
+        end
+      end
+
+      # @param [String, Hash] shape_name_or_ref
+      # @return [Hash]
+      def shape(shape_name_or_ref, api)
+        case shape_name_or_ref
+        when Hash then api.fetch('shapes').fetch(shape_name_or_ref.fetch('shape'))
+        when String then api.fetch('shapes').fetch(shape_name_or_ref)
+        end
+      end
+
+      def ruby_input_type(shape_ref, api, operation = nil, options = {})
+        nested = options.fetch(:nested, false)
+        _, shape = resolve(shape_ref, api)
+        case shape['type']
+        when 'byte' then 'Integer<byte>'
+        when 'blob'
+          if streaming_input?(shape, operation)
+            'String, IO'
+          else
+            'String, StringIO, File'
+          end
+        when 'boolean' then 'Boolean'
+        when 'character' then 'String<character>'
+        when 'double' then 'Float'
+        when 'float' then 'Float'
+        when 'integer' then 'Integer'
+        when 'list'
+          if nested
+            "Array"
+          else
+            "Array<#{ruby_input_type(shape['member'], api, operation, nested: true)}>"
+          end
+        when 'long' then 'Integer'
+        when 'map'
+          if nested
+            "Hash"
+          else
+            "Hash<String,#{ruby_input_type(shape['value'], api, operation, nested: true)}>"
+          end
+        when 'string' then 'String'
+        when 'structure'
+          if shape['document']
+            'Hash,Array,String,Numeric,Boolean'
+          else
+            "Types::#{shape_ref['shape']}"
+          end
+        when 'timestamp' then 'Time,DateTime,Date,Integer,String'
+        else
+          raise "unhandled type #{shape.type}.inspect"
+        end
+      end
+
+      def ruby_type(shape_ref, api)
+        _, shape = resolve(shape_ref, api)
+        case shape['type']
+        when 'blob' then streaming?(shape_ref, api) ? 'IO' : 'String'
+        when 'boolean' then 'Boolean'
+        when 'byte' then 'Integer<byte>'
+        when 'character' then 'String<character>'
+        when 'double' then 'Float'
+        when 'float' then 'Float'
+        when 'integer' then 'Integer'
+        when 'list' then "Array<#{ruby_type(shape['member'], api)}>"
+        when 'long' then 'Integer'
+        when 'map' then "Hash<String,#{ruby_type(shape['value'], api)}>"
+        when 'string' then streaming?(shape_ref, api) ? 'IO' : 'String'
+        when 'structure'
+          if shape['document']
+            'Hash,Array,String,Numeric,Boolean'
+          else
+            "Types::#{shape_ref['shape']}"
+          end
+        when 'timestamp' then 'Time'
+        else
+          raise "unhandled type #{shape['type'].inspect}"
+        end
+      end
+
+      # @return [Boolean]
+      def streaming?(shape_or_shape_ref, api)
+        ref, shape = resolve(shape_or_shape_ref, api)
+        ref['streaming'] || shape['streaming'] ||
+          ref['eventstream'] || shape['eventstream']
+      end
+
+      # @return [Boolean]
+      def eventstream?(shape_or_shape_ref, api)
+        ref, shape = resolve(shape_or_shape_ref, api)
+        ref['eventstream'] || shape['eventstream']
+      end
+
+      # @return [Boolean]
+      def streaming_input?(shape, operation)
+        shape['streaming'] && operation &&
+          operation['authtype'] == "v4-unsigned-body"
+      end
+
+      def plural?(resource)
+        plural = false
+        (resource['identifiers'] || []).each do |i|
+          if i['path'] && i['path'].include?('[]')
+            plural = true
+            break
+          end
+        end
+        plural = true if resource['data'] && resource['data'].include?('[]')
+        plural
+      end
+    end
+  end
+end

data/lib/aws-sdk-code-generator/apply_docs.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module AwsSdkCodeGenerator
   class ApplyDocs
 
@@ -17,17 +19,28 @@ module AwsSdkCodeGenerator
     def apply_docs(docs)
       @api['documentation'] = docs['service']
       docs['operations'].each do |name, docstring|
+        next unless @api['operations'][name]
         @api['operations'][name]['documentation'] = docstring
       end
       docs['shapes'].each do |shape_name, shape_docs|
+        next unless @api['shapes'][shape_name]
         @api['shapes'][shape_name]['documentation'] = shape_docs['base']
         shape_docs['refs'].each do |ref, ref_docs|
           ref_shape, ref_member = ref.split('$')
+          next unless @api['shapes'][ref_shape]
           case @api['shapes'][ref_shape]['type']
           when 'structure'
-            @api['shapes'][ref_shape]['members'][ref_member]['documentation'] = ref_docs
+            shape = @api['shapes'][ref_shape]
+            if shape && shape['members']
+              member = shape['members'][ref_member]
+              member['documentation'] = ref_docs if member
+            end
           when 'list', 'map'
-            @api['shapes'][ref_shape][ref_member]['documentation'] = ref_docs
+            shape = @api['shapes'][ref_shape]
+            if shape
+              member = shape[ref_member]
+              member['documentation'] = ref_docs if member
+            end
           end
         end
       end

data/lib/aws-sdk-code-generator/client_constructor.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module AwsSdkCodeGenerator
+  class ClientConstructor
+
+    # @option options [required, PluginList] :plugins
+    def initialize(options)
+      plugin_options = documented_plugin_options(options.fetch(:plugins))
+      documentation = {}
+      plugin_options.each do |option|
+        documentation[option.name] = YardOptionTag.new(
+          name: option.name,
+          required: option.required,
+          ruby_type: option.doc_type,
+          default_value: option.doc_default(options),
+          docstring: option.docstring,
+          indent: "  "
+        ).to_s
+      end
+      @documentation = Docstring.join_docstrings(documentation.values, block_comment: false)
+    end
+
+    # @return [String]
+    attr_reader :documentation
+
+    private
+
+    def documented_plugin_options(plugins)
+      i = 0
+      plugins.map(&:options).flatten.select(&:documented?).sort_by do |opt|
+        # Stable sort, first required options, then sort by name, then if
+        # two plugins of the same name, use an incrementer.
+        # options.fetch(:plugins) will be ordered.
+        [opt.required ? 'a' : 'b', opt.name, i += 1] #, opt.override ? 'b' : 'a']
+      end
+    end
+
+  end
+end

data/lib/aws-sdk-code-generator/client_operation_documentation.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+module AwsSdkCodeGenerator
+  class ClientOperationDocumentation
+
+    # get all of the enumerable methods that may conflict with members
+    # count has special handling in UnsafeEnumerableMethods
+    ENUMERABLE_METHODS = Class.new.new.extend(Enumerable).methods - [:count]
+
+    # @option options [required, String] :method_name
+    # @option options [required, Hash] :operation
+    # @option options [required, Hash] :api
+    # @option options [Array<Hash>] :examples
+    def initialize(options)
+      @name = options.fetch(:name)
+      @method_name = options.fetch(:method_name)
+      @operation = options.fetch(:operation)
+      @api = options.fetch(:api)
+      @client_examples = options.fetch(:client_examples, [])
+      @examples = options.fetch(:examples)
+      @module_name = options.fetch(:module_name)
+      @async_client = options[:async_client] || false
+      @pager = options[:pager]
+      @waiters = options[:waiters]
+    end
+
+    # @return [String]
+    attr_reader :method_name
+
+    # @return [String]
+    attr_reader :module_name
+
+    # @return [Hash]
+    attr_reader :operation
+
+    # @return [Hash]
+    attr_reader :api
+
+    # @return [Array<Hash>]
+    attr_reader :examples
+
+    # @return [Array<Hash>]
+    attr_reader :client_examples
+
+    # @return [Hash]
+    attr_reader :pager
+
+    # @return [String]
+    def to_str
+      Docstring.join_docstrings([
+        docstring(operation),
+        response_target_tag(operation, api),
+        option_tags(operation, api),
+        return_tag(operation, api),
+        pagination(pager, operation, api),
+        generated_examples(operation, api),
+        eventstream_examples(module_name, method_name, operation, api),
+        shared_examples(examples, operation, api),
+        given_examples(client_examples),
+        @async_client ? async_request_syntax_example(method_name, operation, api)
+        : request_syntax_example(method_name, operation, api),
+        response_structure_example(operation, api),
+        waiters_tag(@waiters),
+        see_also_tag(@name, api),
+      ], block_comment: false)
+    end
+    alias to_s to_str
+
+    private
+
+    def docstring(operation)
+      Docstring.block_comment(
+        Docstring.html_to_markdown(operation['documentation'])
+      )
+    end
+
+    def response_target_tag(operation, api)
+      if output = Api.shape(operation['output'], api)
+        if output['payload'] && output['members'][output['payload']]['streaming']
+          YardOptionTag.new(
+            name: 'response_target',
+            ruby_type: 'String, IO',
+            option_hash_name: 'params',
+            required: false,
+            docstring: 'Where to write response data, file path, or IO object.'
+          ).to_s
+        end
+      end
+    end
+
+    def option_tags(operation, api)
+      if operation['input']
+        shape = Api.shape(operation['input'], api)
+        return if shape['members'].nil?
+        shape['members'].map do |member_name, member_ref|
+          next if member_ref['documented'] === false
+          # input eventstream is not provided by params
+          member_shape = Api.shape(member_ref['shape'], api)
+          next if member_shape['eventstream'] === true
+          docstring = Api.docstring(member_ref, api)
+          if member_ref['idempotencyToken']
+            docstring = docstring.to_s + "<p><b>A suitable default value is auto-generated.** You should normally not need to pass this option.</b></p>"
+          end
+          if member_ref['jsonvalue']
+            docstring = docstring.to_s + "<p><b>SDK automatically handles json encoding and base64 encoding for you when the required value (Hash, Array, etc.) is provided according to the description.</b></p>"
+          end
+          if member_shape['document']
+            docstring = docstring.to_s + "<p>Document type used to carry open content (Hash,Array,String,Numeric,Boolean). A document type value is serialized using the same format as its surroundings and requires no additional encoding or escaping.</p>"
+          end
+          if member_ref['union']
+            docstring = docstring.to_s + "<p>This is a union type and you must set exactly one of the members.</p>"
+          end
+          YardOptionTag.new(
+            name: Underscore.underscore(member_name),
+            ruby_type: Api.ruby_input_type(member_ref, api, operation),
+            required: shape.fetch('required', []).include?(member_name),
+            docstring: Docstring.html_to_markdown(docstring),
+            option_hash_name: 'params',
+          ).to_s
+        end
+      else
+        []
+      end
+    end
+
+    def return_tag(operation, api)
+      output = Api.shape(operation['output'], api)
+      if output && output['members'] && output['members'].size > 0
+        shape_name = operation.fetch('output').fetch('shape')
+        type = "Types::#{shape_name}"
+        _, shape = Api.resolve(shape_name, api)
+        # add rest body streaming if qualified
+        unless shape['payload'].nil?
+          _, member_shape = Api.resolve(shape['payload'], api)
+          unless member_shape.nil?
+            member_shape['streaming'] = member_shape['type'] == 'blob' ||
+              member_shape['type'] == 'string'
+          end
+        end
+        methods = shape['members'].map do |member_name, member_ref|
+          member_type = Docstring.escape_html(Api.ruby_type(member_ref, api))
+          method_name = Underscore.underscore(member_name)
+          if ENUMERABLE_METHODS.include?(method_name.to_sym)
+            "#   * {#{type}##{method_name} #data.#{method_name}} => #{member_type} (This method conflicts with a method on Response, call it through the data member)"
+          else
+            "#   * {#{type}##{method_name} ##{method_name}} => #{member_type}"
+          end
+        end
+        "# @return [#{type}] Returns a {Seahorse::Client::Response response} object which responds to the following methods:\n#\n" + methods.join("\n")
+      else
+        "# @return [Struct] Returns an empty {Seahorse::Client::Response response}."
+      end
+    end
+
+    def pagination(pager, operation, api)
+      return unless pager
+
+      input = Array(pager['input_token'])
+      output = Array(pager['output_token'])
+      tokens = {}
+      input.each.with_index do |key, n|
+        tokens[Underscore.underscore_jmespath(output[n])] = Underscore.underscore_jmespath(key)
+      end
+
+      return if tokens.empty?
+
+      "# The returned {Seahorse::Client::Response response}" \
+      " is a pageable response and is Enumerable. For details on usage see" \
+      " {Aws::PageableResponse PageableResponse}."
+    end
+
+    def shared_examples(examples, operation, api)
+      return if examples.nil? || examples['examples'].nil? || examples['examples'][@name].nil?
+      begin # skip broken/nil examples
+        example_block = []
+        examples['examples'][@name].each do |example|
+          comments = example['comments']
+          input = SharedExample.new(
+            example['input'],
+            method_name,
+            operation,
+            api,
+            (comments.nil? ? '' : comments['input'])).to_str_input
+          parts = []
+          parts << "#\n"
+          parts << "# @example Example: #{example['title']}\n#\n"
+          if example['description'] && example['description'].length > 0
+            parts << "#{Helper.wrap_string(example['description'], 120, "#   # ")}\n#\n"
+          end
+          parts += input.lines.map { |line| "#   " + line }
+          if example['output']
+            output = SharedExample.new(
+              example['output'],
+              method_name,
+              operation,
+              api,
+              (comments.nil? ? '' : comments['output'])).to_str_output
+            parts << "\n#\n#   resp.to_h outputs the following:\n"
+            parts += output.lines.map { |line| "#   " + line }
+          end
+          example_block << parts.join
+        end
+        example_block.join("\n")
+      rescue
+        puts "Invalid example for operation: #{@name}"
+        nil
+      end
+    end
+
+    def generated_examples(operation, api)
+      nil
+    end
+
+    def eventstream_examples(module_name, method_name, operation, api)
+      return unless !!Helper.eventstream_output?(operation, api)
+      EventStreamExample.new(
+        api: api,
+        operation: operation,
+        method_name: method_name,
+        module_name: module_name,
+        receiver: 'client',
+        resp_var: 'resp'
+      ).format
+    end
+
+    def given_examples(client_examples)
+      client_examples.map do |example|
+        name = example[:name]
+        code = example[:code]
+        "# @example #{name}\n" + Docstring.block_comment(code, gap: '   ')
+      end
+    end
+
+    def request_syntax_example(method_name, operation, api)
+      SyntaxExample.new(
+        api: api,
+        shape: Api.shape(operation['input'], api),
+        method_name: method_name,
+        receiver: 'client',
+        resp_var: 'resp',
+      ).format
+    end
+
+    def async_request_syntax_example(method_name, operation, api)
+      SyntaxExample.new(
+        api: api,
+        shape: Api.shape(operation['input'], api),
+        method_name: method_name,
+        receiver: 'async_client',
+        resp_var: 'async_resp',
+        async: true
+      ).format
+    end
+
+    def response_structure_example(operation, api)
+      output = Api.shape(operation['output'], api) if operation['output']
+      if output && output['members'] && output['members'].size > 0
+        Docstring.block_comment(ClientResponseStructureExample.new(
+          shape_ref: operation['output'],
+          api: api
+        ).to_s)
+      end
+    end
+
+    def waiters_tag(waiters)
+      return unless waiters && waiters.size > 0
+
+      waiters_doc = waiters.map do |w|
+        "#   * #{w.name}"
+      end
+      "#\n# The following waiters are defined for this operation (see {Client#wait_until} for detailed usage):\n#\n" + waiters_doc.join("\n")
+    end
+
+    def see_also_tag(operation, api)
+      uid = api['metadata']['uid']
+      if api['metadata']['protocol'] != 'api-gateway' && Crosslink.taggable?(uid)
+        "# " + Crosslink.tag_string(uid, operation)
+      end
+    end
+
+  end
+end

data/lib/aws-sdk-code-generator/client_operation_list.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module AwsSdkCodeGenerator
+  class ClientOperationList
+
+    include Enumerable
+
+    def initialize(options)
+      api = options.fetch(:api)
+      examples = options.fetch(:examples, {})
+      module_name = options.fetch(:module_name)
+      protocol_settings = options.fetch(:protocol_settings, {})
+      client_examples = options.fetch(:client_examples, {})
+      paginators = options.fetch(:paginators, {})
+      operation_waiters = Waiter.build_operations_map(options[:waiters])
+
+      @operations = api['operations'].inject([]) do |ops, (name, operation)|
+        method_name = Underscore.underscore(name)
+        waiters = operation_waiters[method_name]
+
+        async_client = options[:async_client] || false
+        es_output = AwsSdkCodeGenerator::Helper.eventstream_output?(operation, api)
+        es_input = AwsSdkCodeGenerator::Helper.eventstream_input?(operation, api)
+        if es_input || es_output
+          # eventstreaming operations
+          if protocol_settings['h2'] == 'eventstream'
+            # h2 supported, only generate for async client
+            if async_client
+              if es_input == es_output
+                # input & output eventstream sharing
+                # same eventstream shape
+                # see EventStreamModule
+                es_input = "Input" + es_input
+                es_output = "Output" + es_output
+              end
+              ops << Operation.new(
+                name: method_name,
+                documentation: ClientOperationDocumentation.new(
+                  name: name,
+                  module_name: module_name,
+                  method_name: method_name,
+                  operation: operation,
+                  api: api,
+                  examples: examples,
+                  client_examples: client_examples[method_name] || [],
+                  async_client: true
+                ).to_s,
+                streaming: AwsSdkCodeGenerator::Helper.operation_streaming?(operation, api),
+                eventstream_output: es_output,
+                eventstream_input: es_input
+              )
+            end
+          elsif !es_input && es_output && !async_client
+            # http1.1 only support eventstream at output
+            ops << Operation.new(
+              name: method_name,
+              documentation: ClientOperationDocumentation.new(
+                name: name,
+                module_name: module_name,
+                method_name: method_name,
+                operation: operation,
+                api: api,
+                examples: examples,
+                client_examples: client_examples[method_name] || [],
+                async_client: false
+              ).to_s,
+              streaming: AwsSdkCodeGenerator::Helper.operation_streaming?(operation, api),
+              eventstream_output: es_output,
+              eventstream_input: false
+            )
+          end
+        elsif !async_client
+          # non streaming operations
+          # generate at sync client only
+          ops << Operation.new(
+            name: method_name,
+            documentation: ClientOperationDocumentation.new(
+              name: name,
+              module_name: module_name,
+              method_name: method_name,
+              operation: operation,
+              api: api,
+              examples: examples,
+              client_examples: client_examples[method_name] || [],
+              async_client: false,
+              pager: paginators && paginators['pagination'][name],
+              waiters: waiters
+            ).to_s,
+            streaming: AwsSdkCodeGenerator::Helper.operation_streaming?(operation, api),
+            eventstream_output: false,
+            eventstream_input: false
+          )
+        end
+
+        ops
+      end
+    end
+
+    # @return [Enumerable<Operation>]
+    def each(&block)
+      @operations.each(&block)
+    end
+
+    class Operation
+
+      def initialize(options)
+        @name = options.fetch(:name)
+        @documentation = options.fetch(:documentation)
+        @streaming = options.fetch(:streaming)
+        @eventstream_output = !!options.fetch(:eventstream_output)
+        @eventstream_input = !!options.fetch(:eventstream_input)
+        @output_eventstream_member = @eventstream_output ?
+          options.fetch(:eventstream_output) : nil
+        @input_eventstream_member = @eventstream_input ?
+          options.fetch(:eventstream_input) : nil
+        @bidirectional = @eventstream_output && @eventstream_input
+      end
+
+      # @return [String]
+      attr_reader :name
+
+      # @return [String, nil]
+      attr_reader :documentation
+
+      # @return [Boolean]
+      attr_reader :eventstream_input
+
+      # @return [Boolean]
+      attr_reader :eventstream_output
+
+      # @return [String]
+      attr_reader :input_eventstream_member
+
+      # @return [String]
+      attr_reader :output_eventstream_member
+
+      # @return [Boolean]
+      attr_reader :bidirectional
+
+      def block_option
+        if @streaming
+          ", &block"
+        end
+      end
+
+    end
+  end
+end