Waiters

gems/smithy-client/lib/smithy-client/waiters.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'waiters/errors'
+require_relative 'waiters/poller'
+require_relative 'waiters/waiter'

gems/smithy-client/lib/smithy-client/waiters/errors.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module Waiters
+      module Errors
+
+        # Raised when a waiter detects a condition where the waiter can never
+        # succeed.
+        class WaiterFailed < StandardError; end
+
+        class FailureStateError < WaiterFailed
+          def initialize(error)
+            msg = "stopped waiting, encountered a failure state: %s"
+            super(msg % [error])
+          end
+        end
+
+        class MaxWaitTimeExceededError < WaiterFailed
+          def initialize(max_wait_time)
+            msg = "stopped waiting after maximum wait time of %s seconds was exceeded"
+            super(msg % [max_wait_time])
+          end
+        end
+
+        class UnexpectedError < WaiterFailed
+          def initialize(error)
+            msg = "stopped waiting due to an unexpected error: %s"
+            super(msg % [error])
+          end
+        end
+
+        # Raised when attempting to get a waiter by name and the waiter has not
+        # been defined.
+        class NoSuchWaiterError < ArgumentError
+          def initialize(waiter_name, valid_waiters)
+            msg = "no such waiter: %s; valid waiter names are: %s"
+            super(msg % [waiter_name, valid_waiters])
+          end
+        end
+      end
+    end
+  end
+end

gems/smithy-client/lib/smithy-client/waiters/poller.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module Waiters
+      class Poller
+        def initialize(options = {})
+          @operation_name = options[:operation_name]
+          @acceptors = options[:acceptors]
+        end
+
+        def call(client, params)
+          @input = params
+          begin
+            output = client.send(@operation_name, params)
+          rescue StandardError => e
+            error = e
+          end
+          output_or_error = output || error
+          status = evaluate_acceptors(output, error)
+          [output_or_error, status]
+        end
+
+        private
+
+        def evaluate_acceptors(output, error)
+          @acceptors.each do |acceptor|
+            return acceptor['state'] if acceptor_matches?(acceptor['matcher'], output, error)
+          end
+          if error
+            'error'
+          else
+            'retry'
+          end
+        end
+
+        def acceptor_matches?(matcher, output, error)
+          matcher_type = matcher.keys[0]
+          send("matches_#{matcher_type}?", matcher[matcher_type], output, error)
+        end
+
+        def matches_output?(path_matcher, output, error)
+          return false unless error.nil?
+
+          actual = JMESPath.search(path_matcher['path'], output)
+          is_equal?(actual, path_matcher['expected'], path_matcher['comparator'])
+        end
+
+        def matches_inputOutput?(path_matcher, output, error)
+          return false unless error.nil? && @input
+
+          data = {
+            input: @input,
+            output: output
+          }
+          actual = JMESPath.search(path_matcher['path'], data)
+          is_equal?(actual, path_matcher['expected'], path_matcher['comparator'])
+        end
+
+        def matches_success?(path_matcher, output, error)
+          if path_matcher == true
+            !output.nil?
+          else
+            !error.nil?
+          end
+        end
+
+        def matches_errorType?(path_matcher, output, error)
+          return false unless output.nil?
+
+          err = path_matcher.split('#').last.split('#').first
+          error.class.to_s.include?(err)
+        end
+
+        def is_equal?(actual, expected, comparator)
+          case comparator
+          when 'stringEquals'
+            return actual == expected
+          when 'booleanEquals'
+            return actual.to_s == expected
+          when 'allStringEquals'
+            return false if actual.nil? || actual.empty?
+
+            actual.all? { |value| value == expected }
+          when 'anyStringEquals'
+            return false if actual.nil? || actual.empty?
+
+            actual.any? { |value| value == expected }
+          end
+        end
+      end
+    end
+  end
+end

gems/smithy-client/lib/smithy-client/waiters/waiter.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module Waiters
+      class Waiter
+        def initialize(options = {})
+          unless options[:max_wait_time].is_a?(Integer)
+            raise ArgumentError, "expected `:max_wait_time` to be an integer, got: #{options[:max_wait_time]}"
+          end
+
+          @max_wait_time = options[:max_wait_time]
+          @remaining_time = @max_wait_time
+          @max_delay = max_delay(options[:max_delay])
+          @min_delay = min_delay(options[:min_delay])
+          @poller = options[:poller]
+        end
+
+        def wait(client, params)
+          poll(client, params)
+        end
+
+        private
+
+        def max_delay(delay)
+          if delay < 1
+            raise ArgumentError, '`:max_delay` must be greater than 0'
+          end
+          delay
+        end
+
+        def min_delay(delay)
+          if delay < 1 || delay > @max_delay
+            raise ArgumentError, '`:min_delay` must be greater than 0 and less than or equal to `:max_delay`'
+          end
+          delay
+        end
+
+        def poll(client, params)
+          attempts = 0
+          loop do
+            output_or_error, status = @poller.call(client, params)
+            attempts += 1
+
+            case status.to_sym
+            when :retry
+            when :success then return output_or_error
+            when :failure then raise Errors::FailureStateError.new(output_or_error)
+            when :error then raise Errors::UnexpectedError.new(output_or_error)
+            end
+
+            raise Errors::MaxWaitTimeExceededError.new(@max_wait_time) if @remaining_time == 0
+
+            delay = delay(attempts)
+            @remaining_time -= delay
+            sleep(delay)
+          end
+        end
+
+        def delay(attempts)
+          attempt_ceiling = (Math.log(@max_delay / @min_delay) / Math.log(2)) + 1
+          delay = attempts > attempt_ceiling ? @max_delay : @min_delay * 2 ** (attempts - 1)
+          delay = rand(@min_delay..delay)
+          delay = @remaining_time if @remaining_time - delay <= @min_delay
+          delay
+        end
+      end
+    end
+  end
+end