smithy-http 0.0.1__py3-none-any.whl

smithy_http/aio/interfaces/auth.py

@@ -0,0 +1,107 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+# http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+from dataclasses import dataclass
+from typing import Any, Protocol, TypedDict, TypeVar
+
+from smithy_core.aio.interfaces.identity import IdentityResolver
+from smithy_core.interfaces.identity import Identity, IdentityProperties
+
+from . import HTTPRequest
+
+
+class SigningProperties(TypedDict):
+    """Additional properties loaded to modify the signing process."""
+
+
+SigningPropertiesType = TypeVar("SigningPropertiesType", bound=SigningProperties)
+SigningPropertiesType_contra = TypeVar(
+    "SigningPropertiesType_contra", bound=SigningProperties, contravariant=True
+)
+
+
+class HTTPSigner[I: Identity, SP: SigningProperties](Protocol):
+    """An interface for generating a signed HTTP request."""
+
+    async def sign(
+        self,
+        *,
+        http_request: HTTPRequest,
+        identity: I,
+        signing_properties: SP,
+    ) -> HTTPRequest:
+        """Generate a new signed HTTPRequest based on the one provided.
+
+        :param http_request: The HTTP request to sign.
+        :param identity: The signing identity.
+        :param signing_properties: Additional properties loaded to modify the signing
+            process.
+        """
+        ...
+
+
+class HTTPAuthScheme[I: Identity, C, IP: IdentityProperties, SP: SigningProperties](
+    Protocol
+):
+    """Represents a way a service will authenticate the user's identity."""
+
+    # A unique identifier for the authentication scheme.
+    scheme_id: str
+
+    # An API that can be used to sign HTTP requests.
+    signer: HTTPSigner[I, SP]
+
+    def identity_resolver(self, *, config: C) -> IdentityResolver[I, IP]:
+        """An API that can be queried to resolve identity."""
+        ...
+
+
+@dataclass(kw_only=True)
+class HTTPAuthOption:
+    """Auth scheme used for signing and identity resolution."""
+
+    # The ID of the scheme to use. This string matches the one returned by
+    # HttpAuthScheme.scheme_id
+    scheme_id: str
+
+    # Parameters to pass to IdentityResolver.get_identity.
+    identity_properties: dict[str, Any]
+
+    # Parameters to pass to HttpSigner.sign.
+    signer_properties: dict[str, Any]
+
+
+@dataclass(kw_only=True)
+class AuthSchemeParameters:
+    """The input to the auth scheme resolver.
+
+    A code-generated interface for passing in the data required for determining the
+    authentication scheme. By default, this only includes the operation name.
+    """
+
+    # The service operation being invoked by the client.
+    operation: str
+
+
+class AuthSchemeResolver(Protocol):
+    """Determines which authentication scheme to use for a given service."""
+
+    def resolve_auth_scheme(
+        self, *, auth_parameters: AuthSchemeParameters
+    ) -> list[HTTPAuthOption]:
+        """Resolve an ordered list of applicable auth schemes.
+
+        :param auth_parameters: The parameters required for determining which
+            authentication schemes to potentially use.
+        """
+        ...

smithy_http/aio/protocols.py

@@ -0,0 +1,118 @@
+import os
+from inspect import iscoroutinefunction
+from io import BytesIO
+
+from smithy_core.aio.interfaces import ClientProtocol
+from smithy_core.codecs import Codec
+from smithy_core.deserializers import DeserializeableShape
+from smithy_core.documents import TypeRegistry
+from smithy_core.exceptions import ExpectationNotMetException
+from smithy_core.interfaces import Endpoint, TypedProperties, URI
+from smithy_core.schemas import APIOperation
+from smithy_core.serializers import SerializeableShape
+from smithy_core.traits import EndpointTrait, HTTPTrait
+
+from smithy_http.aio.interfaces import HTTPRequest, HTTPResponse
+from smithy_http.deserializers import HTTPResponseDeserializer
+from smithy_http.serializers import HTTPRequestSerializer
+
+
+class HttpClientProtocol(ClientProtocol[HTTPRequest, HTTPResponse]):
+    """An HTTP-based protocol."""
+
+    def set_service_endpoint(
+        self,
+        *,
+        request: HTTPRequest,
+        endpoint: Endpoint,
+    ) -> HTTPRequest:
+        uri = endpoint.uri
+        uri_builder = request.destination
+
+        if uri.scheme:
+            uri_builder.scheme = uri.scheme
+        if uri.host:
+            uri_builder.host = uri.host
+        if uri.port and uri.port > -1:
+            uri_builder.port = uri.port
+        if uri.path:
+            uri_builder.path = os.path.join(uri.path, uri_builder.path or "")
+        # TODO: merge headers from the endpoint properties bag
+        return request
+
+
+class HttpBindingClientProtocol(HttpClientProtocol):
+    """An HTTP-based protocol that uses HTTP binding traits."""
+
+    @property
+    def payload_codec(self) -> Codec:
+        """The codec used for the serde of input and output payloads."""
+        raise NotImplementedError()
+
+    @property
+    def content_type(self) -> str:
+        """The media type of the http payload."""
+        raise NotImplementedError()
+
+    def serialize_request[
+        OperationInput: "SerializeableShape",
+        OperationOutput: "DeserializeableShape",
+    ](
+        self,
+        *,
+        operation: APIOperation[OperationInput, OperationOutput],
+        input: OperationInput,
+        endpoint: URI,
+        context: TypedProperties,
+    ) -> HTTPRequest:
+        # TODO(optimization): request binding cache like done in SJ
+        serializer = HTTPRequestSerializer(
+            payload_codec=self.payload_codec,
+            http_trait=operation.schema.expect_trait(HTTPTrait),
+            endpoint_trait=operation.schema.get_trait(EndpointTrait),
+        )
+
+        input.serialize(serializer=serializer)
+        request = serializer.result
+
+        if request is None:
+            raise ExpectationNotMetException(
+                "Expected request to be serialized, but was None"
+            )
+
+        return request
+
+    async def deserialize_response[
+        OperationInput: "SerializeableShape",
+        OperationOutput: "DeserializeableShape",
+    ](
+        self,
+        *,
+        operation: APIOperation[OperationInput, OperationOutput],
+        request: HTTPRequest,
+        response: HTTPResponse,
+        error_registry: TypeRegistry,
+        context: TypedProperties,
+    ) -> OperationOutput:
+        if not (200 <= response.status <= 299):
+            # TODO: implement error serde from type registry
+            raise NotImplementedError
+
+        body = response.body
+
+        # if body is not streaming and is async, we have to buffer it
+        if not operation.output_stream_member:
+            if (
+                read := getattr(body, "read", None)
+            ) is not None and iscoroutinefunction(read):
+                body = BytesIO(await read())
+
+        # TODO(optimization): response binding cache like done in SJ
+        deserializer = HTTPResponseDeserializer(
+            payload_codec=self.payload_codec,
+            http_trait=operation.schema.expect_trait(HTTPTrait),
+            response=response,
+            body=body,  # type: ignore
+        )
+
+        return operation.output.deserialize(deserializer)

smithy_http/aio/restjson.py

@@ -0,0 +1,60 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+import json
+
+from smithy_core.documents import DocumentValue
+from smithy_core.utils import expect_type
+
+from ..restjson import (
+    _REST_JSON_CODE_HEADER,  # pyright: ignore[reportPrivateUsage]
+    _REST_JSON_CODE_KEYS,  # pyright: ignore[reportPrivateUsage]
+    _REST_JSON_MESSAGE_KEYS,  # pyright: ignore[reportPrivateUsage]
+    RestJsonErrorInfo,
+)
+from .interfaces import HTTPResponse
+
+
+async def parse_rest_json_error_info(
+    http_response: HTTPResponse, check_body: bool = True
+) -> RestJsonErrorInfo:
+    """Parses generic RestJson error info from an HTTP response.
+
+    :param http_response: The HTTP response to parse.
+    :param check_body: Whether to check the body for the code / message.
+    :returns: The parsed error information.
+    """
+    code: str | None = None
+    message: str | None = None
+    json_body: dict[str, DocumentValue] | None = None
+
+    for field in http_response.fields:
+        if field.name.lower() == _REST_JSON_CODE_HEADER:
+            code = field.values[0]
+            break
+
+    if check_body:
+        if body := await http_response.consume_body_async():
+            try:
+                json_body = json.loads(body)
+            except json.JSONDecodeError:
+                # In some cases the body might end up being HTML depending on the
+                # configuration of the server. In those cases we can simply ignore
+                # the body because we can't find the information we need there.
+                pass
+
+        if json_body:
+            for key, value in json_body.items():
+                key_lower = key.lower()
+                if not code and key_lower in _REST_JSON_CODE_KEYS:
+                    code = expect_type(str, value)
+                if not message and key_lower in _REST_JSON_MESSAGE_KEYS:
+                    message = expect_type(str, value)
+
+    # Normalize the error code. Some services may try to send a fully-qualified shape
+    # ID or a URI, but we don't want to include those.
+    if code:
+        if "#" in code:
+            code = code.split("#")[1]
+        code = code.split(":")[0]
+
+    return RestJsonErrorInfo(code or "Unknown", message or "Unknown", json_body)

smithy_http/deserializers.py

@@ -0,0 +1,259 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+import datetime
+from collections.abc import Callable
+from decimal import Decimal
+from typing import TYPE_CHECKING
+
+from smithy_core.codecs import Codec
+from smithy_core.deserializers import ShapeDeserializer, SpecificShapeDeserializer
+from smithy_core.exceptions import UnsupportedStreamException
+from smithy_core.interfaces import is_bytes_reader, is_streaming_blob
+from smithy_core.schemas import Schema
+from smithy_core.shapes import ShapeType
+from smithy_core.traits import (
+    HTTPHeaderTrait,
+    HTTPPayloadTrait,
+    HTTPPrefixHeadersTrait,
+    HTTPResponseCodeTrait,
+    HTTPTrait,
+    TimestampFormatTrait,
+)
+from smithy_core.types import TimestampFormat
+from smithy_core.utils import ensure_utc, strict_parse_bool, strict_parse_float
+
+from .aio.interfaces import HTTPResponse
+from .interfaces import Field, Fields
+
+if TYPE_CHECKING:
+    from smithy_core.aio.interfaces import StreamingBlob as AsyncStreamingBlob
+    from smithy_core.interfaces import StreamingBlob as SyncStreamingBlob
+
+
+__all__ = ["HTTPResponseDeserializer"]
+
+
+class HTTPResponseDeserializer(SpecificShapeDeserializer):
+    """Binds :py:class:`HTTPResponse` properties to a DeserializableShape."""
+
+    # Note: caller will have to read the body if it's async and not streaming
+    def __init__(
+        self,
+        payload_codec: Codec,
+        http_trait: HTTPTrait,
+        response: HTTPResponse,
+        body: "SyncStreamingBlob | None" = None,
+    ) -> None:
+        """Initialize an HTTPResponseDeserializer.
+
+        :param payload_codec: The Codec to use to deserialize the payload, if present.
+        :param http_trait: The HTTP trait of the operation being handled.
+        :param response: The HTTP response to read from.
+        :param body: The HTTP response body in a synchronously readable form. This is
+            necessary for async response bodies when there is no streaming member.
+        """
+        self._payload_codec = payload_codec
+        self._response = response
+        self._http_trait = http_trait
+        self._body = body
+
+    def read_struct(
+        self, schema: Schema, consumer: Callable[[Schema, ShapeDeserializer], None]
+    ) -> None:
+        has_body = False
+        payload_member: Schema | None = None
+
+        for member in schema.members.values():
+            if (trait := member.get_trait(HTTPHeaderTrait)) is not None:
+                header = self._response.fields.entries.get(trait.key.lower())
+                if header is not None:
+                    if member.shape_type is ShapeType.LIST:
+                        consumer(member, HTTPHeaderListDeserializer(header))
+                    else:
+                        consumer(member, HTTPHeaderDeserializer(header.as_string()))
+            elif (trait := member.get_trait(HTTPPrefixHeadersTrait)) is not None:
+                consumer(
+                    member,
+                    HTTPHeaderMapDeserializer(self._response.fields, trait.prefix),
+                )
+            elif HTTPPayloadTrait in member:
+                has_body = True
+                payload_member = member
+            elif HTTPResponseCodeTrait in member:
+                consumer(member, HTTPResponseCodeDeserializer(self._response.status))
+            else:
+                has_body = True
+
+        if has_body:
+            deserializer = self._create_payload_deserializer(payload_member)
+            if payload_member is not None:
+                consumer(payload_member, deserializer)
+            else:
+                deserializer.read_struct(schema, consumer)
+
+    def _create_payload_deserializer(
+        self, payload_member: Schema | None
+    ) -> ShapeDeserializer:
+        body = self._body if self._body is not None else self._response.body
+        if payload_member is not None and payload_member.shape_type in (
+            ShapeType.BLOB,
+            ShapeType.STRING,
+        ):
+            return RawPayloadDeserializer(body)
+
+        if not is_streaming_blob(body):
+            raise UnsupportedStreamException(
+                "Unable to read async stream. This stream must be buffered prior "
+                "to creating the deserializer."
+            )
+
+        if isinstance(body, bytearray):
+            body = bytes(body)
+
+        return self._payload_codec.create_deserializer(body)
+
+
+class HTTPHeaderDeserializer(SpecificShapeDeserializer):
+    """Binds HTTP header values to a deserializable shape.
+
+    For headers with list values, see :py:class:`HTTPHeaderListDeserializer`.
+    """
+
+    def __init__(self, value: str) -> None:
+        """Initialize an HTTPHeaderDeserializer.
+
+        :param value: The string value of the header.
+        """
+        self._value = value
+
+    def read_boolean(self, schema: Schema) -> bool:
+        return strict_parse_bool(self._value)
+
+    def read_byte(self, schema: Schema) -> int:
+        return self.read_integer(schema)
+
+    def read_short(self, schema: Schema) -> int:
+        return self.read_integer(schema)
+
+    def read_integer(self, schema: Schema) -> int:
+        return int(self._value)
+
+    def read_long(self, schema: Schema) -> int:
+        return self.read_integer(schema)
+
+    def read_big_integer(self, schema: Schema) -> int:
+        return self.read_integer(schema)
+
+    def read_float(self, schema: Schema) -> float:
+        return strict_parse_float(self._value)
+
+    def read_double(self, schema: Schema) -> float:
+        return self.read_float(schema)
+
+    def read_big_decimal(self, schema: Schema) -> Decimal:
+        return Decimal(self._value).canonical()
+
+    def read_string(self, schema: Schema) -> str:
+        return self._value
+
+    def read_timestamp(self, schema: Schema) -> datetime.datetime:
+        format = TimestampFormat.HTTP_DATE
+        if (trait := schema.get_trait(TimestampFormatTrait)) is not None:
+            format = trait.format
+        return ensure_utc(format.deserialize(self._value))
+
+
+class HTTPHeaderListDeserializer(SpecificShapeDeserializer):
+    """Binds HTTP header lists to a deserializable shape."""
+
+    def __init__(self, field: Field) -> None:
+        """Initialize an HTTPHeaderListDeserializer.
+
+        :param field: The field to deserialize.
+        """
+        self._field = field
+
+    def read_list(
+        self, schema: Schema, consumer: Callable[["ShapeDeserializer"], None]
+    ) -> None:
+        for value in self._field.values:
+            consumer(HTTPHeaderDeserializer(value))
+
+
+class HTTPHeaderMapDeserializer(SpecificShapeDeserializer):
+    """Binds HTTP header maps to a deserializable shape."""
+
+    def __init__(self, fields: Fields, prefix: str = "") -> None:
+        """Initialize an HTTPHeaderMapDeserializer.
+
+        :param fields: The collection of headers to search for map values.
+        :param prefix: An optional prefix to limit which headers are pulled in to the
+            map. By default, all headers are pulled in, including headers that are bound
+            to other properties on the shape.
+        """
+        self._prefix = prefix.lower()
+        self._fields = fields
+
+    def read_map(
+        self,
+        schema: Schema,
+        consumer: Callable[[str, "ShapeDeserializer"], None],
+    ) -> None:
+        trim = len(self._prefix)
+        for field in self._fields:
+            if field.name.lower().startswith(self._prefix):
+                consumer(field.name[trim:], HTTPHeaderDeserializer(field.as_string()))
+
+
+class HTTPResponseCodeDeserializer(SpecificShapeDeserializer):
+    """Binds HTTP response codes to a deserializeable shape."""
+
+    def __init__(self, response_code: int) -> None:
+        """Initialize an HTTPResponseCodeDeserializer.
+
+        :param response_code: The response code to bind.
+        """
+        self._response_code = response_code
+
+    def read_byte(self, schema: Schema) -> int:
+        return self._response_code
+
+    def read_short(self, schema: Schema) -> int:
+        return self._response_code
+
+    def read_integer(self, schema: Schema) -> int:
+        return self._response_code
+
+
+class RawPayloadDeserializer(SpecificShapeDeserializer):
+    """Binds an HTTP payload to a deserializeable shape."""
+
+    def __init__(self, payload: "AsyncStreamingBlob") -> None:
+        """Initialize a RawPayloadDeserializer.
+
+        :param payload: The payload to bind. If the member that is bound to the payload
+            is a string or blob, it MUST NOT be an async stream. Async streams MUST be
+            buffered into a synchronous stream ahead of time.
+        """
+        self._payload = payload
+
+    def read_string(self, schema: Schema) -> str:
+        return self._consume_payload().decode("utf-8")
+
+    def read_blob(self, schema: Schema) -> bytes:
+        return self._consume_payload()
+
+    def read_data_stream(self, schema: Schema) -> "AsyncStreamingBlob":
+        return self._payload
+
+    def _consume_payload(self) -> bytes:
+        if isinstance(self._payload, bytes):
+            return self._payload
+        if isinstance(self._payload, bytearray):
+            return bytes(self._payload)
+        if is_bytes_reader(self._payload):
+            return self._payload.read()
+        raise UnsupportedStreamException(
+            "Unable to read async stream. This stream must be buffered prior "
+            "to creating the deserializer."
+        )

smithy_http/endpoints.py

@@ -0,0 +1,30 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+from dataclasses import dataclass
+
+from smithy_core.endpoints import Endpoint
+from smithy_core.interfaces import TypedProperties as _TypedProperties
+from smithy_core.interfaces import URI
+from smithy_core.types import PropertyKey, TypedProperties
+
+from . import Fields, interfaces
+
+HEADERS = PropertyKey(key="headers", value_type=interfaces.Fields)
+"""An Endpoint property indicating the given fields MUST be added to the request."""
+
+
+@dataclass(init=False, kw_only=True)
+class HTTPEndpoint(Endpoint):
+    """A resolved endpoint with optional HTTP headers."""
+
+    def __init__(
+        self,
+        *,
+        uri: URI,
+        properties: _TypedProperties | None = None,
+        headers: interfaces.Fields | None = None,
+    ) -> None:
+        self.uri = uri
+        self.properties = properties if properties is not None else TypedProperties()
+        headers = headers if headers is not None else Fields()
+        self.properties[HEADERS] = headers

smithy_http/exceptions.py

@@ -0,0 +1,7 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+from smithy_core.exceptions import SmithyException
+
+
+class SmithyHTTPException(SmithyException):
+    """Base exception type for all exceptions raised in HTTP clients."""

smithy_http/interceptors/__init__.py

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