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

voltkit_rtc/server/errors.py

@@ -0,0 +1,278 @@
+"""
+Errors, and the shared registry of error codes.
+
+The controller answers errors as ``{"error", "message"}`` with a meaningful
+status. Collapsing those into a generic exception loses the one thing a caller
+needs to decide what to do: ``capacity-exhausted`` means page someone and
+retry, ``room-quota`` means your own cleanup is behind, ``bad-request`` means
+fix the call. Keep the code.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Optional
+
+__all__ = [
+    "StreamError",
+    "ErrorInfo",
+    "ERROR_CODES",
+    "REST_ERROR_CODES",
+    "error_info",
+    "is_terminal",
+]
+
+
+class StreamError(Exception):
+    """
+    Every failure this SDK reports.
+
+    ``code`` is the machine-readable code, e.g. ``"capacity-exhausted"``:
+    ``"network"`` if the request never landed, ``"http-<status>"`` if the reply
+    named none, ``"redirected"`` if the server answered a key-carrying request
+    with a redirect. A newer controller may send a code this release does not
+    know; it is passed through unchanged, so switch on the code, never on the
+    message.
+    """
+
+    def __init__(self, code: str, status: int, message: str, retryable: bool = False) -> None:
+        super().__init__(message)
+        #: Machine-readable code, from the registry or the server.
+        self.code = code
+        #: HTTP status, or 0 when the request never reached the server.
+        self.status = status
+        #: What happened, in words. Never contains the API key, so it is safe to log.
+        self.message = message
+        #: True when trying again later could plausibly succeed.
+        self.retryable = retryable
+
+    def __str__(self) -> str:
+        return self.message
+
+    def __repr__(self) -> str:
+        return "StreamError(%r, %r, %r, retryable=%r)" % (self.code, self.status, self.message, self.retryable)
+
+    @property
+    def is_capacity_exhausted(self) -> bool:
+        """The fleet is full. This is the one to alert on: it is about capacity, not correctness."""
+        return self.code in ("capacity-exhausted", "no-nodes")
+
+    @property
+    def is_quota(self) -> bool:
+        """You are at your own concurrent-room limit; rooms are leaking or the quota is too low."""
+        return self.code == "room-quota" or self.status == 429
+
+    @property
+    def is_out_of_minutes(self) -> bool:
+        """
+        The account cannot use more right now: out of minutes, or a daily or
+        monthly usage limit reached. Anything live is warned and then ended.
+        """
+        return self.status == 402 or self.code in (
+            "quota-exhausted",
+            "daily-limit-reached",
+            "monthly-limit-reached",
+        )
+
+    @property
+    def is_broadcast_disabled(self) -> bool:
+        """Broadcast is not switched on for this deployment. Not something a retry fixes."""
+        return self.code == "broadcast-disabled"
+
+    @property
+    def is_billing_unavailable(self) -> bool:
+        """
+        The project is billed from its wallet and no price list is active yet,
+        or the controller has no wallet billing. An operator fixes this, not a
+        retry -- so, although it is a 503, it is never retried.
+        """
+        return self.code == "billing-unavailable"
+
+    @property
+    def is_not_found(self) -> bool:
+        """The room is gone, or was never yours. Rooms are tenant-scoped, so these are the same answer."""
+        return self.status == 404
+
+
+@dataclass(frozen=True)
+class ErrorInfo:
+    """What the shared registry says about one code."""
+
+    #: ``"server"`` (the controller or a media node, passed through unchanged) or ``"sdk"`` (raised here).
+    origin: str
+    #: A join or reconnect refused with it must not be retried. Client SDKs act on
+    #: this; it is kept so the registries agree.
+    terminal: bool
+    #: Trying the same call again later can succeed.
+    retryable: bool
+
+
+# Every error code a VoltKit RTC SDK can report, in the order of the shared
+# registry (docs/sdk-contract.json in the VoltKit RTC repository), which also
+# says what each one means. A copy rather than a read of that file: the
+# package ships without the docs, and a repository check fails when the two
+# drift apart (`scripts/test/sdk-contract-sdks.mjs` reads the lines between
+# the braces: keep one code per line).
+#
+# Most of these only ever reach a client on its socket. REST_ERROR_CODES are
+# the ones a call from this SDK can fail with.
+_REGISTRY: dict[str, ErrorInfo] = {
+    "bad-json": ErrorInfo("server", terminal=False, retryable=False),
+    "bad-params": ErrorInfo("server", terminal=False, retryable=False),
+    "unknown-method": ErrorInfo("server", terminal=False, retryable=False),
+    "too-many-requests": ErrorInfo("server", terminal=False, retryable=True),
+    "not-joined": ErrorInfo("server", terminal=False, retryable=False),
+    "already-joined": ErrorInfo("server", terminal=False, retryable=False),
+    "internal": ErrorInfo("server", terminal=False, retryable=True),
+    "node-error": ErrorInfo("server", terminal=False, retryable=True),
+    "no-token": ErrorInfo("server", terminal=True, retryable=False),
+    "bad-token": ErrorInfo("server", terminal=True, retryable=False),
+    "wrong-tenant": ErrorInfo("server", terminal=True, retryable=False),
+    "token-mismatch": ErrorInfo("server", terminal=False, retryable=False),
+    "no-room": ErrorInfo("server", terminal=True, retryable=False),
+    "room-ended": ErrorInfo("server", terminal=True, retryable=False),
+    "kicked": ErrorInfo("server", terminal=True, retryable=False),
+    "no-node": ErrorInfo("server", terminal=False, retryable=True),
+    "no-capacity": ErrorInfo("server", terminal=False, retryable=True),
+    "stage-full": ErrorInfo("server", terminal=False, retryable=True),
+    "participant-quota": ErrorInfo("server", terminal=False, retryable=True),
+    "viewer-quota": ErrorInfo("server", terminal=False, retryable=True),
+    "quota-exhausted": ErrorInfo("server", terminal=True, retryable=False),
+    "daily-limit-reached": ErrorInfo("server", terminal=True, retryable=False),
+    "monthly-limit-reached": ErrorInfo("server", terminal=True, retryable=False),
+    "tenant-suspended": ErrorInfo("server", terminal=True, retryable=False),
+    "billing-unavailable": ErrorInfo("server", terminal=True, retryable=False),
+    "forbidden": ErrorInfo("server", terminal=True, retryable=False),
+    "not-in-room": ErrorInfo("server", terminal=False, retryable=False),
+    "no-participant": ErrorInfo("server", terminal=False, retryable=False),
+    "bad-transport": ErrorInfo("server", terminal=False, retryable=False),
+    "no-transport": ErrorInfo("server", terminal=False, retryable=False),
+    "no-producer": ErrorInfo("server", terminal=False, retryable=False),
+    "no-consumer": ErrorInfo("server", terminal=False, retryable=False),
+    "cannot-consume": ErrorInfo("server", terminal=False, retryable=False),
+    "consumer-cap": ErrorInfo("server", terminal=False, retryable=True),
+    "producer-cap": ErrorInfo("server", terminal=False, retryable=True),
+    "room-cap": ErrorInfo("server", terminal=False, retryable=True),
+    "draining": ErrorInfo("server", terminal=False, retryable=True),
+    "bad-request": ErrorInfo("server", terminal=False, retryable=False),
+    "source-already-published": ErrorInfo("server", terminal=False, retryable=False),
+    "force-muted": ErrorInfo("server", terminal=False, retryable=False),
+    "media-disabled": ErrorInfo("server", terminal=False, retryable=False),
+    "frame-rate-not-allowed": ErrorInfo("server", terminal=False, retryable=False),
+    "video-quality-not-allowed": ErrorInfo("server", terminal=False, retryable=False),
+    "audio-quality-not-allowed": ErrorInfo("server", terminal=False, retryable=False),
+    "video-not-allowed": ErrorInfo("server", terminal=False, retryable=False),
+    "audio-not-allowed": ErrorInfo("server", terminal=False, retryable=False),
+    "video-subscription-limit": ErrorInfo("server", terminal=False, retryable=False),
+    "slot-taken": ErrorInfo("server", terminal=False, retryable=False),
+    "slot-blocked": ErrorInfo("server", terminal=False, retryable=False),
+    "slot-occupied": ErrorInfo("server", terminal=False, retryable=False),
+    "chat-muted": ErrorInfo("server", terminal=False, retryable=False),
+    "rate-limited": ErrorInfo("server", terminal=False, retryable=True),
+    "no-message": ErrorInfo("server", terminal=False, retryable=False),
+    "chat-unavailable": ErrorInfo("server", terminal=False, retryable=False),
+    "closed": ErrorInfo("server", terminal=False, retryable=True),
+    "unauthorized": ErrorInfo("server", terminal=False, retryable=False),
+    "bad-signature": ErrorInfo("server", terminal=False, retryable=False),
+    "operator-only": ErrorInfo("server", terminal=False, retryable=False),
+    "bad-role": ErrorInfo("server", terminal=False, retryable=False),
+    "room-exists": ErrorInfo("server", terminal=False, retryable=False),
+    "room-quota": ErrorInfo("server", terminal=False, retryable=True),
+    "no-nodes": ErrorInfo("server", terminal=False, retryable=True),
+    "capacity-exhausted": ErrorInfo("server", terminal=False, retryable=True),
+    "unavailable": ErrorInfo("server", terminal=False, retryable=True),
+    "not-found": ErrorInfo("server", terminal=False, retryable=False),
+    "broadcast-disabled": ErrorInfo("server", terminal=False, retryable=False),
+    "chat-disabled": ErrorInfo("server", terminal=False, retryable=False),
+    "no-stream": ErrorInfo("server", terminal=False, retryable=False),
+    "stream-exists": ErrorInfo("server", terminal=False, retryable=False),
+    "stream-quota": ErrorInfo("server", terminal=False, retryable=True),
+    "network": ErrorInfo("sdk", terminal=False, retryable=True),
+    "rates-unconfigured": ErrorInfo("sdk", terminal=False, retryable=False),
+    "redirected": ErrorInfo("sdk", terminal=False, retryable=False),
+    "not-connected": ErrorInfo("sdk", terminal=False, retryable=True),
+    "timeout": ErrorInfo("sdk", terminal=False, retryable=True),
+    "connect-failed": ErrorInfo("sdk", terminal=False, retryable=True),
+    "replaced": ErrorInfo("sdk", terminal=True, retryable=False),
+    "reconnect-gave-up": ErrorInfo("sdk", terminal=True, retryable=False),
+    "devices-gone": ErrorInfo("sdk", terminal=False, retryable=False),
+    "unpublished": ErrorInfo("sdk", terminal=False, retryable=False),
+    "frame-rate-fallback": ErrorInfo("sdk", terminal=False, retryable=False),
+    "codec-fallback": ErrorInfo("sdk", terminal=False, retryable=False),
+    "quality-unavailable": ErrorInfo("sdk", terminal=False, retryable=False),
+    "screen-share-active": ErrorInfo("sdk", terminal=False, retryable=False),
+    "screen-share-unsupported": ErrorInfo("sdk", terminal=False, retryable=False),
+    "screen-share-no-video": ErrorInfo("sdk", terminal=False, retryable=False),
+    "disconnected": ErrorInfo("sdk", terminal=False, retryable=True),
+    "produce-failed": ErrorInfo("sdk", terminal=False, retryable=True),
+    "consume-failed": ErrorInfo("sdk", terminal=False, retryable=True),
+    "media-unavailable": ErrorInfo("sdk", terminal=False, retryable=False),
+    "music-unavailable": ErrorInfo("sdk", terminal=False, retryable=False),
+    "no-camera": ErrorInfo("sdk", terminal=False, retryable=False),
+    "camera-failed": ErrorInfo("sdk", terminal=False, retryable=True),
+    "unknown-producer": ErrorInfo("sdk", terminal=False, retryable=False),
+    "screen-share-denied": ErrorInfo("sdk", terminal=False, retryable=True),
+    "screen-share-service-required": ErrorInfo("sdk", terminal=False, retryable=False),
+    "screen-share-source-required": ErrorInfo("sdk", terminal=False, retryable=False),
+    "screen-share-setup-required": ErrorInfo("sdk", terminal=False, retryable=False),
+    "screen-share-start-timeout": ErrorInfo("sdk", terminal=False, retryable=True),
+    "screen-share-ended": ErrorInfo("sdk", terminal=False, retryable=True),
+    "screen-share-failed": ErrorInfo("sdk", terminal=False, retryable=True),
+    "screen-share-size-unavailable": ErrorInfo("sdk", terminal=False, retryable=True),
+    "screen-audio-unavailable": ErrorInfo("sdk", terminal=False, retryable=False),
+    "screen-stop-failed": ErrorInfo("sdk", terminal=False, retryable=False),
+    "degradation-preference-failed": ErrorInfo("sdk", terminal=False, retryable=False),
+}
+ERROR_CODES: Mapping[str, ErrorInfo] = MappingProxyType(_REGISTRY)
+
+# The registry codes whose surfaces include the tenant REST API: what a call
+# from this SDK can fail with, besides `http-<status>` for a reply that names
+# no code. get_rates also passes the website API's own codes through.
+REST_ERROR_CODES: tuple[str, ...] = (
+    "internal",
+    "no-room",
+    "viewer-quota",
+    "quota-exhausted",
+    "daily-limit-reached",
+    "monthly-limit-reached",
+    "tenant-suspended",
+    "billing-unavailable",
+    "bad-request",
+    "rate-limited",
+    "no-message",
+    "unauthorized",
+    "bad-signature",
+    "operator-only",
+    "bad-role",
+    "room-exists",
+    "room-quota",
+    "no-nodes",
+    "capacity-exhausted",
+    "unavailable",
+    "not-found",
+    "broadcast-disabled",
+    "chat-disabled",
+    "no-stream",
+    "stream-exists",
+    "stream-quota",
+    "network",
+    "rates-unconfigured",
+    "redirected",
+)
+
+
+def error_info(code: str) -> Optional[ErrorInfo]:
+    """What the registry says about ``code``; None for one this release does not know."""
+    return ERROR_CODES.get(code)
+
+
+def is_terminal(code: str) -> bool:
+    """
+    Whether a join refused with ``code`` must not be retried. Unknown codes are
+    never terminal: a newer server's code must not stop a reconnect that could
+    succeed.
+    """
+    info = ERROR_CODES.get(code)
+    return info.terminal if info is not None else False

voltkit_rtc/server/transport.py

@@ -0,0 +1,208 @@
+"""
+How bytes reach the controller: a Transport the client calls once per attempt,
+and the default one on http.client.
+
+The default is standard library only and makes one connection per call, which
+keeps the client safe to share between threads without a pool and a lock. Pass
+your own Transport for a proxy, instrumentation, an httpx client, or a test
+double; the client's retries, redaction and parsing sit above it and do not
+change.
+"""
+
+from __future__ import annotations
+
+import base64
+import http.client
+import socket
+import ssl
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Optional, Protocol
+from urllib.parse import unquote, urljoin, urlsplit
+
+__all__ = [
+    "HttpClientTransport",
+    "Transport",
+    "TransportError",
+    "TransportRequest",
+    "TransportResponse",
+]
+
+
+@dataclass(frozen=True)
+class TransportRequest:
+    """One HTTP exchange, as the client asks for it."""
+
+    method: str
+    #: The URL as the client was configured, credentials included.
+    url: str
+    headers: Mapping[str, str]
+    #: The JSON body, already encoded; None when the request has none.
+    body: Optional[bytes]
+    #: Seconds for the whole exchange, from connecting to the last byte of the body.
+    timeout: float
+    #: True only for the public rates, which carry no credential. A request
+    #: with the API key must get the 3xx back as the reply, never followed.
+    follow_redirects: bool
+
+
+@dataclass(frozen=True)
+class TransportResponse:
+    status: int
+    headers: Mapping[str, str]
+    body: bytes
+
+
+class TransportError(Exception):
+    """
+    Nothing usable came back. A transport raises this (or an OSError, or an
+    http.client.HTTPException) when the request failed in transit; a TimeoutError
+    when its deadline passed. The client reports each as `network`, retryable,
+    with the transport's words redacted, and "timed out after" for the deadline.
+    """
+
+
+class Transport(Protocol):
+    def send(self, request: TransportRequest) -> TransportResponse:
+        """
+        Perform one exchange and return the reply, whatever its status.
+
+        Must honour `request.timeout` as a total deadline, and must not follow
+        a redirect unless `request.follow_redirects` is set.
+        """
+        ...
+
+
+_REDIRECTS = (301, 302, 303, 307, 308)
+_CHUNK = 65536
+
+
+class HttpClientTransport:
+    """
+    The default transport: http.client, one connection per exchange.
+
+    `timeout` is one deadline for the whole exchange, checked before the
+    connect, before the send, and before each read of the body, so a reply
+    whose headers arrive and whose body then stalls fails like a server that
+    never answered. http.client never follows a redirect, so a request with
+    the key gets its 3xx back; the key-less rates request follows up to
+    `max_redirects` of them. Credentials in the URL (`https://user:pass@host`)
+    are sent as Basic authentication, as curl and browsers do.
+    """
+
+    def __init__(self, *, ssl_context: Optional[ssl.SSLContext] = None, max_redirects: int = 5) -> None:
+        self._ssl_context = ssl_context
+        self._max_redirects = max_redirects
+
+    def send(self, request: TransportRequest) -> TransportResponse:
+        deadline = time.monotonic() + request.timeout
+        method, url, body = request.method, request.url, request.body
+        headers = dict(request.headers)
+        hops = 0
+        while True:
+            response = _exchange(method, url, headers, body, deadline, self._ssl_context)
+            if not request.follow_redirects or response.status not in _REDIRECTS or hops >= self._max_redirects:
+                return response
+            location = _header(response.headers, "location")
+            if not location:
+                return response
+            hops += 1
+            url = urljoin(url, location)
+            # As fetch and browsers do: a 303, and a 301 or 302 answering a
+            # POST, continue as a GET without the body.
+            if response.status == 303 or (response.status in (301, 302) and method == "POST"):
+                method, body = "GET", None
+                headers = {name: value for name, value in headers.items() if name.lower() != "content-type"}
+
+
+def _header(headers: Mapping[str, str], name: str) -> Optional[str]:
+    for key, value in headers.items():
+        if key.lower() == name:
+            return value
+    return None
+
+
+def _left(deadline: float) -> float:
+    left = deadline - time.monotonic()
+    if left <= 0:
+        raise TimeoutError("the deadline passed")
+    return left
+
+
+def _exchange(
+    method: str,
+    url: str,
+    headers: Mapping[str, str],
+    body: Optional[bytes],
+    deadline: float,
+    ssl_context: Optional[ssl.SSLContext],
+) -> TransportResponse:
+    parts = urlsplit(url)
+    scheme = parts.scheme.lower()
+    if scheme not in ("http", "https"):
+        raise TransportError("the URL's scheme is not http or https")
+    host = parts.hostname
+    if not host:
+        raise TransportError("the URL names no host")
+    try:
+        port = parts.port
+    except ValueError:
+        raise TransportError("the URL's port is not a number") from None
+    if port is None:
+        port = 443 if scheme == "https" else 80
+    if ":" in host:
+        host = "[%s]" % host
+    path = parts.path or "/"
+    if parts.query:
+        path = "%s?%s" % (path, parts.query)
+
+    conn: http.client.HTTPConnection
+    if scheme == "https":
+        context = ssl_context if ssl_context is not None else ssl.create_default_context()
+        conn = http.client.HTTPSConnection(host, port, timeout=_left(deadline), context=context)
+    else:
+        conn = http.client.HTTPConnection(host, port, timeout=_left(deadline))
+    try:
+        try:
+            conn.connect()
+            sock = conn.sock
+            sock.settimeout(_left(deadline))
+            conn.putrequest(method, path)
+            for name, value in headers.items():
+                conn.putheader(name, value)
+            if parts.username is not None and _header(headers, "authorization") is None:
+                userinfo = "%s:%s" % (unquote(parts.username), unquote(parts.password or ""))
+                credential = base64.b64encode(userinfo.encode("utf-8")).decode("ascii")
+                conn.putheader("Authorization", "Basic " + credential)
+            if body is not None:
+                conn.putheader("Content-Length", str(len(body)))
+            conn.endheaders(body)
+            sock.settimeout(_left(deadline))
+            response = conn.getresponse()
+            chunks: list[bytes] = []
+            while not response.isclosed():
+                # One receive per read1, with the socket's timeout re-armed to
+                # what is left of the deadline before each: read(n) would wait
+                # for n bytes however slowly they drip, and the deadline is
+                # checked only between reads. http.client closes the body's
+                # file once the last byte is in, and the socket with it when
+                # the server said Connection: close.
+                sock.settimeout(_left(deadline))
+                chunk = response.read1(_CHUNK)
+                if not chunk:
+                    break
+                chunks.append(chunk)
+            if response.length:
+                # The server announced more than it sent: read1 returns the
+                # short body quietly, as read(n) does, where read() would raise.
+                raise http.client.IncompleteRead(b"".join(chunks), response.length)
+            out: dict[str, str] = {}
+            for name, value in response.getheaders():
+                out.setdefault(name, value)
+            return TransportResponse(response.status, out, b"".join(chunks))
+        except socket.timeout as err:
+            # Its own class on Python 3.9; an alias of TimeoutError since 3.10.
+            raise TimeoutError(str(err) or "timed out") from None
+    finally:
+        conn.close()