Waiters

Waiters are classes that provide an abstraction for polling operations until desired states are reached. Waiters have a 1:1 mapping to each waiter definition on the waitable trait across all Smithy operation shapes.

@waitable(
    HighScoreExists: {
        documentation: "Waits until a high score has been created",
        acceptors: [
            {
                state: "retry",
                matcher: {
                    errorType: "NotFoundError"
                }
            },
            {
                state: "success",
                matcher: {
                    success: true
                }
            }
        ]
    }
)
operation GetHighScore {
    input: GetHighScoreInput,
    output: GetHighScoreOutput,
    errors: [NotFoundError]
}

Usage

Waiter classes must take an instance of the Client, the :max_wait_time for the waiter before it gives up, and optionally the :min_delay and :max_delay between polling attempts. The waiter's wait method takes both the params and the options for the operation that the waiter is modeled against. If a success acceptor condition is matched, the waiter returns true. Otherwise, if an error condition is matched, the waiter is either retried or fails. Each polling attempt will wait using some backoff with jitter.

client = HighScoreService::Client.new(endpoint: 'http://127.0.0.1:3000')
# => #<HighScoreService::Client ... >

# Some async create function, returning new ID to be created
client.create_high_score_async(...)
# => #<Hearth::Output @data=... >

waiter = HighScoreService::Waiters::HighScoreExists.new(client, max_wait_time: 10)
# => #<HighScoreService::Waiters::HighScoreExists ... >

# Waits up to 10 seconds
waiter.wait(id: '1')
# => true

Return values and errors

If an acceptor condition is matched, the waiter returns true. Otherwise, the waiter will raise an error that inherits from Hearth::Waiters::WaiterFailed. Possible errors include:

• Hearth::Waiters::FailureStateError - Raised when the waiter reached an expected, modeled, failure state.
• Hearth::Waiters::MaxWaitTimeExceededError - Raised when the waiter has reached the maximum waiting time.
• Hearth::Waiters::UnexpectedError - Raised when the waiter received an unexpected error.

Modeling waiters

The Smithy waitable trait documentation goes into detail about how to model waiters, how polling retries are performed, and how acceptors are matched.