aws-sdk-code-generator 0.1.0.pre

data/lib/aws-sdk-code-generator/generators/client_api_module.rb

@@ -0,0 +1,334 @@
+module AwsSdkCodeGenerator
+  module Generators
+    class ClientApiModule < Dsl::Module
+
+      include Helper
+
+      SKIP_TRAITS = Set.new(%w(shape deprecated location locationName documentation))
+
+      SHAPE_CLASSES = {
+        'blob' => 'BlobShape',
+        'byte' => 'IntegerShape',
+        'boolean' => 'BooleanShape',
+        'character' => 'StringShape',
+        'double' => 'FloatShape',
+        'float' => 'FloatShape',
+        'integer' => 'IntegerShape',
+        'list' => 'ListShape',
+        'long' => 'IntegerShape',
+        'map' => 'MapShape',
+        'string' => 'StringShape',
+        'structure' => 'StructureShape',
+        'timestamp' => 'TimestampShape',
+      }
+
+      SHAPE_KEYS = {
+        # keep
+        'flattened' => true,
+        'timestampFormat' => true, # glacier api customization
+        'xmlNamespace' => true,
+        # ignore
+        'box' => false,
+        'fault' => false,
+        'error' => false,
+        'deprecated' => false,
+        'type' => false,
+        'documentation' => false,
+        'members' => false,
+        'member' => false,
+        'key' => false,
+        'locationName'  => false,
+        'value' => false,
+        'required' => false,
+        'streaming'  => false,
+        'enum' => false,
+        'exception' => false,
+        'payload' => false,
+        'pattern' => false,
+        'sensitive' => false,
+        'min' => false,
+        'max' => false,
+        'wrapper' => false,
+        'xmlOrder' => false,
+      }
+
+      METADATA_KEYS = {
+        # keep
+        'endpointPrefix' => true,
+        'signatureVersion' => true,
+        'signingName' => true,
+        'serviceFullName' => true,
+        'protocol' => true,
+        'targetPrefix' => true,
+        'jsonVersion' => true,
+        'errorPrefix' => true,
+        'timestampFormat' => true, # glacier api customization
+        'xmlNamespace' => true,
+
+        # ignore
+        'apiVersion' => false,
+        'checksumFormat' => false,
+        'globalEndpoint' => false,
+        'serviceAbbreviation' => false,
+        'uid' => false,
+      }
+
+      # @option options [required, Hash] :api
+      # @option options [required, Hash, nil] :paginators
+      def initialize(options)
+        @api = options.fetch(:api)
+        @paginators = options.fetch(:paginators)
+        super('ClientApi')
+        docstring("@api private")
+        include('Seahorse::Model')
+        apply_shape_classes(self)
+        apply_shape_definitions(self)
+        apply_api_const(self)
+      end
+
+      private
+
+      def metadata
+        Dsl::CodeLiteral.new do |c|
+          c << "api.metadata = {"
+          c.indent do
+            (@api['metadata'] || {}).keys.sort.each do |key|
+              if METADATA_KEYS[key]
+                c << "#{key.inspect} => #{@api['metadata'][key].inspect},"
+              elsif METADATA_KEYS[key].nil?
+                raise "unhandled metadata key #{key.inspect}"
+              end
+            end
+          end
+          c << "}"
+        end
+      end
+
+      def operations
+        (@api['operations'] || {}).map do |name, operation|
+          operation(name, operation)
+        end
+      end
+
+      def operation(name, operation)
+        Dsl::CodeLiteral.new do |code|
+          code << "api.add_operation(:#{underscore(name)}, Seahorse::Model::Operation.new.tap do |o|"
+          code.indent do |c|
+            c << "o.name = #{name.inspect}"
+            c << "o.http_method = #{operation['http']['method'].inspect}"
+            c << "o.http_request_uri = #{operation['http']['requestUri'].inspect}"
+            c << "o.deprecated = true" if operation['deprecated']
+            c << "o['authtype'] = #{operation['authtype'].inspect}" if operation['authtype']
+            %w(input output).each do |mode|
+              c << "o.#{mode} = #{operation_shape_ref(operation[mode])}"
+            end
+            Array(operation['errors']).each do |error|
+              c << "o.errors << #{operation_shape_ref(error)}"
+            end
+            apply_operation_pager(c, name)
+          end
+          code << "end)"
+        end
+      end
+
+      def operation_shape_ref(ref)
+        if ref
+          metadata = ref.dup
+          shape_name = metadata.delete('shape')
+          if metadata.empty?
+            options = ''
+          else
+            options = {}
+            metadata.each_pair do |key, value|
+              next if key == 'resultWrapper'
+              if key == 'locationName'
+                options[:location_name] = value.inspect
+              else
+                options[:metadata] ||= {}
+                options[:metadata][key] = value.inspect
+              end
+            end
+            if options.empty?
+              options = ''
+            else
+              options = ', ' + HashFormatter.new(wrap:false).format(options)
+            end
+          end
+          "Shapes::ShapeRef.new(shape: #{shape_name}#{options})"
+        else
+          "Shapes::ShapeRef.new(shape: Shapes::StructureShape.new(struct_class: Aws::EmptyStructure))"
+        end
+      end
+
+      def shape_ref(ref, member_name = nil, required = Set.new)
+        line = "Shapes::ShapeRef.new(shape: #{ref['shape']}"
+        line += shape_ref_required(required, member_name)
+        line += shape_ref_deprecated(ref)
+        line += shape_ref_location(ref)
+        line += shape_ref_location_name(member_name, ref)
+        line += shape_ref_metadata(ref)
+        line += ")"
+        line
+      end
+
+      def apply_operation_pager(code, operation_name)
+        if @paginators && @paginators['pagination'][operation_name]
+          p = @paginators['pagination'][operation_name]
+          input = Array(p['input_token'])
+          output = Array(p['output_token'])
+          tokens = {}
+          input.each.with_index do |key, n|
+            tokens[underscore_jmespath(output[n])] = underscore_jmespath(key)
+          end
+          options = {}
+          options[:more_results] = underscore_jmespath(p['more_results']) if p['more_results']
+          options[:limit_key] = underscore_jmespath(p['limit_key']) if p['limit_key']
+          options[:tokens] = tokens
+          options = HashFormatter.new(
+            quote_strings: true,
+            inline: true,
+            wrap: false,
+          ).format(options)
+          code << "o[:pager] = Aws::Pager.new(#{options})" unless tokens.empty?
+        end
+      end
+
+      def underscore_jmespath(str)
+        Underscore.underscore_jmespath(str)
+      end
+
+      def apply_shape_classes(m)
+        m.code do |c|
+          shape_defs.each do |shape_name, shape|
+            attrs = []
+            attrs << "name: '#{shape_name}'"
+            shape.each_pair do |key, value|
+              if SHAPE_KEYS[key]
+                attrs << "#{key}: #{value.inspect}"
+              elsif SHAPE_KEYS[key].nil?
+                raise "unhandled shape key #{key.inspect}"
+              end
+            end
+            attrs = attrs.join(', ')
+            c << "#{shape_name} = Shapes::#{shape_class(shape['type'])}.new(#{attrs})"
+          end
+        end
+      end
+
+      def apply_shape_definitions(m)
+        m.code do |c|
+          shape_defs.each do |shape_name, shape|
+            if shape['type'] == 'structure' && !shape['error'] && !shape['exception']
+              required = Set.new(shape['required'] || [])
+              shape['members'].each do |member_name, member_ref|
+                c << "#{shape_name}.add_member(:#{underscore(member_name)}, #{shape_ref(member_ref, member_name, required)})"
+              end
+              c << "#{shape_name}.struct_class = Types::#{shape_name}"
+              if payload = shape['payload']
+                c << "#{shape_name}[:payload] = :#{underscore(payload)}"
+                c << "#{shape_name}[:payload_member] = #{shape_name}.member(:#{underscore(payload)})"
+              end
+            elsif shape['type'] == 'list'
+              c << "#{shape_name}.member = #{shape_ref(shape['member'])}"
+            elsif shape['type'] == 'map'
+              c << "#{shape_name}.key = #{shape_ref(shape['key'])}"
+              c << "#{shape_name}.value = #{shape_ref(shape['value'])}"
+            else
+              next
+            end
+            c.newline
+          end
+        end
+      end
+
+      def apply_api_const(m)
+        m.code do |c|
+          c << "# @api private"
+          c << "API = Seahorse::Model::Api.new.tap do |api|"
+          c.indent do
+            c.newline
+            if @api['metadata'] && @api['metadata']['apiVersion']
+              c << "api.version = #{@api['metadata']['apiVersion'].inspect}"
+              c.newline
+            end
+            c << metadata
+            operations.each do |operation|
+              c.newline
+              c << operation
+            end
+          end
+          c << "end"
+        end
+      end
+
+      def shape_ref_required(required, member_name)
+        if required.include?(member_name)
+          ", required: true"
+        else
+          ""
+        end
+      end
+
+      def shape_ref_deprecated(ref)
+        if ref['deprecated'] || @api['shapes'][ref['shape']]['deprecated']
+          ", deprecated: true"
+        else
+          ""
+        end
+      end
+
+      def shape_ref_location(ref)
+        if ref['location']
+          ", location: #{ref['location'].inspect}"
+        else
+          ''
+        end
+      end
+
+      def shape_ref_location_name(member_name, member_ref)
+        location_name = member_ref['locationName']
+        location_name ||= member_name unless member_ref['location'] == 'headers'
+        location_name ? ", location_name: #{location_name.inspect}" : ""
+      end
+
+      def shape_ref_metadata(member_ref)
+        metadata = member_ref.inject({}) do |hash, (key, value)|
+          hash[key] = value unless SKIP_TRAITS.include?(key)
+          hash
+        end
+        if metadata.empty?
+          ""
+        else
+          ", metadata: #{metadata.inspect}"
+        end
+      end
+
+      def shape_class(type)
+        if SHAPE_CLASSES.key?(type)
+          SHAPE_CLASSES[type]
+        else
+          raise ArgumentError, "unsupported shape type `#{type}'"
+        end
+      end
+
+      def shape_defs
+        Enumerator.new do |y|
+          (@api['shapes'] || {}).keys.sort.each do |shape_name|
+            y.yield(shape_name, @api['shapes'][shape_name])
+          end
+        end
+      end
+
+      def structure_defs
+        Enumerator.new do |y|
+          shape_defs.each do |shape_name, shape|
+            if shape['type'] == 'structure' && !shape['error'] && !shape['exception']
+              y.yield(shape_name, shape)
+            end
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/aws-sdk-code-generator/generators/client_class.rb

@@ -0,0 +1,389 @@
+require 'set'
+require 'pp'
+require 'seahorse/client/plugin'
+
+module AwsSdkCodeGenerator
+  module Generators
+    class ClientClass < Dsl::Class
+
+      include Helper
+
+      # @option options [required, Main, Module] :parent
+      # @option options [required, String] :identifier
+      # @option options [required, Hash] :api
+      # @option options [required, Hash, nil] :waiters
+      # @option options [required, Hash, nil] :examples
+      # @option options [Hash] :add_plugins ({})
+      # @option options [Array<String>] :remove_plugins ([])
+      def initialize(options)
+        @identifier = options.fetch(:identifier)
+        @api = options.fetch(:api)
+        @waiters = options.fetch(:waiters)
+        @examples = options.fetch(:examples)
+        @add_plugins = options.fetch(:add_plugins, {})
+        @remove_plugins = options.fetch(:remove_plugins, [])
+        @gem_name = options.fetch(:gem_name, nil)
+        @gem_version = options.fetch(:gem_version, nil)
+        super('Client', extends: 'Seahorse::Client::Base', parent: options.fetch(:parent))
+        apply_modules(self)
+        apply_identifier(self)
+        apply_api(self)
+        apply_plugins(self)
+        apply_initialize_method(self)
+        top("\nAws::Plugins::GlobalConfiguration.add_identifier(:#{@identifier})")
+        apply_operations(self)
+        apply_waiter_methods(self)
+        eigenclass do |eigenclass|
+          eigenclass.attr_reader('identifier', api_private: true)
+          eigenclass.method('errors_module', api_private: true) do |m|
+            m.code('Errors')
+          end
+        end
+      end
+
+      private
+
+      def client_plugins
+        @client_plugins ||= begin
+          plugins = {}
+          plugins.update(default_plugins)
+          plugins.update(signature_plugins)
+          plugins.update(protocol_plugins(@api['metadata']['protocol']))
+          plugins.update(@add_plugins)
+          @remove_plugins.each do |plugin_name|
+            plugins.delete(plugin_name)
+          end
+          plugins.map do |class_name, path|
+            path = "./#{path}" unless path[0] == '/'
+            Kernel.require(path)
+            ClientPlugin.new(
+              class_name: class_name,
+              options: const_get(class_name).options,
+              path: path)
+          end
+        end
+      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
+
+      def documented_plugin_options
+        client_plugins.map(&:options).flatten.select(&:documented?).sort_by do |opt|
+          [opt.required ? 'a' : 'b', opt.name]
+        end
+      end
+
+      def apply_modules(klass)
+        klass.include('Aws::ClientStubs')
+      end
+
+      def apply_identifier(klass)
+        klass.code do |c|
+          c << "@identifier = :#{@identifier}"
+        end
+      end
+
+      def apply_api(klass)
+        klass.code("set_api(ClientApi::API)")
+      end
+
+      def apply_plugins(klass)
+        klass.code do |c|
+          client_plugins.each do |plugin|
+            klass.top("require '#{plugin.require_path}'")
+            c << "add_plugin(#{plugin.class_name})"
+          end
+        end
+      end
+
+      def apply_initialize_method(klass)
+        klass.method(:initialize) do |m|
+          documented_plugin_options.each do |option|
+            m.option(
+              name: option.name,
+              type: option.doc_type,
+              required: option.required,
+              default: option.doc_default,
+              docstring: option.docstring
+            )
+          end
+          m.param('*args')
+          m.code('super')
+        end
+      end
+
+      def apply_operations(klass)
+        code('# @!group API Operations')
+        (@api['operations'] || {}).each do |operation_name, operation|
+          method_name = underscore(operation_name)
+          klass.method(method_name) do |m|
+            ClientOperationDocumentation.apply(
+              api: @api,
+              service_identifier: @identifier,
+              operation_name: operation_name,
+              operation: operation,
+              examples: @examples,
+              method: m
+            )
+            m.param('params', type: Hash, default: {})
+            m.param('options', type: Hash, default: {}, documented: false)
+            m.code do |c|
+              c << "req = build_request(:#{method_name}, params)"
+              c << "req.send_request(options)"
+            end
+          end
+        end
+        code('# @!endgroup')
+
+
+        if @gem_name && @gem_version
+          gem_version = "\ncontext[:gem_name] = '#{@gem_name}'"
+          gem_version += "\ncontext[:gem_version] = '#{@gem_version}'"
+        end
+        klass.method(:build_request, api_private: true) do |m|
+          m.param(:operation_name)
+          m.param(:params, default: {})
+          m.code(<<-CODE)
+handlers = @handlers.for(operation_name)
+context = Seahorse::Client::RequestContext.new(
+  operation_name: operation_name,
+  operation: config.api.operation(operation_name),
+  client: self,
+  params: params,
+  config: config)#{gem_version}
+Seahorse::Client::Request.new(handlers, context)
+          CODE
+        end
+      end
+
+      def apply_waiter_methods(klass)
+
+        # wait_until(waiter_name, params = {}, options = {}, &block)
+        if @waiters
+          klass.add(Dsl::Method.new('wait_until') do |m|
+            m.param('waiter_name', type: Symbol)
+            m.param('params', type: Hash, default: {})
+            m.param('options', type: Hash, default: {})
+            m.option(name: 'max_attempts', type: Integer)
+            m.option(name: 'delay', type: Integer)
+            m.option(name: 'before_attempt', type: Proc)
+            m.option(name: 'before_wait', type: Proc)
+            m.docstring(<<-DOCS)
+Polls an API operation until a resource enters a desired state.
+
+## Basic Usage
+
+A waiter will call an API operation until:
+
+* It is successful
+* It enters a terminal state
+* It makes the maximum number of attempts
+
+In between attempts, the waiter will sleep.
+
+    # polls in a loop, sleeping between attempts
+    client.waiter_until(waiter_name, params)
+
+## Configuration
+
+You can configure the maximum number of polling attempts, and the
+delay (in seconds) between each polling attempt. You can pass
+configuration as the final arguments hash.
+
+    # poll for ~25 seconds
+    client.wait_until(waiter_name, params, {
+      max_attempts: 5,
+      delay: 5,
+    })
+
+## Callbacks
+
+You can be notified before each polling attempt and before each
+delay. If you throw `:success` or `:failure` from these callbacks,
+it will terminate the waiter.
+
+    started_at = Time.now
+    client.wait_until(waiter_name, params, {
+
+      # disable max attempts
+      max_attempts: nil,
+
+      # poll for 1 hour, instead of a number of attempts
+      before_wait: -> (attempts, response) do
+        throw :failure if Time.now - started_at > 3600
+      end
+    })
+
+## Handling Errors
+
+When a waiter is unsuccessful, it will raise an error.
+All of the failure errors extend from
+{Aws::Waiters::Errors::WaiterFailed}.
+
+    begin
+      client.wait_until(...)
+    rescue Aws::Waiters::Errors::WaiterFailed
+      # resource did not enter the desired state in time
+    end
+
+## Valid Waiters
+
+The following table lists the valid waiter names, the operations they call,
+and the default `:delay` and `:max_attempts` values.
+
+#{waiter_table}
+
+@raise [Errors::FailureStateError] Raised when the waiter terminates
+  because the waiter has entered a state that it will not transition
+  out of, preventing success.
+
+@raise [Errors::TooManyAttemptsError] Raised when the configured
+  maximum number of attempts have been made, and the waiter is not
+  yet successful.
+
+@raise [Errors::UnexpectedError] Raised when an error is encounted
+  while polling for a resource that is not expected.
+
+@raise [Errors::NoSuchWaiterError] Raised when you request to wait
+  for an unknown state.
+
+@return [Boolean] Returns `true` if the waiter was successful.
+            DOCS
+            m.code(<<-CODE)
+w = waiter(waiter_name, options)
+yield(w.waiter) if block_given? # deprecated
+w.wait(params)
+            CODE
+          end)
+        end
+
+        # waiter_names
+        klass.add(Dsl::Method.new('waiter_names') do |m|
+          m.docstring("@api private")
+          m.docstring("@deprecated")
+          if @waiters
+            m.code("waiters.keys")
+          else
+            m.code('[]')
+          end
+        end)
+
+        # private: waiter(waiter_name)
+        klass.add(Dsl::Method.new('waiter', access: :private) do |m|
+          m.param('waiter_name', type: Symbol)
+          m.param('options', type: Hash, default: {})
+          m.code(<<-CODE)
+waiter_class = waiters[waiter_name]
+if waiter_class
+  waiter_class.new(options.merge(client: self))
+else
+  raise Aws::Waiters::Errors::NoSuchWaiterError.new(waiter_name, waiters.keys)
+end
+          CODE
+        end) if @waiters
+
+        # private: waiters
+        klass.add(Dsl::Method.new('waiters', access: :private) do |m|
+          waiters = {}
+          ((@waiters || {})['waiters'] || {}).each_pair do |name, definition|
+            class_name = "Waiters::#{name}"
+            waiters[underscore(name).to_sym] = class_name
+          end
+          m.code(HashFormatter.new.format(waiters))
+        end) if @waiters
+
+      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 core_plugins
+        "#{core_lib}/aws-sdk-core/plugins"
+      end
+
+      def seahorse_plugins
+        "#{core_lib}/seahorse/client/plugins"
+      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::ResponsePaging' => "#{core_plugins}/response_paging.rb",
+          'Aws::Plugins::StubResponses' => "#{core_plugins}/stub_responses.rb",
+          'Aws::Plugins::IdempotencyToken' => "#{core_plugins}/idempotency_token.rb",
+        }
+      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" },
+          nil         => {}
+        }[protocol]
+      end
+
+      def signature_plugins
+        case @api['metadata']['signatureVersion']
+        when 'v4'
+          { 'Aws::Plugins::SignatureV4' => "#{core_plugins}/signature_v4.rb" }
+        when 'v2'
+          { 'Aws::Plugins::SignatureV2' => "#{core_plugins}/signature_v2.rb" }
+        else
+          {}
+        end
+      end
+
+      def waiter_table
+        # insert one row for each supported service
+        table = []
+        @waiters['waiters'].each_pair do |name, waiter|
+          table << [underscore(name), "{##{underscore(waiter['operation'])}}", waiter['delay'], waiter['maxAttempts']]
+        end
+        table = table.sort_by(&:first)
+
+        # header row
+        table.unshift(['waiter_name', 'params', ':delay', ':max_attempts'])
+        markdown_table(table)
+      end
+
+      # @api private
+      class ClientPlugin
+
+        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
+end