voltkit-rtc-server 0.1.0__py3-none-any.whl

voltkit_rtc/server/client.py

@@ -0,0 +1,846 @@
+"""
+The REST client: rooms, chat, broadcast, usage and billing.
+
+Your backend does two things: decide who may do what, and hand the client a
+short-lived room token. It is never in the media path -- there is no stream to
+proxy, no worker to run, nothing to scale with viewers.
+
+The API secret must never leave your server. It is tenant-wide: anything
+holding it can create rooms, mint host tokens for any identity, and end
+anyone's broadcast. Clients get a room token instead -- one room, one
+identity, one role, ten minutes. It is attached only to requests for the
+controller: the public rates come from another host, and are fetched
+without it.
+
+The same endpoints, bodies, retry policy and errors as the Node SDK
+(``@voltkit-rtc/server``), with snake_case names; replies are the controller's
+JSON as plain dicts and lists, camelCase keys included.
+"""
+
+from __future__ import annotations
+
+import http.client
+import json
+import logging
+import math
+import os
+import random
+import socket
+import time
+from collections.abc import Mapping
+from typing import Any, Callable, Optional, cast
+from urllib.parse import quote, urlencode, urlsplit
+
+from ._redaction import KeyRedactor, check_api_key, hide_url_credentials
+from ._version import __version__
+from .errors import StreamError
+from .transport import HttpClientTransport, Transport, TransportError, TransportRequest
+from .types import (
+    BroadcastStream,
+    BroadcastStreamWithPublish,
+    ChatInfo,
+    ChatMessage,
+    ChatToken,
+    DailyUsage,
+    Participant,
+    PlaybackPolicy,
+    ProjectBalance,
+    Role,
+    RoomList,
+    RoomToken,
+    RoomView,
+    RoomWithHostToken,
+    RtcRates,
+    StreamAction,
+    StreamToken,
+    UsageSummary,
+)
+
+__all__ = ["DEFAULT_RETRIES", "DEFAULT_TIMEOUT", "MAX_TIMEOUT", "RATES_PATH", "USER_AGENT", "StreamClient"]
+
+#: Where the website API serves the public rates.
+RATES_PATH = "/api/v1/billing/rtc/rates/current"
+#: Sent with every request, to the controller and to the rates host.
+USER_AGENT = "voltkit-rtc-python/%s" % __version__
+#: Seconds per attempt, headers and body.
+DEFAULT_TIMEOUT = 10.0
+#: Extra attempts after a transient failure on a call that is safe to repeat.
+DEFAULT_RETRIES = 2
+#: The longest deadline held, in seconds: 2^31-1 ms, about 24.8 days (the longest a Node timer waits).
+MAX_TIMEOUT = 2147483.647
+
+_log = logging.getLogger("voltkit_rtc.server")
+
+_Json = Any
+
+
+class _Secrets:
+    """
+    The key, the URLs as given (credentials and all: where requests go) and
+    the key's redactor, on one attribute whose repr says nothing. vars(client)
+    and a debugger show ``_secrets=<secrets>``; __slots__ keeps vars() off the
+    object itself.
+    """
+
+    __slots__ = ("api_key", "base_url", "rates_base_url", "redact_key")
+
+    def __init__(self, api_key: str, base_url: str, rates_base_url: Optional[str]) -> None:
+        self.api_key = api_key
+        self.base_url = base_url
+        self.rates_base_url = rates_base_url
+        self.redact_key = KeyRedactor(api_key)
+
+    def __repr__(self) -> str:
+        return "<secrets>"
+
+
+class StreamClient:
+    """
+    A client for the tenant REST API. Make one when your server starts and
+    share it: it holds no per-call state and is safe to use from any thread.
+
+    ``base_url`` is the controller, e.g. ``https://api.voltkit.in`` (the API
+    base URL on your project's Credentials tab); ``api_key`` your project's
+    API secret, server-side only. ``rates_base_url`` is the website API's
+    origin, needed only by :meth:`get_rates` and never sent the key.
+    ``timeout`` is the deadline for each attempt in seconds, headers and body;
+    ``retries`` how many more attempts a call that is safe to repeat gets
+    after a transient failure. ``transport`` replaces the HTTP layer (a proxy,
+    instrumentation, a test double); ``sleep`` and ``jitter`` are the backoff's
+    clock and randomness, for tests.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        rates_base_url: Optional[str] = None,
+        timeout: Optional[float] = DEFAULT_TIMEOUT,
+        retries: Optional[int] = DEFAULT_RETRIES,
+        transport: Optional[Transport] = None,
+        sleep: Optional[Callable[[float], None]] = None,
+        jitter: Optional[Callable[[], float]] = None,
+    ) -> None:
+        origin = _check_origin("base_url", base_url)
+        if origin is None:
+            raise TypeError("base_url is required")
+        sent = check_api_key(api_key)
+        # Empty counts as unset, so get_rates says what is missing rather than
+        # requesting a relative URL.
+        rates = _check_origin("rates_base_url", rates_base_url)
+        self._secrets = _Secrets(sent, origin, rates)
+        #: ``base_url`` as error messages show it: credentials as [redacted].
+        self.base_url = hide_url_credentials(origin)
+        #: ``rates_base_url`` the same way, or None.
+        self.rates_base_url = hide_url_credentials(rates) if rates is not None else None
+        self.timeout = _check_timeout(timeout)
+        self.retries = _check_retries(retries)
+        self.transport: Transport = transport if transport is not None else HttpClientTransport()
+        self._sleep = sleep if sleep is not None else time.sleep
+        self._jitter = jitter if jitter is not None else random.random
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        environ: Optional[Mapping[str, str]] = None,
+        rates_base_url: Optional[str] = None,
+        timeout: Optional[float] = DEFAULT_TIMEOUT,
+        retries: Optional[int] = DEFAULT_RETRIES,
+        transport: Optional[Transport] = None,
+    ) -> StreamClient:
+        """
+        A client from ``VOLTKIT_RTC_URL`` and ``VOLTKIT_RTC_SECRET``, and
+        ``VOLTKIT_API_URL`` for the rates when it is set. The plain constructor
+        reads nothing from the environment; this one says so in its name.
+        """
+        env = os.environ if environ is None else environ
+        base_url = env.get("VOLTKIT_RTC_URL")
+        api_key = env.get("VOLTKIT_RTC_SECRET")
+        if not base_url:
+            raise TypeError("StreamClient.from_env needs VOLTKIT_RTC_URL in the environment: the API base URL")
+        if not api_key:
+            raise TypeError("StreamClient.from_env needs VOLTKIT_RTC_SECRET in the environment: the API secret")
+        if rates_base_url is None:
+            rates_base_url = env.get("VOLTKIT_API_URL") or None
+        return cls(
+            base_url,
+            api_key,
+            rates_base_url=rates_base_url,
+            timeout=timeout,
+            retries=retries,
+            transport=transport,
+        )
+
+    # --- the client never shows its secrets ---------------------------------------
+
+    def __repr__(self) -> str:
+        return "StreamClient(base_url=%r, rates_base_url=%r, timeout=%r, retries=%r)" % (
+            self.base_url,
+            self.rates_base_url,
+            self.timeout,
+            self.retries,
+        )
+
+    __str__ = __repr__
+
+    def __getstate__(self) -> dict[str, Any]:
+        # pickle, copy and deepcopy would carry the key into a file or a
+        # queue; a client is made where its key is, not moved.
+        raise TypeError("StreamClient cannot be pickled or copied: it holds the API key")
+
+    # --- rooms -----------------------------------------------------------------
+
+    def create_room(
+        self, host_identity: str, *, room_id: Optional[str] = None, metadata: _Json = None
+    ) -> RoomWithHostToken:
+        """
+        Create a room. Fails with ``room-exists`` if the id is taken; the server
+        makes an id up when ``room_id`` is left out.
+
+        For "go live", prefer :meth:`ensure_room`: a host reconnecting after a
+        dropped call hits the existing-room path, and this turns that into two
+        round trips. Never retried: a lost reply would turn a success into a
+        spurious ``room-exists``.
+        """
+        value, _ = self._request(
+            "POST",
+            "/v1/rooms",
+            body=_compact({"roomId": room_id, "hostIdentity": host_identity, "metadata": metadata}),
+            safe_to_repeat=False,
+        )
+        return cast(RoomWithHostToken, dict(value if isinstance(value, dict) else {}, existed=False))
+
+    def ensure_room(self, room_id: str, host_identity: str, *, metadata: _Json = None) -> RoomWithHostToken:
+        """
+        Create the room, or return it with a fresh host token if it already
+        exists. One round trip whether or not the host has been here before.
+        ``existed`` in the reply says which happened; ``metadata`` is applied
+        only when the room is created.
+        """
+        value, status = self._request(
+            "PUT",
+            "/v1/rooms/%s" % _segment("roomId", room_id),
+            body=_compact({"hostIdentity": host_identity, "metadata": metadata}),
+            safe_to_repeat=True,
+        )
+        return cast(RoomWithHostToken, dict(value if isinstance(value, dict) else {}, existed=status == 200))
+
+    def create_token(self, room_id: str, identity: str, role: Role) -> RoomToken:
+        """
+        Authorise one of your users. YOUR backend decides the role -- it is
+        signed into the token and the client cannot change it.
+        """
+        value, _ = self._request(
+            "POST",
+            "/v1/rooms/%s/tokens" % _segment("roomId", room_id),
+            body={"identity": identity, "role": role},
+            # Minting twice is harmless: tokens are independent and short-lived.
+            safe_to_repeat=True,
+        )
+        return cast(RoomToken, value)
+
+    def get_room(self, room_id: str) -> RoomView:
+        """The authoritative live view: ``{"room", "participants", "producers"}``, as sent."""
+        value, _ = self._request("GET", "/v1/rooms/%s" % _segment("roomId", room_id), safe_to_repeat=True)
+        return cast(RoomView, value)
+
+    def list_rooms(self) -> RoomList:
+        """Every live room for your project, as ``{"rooms": [...]}`` (an object, not a list)."""
+        value, _ = self._request("GET", "/v1/rooms", safe_to_repeat=True)
+        return cast(RoomList, value)
+
+    def list_participants(self, room_id: str) -> list[Participant]:
+        """Who is in the room now. A point-in-time read, not a presence feed."""
+        value, _ = self._request(
+            "GET", "/v1/rooms/%s/participants" % _segment("roomId", room_id), safe_to_repeat=True
+        )
+        return cast(list[Participant], _unwrap_list(value, "participants"))
+
+    def delete_room(self, room_id: str) -> None:
+        """End a room. Everyone is disconnected and the room is gone."""
+        self._request(
+            "DELETE",
+            "/v1/rooms/%s" % _segment("roomId", room_id),
+            safe_to_repeat=True,
+            # A retry that finds the room gone means the lost attempt ended it.
+            gone_is_done=True,
+        )
+
+    # --- chat -------------------------------------------------------------------
+    #
+    # A channel shares its name with the room of the same name: the people in
+    # room "show-42" and the people only in chat "show-42" are one conversation.
+    # A channel with no room behind it is chat on its own.
+
+    def create_chat_token(self, channel: str, identity: str, *, role: Optional[Role] = None) -> ChatToken:
+        """
+        Admit one of your users to a channel's chat, with no media rights. For
+        someone who is not in the room -- an audience watching a broadcast,
+        say. People in the room already have chat on the socket they hold.
+        ``role`` defaults to viewer on the server.
+        """
+        value, _ = self._request(
+            "POST",
+            "/v1/chat/%s/tokens" % _segment("channel", channel),
+            body=_compact({"identity": identity, "role": role}),
+            safe_to_repeat=True,
+        )
+        return cast(ChatToken, value)
+
+    def get_chat_info(self, channel: str) -> ChatInfo:
+        """How many identities are connected to a channel, in the room or only in its chat."""
+        value, _ = self._request("GET", "/v1/chat/%s" % _segment("channel", channel), safe_to_repeat=True)
+        return cast(ChatInfo, value)
+
+    def list_messages(
+        self, channel: str, *, limit: Optional[int] = None, before: Optional[str] = None
+    ) -> list[ChatMessage]:
+        """
+        The newest ``limit`` messages (50 by default, at most 100), oldest
+        first, direct messages included: your backend owns the conversation
+        and may need to moderate it. ``before`` is the id of the oldest message
+        you hold, to page back.
+        """
+        query: list[tuple[str, str]] = []
+        if limit:
+            query.append(("limit", str(limit)))
+        if before:
+            query.append(("before", before))
+        suffix = "?" + urlencode(query) if query else ""
+        value, _ = self._request(
+            "GET", "/v1/chat/%s/messages%s" % (_segment("channel", channel), suffix), safe_to_repeat=True
+        )
+        return cast(list[ChatMessage], _unwrap_list(value, "messages"))
+
+    def send_message(
+        self,
+        channel: str,
+        *,
+        text: Optional[str] = None,
+        type: Optional[str] = None,
+        from_: Optional[str] = None,
+        to: Optional[str] = None,
+        metadata: _Json = None,
+        ephemeral: Optional[bool] = None,
+    ) -> ChatMessage:
+        """
+        Speak from your backend: a system notice, a gift announcement, a
+        warning. Skips the per-socket rate limit and the mute list, both of
+        which exist to restrain clients. ``type`` defaults to "text" and
+        ``from_`` (the wire's ``from``) to "system"; ``to`` makes it a direct
+        message; ``ephemeral`` delivers without storing. Never retried: a lost
+        reply would become the same message twice.
+        """
+        value, _ = self._request(
+            "POST",
+            "/v1/chat/%s/messages" % _segment("channel", channel),
+            body=_compact(
+                {"text": text, "type": type, "from": from_, "to": to, "metadata": metadata, "ephemeral": ephemeral}
+            ),
+            safe_to_repeat=False,
+        )
+        return cast(ChatMessage, value)
+
+    def delete_message(self, channel: str, message_id: str) -> None:
+        """Remove a message. Everyone who could see it is told to drop it."""
+        self._request(
+            "DELETE",
+            "/v1/chat/%s/messages/%s" % (_segment("channel", channel), _segment("messageId", message_id)),
+            safe_to_repeat=True,
+            gone_is_done=True,
+        )
+
+    def list_chat_mutes(self, channel: str) -> list[str]:
+        """Identities currently muted in a channel's chat."""
+        value, _ = self._request("GET", "/v1/chat/%s/mutes" % _segment("channel", channel), safe_to_repeat=True)
+        return cast(list[str], _unwrap_list(value, "muted"))
+
+    def mute_chat(self, channel: str, identity: str) -> None:
+        """
+        Silence an identity in a channel's chat. Held for the channel, not the
+        connection, so reconnecting does not undo it. They can still read.
+        """
+        self._request(
+            "PUT",
+            "/v1/chat/%s/mutes/%s" % (_segment("channel", channel), _segment("identity", identity)),
+            safe_to_repeat=True,
+        )
+
+    def unmute_chat(self, channel: str, identity: str) -> None:
+        """Lift a mute."""
+        self._request(
+            "DELETE",
+            "/v1/chat/%s/mutes/%s" % (_segment("channel", channel), _segment("identity", identity)),
+            safe_to_repeat=True,
+            gone_is_done=True,
+        )
+
+    # --- broadcast --------------------------------------------------------------
+    #
+    # One publisher, any number of viewers, over LL-HLS and WebRTC. Answers
+    # `broadcast-disabled` (404) on a deployment without it, VoltKit cloud today
+    # included.
+
+    def create_stream(
+        self, stream_id: str, *, playback: Optional[PlaybackPolicy] = None, metadata: _Json = None
+    ) -> BroadcastStreamWithPublish:
+        """
+        Create a stream. The reply's ``publish.whipUrl`` is complete -- hand it
+        to the encoder as it is. This is the ONLY call that returns a publish
+        token; reading or listing a stream never does. ``playback`` is
+        "public" (the default) or "token". Never retried, for the reason
+        :meth:`create_room` is not.
+        """
+        value, _ = self._request(
+            "POST",
+            "/v1/streams",
+            body=_compact({"streamId": stream_id, "playback": playback, "metadata": metadata}),
+            safe_to_repeat=False,
+        )
+        return cast(BroadcastStreamWithPublish, value)
+
+    def get_stream(self, stream_id: str) -> BroadcastStream:
+        """A stream's state, viewers and playback URLs; never its publish token."""
+        value, _ = self._request("GET", "/v1/streams/%s" % _segment("streamId", stream_id), safe_to_repeat=True)
+        return cast(BroadcastStream, value)
+
+    def list_streams(self) -> list[BroadcastStream]:
+        """Every stream of your project."""
+        value, _ = self._request("GET", "/v1/streams", safe_to_repeat=True)
+        return cast(list[BroadcastStream], _unwrap_list(value, "streams"))
+
+    def update_stream(
+        self, stream_id: str, *, playback: Optional[PlaybackPolicy] = None, metadata: _Json = None
+    ) -> BroadcastStream:
+        """Change who may watch, or the stream's metadata."""
+        value, _ = self._request(
+            "PATCH",
+            "/v1/streams/%s" % _segment("streamId", stream_id),
+            body=_compact({"playback": playback, "metadata": metadata}),
+            safe_to_repeat=True,
+        )
+        return cast(BroadcastStream, value)
+
+    def delete_stream(self, stream_id: str) -> None:
+        """Delete a stream. Its publish and playback URLs stop working at once."""
+        self._request(
+            "DELETE",
+            "/v1/streams/%s" % _segment("streamId", stream_id),
+            safe_to_repeat=True,
+            gone_is_done=True,
+        )
+
+    def create_stream_token(
+        self,
+        stream_id: str,
+        *,
+        action: Optional[StreamAction] = None,
+        identity: Optional[str] = None,
+        ttl_seconds: Optional[int] = None,
+    ) -> StreamToken:
+        """
+        Mint a playback token for a viewer of a token-protected stream, or a
+        fresh publish token for an encoder whose URL has expired. The reply
+        carries the URLs the token belongs in. ``action`` is "play" (the
+        default) or "publish"; ``ttl_seconds`` is capped at 24 hours by the
+        service.
+        """
+        value, _ = self._request(
+            "POST",
+            "/v1/streams/%s/tokens" % _segment("streamId", stream_id),
+            body=_compact({"action": action, "identity": identity, "ttlSeconds": ttl_seconds}),
+            safe_to_repeat=True,
+        )
+        return cast(StreamToken, value)
+
+    # --- usage ------------------------------------------------------------------
+
+    def get_usage(self) -> UsageSummary:
+        """Your allowance, and usage for today, this month and lifetime."""
+        value, _ = self._request("GET", "/v1/usage", safe_to_repeat=True)
+        return cast(UsageSummary, value)
+
+    def get_usage_series(self, days: int = 30) -> list[DailyUsage]:
+        """
+        One entry per UTC day, oldest first, ending today. Days with no usage
+        are present and zero, so a chart drawn from it has no gaps. Up to 90
+        days.
+        """
+        value, _ = self._request("GET", "/v1/usage/series?days=%s" % quote(str(days), safe=""), safe_to_repeat=True)
+        return cast(list[DailyUsage], _unwrap_list(value, "series"))
+
+    # --- billing ----------------------------------------------------------------
+
+    def get_balance(self) -> ProjectBalance:
+        """
+        What your project can spend right now, and whether a newcomer would be
+        admitted. Read only: recharges happen on the website, never through
+        this API. Amounts are cu (1 credit = 6,000,000 cu) as decimal strings;
+        do arithmetic with int().
+        """
+        value, _ = self._request("GET", "/v1/billing/balance", safe_to_repeat=True)
+        return cast(ProjectBalance, value)
+
+    def get_rates(self) -> RtcRates:
+        """
+        The public price list. It comes from the website API
+        (``rates_base_url``), where prices are set, rather than the controller
+        -- and carries no credential, since it is public and on another host.
+        """
+        if not self._secrets.rates_base_url:
+            raise StreamError(
+                "rates-unconfigured",
+                0,
+                "getRates needs ratesBaseUrl: the website API origin that serves the public rates, "
+                "e.g. https://api.example.com",
+                False,
+            )
+        value, status = self._request(
+            "GET", RATES_PATH, safe_to_repeat=True, public_origin=self._secrets.rates_base_url
+        )
+        data = value.get("data") if isinstance(value, dict) else None
+        if not isinstance(data, dict):
+            # Not the API's { success, data } envelope: rates_base_url most
+            # likely names some other service, and asking again gets the same
+            # answer.
+            raise StreamError(
+                "http-%d" % status,
+                status,
+                "GET %s: the reply carries no rates; is ratesBaseUrl the website API origin?" % RATES_PATH,
+                False,
+            )
+        return cast(RtcRates, data)
+
+    # --- transport -------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        safe_to_repeat: bool,
+        body: Optional[dict[str, Any]] = None,
+        gone_is_done: bool = False,
+        public_origin: Optional[str] = None,
+    ) -> tuple[Any, int]:
+        """
+        One call, retried while it is transient and harmless to repeat.
+
+        Whether repeating is harmless is the caller's decision rather than the
+        verb's: retrying a create would turn a lost response into a spurious
+        "already exists"; retrying a token mint costs nothing. ``gone_is_done``
+        marks a delete: when an attempt failed in a way that may have reached
+        the server (a network failure or a 5xx) and a retry then answers 404,
+        only the earlier reply was lost, and the call is done.
+        ``public_origin`` sends the request to another origin with no API key:
+        the website API's public rates.
+        """
+        # Once, before anything is sent: a body JSON cannot carry is the
+        # caller's to fix, and no attempt would go differently.
+        payload = None if body is None else _serialize(method, path, body)
+        attempts = self.retries + 1 if safe_to_repeat else 1
+        last: Optional[StreamError] = None
+        # Whether an earlier attempt may have reached the server and done the
+        # work, its reply lost on the way back. A 429 is a refusal: that
+        # attempt did nothing.
+        may_have_landed = False
+        for attempt in range(1, attempts + 1):
+            if attempt > 1:
+                # Exponential with jitter: a fleet-wide blip should not produce
+                # a synchronised retry from every backend at once.
+                self._sleep(0.2 * 2 ** (attempt - 2) + self._jitter() * 0.1)
+            started = time.monotonic()
+            try:
+                value, status = self._once(method, path, payload, public_origin)
+            except StreamError as err:
+                _log.debug(
+                    "%s %s: %s after %s (attempt %d of %d)",
+                    method,
+                    path,
+                    err.code,
+                    _since(started),
+                    attempt,
+                    attempts,
+                )
+                if gone_is_done and may_have_landed and _is_gone(err):
+                    # The earlier attempt deleted it; this one finds it gone.
+                    return None, err.status
+                if not err.retryable:
+                    raise
+                last = err
+                if err.status != 429:
+                    may_have_landed = True
+                continue
+            _log.debug(
+                "%s %s: %d after %s (attempt %d of %d)", method, path, status, _since(started), attempt, attempts
+            )
+            return value, status
+        assert last is not None
+        raise last
+
+    def _once(
+        self, method: str, path: str, payload: Optional[bytes], public_origin: Optional[str]
+    ) -> tuple[Any, int]:
+        """One attempt. ``payload`` is the body as JSON, made once by _request."""
+        # The key is attached here and only here, and only for the controller.
+        with_key = public_origin is None
+        headers: dict[str, str] = {}
+        if with_key:
+            headers["X-API-Key"] = self._secrets.api_key
+        if payload is not None:
+            headers["Content-Type"] = "application/json"
+        headers["User-Agent"] = USER_AGENT
+        origin = self._secrets.base_url if public_origin is None else public_origin
+        request = TransportRequest(
+            method=method,
+            url=origin + path,
+            headers=headers,
+            body=payload,
+            timeout=self.timeout,
+            # Never follow a redirect with the key: following one would hand
+            # X-API-Key to whatever host the redirect names. The public rates
+            # carry no credential and may follow one (a website API behind a
+            # www. or https redirect).
+            follow_redirects=not with_key,
+        )
+        try:
+            reply = self.transport.send(request)
+        except (TimeoutError, socket.timeout):
+            raise StreamError(
+                "network", 0, "%s %s: timed out after %s" % (method, path, _ms(self.timeout)), True
+            ) from None
+        except (OSError, http.client.HTTPException, TransportError) as err:
+            # The transport's own words may quote the URL, credentials and
+            # all, or a header value it refused: neither may reach a message
+            # that will end up in someone's logs. The cause is dropped for the
+            # same reason.
+            raise StreamError(
+                "network", 0, "%s %s: %s" % (method, path, self._redact(_words_of(err))), True
+            ) from None
+
+        if with_key and 300 <= reply.status < 400:
+            # The 3xx itself is the answer: it is not retried (the same
+            # base_url redirects the same way) and it is not followed. The
+            # target is named so the fix is obvious; it is cut for a log line
+            # after the key is taken out, so the cut cannot leave part of it.
+            location = _header_of(reply.headers, "location")
+            to = " to %s" % self._redact(location)[:200] if location else ""
+            raise StreamError(
+                "redirected",
+                reply.status,
+                "%s %s: the server answered %d%s; a request carrying the API key is never redirected. "
+                "Point baseUrl at the controller itself (its exact scheme and host)"
+                % (method, path, reply.status, to),
+                False,
+            )
+        return _parse_reply(method, path, reply.status, reply.body.decode("utf-8-sig", "replace"), self._redact)
+
+    def _redact(self, text: str) -> str:
+        """``text`` with the API key, and the credentials of any URL in it, replaced by [redacted]."""
+        return hide_url_credentials(self._secrets.redact_key(text))
+
+
+# --- checks when the client is made --------------------------------------------
+
+
+def _check_origin(name: str, url: object) -> Optional[str]:
+    """``url`` without one trailing slash; None when it is unset (None, "" or "/")."""
+    if url is None or url == "":
+        return None
+    if not isinstance(url, str):
+        raise TypeError("%s must be a str, got %s" % (name, type(url).__name__))
+    origin = url[:-1] if url.endswith("/") else url
+    if not origin:
+        return None
+    parts = urlsplit(origin)
+    if not parts.scheme or not parts.netloc:
+        # Not quoted: a URL may hold credentials, and a scheme-less one is not
+        # one the redaction can read.
+        raise ValueError(
+            "%s must be an absolute URL such as https://api.voltkit.in: it names no scheme or host" % name
+        )
+    return origin
+
+
+def _check_timeout(timeout: object) -> float:
+    """``timeout`` in seconds as a deadline can hold it, or an error now."""
+    if timeout is None:
+        return DEFAULT_TIMEOUT
+    if isinstance(timeout, bool) or not isinstance(timeout, (int, float)):
+        raise TypeError("timeout must be a number of seconds, got %r" % (timeout,))
+    value = float(timeout)
+    # NaN fails every comparison, so it is named.
+    if math.isnan(value) or value <= 0:
+        raise ValueError("timeout must be a number of seconds above 0, got %r" % (timeout,))
+    return min(value, MAX_TIMEOUT)
+
+
+def _check_retries(retries: object) -> int:
+    """``retries`` as given, or an error now, instead of a failure far from the mistake."""
+    if retries is None:
+        return DEFAULT_RETRIES
+    if isinstance(retries, bool) or not isinstance(retries, (int, float)):
+        raise TypeError("retries must be a number, got %r" % (retries,))
+    # is_integer is False for NaN and the infinities as well as fractions.
+    if (isinstance(retries, float) and not retries.is_integer()) or retries < 0:
+        raise ValueError("retries must be a whole number of 0 or more, got %r" % (retries,))
+    return int(retries)
+
+
+# --- requests ------------------------------------------------------------------
+
+
+def _segment(name: str, value: str) -> str:
+    """
+    An id, as one path segment. "", "." and ".." are refused: a URL reads them
+    as steps through the path, spelt %2e or not, so no encoding keeps them in
+    their segment -- delete_room("..") would send DELETE /v1/, with the key.
+    Every other id is percent-encoded as JavaScript's encodeURIComponent does
+    (quote() keeps A-Z a-z 0-9 - _ . ~; these five are the others it leaves
+    alone), so logs read the same whichever SDK wrote them. The names in the
+    message are the API's (roomId, messageId), the same in every VoltKit SDK.
+    """
+    if not isinstance(value, str):
+        raise TypeError("%s must be a str, got %s" % (name, type(value).__name__))
+    if value in ("", ".", ".."):
+        raise StreamError(
+            "bad-request",
+            0,
+            '%s %s: an id may not be "", "." or "..", which a URL resolves to another endpoint; nothing was sent'
+            % (name, json.dumps(value)),
+            False,
+        )
+    return quote(value, safe="!*'()")
+
+
+def _compact(body: dict[str, Any]) -> dict[str, Any]:
+    # JSON.stringify drops undefined fields; an optional argument left at None
+    # is likewise not sent, rather than sent as null for the server to reject.
+    return {key: value for key, value in body.items() if value is not None}
+
+
+def _serialize(method: str, path: str, body: dict[str, Any]) -> bytes:
+    """
+    The body as JSON, or a TypeError naming the call. A structure that refers
+    to itself, a set, a datetime, or a NaN in ``metadata`` used to fail inside
+    the request, as a retryable network error; no retry could change it.
+    """
+    try:
+        return json.dumps(body, ensure_ascii=False, separators=(",", ":"), allow_nan=False).encode("utf-8")
+    except (TypeError, ValueError, OverflowError, RecursionError) as err:
+        raise TypeError("%s %s: the body cannot be sent as JSON: %s" % (method, path, err)) from err
+
+
+def _ms(seconds: float) -> str:
+    ms = round(seconds * 1000, 6)
+    if float(ms).is_integer():
+        return "%dms" % int(ms)
+    return ("%.6f" % ms).rstrip("0").rstrip(".") + "ms"
+
+
+def _since(started: float) -> str:
+    return "%dms" % int((time.monotonic() - started) * 1000)
+
+
+def _words_of(err: BaseException) -> str:
+    text = str(err).strip()
+    name = type(err).__name__
+    return "%s: %s" % (name, text) if text else name
+
+
+def _header_of(headers: Mapping[str, str], name: str) -> Optional[str]:
+    for key, value in headers.items():
+        if key.lower() == name:
+            return value or None
+    return None
+
+
+# --- replies -------------------------------------------------------------------
+
+
+def _parse_reply(method: str, path: str, status: int, text: str, redact: Callable[[str], str]) -> tuple[Any, int]:
+    """
+    A whole reply, read: the value on a 2xx, a StreamError otherwise. The
+    server's words go through ``redact`` before they reach a message, and
+    before they are cut short, so a cut cannot leave part of the key behind.
+    """
+    if not 200 <= status < 300:
+        reply_code, reply_message = _error_reply(text)
+        # Redacted too: a server answering {"error": "Invalid API key: <key>"}
+        # put the key in the code. An ordinary code holds no key and passes
+        # unchanged.
+        code = redact(reply_code) if reply_code is not None else "http-%d" % status
+        message = redact(reply_message) if reply_message is not None else redact(text)[:300]
+        # 5xx and 429 may pass; a 4xx is a decision the server made and will
+        # make again. billing-unavailable is the 503 that will not: it lasts
+        # until an operator activates a price list, or wires wallet billing in.
+        retryable = (status >= 500 or status == 429) and code != "billing-unavailable"
+        raise StreamError(code, status, "%s %s: %s" % (method, path, message), retryable)
+    if not text:
+        return None, status
+    try:
+        return _loads(text), status
+    except ValueError:
+        # A success that is not JSON came from something other than the API
+        # -- a web page, a proxy -- and a retry would fetch the same thing.
+        raise StreamError(
+            "http-%d" % status,
+            status,
+            "%s %s: the reply is not JSON: %s" % (method, path, redact(text)[:100]),
+            False,
+        ) from None
+
+
+def _error_reply(text: str) -> tuple[Optional[str], Optional[str]]:
+    """
+    The code and message of an error reply. The controller answers
+    ``{"error", "message"}``; the website API
+    ``{"success": false, "error": {"code", "message"}}``. Anything else -- a
+    proxy's HTML page -- has neither.
+    """
+    try:
+        body = _loads(text)
+    except ValueError:
+        return None, None
+    if not isinstance(body, dict):
+        return None, None
+    error = body.get("error")
+    if isinstance(error, dict):
+        code, message = error.get("code"), error.get("message")
+    elif isinstance(error, list):
+        code, message = None, None
+    else:
+        code, message = error, body.get("message")
+    return _non_empty(code), _non_empty(message)
+
+
+def _non_empty(value: Any) -> Optional[str]:
+    return value if isinstance(value, str) and value else None
+
+
+def _reject_constant(name: str) -> Any:
+    # NaN and Infinity are not JSON; JavaScript's JSON.parse refuses them too.
+    raise ValueError("not JSON: %s" % name)
+
+
+def _loads(text: str) -> Any:
+    return json.loads(text, parse_constant=_reject_constant)
+
+
+def _unwrap_list(value: Any, key: str) -> list[Any]:
+    # The API wraps every list in an object ({ participants }, { messages },
+    # ...); the method is documented as the list itself.
+    if isinstance(value, dict):
+        items = value.get(key)
+        return items if isinstance(items, list) else []
+    return []
+
+
+def _is_gone(err: StreamError) -> bool:
+    """
+    A 404 saying the thing is not there. Not one saying chat or broadcast is
+    switched off on this deployment: that deleted nothing.
+    """
+    return err.status == 404 and err.code not in ("chat-disabled", "broadcast-disabled")