Decouple endpoint resolvers from http

Author: JordonPhillips

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

@@ -4,3 +4,10 @@
 import importlib.metadata
 
 __version__: str = importlib.metadata.version("smithy-aws-core")
+
+
+from smithy_core.types import PropertyKey
+
+
+REGION = PropertyKey(key="region", value_type=str)
+"""An AWS region."""

packages/smithy-aws-core/src/smithy_aws_core/endpoints/standard_regional.py

@@ -1,70 +1,29 @@
 #  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 #  SPDX-License-Identifier: Apache-2.0
-from dataclasses import dataclass
-from typing import Protocol, Self
-from urllib.parse import urlparse
+from typing import Any
 
-import smithy_core
 from smithy_core import URI
-from smithy_http.aio.interfaces import (
-    EndpointResolver,
-    EndpointParameters,
-)
-from smithy_http.endpoints import Endpoint
-from smithy_http.exceptions import EndpointResolutionError
+from smithy_core.aio.interfaces import EndpointResolver
+from smithy_core.endpoints import Endpoint, EndpointResolverParams, resolve_static_uri
+from smithy_core.exceptions import EndpointResolutionError
 
+from .. import REGION
 
-class _RegionUriConfig(Protocol):
-    endpoint_uri: str | smithy_core.interfaces.URI | None
-    region: str | None
 
-
-@dataclass(kw_only=True)
-class RegionalEndpointParameters(EndpointParameters[_RegionUriConfig]):
-    """Endpoint parameters for services with standard regional endpoints."""
-
-    sdk_endpoint: str | smithy_core.interfaces.URI | None
-    region: str | None
-
-    @classmethod
-    def build(cls, config: _RegionUriConfig) -> Self:
-        return cls(sdk_endpoint=config.endpoint_uri, region=config.region)
-
-
-class StandardRegionalEndpointsResolver(EndpointResolver[RegionalEndpointParameters]):
+class StandardRegionalEndpointsResolver(EndpointResolver):
     """Resolves endpoints for services with standard regional endpoints."""
 
     def __init__(self, endpoint_prefix: str = "bedrock-runtime"):
         self._endpoint_prefix = endpoint_prefix
 
-    async def resolve_endpoint(self, params: RegionalEndpointParameters) -> Endpoint:
-        if params.sdk_endpoint is not None:
-            # If it's not a string, it's already a parsed URI so just pass it along.
-            if not isinstance(params.sdk_endpoint, str):
-                return Endpoint(uri=params.sdk_endpoint)
-
-            parsed = urlparse(params.sdk_endpoint)
-
-            # This will end up getting wrapped in the client.
-            if parsed.hostname is None:
-                raise EndpointResolutionError(
-                    f"Unable to parse hostname from provided URI: {params.sdk_endpoint}"
-                )
-
-            return Endpoint(
-                uri=URI(
-                    host=parsed.hostname,
-                    path=parsed.path,
-                    scheme=parsed.scheme,
-                    query=parsed.query,
-                    port=parsed.port,
-                )
-            )
+    async def resolve_endpoint(self, params: EndpointResolverParams[Any]) -> Endpoint:
+        if (static_uri := resolve_static_uri(params)) is not None:
+            return Endpoint(uri=static_uri)
 
-        if params.region is not None:
+        if (region := params.context.get(REGION)) is not None:
             # TODO: use dns suffix determined from partition metadata
             dns_suffix = "amazonaws.com"
-            hostname = f"{self._endpoint_prefix}.{params.region}.{dns_suffix}"
+            hostname = f"{self._endpoint_prefix}.{region}.{dns_suffix}"
 
             return Endpoint(uri=URI(host=hostname))
 

packages/smithy-aws-core/tests/unit/endpoints/test_standard_regional.py

@@ -1,21 +1,25 @@
 #  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 #  SPDX-License-Identifier: Apache-2.0
-from smithy_aws_core.endpoints.standard_regional import (
-    StandardRegionalEndpointsResolver,
-    RegionalEndpointParameters,
-)
-
-from smithy_core import URI
+from unittest.mock import Mock
 
 import pytest
 
-from smithy_http.exceptions import EndpointResolutionError
+from smithy_core import URI
+from smithy_core.endpoints import STATIC_URI, EndpointResolverParams
+from smithy_core.types import TypedProperties
+from smithy_core.exceptions import EndpointResolutionError
+
+from smithy_aws_core import REGION
+from smithy_aws_core.endpoints.standard_regional import (
+    StandardRegionalEndpointsResolver,
+)
 
 
 async def test_resolve_endpoint_with_valid_sdk_endpoint_string():
     resolver = StandardRegionalEndpointsResolver(endpoint_prefix="service")
-    params = RegionalEndpointParameters(
-        sdk_endpoint="https://example.com/path?query=123", region=None
+    params = Mock(spec=EndpointResolverParams)
+    params.context = TypedProperties(
+        {STATIC_URI.key: "https://example.com/path?query=123"}
     )
 
     endpoint = await resolver.resolve_endpoint(params)
@@ -31,7 +35,8 @@ async def test_resolve_endpoint_with_sdk_endpoint_uri():
     parsed_uri = URI(
         host="example.com", path="/path", scheme="https", query="query=123", port=443
     )
-    params = RegionalEndpointParameters(sdk_endpoint=parsed_uri, region=None)
+    params = Mock(spec=EndpointResolverParams)
+    params.context = TypedProperties({STATIC_URI.key: parsed_uri})
 
     endpoint = await resolver.resolve_endpoint(params)
 
@@ -40,15 +45,17 @@ async def test_resolve_endpoint_with_sdk_endpoint_uri():
 
 async def test_resolve_endpoint_with_invalid_sdk_endpoint():
     resolver = StandardRegionalEndpointsResolver(endpoint_prefix="service")
-    params = RegionalEndpointParameters(sdk_endpoint="invalid-uri", region=None)
+    params = Mock(spec=EndpointResolverParams)
+    params.context = TypedProperties({STATIC_URI.key: "invalid_uri"})
 
     with pytest.raises(EndpointResolutionError):
         await resolver.resolve_endpoint(params)
 
 
 async def test_resolve_endpoint_with_region():
     resolver = StandardRegionalEndpointsResolver(endpoint_prefix="service")
-    params = RegionalEndpointParameters(sdk_endpoint=None, region="us-west-2")
+    params = Mock(spec=EndpointResolverParams)
+    params.context = TypedProperties({REGION.key: "us-west-2"})
 
     endpoint = await resolver.resolve_endpoint(params)
 
@@ -57,16 +64,18 @@ async def test_resolve_endpoint_with_region():
 
 async def test_resolve_endpoint_with_no_sdk_endpoint_or_region():
     resolver = StandardRegionalEndpointsResolver(endpoint_prefix="service")
-    params = RegionalEndpointParameters(sdk_endpoint=None, region=None)
+    params = Mock(spec=EndpointResolverParams)
+    params.context = TypedProperties()
 
     with pytest.raises(EndpointResolutionError):
         await resolver.resolve_endpoint(params)
 
 
 async def test_resolve_endpoint_with_sdk_endpoint_and_region():
     resolver = StandardRegionalEndpointsResolver(endpoint_prefix="service")
-    params = RegionalEndpointParameters(
-        sdk_endpoint="https://example.com", region="us-west-2"
+    params = Mock(spec=EndpointResolverParams)
+    params.context = TypedProperties(
+        {STATIC_URI.key: "https://example.com", REGION.key: "us-west-2"}
     )
 
     endpoint = await resolver.resolve_endpoint(params)

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

@@ -0,0 +1,21 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+from typing import Any
+
+from .interfaces import EndpointResolver
+from ..endpoints import EndpointResolverParams, Endpoint, resolve_static_uri
+from ..exceptions import EndpointResolutionError
+from ..interfaces import Endpoint as _Endpoint
+
+
+class StaticEndpointResolver(EndpointResolver):
+    """A basic endpoint resolver that forwards a static URI."""
+
+    async def resolve_endpoint(self, params: EndpointResolverParams[Any]) -> _Endpoint:
+        static_uri = resolve_static_uri(params)
+        if static_uri is None:
+            raise EndpointResolutionError(
+                "Unable to resolve endpoint: endpoint_uri is required"
+            )
+
+        return Endpoint(uri=static_uri)

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

@@ -1,12 +1,13 @@
 #  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 #  SPDX-License-Identifier: Apache-2.0
 from collections.abc import AsyncIterable
-from typing import Protocol, runtime_checkable, TYPE_CHECKING, Callable
+from typing import Protocol, runtime_checkable, TYPE_CHECKING, Callable, Any
 
 from ...exceptions import UnsupportedStreamException
 from ...interfaces import URI, Endpoint, TypedProperties
 from ...interfaces import StreamingBlob as SyncStreamingBlob
 from ...documents import TypeRegistry
+from ...endpoints import EndpointResolverParams
 
 from .eventstream import EventPublisher, EventReceiver
 
@@ -72,6 +73,17 @@ def consume_body(self) -> bytes:
         ...
 
 
+class EndpointResolver(Protocol):
+    """Resolves an operation's endpoint based given parameters."""
+
+    async def resolve_endpoint(self, params: EndpointResolverParams[Any]) -> Endpoint:
+        """Resolve an endpoint for the given operation.
+
+        :param params: The parameters available to resolve the endpoint.
+        """
+        ...
+
+
 class ClientTransport[I: Request, O: Response](Protocol):
     """Protocol-agnostic representation of a client tranport (e.g. an HTTP client)."""
 

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

@@ -0,0 +1,89 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+from typing import Any
+from dataclasses import dataclass, field
+from urllib.parse import urlparse
+
+from . import URI
+from .serializers import SerializeableShape
+from .schemas import APIOperation
+from .interfaces import TypedProperties as _TypedProperties
+from .interfaces import Endpoint as _Endpoint
+from .interfaces import URI as _URI
+from .types import TypedProperties, PropertyKey
+from .exceptions import EndpointResolutionError
+
+
+STATIC_URI: PropertyKey[str | _URI] = PropertyKey(
+    key="endpoint_uri",
+    # Python currently has problems expressing parametric types that can be
+    # unions, literals, or other special types in addition to a class. So
+    # we have to ignore the type below. PEP 747 should resolve the issue.
+    # TODO: update this when PEP 747 lands
+    value_type=str | _URI,  # type: ignore
+)
+"""The property key for a statically defined URI."""
+
+
+@dataclass(kw_only=True)
+class Endpoint(_Endpoint):
+    """A resolved endpoint."""
+
+    uri: _URI
+    """The endpoint URI."""
+
+    properties: _TypedProperties = field(default_factory=TypedProperties)
+    """Properties required to interact with the endpoint.
+
+    For example, in some AWS use cases this might contain HTTP headers to add to each
+    request.
+    """
+
+
+@dataclass(kw_only=True)
+class EndpointResolverParams[I: SerializeableShape]:
+    """Parameters passed into an Endpoint Resolver's resolve_endpoint method."""
+
+    operation: APIOperation[I, Any]
+    """The operation to resolve an endpoint for."""
+
+    input: I
+    """The input to the operation."""
+
+    context: _TypedProperties
+    """The context of the operation invocation."""
+
+
+def resolve_static_uri(
+    properties: _TypedProperties | EndpointResolverParams[Any],
+) -> _URI | None:
+    """Attempt to resolve a static URI from the endpoint resolver params.
+
+    :param properties: A TypedProperties bag or EndpointResolverParams to search.
+    """
+    properties = (
+        properties.context
+        if isinstance(properties, EndpointResolverParams)
+        else properties
+    )
+    static_uri = properties.get(STATIC_URI)
+    if static_uri is None:
+        return None
+
+    # If it's not a string, it's already a parsed URI so just pass it along.
+    if not isinstance(static_uri, str):
+        return static_uri
+
+    parsed = urlparse(static_uri)
+    if parsed.hostname is None:
+        raise EndpointResolutionError(
+            f"Unable to parse hostname from provided URI: {static_uri}"
+        )
+
+    return URI(
+        host=parsed.hostname,
+        path=parsed.path,
+        scheme=parsed.scheme,
+        query=parsed.query,
+        port=parsed.port,
+    )

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

@@ -33,3 +33,7 @@ class AsyncBodyException(SmithyException):
 class UnsupportedStreamException(SmithyException):
     """Indicates that a serializer or deserializer's stream method was called, but data
     streams are not supported."""
+
+
+class EndpointResolutionError(SmithyException):
+    """Exception type for all exceptions raised by endpoint resolution."""

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

@@ -95,15 +95,13 @@ def is_streaming_blob(obj: Any) -> TypeGuard[StreamingBlob]:
     return isinstance(obj, bytes | bytearray) or is_bytes_reader(obj)
 
 
-# TODO: update HTTP package and existing endpoint implementations to use this.
 class Endpoint(Protocol):
     """A resolved endpoint."""
 
     uri: URI
     """The endpoint URI."""
 
-    # TODO: replace this with a typed context bag
-    properties: dict[str, Any]
+    properties: "TypedProperties"
     """Properties required to interact with the endpoint.
 
     For example, in some AWS use cases this might contain HTTP headers to add to each
@@ -138,6 +136,7 @@ class PropertyKey[T](Protocol):
     key: str
     """The string key used to access the value."""
 
+    # TODO: update this when PEP 747 lands to allow for unions and literals
     value_type: type[T]
     """The type of the associated value in the properties bag."""