reactor-runtime 2.7.8__tar.gz → 2.7.9__tar.gz

{reactor_runtime-2.7.8 → reactor_runtime-2.7.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactor_runtime
-Version: 2.7.8
+Version: 2.7.9
 Summary: Reactor runtime with public model API
 Author-email: Reactor <team@reactor.inc>
 Requires-Python: >=3.9

{reactor_runtime-2.7.8 → reactor_runtime-2.7.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactor_runtime"
-version = "2.7.8"
+version = "2.7.9"
 description = "Reactor runtime with public model API"
 authors = [
 	{ name = "Reactor", email = "team@reactor.inc" }
@@ -87,4 +87,4 @@ gst = [
 # Legacy releases used `X.Y.Z-g<short-sha>` (e.g. `1.4.1-g5660eed`); the wheel
 # stripped the `-g<sha>` suffix. fetch-proto.py still understands that shape
 # for back-compat with old pins, but new bumps should track the calendar format.
-version = "1.20260514.12095"
+version = "1.20260527.14467"

{reactor_runtime-2.7.8 → reactor_runtime-2.7.9}/src/reactor_runtime/model_state.py

@@ -31,6 +31,7 @@ class ModelEvent(Enum):
     CLEANUP_COMPLETE = "cleanup_complete"
     EVICTION = "eviction"
     IDLING = "idling"
+    SESSION_ACTIVE = "session_active"
 
 
 class ModelStateMachine:
@@ -72,6 +73,15 @@ class ModelStateMachine:
         ModelEvent.IDLING: [
             (ModelState.READY, ModelState.READY),
         ],
+        # SESSION_ACTIVE is the analog of IDLING during a live session: a
+        # periodic liveness ping sent while the runtime is serving a
+        # session (WAITING / STREAMING / ORPHANED). All three transitions
+        # are self-loops since the event carries no state change.
+        ModelEvent.SESSION_ACTIVE: [
+            (ModelState.WAITING, ModelState.WAITING),
+            (ModelState.STREAMING, ModelState.STREAMING),
+            (ModelState.ORPHANED, ModelState.ORPHANED),
+        ],
     }
 
     def __init__(self, initial_state: ModelState = ModelState.CREATED):
@@ -98,7 +108,10 @@ class ModelStateMachine:
 
         if to_state is None:
             log_fn = logger.warning
-            if event == ModelEvent.IDLING:
+            # IDLING and SESSION_ACTIVE are high-frequency liveness pings;
+            # legitimate races with state transitions can produce rejected
+            # events that don't deserve a warning.
+            if event in (ModelEvent.IDLING, ModelEvent.SESSION_ACTIVE):
                 log_fn = logger.debug
             log_fn(
                 "Illegal state transition",
@@ -108,7 +121,7 @@ class ModelStateMachine:
             return False
 
         log_fn = logger.info
-        if event == ModelEvent.IDLING:
+        if event in (ModelEvent.IDLING, ModelEvent.SESSION_ACTIVE):
             log_fn = logger.debug
 
         log_fn(
@@ -145,7 +158,18 @@ class ModelStateMachine:
             handler(**kwargs)
 
     def _call_enter_handler(self, state: ModelState, previous_state: ModelState):
-        """Call the appropriate on_enter_<state> method."""
+        """Call the appropriate on_enter_<state> method.
+
+        Self-loop transitions (``state == previous_state``) skip the
+        ``on_enter_*`` hook — those hooks are designed to run on actual
+        state changes, not on every heartbeat. This matters for
+        liveness-ping events like ``IDLING`` and ``SESSION_ACTIVE`` whose
+        from/to states are identical: re-running ``on_enter_WAITING`` /
+        ``on_enter_ORPHANED`` on every tick would, e.g., cancel and
+        restart the orphan timeout, preventing it from ever firing.
+        """
+        if state == previous_state:
+            return
         handler_name = f"on_enter_{state.value}"
         handler = getattr(self, handler_name, None)
         if handler:
@@ -191,6 +215,9 @@ class ModelStateMachine:
     def on_before_idling(self, **kwargs):
         pass
 
+    def on_before_session_active(self, **kwargs):
+        pass
+
     # on_enter_<state> methods
     def on_enter_CREATED(self, previous_state: ModelState):
         pass

{reactor_runtime-2.7.8 → reactor_runtime-2.7.9}/src/reactor_runtime/runtime_api.py

@@ -100,6 +100,13 @@ def _iter_strings(value: Any) -> Iterator[str]:
 _IDLING_INTERVAL_ENV_VAR = "IDLING_INTERVAL_SECONDS"
 _DEFAULT_IDLING_INTERVAL = 30.0
 
+# Periodic SESSION_ACTIVE liveness ping. Sent while the runtime is serving
+# a session (WAITING / STREAMING / ORPHANED). Default cadence matches the
+# Supervisor's reaper tick (10s); the Supervisor declares a session lost
+# after 3 missed intervals.
+_SESSION_ACTIVE_INTERVAL_ENV_VAR = "SESSION_ACTIVE_INTERVAL_SECONDS"
+_DEFAULT_SESSION_ACTIVE_INTERVAL = 10.0
+
 _PING_TIMEOUT_ENV_VAR = "WEBRTC_CLIENT_PING_TIMEOUT_SECONDS"
 _DEFAULT_PING_TIMEOUT = 20.0
 
@@ -130,6 +137,12 @@ class RuntimeConfig:
     # Priority: ENV > CLI > default. Set to None to use default.
     idling_interval: Optional[float] = None
 
+    # Session-active heartbeat interval in seconds. Emitted while the
+    # runtime is serving a session (WAITING / STREAMING / ORPHANED) so
+    # the Supervisor can detect abruptly terminated sessions.
+    # Priority: ENV > CLI > default. Set to None to use default.
+    session_active_interval: Optional[float] = None
+
     # WebRTC client-ping watchdog timeout (seconds). Priority: ENV > CLI > default.
     # Resolved to a concrete float in __post_init__; non-positive disables the watchdog.
     ping_timeout: Optional[float] = None
@@ -162,6 +175,26 @@ class RuntimeConfig:
         if self.idling_interval is None:
             self.idling_interval = _DEFAULT_IDLING_INTERVAL
 
+        # Resolve session_active_interval: ENV > CLI > default, same shape
+        # as idling_interval above.
+        sa_env_val = os.getenv(_SESSION_ACTIVE_INTERVAL_ENV_VAR)
+        if sa_env_val:
+            try:
+                self.session_active_interval = float(sa_env_val)
+            except ValueError:
+                logger.warning(
+                    "Invalid session-active interval env value, falling back to default",
+                    env_var=_SESSION_ACTIVE_INTERVAL_ENV_VAR,
+                    value=sa_env_val,
+                )
+        if (
+            self.session_active_interval is not None
+            and self.session_active_interval <= 0
+        ):
+            self.session_active_interval = None
+        if self.session_active_interval is None:
+            self.session_active_interval = _DEFAULT_SESSION_ACTIVE_INTERVAL
+
         # Resolve ping_timeout: ENV > CLI > default (reject non-finite floats)
         resolved_ping: Optional[float] = None
         ping_env = os.getenv(_PING_TIMEOUT_ENV_VAR)
@@ -239,6 +272,17 @@ class RuntimeConfig:
             help=f"Idling event interval ({_IDLING_INTERVAL_ENV_VAR} env overrides). "
             f"Default: {_DEFAULT_IDLING_INTERVAL}s",
         )
+        parser.add_argument(
+            "--session-active-interval",
+            type=float,
+            default=None,
+            dest="session_active_interval",
+            help=(
+                "SESSION_ACTIVE liveness event interval, emitted while a "
+                f"session is active ({_SESSION_ACTIVE_INTERVAL_ENV_VAR} env "
+                f"overrides). Default: {_DEFAULT_SESSION_ACTIVE_INTERVAL}s"
+            ),
+        )
         parser.add_argument(
             "--profiling-dir",
             type=str,
@@ -291,6 +335,11 @@ class Runtime(ModelStateMachine, ABC):
         # Idling task - sends periodic IDLING events when in READY state
         self._idling_task: Optional[asyncio.Task] = None
 
+        # Session-active task - sends periodic SESSION_ACTIVE events while
+        # the runtime is serving a session (WAITING / STREAMING / ORPHANED).
+        # Lifecycle is gated by on_enter_* state hooks.
+        self._session_active_task: Optional[asyncio.Task] = None
+
         # Trickle-ICE buffer
         # Browsers start emitting ICE candidates as soon as
         # ``setLocalDescription`` runs — typically *before* the SDP
@@ -478,6 +527,9 @@ class Runtime(ModelStateMachine, ABC):
         :meth:`add_ice_candidate`.
         """
         self._cancel_orphan_timeout()
+        # Idempotent: a session arriving here from WAITING will already
+        # have armed the loop; re-arming on ORPHANED -> STREAMING is a no-op.
+        self._start_session_active_loop()
 
         # Replay buffered trickle ICE candidates onto the freshly
         # installed transport. Scheduled via create_task because
@@ -498,15 +550,24 @@ class Runtime(ModelStateMachine, ABC):
         """
         self._clear_pending_ice_candidates()
         self._start_orphan_timeout()
+        # Keep emitting SESSION_ACTIVE while orphaned: the runtime is still
+        # "owning" the session, just temporarily without a client.
+        self._start_session_active_loop()
 
     def on_enter_WAITING(self, previous_state: ModelState) -> None:
         """Handler called when the session enters the WAITING state.
         Starts the orphan timeout.
         """
         self._start_orphan_timeout()
+        # Arm SESSION_ACTIVE pings as soon as the runtime accepts a session,
+        # before the client has even connected.
+        self._start_session_active_loop()
 
     def on_enter_TERMINATED(self, previous_state: ModelState) -> None:
         """TERMINATED means the runtime should exit."""
+        # Cancel the session-active loop synchronously via task.cancel();
+        # the awaited stop happens in _shutdown_cleanup.
+        self._cancel_session_active_task()
         self._shutdown_event.set()
 
     def on_enter_READY(self, previous_state: ModelState) -> None:
@@ -517,6 +578,8 @@ class Runtime(ModelStateMachine, ABC):
         shutdown event if SIGTERM was received earlier.
         """
         self._clear_pending_ice_candidates()
+        # Back to READY: session is fully unwound, stop the per-session loop.
+        self._cancel_session_active_task()
         if self._shutdown_pending:
             self._shutdown_event.set()
 
@@ -530,6 +593,9 @@ class Runtime(ModelStateMachine, ABC):
         """
         self._cancel_orphan_timeout()
         self._clear_pending_ice_candidates()
+        # Session is wrapping up; stop emitting SESSION_ACTIVE so we don't
+        # race the CLEANUP_COMPLETE / STOP_SESSION events.
+        self._cancel_session_active_task()
 
         if self.model is not None:
             self.model._push_event(Disconnected())
@@ -1212,6 +1278,7 @@ class Runtime(ModelStateMachine, ABC):
     async def _shutdown_cleanup(self) -> None:
         """Internal shutdown cleanup implementation."""
         await self._stop_idling_loop()
+        await self._stop_session_active_loop()
 
         try:
             if self.session_running or self.current_state == ModelState.WAITING:
@@ -1325,3 +1392,67 @@ class Runtime(ModelStateMachine, ABC):
                 break
             except Exception:
                 pass
+
+    # -----------------------------------------------------------------
+    # Session-active heartbeat
+    # -----------------------------------------------------------------
+
+    def _start_session_active_loop(self) -> None:
+        """Start the session-active heartbeat loop.
+
+        Emits ``SESSION_ACTIVE`` events while the runtime is serving a
+        session, giving the Supervisor a liveness signal during the
+        WAITING / STREAMING / ORPHANED states. Idempotent: a second call
+        while the loop is already running is a no-op, so it's safe to
+        invoke from every relevant on_enter_* hook.
+        """
+        if self._session_active_task is not None:
+            return
+        self._session_active_task = asyncio.create_task(self._session_active_loop())
+
+    def _cancel_session_active_task(self) -> None:
+        """Cancel the session-active loop synchronously.
+
+        Safe to call from on_enter_* hooks (which run synchronously from
+        ``send()``). The task reference is preserved so that
+        ``_stop_session_active_loop`` (called from ``_shutdown_cleanup``)
+        can still ``await`` the cancelled task during shutdown; the
+        synchronous ``.cancel()`` call is enough for the on_enter_* hooks.
+        """
+        if self._session_active_task is not None:
+            self._session_active_task.cancel()
+
+    async def _stop_session_active_loop(self) -> None:
+        """Cancel the session-active loop and await its exit.
+
+        Called from ``_shutdown_cleanup`` to make sure the loop is fully
+        unwound before the runtime exits.
+        """
+        task = self._session_active_task
+        if task is None:
+            return
+        task.cancel()
+        self._session_active_task = None
+        try:
+            await task
+        except asyncio.CancelledError:
+            pass
+
+    async def _session_active_loop(self) -> None:
+        """Background task that periodically triggers SESSION_ACTIVE events.
+
+        Like ``_idling_loop``, the event is rejected by the state machine
+        unless the runtime is in a busy session state (WAITING / STREAMING
+        / ORPHANED). Rejected events log at debug level, so a late tick
+        racing with a state transition doesn't spam warnings.
+        """
+        assert self.config.session_active_interval is not None
+        interval = self.config.session_active_interval
+        while True:
+            try:
+                await asyncio.sleep(interval)
+                self.send(ModelEvent.SESSION_ACTIVE)
+            except asyncio.CancelledError:
+                break
+            except Exception:
+                pass

{reactor_runtime-2.7.8 → reactor_runtime-2.7.9}/src/reactor_runtime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactor_runtime
-Version: 2.7.8
+Version: 2.7.9
 Summary: Reactor runtime with public model API
 Author-email: Reactor <team@reactor.inc>
 Requires-Python: >=3.9