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,54 @@
+# 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
+          MSG = "stopped waiting, encountered a failure state"
+
+          def initialize(response)
+            @response = response
+            super(MSG)
+          end
+
+          attr_reader :response
+        end
+
+        class MaxWaitTimeExceededError < WaiterFailed
+          MSG = "stopped waiting after maximum wait time of %s seconds was exceeded"
+
+          def initialize(max_wait_time)
+            super(MSG % [max_wait_time])
+          end
+        end
+
+        class UnexpectedError < WaiterFailed
+          MSG = "stopped waiting due to an unexpected error: %s"
+
+          def initialize(error)
+            @error = error
+            super(MSG % [error.message])
+          end
+
+          attr_reader :error
+        end
+
+        # Raised when attempting to get a waiter by name and the waiter has not
+        # been defined.
+        class NoSuchWaiterError < ArgumentError
+          MSG = "no such waiter"
+
+          def initialize
+            super(MSG)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,117 @@
+# 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
+            resp = client.send(@operation_name, params)
+          rescue StandardError => e
+            error = e
+          end
+          resp_or_error = resp || error
+          status = evaluate_acceptors(resp, error)
+          [resp_or_error, status]
+        end
+
+        private
+
+        def evaluate_acceptors(resp, error)
+          @acceptors.each do |acceptor|
+            return acceptor['state'] if acceptor_matches?(acceptor['matcher'], resp, error)
+          end
+
+          # If none of the acceptors match and an error was encountered,
+          # transition to failure state. Otherwise, transition to retry state.
+          if error
+            'error'
+          else
+            'retry'
+          end
+        end
+
+        def acceptor_matches?(matcher, resp, error)
+          matcher_type = matcher.keys[0]
+          send("matches_#{matcher_type}?", matcher[matcher_type], resp, error)
+        end
+
+        def matches_output?(path_matcher, resp, error)
+          return false unless error.nil?
+
+          actual = JMESPath.search(underscore_jmespath(path_matcher['path']), resp)
+          is_equal?(actual, path_matcher['expected'], path_matcher['comparator'])
+        end
+
+        def matches_inputOutput?(path_matcher, resp, error)
+          return false unless error.nil? && @input
+
+          data = {
+            input: @input, ### Where do we get this?
+            output: resp
+          }
+          actual = JMESPath.search(underscore_jmespath(path_matcher['path']), data)
+          is_equal?(actual, path_matcher['expected'], path_matcher['comparator'])
+        end
+
+        def matches_success?(path_matcher, resp, error)
+          if path_matcher == true
+            !resp.nil?
+          else
+            !error.nil?
+          end
+        end
+
+        def matches_errorType?(path_matcher, resp, error)
+          return false unless resp.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.each do |value|
+              return false if value != expected
+            end
+            return true
+          when 'anyStringEquals'
+            return false if actual.nil? || actual.empty?
+
+            actual.each do |value|
+              return true if value == expected
+            end
+            return false
+          end
+        end
+
+        def underscore(string)
+          string.gsub(/::/, '/')
+                .gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
+                .gsub(/([a-z\d])([A-Z])/,'\1_\2')
+                .tr("-", "_")
+                .downcase
+        end
+
+        def underscore_jmespath(expression)
+          expression
+            .gsub(' or ', '||')
+            .gsub(/(?<![`'])\b\w+\b(?![`'])/) { |str| underscore(str) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# 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, 'Waiter must be initialized with `:max_wait_time`'
+          end
+
+          @max_wait_time = options[:max_wait_time]
+          @remaining_time = @max_wait_time
+          @min_delay = options[:min_delay]
+          @max_delay = options[:max_delay]
+          if @max_delay < 1
+            raise ArgumentError, '`:max_delay` must be greater than 0'
+          end
+          if @min_delay < 1 || @min_delay > @max_delay
+            raise ArgumentError, '`:min_delay` must be greater than 0 and less than or equal to `:max_delay`'
+          end
+
+          @poller = options[:poller]
+          @client = options[:client] # runtime approach
+        end
+
+        def wait(client, params)
+          poll(client, params)
+        end
+
+        # Used for runtime approach
+        def wait_custom(params)
+          poll(@client, params)
+        end
+
+        private
+
+        def poll(client, params)
+          attempts = 0
+          loop do
+            resp, status = @poller.call(client, params)
+            attempts += 1
+
+            case status.to_sym
+            when :retry
+            when :success then return resp
+            when :failure then raise Errors::FailureStateError.new(resp)
+            when :error then raise Errors::UnexpectedError.new(resp)
+            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

gems/smithy/lib/smithy/generators/client.rb

@@ -50,6 +50,7 @@ def source_files
           e.yield "lib/#{@gem_name}/endpoint_parameters.rb", Views::Client::EndpointParameters.new(@plan).render
           e.yield "lib/#{@gem_name}/endpoint_provider.rb", Views::Client::EndpointProvider.new(@plan).render
           e.yield "lib/#{@gem_name}/paginators.rb", Views::Client::Paginators.new(@plan).render
+          e.yield "lib/#{@gem_name}/waiters.rb", Views::Client::Waiters.new(@plan).render
           code_generated_plugins.each { |path, plugin| e.yield path, plugin.source }
           e.yield "lib/#{@gem_name}/types.rb", Views::Client::Types.new(@plan).render
           e.yield "lib/#{@gem_name}/schema.rb", Views::Client::Schema.new(@plan).render

gems/smithy/lib/smithy/templates/client/client.erb

@@ -36,6 +36,21 @@ module <%= module_name %>
     end
 
 <% end -%>
+<% if waiters? -%>
+    def wait_until(waiter_name, params = {}, options = {})
+      w = waiter(waiter_name, options)
+      w.wait(params)
+    end
+
+<% end -%>
+    # runtime approach
+    def wait_until_custom(waiter_name, params = {}, options = {})
+      operation_name, waiter_config = find_waiter(waiter_name)
+      poller = poller_custom(operation_name, waiter_config["acceptors"])
+      waiter = waiter_custom(waiter_config, options, poller)
+      waiter.wait_custom(params)
+    end
+
     private
 
     def build_input(operation_name, params)
@@ -51,6 +66,72 @@ module <%= module_name %>
       context[:gem_version] = '<%= gem_version %>'
       Smithy::Client::Input.new(handlers: handlers, context: context)
     end
+<% if waiters? %>
+    def waiter(waiter_name, options = {})
+      waiter_class = waiters[waiter_name]
+      if waiter_class
+        waiter_class.new(options.merge(client: self))
+      else
+        raise Smithy::Client::Waiters::Errors::NoSuchWaiterError.new
+      end
+    end
+
+    def waiters
+<% waiters.each do |line| -%>
+    <%= line %>
+<% end -%>
+    end
+<% end -%>
+
+    # runtime approach
+    def find_waiter(waiter_name)
+      operations = config.service.operations
+      operations.each do |operation_name, operation|
+        if (trait = waitable_trait(operation))
+          trait.each do |name, waiter|
+            if underscore(name) == waiter_name.to_s
+              return [operation_name, waiter]
+            end
+          end
+        end
+      end
+      raise Smithy::Client::Waiters::Errors::NoSuchWaiterError.new
+    end
+
+    # runtime approach
+    def waitable_trait(operation)
+      if operation.traits && !operation.traits['smithy.waiters#waitable'].nil?
+        operation.traits['smithy.waiters#waitable']
+      end
+    end
+
+    # runtime approach
+    def underscore(string)
+      string.gsub(/::/, '/')
+      .gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
+      .gsub(/([a-z\d])([A-Z])/,'\1_\2')
+      .tr("-", "_")
+      .downcase
+    end
+
+    # runtime approach
+    def poller_custom(operation_name, acceptors)
+      Smithy::Client::Waiters::Poller.new(
+        operation_name: operation_name.to_sym,
+        acceptors: acceptors
+      )
+    end
+
+    # runtime approach
+    def waiter_custom(waiter_config, options, poller)
+      Smithy::Client::Waiters::Waiter.new(
+        max_wait_time: options[:max_wait_time],
+        min_delay: options[:min_delay] || waiter_config[:min_delay] || 2,
+        max_delay: options[:max_delay] || waiter_config[:max_delay] || 120,
+        poller: poller,
+        client: self
+      )
+    end
 
     class << self
       # @api private

gems/smithy/lib/smithy/templates/client/waiters.erb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# This is generated code!
+
+require 'smithy-client/waiters'
+
+module <%= module_name %>
+  # @api private
+  module Waiters
+<% waiters.each do |waiter| -%>
+    # @api private
+    class <%= waiter.name %>
+      def initialize(options = {})
+        @client = options[:client]
+        @waiter = Smithy::Client::Waiters::Waiter.new(
+          max_wait_time: options[:max_wait_time],
+          min_delay: options[:min_delay] || <%= waiter.min_delay %>,
+          max_delay: options[:max_delay] || <%= waiter.max_delay %>,
+          poller: Smithy::Client::Waiters::Poller.new(
+            operation_name: :<%= waiter.operation_name %>,
+<%= waiter.acceptors %>
+          )
+        )
+      end
+
+      def wait(params = {})
+        @waiter.wait(@client, params)
+      end
+    end
+
+<% end -%>
+  end
+end

gems/smithy/lib/smithy/views/client.rb

@@ -44,3 +44,4 @@ module Client; end
 require_relative 'client/spec_helper'
 require_relative 'client/types'
 require_relative 'client/types_rbs'
+require_relative 'client/waiters'