Waiters (#292)

Waiters

---------

Co-authored-by: Matt Muller <mamuller@amazon.com>

Author: richardwang1124

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

@@ -28,6 +28,8 @@
 require_relative 'smithy-client/retry'
 require_relative 'smithy-client/service_error'
 require_relative 'smithy-client/util'
+require_relative 'smithy-client/waiters/poller'
+require_relative 'smithy-client/waiters/waiter'
 require_relative 'smithy-client/input'
 require_relative 'smithy-client/output'
 require_relative 'smithy-client/base'

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

@@ -79,6 +79,13 @@ def context_for(operation_name, params)
         )
       end
 
+      def waiter(waiter_name, options = {})
+        waiter_class = waiters[waiter_name]
+        raise Waiters::NoSuchWaiterError.new(waiter_name, waiters.keys) unless waiter_class
+
+        waiter_class.new(options.merge(client: self))
+      end
+
       class << self
         def new(options = {})
           plugins = build_plugins

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module Waiters
+      # Abstract poller class which polls a single API operation and inspects
+      # the output and/or error for states matching one of its acceptors.
+      class Poller
+        def initialize(options = {})
+          @operation_name = options[:operation_name]
+          @acceptors = options[:acceptors]
+        end
+
+        def call(client, params)
+          @input = params
+          # TODO: make build_input public and update this line
+          input = client.send(:build_input, @operation_name, params)
+          input.handlers.remove(Plugins::RaiseResponseErrors::Handler)
+          output = input.send_request
+          status = evaluate_acceptors(output)
+          [output, status.to_sym]
+        end
+
+        private
+
+        def evaluate_acceptors(output)
+          @acceptors.each do |acceptor|
+            return acceptor['state'] if acceptor_matches?(acceptor['matcher'], output)
+          end
+          output.error.nil? ? 'retry' : 'error'
+        end
+
+        def acceptor_matches?(matcher, output)
+          matcher_type = matcher.keys.first
+          send("matches_#{matcher_type}?", matcher[matcher_type], output)
+        end
+
+        def matches_output?(path_matcher, output)
+          return false if output.data.nil?
+
+          actual = JMESPath.search(path_matcher['path'], output.data)
+          equal?(actual, path_matcher['expected'], path_matcher['comparator'])
+        end
+
+        # rubocop:disable Naming/MethodName
+        def matches_inputOutput?(path_matcher, output)
+          return false unless !output.data.nil? && @input
+
+          data = {
+            input: @input,
+            output: output.data
+          }
+          actual = JMESPath.search(path_matcher['path'], data)
+          equal?(actual, path_matcher['expected'], path_matcher['comparator'])
+        end
+
+        def matches_success?(path_matcher, output)
+          path_matcher == true ? !output.data.nil? : !output.error.nil?
+        end
+
+        def matches_errorType?(path_matcher, output)
+          return false if output.error.nil?
+
+          output.error.class.to_s.end_with?("Errors::#{path_matcher}")
+        end
+
+        def equal?(actual, expected, comparator)
+          send("#{comparator}?", actual, expected)
+        end
+
+        def stringEquals?(actual, expected)
+          actual == expected
+        end
+
+        def booleanEquals?(actual, expected)
+          actual.to_s == expected
+        end
+
+        def allStringEquals?(actual, expected)
+          return false if actual.nil? || actual.empty?
+
+          actual.all? { |value| value == expected }
+        end
+
+        def anyStringEquals?(actual, expected)
+          return false if actual.nil? || actual.empty?
+
+          actual.any? { |value| value == expected }
+        end
+        # rubocop:enable Naming/MethodName
+      end
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Client
+    module Waiters
+      # Raised when a waiter detects a condition where the waiter can never
+      # succeed.
+      class WaiterFailed < StandardError; end
+
+      # Raised when a waiter enters a failure state.
+      class FailureStateError < WaiterFailed
+        def initialize(error)
+          msg = "stopped waiting, encountered a failure state: #{error}"
+          super(msg)
+        end
+      end
+
+      # Raised when the total wait time of a waiter exceeds the maximum
+      # wait time.
+      class MaxWaitTimeExceededError < WaiterFailed
+        def initialize(max_wait_time)
+          msg = "stopped waiting after maximum wait time of #{max_wait_time} seconds was exceeded"
+          super(msg)
+        end
+      end
+
+      # Raised when a waiter encounters an unexpected error.
+      class UnexpectedError < WaiterFailed
+        def initialize(error)
+          msg = "stopped waiting due to an unexpected error: #{error}"
+          super(msg)
+        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: #{waiter_name}; valid waiter names are: #{valid_waiters}"
+          super(msg)
+        end
+      end
+
+      # Abstract waiter class which waits for a resource to reach a desired
+      # state.
+      class Waiter
+        def initialize(options = {})
+          @max_wait_time = 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_wait_time(time)
+          unless time.is_a?(Integer)
+            raise ArgumentError, "expected `:max_wait_time` to be an Integer, got: #{time.class}"
+          end
+
+          time
+        end
+
+        def max_delay(delay)
+          raise ArgumentError, '`:max_delay` must be greater than 0' if delay < 1
+
+          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, status = @poller.call(client, params)
+            attempts += 1
+
+            case status
+            when :success then return
+            when :failure then raise FailureStateError, output.error
+            when :error then raise UnexpectedError, output.error
+            when :retry
+              raise MaxWaitTimeExceededError, @max_wait_time if @remaining_time.zero?
+
+              delay = delay(attempts)
+              @remaining_time -= delay
+              sleep(delay)
+            end
+          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