smithy-client 1.0.0.pre0 → 1.0.0.pre1

data/lib/smithy-client/rpc_v2_cbor/response_stubber.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module RPCv2CBOR
+      # @api private
+      class ResponseStubber
+        def initialize(options = {})
+          @codec = CBOR::Codec.new(options)
+        end
+
+        def stub_data(_service, operation, data)
+          response = HTTP::Response.new
+          response.status_code = 200
+          response.headers['Smithy-Protocol'] = 'rpc-v2-cbor'
+          response.headers['Content-Type'] = 'application/cbor'
+          response.body = @codec.serialize(operation.output, data)
+          response
+        end
+
+        def stub_error(_service, error_code)
+          response = HTTP::Response.new
+          response.status_code = 400
+          response.headers['Smithy-Protocol'] = 'rpc-v2-cbor'
+          response.headers['Content-Type'] = 'application/cbor'
+          response.headers['X-Amzn-RequestId'] = 'stubbed-request-id'
+          data = { '__type' => error_code, 'message' => 'stubbed-error-message' }
+          response.body = CBOR.encode(data)
+          response
+        end
+      end
+    end
+  end
+end

data/lib/smithy-client/service_error.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    # The base class for all errors returned by a Smithy generated client.
+    # All ~400 level client errors and ~500 level server errors are raised
+    # as service errors. This indicates it was an error returned from the
+    # service and not one generated by the client.
+    class ServiceError < RuntimeError
+      # @param [Smithy::Client::HandlerContext] context
+      # @param [String] message
+      # @param [Structure] data
+      def initialize(context, message, data)
+        @code = self.class.code
+        @context = context
+        @message = extract_message(message, data)
+        @data = data
+        super(@message)
+      end
+
+      # @return [String, nil] The error code returned by the service.
+      attr_reader :code
+
+      # @return [Smithy::Client::HandlerContext] The context of the request
+      #  that triggered the remote service to return this error.
+      attr_reader :context
+
+      # @return [String] The error message returned by the service.
+      #  Defaults to the class name if no message is provided or can be parsed.
+      attr_reader :message
+
+      # @return [Structure] Additional data returned by the service.
+      attr_accessor :data
+
+      class << self
+        # @return [String, nil]
+        attr_accessor :code
+      end
+
+      # @return [Boolean] Returns `true` if the error is retryable.
+      def retryable?
+        false
+      end
+
+      # @return [Boolean] Returns `true` if the error is due to throttling.
+      def throttling?
+        false
+      end
+
+      private
+
+      def extract_message(message, data)
+        message || (data.message if data.respond_to?(:message)) || self.class.name.to_s
+      end
+    end
+  end
+end

data/lib/smithy-client/signer.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    # Base class for all Signer classes.
+    class Signer
+      def sign(_options = {})
+        raise NotImplementedError
+      end
+
+      def reset(_options = {})
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/smithy-client/signers/anonymous.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module Signers
+      # A signer that does not sign requests.
+      class Anonymous < Signer
+        def sign(**); end
+        def reset(**); end
+      end
+    end
+  end
+end

data/lib/smithy-client/signers/http_api_key.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module Signers
+      # A signer that signs requests using the HTTP API Key Auth scheme.
+      class HttpApiKey < Signer
+        def sign(request:, identity:, properties:)
+          case properties['in']
+          when 'header'
+            value = "#{properties['scheme']} #{identity.key}".strip
+            request.headers[properties['name']] = value
+          when 'query'
+            name = properties['name']
+            append_query_param(request, name, identity.key)
+          end
+        end
+
+        def reset(request:, properties:)
+          case properties['in']
+          when 'header'
+            request.headers.delete(properties['name'])
+          when 'query'
+            name = properties['name']
+            remove_query_param(request, name)
+          end
+        end
+
+        private
+
+        def append_query_param(request, name, value)
+          if request.endpoint.query
+            request.endpoint.query += "&#{name}=#{value}"
+          else
+            request.endpoint.query = "#{name}=#{value}"
+          end
+        end
+
+        def remove_query_param(request, name)
+          parsed = CGI.parse(request.endpoint.query)
+          parsed.delete(name)
+          # encode_www_form ignores query params without values
+          # (CGI parses these as empty lists)
+          parsed.each do |key, values|
+            parsed[key] = values.empty? ? nil : values
+          end
+          request.endpoint.query = URI.encode_www_form(parsed)
+        end
+      end
+    end
+  end
+end

data/lib/smithy-client/signers/http_basic.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Smithy
+  module Client
+    module Signers
+      # A signer that signs requests using the HTTP Basic Auth scheme.
+      class HttpBasic < Signer
+        def sign(request:, identity:, **_options)
+          # TODO: does not handle realm or other properties
+          identity_string = "#{identity.username}:#{identity.password}"
+          encoded = Base64.strict_encode64(identity_string)
+          request.headers['Authorization'] = "Basic #{encoded}"
+        end
+
+        def reset(request:, **_options)
+          request.headers.delete('Authorization')
+        end
+      end
+    end
+  end
+end

data/lib/smithy-client/signers/http_bearer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module Signers
+      # A signer that signs requests using the HTTP Bearer Auth scheme.
+      class HttpBearer < Signer
+        def sign(request:, identity:, **_options)
+          # TODO: does not handle realm or other properties
+          request.headers['Authorization'] = "Bearer #{identity.token}"
+        end
+
+        def reset(request:, **_options)
+          request.headers.delete('Authorization')
+        end
+      end
+    end
+  end
+end

data/lib/smithy-client/signers/http_digest.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module Signers
+      # A signer that signs requests using the HTTP Digest Auth scheme.
+      class HttpDigest < Signer
+        def sign(request:, identity:, **_options)
+          # TODO: requires a nonce from the server - this cannot
+          # be implemented unless we rescue from a 401 and retry
+          # with the nonce
+          raise NotImplementedError
+        end
+
+        def reset(request:, **_options)
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/smithy-client/stubbing/data_applicator.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module Stubbing
+      # Applies data to a stubbed object.
+      # @api private
+      class DataApplicator
+        include Smithy::Schema::Shapes
+
+        def initialize(ref)
+          @ref = ref
+        end
+
+        def apply(data, stub)
+          structure(@ref, data, stub)
+        end
+
+        private
+
+        def shape(ref, value, stub = nil)
+          case ref.shape
+          when StructureShape then structure(ref, value, stub)
+          when ListShape then list(ref, value)
+          when MapShape then map(ref, value)
+          else value
+          end
+        end
+
+        def list(ref, value)
+          return if value.nil?
+
+          shape = ref.shape
+          value.each_with_object([]) do |v, list|
+            list << shape(shape.member, v)
+          end
+        end
+
+        def map(ref, value)
+          return if value.nil?
+
+          shape = ref.shape
+          value.each_with_object({}) do |(k, v), map|
+            map[k.to_s] = shape(shape.value, v)
+          end
+        end
+
+        def structure(ref, data, stub)
+          return if data.nil?
+
+          stub = ref.shape.type.new if stub.nil?
+          shape = ref.shape
+          data.each_pair do |key, value|
+            stub[key] = shape(shape.member(key), value)
+          end
+          stub
+        end
+      end
+    end
+  end
+end

data/lib/smithy-client/stubbing/empty_stub.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+
+module Smithy
+  module Client
+    module Stubbing
+      # Creates an empty default stub.
+      # @api private
+      class EmptyStub
+        include Smithy::Schema::Shapes
+
+        def initialize(ref)
+          @ref = ref
+        end
+
+        # @return [Schema::Structure, Schema::EmptyStructure]
+        def stub
+          structure(@ref, [])
+        end
+
+        private
+
+        def shape(ref, visited)
+          shape = ref.shape
+          return nil if visited.include?(shape)
+
+          visited += [shape]
+
+          case shape
+          when ListShape then []
+          when MapShape then {}
+          when StructureShape then structure(ref, visited)
+          when UnionShape then union(ref, visited)
+          else scalar(ref)
+          end
+        end
+
+        def structure(ref, visited)
+          shape = ref.shape
+          shape.members.each_with_object(shape.type.new) do |(member_name, member_ref), struct|
+            struct[member_name] = shape(member_ref, visited)
+          end
+        end
+
+        def union(ref, visited)
+          shape = ref.shape
+          member_name, member_ref = shape.members.first
+          return unless member_name
+
+          value = shape(member_ref, visited)
+          klass = shape.member_type(member_name)
+          klass.new(member_name => value)
+        end
+
+        def scalar(ref)
+          case ref.shape
+          when BigDecimalShape then BigDecimal(0)
+          when BlobShape, EnumShape, StringShape then ref.member_name
+          when BooleanShape then false
+          when IntegerShape, IntEnumShape then 0
+          when FloatShape then 0.0
+          when TimestampShape then Time.now
+          end
+        end
+      end
+    end
+  end
+end

data/lib/smithy-client/stubbing/endpoint_provider.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module Stubbing
+      # Default endpoint provider when stubbing is configured.
+      # @api private
+      class EndpointProvider
+        def resolve(parameters)
+          uri =
+            if EndpointRules.set?(parameters.endpoint)
+              parameters.endpoint
+            else
+              'http://stubbed-endpoint'
+            end
+
+          EndpointRules::Endpoint.new(uri: uri)
+        end
+      end
+    end
+  end
+end

data/lib/smithy-client/stubbing/protocol.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module Stubbing
+      # Default protocol when stubbing is configured.
+      # @api private
+      class Protocol
+        def build_request(_context); end
+        def parse_data(_output); end
+        def parse_error(_output); end
+
+        def stub_data(_service, _operation, data)
+          response = HTTP::Response.new
+          response.status_code = 200
+          response.body = StringIO.new(data.to_json)
+          response
+        end
+
+        def stub_error(_service, error_code)
+          response = HTTP::Response.new
+          response.status_code = 500
+          response.body = StringIO.new(error_code.to_json)
+          response
+        end
+      end
+    end
+  end
+end

data/lib/smithy-client/stubbing/stub_data.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module Stubbing
+      # Stubs data for an operation.
+      # @api private
+      class StubData
+        def initialize(operation)
+          @output = operation.output
+        end
+
+        # @param [Hash] params
+        # @return [Structure]
+        def stub(params = {})
+          stub = EmptyStub.new(@output).stub
+          data = ParamConverter.new(@output).convert(params)
+          ParamValidator.new(@output, validate_required: false).validate!(data, context: 'stub')
+          DataApplicator.new(@output).apply(data, stub)
+          stub
+        end
+      end
+    end
+  end
+end

data/lib/smithy-client/stubbing.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'stubbing/data_applicator'
+require_relative 'stubbing/empty_stub'
+require_relative 'stubbing/endpoint_provider'
+require_relative 'stubbing/protocol'
+require_relative 'stubbing/stub_data'
+
+module Smithy
+  module Client
+    # @api private
+    module Stubbing; end
+  end
+end

data/lib/smithy-client/stubs.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    # This module provides the ability to specify the data and/or errors to
+    # return when a client is using stubbed responses.
+    module Stubs
+      # Configures what data / errors should be returned from the named operation
+      # when response stubbing is enabled.
+      #
+      # ## Basic usage
+      #
+      # When you enable response stubbing, the client will generate fake
+      # responses and will not make any HTTP requests:
+      #
+      #     client = Weather::Client.new(stub_responses: true)
+      #     client.get_current_time
+      #     #=> #<struct Weather::GetCurrentTimeOutput time=2025-01-20 12:00:00 -0500>
+      #
+      # You can specify the stub data using {#stub_responses}:
+      #
+      #     time = Time.now #=> 2025-01-20 12:00:00 -0500
+      #     client.stub_responses(:get_current_time, { time: time })
+      #     client.get_current_time.time #=> 2025-01-20 12:00:00 -0500
+      #
+      # ## Dynamic Stubbing
+      #
+      # In addition to creating static stubs, it's also possible to generate
+      # stubs dynamically based on the parameters with which operations were
+      # called, by passing a `Proc` object:
+      #
+      #     time = Time.now #=> 2025-01-20 12:00:00 -0500
+      #     client.stub_responses(:get_current_time, ->(context) do
+      #         if context.params[:time] == time
+      #           { time: time + 60 }
+      #         else
+      #           { time: time }
+      #         end
+      #       end
+      #     )
+      #
+      # The yielded object is an instance of {Smithy::Client::HandlerContext}.
+      #
+      # ## Stubbing Errors
+      #
+      # When stubbing is enabled, the SDK will default to generate
+      # fake responses with placeholder values. You can override the data
+      # returned. You can also specify errors it should raise:
+      #
+      #     # To simulate service errors, give the error code:
+      #     client.stub_responses(:get_city, 'NoSuchResource')
+      #     client.get_city(city_id: 'Winchester')
+      #     #=> raises Weather::Errors::NoSuchResource
+      #
+      #     # To simulate other errors, give the error class.
+      #     # You must be able to construct an instance with `.new`:
+      #     client.stub_responses(:get_city, Timeout::Error)
+      #     client.get_city(city_id: 'Winchester')
+      #     #=> raises new Timeout::Error
+      #
+      #     # Or you can give an instance of an error class:
+      #     error = RuntimeError.new('oops')
+      #     client.stub_responses(:get_city, error)
+      #     client.get_city(city_id: 'Winchester')
+      #     #=> raises error
+      #
+      # ## Stubbing HTTP Responses
+      #
+      # As an alternative to providing the response data, you can provide
+      # an HTTP response:
+      #
+      #     client.stub_responses(:get_current_time, {
+      #       status_code: 200,
+      #       headers: { 'header-name' => 'header-value' },
+      #       body: "payload",
+      #     })
+      #
+      # To stub an HTTP response, pass a Hash with all three of the following
+      # keys set:
+      #
+      # * **`:status_code`** - `Integer` - The HTTP status code
+      # * **`:headers`** - `Hash<String, String>` - A hash of HTTP header keys and values
+      # * **`:body`** - `<String, IO>` - The HTTP response body.
+      #
+      # ## Stubbing Multiple Responses
+      #
+      # Calling an operation multiple times will return similar responses.
+      # You can configure multiple stubs, and they will be returned in sequence:
+      #
+      #     client.stub_responses(:get_city, [
+      #       'NoSuchResource',
+      #       { name: 'Winchester', coordinates: { latitude: 39.1825, longitude: -78.1676 } }
+      #     ])
+      #
+      #     client.get_city(city_id: "Winchester')
+      #     #=> raises Weather::Errors::NoSuchResource
+      #
+      #     response = client.get_city(city_id: "Winchester')
+      #     response.name #=> 'Winchester'
+      #     response.coordinates.latitude #=> 39.1825
+      #     response.coordinates.longitude #=> -78.1676
+      #
+      # @param [Symbol] operation_name
+      # @param [Mixed] stubs One or more responses to return from the named operation.
+      # @raise [RuntimeError] Raises a runtime error when called on a client
+      #  that has not enabled response stubbing with `stub_responses: true`.
+      def stub_responses(operation_name, *stubs)
+        unless @config.stub_responses
+          raise 'stubbing is not enabled; enable stubbing in the constructor ' \
+                'with `stub_responses: true`'
+        end
+        apply_stubs(operation_name, stubs.flatten)
+      end
+
+      # Generates and returns stubbed response data from the named operation.
+      #
+      #     client = Weather::Client.new
+      #     client.stub_data(:get_current_time)
+      #     #=> #<struct Weather::Types::GetCurrentTimeOutput time=2025-01-20 12:00:00 -0500>
+      #
+      # In addition to generating default stubs, you can provide data to apply to the response stub.
+      #
+      #     time = Time.now #=> 2025-01-20 12:00:00 -0500
+      #     client.stub_data(:get_current_time, { time: time + 60 })
+      #     #=> #<struct Weather::Types::GetCurrentTimeOutput time=2025-01-20 12:01:00 -0500>
+      #
+      # @param [Symbol] operation_name
+      # @param [Hash] data
+      # @return [Structure] Returns a stubbed response data structure.
+      def stub_data(operation_name, data = {})
+        Stubbing::StubData.new(@config.service.operation(operation_name)).stub(data)
+      end
+
+      # Allows you to access all the requests that the stubbed client has made.
+      # @return [Array] Returns an array of the api requests made. Each request
+      #  object contains keys: :operation_name, :params and :context.
+      # @raise [RuntimeError] Raises a runtime error when called on a client
+      #  that has not enabled response stubbing with `stub_responses: true`.
+      def api_requests
+        unless @config.stub_responses
+          raise 'stubbing is not enabled; enable stubbing in the constructor ' \
+                'with `stub_responses: true`'
+        end
+        @config.api_requests_mutex.synchronize { @config.api_requests }
+      end
+
+      # @api private
+      def next_stub(context)
+        operation_name = context.operation_name
+        stub = @config.stubs_mutex.synchronize do
+          stubs = @config.stubs[operation_name] || []
+          case stubs.length
+          when 0 then stub_data(operation_name)
+          when 1 then stubs.first
+          else stubs.shift
+          end
+        end
+        stub = convert_stub(operation_name, stub, context)
+        stub[:mutex] = Mutex.new
+        stub
+      end
+
+      private
+
+      def apply_stubs(operation_name, stubs)
+        @config.stubs_mutex.synchronize do
+          @config.stubs[operation_name] = stubs
+        end
+      end
+
+      # This method converts the given stub data and converts it to a
+      # HTTP response (when possible). This enables the response stubbing
+      # plugin to provide a HTTP response that triggers all normal events
+      # during response handling.
+      def convert_stub(operation_name, stub, context)
+        case stub
+        when Proc then convert_stub(operation_name, stub.call(context), context)
+        when Exception, Class then { error: stub }
+        when String then service_error_stub(stub)
+        else http_response_stub(operation_name, stub)
+        end
+      end
+
+      def service_error_stub(error_code)
+        { http: @config.protocol.stub_error(@config.service, error_code) }
+      end
+
+      def http_response_stub(operation_name, data)
+        if data.is_a?(Hash) && data.keys.sort == %i[body headers status_code]
+          { http: hash_to_http_response(data) }
+        else
+          { http: data_to_http_response(operation_name, data) }
+        end
+      end
+
+      def hash_to_http_response(data)
+        http_response = HTTP::Response.new
+        http_response.status_code = data[:status_code]
+        http_response.headers.update(data[:headers])
+        http_response.body = data[:body]
+        http_response
+      end
+
+      def data_to_http_response(operation_name, data)
+        operation = @config.service.operation(operation_name)
+        data = ParamConverter.new(operation.output).convert(data)
+        ParamValidator.new(operation.output, validate_required: false).validate!(data, context: 'stub')
+        @config.protocol.stub_data(@config.service, operation, data)
+      end
+    end
+  end
+end