muxws 0.2.0__py3-none-any.whl

muxws/__init__.py

@@ -0,0 +1,94 @@
+"""muxws - multiplexed, cancellable, bidirectional streams over one WebSocket.
+
+The three backoff helpers are exported together or not at all: `backoff_delay`, `unjittered_delay`
+and `should_retry` are one schedule seen from three sides, and an operator computing "when will it
+try again" needs all three. Exporting one of them was arbitrary.
+"""
+
+from muxws.api import accept, connect, resolve_codec, select_subprotocol, serve
+from muxws.codecs import Codec, get_codec, register_codec, registered_codecs
+from muxws.codecs.json_ import JsonCodec
+from muxws.conf import Settings, settings
+from muxws.errors import (
+    CodecError,
+    CodecMismatch,
+    CodecNotRegistered,
+    ConnectionClosed,
+    ConnectionGoingAway,
+    ConnectionLost,
+    MuxwsError,
+    ProtocolError,
+    RemoteError,
+    ResetCode,
+    StreamAlreadyConsumed,
+    StreamClosed,
+    StreamRefused,
+    StreamReset,
+    StreamTimeout,
+)
+from muxws.fragment import Assembler, encoded_length, MAX_FRAME_BYTES, split_frame
+from muxws.frames import ABSENT, Frame, from_mapping, to_mapping
+from muxws.observability import CloseReason
+from muxws.peer import default_error_serializer, ErrorSerializer, Peer, StreamHandler
+from muxws.reconnect import backoff_delay, Hello, Reconnect, should_retry, unjittered_delay
+from muxws.registry import PeerRegistry
+from muxws.stream import Stream, StreamState
+from muxws.transports import SocketAdapter
+
+__version__ = "0.2.0"
+
+# The library registers JSON itself (WSM-CDC-004); the codec module must not (WSM-CDC-014).
+register_codec("json", JsonCodec())
+
+__all__ = [
+    "ABSENT",
+    "Assembler",
+    "CloseReason",
+    "Codec",
+    "CodecError",
+    "CodecMismatch",
+    "CodecNotRegistered",
+    "ConnectionClosed",
+    "ConnectionGoingAway",
+    "ConnectionLost",
+    "ErrorSerializer",
+    "Frame",
+    "Hello",
+    "JsonCodec",
+    "MAX_FRAME_BYTES",
+    "MuxwsError",
+    "Peer",
+    "PeerRegistry",
+    "ProtocolError",
+    "Reconnect",
+    "RemoteError",
+    "ResetCode",
+    "Settings",
+    "SocketAdapter",
+    "Stream",
+    "StreamAlreadyConsumed",
+    "StreamClosed",
+    "StreamHandler",
+    "StreamRefused",
+    "StreamReset",
+    "StreamState",
+    "StreamTimeout",
+    "__version__",
+    "accept",
+    "backoff_delay",
+    "connect",
+    "default_error_serializer",
+    "encoded_length",
+    "from_mapping",
+    "get_codec",
+    "register_codec",
+    "registered_codecs",
+    "resolve_codec",
+    "select_subprotocol",
+    "serve",
+    "settings",
+    "should_retry",
+    "split_frame",
+    "to_mapping",
+    "unjittered_delay",
+]

muxws/api.py

@@ -0,0 +1,267 @@
+"""`connect`, `accept` and `serve` - the module-level factories (§9.3).
+
+The codec is resolved **before** any socket is touched. Putting the lookup after the upgrade is the
+single most likely wrong implementation of WSM-CDC-016, and it is what makes a misconfigured
+deployment fail as a puzzling decode error on the tenth frame rather than as a named startup error.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from muxws.codecs import Codec, get_codec
+from muxws.conf import settings
+from muxws.errors import CodecMismatch, ConnectionClosed, ProtocolError
+from muxws.fragment import MAX_FRAME_BYTES
+from muxws.peer import ErrorSerializer, Peer, StreamHandler
+from muxws.reconnect import ConnectionLoop, Hello, Reconnect
+from muxws.subprotocol import mismatch_error, offer, PREFIX
+from muxws.transports import SocketAdapter
+
+
+def resolve_codec(override: Codec | None = None) -> Codec:
+    """An explicit `codec=` wins (WSM-CDC-012); otherwise the configured name (WSM-CDC-010/016).
+
+    Never falls back to JSON. A deployment that believes it is running msgpack, is not, and finds
+    out from neither end is the failure WSM-INV-015 names.
+    """
+    if override is not None:
+        return override
+    return get_codec(settings.codec)
+
+
+async def connect(
+    url: str,
+    *,
+    headers: dict[str, str] | None = None,
+    subprotocols: list[str] | None = None,
+    hello: Any = None,
+    hello_headers: dict[str, Any] | None = None,
+    reconnect: Reconnect | None = None,
+    ping_interval: float = 20.0,
+    ping_timeout: float = 10.0,
+    hello_timeout: float = 10.0,
+    max_payload_bytes: int = 67_108_864,
+    max_concurrent_streams: int = 100,
+    error_serializer: ErrorSerializer | None = None,
+    codec: Codec | None = None,
+    max_frame_bytes: int = MAX_FRAME_BYTES,
+    on_stream: StreamHandler | None = None,
+    on_close: Callable[[Any], None] | None = None,
+    on_reconnect: Callable[[int, Any], None] | None = None,
+) -> Peer:
+    """Dial `url` and return a serving peer.
+
+    Raises if the **first** attempt fails, with the underlying error, whatever `reconnect` says
+    (WSM-RCN-006). Reconnection applies to connections that were established and then lost; a peer
+    that retried its first dial forever would turn a typo in the URL into silence. There is
+    deliberately no option that changes this (WSM-INV-018): a caller who wants the first dial retried
+    writes that loop itself, where it can decide what a permanent failure looks like.
+
+    Everything after that first dial belongs to the reconnect helper: the backoff schedule, the
+    heartbeat, and the hello replayed verbatim on every connection this peer ever makes.
+
+    `on_stream`, `on_close` and `on_reconnect` are the same handlers `peer.on_stream(...)` and
+    friends register, and they are registered **before** the hello goes out. That is the whole reason
+    they are parameters rather than a line the caller writes afterwards: the acceptor may push a
+    stream the instant it sees the hello, and a peer whose handler is registered one await later
+    answers that push `reset(REFUSED, "no on_stream handler")` (WSM-STM-033).
+    """
+    resolved = resolve_codec(codec)
+    dial = _websocket_dialer(url, resolved, headers=headers, subprotocols=subprotocols)
+
+    socket = await dial()
+    peer = Peer(
+        socket,
+        codec=resolved,
+        is_dialer=True,
+        error_serializer=error_serializer,
+        max_frame_bytes=max_frame_bytes,
+        max_payload_bytes=max_payload_bytes,
+        max_concurrent_streams=max_concurrent_streams,
+    )
+    if on_stream is not None:
+        peer.on_stream(on_stream)
+    if on_close is not None:
+        peer.on_close(on_close)
+    if on_reconnect is not None:
+        peer.on_reconnect(on_reconnect)
+    loop = ConnectionLoop(
+        peer,
+        dial,
+        options=reconnect or Reconnect(),
+        # Captured **here**, once, by value: replayed verbatim on every later connection and never
+        # re-read from the application's object (WSM-RCN-020).
+        hello=Hello(payload=hello, headers=hello_headers, timeout=hello_timeout),
+        ping_interval=ping_interval,
+        ping_timeout=ping_timeout,
+    )
+    await loop.establish()
+    loop.start()
+    # Held so the garbage collector cannot collect the supervisor out from under the peer.
+    peer._connection_loop = loop
+    return peer
+
+
+def _websocket_dialer(
+    url: str,
+    resolved: Codec,
+    *,
+    headers: dict[str, str] | None,
+    subprotocols: list[str] | None,
+) -> Callable[[], Awaitable[SocketAdapter]]:
+    """One closure that dials, verifies the subprotocol, and hands back a `SocketAdapter`.
+
+    The helper is given this rather than a URL because it knows nothing about transports: every
+    reconnect is the same dial as the first one, down to the offered subprotocol list, so there is
+    exactly one place where a connection is made and no way for a reconnect to negotiate something
+    the first connection did not (WSM-CDC-016/020).
+    """
+    offered = offer(resolved.name, subprotocols)
+
+    async def dial() -> SocketAdapter:
+        import websockets
+
+        from muxws.transports.websockets_ import verify_negotiated, WebsocketsSocket
+
+        try:
+            connection = await websockets.connect(
+                url,
+                subprotocols=offered,  # type: ignore[arg-type]
+                additional_headers=headers,
+            )
+        except Exception as exc:
+            if _looks_like_a_refused_handshake(exc):
+                raise mismatch_error(resolved.name) from exc
+            raise
+
+        try:
+            verify_negotiated(getattr(connection, "subprotocol", None), resolved.name)
+        except Exception:
+            from muxws.transports.websockets_ import POLICY_VIOLATION
+
+            await connection.close(code=POLICY_VIOLATION, reason="codec mismatch")
+            raise
+
+        return WebsocketsSocket(connection)
+
+    return dial
+
+
+#: What an acceptor answers a codec it does not speak (WSM-CDC-022), and the only status this reads
+#: as a refusal. Anything else is a server that failed for its own reasons and must surface as itself.
+_REFUSED = 400
+
+
+def _looks_like_a_refused_handshake(exc: BaseException) -> bool:
+    """A 400 on the upgrade is a refused muxws handshake, to be reported as `CodecMismatch`.
+
+    The status comes from `InvalidStatus.response`, never from the message. `"400" in str(exc)` also
+    matches the `OSError` for a connection refused on **port** 400, and matching a status code out of
+    prose is what let a cross-language dial - where the message wording differs - miss a real refusal
+    entirely (WSM-CDC-024). The string branch survives only as a fallback for a `websockets` release
+    that reports the status without attaching the response, and is narrowed to the phrase it uses.
+    """
+    from websockets.exceptions import InvalidStatus
+
+    if isinstance(exc, InvalidStatus):
+        return exc.response.status_code == _REFUSED
+    return f"HTTP {_REFUSED}" in str(exc)
+
+
+async def accept(
+    socket: SocketAdapter | Any,
+    *,
+    max_payload_bytes: int = 67_108_864,
+    max_concurrent_streams: int = 100,
+    error_serializer: ErrorSerializer | None = None,
+    codec: Codec | None = None,
+    max_frame_bytes: int = MAX_FRAME_BYTES,
+) -> Peer:
+    """Accept an inbound connection and return a peer that is not yet serving.
+
+    A Starlette `WebSocket` is upgraded here, because `accept()` is the only party that knows which
+    subprotocol to select (WSM-CDC-026). Anything already implementing `SocketAdapter` is taken as
+    it is.
+    """
+    resolved = resolve_codec(codec)
+    adapter = await _adapt(socket, resolved.name)
+    peer = Peer(
+        adapter,
+        codec=resolved,
+        is_dialer=False,
+        error_serializer=error_serializer,
+        max_frame_bytes=max_frame_bytes,
+        max_payload_bytes=max_payload_bytes,
+        max_concurrent_streams=max_concurrent_streams,
+    )
+    return peer
+
+
+async def _adapt(socket: Any, codec_name: str) -> SocketAdapter:
+    """Wrap whatever the application handed us, upgrading it first when that is still to be done.
+
+    The framework checks come **before** the `SocketAdapter` one. `SocketAdapter` is a
+    `runtime_checkable` Protocol, and `isinstance` against one of those tests only that the four
+    method *names* exist - which Starlette's `WebSocket` happens to satisfy. Checking it first meant
+    a Starlette socket was taken as an already-adapted one and the upgrade never happened, which
+    surfaces only against a real ASGI server.
+    """
+    if _is_starlette_websocket(socket):
+        from muxws.transports.starlette import perform_upgrade
+
+        return await perform_upgrade(socket, codec_name)
+
+    if _is_websockets_connection(socket):
+        from muxws.transports.websockets_ import verify_negotiated, WebsocketsSocket
+
+        verify_negotiated(getattr(socket, "subprotocol", None), codec_name)
+        return WebsocketsSocket(socket)
+
+    if isinstance(socket, SocketAdapter):
+        return socket
+
+    raise ProtocolError(
+        f"{type(socket).__name__} is neither a SocketAdapter nor a socket muxws knows how to "
+        f"upgrade; wrap it in an adapter (WSM-API-021)"
+    )
+
+
+def _is_starlette_websocket(socket: Any) -> bool:
+    return hasattr(socket, "scope") and hasattr(socket, "client_state")
+
+
+def _is_websockets_connection(socket: Any) -> bool:
+    """A `websockets` connection, which has already handshaken by the time we see it."""
+    return hasattr(socket, "recv") and hasattr(socket, "send") and hasattr(socket, "subprotocol")
+
+
+async def serve(socket: SocketAdapter | Any, *, handler: StreamHandler, **peer_options: Any) -> None:
+    """Accept, register `handler`, and run the read loop until the socket closes."""
+    try:
+        peer = await accept(socket, **peer_options)
+    except CodecMismatch:
+        # The upgrade was refused and the 400 has already been sent (WSM-CDC-022). There is no peer
+        # and nothing further to do; raising here would turn an ordinary misconfiguration into a
+        # traceback out of the application's endpoint.
+        return
+    peer.on_stream(handler)
+    try:
+        await peer.serve()
+    except ConnectionClosed:
+        return
+
+
+def select_subprotocol(connection: Any, subprotocols: list[str]) -> str:
+    """Re-exported handshake hook for the `websockets` library (WSM-CDC-027).
+
+    Raises `NegotiationError` rather than returning None on a mismatch; see the hook itself for why
+    that is the only shape `websockets` turns into the 400 WSM-CDC-022 requires.
+    """
+    from muxws.transports.websockets_ import select_subprotocol as hook
+
+    return hook(connection, subprotocols)
+
+
+__all__ = ["PREFIX", "accept", "connect", "resolve_codec", "select_subprotocol", "serve"]

muxws/codecs/__init__.py

@@ -0,0 +1,99 @@
+"""The codec seam: the port, and the explicit registry behind it (§2.1, WSM-CDC-001..016)."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from muxws.errors import CodecNotRegistered
+from muxws.frames import Frame
+
+
+@runtime_checkable
+class Codec(Protocol):
+    """Turns a logical frame into a WebSocket message and back.
+
+    `binary` is **declared, not inferred** (WSM-CDC-002): the peer reads it to choose the socket's
+    text or binary send method and the inbound message type it expects. A peer never sniffs a message
+    to decide which branch to take.
+
+    `encode_payload` / `decode_payload` are the payload-level half of the port. WSM-CDC-001 names
+    only the frame-level pair, but fragmentation is defined in terms of the encoded form of a
+    *logical payload* (WSM-FRG-011) which the receiver hands back to the codec once reassembled
+    (WSM-FRG-030), and neither operation can be expressed through `encode`/`decode` alone.
+    See GAPS.md.
+    """
+
+    name: str
+    binary: bool
+
+    def encode(self, frame: Frame) -> str | bytes:
+        """One whole frame - envelope and payload - as it goes on the wire.
+
+        `str` under a text codec, `bytes` under a binary one; the peer picks the socket method from
+        `binary` and never from this return type. An absent field MUST NOT be emitted at all: an
+        omitted `payload` key and `"payload": null` are different frames.
+        """
+        ...
+
+    def decode(self, message: str | bytes) -> Frame:
+        """The inverse. Unknown envelope fields MUST be dropped rather than rejected (WSM-FRM-001).
+
+        Raises `ProtocolError` when the message is not something this codec can read - that is a
+        connection-level failure, and the peer answers it with `goaway`.
+        """
+        ...
+
+    def encode_payload(self, payload: Any) -> str | bytes:
+        """A payload on its own, with no envelope around it.
+
+        This is what fragmentation slices (WSM-FRG-011), so its output has to be exactly the bytes
+        that would appear inside a frame's payload position - a codec whose two encoders disagree
+        cuts fragments at boundaries the receiver cannot rejoin.
+        """
+        ...
+
+    def decode_payload(self, data: str | bytes) -> Any:
+        """What the receiver hands back once the fragments are concatenated (WSM-FRG-030).
+
+        The inverse of `encode_payload`, and the reason the port carries four members rather than
+        the two WSM-CDC-001 names.
+        """
+        ...
+
+
+_REGISTRY: dict[str, Codec] = {}
+
+
+def register_codec(name: str, codec: Codec) -> None:
+    """Register `codec` under `name`.
+
+    Registration is explicit and eager (WSM-CDC-013): there is no dynamic import, no lazy
+    auto-registration, no entry-point scan, and no probing of whether a module happens to be
+    installed. A codec module never registers itself at import time (WSM-CDC-014).
+    """
+    _REGISTRY[name] = codec
+
+
+def get_codec(name: str) -> Codec:
+    """Return the codec registered under `name`.
+
+    Raises `CodecNotRegistered` naming the environment variable, the value found and the registered
+    set (WSM-CDC-016). There is no fallback to JSON, ever - a deployment that believes it is running
+    msgpack and silently is not may never find out (WSM-INV-015).
+    """
+    try:
+        return _REGISTRY[name]
+    except KeyError:
+        available = registered_codecs()
+        raise CodecNotRegistered(
+            f"codec {name!r} is not registered (MUXWS_CODEC={name!r}); "
+            f"registered codecs are {available!r}. Call register_codec({name!r}, ...) during "
+            f"bootstrap, before connecting.",
+            configured=name,
+            available=available,
+        ) from None
+
+
+def registered_codecs() -> list[str]:
+    """Every registered codec name, sorted."""
+    return sorted(_REGISTRY)

muxws/codecs/json_.py

@@ -0,0 +1,71 @@
+"""The JSON codec - the interoperability baseline (WSM-CDC-004..008).
+
+The module name carries a trailing underscore: a top-level `json.py` inside the package would shadow
+the stdlib module this very file imports.
+
+This module does **not** register itself (WSM-CDC-014). `muxws/__init__.py` does, because the library
+is required to ship JSON registered (WSM-CDC-004) while a side-effecting import can never be
+tree-shaken out.
+"""
+
+from __future__ import annotations
+
+import json
+
+from typing import Any
+
+from muxws.errors import ProtocolError
+from muxws.frames import Frame, from_mapping, to_mapping
+
+#: Compact separators and no ASCII escaping, so that `json.dumps` here and `JSON.stringify` in the
+#: TypeScript port emit the same bytes for the same value - for strings, containers, booleans, null
+#: and integers up to 2**53. They do **not** agree on floats or on larger integers: Python writes
+#: `1.0`, `-0.0`, `1e+16`, `1e-07` where JavaScript writes `1`, `0`, `10000000000000000`, `1e-7`,
+#: and JavaScript rounds an integer beyond 2**53 to the nearest double. Fragment boundaries are cut
+#: over this encoded form, so a payload carrying a float is cut differently by the two ports - see
+#: GAPS.md. It costs nothing on the wire (the sender chooses the cuts and the receiver only
+#: concatenates), but it does bound what the shared boundary corpus may contain.
+_DUMP_KWARGS: dict[str, Any] = {"separators": (",", ":"), "ensure_ascii": False, "allow_nan": False}
+
+
+def _reject(value: Any) -> Any:
+    """`json.dumps` default hook: refuse rather than invent an encoding.
+
+    Bytes are a first-class payload type under a binary codec and are *not* one under JSON, and muxws
+    MUST NOT base64-encode them on the application's behalf (WSM-CDC-008).
+    """
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        raise TypeError(
+            f"the json codec cannot carry {type(value).__name__}: bytes are a payload type only under "
+            f"a binary codec, and muxws does not base64-encode them for you (WSM-CDC-008). Either "
+            f"encode them in the application or configure the msgpack codec."
+        )
+    raise TypeError(f"the json codec cannot encode {type(value).__name__}")
+
+
+class JsonCodec:
+    """`Codec` implementation over the standard library's JSON."""
+
+    name = "json"
+    binary = False
+
+    def encode(self, frame: Frame) -> str:
+        return json.dumps(to_mapping(frame), default=_reject, **_DUMP_KWARGS)
+
+    def decode(self, message: str | bytes) -> Frame:
+        try:
+            mapping = json.loads(message)
+        except (ValueError, TypeError) as exc:
+            raise ProtocolError(f"the json codec could not decode the message: {exc} (WSM-FRM-005)") from exc
+        if not isinstance(mapping, dict):
+            raise ProtocolError(f"a frame must decode to an object, got {type(mapping).__name__} (WSM-FRM-005)")
+        return from_mapping(mapping)
+
+    def encode_payload(self, payload: Any) -> str:
+        return json.dumps(payload, default=_reject, **_DUMP_KWARGS)
+
+    def decode_payload(self, data: str | bytes) -> Any:
+        try:
+            return json.loads(data)
+        except (ValueError, TypeError) as exc:
+            raise ProtocolError(f"the json codec could not decode a reassembled payload: {exc}") from exc

muxws/codecs/msgpack_.py

@@ -0,0 +1,91 @@
+"""The msgpack codec - the honest proof that the codec seam is a seam (WSM-CDC-006/007/008).
+
+The module name carries a trailing underscore for the same reason `json_.py` does: a top-level
+`msgpack.py` inside the package would shadow the third-party module this very file imports.
+
+`msgpack` is an **optional extra** (WSM-PKG-002). Importing this module is the whole of the
+selection: nothing inside muxws imports it, so a deployment that never asks for msgpack never pays
+for it. And this module does **not** register itself (WSM-CDC-014) - the application calls
+`register_codec("msgpack", MsgpackCodec())` during bootstrap. There is no entry-point scan and no
+"is it installed" probe anywhere (WSM-CDC-013).
+
+Nothing here may be pinned as bytes in a fixture (WSM-CDC-006): this library and
+`@msgpack/msgpack` make different but equally valid choices about integer width and map format, and
+a pinned-bytes fixture would make a legal encoder fail. Round-trip is the only assertion.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Final
+
+import msgpack
+
+from muxws.errors import ProtocolError
+from muxws.frames import Frame, from_mapping, to_mapping
+
+#: `use_bin_type=True` is what keeps `bytes` and `str` distinguishable on the wire, and bytes are a
+#: first-class payload type under a binary codec (WSM-CDC-008). It has been the default since
+#: msgpack 1.0; it is written out because a codec whose byte type collapsed into its string type
+#: would still round-trip within one language and fail only against the other port.
+_PACK_KWARGS: Final[dict[str, Any]] = {"use_bin_type": True}
+
+#: - `raw=False` decodes msgpack `str` to `str` rather than to `bytes`. Without it every envelope key
+#:   and every `type` value would come back as `bytes`, `from_mapping` would see no `"type"` key, and
+#:   every inbound frame would be a protocol error. It is the 1.x default, and it is stated because
+#:   it was *not* the default in 0.x and a codec that silently changed shape on a downgrade is worse
+#:   than one that fails.
+#: - `strict_map_key=False` lets a map key be something other than `str`/`bytes`. The default (True)
+#:   raises `ValueError` on an integer key, which would turn an application's choice of payload shape
+#:   into a decode failure that kills the connection - muxws does not police what a payload contains.
+#:   `@msgpack/msgpack` accepts integer keys by default, so this is also what makes the two ports
+#:   agree about which payloads are decodable at all. They do *not* agree on the result: JavaScript
+#:   object keys are strings, so `{1: "a"}` comes back as `{1: "a"}` here and as `{"1": "a"}` there.
+#:   That divergence is reported in GAPS.md and is why no such payload is in the shared corpus.
+#: - `use_list=True` decodes a msgpack array to a `list`, not a `tuple`. It is the default, and it is
+#:   load-bearing: with `use_list=False`, `decode(encode(frame)) == frame` fails for every payload
+#:   containing an array, which is exactly the assertion WSM-CDC-006 rests on.
+_UNPACK_KWARGS: Final[dict[str, Any]] = {"raw": False, "strict_map_key": False, "use_list": True}
+
+
+def _unpack(data: str | bytes, what: str) -> Any:
+    """Decode one msgpack value, turning every library failure into a `ProtocolError`.
+
+    A `str` never reaches a binary codec from a correct peer: `binary` is declared, and a peer picks
+    `send_bytes` from it rather than sniffing the encoded value (WSM-CDC-002). A text message
+    arriving here therefore means the remote sent one on a binary connection, and there is no
+    recoding that could recover the bytes - the transport has already lost them. Saying so is the
+    only honest answer (WSM-FRM-005).
+    """
+    if isinstance(data, str):
+        raise ProtocolError(
+            f"the msgpack codec was handed a text {what}: msgpack is a binary codec and a text "
+            f"WebSocket message cannot carry it (WSM-CDC-002, WSM-FRM-005)"
+        )
+    try:
+        return msgpack.unpackb(data, **_UNPACK_KWARGS)
+    except (msgpack.UnpackException, ValueError, TypeError) as exc:
+        raise ProtocolError(f"the msgpack codec could not decode the {what}: {exc} (WSM-FRM-005)") from exc
+
+
+class MsgpackCodec:
+    """`Codec` implementation over the `msgpack` package."""
+
+    name = "msgpack"
+    #: Declared, never inferred (WSM-CDC-002). The peer reads this to choose `send_bytes`; it does
+    #: not look at what `encode` returned.
+    binary = True
+
+    def encode(self, frame: Frame) -> bytes:
+        return msgpack.packb(to_mapping(frame), **_PACK_KWARGS)
+
+    def decode(self, message: str | bytes) -> Frame:
+        mapping = _unpack(message, "message")
+        if not isinstance(mapping, dict):
+            raise ProtocolError(f"a frame must decode to a map, got {type(mapping).__name__} (WSM-FRM-005)")
+        return from_mapping(mapping)
+
+    def encode_payload(self, payload: Any) -> bytes:
+        return msgpack.packb(payload, **_PACK_KWARGS)
+
+    def decode_payload(self, data: str | bytes) -> Any:
+        return _unpack(data, "reassembled payload")

muxws/conf.py

@@ -0,0 +1,28 @@
+"""Deployment configuration (§2.2, WSM-CDC-010/011).
+
+The codec name is read from the environment, not from a call argument, because both ends of a
+connection must agree on it and an argument is decided per call site rather than per deployment.
+"""
+
+from __future__ import annotations
+
+import os
+
+
+class Settings:
+    """The one settings singleton. Writable, so an application may set it during bootstrap."""
+
+    def __init__(self) -> None:
+        self.codec: str = os.environ.get("MUXWS_CODEC", "json")
+
+    def reload(self) -> None:
+        """Re-read the environment. For tests; an application sets `codec` directly."""
+        self.codec = os.environ.get("MUXWS_CODEC", "json")
+
+    def __repr__(self) -> str:
+        return f"Settings(codec={self.codec!r})"
+
+
+#: Read at connection time, never at import time - or WSM-CDC-011's "an application may set it
+#: during bootstrap" stops being true for anything that imports muxws early.
+settings = Settings()