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

data/lib/aws-sdk-code-generator/views/service_module.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'set'
 
 module AwsSdkCodeGenerator
@@ -5,11 +7,18 @@ module AwsSdkCodeGenerator
     class ServiceModule < View
 
       # @option options [required, Service] :service
+      # @option options [required, String] :prefix
       def initialize(options)
         @service = options.fetch(:service)
         @prefix = options.fetch(:prefix)
       end
 
+      # @return [String|nil]
+      def generated_src_warning
+        return if @service.protocol == 'api-gateway'
+        GENERATED_SRC_WARNING
+      end
+
       def full_name
         @service.full_name
       end
@@ -42,18 +51,26 @@ module AwsSdkCodeGenerator
         @service.gem_dependencies.keys
       end
 
+      # @return [Boolean] - Return true if a check is needed before
+      # requiring core to prevent circular dependencies.
+      # This is required to support backwards compatibility for SSO which was
+      # moved from the aws-sdk-sso gem into aws-sdk-core.
+      def require_core_guard?
+        name == 'SSO' || name == 'STS'
+      end
+
       # @return [Array<String>]
       def relative_requires
         paths = Set.new
-        paths << "#{prefix}/types"
-        paths << "#{prefix}/client_api"
-        paths << "#{prefix}/client"
-        paths << "#{prefix}/errors"
-        paths << "#{prefix}/waiters" if @service.waiters
-        paths << "#{prefix}/resource"
+        paths << "#{@prefix}/types"
+        paths << "#{@prefix}/client_api"
+        paths << "#{@prefix}/client"
+        paths << "#{@prefix}/errors"
+        paths << "#{@prefix}/waiters" if @service.waiters
+        paths << "#{@prefix}/resource"
         if @service.resources && @service.resources['resources']
           @service.resources['resources'].keys.each do |resource_name|
-            path = "#{prefix}/#{underscore(resource_name)}"
+            path = "#{@prefix}/#{underscore(resource_name)}"
             if paths.include?(path)
               raise "resource path conflict for `#{resource_name}'"
             else
@@ -61,7 +78,14 @@ module AwsSdkCodeGenerator
             end
           end
         end
-        paths << "#{prefix}/customizations"
+        paths << "#{@prefix}/customizations"
+        if @service.api['metadata']['protocolSettings'] &&
+          @service.api['metadata']['protocolSettings']['h2'] == 'eventstream'
+          paths << "#{@prefix}/async_client"
+          paths << "#{@prefix}/event_streams"
+        elsif eventstream_shape?
+          paths << "#{@prefix}/event_streams"
+        end
         paths.to_a
       end
 
@@ -70,16 +94,16 @@ module AwsSdkCodeGenerator
       end
 
       def example_operation_name
+        raise "no operations found for the service" if @service.api['operations'].empty?
         underscore(@service.api['operations'].keys.first)
-        nil
       end
 
-      private
-
-      def prefix
-        @prefix
+      def eventstream_shape?
+        @service.api['shapes'].each do |_, shape_ref|
+          return true if shape_ref['eventstream']
+        end
+        false
       end
-
     end
   end
 end

data/lib/aws-sdk-code-generator/views/spec/spec_helper.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module AwsSdkCodeGenerator
   module Views
     module Spec
@@ -13,11 +15,18 @@ module AwsSdkCodeGenerator
           @gem_dependencies = service.gem_dependencies.map do |gem_name, _|
             { dependency: gem_name }
           end
+          @custom = service.protocol == 'api-gateway'
         end
 
         attr_reader :gem_name
         attr_reader :gem_dependencies
 
+        # @return [String|nil]
+        def generated_src_warning
+          return if @custom
+          GENERATED_SRC_WARNING
+        end
+
       end
     end
   end

data/lib/aws-sdk-code-generator/views/types_module.rb

@@ -0,0 +1,329 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module AwsSdkCodeGenerator
+  module Views
+    class TypesModule < View
+
+      include Helper
+
+      # @option options [required, Service] :service
+      def initialize(options)
+        @service = options.fetch(:service)
+        @api = @service.api
+        @input_shapes = compute_input_shapes(@service.api)
+        @output_shapes = compute_output_shapes(@service.api)
+      end
+
+      # @return [String|nil]
+      def generated_src_warning
+        return if @service.protocol == 'api-gateway'
+        GENERATED_SRC_WARNING
+      end
+
+      def module_name
+        @service.module_name
+      end
+
+      # @return [Array<StructClass>]
+      def structures
+        unless @service.protocol_settings.empty?
+          if @service.protocol_settings['h2'] == 'eventstream'
+            @service.api['shapes'].each do |_, shape|
+              if shape['eventstream']
+                # add event trait to all members if not exists
+                shape['members'].each do |name, ref|
+                  @service.api['shapes'][ref['shape']]['event'] = true
+                end
+              end
+            end
+          end
+        end
+        @service.api['shapes'].inject([]) do |list, (shape_name, shape)|
+          # APIG model can have input/output shape with downcase and '__'
+          if @service.protocol == 'api-gateway'
+            shape_name = lstrip_prefix(upcase_first(shape_name))
+          end
+          # eventstream shape will be inheriting from enumerator
+          if shape['eventstream']
+            list
+          elsif shape['type'] == 'structure' && !shape['document']
+            struct_members = struct_members(shape)
+            sensitive_params = struct_members.select(&:sensitive).map do |m|
+              m.member_name.to_sym
+            end
+            list << StructClass.new(
+              class_name: shape_name,
+              members: struct_members,
+              sensitive_params: sensitive_params,
+              documentation: struct_class_docs(shape_name, shape),
+              union: shape['union']
+            )
+          else
+            list
+          end
+        end
+      end
+
+      # return [Array<EventStreamClass>]
+      def eventstreams
+        @service.api['shapes'].inject([]) do |list, (shape_name, shape)|
+          if shape['eventstream']
+            list << EventStreamClass.new(
+              class_name: shape_name,
+              types: struct_members(shape),
+              documentation: eventstream_class_docs(shape_name, shape)
+            )
+          else
+            list
+          end
+        end
+      end
+
+      private
+
+      def struct_members(shape)
+        return if shape['members'].nil?
+        members = shape['members'].map do |member_name, member_ref|
+          sensitive = !!(member_ref['sensitive'] ||
+            @api['shapes'][member_ref['shape']]['sensitive'])
+          StructMember.new(
+            member_name: underscore(member_name),
+            sensitive: sensitive
+          )
+        end
+        if shape['event']
+          members << StructMember.new(member_name: 'event_type')
+        end
+        members
+      end
+
+      def struct_class_docs(shape_name, shape)
+        join_docstrings([
+          html_to_markdown(Api.docstring(shape_name, @api)),
+          input_example_docs(shape_name, shape),
+          output_example_docs(shape_name, shape),
+          attribute_macros_docs(shape_name),
+          see_also_tag(shape_name),
+        ])
+      end
+
+      def eventstream_class_docs(shape_name, shape)
+        join_docstrings([
+          html_to_markdown(Api.docstring(shape_name, @api)),
+          input_example_docs(shape_name, shape),
+          eventstream_docs(shape_name),
+          see_also_tag(shape_name),
+        ])
+      end
+
+      def eventstream_docs(shape_name)
+        "EventStream is an Enumerator of Events.\n"\
+        " #event_types #=> Array, returns all modeled event types in the stream"
+      end
+
+      def output_example_docs(shape_name, shape)
+        if @output_shapes.include?(shape_name)
+          if shape['union']
+            "@note #{shape_name} is a union - when returned from an API call"\
+            ' exactly one value will be set and the returned type will'\
+            " be a subclass of #{shape_name} corresponding to the set member."
+          end
+        end
+      end
+
+      def input_example_docs(shape_name, shape)
+        if @input_shapes.include?(shape_name)
+          return if shape(shape_name)['members'].nil?
+          if shape(shape_name)['members'].empty?
+            '@api private'
+          elsif shape['union']
+            "@note #{shape_name} is a union - when making an API calls you"\
+            ' must set exactly one of the members.'
+          else
+            note = "@note When making an API call, you may pass #{shape_name}\n"
+            note += "  data as a hash:\n\n"
+            note += '      ' + SyntaxExampleHash.new(
+              shape: shape(shape_name),
+              api: @service.api,
+            ).format('      ')
+          end
+        end
+      end
+
+      def attribute_macros_docs(shape_name)
+        # APIG model downcase shape name in origin or "__" prefix in origin
+        if @service.protocol == 'api-gateway'
+          if shape(shape_name).nil?
+            if !shape(downcase_first(shape_name)).nil?
+              shape_name = downcase_first(shape_name)
+            elsif !shape(apig_prefix(shape_name)).nil?
+              shape_name = apig_prefix(shape_name)
+            else
+              shape_name = apig_prefix(downcase_first(shape_name))
+            end
+          end
+        end
+        return if shape(shape_name)['members'].nil?
+        shape(shape_name)['members'].map do |member_name, member_ref|
+          docs = Api.docstring(member_ref, @api).to_s
+          docs += idempotency_token_msg if idempotency_token?(member_ref)
+          docs = html_to_markdown(docs, line_width: 68)
+          docs = docs.to_s.lines.to_a.join('  ')
+          macro = "@!attribute [rw] #{underscore(member_name)}\n"
+          macro += "  #{docs}\n" unless docs == ''
+          macro += "  @return [#{Api.ruby_type(member_ref, @api)}]"
+          macro
+        end
+      end
+
+      def see_also_tag(shape_name)
+        uid = @api['metadata']['uid']
+        if @api['metadata']['protocol'] != 'api-gateway' && Crosslink.taggable?(uid)
+          Crosslink.tag_string(uid, shape_name)
+        end
+      end
+
+      def compute_input_shapes(api)
+        inputs = Set.new
+        (api['operations'] || {}).each do |_, operation|
+          visit_shapes(operation['input'], inputs) if operation['input']
+        end
+        inputs
+      end
+
+      def compute_output_shapes(api)
+        outputs = Set.new
+        (api['operations'] || {}).each do |_, operation|
+          visit_shapes(operation['output'], outputs) if operation['output']
+        end
+        outputs
+      end
+
+      def idempotency_token?(member_ref)
+        member_ref['idempotencyToken'] || shape(member_ref)['idempotencyToken']
+      end
+
+      def idempotency_token_msg
+        "<p><b>A suitable default value is auto-generated.</b> You should normally not need to pass this option.</p>"
+      end
+
+      def visit_shapes(shape_ref, shapes)
+        return if shapes.include?(shape_ref['shape']) # recursion
+        shapes << shape_ref['shape']
+        s = shape(shape_ref)
+        raise "cannot locate shape #{shape_ref['shape']}" if s.nil?
+        case s['type']
+        when 'structure'
+          return if s['members'].nil?
+          s['members'].each_pair do |_, member_ref|
+            visit_shapes(member_ref, shapes)
+          end
+        when 'list'
+          visit_shapes(s['member'], shapes)
+        when 'map'
+          visit_shapes(s['key'], shapes)
+          visit_shapes(s['value'], shapes)
+        end
+      end
+
+      def shape(shape_ref)
+        Api.resolve(shape_ref, @api)[1]
+      end
+
+      class EventStreamClass
+
+        def initialize(options)
+          @class_name = options.fetch(:class_name)
+          @types = options.fetch(:types)
+          @documentation = options.fetch(:documentation)
+          if @types.nil? || @types.empty?
+            @empty = true
+          else
+            @empty = false
+            @types.last.last = true
+          end
+        end
+
+        # @return [String]
+        attr_accessor :class_name
+
+        # @return [Array<StructMember>]
+        attr_accessor :types
+
+        # @return [String, nil]
+        attr_accessor :documentation
+
+        # @return [Boolean]
+        def empty?
+          @empty
+        end
+
+      end
+
+      class StructClass
+
+        def initialize(options)
+          @class_name = options.fetch(:class_name)
+          @members = options.fetch(:members)
+          @documentation = options.fetch(:documentation)
+          @sensitive_params = options.fetch(:sensitive_params)
+          @union = options.fetch(:union)
+          @members << StructMember.new(member_name: :unknown, member_class_name: 'Unknown') if @union
+          if @members.nil? || @members.empty?
+            @empty = true
+          else
+            @empty = false
+            @members.last.last = true
+          end
+        end
+
+        # @return [String]
+        attr_accessor :class_name
+
+        # @return [Array<StructMember>]
+        attr_accessor :members
+
+        # @return [String, nil]
+        attr_accessor :documentation
+
+        # @return [Array<Symbol>]
+        attr_accessor :sensitive_params
+
+        # @return [Boolean]
+        def union?
+          @union
+        end
+
+        # @return [Boolean]
+        def empty?
+          @empty
+        end
+      end
+
+      class StructMember
+
+        def initialize(options)
+          @member_name = options.fetch(:member_name)
+          @member_class_name = AwsSdkCodeGenerator::Helper::pascal_case(@member_name)
+          @sensitive = options.fetch(:sensitive, false)
+          @last = false
+        end
+
+        # @return [String]
+        attr_accessor :member_name
+
+        # @return [Boolean]
+        attr_accessor :sensitive
+
+        # @return [String]
+        attr_accessor :member_class_name
+
+        # @return [Boolean]
+        attr_accessor :last
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-code-generator/views/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module AwsSdkCodeGenerator
   module Views
     class Version < View

data/lib/aws-sdk-code-generator/views/waiters_module.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module AwsSdkCodeGenerator
+  module Views
+    class WaitersModule < View
+
+      def initialize(options)
+        @module_name = options.fetch(:module_name)
+        @waiters = Waiter.build_list(options.fetch(:waiters))
+        @custom = options.fetch(:custom)
+      end
+
+      # @return [String]
+      attr_reader :module_name
+
+      # @return [Array<Waiter>]
+      attr_reader :waiters
+
+      # @return [String|nil]
+      def generated_src_warning
+        return if @custom
+        GENERATED_SRC_WARNING
+      end
+
+      # @return [Boolean]
+      def waiters?
+        waiters.size > 0
+      end
+
+      # @return [String<Markdown>]
+      def waiters_markdown_table
+        Waiter.markdown_table(@waiters)
+      end
+
+    end
+  end
+end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'gemspec'
 
 module Views; end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module AwsSdkCodeGenerator
+  class Waiter
+
+    # @return [String]
+    attr_accessor :name
+
+    # @return [String]
+    attr_accessor :documentation
+
+    # @return [String]
+    attr_accessor :class_name
+
+    # @return [String]
+    attr_accessor :client_method
+
+    # @return [Integer]
+    attr_accessor :delay
+
+    # @return [Integer]
+    attr_accessor :max_attempts
+
+    # @return [String]
+    attr_accessor :acceptors
+
+    # @return [Boolean]
+    attr_accessor :last
+
+    class << self
+
+      # @return [Array<Waiter>]
+      def build_list(waiters)
+        waiters = waiters ? waiters['waiters'] : {}
+        waiters = waiters.map do |waiter_name, waiter|
+          Waiter.new.tap do |w|
+            w.name = Underscore.underscore(waiter_name)
+            w.class_name = waiter_name
+            w.client_method = Underscore.underscore(waiter['operation'])
+            w.delay = waiter['delay'].to_i
+            w.max_attempts = waiter['maxAttempts'].to_i
+            w.acceptors = acceptors(waiter['acceptors'])
+            w.documentation = Docstring.block_comment(waiter['description'])
+          end
+        end.sort_by(&:name)
+        waiters.last.last = true unless waiters.empty?
+        waiters
+      end
+
+      # @return [Map<String, Array<Waiter> >]
+      def build_operations_map(waiters)
+        operations_map = {}
+        waiters = build_list(waiters)
+        waiters.each do |w|
+          (operations_map[w.client_method] ||= []) << w
+        end
+        operations_map
+      end
+
+      # @param [Array<Waiter>]
+      # @return [String<Markdown>]
+      def markdown_table(waiters)
+        table = []
+        table << ['waiter_name', 'params', ':delay', ':max_attempts']
+        waiters.each do |waiter|
+          table << [
+            waiter.name,
+            "{Client##{waiter.client_method}}",
+            waiter.delay,
+            waiter.max_attempts
+          ]
+        end
+        Docstring.markdown_table(table)
+      end
+
+      private
+
+      def acceptors(acceptors)
+        acceptors.each do |acceptor|
+          if acceptor['argument']
+            acceptor['argument'] = Underscore.underscore_jmespath(
+              acceptor['argument']
+            )
+          end
+        end
+        HashFormatter.new(
+          wrap: false,
+          inline: false,
+          quote_strings: true
+        ).format(acceptors: acceptors)
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module AwsSdkCodeGenerator
+  class YardOptionTag
+
+    # @option options [required, String] :name
+    # @option options [Boolean] :required (false)
+    # @option options [required, String] :ruby_type
+    # @option options [String, nil] :docstring (nil)
+    # @option options [Object] :default_value
+    # @option options [String] :option_hash_name ('options')
+    def initialize(options)
+      @name = options.fetch(:name)
+      @ruby_type = options.fetch(:ruby_type)
+      @required = options.fetch(:required, false) ? 'required, ' : ''
+      @docstring = options.fetch(:docstring).to_s
+      @default_value = options[:default_value]
+      @option_hash_name = options.fetch(:option_hash_name, 'options')
+      @indent = options.fetch(:indent, "")
+    end
+
+    def build
+      if @docstring.empty?
+        first_line.rstrip
+      else
+        first_line + Docstring.block_comment(@docstring, gap: "   #{@indent}")
+      end
+    end
+    alias to_str build
+    alias to_s build
+
+    private
+
+    def first_line
+      "# #{@indent}@option #{@option_hash_name} [#{@required}#{@ruby_type}] :#{@name}#{default_value}\n"
+    end
+
+    def default_value
+      @default_value.nil? ? '' : " (#{@default_value.inspect})"
+    end
+
+  end
+end