Implement updated standard retry behavior

codegen/aws/core/src/main/java/software/amazon/smithy/python/aws/codegen/AwsDynamoDbRetryIntegration.java

@@ -0,0 +1,142 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package software.amazon.smithy.python.aws.codegen;
+
+import java.util.List;
+import java.util.Set;
+import software.amazon.smithy.aws.traits.ServiceTrait;
+import software.amazon.smithy.codegen.core.Symbol;
+import software.amazon.smithy.codegen.core.SymbolReference;
+import software.amazon.smithy.python.codegen.GenerationContext;
+import software.amazon.smithy.python.codegen.SmithyPythonDependency;
+import software.amazon.smithy.python.codegen.integrations.PythonIntegration;
+import software.amazon.smithy.python.codegen.integrations.RuntimeClientPlugin;
+
+/**
+ * Generates DynamoDB's retry defaults as a service-scoped client plugin on
+ * DynamoDB / DynamoDB Streams clients.
+ */
+public final class AwsDynamoDbRetryIntegration implements PythonIntegration {
+
+    private static final Set<String> DYNAMODB_SDK_IDS = Set.of("DynamoDB", "DynamoDB Streams");
+
+    public static final String DYNAMODB_RETRY_MODULE = """
+            _DYNAMODB_DEFAULT_MAX_ATTEMPTS = 4
+            _DYNAMODB_DEFAULT_BACKOFF_SCALE = 0.025
+            _DYNAMODB_DEFAULT_MAX_BACKOFF = 20
+
+
+            class _RetryConfig(Protocol):
+                retry_strategy: $1T | $2T | None
+
+
+            def dynamodb_retry_plugin(config: _RetryConfig) -> None:
+                \"\"\"Apply DynamoDB's standard-mode retry defaults for any option left unset.\"\"\"
+                retry_strategy = config.retry_strategy
+                if retry_strategy is not None and not isinstance(
+                    retry_strategy, $2T
+                ):
+                    return
+
+                if isinstance(retry_strategy, $2T):
+                    # Explicit options take precedence over separately resolved fields.
+                    retry_mode = retry_strategy.retry_mode
+                    max_attempts = retry_strategy.max_attempts
+                else:
+                    # Read independently resolved AsyncConfig fields when available. A legacy
+                    # Config has no scalar retry fields, so None represents an unset value.
+                    retry_mode = getattr(config, "retry_mode", None) or "standard"
+                    max_attempts = getattr(config, "max_attempts", None)
+                    source_of = getattr(config, "source_of", None)
+                    if (
+                        source_of is not None
+                        and source_of("max_attempts") == $4T.DEFAULT
+                    ):
+                        max_attempts = None
+
+                if retry_mode != "standard":
+                    return
+
+                config.retry_strategy = $3T(
+                    max_attempts=(
+                        max_attempts
+                        if max_attempts is not None
+                        else _DYNAMODB_DEFAULT_MAX_ATTEMPTS
+                    ),
+                    backoff_strategy=$5T(
+                        backoff_scale_value=_DYNAMODB_DEFAULT_BACKOFF_SCALE,
+                        max_backoff=_DYNAMODB_DEFAULT_MAX_BACKOFF,
+                        jitter_type=$6T.FULL,
+                    ),
+                )
+            """;
+
+    @Override
+    public List<RuntimeClientPlugin> getClientPlugins(GenerationContext context) {
+        final String pluginFile = "retries";
+        final String moduleName = context.settings().moduleName();
+
+        final SymbolReference dynamodbRetryPlugin = SymbolReference.builder()
+                .symbol(Symbol.builder()
+                        .namespace(String.format("%s.%s", moduleName, pluginFile), ".")
+                        .definitionFile(String.format("./src/%s/%s.py", moduleName, pluginFile))
+                        .name("dynamodb_retry_plugin")
+                        .build())
+                .build();
+        final Symbol retryStrategy = Symbol.builder()
+                .namespace("smithy_core.aio.interfaces.retries", ".")
+                .name("RetryStrategy")
+                .build();
+        final Symbol retryStrategyOptions = Symbol.builder()
+                .namespace("smithy_core.retries", ".")
+                .name("RetryStrategyOptions")
+                .build();
+        final Symbol standardRetryStrategy = Symbol.builder()
+                .namespace("smithy_core.aio.retries", ".")
+                .name("StandardRetryStrategy")
+                .build();
+        final Symbol configSource = Symbol.builder()
+                .namespace("smithy_aws_core.config", ".")
+                .name("ConfigSource")
+                .build();
+        final Symbol exponentialBackoffStrategy = Symbol.builder()
+                .namespace("smithy_core.retries", ".")
+                .name("ExponentialRetryBackoffStrategy")
+                .build();
+        final Symbol exponentialBackoffJitterType = Symbol.builder()
+                .namespace("smithy_core.retries", ".")
+                .name("ExponentialBackoffJitterType")
+                .build();
+
+        return List.of(
+                RuntimeClientPlugin.builder()
+                        .servicePredicate((model, service) -> service.getTrait(ServiceTrait.class)
+                                .map(trait -> DYNAMODB_SDK_IDS.contains(trait.getSdkId()))
+                                .orElse(false))
+                        .pythonPlugin(dynamodbRetryPlugin)
+                        .writeAdditionalFiles((c) -> {
+                            String filename = "src/%s/%s.py".formatted(moduleName, pluginFile);
+                            c.writerDelegator()
+                                    .useFileWriter(
+                                            filename,
+                                            moduleName + ".",
+                                            writer -> {
+                                                writer.addDependency(SmithyPythonDependency.SMITHY_CORE);
+                                                writer.addDependency(AwsPythonDependency.SMITHY_AWS_CORE);
+                                                writer.addStdlibImport("typing", "Protocol");
+                                                writer.write(
+                                                        DYNAMODB_RETRY_MODULE,
+                                                        retryStrategy,
+                                                        retryStrategyOptions,
+                                                        standardRetryStrategy,
+                                                        configSource,
+                                                        exponentialBackoffStrategy,
+                                                        exponentialBackoffJitterType);
+                                            });
+                            return List.of(filename);
+                        })
+                        .build());
+    }
+}

codegen/aws/core/src/main/resources/META-INF/services/software.amazon.smithy.python.codegen.integrations.PythonIntegration

@@ -9,3 +9,4 @@ software.amazon.smithy.python.aws.codegen.AwsProtocolsIntegration
 software.amazon.smithy.python.aws.codegen.AwsServiceIdIntegration
 software.amazon.smithy.python.aws.codegen.AwsUserAgentIntegration
 software.amazon.smithy.python.aws.codegen.AwsStandardRegionalEndpointsIntegration
+software.amazon.smithy.python.aws.codegen.AwsDynamoDbRetryIntegration

designs/exceptions.md

@@ -52,7 +52,8 @@ class ErrorRetryInfo(Protocol):
     retry_after: float | None = None
     """The amount of time that should pass before a retry.
 
-    Retry strategies MAY choose to wait longer.
+    Retry strategies MAY adjust this value, for example by clamping it to an
+    upper bound.
     """
 
     is_throttling_error: bool = False

designs/retries.md

@@ -89,7 +89,8 @@ class ErrorRetryInfo(Protocol):
     retry_after: float | None = None
     """The amount of time that should pass before a retry.
 
-    Retry strategies MAY choose to wait longer.
+    Retry strategies MAY adjust this value, for example by clamping it to an
+    upper bound.
     """
 
     is_throttling_error: bool = False
@@ -110,8 +111,9 @@ class HasFault(Protocol):
 
 `RetryStrategy` implementations MUST raise a `RetryError` if they receive an
 exception where `is_retry_safe` is `False` and SHOULD raise a `RetryError` if it
-is `None`. `RetryStrategy` implementations SHOULD use a delay that is at least
-as long as `retry_after` but MAY choose to wait longer.
+is `None`. `RetryStrategy` implementations SHOULD take `retry_after` into account
+when computing the delay, but MAY adjust it (for example, by clamping it to an
+upper bound).
 
 ### Backoff Strategy
 

packages/smithy-aws-core/.changes/next-release/smithy-aws-core-enhancement-881860b5bda049d1b000983dd2a3bd0e.json

@@ -0,0 +1,4 @@
+{
+  "type": "enhancement",
+  "description": "Added support for the `x-amz-retry-after` response header."
+}

packages/smithy-aws-core/src/smithy_aws_core/_private/query/errors.py

@@ -99,6 +99,7 @@ def create_aws_query_error(
     wrapper_elements: tuple[str, ...],
     status: int,
     context: TypedProperties,
+    retry_after: float | None = None,
 ) -> CallError:
     """Create a modeled or generic CallError from an awsQuery error response."""
     code = _parse_aws_query_error_code(body, wrapper_elements)
@@ -121,7 +122,10 @@ def create_aws_query_error(
             deserializer = XMLCodec().create_deserializer(
                 body, wrapper_elements=wrapper_elements
             )
-            return error_shape.deserialize(deserializer)
+            modeled_error = error_shape.deserialize(deserializer)
+            if retry_after is not None:
+                modeled_error.retry_after = retry_after
+            return modeled_error
 
     message = f"Unknown error for operation {operation.schema.id} - status: {status}"
     if code is not None:
@@ -137,4 +141,5 @@ def create_aws_query_error(
         is_throttling_error=is_throttle,
         is_timeout_error=is_timeout,
         is_retry_safe=is_throttle or is_timeout or None,
+        retry_after=retry_after,
     )

packages/smithy-aws-core/src/smithy_aws_core/aio/protocols.py

@@ -27,15 +27,18 @@
 from smithy_http import tuples_to_fields
 from smithy_http.aio import HTTPRequest as _HTTPRequest
 from smithy_http.aio.interfaces import HTTPErrorIdentifier, HTTPRequest, HTTPResponse
-from smithy_http.aio.protocols import HttpBindingClientProtocol, HttpClientProtocol
+from smithy_http.aio.protocols import (
+    HttpBindingClientProtocol,
+    HttpClientProtocol,
+)
 from smithy_http.deserializers import HTTPResponseDeserializer
 
 from .._private.query.errors import (
     create_aws_query_error,
 )
 from .._private.query.serializers import QueryShapeSerializer
 from ..traits import AwsQueryTrait, RestJson1Trait
-from ..utils import parse_document_discriminator, parse_error_code
+from ..utils import parse_document_discriminator, parse_error_code, parse_retry_after
 
 try:
     from smithy_json import JSONCodec, JSONDocument
@@ -166,6 +169,9 @@ def content_type(self) -> str:
     def error_identifier(self) -> HTTPErrorIdentifier:
         return self._error_identifier
 
+    def _retry_after(self, response: HTTPResponse) -> float | None:
+        return parse_retry_after(response)
+
     def _resolve_error_id(
         self,
         *,
@@ -364,6 +370,7 @@ async def _create_error(
             wrapper_elements=self._error_wrapper_elements(),
             status=response.status,
             context=context,
+            retry_after=parse_retry_after(response),
         )
 
     def _action_name(

packages/smithy-aws-core/src/smithy_aws_core/utils.py

@@ -1,7 +1,38 @@
 #  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 #  SPDX-License-Identifier: Apache-2.0
+import logging
+
 from smithy_core.documents import Document
 from smithy_core.shapes import ShapeID, ShapeType
+from smithy_http.aio.interfaces import HTTPResponse
+
+_LOGGER = logging.getLogger(__name__)
+
+_RETRY_AFTER_HEADER = "x-amz-retry-after"
+
+
+def parse_retry_after(response: HTTPResponse) -> float | None:
+    """Parse the ``x-amz-retry-after`` header into a backoff duration in seconds.
+
+    The header value is an integer number of milliseconds. Invalid or missing
+    values are ignored (return ``None``) so they fall back to exponential backoff.
+    """
+    if _RETRY_AFTER_HEADER not in response.fields:
+        return None
+    raw = response.fields[_RETRY_AFTER_HEADER].as_string()
+    try:
+        seconds = int(raw) / 1000.0
+        if seconds < 0:
+            raise ValueError("Negative retry-after value")
+        return seconds
+    except (ValueError, TypeError, OverflowError) as error:
+        _LOGGER.debug(
+            "Ignoring invalid %s header value: %r. Error: %s",
+            _RETRY_AFTER_HEADER,
+            raw,
+            error,
+        )
+        return None
 
 
 def parse_document_discriminator(

packages/smithy-aws-core/tests/unit/test_query.py

@@ -2,13 +2,18 @@
 #  SPDX-License-Identifier: Apache-2.0
 from dataclasses import dataclass
 from io import BytesIO
+from typing import Any, cast
+from unittest.mock import Mock
 
+from smithy_aws_core._private.query.errors import create_aws_query_error
 from smithy_aws_core._private.query.serializers import QueryShapeSerializer
+from smithy_core.documents import TypeRegistry
 from smithy_core.prelude import STRING
-from smithy_core.schemas import Schema
+from smithy_core.schemas import APIOperation, Schema
 from smithy_core.serializers import ShapeSerializer
 from smithy_core.shapes import ShapeID, ShapeType
 from smithy_core.traits import XMLFlattenedTrait, XMLNameTrait
+from smithy_core.types import TypedProperties
 
 
 def test_query_list_serialization() -> None:
@@ -280,3 +285,39 @@ def serialize_members(self, serializer: ShapeSerializer) -> None:
     Outer(inner=Inner("x")).serialize(serializer)
 
     assert params == [("inner.value", "x")]
+
+
+def _error_test_operation() -> APIOperation[Any, Any]:
+    operation = Mock(spec=APIOperation)
+    operation.schema = Schema(
+        id=ShapeID("com.example#TestOp"), shape_type=ShapeType.OPERATION
+    )
+    operation.error_schemas = []
+    return cast("APIOperation[Any, Any]", operation)
+
+
+def test_aws_query_error_sets_retry_after_on_generic_error() -> None:
+    error = create_aws_query_error(
+        body=b"",
+        operation=_error_test_operation(),
+        error_registry=TypeRegistry({}),
+        default_namespace="com.example",
+        wrapper_elements=("ErrorResponse", "Error"),
+        status=503,
+        context=TypedProperties(),
+        retry_after=1.5,
+    )
+    assert error.retry_after == 1.5
+
+
+def test_aws_query_error_retry_after_none_by_default() -> None:
+    error = create_aws_query_error(
+        body=b"",
+        operation=_error_test_operation(),
+        error_registry=TypeRegistry({}),
+        default_namespace="com.example",
+        wrapper_elements=("ErrorResponse", "Error"),
+        status=503,
+        context=TypedProperties(),
+    )
+    assert error.retry_after is None