PyAgoraRTC 0.2.0__py3-none-any.whl

pyagorartc/const.py

@@ -0,0 +1,55 @@
+"""Hosts, protocol constants and timers; the only place a URL, service id or duration is spelled out.
+
+Sources are noted per value: ``sdk`` means observed in Agora's Web SDK 4.24.x, ``shipped``
+means the value the Mammotion or PetKit integration ran with in production.
+"""
+
+from __future__ import annotations
+
+SDK_VERSION = "4.24.3"  # sdk: sent as sdk_version in join_v3
+
+AP_HOSTS: tuple[str, ...] = (  # sdk: primary, then backup
+    "https://webrtc2-ap-web-1.agora.io",
+    "https://webrtc2-ap-web-2.agora.io",
+    "https://webrtc2-ap-web-3.agora.io",
+    "https://webrtc2-ap-web-4.agora.io",
+)
+AP_PATH = "/api/v2/transpond/webrtc"  # sdk
+
+RTM_HOSTS: tuple[str, ...] = ("https://api.agora.io", "https://api.sd-rtn.com")  # shipped (PetKit)
+RTM_PEER_MESSAGES_PATH = "/dev/v2/project/{app_id}/rtm/users/{user_id}/peer_messages"  # shipped (PetKit)
+
+# AP request uris and service ids (docs/protocol.md §1)
+AP_URI_CHOOSE_SERVER = 22
+AP_URI_UPDATE_TICKET = 28
+SERVICE_GATEWAY = 11
+SERVICE_TURN = 26
+DEFAULT_SERVICE_IDS: tuple[int, ...] = (SERVICE_GATEWAY, SERVICE_TURN)
+AP_FLAG_GATEWAY = 4096  # the response block whose scalars (ticket, uid, cid) are primary
+AP_FLAG_TURN = 4194310
+AP_QUERY = "?v=2"  # sdk
+EDGE_DOMAIN_SUFFIX = ".edge.agora.io"  # sdk: wss://<ip-dashed>.edge.agora.io:<port>
+TURN_PORT = 3478  # sdk
+TURNS_PORT = 443  # sdk
+DEFAULT_AREA_CODE = "CN,GLOBAL"  # sdk
+ROLE_HOST = 1  # shipped: AP detail 17, the client role
+
+GATEWAY_TURN_PORT_OFFSET = 30  # sdk: serversFromGateway uses the gateway port + 30
+
+# Timers, in seconds
+AP_TIMEOUT_S = 10.0
+GATEWAY_CONNECT_TIMEOUT_S = 10.0
+JOIN_TIMEOUT_S = 15.0
+GATEWAY_SEND_TIMEOUT_S = 5.0  # bounds the join and leave sends on a stalled socket
+PING_INTERVAL_S = 3.0  # sdk
+RENEW_TOKEN_DEBOUNCE_S = 30.0  # shipped (Mammotion); D8
+KEEPALIVE_INTERVAL_S = 3.0  # shipped (Mammotion 4G FPV); D15
+PEER_REJOIN_DEBOUNCE_S = 2.0  # shipped; D14
+PEER_RECOVER_COOLDOWN_S = 15.0  # shipped
+PEER_RECOVER_MAX_ATTEMPTS = 5  # shipped
+PEER_RECOVER_RESET_S = 600.0  # shipped
+DECLARED_SSRC_TIMEOUT_S = 15.0  # shipped (PetKit): answer without a remote SSRC after this
+RTM_TIMEOUT_S = 10.0
+
+DEFAULT_CLIENT_CODEC = "vp8"  # shipped (Mammotion); PetKit uses h264
+DEFAULT_ORTC_DTLS_ROLE = "server"  # shipped (HA-Luba); D4

pyagorartc/exceptions.py

@@ -0,0 +1,61 @@
+"""The exception hierarchy; nothing else in the package defines an exception type.
+
+Each type names a distinct recovery (``docs/architecture.md`` §2). Messages describe the
+condition; no exception ever carries a token, ticket, credential or key.
+"""
+
+from __future__ import annotations
+
+
+class PyAgoraRTCError(Exception):
+    """Base class for every error raised by this library."""
+
+
+class APError(PyAgoraRTCError):
+    """Edge discovery failed: every access point host was tried and none answered usefully."""
+
+    def __init__(self, message: str, *, status: int | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+class APRejectedError(APError):
+    """The access point answered, but every requested service came back with a non-zero code."""
+
+    def __init__(self, codes: dict[int, int]) -> None:
+        super().__init__(f"access point rejected every service: {codes}")
+        self.codes = codes
+
+
+class SdpError(PyAgoraRTCError):
+    """An SDP offer could not be turned into ORTC, or an answer could not be built from the gateway ORTC."""
+
+
+class GatewayConnectError(PyAgoraRTCError):
+    """The gateway WebSocket could not be opened on any edge."""
+
+
+class JoinRejectedError(PyAgoraRTCError):
+    """The gateway answered the join with a failure result."""
+
+    def __init__(self, code: int | None, message: str) -> None:
+        super().__init__(f"join rejected (code={code}): {message}")
+        self.code = code
+        self.message = message
+
+
+class JoinTimeoutError(PyAgoraRTCError):
+    """The gateway did not answer the join within the configured timeout."""
+
+
+class SessionClosedError(PyAgoraRTCError):
+    """An operation was attempted on a session that has already ended."""
+
+
+class RtmError(PyAgoraRTCError):
+    """An RTM peer message could not be delivered on any endpoint."""
+
+    def __init__(self, message: str, *, status: int | None = None, code: str | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code

pyagorartc/models.py

@@ -0,0 +1,223 @@
+"""Host-neutral value types shared by every layer (D2, D19).
+
+Secrets (tokens, keys, credentials) are redacted in ``repr``; ``fingerprint`` is the only
+form that may reach a log line.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum, IntEnum
+import hashlib
+import re
+from types import MappingProxyType
+from typing import TYPE_CHECKING, overload
+
+from pyagorartc.const import (
+    DEFAULT_AREA_CODE,
+    DEFAULT_CLIENT_CODEC,
+    DEFAULT_ORTC_DTLS_ROLE,
+    GATEWAY_CONNECT_TIMEOUT_S,
+    JOIN_TIMEOUT_S,
+    RENEW_TOKEN_DEBOUNCE_S,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+_FINGERPRINT_CHARS = 12
+_INTEGER_TEXT = re.compile(r"[+-]?[0-9]+")
+
+
+def fingerprint(secret: str) -> str:
+    """A short, non-reversible handle for a secret, safe for log lines."""
+    return hashlib.sha256(secret.encode("utf-8")).hexdigest()[:_FINGERPRINT_CHARS]
+
+
+@overload
+def as_int(value: object) -> int | None: ...
+@overload
+def as_int(value: object, default: int) -> int: ...
+def as_int(value: object, default: int | None = None) -> int | None:
+    """``value`` as a wire integer: an int (not a bool) or ASCII digits with an optional sign, else ``default``.
+
+    The one coercion rule for every wire integer, so the AP and gateway parsers agree on ``"12"`` and ``True``.
+    """
+    if isinstance(value, bool):
+        return default
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str) and _INTEGER_TEXT.fullmatch(text := value.strip()):
+        return int(text)
+    return default
+
+
+@dataclass(frozen=True, kw_only=True, repr=False)
+class ChannelEncryption:
+    """Agora channel encryption parameters; modelled but never sent in the join (D20, Q17).
+
+    ``mode`` is the SDK's name (``aes-256-gcm2``); ``salt`` is the raw bytes, already
+    base64-decoded by the host. Setting it only makes the join log a WARNING.
+    """
+
+    mode: str
+    secret: str
+    salt: bytes | None = None
+
+    def __repr__(self) -> str:
+        return f"ChannelEncryption(mode={self.mode!r}, secret=<redacted>, salt={'<present>' if self.salt else None})"
+
+
+@dataclass(frozen=True, kw_only=True, repr=False)
+class ChannelCredentials:
+    """Everything needed to join one Agora channel, whichever vendor minted it.
+
+    Mapping: Mammotion ``appid/channelName/token/uid/areaCode/license``; PetKit
+    ``AGORA_APP_ID/channel_id/rtc_token/uid``. Token refresh is a callback on the session,
+    so this stays immutable.
+    """
+
+    app_id: str
+    channel_name: str
+    token: str
+    uid: int
+    string_uid: str | None = None
+    area_code: str = DEFAULT_AREA_CODE
+    license: str | None = None
+    encryption: ChannelEncryption | None = None
+
+    def __repr__(self) -> str:
+        return (
+            f"ChannelCredentials(app_id={fingerprint(self.app_id)!s}, channel_name={self.channel_name!r}, "
+            f"token=<{fingerprint(self.token)}>, uid={self.uid!r}, string_uid={self.string_uid!r}, "
+            f"area_code={self.area_code!r}, license={'<present>' if self.license else None}, "
+            f"encryption={self.encryption!r})"
+        )
+
+
+@dataclass(frozen=True, kw_only=True, repr=False)
+class RtmCredentials:
+    """Credentials for Agora RTM peer messages (D18)."""
+
+    app_id: str
+    user_id: str
+    peer_user_id: str
+    token: str
+
+    def __repr__(self) -> str:
+        return (
+            f"RtmCredentials(app_id={fingerprint(self.app_id)}, user_id={self.user_id!r}, "
+            f"peer_user_id={self.peer_user_id!r}, token=<{fingerprint(self.token)}>)"
+        )
+
+
+@dataclass(frozen=True)
+class IceCandidate:
+    """One ICE candidate as a viewer reports it (``candidate:`` line without the ``a=`` prefix)."""
+
+    candidate: str
+    sdp_mid: str | None = None
+    sdp_mline_index: int | None = None
+
+
+@dataclass(frozen=True)
+class EdgeAddress:
+    """One gateway or TURN edge from an access-point response."""
+
+    ip: str
+    port: int
+    username: str | None = None
+    credentials: str | None = None
+    ticket: str | None = None
+    fingerprint: str | None = None
+
+    def __repr__(self) -> str:
+        return (
+            f"EdgeAddress(ip={self.ip!r}, port={self.port!r}, username={self.username!r}, "
+            f"credentials={'<redacted>' if self.credentials else None}, ticket={'<present>' if self.ticket else None}, "
+            f"fingerprint={self.fingerprint!r})"
+        )
+
+
+@dataclass(frozen=True, repr=False)
+class ICEServer:
+    """An ICE server entry in the shape a WebRTC consumer expects (``urls``, ``username``, ``credential``)."""
+
+    urls: list[str]
+    username: str | None = None
+    credential: str | None = None
+
+    def __repr__(self) -> str:
+        return f"ICEServer(urls={self.urls!r}, username={self.username!r}, credential={'<redacted>' if self.credential else None})"
+
+
+class TurnMode(IntEnum):
+    """Which TURN transports ``get_ice_servers`` emits (the SDK's ``new_turn_mode``)."""
+
+    ALL = 1
+    UDP_ONLY = 2
+    TCP_ONLY = 3
+    TLS_ONLY = 4
+
+
+class TurnCredentialStrategy(Enum):
+    """Where TURN username/credential come from (D12)."""
+
+    UID = "uid"  # username = str(uid), credential = derive_password(uid)
+    DETAIL_FIRST = "detail_first"  # AP detail 8/4 when present, else UID
+
+
+class CloseReason(Enum):
+    """Why a session ended; delivered once to ``on_closed`` (D14)."""
+
+    CLOSED_BY_HOST = "closed_by_host"
+    GATEWAY_QUIT = "gateway_quit"
+    P2P_LOST = "p2p_lost"
+    SOCKET_CLOSED = "socket_closed"
+    DEADLINE = "deadline"
+    JOIN_FAILED = "join_failed"
+
+
+@dataclass(frozen=True)
+class RemoteStream:
+    """A publisher's video stream as announced by the gateway (``on_add_video_stream``)."""
+
+    uid: int
+    ssrc: int
+    rtx_ssrc: int | None = None
+    codec: str | None = None
+    payload_type: int | None = None
+    cname: str | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class SessionOptions:
+    """Per-session knobs; defaults preserve the Mammotion behaviour that shipped (architecture §4).
+
+    ``extra_join_attributes`` merges into the join's ``userAttributes`` last; it is stored read-only and left
+    out of the hash, so the options stay hashable. ``end_on_p2p_lost``
+    is off because the Mammotion integration deliberately ignored ``on_p2p_lost`` (D22);
+    PetKit ends the session on it. ``prealloc_pc`` and ``renew_debounce_s`` exist so a host can
+    answer Q10 and Q11 without patching.
+    """
+
+    client_codec: str = DEFAULT_CLIENT_CODEC
+    target_uid: int | None = None
+    send_set_client_role: bool = False
+    ortc_dtls_role: str | None = DEFAULT_ORTC_DTLS_ROLE
+    instant_video: bool = False
+    declare_remote_video_ssrc: bool = False
+    disable_audio: bool = False
+    subscribe_retry_attempts: int = 0
+    subscribe_retry_delay_s: float = 0.0
+    strip_mid_extension: bool = True
+    prealloc_pc: bool = True
+    end_on_p2p_lost: bool = False
+    renew_debounce_s: float = RENEW_TOKEN_DEBOUNCE_S
+    join_timeout_s: float = JOIN_TIMEOUT_S
+    connect_timeout_s: float = GATEWAY_CONNECT_TIMEOUT_S
+    verify_ssl: bool = True
+    extra_join_attributes: Mapping[str, object] = field(default_factory=lambda: MappingProxyType({}), hash=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "extra_join_attributes", MappingProxyType(dict(self.extra_join_attributes)))

pyagorartc/rtm/__init__.py

@@ -0,0 +1,5 @@
+"""Agora RTM peer messages over REST."""
+
+from pyagorartc.rtm.client import DEFAULT_ACCEPTED_CODES, RtmRestClient
+
+__all__ = ["DEFAULT_ACCEPTED_CODES", "RtmRestClient"]

pyagorartc/rtm/client.py

@@ -0,0 +1,170 @@
+"""Agora RTM peer messages over the REST API: request shape, endpoint rotation and ack semantics (D18)."""
+
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+import json
+import logging
+from typing import TYPE_CHECKING, Self
+from urllib.parse import quote
+
+import aiohttp
+
+from pyagorartc.const import RTM_HOSTS, RTM_PEER_MESSAGES_PATH, RTM_TIMEOUT_S
+from pyagorartc.exceptions import RtmError
+from pyagorartc.models import fingerprint
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from types import TracebackType
+
+    from pyagorartc.models import RtmCredentials
+
+_LOGGER = logging.getLogger(__name__)
+
+DEFAULT_ACCEPTED_CODES: frozenset[str] = frozenset({"message_sent", "message_delivered"})
+_HTTP_OK = 200
+_HTTP_NOT_FOUND = 404
+_HTTP_TOO_MANY_REQUESTS = 429
+_HTTP_SERVER_ERROR = 500
+
+
+def _is_rotating_status(status: int) -> bool:
+    return status in {_HTTP_NOT_FOUND, _HTTP_TOO_MANY_REQUESTS} or status >= _HTTP_SERVER_ERROR
+
+
+class RtmRestClient:
+    """Sends RTM peer messages from ``creds.user_id`` to ``creds.peer_user_id``.
+
+    The message vocabulary (what goes in ``payload``, how often) belongs to the host. A
+    borrowed ``session`` is never closed; one the client creates is closed by ``close()``.
+    """
+
+    def __init__(
+        self,
+        creds: RtmCredentials,
+        session: aiohttp.ClientSession | None = None,
+        *,
+        hosts: Sequence[str] = RTM_HOSTS,
+        verify_ssl: bool = True,
+        timeout_s: float = RTM_TIMEOUT_S,
+    ) -> None:
+        self._creds = creds
+        self._session = session
+        self._owns_session = session is None
+        self._hosts = tuple(hosts)
+        self._verify_ssl = verify_ssl
+        self._timeout = aiohttp.ClientTimeout(total=timeout_s)
+        self._preferred_host: str | None = None
+        self._send_lock = asyncio.Lock()
+
+    def __repr__(self) -> str:
+        return f"RtmRestClient(creds={self._creds!r}, hosts={self._hosts!r}, preferred_host={self._preferred_host!r})"
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        await self.close()
+
+    def update_token(self, token: str) -> None:
+        """Use ``token`` from the next request on; RTM tokens rotate while a client lives."""
+        self._creds = dataclasses.replace(self._creds, token=token)
+        _LOGGER.info("RTM token updated (fp=%s)", fingerprint(token))
+
+    async def close(self) -> None:
+        """Close the HTTP session if this client created it."""
+        if self._owns_session and self._session is not None:
+            session, self._session = self._session, None
+            await session.close()
+
+    async def send_peer_message(
+        self,
+        payload: Mapping[str, object],
+        *,
+        wait_for_ack: bool = True,
+        accepted_codes: frozenset[str] = DEFAULT_ACCEPTED_CODES,
+    ) -> str:
+        """Send ``payload`` (serialised to a compact JSON string) to the peer and return the ack code.
+
+        A 404, 429, 5xx, connection error or timeout moves to the next host; the host that
+        last succeeded is tried first on later calls.
+
+        Raises:
+            RtmError: every host failed (``status`` is the last HTTP status, or ``None`` if the
+                last host was unreachable), the server refused the request with another status,
+                or it answered 200 with a result or ``code`` outside ``accepted_codes`` (compared case-insensitively).
+        """
+        creds = self._creds
+        path = RTM_PEER_MESSAGES_PATH.format(app_id=creds.app_id, user_id=quote(creds.user_id, safe=""))
+        query = "?wait_for_ack=true" if wait_for_ack else ""
+        headers = {
+            "Content-Type": "application/json",
+            "x-agora-token": creds.token,
+            "x-agora-uid": creds.user_id,
+            "Authorization": f"agora token={creds.token}",
+        }
+        body = {
+            "destination": creds.peer_user_id,
+            "enable_offline_messaging": False,
+            "enable_historical_messaging": False,
+            "payload": json.dumps(payload, separators=(",", ":")),
+        }
+        accepted = frozenset(code.lower() for code in accepted_codes)
+        last_status: int | None = None
+        async with self._send_lock:
+            for host in self._iter_endpoints():
+                url = f"{host}{path}{query}"
+                try:
+                    status, data = await self._post(url, headers, body)
+                except (aiohttp.ClientError, TimeoutError) as exc:
+                    _LOGGER.debug("RTM POST %s failed: %s", url, type(exc).__name__)
+                    last_status = None
+                    continue
+                if _is_rotating_status(status):
+                    _LOGGER.debug("RTM POST %s -> %s, trying next host", url, status)
+                    last_status = status
+                    continue
+                return self._accept(url, status, data, accepted, host)
+        raise RtmError("RTM peer message failed on every host", status=last_status)
+
+    def _accept(self, url: str, status: int, data: object, accepted_codes: frozenset[str], host: str) -> str:
+        if status != _HTTP_OK:
+            raise RtmError(f"RTM peer message refused with HTTP {status}", status=status)
+        fields = data if isinstance(data, dict) else {}
+        result = str(fields.get("result", "")).lower()
+        code = str(fields.get("code", "")).lower()
+        _LOGGER.debug("RTM POST %s -> %s result=%s code=%s", url, status, result, code)
+        if result != "success" or code not in accepted_codes:
+            raise RtmError(
+                f"RTM peer message not accepted: result={result} code={code}", status=status, code=code or None
+            )
+        self._preferred_host = host
+        return code
+
+    def _iter_endpoints(self) -> list[str]:
+        """The hosts in order, the last one that succeeded first."""
+        hosts = list(self._hosts)
+        if self._preferred_host in hosts:
+            hosts.remove(self._preferred_host)
+            hosts.insert(0, self._preferred_host)
+        return hosts
+
+    def _http(self) -> aiohttp.ClientSession:
+        if self._session is None:
+            self._session = aiohttp.ClientSession()
+        return self._session
+
+    async def _post(self, url: str, headers: Mapping[str, str], body: Mapping[str, object]) -> tuple[int, object]:
+        """POST one request; returns the status and the decoded JSON body (``None`` if not JSON)."""
+        async with self._http().post(
+            url, headers=headers, json=body, timeout=self._timeout, ssl=self._verify_ssl
+        ) as response:
+            text = await response.text(errors="replace")
+        try:
+            return response.status, json.loads(text) if text else None
+        except (ValueError, RecursionError):
+            return response.status, None

pyagorartc/sdp/__init__.py

@@ -0,0 +1,26 @@
+"""Pure SDP ↔ ORTC conversion (docs/architecture.md §1)."""
+
+from pyagorartc.sdp.answer import STRIPPED_EXTENSIONS, answer_from_ortc, offers_rtx, setup_for_role, validate_answer
+from pyagorartc.sdp.candidates import (
+    candidates_to_ortc,
+    extract_inline_candidates,
+    filter_candidates,
+    parse_trickle_fragment,
+)
+from pyagorartc.sdp.offer import can_send, negotiated_caps, offer_to_ortc, parse_offer
+
+__all__ = [
+    "STRIPPED_EXTENSIONS",
+    "answer_from_ortc",
+    "can_send",
+    "candidates_to_ortc",
+    "extract_inline_candidates",
+    "filter_candidates",
+    "negotiated_caps",
+    "offer_to_ortc",
+    "offers_rtx",
+    "parse_offer",
+    "parse_trickle_fragment",
+    "setup_for_role",
+    "validate_answer",
+]