Add error classification

Author: SamRemis

packages/smithy-core/src/smithy_core/aio/client.py

@@ -12,7 +12,7 @@
 from ..auth import AuthParams
 from ..deserializers import DeserializeableShape, ShapeDeserializer
 from ..endpoints import EndpointResolverParams
-from ..exceptions import RetryError, SmithyError
+from ..exceptions import ClientTimeoutError, RetryError, SmithyError
 from ..interceptors import (
     InputContext,
     Interceptor,
@@ -448,24 +448,32 @@ async def _handle_attempt[I: SerializeableShape, O: DeserializeableShape](
 
             _LOGGER.debug("Sending request %s", request_context.transport_request)
 
-            if request_future is not None:
-                # If we have an input event stream (or duplex event stream) then we
-                # need to let the client return ASAP so that it can start sending
-                # events. So here we start the transport send in a background task
-                # then set the result of the request future. It's important to sequence
-                # it just like that so that the client gets a stream that's ready
-                # to send.
-                transport_task = asyncio.create_task(
-                    self.transport.send(request=request_context.transport_request)
-                )
-                request_future.set_result(request_context)
-                transport_response = await transport_task
-            else:
-                # If we don't have an input stream, there's no point in creating a
-                # task, so we just immediately await the coroutine.
-                transport_response = await self.transport.send(
-                    request=request_context.transport_request
-                )
+            try:
+                if request_future is not None:
+                    # If we have an input event stream (or duplex event stream) then we
+                    # need to let the client return ASAP so that it can start sending
+                    # events. So here we start the transport send in a background task
+                    # then set the result of the request future. It's important to sequence
+                    # it just like that so that the client gets a stream that's ready
+                    # to send.
+                    transport_task = asyncio.create_task(
+                        self.transport.send(request=request_context.transport_request)
+                    )
+                    request_future.set_result(request_context)
+                    transport_response = await transport_task
+                else:
+                    # If we don't have an input stream, there's no point in creating a
+                    # task, so we just immediately await the coroutine.
+                    transport_response = await self.transport.send(
+                        request=request_context.transport_request
+                    )
+            except Exception as e:
+                error_info = self.transport.get_error_info(e)
+                if error_info.is_timeout_error:
+                    raise ClientTimeoutError(
+                        message=f"Client timeout occurred: {e}", fault=error_info.fault
+                    ) from e
+                raise
 
             _LOGGER.debug("Received response: %s", transport_response)
 

packages/smithy-core/src/smithy_core/aio/interfaces/__init__.py

@@ -1,7 +1,8 @@
 #  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 #  SPDX-License-Identifier: Apache-2.0
 from collections.abc import AsyncIterable, Callable
-from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal, Protocol, runtime_checkable
 
 from ...documents import TypeRegistry
 from ...endpoints import EndpointResolverParams
@@ -10,6 +11,18 @@
 from ...interfaces import StreamingBlob as SyncStreamingBlob
 from .eventstream import EventPublisher, EventReceiver
 
+
+@dataclass(frozen=True)
+class ErrorInfo:
+    """Information about an error from a transport."""
+
+    is_timeout_error: bool
+    """Whether this error represents a timeout condition."""
+
+    fault: Literal["client", "server"] = "client"
+    """Whether the client or server is at fault."""
+
+
 if TYPE_CHECKING:
     from typing_extensions import TypeForm
 
@@ -86,7 +99,23 @@ async def resolve_endpoint(self, params: EndpointResolverParams[Any]) -> Endpoin
 
 
 class ClientTransport[I: Request, O: Response](Protocol):
-    """Protocol-agnostic representation of a client tranport (e.g. an HTTP client)."""
+    """Protocol-agnostic representation of a client transport (e.g. an HTTP client).
+
+    Transport implementations must define the get_error_info method to determine which
+    exceptions represent timeout conditions for that transport.
+    """
+
+    def get_error_info(self, exception: Exception, **kwargs) -> ErrorInfo:
+        """Get information about an exception.
+
+        Args:
+            exception: The exception to analyze
+            **kwargs: Additional context for analysis
+
+        Returns:
+            ErrorInfo with timeout and fault information.
+        """
+        ...
 
     async def send(self, request: I) -> O:
         """Send a request over the transport and receive the response."""

packages/smithy-core/src/smithy_core/exceptions.py

@@ -50,6 +50,9 @@ class CallError(SmithyError):
     is_throttling_error: bool = False
     """Whether the error is a throttling error."""
 
+    is_timeout_error: bool = False
+    """Whether the error represents a timeout condition."""
+
     def __post_init__(self):
         super().__init__(self.message)
 
@@ -61,6 +64,20 @@ class ModeledError(CallError):
     fault: Fault = "client"
 
 
+@dataclass(kw_only=True)
+class ClientTimeoutError(CallError):
+    """Exception raised when a client-side timeout occurs.
+
+    This error indicates that the client transport layer encountered a timeout while
+    attempting to communicate with the server. This typically occurs when network
+    requests take longer than the configured timeout period.
+    """
+
+    fault: Fault = "client"
+    is_timeout_error: bool = True
+    is_retry_safe: bool = True
+
+
 class SerializationError(SmithyError):
     """Base exception type for exceptions raised during serialization."""
 

packages/smithy-http/src/smithy_http/aio/aiohttp.py

@@ -20,7 +20,7 @@
 except ImportError:
     HAS_AIOHTTP = False  # type: ignore
 
-from smithy_core.aio.interfaces import StreamingBlob
+from smithy_core.aio.interfaces import ErrorInfo, StreamingBlob
 from smithy_core.aio.types import AsyncBytesReader
 from smithy_core.aio.utils import async_list
 from smithy_core.exceptions import MissingDependencyError
@@ -52,6 +52,14 @@ def __post_init__(self) -> None:
 class AIOHTTPClient(HTTPClient):
     """Implementation of :py:class:`.interfaces.HTTPClient` using aiohttp."""
 
+    def get_error_info(self, exception: Exception, **kwargs) -> ErrorInfo:
+        """Get information about aiohttp errors."""
+
+        if isinstance(exception, TimeoutError):
+            return ErrorInfo(is_timeout_error=True)
+
+        return ErrorInfo(is_timeout_error=False)
+
     def __init__(
         self,
         *,

packages/smithy-http/src/smithy_http/aio/crt.py

@@ -8,6 +8,8 @@
 from inspect import iscoroutinefunction
 from typing import TYPE_CHECKING, Any
 
+from awscrt.exceptions import AwsCrtError
+
 if TYPE_CHECKING:
     # pyright doesn't like optional imports. This is reasonable because if we use these
     # in type hints then they'd result in runtime errors.
@@ -33,6 +35,7 @@
 
 from smithy_core import interfaces as core_interfaces
 from smithy_core.aio import interfaces as core_aio_interfaces
+from smithy_core.aio.interfaces import ErrorInfo
 from smithy_core.aio.types import AsyncBytesReader
 from smithy_core.exceptions import MissingDependencyError
 
@@ -133,6 +136,22 @@ class AWSCRTHTTPClient(http_aio_interfaces.HTTPClient):
     _HTTP_PORT = 80
     _HTTPS_PORT = 443
 
+    def get_error_info(self, exception: Exception, **kwargs) -> ErrorInfo:
+        """Get information about CRT errors."""
+
+        timeout_indicators = (
+            "AWS_IO_SOCKET_TIMEOUT",
+            "AWS_IO_CHANNEL_ERROR_SOCKET_TIMEOUT",
+            "AWS_ERROR_HTTP_REQUEST_TIMEOUT",
+        )
+        if isinstance(exception, TimeoutError):
+            return ErrorInfo(is_timeout_error=True, fault="client")
+
+        if isinstance(exception, AwsCrtError) and exception.name in timeout_indicators:
+            return ErrorInfo(is_timeout_error=True, fault="client")
+
+        return ErrorInfo(is_timeout_error=False)
+
     def __init__(
         self,
         eventloop: _AWSCRTEventLoop | None = None,

packages/smithy-http/src/smithy_http/aio/protocols.py

@@ -215,7 +215,6 @@ async def _create_error(
             )
             return error_shape.deserialize(deserializer)
 
-        is_throttle = response.status == 429
         message = (
             f"Unknown error for operation {operation.schema.id} "
             f"- status: {response.status}"
@@ -224,11 +223,22 @@ async def _create_error(
             message += f" - id: {error_id}"
         if response.reason is not None:
             message += f" - reason: {response.status}"
+
+        if response.status == 408:
+            is_timeout = True
+            fault = "server"
+        else:
+            is_timeout = False
+            fault = "client" if response.status < 500 else "server"
+
+        is_throttle = response.status == 429
+
         return CallError(
             message=message,
-            fault="client" if response.status < 500 else "server",
+            fault=fault,
             is_throttling_error=is_throttle,
-            is_retry_safe=is_throttle or None,
+            is_timeout_error=is_timeout,
+            is_retry_safe=is_throttle or is_timeout or None,
         )
 
     def _matches_content_type(self, response: HTTPResponse) -> bool:

packages/smithy-http/tests/unit/aio/test_protocols.py

@@ -2,23 +2,24 @@
 #  SPDX-License-Identifier: Apache-2.0
 
 from typing import Any
+from unittest.mock import Mock
 
 import pytest
 from smithy_core import URI
 from smithy_core.documents import TypeRegistry
 from smithy_core.endpoints import Endpoint
-from smithy_core.interfaces import TypedProperties
 from smithy_core.interfaces import URI as URIInterface
 from smithy_core.schemas import APIOperation
 from smithy_core.shapes import ShapeID
+from smithy_core.types import TypedProperties
 from smithy_http import Fields
-from smithy_http.aio import HTTPRequest
+from smithy_http.aio import HTTPRequest, HTTPResponse
 from smithy_http.aio.interfaces import HTTPRequest as HTTPRequestInterface
 from smithy_http.aio.interfaces import HTTPResponse as HTTPResponseInterface
-from smithy_http.aio.protocols import HttpClientProtocol
+from smithy_http.aio.protocols import HttpBindingClientProtocol, HttpClientProtocol
 
 
-class TestProtocol(HttpClientProtocol):
+class MockProtocol(HttpClientProtocol):
     _id = ShapeID("ns.foo#bar")
 
     @property
@@ -125,7 +126,7 @@ def deserialize_response(
 def test_http_protocol_joins_uris(
     request_uri: URI, endpoint_uri: URI, expected: URI
 ) -> None:
-    protocol = TestProtocol()
+    protocol = MockProtocol()
     request = HTTPRequest(
         destination=request_uri,
         method="GET",
@@ -135,3 +136,28 @@ def test_http_protocol_joins_uris(
     updated_request = protocol.set_service_endpoint(request=request, endpoint=endpoint)
     actual = updated_request.destination
     assert actual == expected
+
+
+@pytest.mark.asyncio
+async def test_http_408_creates_timeout_error() -> None:
+    """Test that HTTP 408 creates a timeout error with server fault."""
+    protocol = Mock(spec=HttpBindingClientProtocol)
+    protocol.error_identifier = Mock()
+    protocol.error_identifier.identify.return_value = None
+
+    response = HTTPResponse(status=408, fields=Fields())
+
+    error = await HttpBindingClientProtocol._create_error(
+        protocol,
+        operation=Mock(),
+        request=HTTPRequest(
+            destination=URI(host="example.com"), method="POST", fields=Fields()
+        ),
+        response=response,
+        response_body=b"",
+        error_registry=TypeRegistry({}),
+        context=TypedProperties(),
+    )
+
+    assert error.is_timeout_error is True
+    assert error.fault == "server"

packages/smithy-http/tests/unit/aio/test_timeout_errors.py

@@ -0,0 +1,63 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+
+import pytest
+from smithy_core.aio.interfaces import ErrorInfo
+
+try:
+    from smithy_http.aio.aiohttp import AIOHTTPClient
+
+    HAS_AIOHTTP = True
+except ImportError:
+    HAS_AIOHTTP = False
+
+try:
+    from smithy_http.aio.crt import AWSCRTHTTPClient
+
+    HAS_CRT = True
+except ImportError:
+    HAS_CRT = False
+
+
+@pytest.mark.skipif(not HAS_AIOHTTP, reason="aiohttp not available")
+class TestAIOHTTPTimeoutErrorHandling:
+    """Test timeout error handling for AIOHTTPClient."""
+
+    @pytest.fixture
+    async def client(self):
+        return AIOHTTPClient()
+
+    @pytest.mark.asyncio
+    async def test_timeout_error_detection(self, client):
+        """Test timeout error detection for standard TimeoutError."""
+        timeout_err = TimeoutError("Connection timed out")
+        result = client.get_error_info(timeout_err)
+        assert result == ErrorInfo(is_timeout_error=True, fault="client")
+
+    @pytest.mark.asyncio
+    async def test_non_timeout_error_detection(self, client):
+        """Test non-timeout error detection."""
+        other_err = ValueError("Not a timeout")
+        result = client.get_error_info(other_err)
+        assert result == ErrorInfo(is_timeout_error=False, fault="client")
+
+
+@pytest.mark.skipif(not HAS_CRT, reason="AWS CRT not available")
+class TestAWSCRTTimeoutErrorHandling:
+    """Test timeout error handling for AWSCRTHTTPClient."""
+
+    @pytest.fixture
+    def client(self):
+        return AWSCRTHTTPClient()
+
+    def test_timeout_error_detection(self, client):
+        """Test timeout error detection for standard TimeoutError."""
+        timeout_err = TimeoutError("Connection timed out")
+        result = client.get_error_info(timeout_err)
+        assert result == ErrorInfo(is_timeout_error=True, fault="client")
+
+    def test_non_timeout_error_detection(self, client):
+        """Test non-timeout error detection."""
+        other_err = ValueError("Not a timeout")
+        result = client.get_error_info(other_err)
+        assert result == ErrorInfo(is_timeout_error=False, fault="client")