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

voltkit_rtc/server/types.py

@@ -0,0 +1,448 @@
+"""
+The shapes of what the calls return, as the wire sends them: plain dicts and
+lists with camelCase keys. These TypedDicts are for editors and type checkers;
+nothing is converted, and a field a newer controller adds comes through as is.
+
+Money is credit units (cu): 1 credit = 6,000,000 cu. Every cu amount is a
+decimal string, never a number: a JSON number is a float, and a float rounds a
+large balance without telling you. Do arithmetic with int(amount).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Optional, TypedDict
+
+__all__ = [
+    "Allowance",
+    "BroadcastStream",
+    "BroadcastStreamWithPublish",
+    "BurnView",
+    "ChatInfo",
+    "ChatMessage",
+    "ChatToken",
+    "DailyUsage",
+    "LegacyFunds",
+    "Participant",
+    "PlaybackPolicy",
+    "PlaybackUrls",
+    "ProjectBalance",
+    "PublishGrant",
+    "Role",
+    "Room",
+    "RoomList",
+    "RoomToken",
+    "RoomView",
+    "RoomWithHostToken",
+    "RtcConversion",
+    "RtcMode",
+    "RtcRates",
+    "RtcSurcharge",
+    "RtcTierRate",
+    "RtcUnit",
+    "StreamAction",
+    "StreamEvent",
+    "StreamToken",
+    "Usage",
+    "UsageSummary",
+    "WalletFunds",
+    "WalletLowState",
+    "WalletScopeAmount",
+]
+
+Role = Literal["host", "cohost", "moderator", "viewer"]
+PlaybackPolicy = Literal["public", "token"]
+StreamAction = Literal["play", "publish"]
+
+
+# --- rooms --------------------------------------------------------------------
+
+
+class _RoomRequired(TypedDict):
+    roomId: str
+    tenantId: str
+    originNode: str
+    state: str
+    hostIdentity: str
+    #: Unix milliseconds.
+    createdAt: int
+    nodes: list[str]
+
+
+class Room(_RoomRequired, total=False):
+    participants: int
+    demo: bool
+    metadata: Any
+
+
+class _RoomWithHostTokenRequired(_RoomRequired):
+    hostToken: str
+    wsUrl: str
+    #: Unix seconds.
+    expiresAt: int
+    #: True when the room already existed and was returned rather than created.
+    existed: bool
+
+
+class RoomWithHostToken(_RoomWithHostTokenRequired, total=False):
+    participants: int
+    demo: bool
+    metadata: Any
+
+
+class RoomToken(TypedDict):
+    token: str
+    wsUrl: str
+    role: Role
+    identity: str
+    roomId: str
+    #: Unix seconds.
+    expiresAt: int
+
+
+class _ParticipantRequired(TypedDict):
+    identity: str
+    role: Role
+    nodeId: str
+    handRaised: bool
+    muted: bool
+
+
+class Participant(_ParticipantRequired, total=False):
+    handMetadata: Any
+    kicked: bool
+    #: A moderator has switched this participant's camera off.
+    videoBlocked: bool
+    #: When they joined, in unix milliseconds.
+    joinedAt: int
+    metadata: Any
+
+
+class RoomView(TypedDict, total=False):
+    room: Room
+    participants: list[Participant]
+    producers: list[dict[str, Any]]
+
+
+class RoomList(TypedDict):
+    rooms: list[Room]
+
+
+# --- chat ---------------------------------------------------------------------
+
+
+class ChatToken(TypedDict):
+    token: str
+    #: Where a chat-only client connects. Ends in /ws/chat.
+    wsUrl: str
+    role: Role
+    identity: str
+    channel: str
+    expiresAt: int
+
+
+class ChatInfo(TypedDict):
+    channel: str
+    members: int
+
+
+class _ChatMessageRequired(TypedDict):
+    #: Monotonic within a channel: the oldest id you hold is a paging cursor.
+    id: str
+    channel: str
+    #: Who it is from; "system" for a backend message that named nobody.
+    from_: str  # noqa: F841 - the wire key is "from"; see ChatMessage below.
+    type: str
+    #: Unix milliseconds.
+    ts: int
+
+
+# "from" is a keyword, so the wire key cannot be a class attribute: this is the
+# functional form, with the same fields as above plus the optional ones.
+ChatMessage = TypedDict(
+    "ChatMessage",
+    {
+        "id": str,
+        "channel": str,
+        "from": str,
+        "to": str,
+        "type": str,
+        "text": str,
+        "metadata": Any,
+        "clientMsgId": str,
+        "ts": int,
+    },
+    total=False,
+)
+
+
+# --- broadcast ----------------------------------------------------------------
+
+
+class PlaybackUrls(TypedDict, total=False):
+    llhls: str
+    webrtc: str
+    token: str
+    expiresAt: int
+
+
+class PublishGrant(TypedDict):
+    #: Complete: hand it to the encoder as it is. It carries the token.
+    whipUrl: str
+    token: str
+    expiresAt: int
+
+
+class _BroadcastStreamRequired(TypedDict):
+    streamId: str
+    tenantId: str
+    #: The name the media server knows the stream by. Random, so a playback
+    #: URL cannot be derived from a stream id.
+    streamKey: str
+    state: Literal["idle", "live"]
+    playback: PlaybackPolicy
+    createdAt: int
+    #: Playback sessions the media server serves itself; an audience behind a CDN is not counted.
+    viewers: int
+    peakViewers: int
+    playbackUrls: PlaybackUrls
+
+
+class BroadcastStream(_BroadcastStreamRequired, total=False):
+    startedAt: int
+    endedAt: int
+    metadata: Any
+
+
+class _BroadcastStreamWithPublishRequired(_BroadcastStreamRequired):
+    #: Only ever returned by create_stream.
+    publish: PublishGrant
+
+
+class BroadcastStreamWithPublish(_BroadcastStreamWithPublishRequired, total=False):
+    startedAt: int
+    endedAt: int
+    metadata: Any
+
+
+class _StreamTokenRequired(TypedDict):
+    streamId: str
+    action: StreamAction
+    token: str
+    expiresAt: int
+
+
+class StreamToken(_StreamTokenRequired, total=False):
+    #: Present when action is "publish".
+    whipUrl: str
+    #: Present when action is "play".
+    llhls: str
+    webrtc: str
+
+
+# --- usage --------------------------------------------------------------------
+
+
+class _UsageRequired(TypedDict):
+    participantSeconds: int
+    publisherSeconds: int
+    roomSeconds: int
+    roomsCreated: int
+    peakParticipants: int
+    chatMessages: int
+    chatConnectionSeconds: int
+    broadcastSeconds: int
+    broadcastViewerSeconds: int
+    streamsStarted: int
+
+
+class Usage(_UsageRequired, total=False):
+    #: Everything that counts against an allowance: room plus broadcast seconds.
+    billableSeconds: int
+    #: The part of billableSeconds a free allowance covered.
+    freeSeconds: int
+
+
+class DailyUsage(Usage, total=False):
+    #: UTC day, YYYY-MM-DD.
+    day: str
+
+
+class Allowance(TypedDict, total=False):
+    plan: Literal["metered", "unlimited"]
+    freeDailyMinutes: int
+    freeMonthlyMinutes: int
+    dailyCapMinutes: int
+    monthlyCapMinutes: int
+    usedTodaySeconds: int
+    usedMonthSeconds: int
+    freeUsedTodaySeconds: int
+    freeUsedMonthSeconds: int
+    freeRemainingSeconds: int
+    paidRemainingSeconds: int
+    remainingSeconds: int
+    #: Why the account cannot be used right now, if it cannot.
+    blocked: str
+
+
+class _UsageSummaryRequired(TypedDict):
+    tenantId: str
+    plan: Literal["metered", "unlimited"]
+    status: Literal["active", "suspended"]
+    minutesLimit: int
+    usedMinutes: int
+    #: -1 on the unlimited plan.
+    minutesRemaining: int
+    today: Usage
+    month: Usage
+    lifetime: Usage
+
+
+class UsageSummary(_UsageSummaryRequired, total=False):
+    sharedUsedMinutes: int
+    allowance: Allowance
+
+
+# --- billing ------------------------------------------------------------------
+
+
+class LegacyFunds(TypedDict):
+    #: A plan whose own minutes never run out; ownSeconds and totalSeconds are then -1.
+    unlimited: bool
+    freeSeconds: int
+    ownSeconds: int
+    sharedSeconds: int
+    totalSeconds: int
+
+
+class WalletScopeAmount(TypedDict):
+    paidCu: str
+    promoCu: str
+
+
+class WalletFunds(TypedDict):
+    #: In the order they are spent: project:<tenantId>, product:rtc, unallocated.
+    spendOrder: list[str]
+    scopes: dict[str, WalletScopeAmount]
+    paidCu: str
+    promoCu: str
+    #: paidCu + promoCu: everything this project may spend from the wallet now.
+    availableCu: str
+    #: availableCu in credits, at most four decimals, rounded down. For display only.
+    availableCredits: str
+
+
+class BurnView(TypedDict):
+    liveParticipants: int
+    projectCuPerSecond: str
+    walletCuPerSecond: str
+
+
+class WalletLowState(TypedDict):
+    active: bool
+    graceSeconds: int
+
+
+class ProjectBalance(TypedDict):
+    tenantId: str
+    billingMode: Literal["legacy", "wallet"]
+    #: Whether a newcomer would be admitted now.
+    canJoin: bool
+    #: When canJoin is false, the code a join or a token mint is refused with.
+    blocked: Optional[str]
+    legacy: LegacyFunds
+    #: None unless the project is billed from its wallet.
+    wallet: Optional[WalletFunds]
+    burn: BurnView
+    #: How long the funds last at the current burn, in seconds; -1 when nothing limits it.
+    remainingSeconds: int
+    walletLow: WalletLowState
+    pricingVersion: Optional[int]
+    #: Unix milliseconds.
+    updatedAt: int
+
+
+# --- rates --------------------------------------------------------------------
+
+
+class RtcUnit(TypedDict):
+    price: str
+    rate: str
+    cuPerCredit: str
+
+
+class RtcTierRate(TypedDict):
+    id: str
+    rank: int
+    label: str
+    media: str
+    #: Credits per 1,000 participant-minutes, e.g. "99.00".
+    credits: str
+    #: The same price as an integer: cu per participant-second, e.g. "9900".
+    cuPerParticipantSecond: str
+    base: str
+    surcharge: Optional[str]
+    available: bool
+
+
+class RtcSurcharge(TypedDict):
+    tier: str
+    height: int
+    fps: int
+    credits: str
+
+
+class RtcMode(TypedDict, total=False):
+    profileId: str
+    label: str
+    tier: str
+    tierLabel: str
+    enabled: bool
+    codecs: list[str]
+    receiveKbps: dict[str, int]
+    kind: Literal["audio", "video"]
+    channels: int
+    width: int
+    height: int
+    fps: int
+    layers: int
+
+
+class RtcConversion(TypedDict):
+    creditsPerRupee: str
+    numerator: str
+    denominator: str
+    inrPerCredit: str
+    version: Optional[int]
+    effectiveAt: Optional[str]
+    source: str
+
+
+class RtcRates(TypedDict):
+    version: int
+    kind: Literal["standard", "contract"]
+    effectiveAt: Optional[str]
+    unit: RtcUnit
+    tiers: list[RtcTierRate]
+    surcharges: list[RtcSurcharge]
+    idleTier: str
+    modes: list[RtcMode]
+    conversion: RtcConversion
+    notes: list[str]
+
+
+# --- webhooks -----------------------------------------------------------------
+
+
+class _StreamEventRequired(TypedDict):
+    id: str
+    type: str
+    tenantId: str
+    #: Unix milliseconds.
+    createdAt: int
+
+
+class StreamEvent(_StreamEventRequired, total=False):
+    """One delivery. `data` varies by `type`: https://voltkit.in/docs/webhooks."""
+
+    roomId: str
+    data: dict[str, Any]

voltkit_rtc/server/webhooks.py

@@ -0,0 +1,184 @@
+"""
+Verified webhooks: the part of an integration that fails silently.
+
+The controller signs every delivery as ``X-Stream-Signature:
+t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">``, with one ``v1``
+per secret during a rotation's overlap. The timestamp is inside the signed
+payload, so a captured request cannot be replayed later against a receiver
+that checks it; signing the body alone would leave that door open.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import math
+import re
+import time
+from collections.abc import Sequence
+from typing import Optional, Union, cast
+
+from .errors import StreamError
+from .types import StreamEvent
+
+__all__ = ["DEFAULT_TOLERANCE_SECONDS", "MAX_HEADER_LENGTH", "parse_webhook", "verify_webhook"]
+
+#: The raw request body: bytes as received, or a str the framework decoded as UTF-8.
+RawBody = Union[bytes, bytearray, memoryview, str]
+#: The signature header as a framework hands it over: the string, a list of them, or nothing.
+SignatureHeader = Union[str, Sequence[str], None]
+
+#: How far out of date a timestamp may be, in seconds, when nothing else is said.
+DEFAULT_TOLERANCE_SECONDS = 300
+#: A header longer than this is refused before it is read.
+MAX_HEADER_LENGTH = 4096
+
+_TIMESTAMP = re.compile(r"[0-9]{1,15}")
+_SIGNATURE = re.compile(r"[0-9a-f]{64}")
+
+
+def verify_webhook(
+    raw_body: RawBody,
+    signature_header: SignatureHeader,
+    secrets: Union[str, Sequence[str]],
+    *,
+    tolerance_seconds: Optional[float] = DEFAULT_TOLERANCE_SECONDS,
+    now: Optional[float] = None,
+) -> bool:
+    """
+    Whether a delivery's signature verifies.
+
+    ``raw_body`` must be the bytes as received (Flask ``request.get_data()``,
+    FastAPI ``await request.body()``, Django ``request.body``). A parsed
+    object, or JSON that has been through ``json.loads`` and back, changes the
+    bytes and no signature could ever match, so that is a TypeError rather
+    than a False that looks like an attack. ``secrets`` may be a list: during a
+    rotation, give the old and the new secret and a delivery signed with
+    either verifies. ``tolerance_seconds`` (default 300) is how far from now,
+    in either direction, the timestamp may be; ``now`` replaces the clock, for
+    tests.
+    """
+    body = _raw_bytes(raw_body)
+    keys = _secret_list(secrets)
+    tolerance = _check_tolerance(tolerance_seconds)
+
+    parsed = _parse_header(signature_header)
+    if parsed is None:
+        return False
+    timestamp, signatures = parsed
+
+    moment = time.time() if now is None else float(now)
+    if abs(moment - int(timestamp)) > tolerance:
+        return False
+
+    # Every secret against every signature, each compared in constant time.
+    # Both lists are short (two at most in practice), and nothing returns
+    # early on a match.
+    ok = False
+    for key in keys:
+        expected = hmac.new(key.encode("utf-8"), timestamp.encode("ascii") + b"." + body, hashlib.sha256)
+        digest = expected.hexdigest()
+        for signature in signatures:
+            if hmac.compare_digest(digest, signature):
+                ok = True
+    return ok
+
+
+def parse_webhook(
+    raw_body: RawBody,
+    signature_header: SignatureHeader,
+    secrets: Union[str, Sequence[str]],
+    *,
+    tolerance_seconds: Optional[float] = DEFAULT_TOLERANCE_SECONDS,
+    now: Optional[float] = None,
+) -> StreamEvent:
+    """
+    Verify and decode in one step. Raises ``StreamError("bad-signature")``
+    (status 401) rather than returning None, so a handler cannot forget to
+    check. The event is ``{"id", "type", "tenantId", "roomId"?, "createdAt",
+    "data"?}``; ``data`` varies by ``type``.
+    """
+    if not verify_webhook(raw_body, signature_header, secrets, tolerance_seconds=tolerance_seconds, now=now):
+        raise StreamError("bad-signature", 401, "webhook signature did not verify", False)
+    return cast(StreamEvent, json.loads(_raw_bytes(raw_body).decode("utf-8")))
+
+
+def _raw_bytes(raw_body: object) -> bytes:
+    if isinstance(raw_body, str):
+        return raw_body.encode("utf-8")
+    if isinstance(raw_body, (bytes, bytearray, memoryview)):
+        return bytes(raw_body)
+    raise TypeError(
+        "verify_webhook needs the RAW request body (bytes or str), not a parsed object. "
+        "Flask: request.get_data(); FastAPI/Starlette: await request.body(); Django: request.body."
+    )
+
+
+def _secret_list(secrets: object) -> list[str]:
+    given: list[object]
+    if isinstance(secrets, str):
+        given = [secrets]
+    elif isinstance(secrets, (list, tuple)):
+        given = list(secrets)
+    else:
+        given = [secrets]
+    kept = [secret for secret in given if isinstance(secret, str) and secret]
+    if not kept:
+        raise TypeError("verify_webhook needs the signing secret")
+    return kept
+
+
+def _check_tolerance(tolerance: object) -> float:
+    """
+    ``tolerance_seconds`` as a number, or an error now. A NaN switched the age
+    check off once, since every comparison with NaN is false, so a captured
+    delivery verified forever; a negative refused every delivery.
+    """
+    if tolerance is None:
+        return float(DEFAULT_TOLERANCE_SECONDS)
+    if isinstance(tolerance, bool) or not isinstance(tolerance, (int, float)):
+        raise TypeError("tolerance_seconds must be a number of 0 or more, got %r" % (tolerance,))
+    value = float(tolerance)
+    if math.isnan(value) or value < 0:
+        raise ValueError("tolerance_seconds must be a number of 0 or more, got %r" % (tolerance,))
+    return value
+
+
+def _parse_header(header: object) -> Optional[tuple[str, list[str]]]:
+    """
+    Split ``t=<ts>,v1=<hex>[,v1=<hex>...]`` into its timestamp and signatures.
+
+    Schemes other than ``v1`` are skipped, so a later scheme can be added
+    beside it without breaking this. Anything malformed, or with more than one
+    timestamp, is refused.
+    """
+    if header is None:
+        value = ""
+    elif isinstance(header, str):
+        value = header
+    elif isinstance(header, (list, tuple)) and all(isinstance(part, str) for part in header):
+        value = ",".join(header)
+    else:
+        return None
+    if len(value) > MAX_HEADER_LENGTH:
+        return None
+    timestamp: Optional[str] = None
+    signatures: list[str] = []
+    for part in value.split(","):
+        item = part.strip()
+        eq = item.find("=")
+        if eq <= 0:
+            return None
+        key, val = item[:eq], item[eq + 1 :]
+        if key == "t":
+            if timestamp is not None or _TIMESTAMP.fullmatch(val) is None:
+                return None
+            timestamp = val
+        elif key == "v1":
+            if _SIGNATURE.fullmatch(val) is None:
+                return None
+            signatures.append(val)
+    if timestamp is None or not signatures:
+        return None
+    return timestamp, signatures