smithy-client 1.0.0.pre0 → 1.0.0.pre1

data/lib/smithy-client/request.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    # Represents a request for a service operation call.
+    class Request
+      include HandlerBuilder
+
+      # @option options [HandlerList] :handlers (nil)
+      # @option options [HandlerContext] :context (nil)
+      def initialize(options = {})
+        @handlers = options[:handlers] || HandlerList.new
+        @context = options[:context] || HandlerContext.new
+      end
+
+      # @return [HandlerList]
+      attr_reader :handlers
+
+      # @return [HandlerContext]
+      attr_reader :context
+
+      # Sends the request, returning an {Response} object.
+      #
+      #     response = request.send_request
+      #
+      # # Streaming Responses
+      #
+      # By default, responses are buffered into memory. This can be
+      # bad if you are downloading large responses, e.g. large files.
+      # You can avoid this by streaming the response to a block or some other
+      # target.
+      #
+      # ## Streaming to a File
+      #
+      # You can stream the raw response bodies to a File, or any IO-like
+      # object, by passing the `:target` option.
+      #
+      #     # create a new file at the given path
+      #     request.send_request(target: '/path/to/target/file')
+      #
+      #     # or provide an IO object to write to
+      #     File.open('photo.jpg', 'wb') do |file|
+      #       request.send_request(target: file)
+      #     end
+      #
+      # **Please Note**: The target IO object may receive `#truncate(0)`
+      # if the request generates a networking error and bytes have already
+      # been written to the target.
+      #
+      # ## Block Streaming
+      #
+      # Pass a block to `#send_request` and the response will be yielded in
+      # chunks to the given block.
+      #
+      #     # stream the response data
+      #     request.send_request do |chunk|
+      #       file.write(chunk)
+      #     end
+      #
+      # **Please Note**: When streaming to a block, it is not possible to
+      # retry failed requests.
+      #
+      # @option options [String, IO] :target When specified, the response
+      #   body is written to the target. This is helpful when you are sending
+      #   a request that may return a large payload that you don't want to
+      #   load into memory.
+      #
+      # @return [Response, nil]
+      #
+      def send_request(options = {}, &block)
+        @context[:response_target] = options[:target] || block
+        @handlers.to_stack&.call(@context)
+      end
+    end
+  end
+end

data/lib/smithy-client/response.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module Smithy
+  module Client
+    # Represents the response for a service operation call.
+    class Response < Delegator
+      # @option options [HandlerContext] :context (nil)
+      # @option options [Structure] :data (nil)
+      # @option options [StandardError] :error (nil)
+      def initialize(options = {})
+        @context = options[:context] || HandlerContext.new
+        @data = options[:data]
+        @error = options[:error]
+        @context.http_response.on_error { |error| @error = error }
+        super(@error || @data)
+      end
+
+      # @return [HandlerContext]
+      attr_reader :context
+
+      # @return [Structure, nil] The response data. This may be `nil` if the
+      #  response contains an {#error}.
+      attr_accessor :data
+
+      # @return [StandardError, nil] The error that occurred during the
+      #  operation.  This will be `nil` if the operation was successful.
+      attr_accessor :error
+
+      # Necessary to define as a subclass of Delegator
+      # @api private
+      def __getobj__(&)
+        @error || @data
+      end
+
+      # Necessary to define as a subclass of Delegator
+      # @api private
+      def __setobj__(obj)
+        if obj.is_a?(StandardError)
+          @error = obj
+        else
+          @data = obj
+        end
+      end
+    end
+  end
+end

data/lib/smithy-client/retry/adaptive.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module Retry
+      # Adaptive retry strategy for retrying requests.
+      class Adaptive
+        # @option [#call] :backoff (EXPONENTIAL_BACKOFF) A callable object that
+        #  calculates a backoff delay for a retry attempt.
+        # @option [Integer] :max_attempts (3) The maximum number of attempts that
+        #  will be made for a single request, including the initial attempt.
+        # @option [Boolean] :wait_to_fill When true, the request will sleep until
+        #  there is sufficient client side capacity to retry the request. When
+        #  false, the request will raise a `CapacityNotAvailableError` and will
+        #  not retry instead of sleeping.
+        def initialize(options = {})
+          super()
+          @backoff = options[:backoff] || EXPONENTIAL_BACKOFF
+          @max_attempts = options[:max_attempts] || 3
+          @wait_to_fill = options[:wait_to_fill] || true
+          @client_rate_limiter = ClientRateLimiter.new
+          @quota = Quota.new
+          @capacity_amount = 0
+        end
+
+        # @return [#call]
+        attr_reader :backoff
+
+        # @return [Integer]
+        attr_reader :max_attempts
+
+        # @return [Boolean]
+        attr_reader :wait_to_fill
+
+        def acquire_initial_retry_token(_token_scope = nil)
+          @client_rate_limiter.token_bucket_acquire(1, wait_to_fill: @wait_to_fill)
+          Token.new
+        end
+
+        def refresh_retry_token(retry_token, error_info)
+          return unless error_info.retryable?
+
+          @client_rate_limiter.update_sending_rate(
+            error_info.error_type == 'Throttling'
+          )
+          return if retry_token.retry_count >= @max_attempts - 1
+
+          @capacity_amount = @quota.checkout_capacity(error_info)
+          return unless @capacity_amount.positive?
+
+          delay = error_info.hints[:retry_after]
+          delay ||= @backoff.call(retry_token.retry_count)
+          retry_token.retry_count += 1
+          retry_token.retry_delay = delay
+          retry_token
+        end
+
+        def record_success(retry_token)
+          @client_rate_limiter.update_sending_rate(false)
+          @quota.release(@capacity_amount)
+          retry_token
+        end
+      end
+    end
+  end
+end

data/lib/smithy-client/retry/client_rate_limiter.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module Retry
+      # Raised when the adaptive retry strategy is unable to acquire capacity.
+      class CapacityNotAvailableError < RuntimeError; end
+
+      # Used only in 'adaptive' retry mode
+      # @api private
+      class ClientRateLimiter
+        MIN_CAPACITY = 1
+        MIN_FILL_RATE = 0.5
+        SMOOTH = 0.8
+        # How much to scale back after a throttling response
+        BETA = 0.7
+        # Controls how aggressively we scale up after being throttled
+        SCALE_CONSTANT = 0.4
+
+        def initialize
+          @mutex = Mutex.new
+          @fill_rate = nil
+          @max_capacity = nil
+          @current_capacity = 0
+          @last_timestamp = nil
+          @enabled = false
+          @measured_tx_rate = 0
+          @last_tx_rate_bucket = monotonic_seconds
+          @request_count = 0
+          @last_max_rate = 0
+          @last_throttle_time = monotonic_seconds
+          @calculated_rate = nil
+        end
+
+        def token_bucket_acquire(amount, wait_to_fill: true)
+          # Client side throttling is not enabled until we see a
+          # throttling error
+          return unless @enabled
+
+          @mutex.synchronize do
+            token_bucket_refill
+
+            # Next see if we have enough capacity for the requested amount
+            while @current_capacity < amount
+              raise CapacityNotAvailableError unless wait_to_fill
+
+              @mutex.sleep((amount - @current_capacity) / @fill_rate)
+              token_bucket_refill
+            end
+            @current_capacity -= amount
+          end
+        end
+
+        def update_sending_rate(is_throttling_error)
+          @mutex.synchronize do
+            update_measured_rate
+
+            if is_throttling_error
+              # The fill_rate is from the token bucket
+              @last_max_rate = rate_to_use
+              calculate_time_window
+              @last_throttle_time = monotonic_seconds
+              @calculated_rate = cubic_throttle(rate_to_use)
+              @enabled = true
+            else
+              calculate_time_window
+              @calculated_rate = cubic_success(monotonic_seconds)
+            end
+
+            new_rate = [@calculated_rate, 2 * @measured_tx_rate].min
+            token_bucket_update_rate(new_rate)
+          end
+        end
+
+        private
+
+        def monotonic_seconds
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+
+        def token_bucket_refill
+          timestamp = monotonic_seconds
+          unless @last_timestamp
+            @last_timestamp = timestamp
+            return
+          end
+
+          fill_amount = (timestamp - @last_timestamp) * @fill_rate
+          @current_capacity = [@max_capacity, @current_capacity + fill_amount].min
+          @last_timestamp = timestamp
+        end
+
+        def token_bucket_update_rate(new_rps)
+          # Refill based on our current rate before we update to the
+          # new fill rate
+          token_bucket_refill
+          @fill_rate = [new_rps, MIN_FILL_RATE].max
+          @max_capacity = [new_rps, MIN_CAPACITY].max
+          # When we scale down we can't have a current capacity that exceeds our
+          # max_capacity.
+          @current_capacity = [@current_capacity, @max_capacity].min
+        end
+
+        def update_measured_rate
+          t = monotonic_seconds
+          time_bucket = (t * 2).floor / 2.0
+          @request_count += 1
+          return unless time_bucket > @last_tx_rate_bucket
+
+          current_rate = @request_count / (time_bucket - @last_tx_rate_bucket)
+          @measured_tx_rate = (current_rate * SMOOTH) + (@measured_tx_rate * (1 - SMOOTH))
+          @request_count = 0
+          @last_tx_rate_bucket = time_bucket
+        end
+
+        def calculate_time_window
+          # This is broken out into a separate calculation because it only
+          # gets updated when @last_max_rate changes so it can be cached.
+          base = ((@last_max_rate * (1 - BETA)) / SCALE_CONSTANT)
+          @time_window = base**(1.0 / 3)
+        end
+
+        def cubic_success(timestamp)
+          dt = timestamp - @last_throttle_time
+          (SCALE_CONSTANT * ((dt - @time_window)**3)) + @last_max_rate
+        end
+
+        def cubic_throttle(rate_to_use)
+          rate_to_use * BETA
+        end
+
+        def rate_to_use
+          if @enabled
+            [@measured_tx_rate, @fill_rate].min
+          else
+            @measured_tx_rate
+          end
+        end
+      end
+    end
+  end
+end

data/lib/smithy-client/retry/quota.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module Retry
+      # @api private
+      # Used in 'standard' and 'adaptive' retry modes.
+      class Quota
+        INITIAL_RETRY_TOKENS = 500
+        RETRY_COST = 5
+        NO_RETRY_INCREMENT = 1
+        TIMEOUT_RETRY_COST = 10
+
+        def initialize
+          @mutex = Mutex.new
+          @max_capacity = INITIAL_RETRY_TOKENS
+          @available_capacity = @max_capacity
+        end
+
+        # Check if there is sufficient capacity to retry and return it.
+        # If there is insufficient capacity, return 0
+        # @return [Integer] The amount of capacity checked out
+        def checkout_capacity(error_info)
+          @mutex.synchronize do
+            capacity_amount =
+              if error_info.error_type == 'Transient'
+                TIMEOUT_RETRY_COST
+              else
+                RETRY_COST
+              end
+
+            # unable to acquire capacity
+            return 0 if capacity_amount > @available_capacity
+
+            @available_capacity -= capacity_amount
+            capacity_amount
+          end
+        end
+
+        # capacity_amount refers to the amount of capacity requested from
+        # the last retry.  It can either be RETRY_COST, TIMEOUT_RETRY_COST,
+        # or unset.
+        def release(capacity_amount)
+          # Implementation note:  The release() method is called for
+          # every API call.  In the common case where the request is
+          # successful and we're at full capacity, we can avoid locking.
+          # We can't exceed max capacity so there's no work we have to do.
+          return if @available_capacity == @max_capacity
+
+          @mutex.synchronize do
+            @available_capacity += capacity_amount || NO_RETRY_INCREMENT
+            @available_capacity = [@available_capacity, @max_capacity].min
+          end
+        end
+      end
+    end
+  end
+end

data/lib/smithy-client/retry/standard.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module Retry
+      # Standard retry strategy for retrying requests.
+      class Standard
+        # @option [#call] :backoff (EXPONENTIAL_BACKOFF) A callable object that
+        #  calculates a backoff delay for a retry attempt.
+        # @option [Integer] :max_attempts (3) The maximum number of attempts that
+        #  will be made for a single request, including the initial attempt.
+        def initialize(options = {})
+          super()
+          @backoff = options[:backoff] || EXPONENTIAL_BACKOFF
+          @max_attempts = options[:max_attempts] || 3
+          @quota = Quota.new
+          @capacity_amount = 0
+        end
+
+        # @return [#call]
+        attr_reader :backoff
+
+        # @return [Integer]
+        attr_reader :max_attempts
+
+        def acquire_initial_retry_token(_token_scope = nil)
+          Token.new
+        end
+
+        def refresh_retry_token(retry_token, error_info)
+          return unless error_info.retryable?
+
+          return if retry_token.retry_count >= @max_attempts - 1
+
+          @capacity_amount = @quota.checkout_capacity(error_info)
+          return unless @capacity_amount.positive?
+
+          delay = error_info.hints[:retry_after]
+          delay ||= @backoff.call(retry_token.retry_count)
+          retry_token.retry_count += 1
+          retry_token.retry_delay = delay
+          retry_token
+        end
+
+        def record_success(retry_token)
+          @quota.release(@capacity_amount)
+          retry_token
+        end
+      end
+    end
+  end
+end

data/lib/smithy-client/retry.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'retry/adaptive'
+require_relative 'retry/client_rate_limiter'
+require_relative 'retry/quota'
+require_relative 'retry/standard'
+
+module Smithy
+  module Client
+    module Retry
+      # The maximum backoff delay for retrying requests.
+      MAX_BACKOFF = 20
+
+      # The default backoff for retrying requests.
+      EXPONENTIAL_BACKOFF = lambda do |attempts|
+        [Kernel.rand * (2**attempts), MAX_BACKOFF].min || 0
+      end
+
+      # Represents a token that can be used to retry an operation.
+      class Token
+        def initialize
+          @retry_count = 0
+          @retry_delay = 0
+        end
+
+        # The number of times the operation has been retried.
+        # @return [Integer]
+        attr_accessor :retry_count
+
+        # The delay before the next retry.
+        # @return [Numeric]
+        attr_accessor :retry_delay
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'request_builder'
+require_relative 'response_parser'
+require_relative 'response_stubber'
+
+module Smithy
+  module Client
+    module RPCv2CBOR
+      # @api private
+      class Protocol
+        def initialize(options = {})
+          @options = options
+        end
+
+        def build_request(context)
+          RequestBuilder.new(@options).build(context)
+        end
+
+        def parse_error(response)
+          ResponseParser.new(@options).parse_error(response.context)
+        end
+
+        def parse_data(response)
+          ResponseParser.new(@options).parse_data(response.context)
+        end
+
+        def stub_data(service, operation, data)
+          ResponseStubber.new(@options).stub_data(service, operation, data)
+        end
+
+        def stub_error(service, error_code)
+          ResponseStubber.new(@options).stub_error(service, error_code)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module RPCv2CBOR
+      # @api private
+      class RequestBuilder
+        include Schema::Shapes
+
+        def initialize(options = {})
+          @codec = CBOR::Codec.new(options)
+        end
+
+        def build(context)
+          apply_http_method(context)
+          apply_headers(context)
+          apply_body(context)
+          apply_url_path(context)
+        end
+
+        private
+
+        def apply_http_method(context)
+          context.http_request.http_method = 'POST'
+        end
+
+        def apply_headers(context)
+          context.http_request.headers['Smithy-Protocol'] = 'rpc-v2-cbor'
+          apply_content_type_header(context)
+          apply_accept_header(context)
+        end
+
+        def apply_content_type_header(context)
+          input = context.operation.input
+          content_type =
+            if event_stream?(input)
+              'application/vnd.amazon.eventstream'
+            elsif input.shape != Prelude::Unit
+              'application/cbor'
+            end
+
+          context.http_request.headers['Content-Type'] ||= content_type if content_type
+        end
+
+        def apply_accept_header(context)
+          accept =
+            if event_stream?(context.operation.output)
+              'application/vnd.amazon.eventstream'
+            else
+              'application/cbor'
+            end
+
+          context.http_request.headers['Accept'] ||= accept
+        end
+
+        def apply_body(context)
+          context.http_request.body = @codec.serialize(context.operation.input, context.params)
+        end
+
+        def apply_url_path(context)
+          base = context.http_request.endpoint
+          service_name = context.config.service.name
+          base.path += "/service/#{service_name}/operation/#{context.operation.name}"
+        end
+
+        def event_stream?(ref)
+          ref.shape.members.each_value do |member_ref|
+            shape = member_ref.shape
+            return true if shape.traits.key?('smithy.api#streaming') && shape.is_a?(UnionShape)
+          end
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module RPCv2CBOR
+      # @api private
+      class ResponseParser
+        def initialize(options = {})
+          @codec = CBOR::Codec.new(options)
+        end
+
+        def parse_error(context)
+          if !valid_response?(context)
+            code, message, data = http_status_error(context)
+            build_error(context, code, message, data)
+          elsif (300..599).cover?(context.http_response.status_code)
+            error(context)
+          end
+        end
+
+        def parse_data(context)
+          @codec.deserialize(context.operation.output, context.http_response.body.read)
+        end
+
+        private
+
+        def valid_response?(context)
+          req_header = context.http_request.headers['smithy-protocol']
+          resp_header = context.http_request.headers['smithy-protocol']
+          req_header == resp_header
+        end
+
+        def error(context)
+          body = context.http_response.body.read
+          if body.empty?
+            code, message, data = http_status_error(context)
+          else
+            code, message, data = extract_error(body, context)
+          end
+          build_error(context, code, message, data)
+        end
+
+        def extract_error(body, context)
+          data = CBOR.decode(body)
+          type = data['__type']
+          code = error_code(type, context)
+          message = data['message']
+          data = parse_error_data(context, body, type)
+          [code, message, data]
+        rescue CBOR::Error
+          [http_status_error_code(context), '', Schema::EmptyStructure.new]
+        end
+
+        def parse_error_data(context, body, code)
+          data = Schema::EmptyStructure.new
+          context.operation.errors.each do |ref|
+            next unless ref.shape.id == code
+
+            data = @codec.deserialize(ref, body, ref.shape.type.new)
+          end
+          data
+        end
+
+        def error_code(type, context)
+          return type.split('#').last if type
+
+          http_status_error_code(context)
+        end
+
+        def build_error(context, code, message, data)
+          errors_module = context.client.class.errors_module
+          errors_module.error_class(code).new(context, message, data)
+        end
+
+        def http_status_error(context)
+          [http_status_error_code(context), '', Schema::EmptyStructure.new]
+        end
+
+        def http_status_error_code(context)
+          status_code = context.http_response.status_code
+          "HTTP#{status_code}Error"
+        end
+      end
+    end
+  end
+end