reactor-runtime 3.1.2__tar.gz → 3.2.0__tar.gz

{reactor_runtime-3.1.2 → reactor_runtime-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactor-runtime
-Version: 3.1.2
+Version: 3.2.0
 Summary: A Python framework for building real-time, interactive video models
 Author: Reactor
 Author-email: Reactor <team@reactor.inc>
@@ -18,7 +18,7 @@ Requires-Dist: numpy>=2.1
 Requires-Dist: prometheus-client>=0.26.0
 Requires-Dist: protobuf>=7.35.1
 Requires-Dist: pyyaml>=6.0.3
-Requires-Dist: reactor-webrtc==0.7.2
+Requires-Dist: reactor-webrtc==0.10.0
 Requires-Dist: uvicorn>=0.49.0
 Requires-Python: >=3.12
 Project-URL: Source, https://github.com/reactor-team/reactor-runtime
@@ -68,7 +68,9 @@ class MyModel(ReactorModel):
         self.prompt = "a sunny meadow"
 
     @event(name="set_prompt", description="Scene the model renders")
-    async def set_prompt(self, prompt: str = InputField(default="a sunny meadow")) -> None:
+    async def set_prompt(
+        self, prompt: str = InputField(default="a sunny meadow", moderate=True)
+    ) -> None:
         self.prompt = prompt
 
     async def run(self) -> None:

{reactor_runtime-3.1.2 → reactor_runtime-3.2.0}/README.md

@@ -42,7 +42,9 @@ class MyModel(ReactorModel):
         self.prompt = "a sunny meadow"
 
     @event(name="set_prompt", description="Scene the model renders")
-    async def set_prompt(self, prompt: str = InputField(default="a sunny meadow")) -> None:
+    async def set_prompt(
+        self, prompt: str = InputField(default="a sunny meadow", moderate=True)
+    ) -> None:
         self.prompt = prompt
 
     async def run(self) -> None:

{reactor_runtime-3.1.2 → reactor_runtime-3.2.0}/pyproject.toml

@@ -10,7 +10,7 @@ module-name = [
 namespace = true
 
 [tool.reactor-wire]
-version = "1.20260722.6"
+version = "1.20260814.7"
 
 [tool.ruff]
 line-length = 100
@@ -45,6 +45,14 @@ ignore = [
     "D107",
 ]
 
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = [
+    "reactor_runtime.InputField",
+    "reactor_runtime.core.InputField",
+    "reactor_runtime.core.fields.InputField",
+    "reactor_runtime.interface.InputField",
+]
+
 [tool.ruff.lint.isort]
 known-first-party = [
     "examples",
@@ -84,7 +92,7 @@ pythonpath = ["."]
 
 [project]
 name = "reactor-runtime"
-version = "3.1.2"
+version = "3.2.0"
 description = "A Python framework for building real-time, interactive video models"
 readme = "README.md"
 license = "Apache-2.0"
@@ -107,7 +115,7 @@ dependencies = [
     "prometheus-client>=0.26.0",
     "protobuf>=7.35.1",
     "pyyaml>=6.0.3",
-    "reactor-webrtc==0.7.2",
+    "reactor-webrtc==0.10.0",
     "uvicorn>=0.49.0",
 ]
 

{reactor_runtime-3.1.2 → reactor_runtime-3.2.0}/pyproject.toml.orig

@@ -16,11 +16,11 @@ namespace = true
 # gates the pin against proto/, so a release cannot ship a schema older than the
 # sources it was built from.
 [tool.reactor-wire]
-version = "1.20260722.6"
+version = "1.20260814.7"
 
 [project]
 name = "reactor-runtime"
-version = "3.1.2"
+version = "3.2.0"
 description = "A Python framework for building real-time, interactive video models"
 readme = "README.md"
 license = "Apache-2.0"
@@ -41,7 +41,7 @@ dependencies = [
     "prometheus-client>=0.26.0",
     "protobuf>=7.35.1",
     "pyyaml>=6.0.3",
-    "reactor-webrtc==0.7.2",
+    "reactor-webrtc==0.10.0",
     "uvicorn>=0.49.0",
 ]
 
@@ -93,6 +93,21 @@ ignore = [
     "D107", # __init__ is documented on the class
 ]
 
+[tool.ruff.lint.flake8-bugbear]
+# `InputField(...)` is the declaration idiom for a field's default and
+# constraints, and it returns a frozen dataclass, so the shared-mutable-default
+# hazard B008 guards against cannot arise. Ruff exempts it already on fields
+# annotated with an immutable builtin; this extends that to every annotation,
+# an upload field included.
+# Ruff resolves the name from the import statement, so every re-export path a
+# caller can reach it by is listed, not the definition site alone.
+extend-immutable-calls = [
+    "reactor_runtime.InputField",
+    "reactor_runtime.core.InputField",
+    "reactor_runtime.core.fields.InputField",
+    "reactor_runtime.interface.InputField",
+]
+
 [tool.ruff.lint.isort]
 # The example models are first-party even though they live outside the package.
 # The generated wire bindings (reactor_wire) are first-party too, but they are

{reactor_runtime-3.1.2 → reactor_runtime-3.2.0}/src/reactor_runtime/core/fields.py

@@ -42,7 +42,10 @@ class FieldInfo:
         min_length: Minimum length for a string or sequence value.
         max_length: Maximum length for a string or sequence value.
         choices: Exhaustive set of allowed values.
-        moderate: Whether the field's value is eligible for content moderation.
+        moderate: Whether the field is marked for content moderation in the
+            rendered schema, which states either polarity. Defaults to
+            ``False``; see :func:`InputField` for what the mark does and which
+            fields it applies to.
     """
 
     default: Any = NO_DEFAULT
@@ -52,7 +55,7 @@ class FieldInfo:
     min_length: int | None = None
     max_length: int | None = None
     choices: list[Any] | None = None
-    moderate: bool = True
+    moderate: bool = False
 
 
 def InputField(  # noqa: N802 — a capitalised factory reads as a type in field declarations
@@ -65,7 +68,7 @@ def InputField(  # noqa: N802 — a capitalised factory reads as a type in field
     min_length: int | None = None,
     max_length: int | None = None,
     choices: list[Any] | None = None,
-    moderate: bool = True,
+    moderate: bool = False,
 ) -> Any:
     """Declare a default value and validation constraints for a field.
 
@@ -84,11 +87,16 @@ def InputField(  # noqa: N802 — a capitalised factory reads as a type in field
         min_length: Minimum length for a string or sequence value.
         max_length: Maximum length for a string or sequence value.
         choices: Exhaustive set of allowed values.
-        moderate: Whether the field's value is eligible for content moderation
-            when moderation is enabled. Only free-text strings and uploaded
-            files are ever moderated; typed, enum, and bounded numeric fields
-            are rejected before a handler sees them, so there is nothing left to
-            moderate.
+        moderate: Whether to mark the field for content moderation. ``False``
+            by default, so a field is marked only when you ask for it. Either
+            way the rendered schema states the answer: the field carries
+            ``x-reactor-moderate: true`` or ``x-reactor-moderate: false``. The
+            mark is a preference and nothing more — it starts no check, and the
+            runtime moderates nothing itself. Whether a check runs against a
+            marked field is a deployment decision taken from that schema. Only
+            free-text strings and uploaded files are ever eligible — typed,
+            enum, and bounded numeric fields carry no free text, so the mark
+            does nothing for them.
 
     Returns:
         A :class:`FieldInfo` carrying the supplied default and constraints.

{reactor_runtime-3.1.2 → reactor_runtime-3.2.0}/src/reactor_runtime/http/routes.py

@@ -13,7 +13,7 @@ from typing import Annotated, Any
 
 from fastapi import Body, FastAPI, Header, HTTPException, Request
 from fastapi.responses import FileResponse, Response, StreamingResponse
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from reactor_runtime.core import Health, HealthStatus, RuntimeState, SessionState
 from reactor_runtime.http.events import format_sse
@@ -40,10 +40,15 @@ class StopSessionRequest(BaseModel):
 
     ``moderate`` marks the stop as a content-moderation verdict: the session
     ends as moderated and clients are notified before their connections close.
-    The body itself is optional — a bare ``POST /stop_session`` is a plain stop.
+    ``reason`` is the platform's human-readable description of why the session
+    is ending: when set, clients receive a session-ended notice carrying it
+    verbatim before their connections close. A moderated stop outranks it —
+    clients see only the moderation notice. The body itself is optional — a
+    bare ``POST /stop_session`` is a plain stop.
     """
 
     moderate: bool = False
+    reason: str = Field(default="", max_length=64)
 
 
 # The non-2xx statuses a route can answer, declared so the published contract
@@ -126,7 +131,10 @@ class SessionRoutes:
             req: Annotated[StopSessionRequest | None, Body()] = None,
         ) -> Response:
             try:
-                runner.stop_session(moderated=req.moderate if req else False)
+                runner.stop_session(
+                    moderated=req.moderate if req else False,
+                    reason=req.reason if req else "",
+                )
             except SessionTransitionError as rejected:
                 raise _transition_rejection(rejected) from None
             return Response(status_code=200)

{reactor_runtime-3.1.2 → reactor_runtime-3.2.0}/src/reactor_runtime/interface/model/schema.py

@@ -237,8 +237,9 @@ def _merge_constraints(schema: dict[str, Any], info: FieldInfo) -> None:
         schema["maxLength"] = info.max_length
     if info.choices is not None:
         schema["enum"] = info.choices
-    if not info.moderate:
-        schema["x-reactor-moderate"] = False
+    # Unconditional, in both polarities: a consumer reads the preference off the
+    # document rather than inferring it from an absent key.
+    schema["x-reactor-moderate"] = info.moderate
 
 
 def _coerce_default(value: Any) -> Any:

{reactor_runtime-3.1.2 → reactor_runtime-3.2.0}/src/reactor_runtime/protocol/base.py

@@ -265,6 +265,21 @@ class Codec(ABC):
         )
         return self.encode(wire)
 
+    def encode_session_ended(self, *, reason: str) -> tuple[Channel, bytes | str]:
+        """Encode the platform's session-ended notice for the client.
+
+        Like a moderation verdict, the notice is unsolicited, so it rides a
+        ``ControlServerMessage`` notification with no ``request_id``. *reason*
+        is the platform-authored, human-readable description of the cause,
+        delivered verbatim. The physical channel is version-dependent and
+        returned alongside the frame.
+        """
+        wire = control_pb2.ControlServerMessage(
+            kind=common_pb2.MessageKind.MESSAGE_KIND_NOTIFICATION,
+            session_ended=platform_pb2.SessionEnded(reason=reason),
+        )
+        return self.encode(wire)
+
 
 def select(version: ProtocolVersion) -> Codec:
     """Return the codec for a negotiated wire version."""

{reactor_runtime-3.1.2 → reactor_runtime-3.2.0}/src/reactor_runtime/protocol/v0/codec.py

@@ -152,6 +152,9 @@ class V0Codec(Codec):
             return Channel.DATA, _runtime("clipFailed", {"reason": message.clip_failed.reason})
         if which == "moderation":
             return Channel.DATA, _runtime("moderation", _moderation_to_dict(message.moderation))
+        if which == "session_ended":
+            ended = message.session_ended
+            return Channel.DATA, _runtime("sessionEnded", {"reason": ended.reason})
         if which == "publish_track":
             return Channel.CONTROL, _dump(
                 {
@@ -314,6 +317,11 @@ class V0Codec(Codec):
                 kind=_KIND.MESSAGE_KIND_NOTIFICATION,
                 moderation=_dict_to_moderation(data),
             )
+        if kind == "sessionEnded":
+            return control_pb2.ControlServerMessage(
+                kind=_KIND.MESSAGE_KIND_NOTIFICATION,
+                session_ended=platform_pb2.SessionEnded(reason=str(data.get("reason", ""))),
+            )
         raise UnsupportedMessageError(f"unrecognized v0 runtime server message: {kind!r}")
 
 

{reactor_runtime-3.1.2 → reactor_runtime-3.2.0}/src/reactor_runtime/runner/connection_manager.py

@@ -10,12 +10,37 @@ turns into a client event.
 It is deliberately wire-blind. Connections enter as the neutral ``Connection``
 shape and the manager only ever calls that shape — it never asks which transport
 produced a connection, which is exactly what lets one session mix transports.
+
+Threading
+---------
+Writers run on one thread and readers run on several, so the registry is
+replaced rather than edited.
+
+* Every write — a register, a drop, a teardown — arrives on the runtime's event
+  loop, because a transport reports a connection opening or closing through the
+  sink from that loop. Writers therefore never race each other, and the manager
+  holds no lock.
+* Reads arrive from any thread. The model's own thread broadcasts messages and
+  drives the playout controls, and a worker thread off that loop fans each
+  emitted media chunk out, so a fan-out is iterating the registry while a
+  client's disconnect is landing on the loop.
+* The registry is bound as an immutable ``Mapping`` and swapped for a fresh one
+  on every change. A reader takes one attribute load and iterates a mapping
+  nothing will ever mutate, so a disconnect mid-fan-out is invisible to it — the
+  chunk simply reaches a connection that has just gone, whose stopped pacer no
+  longer puts anything on the wire. A lock would be worse than unnecessary
+  here: a fan-out can block for seconds inside a connection's pacer waiting for
+  queue room, and a lock spanning that wait would hold the event loop out of
+  the very disconnect it needs to process.
+* The publisher table and the used-id pool stay ordinary mutable containers.
+  Both are read and written only on the event loop, and nothing iterates them
+  from another thread.
 """
 
 from __future__ import annotations
 
 import random
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 
 from reactor_runtime.core import (
     Connection,
@@ -23,10 +48,13 @@ from reactor_runtime.core import (
     MediaChunk,
     SessionEvent,
 )
+from reactor_runtime.log import get_logger
 from reactor_runtime.protocol import Channel, ProtocolVersion
 from reactor_runtime.runner.state_machine import SessionStateMachine
 from reactor_runtime.transport.router import ConnectionsExhaustedError
 
+logger = get_logger(__name__)
+
 # Connection ids are minted at random in this inclusive range, the same id space
 # a production director hands out. 1000 is invalid and 1001 is reserved for
 # legacy single-connection compatibility, so explicit ids start at 1002.
@@ -42,6 +70,31 @@ _MAX_CONN_ID = 9999
 _MAX_MINT_ATTEMPTS = 100
 
 
+def _deliver(conn: Connection, operation: str, act: Callable[[Connection], None]) -> None:
+    """Hand one already-encoded frame to one wire, containing what the wire raises.
+
+    A fan-out reaches every client in the session, so a failure on one wire is
+    the fan-out's to absorb: the remaining connections are still owed the frame,
+    and the caller — often the model's own thread, mid-``emit`` — has no wire of
+    its own to fail. Left to propagate, one connection's exception would surface
+    as a crash of the model's run loop and end the session for everyone on it.
+    The failure is logged with its traceback, naming the wire, so one connection
+    that fails every time is visible rather than silently dark.
+
+    Only the delivery belongs in here. *act* must already hold its frame, because
+    encoding is the model's or the codec's to get right rather than any one
+    client's: a payload the codec cannot render fails identically for every
+    connection, and absorbing it would turn one authoring mistake into a message
+    that silently reaches nobody and a log line per client blaming their wires.
+    """
+    try:
+        act(conn)
+    except Exception:
+        logger.exception(
+            "connection rejected an outbound frame", operation=operation, conn_id=conn.id
+        )
+
+
 class ConnectionManager:
     """Registry and multiplexer of the live connections in one session.
 
@@ -49,12 +102,19 @@ class ConnectionManager:
     first and last connection, arbitrates publisher tracks first-come-first-served,
     and exposes the broadcast / addressed / media sends the model's outbound path
     binds to. Constructed with the machine it drives; nothing here is async.
+
+    Reads are safe from any thread and writes belong to the runtime's event
+    loop; see the module docstring for what that buys and what it costs.
     """
 
     def __init__(self, *, state_machine: SessionStateMachine) -> None:
         """Bind the manager to the session machine it advances."""
         self._sm = state_machine
-        self._by_id: dict[ConnId, Connection] = {}
+        # Bound as a read-only mapping and swapped whole on every change, so a
+        # reader on another thread iterates a snapshot that cannot move under
+        # it. The type is what holds the invariant: an in-place write here is a
+        # type error rather than a race discovered in production.
+        self._by_id: Mapping[ConnId, Connection] = {}
         # The owner of each published track. First publisher wins: a track is held
         # by one connection until it releases or drops, and a later claim on a held
         # track is refused.
@@ -103,11 +163,10 @@ class ConnectionManager:
         replaces the handle without re-driving the session — connection identity
         across a reconnect is the transport's concern, not the manager's.
         """
-        if conn.id in self._by_id:
-            self._by_id[conn.id] = conn
-            return
-        self._by_id[conn.id] = conn
-        self._sm.send(SessionEvent.CONNECTION_OPENED, conn_id=conn.id)
+        known = conn.id in self._by_id
+        self._by_id = {**self._by_id, conn.id: conn}
+        if not known:
+            self._sm.send(SessionEvent.CONNECTION_OPENED, conn_id=conn.id)
 
     def drop(self, cid: ConnId) -> None:
         """Remove a connection and advance the session for its loss.
@@ -121,7 +180,7 @@ class ConnectionManager:
         """
         if cid not in self._by_id:
             return
-        del self._by_id[cid]
+        self._by_id = {other: conn for other, conn in self._by_id.items() if other != cid}
         self._sm.send(SessionEvent.CONNECTION_CLOSED, conn_id=cid)
         held = [name for name, owner in self._publishers.items() if owner == cid]
         for name in held:
@@ -141,7 +200,7 @@ class ConnectionManager:
         too, so the next session starts with the whole id range free again.
         """
         conns = list(self._by_id.values())
-        self._by_id.clear()
+        self._by_id = {}
         self._publishers.clear()
         self._used_conn_ids.clear()
         for conn in conns:
@@ -205,9 +264,12 @@ class ConnectionManager:
         *encode* renders the outbound frame for a given wire version. Each
         connection is sent the frame encoded for the codec it negotiated, so a
         mixed-version session reaches every client in the version it speaks.
+        Encoding happens outside the per-wire containment, so a frame the codec
+        cannot render raises here rather than being absorbed once per client.
         """
         for conn in self._by_id.values():
-            conn.send_message(encode(conn.protocol_version))
+            frame = encode(conn.protocol_version)
+            _deliver(conn, "broadcast", lambda c, payload=frame: c.send_message(payload))
 
     def send(self, cid: ConnId, encode: Callable[[ProtocolVersion], bytes | str]) -> None:
         """Encode and send a frame to one connection in its codec, if registered."""
@@ -253,7 +315,8 @@ class ConnectionManager:
         conn = self._by_id.get(cid)
         if conn is None:
             return
-        self._send_on_channel(conn, encode)
+        channel, frame = encode(conn.protocol_version)
+        self._send_on_channel(conn, channel, frame)
 
     def broadcast_response(
         self, encode: Callable[[ProtocolVersion], tuple[Channel, bytes | str]]
@@ -263,17 +326,21 @@ class ConnectionManager:
         The all-connections analogue of :meth:`send_response`: each connection
         receives the frame encoded for its negotiated codec, on the physical
         channel that codec picks for it. A runtime-authored notice with no single
-        addressee — a moderation verdict — rides this.
+        addressee — a moderation verdict — rides this. As in :meth:`broadcast`,
+        encoding happens outside the per-wire containment so a frame the codec
+        cannot render raises rather than being absorbed once per client.
         """
         for conn in self._by_id.values():
-            self._send_on_channel(conn, encode)
+            channel, frame = encode(conn.protocol_version)
+            _deliver(
+                conn,
+                "broadcast_response",
+                lambda c, ch=channel, payload=frame: self._send_on_channel(c, ch, payload),
+            )
 
     @staticmethod
-    def _send_on_channel(
-        conn: Connection, encode: Callable[[ProtocolVersion], tuple[Channel, bytes | str]]
-    ) -> None:
-        """Encode a frame for one connection and route it to the channel picked."""
-        channel, frame = encode(conn.protocol_version)
+    def _send_on_channel(conn: Connection, channel: Channel, frame: bytes | str) -> None:
+        """Send an already-encoded frame on the channel its codec picked for it."""
         if channel is Channel.CONTROL:
             conn.send_control(frame)
         else:
@@ -300,22 +367,22 @@ class ConnectionManager:
                 return
             caps = conn.capabilities
             if caps.carries_video or caps.carries_audio:
-                conn.send_media(chunk)
+                _deliver(conn, "broadcast_media", lambda c: c.send_media(chunk))
 
     def flush_media(self) -> None:
         """Drop every connection's queued media and cut playout to black."""
         for conn in self._by_id.values():
-            conn.flush_media()
+            _deliver(conn, "flush_media", lambda c: c.flush_media())
 
     def set_media_rate(self, fps: float) -> None:
         """Re-pace every connection's queued media at *fps* immediately."""
         for conn in self._by_id.values():
-            conn.set_media_rate(fps)
+            _deliver(conn, "set_media_rate", lambda c: c.set_media_rate(fps))
 
     def set_media_depth(self, depth: int) -> None:
         """Bound every connection's media queue at *depth* frames."""
         for conn in self._by_id.values():
-            conn.set_media_depth(depth)
+            _deliver(conn, "set_media_depth", lambda c: c.set_media_depth(depth))
 
     def note_keepalive(self, cid: ConnId) -> None:
         """Record a per-connection liveness ping.

reactor_runtime-3.2.0/src/reactor_runtime/runner/offer_epochs.py

@@ -0,0 +1,44 @@
+"""Session epochs for admitted connection offers."""
+
+from __future__ import annotations
+
+from reactor_runtime.core import ConnId
+
+
+class OfferEpochs:
+    """Track which session each admitted connection offer belongs to.
+
+    Negotiation is asynchronous, so a wire can reach its connected state after
+    the session that admitted its offer ended. While no session runs, the
+    session state exposes that; once the next session starts, the state looks
+    valid again and cannot. The epoch counts sessions: each admitted offer is
+    stamped with the live epoch, and the wire is checked against the current
+    one when it connects.
+
+    Bounded by the connection-id space: a re-offer on the same id restamps it,
+    and a checked stamp is dropped.
+    """
+
+    def __init__(self) -> None:
+        """Start before any session, with no offers stamped."""
+        self._current = 0
+        self._stamps: dict[ConnId, int] = {}
+
+    def session_started(self) -> None:
+        """Move to the next epoch; offers stamped from now on belong to it."""
+        self._current += 1
+
+    def stamp(self, conn_id: ConnId) -> None:
+        """Stamp an admitted offer with the live epoch. A re-offer restamps."""
+        self._stamps[conn_id] = self._current
+
+    def consume(self, conn_id: ConnId) -> bool:
+        """Take the stamp for *conn_id* and report whether it is stale.
+
+        Returns ``True`` when the offer was stamped in an earlier epoch, so
+        its wire belongs to a session that ended. An unstamped id is not
+        stale: a transport that does not stamp offers is judged on session
+        state alone. The stamp is consumed either way.
+        """
+        stamped = self._stamps.pop(conn_id, None)
+        return stamped is not None and stamped != self._current