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

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

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module AwsSdkCodeGenerator
+  class ClientResponseStructureExample
+
+    # @option options [required, Hash] :shape_ref
+    # @option options [required, Hash] :api
+    def initialize(options = {})
+      @shape_ref = options.fetch(:shape_ref)
+      @api = options.fetch(:api)
+    end
+
+    def to_str
+      "@example Response structure\n\n  #{entry(@shape_ref, 'resp', Set.new).join("\n  ")}"
+    end
+    alias to_s to_str
+
+    private
+
+    def structure(ref, context, visited)
+      lines = []
+      shape = shape(ref)
+      if shape['eventstream']
+        event_types = []
+        # Add event entry
+        event_ctx = shape['members'].each.inject([]) do |ctx, (member_name, member_ref)|
+          event_type = Underscore.underscore(member_name).to_sym
+          event_types << event_type
+          ctx << "For #{event_type.inspect} event available at #on_#{event_type}_event callback"\
+                 ' and response eventstream enumerator:'
+          event_entry = entry(member_ref, 'event', Set.new).join("\n  ")
+          ctx << (event_entry.empty? ? ' #=> EmptyStruct' : event_entry + "\n")
+        end
+        # Add eventstream entry
+        event_ctx.unshift("#{context}.event_types #=> #{event_types.inspect}\n")
+        event_ctx.unshift("#{context} #=> Enumerator")
+        event_ctx.unshift("All events are available at #{context}:")
+        return event_ctx
+      elsif shape['members']
+        shape['members'].each_pair do |member_name, member_ref|
+          lines += entry(member_ref, "#{context}.#{underscore(member_name)}", visited)
+        end
+      end
+      lines
+    end
+
+    def list(ref, context, visited)
+      lines = []
+      lines << "#{context} #=> Array"
+      lines += entry(shape(ref)['member'], "#{context}[0]", visited)
+      lines
+    end
+
+    def map(ref, context, visited)
+      lines = []
+      lines << "#{context} #=> Hash"
+      lines += entry(shape(ref)['value'], "#{context}[#{map_key(ref)}]", visited)
+      lines
+    end
+
+    def map_key(ref)
+      shape(ref)['key']['shape'].inspect
+    end
+
+    def entry(ref, context, visited)
+      if ref['shape'] == 'AttributeValue'
+        return ["#{context} #=> <Hash,Array,String,Numeric,Boolean,IO,Set,nil>"]
+      elsif visited.include?(ref['shape'])
+        return ["#{context} #=> Types::#{ref['shape']}"]
+      else
+        visited  = visited + [ref['shape']]
+      end
+      case shape(ref)['type']
+      when 'structure' then structure(ref, context, visited)
+      when 'list' then list(ref, context, visited)
+      when 'map' then map(ref, context, visited)
+      else ["#{context} #=> #{type(ref)}"]
+      end
+    end
+
+    def type(ref)
+      if shape(ref)['type'] == 'string'
+        string(ref)
+      else
+        Api.ruby_type(ref, @api)
+      end
+    end
+
+    def string(ref)
+      if shape(ref)['enum']
+        "String, one of #{shape(ref)['enum'].map(&:inspect).join(', ')}"
+      else
+        'String'
+      end
+    end
+
+    def shape(ref)
+      Api.shape(ref, @api)
+    end
+
+    def underscore(str)
+      Underscore.underscore(str)
+    end
+
+  end
+end

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

@@ -1,23 +1,27 @@
+# frozen_string_literal: true
+
 module AwsSdkCodeGenerator
   class CodeBuilder
 
-    # @api private
-    GENERATED_SRC_WARNING = <<-WARNING
-# WARNING ABOUT GENERATED CODE
-#
-# This file is generated. See the contributing for info on making contributions:
-# https://github.com/aws/aws-sdk-ruby/blob/master/CONTRIBUTING.md
-#
-# WARNING ABOUT GENERATED CODE
-
-    WARNING
-
-    include Helper
-
     # @option options [required, Service] :service
+    #
+    # @option options [required, String] :aws_sdk_core_lib_path
+    #   Path to the lib directory for the source code of the
+    #   AWS SDK for Ruby. This is needed so that documentation
+    #   can be generated for default plugins and their options.
+    #
+    # @option options [Hash<String, Array<Hash>] :client_examples ({})
+    #   A hash of client examples. Hash keys should be API operation method
+    #   names (snake_cased). Hash values should be arrays of hashes.
+    #   Each hash should contain the following keys:
+    #
+    #   * `:name` - The name of the example
+    #   * `:code` - The Ruby example code
+    #
     def initialize(options)
       @service = options.fetch(:service)
-      # TODO : remove these
+      @aws_sdk_core_lib_path = options.fetch(:aws_sdk_core_lib_path)
+      @client_examples = options.fetch(:client_examples, {})
       @add_plugins = @service.add_plugins
       @remove_plugins = @service.remove_plugins
       @gem_dependencies = @service.gem_dependencies
@@ -29,38 +33,52 @@ module AwsSdkCodeGenerator
       @examples = @service.examples
     end
 
+    # Generates the source for a library as a single string.
+    # @return [String<code>]
+    # @api private
     def source
-      svc_mod = new_svc_module
-      @gem_dependencies.each { |gem_name, _| svc_mod.require(gem_name) }
-      svc_mod.docstring(service_docstring)
-      each_module do |mod, _|
-        svc_mod.add(mod)
+      code = @gem_dependencies.map { |gem_name, _| "require '#{gem_name}'" }
+      source_files.each.with_index do |(file_name, src_code), n|
+        # skip the service module and customizations
+        next if file_name.include? '/customizations.rb'
+        next unless file_name.include? '/'
+        # skip markdown files
+        next if file_name.include? 'README.md'
+        code << src_code
       end
-      @callback.call(svc_mod) if @callback
-      svc_mod.root.to_s
+      code.join("\n")
     end
 
-    # @option options [String] :prefix
     # @return [Enumerable<String<path>, String<code>>]
     def source_files(options = {})
-      prefix = options.fetch(:prefix, nil)
-      prefix ||= @module_names.map { |n| underscore(n) }.join('/')
-      # prefix should always be the gemname. The service-module (the first
-      # item yielded below) should be moved from here into the gem builder
-      # The source code builder should simply yield the empty module
+      prefix = options.fetch(:prefix, @service.gem_name)
       Enumerator.new do |y|
-        y.yield("#{prefix}.rb", Views::ServiceModule.new(service: @service, prefix: prefix).render)
-        y.yield("#{prefix}/customizations.rb", '')
-        each_module do |mod, type, code|
-          case type
-          when :unwrapped
-            filename = File.join(prefix, underscore(mod.name) + '.rb')
-            y.yield(filename, GENERATED_SRC_WARNING + wrap(mod))
-          when :wrapped # dsl module
-            filename = File.join(prefix, underscore(mod.name) + '.rb')
-            y.yield(filename, GENERATED_SRC_WARNING + mod.root.to_s)
-          else
-            raise "expected :wrapped or :unwrapped"
+        if @service.protocol == 'api-gateway'
+          y.yield("#{prefix}/../../README.md", apig_readme)
+          y.yield("#{prefix}/plugins/authorizer.rb", authorizer_class)
+          y.yield("#{prefix}/plugins/apig_endpoint.rb", apig_endpoint_class)
+        end
+        y.yield("#{prefix}.rb", service_module(prefix))
+        unless prefix == 'aws-sdk-sts'
+          y.yield("#{prefix}/customizations.rb", '')
+        end
+        y.yield("#{prefix}/types.rb", types_module)
+        if has_eventstream
+          y.yield("#{prefix}/event_streams.rb", event_streams_module)
+        end
+        y.yield("#{prefix}/client_api.rb", client_api_module)
+        y.yield("#{prefix}/client.rb", client_class)
+        if @service.protocol_settings['h2'] == 'eventstream'
+          y.yield("#{prefix}/async_client.rb", async_client_class)
+        end
+        y.yield("#{prefix}/errors.rb", errors_module)
+        y.yield("#{prefix}/waiters.rb", waiters_module) if @waiters
+        y.yield("#{prefix}/resource.rb", root_resource_class)
+        if @resources
+          @resources['resources'].keys.sort.each do |name|
+            path = "#{prefix}/#{Underscore.underscore(name)}.rb"
+            code = resource_class(name, @resources['resources'][name])
+            y.yield(path, code)
           end
         end
       end
@@ -68,134 +86,129 @@ module AwsSdkCodeGenerator
 
     private
 
-    def each_module(&block)
-      yield(types_module, :unwrapped)
-      yield(client_api_module, :unwrapped)
-      yield(client_class, :wrapped)
-      yield(errors_module, :unwrapped)
-      yield(waiters_module, :wrapped) if @waiters
-      yield(root_resource_class, :unwrapped)
-      if @resources
-        @resources['resources'].keys.sort.each do |name|
-          yield(resource_class(name, @resources['resources'][name]), :unwrapped)
-        end
-      end
+    def service_module(prefix)
+      Views::ServiceModule.new(service: @service, prefix: prefix).render
     end
 
-    def new_svc_module
-      @module_names.inject(Dsl::Main.new) do |mod, module_name|
-        mod.module(module_name)
-      end
+    def types_module
+      Views::TypesModule.new(service: @service).render
     end
 
-    def wrap(mod)
-      svc_mod = new_svc_module
-      svc_mod.add(mod)
-      svc_mod.root.to_s
+    def event_streams_module
+      Views::EventStreamsModule.new(service: @service).render
     end
 
-    def service_module(autoload_prefix)
-      autoloads = Generators::ServiceAutoloads.new(
-        prefix: autoload_prefix,
-        resources: @resources,
-        waiters: !!@waiters
-      )
-      svc_mod = new_svc_module
-      @gem_dependencies.each { |gem_name, _| svc_mod.require(gem_name) }
-      svc_mod.docstring(service_docstring)
-      svc_mod.code("GEM_VERSION = '#{@service.gem_version}'")
-      autoloads.apply(svc_mod)
-      @callback.call(svc_mod) if @callback
-      svc_mod.root.to_s
+    def client_api_module
+      Views::ClientApiModule.new(service: @service).render
     end
 
-    def types_module
-      Generators::TypesModule.new(api: @api)
+    def client_class
+      Views::ClientClass.new(
+        service_identifier: @service.identifier,
+        service_name: @service.name,
+        protocol_settings: @service.protocol_settings,
+        module_name: @service.module_name,
+        gem_name: @service.gem_name,
+        gem_version: @service.gem_version,
+        aws_sdk_core_lib_path: @aws_sdk_core_lib_path,
+        client_examples: @client_examples,
+        protocol: @service.protocol,
+        signature_version: @service.signature_version,
+        require_endpoint_discovery: @service.require_endpoint_discovery,
+        add_plugins: @service.add_plugins,
+        remove_plugins: @service.remove_plugins,
+        api: @service.api,
+        paginators: @service.paginators,
+        waiters: @service.waiters,
+        examples: @service.examples,
+        custom: @service.protocol == 'api-gateway'
+      ).render
+    end
+
+    def async_client_class
+      Views::AsyncClientClass.new(
+        service_identifier: @service.identifier,
+        service_name: @service.name,
+        protocol_settings: @service.protocol_settings,
+        module_name: @service.module_name,
+        gem_name: @service.gem_name,
+        gem_version: @service.gem_version,
+        aws_sdk_core_lib_path: @aws_sdk_core_lib_path,
+        protocol: @service.protocol,
+        signature_version: @service.signature_version,
+        add_plugins: @service.add_plugins,
+        remove_plugins: @service.remove_plugins,
+        api: @service.api,
+        async_client: true
+      ).render
     end
 
-    def client_api_module
-      Generators::ClientApiModule.new(api: @api, paginators:@paginators)
+    def errors_module
+      Views::ErrorsModule.new(service: @service).render
     end
 
-    def client_class(svc_mod = new_svc_module)
-      klass = Generators::ClientClass.new(
-        parent: svc_mod,
-        identifier: @module_names.last.downcase,
-        api: @api,
+    def waiters_module
+      Views::WaitersModule.new(
+        module_name: @service.module_name,
         waiters: @waiters,
-        examples: @examples,
-        add_plugins: @add_plugins,
-        remove_plugins: @remove_plugins,
-        gem_name: @service.gem_name,
-        gem_version: @service.gem_version,
-      )
-      svc_mod.add(klass)
-      klass
+        custom: @service.protocol == 'api-gateway'
+      ).render
     end
 
-    def errors_module
-      Generators::ErrorsModule.new(api: @api)
+    def authorizer_class
+      Views::AuthorizerClass.new(
+        module_name: @service.module_name
+      ).render
     end
 
-    def waiters_module(svc_mod = new_svc_module)
-      klass = Generators::WaitersModule.new(
-        parent: svc_mod,
-        waiters: @waiters
-      )
-      svc_mod.add(klass)
-      klass
+    def apig_endpoint_class
+      Views::APIGEndpointClass.new(
+        module_name: @service.module_name,
+        default_endpoint: @service.default_endpoint
+      ).render
     end
 
     def root_resource_class
-      Generators::RootResourceClass.new({
-        api: @api,
-        resources: @resources,
+      Views::RootResourceClass.new(
+        module_name: @service.module_name,
+        service_name: @service.name,
+        resources: @service.resources,
         paginators: @paginators,
-        var_name: underscore(@module_names.last),
-      })
+        api: @api,
+        custom: @service.protocol == 'api-gateway'
+      ).render
     end
 
     def resource_class(resource_name, resource_definition)
-      Generators::ResourceClass.new(
+      Views::ResourceClass.new(
+        module_name: @service.module_name,
+        class_name: resource_name,
         api: @api,
-        name: resource_name,
-        resource: resource_definition,
         paginators: @paginators,
         waiters: @waiters,
-      )
+        resource: resource_definition,
+        custom: @service.protocol == 'api-gateway'
+      ).render
     end
 
-    def service_docstring
-      metadata = @api['metadata'] || {}
-      Generators::ServiceDocumentation.new(
-        product_name: metadata['serviceFullName'] || @module_names.last,
-        namespace: @module_names.join('::'),
-        api: @api
-      ).docstring
+    def apig_readme
+      Views::APIGReadme.new(
+        service_name: @service.name,
+        gem_major_version: @service.gem_version.split('.').first,
+        gem_name: @service.gem_name,
+        module_name: @service.module_name
+      ).render
     end
 
-    # @api private
-    # This method can be removed if move to used the combined API and
-    # docs JSON document.
-    def apply_docs(api, docs)
-      api['documentation'] = docs['service']
-      docs['operations'].each do |name, docstring|
-        api['operations'][name]['documentation'] = docstring
-      end
-      docs['shapes'].each do |shape_name, shape_docs|
-        api['shapes'][shape_name]['documentation'] = shape_docs['base']
-        shape_docs['refs'].each do |ref, ref_docs|
-          ref_shape, ref_member = ref.split('$')
-          case api['shapes'][ref_shape]['type']
-          when 'structure'
-            api['shapes'][ref_shape]['members'][ref_member]['documentation'] = ref_docs
-          when 'list', 'map'
-            api['shapes'][ref_shape][ref_member]['documentation'] = ref_docs
-          end
+    private
 
-        end
+    def has_eventstream
+      @service.api['shapes'].each do |_, ref|
+        return true if ref['eventstream']
       end
+      false
     end
 
   end
+
 end