smithy 2.0.0.pre0 → 2.0.0.pre1

data/lib/smithy/model/shape.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Model
+    # Represents a shape from the model.
+    # Shape IDs have the following syntax:
+    #
+    # smithy.example.foo#ExampleShapeName$memberName
+    # └─────────┬──────┘ └───────┬──────┘ └────┬───┘
+    #      (Namespace)     (Shape name)  (Member name)
+    #                    └──────────────┬────────────┘
+    #                          (Relative shape ID)
+    # └──────────────────────┬───────────────────────┘
+    #               (Absolute shape ID)
+    class Shape
+      # Optional shape namespace
+      # @param [String] id Shape ID
+      # @return [String, nil] Shape namespace
+      def self.namespace(id)
+        return nil unless id.include?('#')
+
+        id.split('#').first
+      end
+
+      # Relative shape ID
+      # @param [String] id Shape ID
+      # @return [String, nil] Relative shape ID
+      def self.relative_id(id)
+        id.split('#').last
+      end
+
+      # Shape name
+      # @param [String] id Shape ID
+      # @return [String, nil] Shape name
+      def self.name(id)
+        id.split('#').last&.split('$')&.first
+      end
+
+      # Optional member name
+      # @param [String] id Shape ID
+      # @return [String, nil] Member name
+      def self.member_name(id)
+        return nil unless id.include?('$')
+
+        id.split('$').last
+      end
+    end
+  end
+end

data/lib/smithy/model/structure_parser.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Model
+    # @api private
+    class StructureParser
+      def initialize(model)
+        @model = model
+      end
+
+      def shapes_for(structure)
+        shapes = {}
+        _id, structure = structure.first
+        structure['members']&.each_value { |member| parse_member(member, shapes) }
+        shapes
+      end
+
+      private
+
+      def parse_member(member_shape, shapes)
+        target = member_shape['target']
+        return if shapes.key?(target)
+        return if Model::PRELUDE_SHAPES.key?(target)
+
+        shape = Model.shape(@model, target)
+        shapes[target] = shape
+        parse_shape(shape, shapes)
+      end
+
+      def parse_shape(shape, shapes)
+        case shape['type']
+        when 'list'
+          parse_member(shape['member'], shapes)
+        when 'map'
+          parse_member(shape['key'], shapes)
+          parse_member(shape['value'], shapes)
+        when 'structure', 'union', 'intEnum', 'enum'
+          shape['members']&.each_value { |member| parse_member(member, shapes) }
+        end
+      end
+    end
+  end
+end

data/lib/smithy/model/yard.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Model
+    # @api private
+    class YARD
+      class << self
+        def deprecated_docstrings(message, since)
+          lines = ['@deprecated']
+          lines << "  #{escape(message)}" unless message.empty?
+          lines << "  Since: #{escape(since)}" unless since.empty?
+          lines
+        end
+
+        def external_documentation_docstrings(hash)
+          hash.map { |key, value| "@see #{escape(value)} #{escape(key)}" }
+        end
+
+        def option_docstrings(service, model, id, shape, option, docstrings) # rubocop:disable Metrics/ParameterLists
+          lines = ["@option params [#{type(service, model, id, shape)}] :#{option}"]
+          docstrings.each do |docstring|
+            lines << "  #{docstring}"
+          end
+          lines
+        end
+
+        def param_docstring(service, model, id, shape)
+          "@param [Hash, #{type(service, model, id, shape)}] params"
+        end
+
+        def recommended_docstrings(reason)
+          lines = ['@note']
+          lines << '  This shape is recommended'
+          lines << "  Reason: #{escape(reason)}" unless reason.empty?
+          lines
+        end
+
+        def return_docstring(service, model, id, shape)
+          "@return [#{type(service, model, id, shape)}]"
+        end
+
+        def sensitive_docstring
+          '@note This shape contains sensitive data and should be treated as such.'
+        end
+
+        def since_docstring(since)
+          "@since #{escape(since)}"
+        end
+
+        def title_docstring(title)
+          "@title #{escape(title)}"
+        end
+
+        def unstable_docstring
+          '@note This shape is unstable and may change in future releases.'
+        end
+
+        private
+
+        def type(service, model, id, shape) # rubocop:disable Metrics/CyclomaticComplexity
+          case shape['type']
+          when 'blob', 'string', 'enum' then 'String'
+          when 'boolean' then 'Boolean'
+          when 'byte', 'short', 'integer', 'long', 'intEnum' then 'Integer'
+          when 'float', 'double' then 'Float'
+          when 'timestamp' then 'Time'
+          when 'document' then 'JSON'
+          when 'list' then list(service, model, shape)
+          when 'map' then map(service, model, shape)
+          when 'structure', 'union' then structure(service, id)
+          else 'Object'
+          end
+        end
+
+        def structure(service, id)
+          return 'Smithy::Schema::EmptyStructure' if id == 'smithy.api#Unit'
+
+          "Types::#{(service.dig('rename', id) || Model::Shape.name(id)).camelize}"
+        end
+
+        def map(service, model, shape)
+          key_target = Model.shape(model, shape['key']['target'])
+          value_target = Model.shape(model, shape['value']['target'])
+          key_type = type(service, model, shape['key']['target'], key_target)
+          value_type = type(service, model, shape['value']['target'], value_target)
+          "Hash<#{key_type}, #{value_type}>"
+        end
+
+        def list(service, model, shape)
+          member_target = Model.shape(model, shape['member']['target'])
+          "Array<#{type(service, model, shape['member']['target'], member_target)}>"
+        end
+
+        def escape(string)
+          string.split("\n").join(' ')
+        end
+      end
+    end
+  end
+end

data/lib/smithy/model.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative 'model/flattener'
+require_relative 'model/operation_parser'
+require_relative 'model/rbs'
+require_relative 'model/service_index'
+require_relative 'model/service_parser'
+require_relative 'model/shape'
+require_relative 'model/structure_parser'
+require_relative 'model/yard'
+
+module Smithy
+  # A module that parses the Smithy JSON model.
+  module Model
+    # Generated with smithy-cli 1.53.0
+    # @api private
+    PRELUDE_SHAPES = {
+      'smithy.api#BigInteger' => { 'type' => 'bigInteger' },
+      'smithy.api#BigDecimal' => { 'type' => 'bigDecimal' },
+      'smithy.api#Blob' => { 'type' => 'blob' },
+      'smithy.api#Boolean' => { 'type' => 'boolean' },
+      'smithy.api#Byte' => { 'type' => 'byte' },
+      'smithy.api#Document' => { 'type' => 'document' },
+      'smithy.api#Double' => { 'type' => 'double' },
+      'smithy.api#Float' => { 'type' => 'float' },
+      'smithy.api#Integer' => { 'type' => 'integer' },
+      'smithy.api#Long' => { 'type' => 'long' },
+      'smithy.api#PrimitiveBoolean' => { 'type' => 'boolean', 'traits' => { 'smithy.api#default' => false } },
+      'smithy.api#PrimitiveByte' => { 'type' => 'byte', 'traits' => { 'smithy.api#default' => 0 } },
+      'smithy.api#PrimitiveDouble' => { 'type' => 'double', 'traits' => { 'smithy.api#default' => 0 } },
+      'smithy.api#PrimitiveFloat' => { 'type' => 'float', 'traits' => { 'smithy.api#default' => 0 } },
+      'smithy.api#PrimitiveInteger' => { 'type' => 'integer', 'traits' => { 'smithy.api#default' => 0 } },
+      'smithy.api#PrimitiveLong' => { 'type' => 'long', 'traits' => { 'smithy.api#default' => 0 } },
+      'smithy.api#PrimitiveShort' => { 'type' => 'short', 'traits' => { 'smithy.api#default' => 0 } },
+      'smithy.api#Short' => { 'type' => 'short' },
+      'smithy.api#String' => { 'type' => 'string' },
+      'smithy.api#Timestamp' => { 'type' => 'timestamp' },
+      'smithy.api#Unit' => { 'type' => 'structure', 'members' => {}, 'traits' => { 'smithy.api#unitType' => {} } }
+    }.freeze
+
+    # @param [Hash] model Model
+    # @param [String] id Shape ID
+    # @return [Hash]
+    def self.shape(model, id)
+      if model['shapes'].key?(id)
+        Flattener.new(model).shape(id)
+      elsif PRELUDE_SHAPES.key?(id)
+        PRELUDE_SHAPES[id]
+      else
+        raise ArgumentError, "Shape not found: #{id}"
+      end
+    end
+  end
+end

data/lib/smithy/plan.rb

@@ -1,10 +1,86 @@
 # frozen_string_literal: true
 
 module Smithy
+  # The Plan class is a simple data structure that holds the model, type, and options for a generator.
   class Plan
-    def initialize(*args)
-      puts 'Creating a Smithy plan'
-      puts "ARGS: #{args.join(', ')}"
+    # @param [Hash] model The API model as a JSON hash.
+    # @param [Symbol] type The type of code to generate, either :client, :server, or :schema.
+    # @param [Hash] options
+    # @option options [String] :name The name of the service to generate code for.
+    # @option options [String] :module_name The module name for clients and schemas.
+    #  Defaults to the name of the service.
+    # @option options [String] :gem_name The gem name for clients and schemas.
+    #  Defaults to a gem name derived from the module name, suffixed with '-schema' if type is schema.
+    # @option options [String] :gem_version The version of the gem to generate.
+    # @option options [String] :destination_root The destination directory for the generated code.
+    #  If not provided, source code will be generated to STDOUT.
+    # @option options [Boolean] :quiet Whether to suppress output.
+    def initialize(model, type, options = {})
+      @model = model
+      @type = type
+      @service = find_service(model['shapes'])
+
+      @name = options.fetch(:name, default_name(@service))
+      @module_name = options.fetch(:module_name, @name)
+      @gem_name = options.fetch(:gem_name, default_gem_name(@module_name, @type))
+      @gem_version = options.fetch(:gem_version)
+
+      @destination_root = options.fetch(:destination_root, nil)
+      @quiet = options.fetch(:quiet, false)
+
+      Welds.load!(self)
+      @welds = Welds.for(@service)
+    end
+
+    # @return [Hash] The API model as a JSON hash.
+    attr_reader :model
+
+    # @return [Symbol] The type of code to generate.
+    attr_reader :type
+
+    # @return [Hash<String, Hash>] The service shape for the shapes.
+    attr_reader :service
+
+    # @return [String] The name of the service.
+    attr_reader :name
+
+    # @return [String] The module name for clients and schemas.
+    attr_reader :module_name
+
+    # @return [String] The gem name for clients and schemas.
+    attr_reader :gem_name
+
+    # @return [String] The version of the gem to generate.
+    attr_reader :gem_version
+
+    # @return [String] The destination directory for the generated code.
+    attr_reader :destination_root
+
+    # @return [Boolean] Whether to suppress output.
+    attr_reader :quiet
+
+    # @return [Array<Weld>] The welds that apply to this plan.
+    attr_reader :welds
+
+    private
+
+    def find_service(shapes)
+      service = shapes.select { |_, shape| shape['type'] == 'service' }
+      raise 'Multiple service shapes found' if service.size > 1
+      raise 'No service shape found' if service.empty?
+
+      service
+    end
+
+    def default_name(service)
+      Model::Shape.name(service.keys.first)
+    end
+
+    def default_gem_name(module_name, type)
+      gem_name = module_name.split('::').map do |part|
+        part.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+      end.join('-')
+      type == :schema ? "#{gem_name.downcase}-schema" : gem_name.downcase
     end
   end
 end

data/lib/smithy/templates/client/auth_parameters.erb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# This is generated code!
+
+module <%= module_name %>
+  # Auth parameters used to resolve authentication per request.
+<% parameters.each do |param| -%>
+  # @!attribute <%= param.name %>
+<% param.docstrings.each do |docstring| -%>
+  #   <%= docstring %>
+<% end -%>
+  #
+  #   @return [<%= param.documentation_type %>]
+  #
+<% end -%>
+  AuthParameters = Struct.new(
+<% parameters.each do |param| -%>
+    :<%= param.name %>,
+<% end -%>
+    keyword_init: true
+  ) do
+
+    # @api private
+    def self.create(context)
+      # TODO: support more properties
+      new(operation_name: context.operation_name)
+    end
+  end
+end

data/lib/smithy/templates/client/auth_parameters_rbs.erb

@@ -0,0 +1,14 @@
+module <%= module_name %>
+  class AuthParameters
+    def initialize: (
+<% parameters.each do |param| -%>
+      <%= '?' unless param.name == :operation_name %><%= param.name %>: <%= param.rbs_type %>,
+<% end -%>
+    ) -> void
+    | (?Hash[Symbol, untyped]) -> void
+
+<% parameters.each do |param| -%>
+    attr_accessor <%= param.name %>: <%= param.rbs_type %><%= '?' unless param.name == :operation_name %>
+<% end -%>
+  end
+end

data/lib/smithy/templates/client/auth_plugin.erb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+# This is generated code!
+
+module <%= module_name %>
+  module Plugins
+    # @api private
+    class Auth < Smithy::Client::Plugin
+      option(
+        :auth_resolver,
+        doc_type: '<%= module_name %>::AuthResolver',
+        docstring: <<~DOCS) do |config|
+          The auth resolver used to resolve authentication. Any object that responds to `#resolve(parameters)`.
+        DOCS
+        AuthResolver.new
+      end
+
+      option(
+        :auth_schemes,
+        doc_type: Hash,
+        rbs_type: 'Hash[String, Smithy::Client::AuthScheme]',
+        docstring: <<~DOCS) do |config|
+          The auth schemes used to resolve authentication. The key is the scheme name as a String,
+          and the value is an initialized auth scheme class.
+        DOCS
+        {
+<% auth_schemes.each do |k, v| -%>
+          '<%= k %>' => config.<%= v %>,
+<% end -%>
+        }
+      end
+
+      # @api private
+      class Handler < Smithy::Client::Handler
+        def call(context)
+          # TODO: apply endpoint auth properties if present
+          auth_params = AuthParameters.create(context)
+          auth_options = context.config.auth_resolver.resolve(auth_params)
+          context[:auth] = resolve_auth(context, auth_options)
+          @handler.call(context)
+        end
+
+        private
+
+        def resolve_auth(context, auth_options)
+          failures = []
+
+          raise 'No auth options were resolved' if auth_options.empty?
+
+          identity_providers = {
+<% identity_providers.each do |k, v| -%>
+            <%= k %> => context.config.<%= v %>,
+<% end -%>
+          }
+
+          auth_options.each do |auth_option|
+            auth_scheme = context.config.auth_schemes[auth_option.scheme_id]
+            resolved_auth = try_load_auth_scheme(
+              auth_option,
+              auth_scheme,
+              identity_providers,
+              failures
+            )
+
+            return resolved_auth if resolved_auth
+          end
+
+          raise failures.join("\n")
+        end
+
+        def try_load_auth_scheme(auth_option, auth_scheme, identity_providers, failures)
+          scheme_id = auth_option.scheme_id
+          unless auth_scheme
+            failures << "Auth scheme #{scheme_id} was not enabled " \
+              'for this request'
+            return
+          end
+
+          identity_provider = auth_scheme.identity_provider(identity_providers)
+          unless identity_provider
+            failures << "Auth scheme #{scheme_id} did not have an " \
+              'identity resolver configured'
+            return
+          end
+
+          identity_properties = auth_option.identity_properties
+          identity = identity_provider.identity(identity_properties)
+
+          ResolvedAuth.new(
+            scheme_id: scheme_id,
+            identity: identity,
+            identity_properties: auth_option.identity_properties,
+            signer: auth_scheme.signer,
+            signer_properties: auth_option.signer_properties
+          )
+        end
+
+        # @api private
+        class ResolvedAuth
+          def initialize(options = {})
+            @scheme_id = options[:scheme_id]
+            @signer = options[:signer]
+            @signer_properties = options[:signer_properties]
+            @identity = options[:identity]
+            @identity_properties = options[:identity_properties]
+          end
+
+          attr_accessor :scheme_id, :signer, :signer_properties, :identity, :identity_properties
+        end
+      end
+
+      handler(Handler, step: :sign, priority: 70)
+    end
+  end
+end

data/lib/smithy/templates/client/auth_resolver.erb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# This is generated code!
+
+module <%= module_name %>
+  # Resolves the auth scheme from {AuthParameters}.
+  class AuthResolver
+    # @param [AuthParameters] parameters
+    # @return [Smithy::Client::AuthOption]
+    def resolve(parameters)
+<% auth_rules_code.each do |line| -%>
+      <%= line %>
+<% end -%>
+    end
+  end
+end

data/lib/smithy/templates/client/auth_resolver_rbs.erb

@@ -0,0 +1,5 @@
+module <%= module_name %>
+  class AuthResolver
+    def resolve: (AuthParameters) -> Array[Smithy::Client::AuthOption]
+  end
+end

data/lib/smithy/templates/client/client.erb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+# This is generated code!
+
+<%require_plugins.each do |require| -%>
+<%= require %>
+<% end -%>
+
+module <%= module_name %>
+  # An API client for <%= module_name %>.
+  # See {#initialize} for a full list of supported configuration options.
+  class Client < Smithy::Client::Base
+    include Smithy::Client::Stubs
+
+    self.service = Schema::<%= service_name %>
+
+<% add_plugins.each do |plugin_class| -%>
+    add_plugin(<%= plugin_class %>)
+<% end -%>
+
+    # @param options [Hash] Client options
+<% docstrings.each do |docstring| -%>
+    # <%= docstring %>
+<% end -%>
+    def initialize(*options)
+      super
+    end
+
+<% operations.each do |operation| -%>
+<% operation.docstrings.each do |docstring| -%>
+    # <%= docstring %>
+<% end -%>
+    def <%= operation.method_name %>(params = {}, options = {})
+      request = build_request(:<%= operation.method_name %>, params)
+      request.send_request(options)
+    end
+
+<% end -%>
+    # 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 reaches the maximum wait time allowed
+    #
+    # In between attempts, the waiter will sleep.
+    #
+    #     # polls in a loop, sleeping between attempts
+    #     client.wait_until(waiter_name, params, options)
+    #
+    # ## Configuration
+    #
+    # You must configure the maximum amount of time in seconds a
+    # waiter should wait for. You may also configure the minimum
+    # and maximum amount of time in seconds to delay between
+    # retries. You can pass these configuration as the final
+    # arguments hash.
+    #
+    #     weather = Weather::Client.new
+    #
+    #     # poll for a maximum of 25 seconds
+    #     weather.wait_until(:forecast_exists, { forecast_id: '1' }, {
+    #       max_wait_time: 25,
+    #       min_delay: 2,
+    #       max_delay: 10
+    #     })
+    #
+    # ## Handling Errors
+    #
+    # When a waiter is unsuccessful, it will raise an error.
+    # All the failure errors extend from
+    # {Smithy::Client::Waiters::WaiterFailed}.
+    #
+    #     weather = Weather::Client.new
+    #     begin
+    #       weather.wait_until(:forecast_exists, { forecast_id: '1' }, max_wait_time: 60)
+    #     rescue Smithy::Client::Waiters::WaiterFailed
+    #       # resource did not enter the desired state in time
+    #     end
+    #
+    # @param [Symbol] waiter_name
+    # @param [Hash] params ({})
+    # @param [Hash] options ({})
+    # @option options [Integer] :max_wait_time
+    # @option options [Integer] :min_delay
+    # @option options [Integer] :max_delay
+    # @return [nil] Returns `nil` if the waiter was successful.
+    # @raise [FailureStateError] Raised when the waiter terminates
+    #   because the waiter has entered a state that it will not transition
+    #   out of, preventing success.
+    # @raise [MaxWaitTimeExceededError] Raised when the configured
+    #   maximum wait time is reached and the waiter is not yet successful.
+    # @raise [UnexpectedError] Raised when an error that is not
+    #   expected is encountered while polling for a resource.
+    # @raise [NoSuchWaiterError] Raised when you request to wait
+    #   for an unknown state.
+    def wait_until(waiter_name, params = {}, options = {})
+      waiter(waiter_name, options).wait(params)
+    end
+
+    # @api private
+    def build_request(operation_name, params)
+      handlers = @handlers.for(operation_name)
+      context = Smithy::Client::HandlerContext.new(
+        operation_name: operation_name,
+        operation: config.service.operation(operation_name),
+        client: self,
+        config: config,
+        params: params
+      )
+      context[:gem_name] = '<%= gem_name %>'
+      context[:gem_version] = '<%= gem_version %>'
+      Smithy::Client::Request.new(handlers: handlers, context: context)
+    end
+
+    private
+
+    def waiters
+<% waiters.each do |line| -%>
+      <%= line %>
+<% end -%>
+    end
+
+    class << self
+      # @api private
+      attr_reader :identifier
+
+      # @api private
+      def protocols
+        <%= protocols %>
+      end
+
+      # @api private
+      def errors_module
+        Errors
+      end
+    end
+  end
+end