smithy-http 0.0.1__tar.gz

smithy_http-0.0.1/.gitignore

@@ -0,0 +1,36 @@
+# Eclipse
+.classpath
+.project
+.settings/
+
+# Intellij
+.idea/
+*.iml
+*.iws
+
+# VS Code
+.vscode/
+
+# Mac
+.DS_Store
+
+# Maven
+target/
+**/dependency-reduced-pom.xml
+
+# Gradle
+**/.gradle
+build/
+*/out/
+**/*/out/
+
+# Python
+__pycache__
+*.swp
+.mypy_cache
+.coverage
+coverage.xml
+htmlcov
+*.egg-info
+dist
+.venv

smithy_http-0.0.1/CHANGES.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## Unreleased
+
+* <Add new items here>
+
+## v0.0.1
+
+### Feature
+* Added support for aiohttp and AWSCRT http clients.
+* Added basic HTTP primitives and interfaces for Smithy clients.

smithy_http-0.0.1/NOTICE

@@ -0,0 +1 @@
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

smithy_http-0.0.1/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: smithy-http
+Version: 0.0.1
+Summary: HTTP components for Smithy tooling.
+License-File: NOTICE
+Requires-Python: >=3.12
+Requires-Dist: smithy-core
+Provides-Extra: aiohttp
+Requires-Dist: aiohttp<4.0,>=3.11.12; extra == 'aiohttp'
+Requires-Dist: yarl; extra == 'aiohttp'
+Provides-Extra: awscrt
+Requires-Dist: awscrt>=0.23.10; extra == 'awscrt'

smithy_http-0.0.1/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "smithy-http"
+version = "0.0.1"
+description = "HTTP components for Smithy tooling."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "smithy-core",
+]
+
+[project.optional-dependencies]
+awscrt = [
+    "awscrt>=0.23.10",
+]
+aiohttp = [
+    "aiohttp>=3.11.12, <4.0",
+    "yarl"
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+exclude = [
+  "tests",
+]
+
+[tool.ruff]
+src = ["src"]

smithy_http-0.0.1/src/smithy_http/__init__.py

@@ -0,0 +1,233 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+import importlib.metadata
+from collections import Counter, OrderedDict
+from collections.abc import Iterable, Iterator
+
+from . import interfaces
+from .interfaces import FieldPosition
+
+__version__: str = importlib.metadata.version("smithy-http")
+
+
+class Field(interfaces.Field):
+    """A name-value pair representing a single field in an HTTP Request or Response.
+
+    The kind will dictate metadata placement within an HTTP message.
+
+    All field names are case insensitive and case-variance must be treated as
+    equivalent. Names may be normalized but should be preserved for accuracy during
+    transmission.
+    """
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        values: Iterable[str] | None = None,
+        kind: FieldPosition = FieldPosition.HEADER,
+    ):
+        self.name = name
+        self.values: list[str] = list(values) if values is not None else []
+        self.kind = kind
+
+    def add(self, value: str) -> None:
+        """Append a value to a field."""
+        self.values.append(value)
+
+    def set(self, values: list[str]) -> None:
+        """Overwrite existing field values."""
+        self.values = values
+
+    def remove(self, value: str) -> None:
+        """Remove all matching entries from list."""
+        try:
+            while True:
+                self.values.remove(value)
+        except ValueError:
+            return
+
+    def as_string(self, delimiter: str = ",") -> str:
+        """Get delimited string of all values. A comma is used by default.
+
+        If the ``Field`` has zero values, the empty string is returned. If the ``Field``
+        has exactly one value, the value is returned unmodified.
+
+        For ``Field``s with more than one value, the values are joined by a comma and a
+        space. For such multi-valued ``Field``s, any values that already contain
+        commas or double quotes will be surrounded by double quotes. Within any values
+        that get quoted, pre-existing double quotes and backslashes are escaped with a
+        backslash.
+        """
+        value_count = len(self.values)
+        if value_count == 0:
+            return ""
+        if value_count == 1:
+            return self.values[0]
+        return ", ".join(quote_and_escape_field_value(val) for val in self.values)
+
+    def as_tuples(self) -> list[tuple[str, str]]:
+        """Get list of ``name``, ``value`` tuples where each tuple represents one
+        value."""
+        return [(self.name, val) for val in self.values]
+
+    def __eq__(self, other: object) -> bool:
+        """Name, values, and kind must match.
+
+        Values order must match.
+        """
+        if not isinstance(other, Field):
+            return False
+        return (
+            self.name == other.name
+            and self.kind is other.kind
+            and self.values == other.values
+        )
+
+    def __repr__(self) -> str:
+        return f"Field(name={self.name!r}, value={self.values!r}, kind={self.kind!r})"
+
+
+class Fields(interfaces.Fields):
+    def __init__(
+        self,
+        initial: Iterable[interfaces.Field] | None = None,
+        *,
+        encoding: str = "utf-8",
+    ):
+        """Collection of header and trailer entries mapped by name.
+
+        :param initial: Initial list of ``Field`` objects. ``Field``s can also be added
+        and later removed.
+        :param encoding: The string encoding to be used when converting the ``Field``
+        name and value from ``str`` to ``bytes`` for transmission.
+        """
+        init_fields = list(initial) if initial is not None else []
+        init_field_names = [self._normalize_field_name(fld.name) for fld in init_fields]
+        fname_counter = Counter(init_field_names)
+        repeated_names_exist = (
+            len(init_fields) > 0 and fname_counter.most_common(1)[0][1] > 1
+        )
+        if repeated_names_exist:
+            non_unique_names = [name for name, num in fname_counter.items() if num > 1]
+            raise ValueError(
+                "Field names of the initial list of fields must be unique. The "
+                "following normalized field names appear more than once: "
+                f"{', '.join(non_unique_names)}."
+            )
+        init_tuples = zip(init_field_names, init_fields)
+        self.entries: dict[str, interfaces.Field] = OrderedDict(init_tuples)
+        self.encoding: str = encoding
+
+    def set_field(self, field: interfaces.Field) -> None:
+        """Alias for __setitem__ to utilize the field.name for the entry key."""
+        self.__setitem__(field.name, field)
+
+    def __setitem__(self, name: str, field: interfaces.Field) -> None:
+        """Set or override entry for a Field name."""
+        normalized_name = self._normalize_field_name(name)
+        normalized_field_name = self._normalize_field_name(field.name)
+        if normalized_name != normalized_field_name:
+            raise ValueError(
+                f"Supplied key {name} does not match Field.name "
+                f"provided: {normalized_field_name}"
+            )
+        self.entries[normalized_name] = field
+
+    def get(
+        self, key: str, default: interfaces.Field | None = None
+    ) -> interfaces.Field | None:
+        return self[key] if key in self else default
+
+    def __getitem__(self, name: str) -> interfaces.Field:
+        """Retrieve Field entry."""
+        normalized_name = self._normalize_field_name(name)
+        return self.entries[normalized_name]
+
+    def __delitem__(self, name: str) -> None:
+        """Delete entry from collection."""
+        normalized_name = self._normalize_field_name(name)
+        del self.entries[normalized_name]
+
+    def get_by_type(self, kind: FieldPosition) -> list[interfaces.Field]:
+        """Helper function for retrieving specific types of fields.
+
+        Used to grab all headers or all trailers.
+        """
+        return [entry for entry in self.entries.values() if entry.kind is kind]
+
+    def extend(self, other: interfaces.Fields) -> None:
+        """Merges ``entries`` of ``other`` into the current ``entries``.
+
+        For every `Field` in the ``entries`` of ``other``: If the normalized name
+        already exists in the current ``entries``, the values from ``other`` are
+        appended. Otherwise, the ``Field`` is added to the list of ``entries``.
+        """
+        for other_field in other:
+            try:
+                cur_field = self.__getitem__(other_field.name)
+                for other_value in other_field.values:
+                    cur_field.add(other_value)
+            except KeyError:
+                self.__setitem__(other_field.name, other_field)
+
+    def _normalize_field_name(self, name: str) -> str:
+        """Normalize field names.
+
+        For use as key in ``entries``.
+        """
+        return name.lower()
+
+    def __eq__(self, other: object) -> bool:
+        """Encoding must match.
+
+        Entries must match in values and order.
+        """
+        if not isinstance(other, Fields):
+            return False
+        return self.encoding == other.encoding and self.entries == other.entries
+
+    def __iter__(self) -> Iterator[interfaces.Field]:
+        yield from self.entries.values()
+
+    def __len__(self) -> int:
+        return len(self.entries)
+
+    def __repr__(self) -> str:
+        return f"Fields({self.entries})"
+
+    def __contains__(self, key: str) -> bool:
+        return self._normalize_field_name(key) in self.entries
+
+
+def quote_and_escape_field_value(value: str) -> str:
+    """Escapes and quotes a single :class:`Field` value if necessary.
+
+    See :func:`Field.as_string` for quoting and escaping logic.
+    """
+    chars_to_quote = (",", '"')
+    if any(char in chars_to_quote for char in value):
+        escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+        return f'"{escaped}"'
+    else:
+        return value
+
+
+def tuples_to_fields(
+    tuples: Iterable[tuple[str, str]], *, kind: FieldPosition | None = None
+) -> Fields:
+    """Convert ``name``, ``value`` tuples to ``Fields`` object. Each tuple represents
+    one Field value.
+
+    :param kind: The Field kind to define for all tuples.
+    """
+    fields = Fields()
+    for name, value in tuples:
+        try:
+            fields[name].add(value)
+        except KeyError:
+            fields[name] = Field(
+                name=name, values=[value], kind=kind or FieldPosition.HEADER
+            )
+
+    return fields

smithy_http-0.0.1/src/smithy_http/aio/__init__.py

@@ -0,0 +1,53 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+from dataclasses import dataclass, field
+
+from smithy_core import interfaces as core_interfaces
+from smithy_core.aio import interfaces as core_aio_interfaces
+from smithy_core.aio.utils import read_streaming_blob, read_streaming_blob_async
+
+from .. import interfaces as http_interfaces
+from . import interfaces as http_aio_interfaces
+
+
+@dataclass(kw_only=True)
+class HTTPRequest(http_aio_interfaces.HTTPRequest):
+    """HTTP primitives for an Exchange to construct a version agnostic HTTP message."""
+
+    destination: core_interfaces.URI
+    body: core_aio_interfaces.StreamingBlob = field(repr=False, default=b"")
+    method: str
+    fields: http_interfaces.Fields
+
+
+# HTTPResponse implements http_interfaces.HTTPResponse but cannot be explicitly
+# annotated to reflect this because doing so causes Python to raise an AttributeError.
+# See https://github.com/python/typing/discussions/903#discussioncomment-4866851 for
+# details.
+@dataclass(kw_only=True)
+class HTTPResponse:
+    """Basic implementation of :py:class:`.interfaces.HTTPResponse`.
+
+    Implementations of :py:class:`.interfaces.HTTPClient` may return instances of this
+    class or of custom response implementations.
+    """
+
+    body: core_aio_interfaces.StreamingBlob = field(repr=False, default=b"")
+    """The response payload as iterable of chunks of bytes."""
+
+    status: int
+    """The 3 digit response status code (1xx, 2xx, 3xx, 4xx, 5xx)."""
+
+    fields: http_interfaces.Fields
+    """HTTP header and trailer fields."""
+
+    reason: str | None = None
+    """Optional string provided by the server explaining the status."""
+
+    async def consume_body_async(self) -> bytes:
+        """Iterate over response body and return as bytes."""
+        return await read_streaming_blob_async(body=self.body)
+
+    def consume_body(self) -> bytes:
+        """Iterate over request body and return as bytes."""
+        return read_streaming_blob(body=self.body)

smithy_http-0.0.1/src/smithy_http/aio/aiohttp.py

@@ -0,0 +1,140 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+from copy import copy, deepcopy
+from itertools import chain
+from typing import TYPE_CHECKING, Any
+from urllib.parse import parse_qs
+
+import yarl
+
+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.
+    # TODO: add integ tests that import these without the dependendency installed
+    import aiohttp
+
+try:
+    import aiohttp
+
+    HAS_AIOHTTP = True
+except ImportError:
+    HAS_AIOHTTP = False  # type: ignore
+
+from smithy_core.aio.interfaces import StreamingBlob
+from smithy_core.aio.types import AsyncBytesReader
+from smithy_core.aio.utils import async_list
+from smithy_core.exceptions import MissingDependencyException
+from smithy_core.interfaces import URI
+
+from .. import Field, Fields
+from ..interfaces import (
+    FieldPosition,
+    HTTPClientConfiguration,
+    HTTPRequestConfiguration,
+)
+from . import HTTPResponse
+from .interfaces import HTTPClient, HTTPRequest
+from .interfaces import HTTPResponse as HTTPResponseInterface
+
+
+def _assert_aiohttp() -> None:
+    if not HAS_AIOHTTP:
+        raise MissingDependencyException(
+            "Attempted to use aiohttp component, but aiohttp is not installed."
+        )
+
+
+class AIOHTTPClientConfig(HTTPClientConfiguration):
+    def __post_init__(self) -> None:
+        _assert_aiohttp()
+
+
+class AIOHTTPClient(HTTPClient):
+    """Implementation of :py:class:`.interfaces.HTTPClient` using aiohttp."""
+
+    def __init__(
+        self,
+        *,
+        client_config: AIOHTTPClientConfig | None = None,
+        _session: "aiohttp.ClientSession | None" = None,
+    ) -> None:
+        """
+        :param client_config: Configuration that applies to all requests made with this
+        client.
+        """
+        _assert_aiohttp()
+        self._config = client_config or AIOHTTPClientConfig()
+        self._session = _session or aiohttp.ClientSession()
+
+    async def send(
+        self,
+        request: HTTPRequest,
+        *,
+        request_config: HTTPRequestConfiguration | None = None,
+    ) -> HTTPResponseInterface:
+        """Send HTTP request using aiohttp client.
+
+        :param request: The request including destination URI, fields, payload.
+        :param request_config: Configuration specific to this request.
+        """
+        request_config = request_config or HTTPRequestConfiguration()
+
+        headers_list = list(
+            chain.from_iterable(fld.as_tuples() for fld in request.fields)
+        )
+
+        body: StreamingBlob = request.body
+        if not isinstance(body, AsyncBytesReader):
+            body = AsyncBytesReader(body)
+
+        # The typing on `params` is incorrect, it'll happily accept a mapping whose
+        # values are lists (or tuples) and produce expected values.
+        # See: https://github.com/aio-libs/aiohttp/issues/8563
+        async with self._session.request(
+            method=request.method,
+            url=self._serialize_uri_without_query(request.destination),
+            params=parse_qs(request.destination.query),  # type: ignore
+            headers=headers_list,
+            data=body,
+        ) as resp:
+            return await self._marshal_response(resp)
+
+    def _serialize_uri_without_query(self, uri: URI) -> yarl.URL:
+        """Serialize all parts of the URI up to and including the path."""
+        return yarl.URL.build(
+            scheme=uri.scheme or "",
+            host=uri.host,
+            port=uri.port,
+            user=uri.username,
+            password=uri.password,
+            path=uri.path or "",
+            encoded=True,
+        )
+
+    async def _marshal_response(
+        self, aiohttp_resp: "aiohttp.ClientResponse"
+    ) -> HTTPResponseInterface:
+        """Convert a ``aiohttp.ClientResponse`` to a ``smithy_http.aio.HTTPResponse``"""
+        headers = Fields()
+        for header_name, header_val in aiohttp_resp.headers.items():
+            try:
+                headers[header_name].add(header_val)
+            except KeyError:
+                headers[header_name] = Field(
+                    name=header_name,
+                    values=[header_val],
+                    kind=FieldPosition.HEADER,
+                )
+
+        return HTTPResponse(
+            status=aiohttp_resp.status,
+            fields=headers,
+            body=async_list([await aiohttp_resp.read()]),
+            reason=aiohttp_resp.reason,
+        )
+
+    def __deepcopy__(self, memo: Any) -> "AIOHTTPClient":
+        return AIOHTTPClient(
+            client_config=deepcopy(self._config),
+            _session=copy(self._session),
+        )

smithy_http-0.0.1/src/smithy_http/aio/auth/__init__.py

@@ -0,0 +1,2 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0

smithy_http-0.0.1/src/smithy_http/aio/auth/apikey.py

@@ -0,0 +1,117 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+from dataclasses import dataclass
+from enum import Enum
+from typing import NotRequired, Protocol, TypedDict
+
+from smithy_core import URI
+from smithy_core.aio.interfaces.identity import IdentityResolver
+from smithy_core.exceptions import SmithyIdentityException
+from smithy_core.interfaces.identity import IdentityProperties
+
+from ... import Field
+from ..identity.apikey import ApiKeyIdentity
+from ..interfaces import HTTPRequest
+from ..interfaces.auth import HTTPAuthScheme, HTTPSigner
+
+
+class ApiKeyLocation(Enum):
+    """The locations that the api key could be placed in the signed request."""
+
+    HEADER = "header"
+    QUERY = "query"
+
+
+class ApiKeySigningProperties(TypedDict):
+    """The properties needed to sign a request with api key auth.
+
+    seealso:: The `Smithy API Key auth trait docs <https://smithy.io/2.0/spec/authentication-traits.html#smithy-api-httpapikeyauth-trait>`_
+    , which have more details on these properties, including examples.
+    """
+
+    name: str
+    """The name of the HTTP header or query string parameter containing the key."""
+
+    scheme: NotRequired[str]
+    """The :rfc:`9110#section-11.4` scheme to prefix a header value with."""
+
+    location: ApiKeyLocation
+    """Where the key is serialized."""
+
+
+class ApiKeyConfig(Protocol):
+    api_key_identity_resolver: (
+        IdentityResolver[ApiKeyIdentity, IdentityProperties] | None
+    )
+
+
+@dataclass(init=False)
+class ApiKeyAuthScheme(
+    HTTPAuthScheme[
+        ApiKeyIdentity, ApiKeyConfig, IdentityProperties, ApiKeySigningProperties
+    ]
+):
+    """An auth scheme containing necessary data and tools for api key auth."""
+
+    scheme_id: str
+    signer: HTTPSigner[ApiKeyIdentity, ApiKeySigningProperties]
+
+    def __init__(
+        self,
+        *,
+        signer: HTTPSigner[ApiKeyIdentity, ApiKeySigningProperties] | None = None,
+    ) -> None:
+        """Constructor.
+
+        :param identity_resolver: The identity resolver to extract the api key identity.
+        :param signer: The signer used to sign the request.
+        """
+        self.scheme_id = "smithy.api#httpApiKeyAuth"
+        self.signer = signer or ApiKeySigner()
+
+    def identity_resolver(
+        self, *, config: ApiKeyConfig
+    ) -> IdentityResolver[ApiKeyIdentity, IdentityProperties]:
+        if not config.api_key_identity_resolver:
+            raise SmithyIdentityException(
+                "Attempted to use API key auth, but api_key_identity_resolver was not "
+                "set on the config."
+            )
+        return config.api_key_identity_resolver
+
+
+class ApiKeySigner(HTTPSigner[ApiKeyIdentity, ApiKeySigningProperties]):
+    """A signer that signs http requests with an api key."""
+
+    async def sign(
+        self,
+        *,
+        http_request: HTTPRequest,
+        identity: ApiKeyIdentity,
+        signing_properties: ApiKeySigningProperties,
+    ) -> HTTPRequest:
+        match signing_properties["location"]:
+            case ApiKeyLocation.QUERY:
+                query = http_request.destination.query or ""
+                if query:
+                    query += "&"
+                query += f"{signing_properties['name']}={identity.api_key}"
+                http_request.destination = URI(
+                    scheme=http_request.destination.scheme,
+                    username=http_request.destination.username,
+                    password=http_request.destination.password,
+                    host=http_request.destination.host,
+                    port=http_request.destination.port,
+                    path=http_request.destination.password,
+                    query=query,
+                    fragment=http_request.destination.fragment,
+                )
+            case ApiKeyLocation.HEADER:
+                value = identity.api_key
+                if (scheme := signing_properties.get("scheme", None)) is not None:
+                    value = f"{scheme} {value}"
+                http_request.fields.set_field(
+                    Field(name=signing_properties["name"], values=[value])
+                )
+
+        return http_request