caprid-moq-core 0.1.0__py3-none-any.whl

caprid_moq_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: caprid-moq-core
+Version: 0.1.0
+Summary: Transport-independent MOQT track primitives
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/caprids/relay-sdks
+Description-Content-Type: text/markdown
+
+# Generic MoQ core (Python)
+
+An independently buildable package for MOQT sessions and arbitrary track objects. It has no runtime
+dependencies and does not import Relay product code or any transport library.
+
+`create_moqt_session` owns a supplied, established transport. Subscribe, fetch, and track-status
+requests use callback handlers, preserve uninterpreted payloads and object properties, and expose
+protocol lifecycle notifications. `MoqTrackSource` describes borrowed track access without shutdown.
+
+`create_moqt_publish_session` serves a namespace and its registered tracks over a separate
+transport. Track properties are explicit, with no default media timescale. `create_subgroup_writer`
+writes arbitrary object payloads and metadata; the SDK supplies the bounded, single-object-group
+publishing policy above it.
+
+The transport seam is `moq_core.transport.MoqtTransport`: the structural subset of a WebTransport
+session the drivers need, spelled for asyncio. `caprid_relay` supplies the aioquic implementation and
+tests supply in-memory pairs.
+
+This package follows MOQT draft 22, and draft 20 for a peer that selects it, and receives subscription objects over reliable streams. It does
+not implement application timing, decoding, datagram reception, or automatic session recovery.
+
+The implementation is a port of `ts/packages/moq-core`, which is itself an attributed snapshot of the
+Video.js protocol modules under Apache-2.0. See `NOTICE` and `UPSTREAM.json`.
+
+For Relay application usage and local installation, start with the [Python quickstart](../../README.md#first-round-trip).
+
+The distribution on PyPI is `caprid-moq-core`; the import name is `moq_core`.
+
+## Stability
+
+Before 1.0, a minor version can break the API. This package releases together with `caprid-relay` at
+the same version; see the [changelog](../../CHANGELOG.md).

caprid_moq_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+moq_core/__init__.py,sha256=zGc6-SuvVGrJzpHSRfXp4alpY6FUIASxs1WKQZ5Zqrs,3779
+moq_core/_tasks.py,sha256=sVmoZXzl8wpy3fDJE6Yyv5vPYsFPCUKdDMXii5xbS3I,2151
+moq_core/bytes.py,sha256=nusEp_PTrzsdYt5Z1dRuZ_oisC15G1fkucDyXY74bKQ,6450
+moq_core/control_messages.py,sha256=x_xNp7qZpVSIB2xqvM_ysPW_ZRkJpKu7mkmq964eksk,66512
+moq_core/errors.py,sha256=84f7MP_ym6IRVOnTz2XbliVz3al8qK0IJKbR9XvJSKQ,2319
+moq_core/object_stream.py,sha256=4blGp0GPMOOnkHjC4RjlpmIfbvEvFaDwevTgpcSdWmc,15839
+moq_core/publish_session.py,sha256=rhDJedPsG_Q-lKcyaE-Ef2d1AJPaozj6BpGT6Xvn0Xw,63794
+moq_core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+moq_core/request_stream.py,sha256=j5rl_G8r-D6Z5hWPeqexDc26OvZGbvzCeCu3gz3G3q4,5827
+moq_core/session.py,sha256=7ww54AA8eaumBmpz7EN0sZr6SoJAriVr6_G8WwS02sI,58224
+moq_core/subgroup_writer.py,sha256=9XQVpbhLndcW1O1xV1_KBM4_oT1-UAqiC8gqsoTK3mI,9183
+moq_core/track_source.py,sha256=pVH48ENq1NLiekCvNTGGszS9ghHP8dKqfwbD4uVGjPI,1416
+moq_core/transport.py,sha256=yi90PB_UT1oovGvAxx5nEU9vB-au4UbxV1wE_cMkq8U,6363
+moq_core/varint.py,sha256=O6wjBn4S0XmNT5EoGL8rchoG3O1Ti4o9ABgvkApY2gY,3193
+caprid_moq_core-0.1.0.dist-info/licenses/LICENSE,sha256=21Hob9QKsIT6YVb2B3SZW2sqHby_IAc5MTG2YAHM5sY,870
+caprid_moq_core-0.1.0.dist-info/licenses/NOTICE,sha256=dhRVybYfLgWRX64eNklLX6TnL1Vxo9SOi5xUo6T82Ak,376
+caprid_moq_core-0.1.0.dist-info/WHEEL,sha256=WKk67IZPzp9uSkBO-iWoZzrqp9-AwH7FE9EB8EoJbf4,81
+caprid_moq_core-0.1.0.dist-info/METADATA,sha256=qgQCDVLNPdS0cMIElGU9pOmN0ka7nhMs_bSw2AGZf_k,2162
+caprid_moq_core-0.1.0.dist-info/RECORD,,

caprid_moq_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.12
+Root-Is-Purelib: true
+Tag: py3-none-any

caprid_moq_core-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,20 @@
+   Copyright 2025-present Video.js contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+------------------------------------------------------------------
+
+Trademark Notice:
+“Video.js” is a registered trademark of Brightcove Inc.
+The project is maintained independently by the open-source community,
+governed by the Video.js Technical Steering Committee.

caprid_moq_core-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,6 @@
+The protocol implementation and its initial tests are a Python port of the TypeScript
+@caprid/moq-core package (ts/packages/moq-core in this repository), which is derived from Video.js.
+Copyright 2025-present Video.js contributors.
+Licensed under the Apache License, Version 2.0. See LICENSE.
+
+See UPSTREAM.json for the source revision, original file hashes, and adaptations.

moq_core/__init__.py

@@ -0,0 +1,150 @@
+"""Transport-independent MOQT track primitives.
+
+The Python counterpart of ``ts/packages/moq-core``: protocol encoding, sessions, and stream
+handling over an abstract transport, with no runtime dependencies and no knowledge of Relay.
+``MOQT_PROTOCOL_ID`` is the default draft every SDK shares and ``MOQT_PROTOCOL_IDS`` the drafts a
+client offers; ``spec/protocol.json`` is their source of truth and ``tests/test_spec_protocol.py``
+checks they agree.
+"""
+
+from .control_messages import (
+    MAX_NAMESPACE_FIELDS,
+    MOQT_PROTOCOL_ID,
+    MOQT_PROTOCOL_IDS,
+    PUBLISH_DONE_STATUS,
+    REQUEST_ERROR_CODE,
+    AbsoluteLocationFilter,
+    FetchOk,
+    Goaway,
+    GroupOrder,
+    KeyValuePair,
+    Location,
+    LocationFilter,
+    MessageParameters,
+    MoqtProtocolId,
+    NextObjectFilter,
+    NoLocationFilter,
+    PublishDone,
+    RelativeGroupFilter,
+    RequestError,
+    SubscribeOk,
+    TrackNamespace,
+)
+from .errors import SESSION_ERROR, MoqtProtocolError, is_moqt_protocol_error
+from .object_stream import (
+    MAX_OBJECT_PAYLOAD_LENGTH,
+    FetchEndOfRange,
+    FetchObject,
+    FetchStreamEntry,
+    MoqtObject,
+    ObjectStatus,
+)
+from .publish_session import (
+    MAX_TRACK_PROPERTIES_LENGTH,
+    AnnounceEnded,
+    IncomingRequestUpdate,
+    MoqtPublishSession,
+    MoqtPublishSessionCallbacks,
+    MoqtPublishSessionConfig,
+    RegisteredTrack,
+    RegisterTrackOptions,
+    SubscribeFailed,
+    TrackBinding,
+    create_moqt_publish_session,
+)
+from .session import (
+    Closed,
+    FetchHandle,
+    FetchHandlers,
+    FetchReset,
+    MoqtFetchOptions,
+    MoqtSession,
+    MoqtSessionCallbacks,
+    MoqtSessionConfig,
+    MoqtSubscribeNamespaceOptions,
+    MoqtSubscribeOptions,
+    NamespaceSubscription,
+    NamespaceSubscriptionHandlers,
+    PublishResponder,
+    SubgroupEnd,
+    SubgroupReset,
+    Subscription,
+    SubscriptionHandlers,
+    TrackStatusHandlers,
+    TrackStatusOk,
+    create_moqt_session,
+)
+from .subgroup_writer import SubgroupWriter, create_subgroup_writer
+from .track_source import MoqTrackSource
+from .transport import BidirectionalStream, MoqtTransport, ReceiveStream, SendStream
+
+__all__ = [
+    "MAX_NAMESPACE_FIELDS",
+    "MAX_OBJECT_PAYLOAD_LENGTH",
+    "MAX_TRACK_PROPERTIES_LENGTH",
+    "MOQT_PROTOCOL_ID",
+    "MOQT_PROTOCOL_IDS",
+    "PUBLISH_DONE_STATUS",
+    "REQUEST_ERROR_CODE",
+    "SESSION_ERROR",
+    "AbsoluteLocationFilter",
+    "AnnounceEnded",
+    "BidirectionalStream",
+    "Closed",
+    "FetchEndOfRange",
+    "FetchHandle",
+    "FetchHandlers",
+    "FetchObject",
+    "FetchOk",
+    "FetchReset",
+    "FetchStreamEntry",
+    "Goaway",
+    "GroupOrder",
+    "IncomingRequestUpdate",
+    "KeyValuePair",
+    "Location",
+    "LocationFilter",
+    "MessageParameters",
+    "MoqTrackSource",
+    "MoqtFetchOptions",
+    "MoqtObject",
+    "MoqtProtocolError",
+    "MoqtProtocolId",
+    "MoqtPublishSession",
+    "MoqtPublishSessionCallbacks",
+    "MoqtPublishSessionConfig",
+    "MoqtSession",
+    "MoqtSessionCallbacks",
+    "MoqtSessionConfig",
+    "MoqtSubscribeNamespaceOptions",
+    "MoqtSubscribeOptions",
+    "MoqtTransport",
+    "NamespaceSubscription",
+    "NamespaceSubscriptionHandlers",
+    "NextObjectFilter",
+    "NoLocationFilter",
+    "ObjectStatus",
+    "PublishDone",
+    "PublishResponder",
+    "ReceiveStream",
+    "RegisterTrackOptions",
+    "RegisteredTrack",
+    "RelativeGroupFilter",
+    "RequestError",
+    "SendStream",
+    "SubgroupEnd",
+    "SubgroupReset",
+    "SubgroupWriter",
+    "SubscribeFailed",
+    "SubscribeOk",
+    "Subscription",
+    "SubscriptionHandlers",
+    "TrackBinding",
+    "TrackNamespace",
+    "TrackStatusHandlers",
+    "TrackStatusOk",
+    "create_moqt_publish_session",
+    "create_moqt_session",
+    "create_subgroup_writer",
+    "is_moqt_protocol_error",
+]

moq_core/_tasks.py

@@ -0,0 +1,68 @@
+"""Background-task plumbing shared by the session drivers.
+
+The TypeScript core fires promises with ``void`` and attaches ``.catch`` handlers where a failure
+has a meaning. asyncio needs a strong reference to every task it should keep running, and an
+unretrieved task exception is reported as a warning at garbage-collection time, so :func:`spawn`
+keeps that reference and routes the outcome through an optional error handler.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+_log = logging.getLogger("moq_core")
+_background: set[asyncio.Task[Any]] = set()
+
+
+def spawn(
+    coroutine: Coroutine[Any, Any, Any],
+    *,
+    on_error: Callable[[BaseException], None] | None = None,
+) -> asyncio.Task[Any]:
+    """Run ``coroutine`` in the background, keeping it referenced until it finishes.
+
+    ``on_error`` receives an exception the coroutine raised (never a cancellation). Without it the
+    exception is logged at debug level and otherwise dropped, the counterpart of ``.catch(() => {})``.
+    """
+    task = asyncio.get_running_loop().create_task(coroutine)
+    _background.add(task)
+
+    def finished(done: asyncio.Task[Any]) -> None:
+        _background.discard(done)
+
+        if done.cancelled():
+            return
+
+        error = done.exception()
+
+        if error is None:
+            return
+
+        if on_error is not None:
+            on_error(error)
+        else:
+            _log.debug("background task failed", exc_info=error)
+
+    task.add_done_callback(finished)
+    return task
+
+
+def observe(future: asyncio.Future[Any]) -> None:
+    """Mark a future's eventual exception as handled without acting on it."""
+
+    def finished(done: asyncio.Future[Any]) -> None:
+        if not done.cancelled():
+            done.exception()
+
+    future.add_done_callback(finished)
+
+
+def call_later(delay: float, callback: Callable[[], None]) -> asyncio.TimerHandle:
+    """Schedule ``callback`` after ``delay`` seconds on the running loop."""
+    return asyncio.get_running_loop().call_later(delay, callback)
+
+
+__all__ = ["call_later", "observe", "spawn"]

moq_core/bytes.py

@@ -0,0 +1,199 @@
+"""Byte-level readers and writers shared by the MOQT wire codecs.
+
+:class:`ByteReader` and :class:`ByteWriter` are synchronous cursors over in-memory buffers, used for
+control-message bodies (always fully buffered: the 16-bit message length bounds them).
+:class:`StreamReader` is the asynchronous counterpart for unidirectional data streams, where headers
+and objects arrive incrementally over a transport :class:`~moq_core.transport.ReceiveStream`.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+
+from .errors import IncompleteInputError
+from .transport import ReceiveStream
+from .varint import MAX_VARINT_VALUE, decode_varint, encode_varint, varint_length_from_first_byte
+
+
+def utf8_encode(value: str) -> bytes:
+    return value.encode("utf-8")
+
+
+def utf8_decode(data: bytes | bytearray | memoryview) -> str:
+    # Lenient like TextDecoder's default: invalid sequences become U+FFFD instead of failing.
+    return bytes(data).decode("utf-8", errors="replace")
+
+
+class ByteReader:
+    """Synchronous cursor over a byte buffer. Every read past the end raises :class:`IncompleteInputError`."""
+
+    __slots__ = ("_data", "_offset")
+
+    def __init__(self, data: bytes | bytearray | memoryview, offset: int = 0) -> None:
+        self._data = bytes(data)
+        self._offset = offset
+
+    @property
+    def offset(self) -> int:
+        return self._offset
+
+    @property
+    def remaining(self) -> int:
+        return len(self._data) - self._offset
+
+    def read_varint(self) -> int:
+        value, byte_length = decode_varint(self._data, self._offset)
+        self._offset += byte_length
+        return value
+
+    def read_count_varint(self) -> int | None:
+        """Read a count whose "unknown" sentinel is the maximal varint 2^64-1 (PUBLISH_DONE's Stream Count, §9.9).
+
+        Exactly that sentinel reads as ``None``; every other value is returned as is.
+        """
+        value = self.read_varint()
+        return None if value == MAX_VARINT_VALUE else value
+
+    def read_uint8(self) -> int:
+        if self.remaining < 1:
+            raise IncompleteInputError("read past end of buffer")
+
+        value = self._data[self._offset]
+        self._offset += 1
+        return value
+
+    def read_uint16(self) -> int:
+        if self.remaining < 2:
+            raise IncompleteInputError("read past end of buffer")
+
+        value = (self._data[self._offset] << 8) | self._data[self._offset + 1]
+        self._offset += 2
+        return value
+
+    def read_bytes(self, length: int) -> bytes:
+        if length < 0 or self.remaining < length:
+            raise IncompleteInputError("read past end of buffer")
+
+        view = self._data[self._offset : self._offset + length]
+        self._offset += length
+        return view
+
+
+class ByteWriter:
+    """Growable byte sink for encoding wire structures."""
+
+    __slots__ = ("_buffer",)
+
+    def __init__(self, initial_capacity: int = 0) -> None:
+        del initial_capacity  # bytearray grows on its own; the parameter keeps call sites symmetric with the TS core
+        self._buffer = bytearray()
+
+    @property
+    def length(self) -> int:
+        return len(self._buffer)
+
+    def write_varint(self, value: int) -> None:
+        self._buffer += encode_varint(value)
+
+    def write_uint8(self, value: int) -> None:
+        self._buffer.append(value & 0xFF)
+
+    def write_uint16(self, value: int) -> None:
+        self._buffer += bytes(((value >> 8) & 0xFF, value & 0xFF))
+
+    def write_bytes(self, data: bytes | bytearray | memoryview) -> None:
+        self._buffer += data
+
+    def write_length_prefixed(self, data: bytes | bytearray | memoryview) -> None:
+        """Varint length prefix followed by the bytes."""
+        self.write_varint(len(data))
+        self.write_bytes(data)
+
+    def to_bytes(self) -> bytes:
+        """A copy of the written bytes."""
+        return bytes(self._buffer)
+
+
+class StreamReader:
+    """Buffered asynchronous reader over a transport :class:`ReceiveStream`.
+
+    Reads never split a varint or byte run: each method pulls chunks until it can satisfy the
+    request. A clean end-of-stream mid-read raises :class:`IncompleteInputError`; use
+    :meth:`at_end` to probe for a clean boundary first. A reset stream raises whatever the transport
+    raises.
+    """
+
+    __slots__ = ("_buffered", "_chunks", "_done", "_stream")
+
+    def __init__(self, stream: ReceiveStream) -> None:
+        self._stream = stream
+        self._chunks: deque[bytes] = deque()
+        self._buffered = 0
+        self._done = False
+
+    async def _pull(self) -> bool:
+        if self._done:
+            return False
+
+        chunk = await self._stream.read()
+
+        if chunk is None:
+            self._done = True
+            return False
+
+        if chunk:
+            self._chunks.append(bytes(chunk))
+            self._buffered += len(chunk)
+
+        return True
+
+    async def _fill(self, length: int) -> None:
+        while self._buffered < length:
+            if not await self._pull():
+                raise IncompleteInputError("unexpected end of stream")
+
+    def _take(self, length: int) -> bytes:
+        out = bytearray()
+
+        while len(out) < length:
+            head = self._chunks[0]
+            take = min(len(head), length - len(out))
+            out += head[:take]
+
+            if take == len(head):
+                self._chunks.popleft()
+            else:
+                self._chunks[0] = head[take:]
+
+        self._buffered -= length
+        return bytes(out)
+
+    async def at_end(self) -> bool:
+        """True when the stream ended cleanly with no bytes left unread."""
+        while self._buffered == 0:
+            if not await self._pull():
+                return True
+
+        return False
+
+    async def read_bytes(self, length: int) -> bytes:
+        await self._fill(length)
+        return self._take(length)
+
+    async def read_uint8(self) -> int:
+        await self._fill(1)
+        return self._take(1)[0]
+
+    async def read_varint(self) -> int:
+        await self._fill(1)
+        byte_length = varint_length_from_first_byte(self._chunks[0][0])
+        await self._fill(byte_length)
+        return decode_varint(self._take(byte_length))[0]
+
+    def cancel(self, reason: object = None) -> None:
+        """Cancel the underlying stream (drop an unwanted data stream)."""
+        self._done = True
+        self._stream.cancel(reason)
+
+
+__all__ = ["ByteReader", "ByteWriter", "StreamReader", "utf8_decode", "utf8_encode"]