smithy-cbor 0.1.0__py3-none-any.whl

smithy_cbor/__init__.py

@@ -0,0 +1,40 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+from io import BytesIO
+
+from smithy_core.codecs import Codec
+from smithy_core.deserializers import ShapeDeserializer
+from smithy_core.interfaces import BytesReader, BytesWriter
+from smithy_core.serializers import ShapeSerializer
+
+from ._private.deserializers import CBORShapeDeserializer as _CBORShapeDeserializer
+from ._private.generic import loads as loads
+from ._private.serializers import CBORShapeSerializer as _CBORShapeSerializer
+from .settings import CBORSettings
+
+__version__ = "0.1.0"
+__all__ = ("CBORCodec", "CBORSettings", "loads")
+
+
+class CBORCodec(Codec):
+    """Targets the subset of CBOR used by the ``smithy.protocols#rpcv2Cbor`` protocol."""
+
+    def __init__(
+        self,
+        default_namespace: str | None = None,
+    ) -> None:
+        self._settings = CBORSettings(
+            default_namespace=default_namespace,
+        )
+
+    @property
+    def media_type(self) -> str:
+        return "application/cbor"
+
+    def create_serializer(self, sink: BytesWriter) -> "ShapeSerializer":
+        return _CBORShapeSerializer(sink, settings=self._settings)
+
+    def create_deserializer(self, source: bytes | BytesReader) -> "ShapeDeserializer":
+        if isinstance(source, bytes):
+            source = BytesIO(source)
+        return _CBORShapeDeserializer(source, settings=self._settings)

smithy_cbor/_private/__init__.py

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

smithy_cbor/_private/deserializers.py

@@ -0,0 +1,431 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+"""CBOR shape deserializer."""
+
+import datetime
+import struct as _struct
+from collections.abc import Callable
+from decimal import Decimal
+from typing import override
+
+from smithy_core.deserializers import ShapeDeserializer
+from smithy_core.documents import Document
+from smithy_core.exceptions import SmithyError
+from smithy_core.interfaces import BytesReader
+from smithy_core.schemas import Schema
+
+from ..settings import CBORSettings
+
+# Major type occupies the high 3 bits; the low 5 bits are the "additional information".
+_MAJOR_UINT = 0
+_MAJOR_NEGINT = 1
+_MAJOR_BYTES = 2
+_MAJOR_TEXT = 3
+_MAJOR_ARRAY = 4
+_MAJOR_MAP = 5
+_MAJOR_TAG = 6
+_MAJOR_SIMPLE = 7
+
+# Additional-information 24-27: the following value occupies 1, 2, 4, or 8 bytes.
+_W_1BYTE = 24
+_W_2BYTE = 25
+_W_4BYTE = 26
+_W_8BYTE = 27
+_INDEFINITE = 31
+
+_SIMPLE_FALSE = 20
+_SIMPLE_TRUE = 21
+_SIMPLE_NULL = 22
+
+_TAG_EPOCH = 1
+_TAG_UNSIGNED_BIGNUM = 2
+_TAG_NEGATIVE_BIGNUM = 3
+_TAG_DECIMAL_FRACTION = 4
+
+# ends indefinite item
+_BREAK = 0xFF
+
+# Initial byte of a CBOR null (major 7, simple value 22).
+_NULL_BYTE = (_MAJOR_SIMPLE << 5) | _SIMPLE_NULL
+
+
+class CBORDecodeError(SmithyError):
+    pass
+
+
+class CBORShapeDeserializer(ShapeDeserializer):
+    def __init__(self, source: BytesReader, settings: CBORSettings) -> None:
+        self._settings = settings
+        self._data = source.read()
+        self._len: int = len(self._data)
+        self._pos: int = 0
+
+    @override
+    def read_struct(
+        self,
+        schema: Schema,
+        consumer: Callable[[Schema, ShapeDeserializer], None],
+    ) -> None:
+        count = self._expect(_MAJOR_MAP)
+        members_get = schema.members.get
+        cursor = self
+        read_text = self._read_text
+        skip_value = self._skip_value
+        read_null = self.read_null
+
+        indefinite = count == -1
+        remaining = count
+        while True:
+            if indefinite:
+                if cursor._at_break():
+                    cursor._consume_break()
+                    break
+            else:
+                if remaining <= 0:
+                    break
+                remaining -= 1
+            key = read_text()
+            member = members_get(key)
+            if member is None:
+                skip_value()
+            elif cursor._at_null():
+                read_null()
+            else:
+                consumer(member, self)
+
+    @override
+    def read_list(
+        self, schema: Schema, consumer: Callable[[ShapeDeserializer], None]
+    ) -> None:
+        count = self._expect(_MAJOR_ARRAY)
+        if count == -1:
+            while not self._at_break():
+                consumer(self)
+            self._consume_break()
+        else:
+            for _ in range(count):
+                consumer(self)
+
+    @override
+    def read_map(
+        self,
+        schema: Schema,
+        consumer: Callable[[str, ShapeDeserializer], None],
+    ) -> None:
+        count = self._expect(_MAJOR_MAP)
+        if count == -1:
+            while not self._at_break():
+                key = self._read_text()
+                consumer(key, self)
+            self._consume_break()
+        else:
+            for _ in range(count):
+                key = self._read_text()
+                consumer(key, self)
+
+    @override
+    def is_null(self) -> bool:
+        initial = self._peek_byte()
+        return initial == ((_MAJOR_SIMPLE << 5) | _SIMPLE_NULL)
+
+    @override
+    def read_null(self) -> None:
+        major, arg = self._read_head()
+        if major != _MAJOR_SIMPLE or arg != _SIMPLE_NULL:
+            raise CBORDecodeError("Expected CBOR null.")
+
+    @override
+    def read_boolean(self, schema: Schema) -> bool:
+        major, arg = self._read_head()
+        if major != _MAJOR_SIMPLE or arg not in (_SIMPLE_FALSE, _SIMPLE_TRUE):
+            raise CBORDecodeError("Expected CBOR boolean.")
+        return arg == _SIMPLE_TRUE
+
+    @override
+    def read_blob(self, schema: Schema) -> bytes:
+        return self._read_string_bytes(_MAJOR_BYTES)
+
+    @override
+    def read_integer(self, schema: Schema) -> int:
+        major, arg = self._read_head()
+        if major == _MAJOR_UINT:
+            return arg
+        if major == _MAJOR_NEGINT:
+            return -1 - arg
+        raise CBORDecodeError(f"Expected CBOR integer, found major type {major}.")
+
+    @override
+    def read_float(self, schema: Schema) -> float:
+        major, add_info, arg = self._read_head_add_info()
+        if major != _MAJOR_SIMPLE:
+            raise CBORDecodeError("Expected CBOR float.")
+        if add_info == _W_8BYTE:  # double
+            return _struct.unpack(">d", arg.to_bytes(8, "big"))[0]
+        if add_info == _W_4BYTE:  # single
+            return _struct.unpack(">f", arg.to_bytes(4, "big"))[0]
+        if add_info == _W_2BYTE:  # half
+            return _decode_half(arg.to_bytes(2, "big"))
+        raise CBORDecodeError(f"Unexpected float additional-info: {add_info}.")
+
+    @override
+    def read_big_integer(self, schema: Schema) -> int:
+        major, tag = self._read_head()
+        if major != _MAJOR_TAG or tag not in (
+            _TAG_UNSIGNED_BIGNUM,
+            _TAG_NEGATIVE_BIGNUM,
+        ):
+            raise CBORDecodeError("Expected CBOR bignum tag.")
+        magnitude = int.from_bytes(self.read_blob(schema), "big")
+        return magnitude if tag == _TAG_UNSIGNED_BIGNUM else -1 - magnitude
+
+    @override
+    def read_big_decimal(self, schema: Schema) -> Decimal:
+        major, tag = self._read_head()
+        if major != _MAJOR_TAG or tag != _TAG_DECIMAL_FRACTION:
+            raise CBORDecodeError("Expected CBOR decimal-fraction tag.")
+        count = self._expect(_MAJOR_ARRAY)
+        if count != 2:
+            raise CBORDecodeError("Decimal fraction must be a 2-element array.")
+        exponent = self.read_integer(schema)
+        mantissa = self.read_integer(schema)
+        return Decimal(mantissa).scaleb(exponent)
+
+    @override
+    def read_string(self, schema: Schema) -> str:
+        return self._read_text()
+
+    @override
+    def read_document(self, schema: Schema) -> Document:
+        raise NotImplementedError(
+            "This version of the Smithy RPCv2 CBOR protocol does not support document types."
+        )
+
+    @override
+    def read_timestamp(self, schema: Schema) -> datetime.datetime:
+        major, tag = self._read_head()
+        if major != _MAJOR_TAG or tag != _TAG_EPOCH:
+            raise CBORDecodeError("Expected CBOR epoch-timestamp tag.")
+        # The tagged value is an int or float number of epoch seconds.
+        peek_major = self._peek_byte() >> 5
+        if peek_major in (_MAJOR_UINT, _MAJOR_NEGINT):
+            seconds: float = self.read_integer(schema)
+        else:
+            seconds = self.read_float(schema)
+        return datetime.datetime.fromtimestamp(seconds, tz=datetime.UTC)
+
+    def _read_text(self) -> str:
+        text = self._try_read_text()
+        if text is not None:
+            return text
+        return self._read_string_bytes(_MAJOR_TEXT).decode("utf-8")
+
+    def _read_string_bytes(self, major: int) -> bytes:
+        """An indefinite-length string (RFC 8949 §3.2.3) is a sequence of definite-length
+        chunks of the same major type, terminated by a break.
+        """
+        found_major, arg = self._read_head()
+        while found_major == _MAJOR_TAG:
+            found_major, arg = self._read_head()
+        if found_major != major:
+            raise CBORDecodeError(
+                f"Expected CBOR major type {major}, found {found_major}."
+            )
+        if arg != -1:
+            return self._take(arg)
+        chunks = bytearray()
+        while not self._at_break():
+            chunk_major, chunk_len = self._read_head()
+            if chunk_major != major:
+                raise CBORDecodeError(
+                    "Indefinite-length string chunk has mismatched major type."
+                )
+            chunks += self._take(chunk_len)
+        self._consume_break()
+        return bytes(chunks)
+
+    def _skip_value(self) -> None:
+        """e.g. unrecognized member."""
+        major, arg = self._read_head()
+        if major in (_MAJOR_UINT, _MAJOR_NEGINT):
+            return
+        if major in (_MAJOR_BYTES, _MAJOR_TEXT):
+            self._take(arg)
+        elif major == _MAJOR_ARRAY:
+            if arg == -1:
+                while not self._at_break():
+                    self._skip_value()
+                self._consume_break()
+            else:
+                for _ in range(arg):
+                    self._skip_value()
+        elif major == _MAJOR_MAP:
+            if arg == -1:
+                while not self._at_break():
+                    self._skip_value()
+                    self._skip_value()
+                self._consume_break()
+            else:
+                for _ in range(arg):
+                    self._skip_value()
+                    self._skip_value()
+        elif major == _MAJOR_TAG:
+            self._skip_value()
+        elif major == _MAJOR_SIMPLE:
+            if arg == _W_2BYTE:
+                self._take(2)
+            elif arg == _W_4BYTE:
+                self._take(4)
+            elif arg == _W_8BYTE:
+                self._take(8)
+
+    def _expect(self, major: int) -> int:
+        found_major, arg = self._read_head()
+        while found_major == _MAJOR_TAG:
+            found_major, arg = self._read_head()
+        if found_major != major:
+            raise CBORDecodeError(
+                f"Expected CBOR major type {major}, found {found_major}."
+            )
+        return arg
+
+    def _take(self, n: int) -> bytes:
+        end = self._pos + n
+        if end > self._len:
+            raise CBORDecodeError("Unexpected end of CBOR input.")
+        chunk = self._data[self._pos : end]
+        self._pos = end
+        return chunk
+
+    def _peek_byte(self) -> int:
+        pos = self._pos
+        if pos >= self._len:
+            raise CBORDecodeError("Unexpected end of CBOR input.")
+        return self._data[pos]
+
+    def _read_head(self) -> tuple[int, int]:
+        """For indefinite-length items the argument is returned as ``-1``."""
+        data = self._data
+        pos = self._pos
+        if pos >= self._len:
+            raise CBORDecodeError("Unexpected end of CBOR input.")
+        initial = data[pos]
+        major = initial >> 5
+        add_info = initial & 0x1F
+        if add_info < _W_1BYTE:
+            self._pos = pos + 1
+            return major, add_info
+        if add_info == _W_1BYTE:
+            end = pos + 2
+            if end > self._len:
+                raise CBORDecodeError("Unexpected end of CBOR input.")
+            self._pos = end
+            return major, data[pos + 1]
+        if add_info == _W_2BYTE:
+            width = 2
+        elif add_info == _W_4BYTE:
+            width = 4
+        elif add_info == _W_8BYTE:
+            width = 8
+        elif add_info == _INDEFINITE:
+            self._pos = pos + 1
+            return major, -1
+        else:
+            raise CBORDecodeError(f"Reserved additional-information value: {add_info}")
+        start = pos + 1
+        end = start + width
+        if end > self._len:
+            raise CBORDecodeError("Unexpected end of CBOR input.")
+        self._pos = end
+        return major, int.from_bytes(data[start:end], "big")
+
+    def _read_head_add_info(self) -> tuple[int, int, int]:
+        """Returns (major, add_info, arg): major type, raw additional-info bits, and the
+        decoded argument. add_info is kept to recover a float's width, which arg alone
+        loses; arg is -1 for an indefinite-length item.
+        """
+        data = self._data
+        pos = self._pos
+        if pos >= self._len:
+            raise CBORDecodeError("Unexpected end of CBOR input.")
+        initial = data[pos]
+        major = initial >> 5
+        add_info = initial & 0x1F
+        if add_info < _W_1BYTE:
+            self._pos = pos + 1
+            return major, add_info, add_info
+        if add_info == _W_1BYTE:
+            end = pos + 2
+            if end > self._len:
+                raise CBORDecodeError("Unexpected end of CBOR input.")
+            self._pos = end
+            return major, add_info, data[pos + 1]
+        if add_info == _W_2BYTE:
+            width = 2
+        elif add_info == _W_4BYTE:
+            width = 4
+        elif add_info == _W_8BYTE:
+            width = 8
+        elif add_info == _INDEFINITE:
+            self._pos = pos + 1
+            return major, add_info, -1
+        else:
+            raise CBORDecodeError(f"Reserved additional-information value: {add_info}")
+        start = pos + 1
+        end = start + width
+        if end > self._len:
+            raise CBORDecodeError("Unexpected end of CBOR input.")
+        self._pos = end
+        return major, add_info, int.from_bytes(data[start:end], "big")
+
+    def _at_break(self) -> bool:
+        pos = self._pos
+        return pos < self._len and self._data[pos] == _BREAK
+
+    def _consume_break(self) -> None:
+        self._take(1)
+
+    def _try_read_text(self) -> str | None:
+        """Fast path for a definite-length text string (major 3, no tag prefix), which
+        is every struct key and every string value in practice. Returns ``None`` when
+        the next item is not such a string, so the caller falls back to the general path.
+        """
+        data = self._data
+        pos = self._pos
+        if pos >= self._len:
+            return None
+        initial = data[pos]
+        if (initial >> 5) != _MAJOR_TEXT:
+            return None
+        add_info = initial & 0x1F
+        if add_info < _W_1BYTE:
+            start = pos + 1
+            end = start + add_info
+        elif add_info == _W_1BYTE and pos + 1 < self._len:
+            length = data[pos + 1]
+            start = pos + 2
+            end = start + length
+        else:
+            return None
+        if end > self._len:
+            return None
+        self._pos = end
+        return data[start:end].decode("utf-8")
+
+    def _at_null(self) -> bool:
+        pos = self._pos
+        return pos < self._len and self._data[pos] == _NULL_BYTE
+
+
+def _decode_half(data: bytes) -> float:
+    """Decodes an IEEE 754 half-precision float, implementing RFC 8949 Appendix D."""
+    (bits,) = _struct.unpack(">H", data)
+    sign = (bits >> 15) & 0x1
+    exp = (bits >> 10) & 0x1F
+    mant = bits & 0x3FF
+    if exp == 0:
+        value = (mant / 1024.0) * (2.0**-14)
+    elif exp == 0x1F:
+        value = float("inf") if mant == 0 else float("nan")
+    else:
+        value = (1.0 + mant / 1024.0) * (2.0 ** (exp - 15))
+    return -value if sign else value

smithy_cbor/_private/generic.py

@@ -0,0 +1,152 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+"""Generic, schema-free CBOR decoding."""
+
+import datetime
+import struct as _struct
+from decimal import Decimal
+from typing import Any
+
+_TAG_EPOCH = 1
+_TAG_UNSIGNED_BIGNUM = 2
+_TAG_NEGATIVE_BIGNUM = 3
+_TAG_DECIMAL_FRACTION = 4
+
+# Additional-information 24-27: the following value occupies 1, 2, 4, or 8 bytes.
+_W_1BYTE = 24
+_W_2BYTE = 25
+_W_4BYTE = 26
+_W_8BYTE = 27
+_INDEFINITE = 31
+
+_BREAK = 0xFF
+
+
+def loads(data: bytes) -> Any:
+    return _decode(data, 0)[0]
+
+
+def _read_head(data: bytes, pos: int) -> tuple[int, int, int, int]:
+    """Indefinite arg is -1."""
+    initial = data[pos]
+    major = initial >> 5
+    ai = initial & 0x1F
+    pos += 1
+    if ai < _W_1BYTE:
+        return major, ai, ai, pos
+    if ai == _W_1BYTE:
+        return major, ai, data[pos], pos + 1
+    if ai == _W_2BYTE:
+        return major, ai, int.from_bytes(data[pos : pos + 2], "big"), pos + 2
+    if ai == _W_4BYTE:
+        return major, ai, int.from_bytes(data[pos : pos + 4], "big"), pos + 4
+    if ai == _W_8BYTE:
+        return major, ai, int.from_bytes(data[pos : pos + 8], "big"), pos + 8
+    if ai == _INDEFINITE:
+        return major, ai, -1, pos
+    raise ValueError(f"Reserved CBOR additional-information value: {ai}")
+
+
+def _decode(data: bytes, pos: int) -> tuple[Any, int]:
+    major, ai, arg, pos = _read_head(data, pos)
+    if major == 0:
+        return arg, pos
+    if major == 1:
+        return -1 - arg, pos
+    if major == 2:
+        return _decode_bytes(data, pos, arg, major)
+    if major == 3:
+        raw, pos = _decode_bytes(data, pos, arg, major)
+        return raw.decode("utf-8"), pos
+    if major == 4:
+        return _decode_array(data, pos, arg)
+    if major == 5:
+        return _decode_map(data, pos, arg)
+    if major == 6:
+        return _decode_tagged(data, pos, arg)
+    return _decode_simple(data, ai, arg, pos)
+
+
+def _decode_bytes(data: bytes, pos: int, arg: int, major: int) -> tuple[bytes, int]:
+    if arg != -1:
+        return data[pos : pos + arg], pos + arg
+    # Indefinite-length string: concatenation of definite-length chunks until break.
+    chunks = bytearray()
+    while data[pos] != _BREAK:
+        _cmajor, _cai, clen, pos = _read_head(data, pos)
+        chunks += data[pos : pos + clen]
+        pos += clen
+    return bytes(chunks), pos + 1
+
+
+def _decode_array(data: bytes, pos: int, arg: int) -> tuple[list[Any], int]:
+    items: list[Any] = []
+    if arg == -1:
+        while data[pos] != _BREAK:
+            value, pos = _decode(data, pos)
+            items.append(value)
+        return items, pos + 1
+    for _ in range(arg):
+        value, pos = _decode(data, pos)
+        items.append(value)
+    return items, pos
+
+
+def _decode_map(data: bytes, pos: int, arg: int) -> tuple[dict[Any, Any], int]:
+    result: dict[Any, Any] = {}
+    if arg == -1:
+        while data[pos] != _BREAK:
+            key, pos = _decode(data, pos)
+            value, pos = _decode(data, pos)
+            result[key] = value
+        return result, pos + 1
+    for _ in range(arg):
+        key, pos = _decode(data, pos)
+        value, pos = _decode(data, pos)
+        result[key] = value
+    return result, pos
+
+
+def _decode_tagged(data: bytes, pos: int, tag: int) -> tuple[Any, int]:
+    if tag in (_TAG_UNSIGNED_BIGNUM, _TAG_NEGATIVE_BIGNUM):
+        magnitude_bytes, pos = _decode(data, pos)
+        magnitude = int.from_bytes(magnitude_bytes, "big")
+        return (magnitude if tag == _TAG_UNSIGNED_BIGNUM else -1 - magnitude), pos
+    if tag == _TAG_DECIMAL_FRACTION:
+        array, pos = _decode(data, pos)
+        exponent, mantissa = array
+        return Decimal(mantissa).scaleb(exponent), pos
+    if tag == _TAG_EPOCH:
+        seconds, pos = _decode(data, pos)
+        return datetime.datetime.fromtimestamp(seconds, tz=datetime.UTC), pos
+    # Unknown tag: return the tagged content unchanged.
+    return _decode(data, pos)
+
+
+def _decode_simple(data: bytes, ai: int, arg: int, pos: int) -> tuple[Any, int]:
+    if ai == 20:
+        return False, pos
+    if ai == 21:
+        return True, pos
+    if ai in (22, 23):
+        return None, pos
+    if ai == 25:
+        return _decode_half(arg), pos
+    if ai == 26:
+        return _struct.unpack(">f", arg.to_bytes(4, "big"))[0], pos
+    if ai == 27:
+        return _struct.unpack(">d", arg.to_bytes(8, "big"))[0], pos
+    return arg, pos
+
+
+def _decode_half(bits: int) -> float:
+    sign = (bits >> 15) & 0x1
+    exp = (bits >> 10) & 0x1F
+    mant = bits & 0x3FF
+    if exp == 0:
+        value = (mant / 1024.0) * (2.0**-14)
+    elif exp == 0x1F:
+        value = float("inf") if mant == 0 else float("nan")
+    else:
+        value = (1.0 + mant / 1024.0) * (2.0 ** (exp - 15))
+    return -value if sign else value

smithy_cbor/_private/schema_extensions.py

@@ -0,0 +1,115 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+"""Cached schema metadata used by the CBOR codec."""
+
+from dataclasses import dataclass
+
+from smithy_core.schemas import Schema, SchemaExtension
+from smithy_core.shapes import ShapeType
+
+
+@dataclass(frozen=True, slots=True)
+class CBORMemberLookup:
+    """Matches raw UTF-8 CBOR field names to member schemas."""
+
+    ordered_schemas: tuple[Schema, ...]
+    ordered_name_bytes: tuple[bytes, ...]
+    entries_by_name: dict[bytes, Schema]
+
+    def lookup(
+        self,
+        data: bytes,
+        start: int,
+        end: int,
+        expected_next: int,
+    ) -> Schema | None:
+        """Look up a member without decoding its field name to a string."""
+        name_length = end - start
+        if 0 <= expected_next < len(self.ordered_name_bytes):
+            expected = self.ordered_name_bytes[expected_next]
+            if len(expected) == name_length and data.startswith(expected, start, end):
+                return self.ordered_schemas[expected_next]
+
+        return self.entries_by_name.get(data[start:end])
+
+
+@dataclass(frozen=True, slots=True)
+class CBORSchemaMetadata:
+    """Precomputed CBOR data stored on a schema."""
+
+    member_name_bytes: bytes | None = None
+    member_lookup: CBORMemberLookup | None = None
+    field_name_table: tuple[bytes | None, ...] = ()
+    member_count: int = 0
+    struct_header_width: int = 1
+
+
+def _encode_member_name(name: str) -> bytes:
+    encoded = name.encode("utf-8")
+    length = len(encoded)
+    if length < 24:
+        return bytes((0x60 | length,)) + encoded
+    if length < 0x100:
+        return b"\x78" + bytes((length,)) + encoded
+    if length < 0x10000:
+        return b"\x79" + length.to_bytes(2, "big") + encoded
+    if length < 0x100000000:
+        return b"\x7a" + length.to_bytes(4, "big") + encoded
+    return b"\x7b" + length.to_bytes(8, "big") + encoded
+
+
+def _head_width(arg: int) -> int:
+    if arg < 24:
+        return 1
+    if arg < 0x100:
+        return 2
+    if arg < 0x10000:
+        return 3
+    if arg < 0x100000000:
+        return 5
+    return 9
+
+
+def _build_cbor_schema_metadata(schema: Schema) -> CBORSchemaMetadata | None:
+    if schema.member_target is not None:
+        return CBORSchemaMetadata(
+            member_name_bytes=_encode_member_name(schema.expect_member_name())
+        )
+
+    if schema.shape_type not in (ShapeType.STRUCTURE, ShapeType.UNION):
+        return None
+
+    members = tuple(
+        sorted(schema.members.values(), key=lambda member: member.expect_member_index())
+    )
+    member_count = len(members)
+    if not members:
+        return CBORSchemaMetadata()
+
+    max_index = max(member.expect_member_index() for member in members)
+    field_name_table: list[bytes | None] = [None] * (max_index + 1)
+    ordered_name_bytes: list[bytes] = []
+    entries_by_name: dict[bytes, Schema] = {}
+
+    for member in members:
+        raw_name = member.expect_member_name().encode("utf-8")
+        ordered_name_bytes.append(raw_name)
+        entries_by_name[raw_name] = member
+        field_name_table[member.expect_member_index()] = _encode_member_name(
+            member.expect_member_name()
+        )
+
+    return CBORSchemaMetadata(
+        member_lookup=CBORMemberLookup(
+            ordered_schemas=members,
+            ordered_name_bytes=tuple(ordered_name_bytes),
+            entries_by_name=entries_by_name,
+        ),
+        field_name_table=tuple(field_name_table),
+        member_count=member_count,
+        struct_header_width=_head_width(member_count),
+    )
+
+
+CBOR_SCHEMA_EXTENSION = SchemaExtension(_build_cbor_schema_metadata)
+"""Shared descriptor for lazily cached CBOR schema metadata."""

smithy_cbor/_private/serializers.py

@@ -0,0 +1,357 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+"""CBOR shape serializer.
+
+Aggregates are definite-length: lists and maps take their element count up front, and
+structs reserve a header slot sized for the schema's max member count, then patch the
+actual present-member count into it on close.
+"""
+
+import datetime
+import struct as _struct
+from collections.abc import Callable
+from contextlib import AbstractContextManager, nullcontext
+from decimal import Decimal
+from io import BytesIO
+from types import TracebackType
+from typing import Self, override
+
+from smithy_core.documents import Document
+from smithy_core.interfaces import BytesWriter
+from smithy_core.schemas import Schema
+from smithy_core.serializers import MapSerializer, ShapeSerializer
+from smithy_core.shapes import ShapeType
+from smithy_core.utils import ensure_utc
+
+from ..settings import CBORSettings
+
+# CBOR major types, shifted into the high 3 bits of the initial byte.
+_MAJOR_UINT = 0 << 5
+_MAJOR_NEGINT = 1 << 5
+_MAJOR_BYTES = 2 << 5
+_MAJOR_TEXT = 3 << 5
+_MAJOR_ARRAY = 4 << 5
+_MAJOR_MAP = 5 << 5
+_MAJOR_TAG = 6 << 5
+_MAJOR_SIMPLE = 7 << 5
+
+# Tags used by rpcv2Cbor.
+_TAG_EPOCH = 1
+_TAG_UNSIGNED_BIGNUM = 2
+_TAG_NEGATIVE_BIGNUM = 3
+_TAG_DECIMAL_FRACTION = 4
+
+# Simple values (major type 7).
+_SIMPLE_FALSE = 20
+_SIMPLE_TRUE = 21
+_SIMPLE_NULL = 22
+
+# Additional-information 24-27: the following value occupies 1, 2, 4, or 8 bytes.
+_W_1BYTE = 24
+_W_2BYTE = 25
+_W_4BYTE = 26
+_W_8BYTE = 27
+
+
+class CBORShapeSerializer(ShapeSerializer):
+    def __init__(self, sink: BytesWriter, settings: CBORSettings) -> None:
+        self._sink = sink
+        self.settings = settings
+
+    def write(self, data: bytes) -> None:
+        self._sink.write(data)
+
+    @override
+    def begin_struct(self, schema: Schema) -> AbstractContextManager[ShapeSerializer]:
+        return _CBORStructSerializer(self, self._sink, schema)
+
+    @override
+    def begin_list(
+        self, schema: Schema, size: int
+    ) -> AbstractContextManager[ShapeSerializer]:
+        # A definite-length list needs no per-element framing or close step, and a value
+        # encodes identically inside a collection or not, so elements reuse this same
+        # serializer; only the header is context-specific.
+        self.write(_encode_head(_MAJOR_ARRAY, size))
+        return nullcontext(self)
+
+    @override
+    def begin_map(
+        self, schema: Schema, size: int
+    ) -> AbstractContextManager[MapSerializer]:
+        self.write(_encode_head(_MAJOR_MAP, size))
+        return nullcontext(_CBORMapSerializer(self))
+
+    @override
+    def write_null(self, schema: Schema) -> None:
+        self.write(bytes((_MAJOR_SIMPLE | _SIMPLE_NULL,)))
+
+    @override
+    def write_boolean(self, schema: Schema, value: bool) -> None:
+        self.write(bytes((_MAJOR_SIMPLE | (_SIMPLE_TRUE if value else _SIMPLE_FALSE),)))
+
+    @override
+    def write_integer(self, schema: Schema, value: int) -> None:
+        self.write(_encode_int(value))
+
+    @override
+    def write_float(self, schema: Schema, value: float) -> None:
+        # A `float` shape encodes as IEEE single (major 7, add_info 26); `double` as
+        # IEEE double (add_info 27). Half-precision is not emitted. NaN/Infinity
+        # round-trip through struct.pack unchanged.
+        if schema.shape_type is ShapeType.FLOAT:
+            self.write(bytes((_MAJOR_SIMPLE | 26,)) + _struct.pack(">f", value))
+        else:
+            self.write(bytes((_MAJOR_SIMPLE | 27,)) + _struct.pack(">d", value))
+
+    @override
+    def write_big_integer(self, schema: Schema, value: int) -> None:
+        if value >= 0:
+            tag, magnitude = _TAG_UNSIGNED_BIGNUM, value
+        else:
+            tag, magnitude = _TAG_NEGATIVE_BIGNUM, -1 - value
+        length = (magnitude.bit_length() + 7) // 8
+        payload = magnitude.to_bytes(length, "big")
+        self.write(_encode_head(_MAJOR_TAG, tag))
+        self.write(_encode_head(_MAJOR_BYTES, len(payload)))
+        self.write(payload)
+
+    @override
+    def write_big_decimal(self, schema: Schema, value: Decimal) -> None:
+        sign, digits, exponent = value.as_tuple()
+        if not isinstance(exponent, int):  # "n"/"N"/"F" for special values
+            raise ValueError(f"Cannot CBOR-encode non-finite Decimal: {value!r}")
+        mantissa = int("".join(map(str, digits)) or "0")
+        if sign:
+            mantissa = -mantissa
+        self.write(_encode_head(_MAJOR_TAG, _TAG_DECIMAL_FRACTION))
+        self.write(_encode_head(_MAJOR_ARRAY, 2))
+        self.write(_encode_int(exponent))
+        self.write(_encode_int(mantissa))
+
+    @override
+    def write_string(self, schema: Schema, value: str) -> None:
+        encoded = value.encode("utf-8")
+        self.write(_encode_head(_MAJOR_TEXT, len(encoded)))
+        self.write(encoded)
+
+    @override
+    def write_blob(self, schema: Schema, value: bytes) -> None:
+        self.write(_encode_head(_MAJOR_BYTES, len(value)))
+        self.write(value)
+
+    @override
+    def write_timestamp(self, schema: Schema, value: datetime.datetime) -> None:
+        # timestampFormat MUST NOT be respected.
+        self.write(_encode_head(_MAJOR_TAG, _TAG_EPOCH))
+        self.write_float(schema, ensure_utc(value).timestamp())
+
+    @override
+    def write_document(self, schema: Schema, value: Document) -> None:
+        raise NotImplementedError(
+            "The rpcv2Cbor protocol does not support document types."
+        )
+
+    @override
+    def flush(self) -> None:
+        # BytesWriter has no flush; the sink is written to directly.
+        pass
+
+
+def _encode_head(major: int, arg: int) -> bytes:
+    """Uses the smallest of the 1/2/4/8-byte length forms per RFC 8949 §3."""
+    if arg < _W_1BYTE:
+        return bytes((major | arg,))
+    if arg < 0x100:
+        return bytes((major | _W_1BYTE, arg))
+    if arg < 0x10000:
+        return bytes((major | _W_2BYTE,)) + arg.to_bytes(2, "big")
+    if arg < 0x100000000:
+        return bytes((major | _W_4BYTE,)) + arg.to_bytes(4, "big")
+    return bytes((major | _W_8BYTE,)) + arg.to_bytes(8, "big")
+
+
+def _head_width(arg: int) -> int:
+    """Bytes _encode_head needs for arg. A struct reserves this for its MAX member count
+    up front, then patches the actual (<=) count into that width on close.
+    """
+    if arg < _W_1BYTE:
+        return 1
+    if arg < 0x100:
+        return 2
+    if arg < 0x10000:
+        return 3
+    if arg < 0x100000000:
+        return 5
+    return 9
+
+
+def _write_head_fixed(
+    buf: memoryview, offset: int, major: int, arg: int, width: int
+) -> None:
+    """Patches a definite header of exactly `width` bytes into `buf` at `offset`.
+
+    CBOR allows a non-minimal length form, so an over-reserved width just holds the same
+    count in a wider encoding (e.g. 5 as 0xb8 0x05, not the minimal 0xa5) -- no gap.
+    """
+    if width == 1:
+        buf[offset] = major | arg
+        return
+    add_info = {2: _W_1BYTE, 3: _W_2BYTE, 5: _W_4BYTE, 9: _W_8BYTE}[width]
+    buf[offset] = major | add_info
+    buf[offset + 1 : offset + width] = arg.to_bytes(width - 1, "big")
+
+
+def _encode_int(value: int) -> bytes:
+    if value >= 0:
+        return _encode_head(_MAJOR_UINT, value)
+    # Negative integers encode -1 - n as an unsigned argument.
+    return _encode_head(_MAJOR_NEGINT, -1 - value)
+
+
+# Attribute name under which a member schema's pre-encoded CBOR key (text header +
+# UTF-8 name) is memoized. Member schemas are long-lived and shared, so encoding the
+# key once per schema removes a per-serialization encode + head allocation.
+_CBOR_KEY_ATTR = "_cbor_encoded_key"
+
+
+def _encoded_member_key(schema: Schema) -> bytes:
+    key = getattr(schema, _CBOR_KEY_ATTR, None)
+    if key is None:
+        encoded = schema.expect_member_name().encode("utf-8")
+        key = _encode_head(_MAJOR_TEXT, len(encoded)) + encoded
+        # Schema is a frozen dataclass; object.__setattr__ is its own escape hatch.
+        object.__setattr__(schema, _CBOR_KEY_ATTR, key)
+    return key
+
+
+class _CBORStructSerializer(ShapeSerializer):
+    """Emits definite-length map. Reserves the full memberCount worth of byte-width
+    and writes the actual member count back to that position when completing the struct.
+    This may waste up to 1 byte in edge-case conditions, but minimizes overall work.
+    """
+
+    def __init__(
+        self, parent: CBORShapeSerializer, sink: BytesWriter, schema: Schema
+    ) -> None:
+        self._parent = parent
+        # Reserve-and-patch needs a seekable buffer; Codec.serialize always supplies a
+        # BytesIO, and rpcv2Cbor has no streaming-serialize path that would not.
+        if not isinstance(sink, BytesIO):
+            raise TypeError(
+                "CBOR struct serialization requires a seekable BytesIO sink."
+            )
+        self._sink: BytesIO = sink
+        self._width = _head_width(len(schema.members))
+        self._offset = sink.tell()
+        sink.write(bytes(self._width))  # reserved header slot, patched on close
+        self._count = 0
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        if exc_value is not None:
+            return
+        buf = self._sink.getbuffer()
+        _write_head_fixed(buf, self._offset, _MAJOR_MAP, self._count, self._width)
+        buf.release()
+
+    @override
+    def begin_struct(self, schema: Schema) -> AbstractContextManager[ShapeSerializer]:
+        self._write_key(schema)
+        return self._parent.begin_struct(schema)
+
+    @override
+    def begin_list(
+        self, schema: Schema, size: int
+    ) -> AbstractContextManager[ShapeSerializer]:
+        self._write_key(schema)
+        return self._parent.begin_list(schema, size)
+
+    @override
+    def begin_map(
+        self, schema: Schema, size: int
+    ) -> AbstractContextManager[MapSerializer]:
+        self._write_key(schema)
+        return self._parent.begin_map(schema, size)
+
+    @override
+    def write_null(self, schema: Schema) -> None:
+        self._write_key(schema)
+        self._parent.write_null(schema)
+
+    @override
+    def write_boolean(self, schema: Schema, value: bool) -> None:
+        self._write_key(schema)
+        self._parent.write_boolean(schema, value)
+
+    @override
+    def write_integer(self, schema: Schema, value: int) -> None:
+        self._write_key(schema)
+        self._parent.write_integer(schema, value)
+
+    @override
+    def write_float(self, schema: Schema, value: float) -> None:
+        self._write_key(schema)
+        self._parent.write_float(schema, value)
+
+    @override
+    def write_big_integer(self, schema: Schema, value: int) -> None:
+        self._write_key(schema)
+        self._parent.write_big_integer(schema, value)
+
+    @override
+    def write_big_decimal(self, schema: Schema, value: Decimal) -> None:
+        self._write_key(schema)
+        self._parent.write_big_decimal(schema, value)
+
+    @override
+    def write_string(self, schema: Schema, value: str) -> None:
+        self._write_key(schema)
+        self._parent.write_string(schema, value)
+
+    @override
+    def write_blob(self, schema: Schema, value: bytes) -> None:
+        self._write_key(schema)
+        self._parent.write_blob(schema, value)
+
+    @override
+    def write_timestamp(self, schema: Schema, value: datetime.datetime) -> None:
+        self._write_key(schema)
+        self._parent.write_timestamp(schema, value)
+
+    @override
+    def write_document(self, schema: Schema, value: Document) -> None:
+        raise NotImplementedError(
+            "The rpcv2Cbor protocol does not support document types."
+        )
+
+    @override
+    def flush(self) -> None:
+        pass
+
+    def _write_key(self, schema: Schema) -> None:
+        self._count += 1
+        self._sink.write(_encoded_member_key(schema))
+
+
+class _CBORMapSerializer(MapSerializer):
+    """The definite-length map header (from `size`) is written by `begin_map` before
+    this is constructed; entries stream straight to the sink.
+    """
+
+    def __init__(self, parent: CBORShapeSerializer) -> None:
+        self._parent = parent
+
+    @override
+    def entry(self, key: str, value_writer: Callable[[ShapeSerializer], None]) -> None:
+        encoded = key.encode("utf-8")
+        self._parent.write(_encode_head(_MAJOR_TEXT, len(encoded)))
+        self._parent.write(encoded)
+        value_writer(self._parent)

smithy_cbor/py.typed

@@ -0,0 +1 @@
+Marker

smithy_cbor/settings.py

@@ -0,0 +1,12 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class CBORSettings:
+    """Configuration for the CBOR codec."""
+
+    default_namespace: str | None = None
+    """Default namespace for resolving a document's discriminator. Not yet consumed:
+    the codec does not implement document types."""

smithy_cbor-0.1.0.dist-info/METADATA

@@ -0,0 +1,35 @@
+Metadata-Version: 2.5
+Name: smithy-cbor
+Version: 0.1.0
+Summary: CBOR serialization and deserialization support for Smithy tooling.
+Project-URL: Changelog, https://github.com/smithy-lang/smithy-python/blob/develop/packages/smithy-cbor/CHANGELOG.md
+Project-URL: Code, https://github.com/smithy-lang/smithy-python/blob/develop/packages/smithy-cbor/
+Project-URL: Issue tracker, https://github.com/smithy-lang/smithy-python/issues
+Author: Amazon Web Services
+License: Apache License 2.0
+License-File: NOTICE
+Keywords: cbor,sdk,smithy
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Free Threading :: 2 - Beta
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: smithy-core
+Description-Content-Type: text/markdown
+
+# smithy-cbor
+
+This package provides generic CBOR ([RFC 8949](https://www.rfc-editor.org/rfc/rfc8949))
+serialization and deserialization support for Smithy clients and servers, targeting
+the subset of CBOR used by the `smithy.protocols#rpcv2Cbor` protocol.

smithy_cbor-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+smithy_cbor/__init__.py,sha256=-tG-gheJRSxBPnmuiVZnUsiUg4AX0K7_qnlxs0b4AKU,1418
+smithy_cbor/py.typed,sha256=E84IaZyFwfLqvXjOVW4LS6WH7QOaKEFpNh9TFyzHNQc,6
+smithy_cbor/settings.py,sha256=UnEwQRd9kuv1-Pxey5EgD4D-9hUofMN4WS7HUlGHsHo,411
+smithy_cbor/_private/__init__.py,sha256=5idTbB990emq5l8fB_u7RfQB5qGATEBtb4PxBU2IIhs,109
+smithy_cbor/_private/deserializers.py,sha256=GhT0RQTTwXEI1k1agC7Vcc6QM2AD_LVeKdL0tgPToiE,14589
+smithy_cbor/_private/generic.py,sha256=y_NJFIlyPCBT_6kXfQpGqXdK5V5ciCXGw8-M_0CgC5Q,4795
+smithy_cbor/_private/schema_extensions.py,sha256=xODPgafw0GXSmenDnOCWx3tyKBs9f_l_3dExgalFJyo,3714
+smithy_cbor/_private/serializers.py,sha256=tjS3bsm6KCcfYauEtQeKqeoN6Y_5PlV_nWn_qYGtedI,12458
+smithy_cbor-0.1.0.dist-info/METADATA,sha256=m9BG-7PXYeY-M5KdooobFfk39q8EUihHsXhe2nsUhQI,1675
+smithy_cbor-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+smithy_cbor-0.1.0.dist-info/licenses/NOTICE,sha256=1CkO1kwu3Q_OHYTj-d-yiBJA_lNN73a4zSntavaD4oc,67
+smithy_cbor-0.1.0.dist-info/RECORD,,

smithy_cbor-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

smithy_cbor-0.1.0.dist-info/licenses/NOTICE

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