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

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

@@ -1,5 +1,8 @@
-require 'kramdown'
+# frozen_string_literal: true
+
 require 'set'
+# kramdown
+require 'kramdown'
 
 # disable inline attribute lists
 class Kramdown::Converter::Kramdown
@@ -7,6 +10,7 @@ class Kramdown::Converter::Kramdown
     nil
   end
 end
+# end kramdown
 
 module AwsSdkCodeGenerator
   module Helper
@@ -21,37 +25,21 @@ module AwsSdkCodeGenerator
       end
     end
 
-    # @param [Array<Array<String>>]
-    def markdown_table(table)
-      # compute the width of each column by scanning for longest values
-      column_width = lambda do |col|
-        table.map { |row| row[col].size }.max
-      end
-      widths = [
-        column_width.call(0),
-        column_width.call(1),
-        column_width.call(2),
-        column_width.call(3),
-      ]
-
-      # insert a dashed line after the header row
-      table = [
-        table[0],
-        ['-' * widths[0], '-' * widths[1], '-' * widths[2], '-' * widths[3]]
-      ] + table[1..-1]
-
-      # build the final table
-      line = "| #{widths.map{|n| "%-#{n}s" }.join(' | ')} |"
-      table.map { |row| line % row }.join("\n")
-    end
-    module_function :markdown_table
-
     def underscore(str)
       str.split('.').map do |part|
         Underscore.underscore(part)
       end.join('.')
     end
 
+    # convert a snake case to pascal case
+    def pascal_case(str)
+      str
+        .to_s
+        .split('_')
+        .collect(&:capitalize)
+        .join
+    end
+
     def structures
       Enumerator.new do |y|
         (@api['shapes'] || {}).each do |shape_name, shape|
@@ -62,64 +50,6 @@ module AwsSdkCodeGenerator
       end
     end
 
-    # @option options [Boolean] :nested (false)
-    def ruby_input_type(shape_ref, options = {})
-      nested = options.fetch(:nested, false)
-      shape = @api['shapes'][shape_ref['shape']]
-      case shape['type']
-      when 'byte' then 'Integer<byte>'
-      when 'blob' then 'String, IO'
-      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'], nested:true)}>"
-        end
-      when 'long' then 'Integer'
-      when 'map'
-        if nested
-          "Hash"
-        else
-          "Hash<String,#{ruby_input_type(shape['value'], nested:true)}>"
-        end
-      when 'string' then 'String'
-      when 'structure' then "Types::#{shape_ref['shape']}"
-      when 'timestamp' then 'Time,DateTime,Date,Integer,String'
-      else
-        raise "unhandled type #{shape.type}.inspect"
-      end
-    end
-
-    def ruby_type(shape_ref)
-      shape = @api['shapes'][shape_ref['shape']]
-      case shape['type']
-      when 'blob' then streaming?(shape_ref, shape) ? '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'])}>"
-      when 'long' then 'Integer'
-      when 'map' then "Hash<String,#{ruby_type(shape['value'])}>"
-      when 'string' then 'String'
-      when 'structure' then "Types::#{shape_ref['shape']}"
-      when 'timestamp' then 'Time'
-      else
-        raise "unhandled type #{shape['type'].inspect}"
-      end
-    end
-
-    def streaming?(ref, shape)
-      ref['streaming'] || shape['streaming']
-    end
-
     # @option options [Integer] :line_width (70)
     def documentation(ref_or_shape, options = {})
       line_width = options.fetch(:line_width, 70)
@@ -143,6 +73,30 @@ module AwsSdkCodeGenerator
       shape(member_ref)
     end
 
+    def upcase_first(name)
+      if name[0] =~ /[a-z]/
+        name.size == 1 ? name.upcase : name[0].upcase + name[1..-1]
+      else
+        name
+      end
+    end
+
+    def downcase_first(name)
+      if name[0] =~/[A-Z]/
+        name.size == 1 ? name.downcase : name[0].downcase + name[1..-1]
+      else
+        name
+      end
+    end
+
+    def lstrip_prefix(name)
+      name.start_with?("__") ? name[2..-1] : name
+    end
+
+    def apig_prefix(name)
+      "__#{name}"
+    end
+
     def shape(ref)
       if ref.nil?
         nil
@@ -153,44 +107,50 @@ module AwsSdkCodeGenerator
       end
     end
 
+    # @param [String<HTML>] html
     # @option options [Integer] :line_width (70)
     def markdown(html, options = {})
-      line_width = options.fetch(:line_width, 70)
-      # TODO : this section of code is **very slow** and runs many times
-      #   while building a service.
-      if html
-        html = "<p>#{html}</p>" unless html.match(/<\w+>/)
-
-        # unescaped curly braces cause YARD errors, they are interpreted
-        # as code links.
-        html = html.gsub('{', "\\{").gsub('}', "\\}")
-
-        # Kramdown generates invalid markup when there are attributes
-        # on the code tag, have to reduce these down to get the proper markdown.
-        html = html.gsub(/<code.*?>(.+?)<\/code>/) { "<code>#{$1}</code>" }
-
-        # Kramdown creates invalid markup with target="_blank" attributes.
-        html = html.gsub(' target="_blank"', '')
-
-        # There are quite a few empty <a> tags. These appear to be code names,
-        # such as structure member names, or structure type names. We should
-        # investigate if it is possible to inflect these properly and then
-        # turn them into YARD links.
-        html = html.gsub(/<a>(.+?)<\/a>/) { $1 }
-
-        # <important> tag doesn't render well
-        html = html.gsub(/<important>(.+?)<\/important>/){ "<p>#{$1}</p>" }
-
-        markdown = Kramdown::Document.new(
-          html,
-          input: 'html',
-          line_width: line_width,
-          auto_ids: false
-        ).to_kramdown.strip
-
-        # remove extra escape
-        markdown.gsub(/\\(\*|`|'|")/, '\1')
+      Docstring.html_to_markdown(html, options)
+    end
+
+    def operation_streaming?(operation, api)
+      return unless operation.key? 'output'
+      output = operation['output']['shape']
+      if api['shapes'][output].key? 'payload'
+        output_shape = api['shapes'][output]
+        payload = output_shape['payload']
+        if output_shape.key? 'members'
+          payload_ref = output_shape['members'][payload]
+        elsif output_shape.key? 'member'
+          payload_ref = output_shape['member'][payload]
+        end
+        Api.streaming?(payload_ref, api)
+      end
+    end
+
+    def operation_eventstreaming?(operation, api)
+      !!eventstream_input?(operation, api) ||
+        !!eventstream_output?(operation, api)
+    end
+
+    def eventstream_output?(operation, api)
+      return false unless operation.key? 'output'
+      output_shape = api['shapes'][operation['output']['shape']]
+      return false unless output_shape.key? 'members'
+      output_shape['members'].each do |name, ref|
+        return ref['shape'] if Api.eventstream?(ref, api)
       end
+      return false
+    end
+
+    def eventstream_input?(operation, api)
+      return false unless operation.key? 'input'
+      input_shape = api['shapes'][operation['input']['shape']]
+      return false unless input_shape.key? 'members'
+      input_shape['members'].each do |name, ref|
+        return ref['shape'] if Api.eventstream?(ref, api)
+      end
+      return false
     end
 
     def deep_copy(obj)
@@ -211,5 +171,12 @@ module AwsSdkCodeGenerator
       end
     end
 
+    def wrap_string(str, width, indent = '')
+      str.gsub(/(.{1,#{width}})(\s+|\Z)/, "#{indent}\\1\n").chomp
+    end
+
+    module_function :deep_copy, :operation_streaming?, :downcase_first, :wrap_string, :apig_prefix,
+      :eventstream_output?, :eventstream_input?, :operation_eventstreaming?, :pascal_case
+
   end
 end

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

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module AwsSdkCodeGenerator
+  class PluginList
+
+    include Enumerable
+
+    def initialize(options)
+      @aws_sdk_core_lib_path = options.fetch(:aws_sdk_core_lib_path)
+      @plugins = compute_plugins(options)
+    end
+
+    # @return [Enumerable<Plugin>]
+    def each(&block)
+      @plugins.each(&block)
+    end
+
+    private
+
+    def compute_plugins(options)
+      plugins = {}
+      plugins.update(options[:async_client] ? default_async_plugins : default_plugins)
+      plugins.update(signature_plugins(options.fetch(:signature_version)))
+      plugins.update(protocol_plugins(options.fetch(:protocol)))
+      plugins.update(options.fetch(:add_plugins))
+      options.fetch(:remove_plugins).each do |plugin_name|
+        plugins.delete(plugin_name)
+      end
+      plugins.map do |class_name, path|
+        path = File.absolute_path(path)
+        Kernel.require(path)
+
+        Plugin.new(
+          class_name: class_name,
+          options: const_get(class_name).options,
+          path: path)
+      end
+    end
+
+    def default_plugins
+      {
+        'Seahorse::Client::Plugins::ContentLength' => "#{seahorse_plugins}/content_length.rb",
+        'Aws::Plugins::CredentialsConfiguration' => "#{core_plugins}/credentials_configuration.rb",
+        'Aws::Plugins::Logging' => "#{core_plugins}/logging.rb",
+        'Aws::Plugins::ParamConverter' => "#{core_plugins}/param_converter.rb",
+        'Aws::Plugins::ParamValidator' => "#{core_plugins}/param_validator.rb",
+        'Aws::Plugins::UserAgent' => "#{core_plugins}/user_agent.rb",
+        'Aws::Plugins::HelpfulSocketErrors' => "#{core_plugins}/helpful_socket_errors.rb",
+        'Aws::Plugins::RetryErrors' => "#{core_plugins}/retry_errors.rb",
+        'Aws::Plugins::GlobalConfiguration' => "#{core_plugins}/global_configuration.rb",
+        'Aws::Plugins::RegionalEndpoint' => "#{core_plugins}/regional_endpoint.rb",
+        'Aws::Plugins::EndpointDiscovery' => "#{core_plugins}/endpoint_discovery.rb",
+        'Aws::Plugins::EndpointPattern' => "#{core_plugins}/endpoint_pattern.rb",
+        'Aws::Plugins::ResponsePaging' => "#{core_plugins}/response_paging.rb",
+        'Aws::Plugins::StubResponses' => "#{core_plugins}/stub_responses.rb",
+        'Aws::Plugins::IdempotencyToken' => "#{core_plugins}/idempotency_token.rb",
+        'Aws::Plugins::JsonvalueConverter' => "#{core_plugins}/jsonvalue_converter.rb",
+        'Aws::Plugins::ClientMetricsPlugin' => "#{core_plugins}/client_metrics_plugin.rb",
+        'Aws::Plugins::ClientMetricsSendPlugin' => "#{core_plugins}/client_metrics_send_plugin.rb",
+        'Aws::Plugins::TransferEncoding' => "#{core_plugins}/transfer_encoding.rb",
+        'Aws::Plugins::HttpChecksum' => "#{core_plugins}/http_checksum.rb"
+      }
+    end
+
+    def default_async_plugins
+      plugins = default_plugins.dup
+      plugins.delete('Seahorse::Client::Plugins::ContentLength')
+      plugins.delete('Aws::Plugins::ResponsePaging')
+      plugins.delete('Aws::Plugins::EndpointDiscovery')
+      plugins.delete('Aws::Plugins::EndpointPattern')
+      plugins.delete('Aws::Plugins::ClientMetricsPlugin')
+      plugins.delete('Aws::Plugins::ClientMetricsSendPlugin')
+      plugins.delete('Aws::Plugins::TransferEncoding')
+      plugins['Aws::Plugins::InvocationId'] = "#{core_plugins}/invocation_id.rb"
+      plugins
+    end
+
+    def protocol_plugins(protocol)
+      {
+        'json'      => { 'Aws::Plugins::Protocols::JsonRpc' => "#{core_plugins}/protocols/json_rpc.rb" },
+        'rest-json' => { 'Aws::Plugins::Protocols::RestJson' => "#{core_plugins}/protocols/rest_json.rb" },
+        'rest-xml'  => { 'Aws::Plugins::Protocols::RestXml' => "#{core_plugins}/protocols/rest_xml.rb" },
+        'query'     => { 'Aws::Plugins::Protocols::Query' => "#{core_plugins}/protocols/query.rb" },
+        'ec2'       => { 'Aws::Plugins::Protocols::EC2' => "#{core_plugins}/protocols/ec2.rb" },
+        'api-gateway' => {
+          'Aws::Plugins::Protocols::ApiGateway' => "#{core_plugins}/protocols/api_gateway.rb",
+          'Aws::Plugins::ApiKey' => "#{core_plugins}/api_key.rb",
+          'Aws::Plugins::APIGUserAgent' => "#{core_plugins}/apig_user_agent.rb",
+          'Aws::Plugins::APIGAuthorizerToken' => "#{core_plugins}/apig_authorizer_token.rb",
+          'Aws::Plugins::APIGCredentialsConfiguration' => "#{core_plugins}/apig_credentials_configuration.rb"
+        },
+        nil         => {}
+      }[protocol]
+    end
+
+    def signature_plugins(signature_version)
+      case signature_version
+      when 'v4'
+        { 'Aws::Plugins::SignatureV4' => "#{core_plugins}/signature_v4.rb" }
+      when 'v2'
+        { 'Aws::Plugins::SignatureV2' => "#{core_plugins}/signature_v2.rb" }
+      else
+        {}
+      end
+    end
+
+    def core_plugins
+      File.join(@aws_sdk_core_lib_path, 'aws-sdk-core/plugins')
+    end
+
+    def seahorse_plugins
+      File.join(@aws_sdk_core_lib_path, 'seahorse/client/plugins')
+    end
+
+    def core_lib
+      # TODO : may need to register the default plugins directory rather
+      #        than have the hard-coded here as a relative path
+      File.expand_path('../../../../../gems/aws-sdk-core/lib', __FILE__)
+    end
+
+    def const_get(class_name)
+      const_names = class_name.split('::')
+      const_names.inject(Kernel) do |const, const_name|
+        const.const_get(const_name)
+      end
+    end
+
+    class Plugin
+
+      def initialize(options)
+        @class_name = options.fetch(:class_name)
+        @options = options.fetch(:options)
+        @require_path = options.fetch(:path).split('/lib/').last
+      end
+
+      # @return [String]
+      attr_reader :class_name
+
+      # @return [Array<Seahorse::Client::Plugin::PluginOption>]
+      attr_reader :options
+
+      # @return [String]
+      attr_reader :require_path
+
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module AwsSdkCodeGenerator
+  class ResourceAction
+    class << self
+
+      include Helper
+
+      # @return [Array<ResourceMethod>]
+      def build_list(resource_name, resource, api)
+        resource.fetch('actions', {}).map do |action_name, action|
+          build(
+            resource_name: resource_name,
+            action_name: action_name,
+            action: action,
+            api: api
+          )
+        end
+      end
+
+      # @option options [required, String] :resource_name
+      # @option options [required, String] :action_name
+      # @option options [required, String] :action
+      # @option options [required, String] :api
+      def build(options)
+        ResourceMethod.new.tap do |m|
+          m.method_name = Underscore.underscore(options.fetch(:action_name))
+          m.arguments = 'options = {}'
+          operation_name = options.fetch(:action)['request']['operation']
+          api = options.fetch(:api)
+          if operation_streaming?(api['operations'][operation_name], api)
+            m.arguments += ', &block'
+            options[:streaming] = true
+          end
+          m.code = ResourceActionCode.new(options).build
+          m.documentation = documentation(options)
+        end
+      end
+
+      private
+
+      def documentation(options)
+        api = options.fetch(:api)
+        action = options.fetch(:action)
+        operation = api['operations'][action['request']['operation']]
+        ResourceClientReqeustDocumentation.new(
+          method_name: Underscore.underscore(options.fetch(:action_name)),
+          receiver: Underscore.underscore(options.fetch(:resource_name)),
+          resp_var: action['resource'] ? action['resource']['type'].downcase : nil,
+          returns: returns(action, operation),
+          request: action['request'],
+          api: api,
+        ).build
+      end
+
+      def returns(action, operation)
+        if action['resource']
+          resource = action['resource']
+          Api.plural?(resource) ? "#{resource['type']}::Collection" : resource['type']
+        elsif operation['output']
+          "Types::#{operation['output']['shape']}"
+        else
+          "EmptyStructure"
+        end
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module AwsSdkCodeGenerator
+  class ResourceActionCode
+
+    def initialize(options)
+      action = options.fetch(:action)
+      @request = action.fetch('request')
+      @resource = action.fetch('resource', nil)
+      @streaming = options.fetch(:streaming, false)
+    end
+
+    def build
+      parts = []
+      if batch_action?
+        parts << 'batch = []'
+        parts << client_request
+        parts << ResourceBatchBuilder.new(resource: @resource).build
+        parts << "#{resource_type}::Collection.new([batch], size: batch.size)"
+      elsif resource_action?
+        parts << client_request(
+          @resource['identifiers'].any? { |i| i['source'] == 'response' } || @resource['path']
+        )
+        parts << ResourceBuilder.new(resource: @resource, request_made: true).build
+      else
+        parts << client_request
+        parts << 'resp.data'
+      end
+      parts.join("\n").rstrip
+    end
+
+    private
+
+    def client_request(resp = true)
+      ResourceClientRequest.build(request: @request, resp: resp, streaming: @streaming)
+    end
+
+    def resource_type
+      @resource['type']
+    end
+
+    def batch_action?
+      if resource_action?
+        paths = (@resource['identifiers'] || []).map {|i| i['path'] }
+        paths << @resource['path']
+        paths.compact.any? { |path| path.match(/\[/) }
+      else
+        false
+      end
+    end
+
+    def resource_action?
+      !!@resource
+    end
+
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module AwsSdkCodeGenerator
+  class ResourceAssociation
+    class << self
+
+      # @return [Array<ResourceMethod>]
+      def build_list(options)
+        associations = []
+        associations += has_associations(options)
+        associations += has_many_associations(options)
+        associations.sort_by(&:method_name)
+      end
+
+      private
+
+      def has_associations(options)
+        options.fetch(:resource).fetch('has', {}).map do |name, assoc|
+          ResourceHasAssociation.build(options.merge(
+            name: name,
+            assoc: assoc,
+          ))
+        end
+      end
+
+      def has_many_associations(options)
+        options.fetch(:resource).fetch('hasMany', {}).map do |name, assoc|
+          ResourceHasManyAssociation.build(options.merge(
+            name: name,
+            assoc: assoc,
+          ))
+        end
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module AwsSdkCodeGenerator
+  class ResourceAttribute
+
+    # @return [String]
+    attr_accessor :name
+
+    # @return [String, nil]
+    attr_accessor :documentation
+
+    class << self
+
+      # @return [Array<ResourceAttribute>)
+      def build_list(resource, api)
+        if resource['shape']
+          data_attribute_names(resource, api).map do |member_name, member_ref|
+            docstring = Docstring.block_comment(
+              Docstring.html_to_markdown(Api.docstring(member_ref, api))
+            )
+            docstring = (docstring ? "#{docstring}\n" : '')
+            type = Api.ruby_type(member_ref, api)
+            ResourceAttribute.new.tap do |attr|
+              attr.name = Underscore.underscore(member_name)
+              attr.documentation = docstring + "# @return [#{type}]"
+            end
+          end
+        else
+          []
+        end
+
+      end
+
+      private
+
+      def data_attribute_names(resource, api)
+
+        identifiers = resource['identifiers']
+
+        skip = Set.new
+
+        # do no duplicate identifiers
+        identifiers.each do |i|
+          skip << i['name']
+          skip << i['memberName'] if i.key?('memberName')
+        end
+
+        # do no duplicate action names
+        (resource['actions'] || {}).keys.each do |action_name|
+          skip << action_name
+        end
+
+        # do no duplicate has association names
+        (resource['has'] || {}).keys.each do |association_name|
+          skip << association_name
+        end
+
+        # do no duplicate hasMany association names
+        (resource['hasMany'] || {}).keys.each do |association_name|
+          skip << association_name
+        end
+
+        shape = Api.shape(resource['shape'], api)
+        members = shape['members'] || {}
+        Enumerator.new do |y|
+          members.each do |member_name, member_ref|
+            unless skip.include?(member_name)
+              y.yield(member_name, member_ref)
+            end
+          end
+        end
+      end
+
+    end
+  end
+end