BREAKING: Retry configuration

[ianbotsf]

An upcoming release of the AWS SDK for Kotlin changes the configuration API for retries. This change simplifies retry configuration and enables new capabilities to copy subsets of retry config when using the withConfig method but affects existing code which customizes the retry configuration on service clients.

Note: If you do not set custom retry strategy configuration then this change does not affect you.

Release date

This feature will ship with the v0.28.0-beta release planned for 6/29/2023.

What's changing

Previously, retry strategies (e.g., StandardRetryStrategy) were constructed by passing an options class (e.g., StandardRetryStrategyOptions) containing some—but not all—of the relevant configuration. Additional configuration such as delay parameters were passed as separate parameters. Additionally, the configuration and nested objects were not copyable. Thus when setting a new retry configuration via withClient, a completely new strategy had to be constructed from scratch.

These options classes and separate configuration are being replaced with config classes more in line with other buildable objects within the SDK (e.g., HTTP configuration). Additionally, new DSL methods are being added to the relevant containing builders to facilitate more concise construction.

How to migrate

Previously, retry strategies were customized like this:

val customStrategy = StandardRetryStrategy(
    StandardRetryStrategyOptions(maxAttempts = 10),
    delayProvider = ExponentialBackoffWithJitter(
        ExponentialBackoffWithJitterOptions.Default.copy(
            initialDelay = 50.milliseconds,
            maxBackoff = 30.seconds,
        )
    )
)

val ddb = DynamoDbClient.fromEnvironment {
    retryStrategy = customStrategy
}

After this change, retry strategies will be customizable via DSL:

val ddb = DynamoDbClient.fromEnvironment {
    retryStrategy {
        maxAttempts = 10
        delayProvider {
            initialDelay = 50.milliseconds
            maxBackoff = 30.seconds
        }
    }
}

Retry strategies may be further customized for specific invocations via withConfig:

ddb.withConfig {
    retryStrategy {
        maxAttempts = 20
    }
}.use { ddbWithMoreMaxAttempts ->
    ...
}

If desired, retry strategies may still be constructed outside of client builders and stored in variables (facilitating reuse across multiple clients):

val customStrategy = StandardRetryStrategy {
    maxAttempts = 10
    delayProvider {
        initialDelay = 50.milliseconds
        maxBackoff = 30.seconds
    }
}

Additional resources

If you have any questions concerning this change, please feel free to engage with us in this discussion. If you encounter a bug with these changes, please file an issue.