Files
MeshTerm/meshterm/services/event_hub.py
T
Jean-Pierre MartineauandClaude Opus 5.5 5fc224476c Docstrings and comments of meshterm/services are in ASD-STE100
The same rewrite as for the core package. Three comments now agree with
the code: the activity bucket of the header is one minute
(ACTIVITY_BUCKET_S), the RX log holds packets, and a reference to a
module note that does not exist is gone.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-06 03:48:44 -04:00

236 lines
9.2 KiB
Python

# SPDX-License-Identifier: Apache-2.0
"""The mesh event hub, which is always on.
The hub is the only connection point between the raw event stream of the companion device
and all the code that reacts to it. It opens one subscription to the connected device. It
normalizes the data that arrives into typed :class:`~meshterm.core.events.MeshEvent`
values, and it sends each value to all the subscribers (any number of them). A one-shot
capture stops, but the hub runs for the full life of an interactive session, because a
MeshCore client must always listen. Thus subscribers come and go while the pump continues
to run below them.
This design makes the code that listens independent of the code that uses the events.
The database logging of the passive monitor is only one subscriber (refer to
:class:`~meshterm.services.monitor_service.MonitorService`). Future client features (a
live node list, an inbox for received messages) attach as more subscribers, and they do
not change the device layer.
The hub is state of the session, on the :class:`~meshterm.context.AppContext`
(``ctx.events``). The fan-out runs synchronously on the event loop when packets arrive.
Thus handlers must be fast. When a handler returns a coroutine, the hub schedules it as a
task.
"""
from __future__ import annotations
import asyncio
from collections.abc import Awaitable, Callable
from dataclasses import dataclass, field
from typing import TYPE_CHECKING
from ..core.connection import Unsubscribe
from ..core.events import EventKind, MeshEvent
if TYPE_CHECKING:
from ..context import AppContext
#: A subscriber callback. The hub calls it with each matching :class:`MeshEvent`. Keep it
#: fast, because it runs inline on the event loop when packets arrive. It can return a
#: coroutine. Then the hub schedules the coroutine as a task, and does not await it inline.
EventHandler = Callable[[MeshEvent], None | Awaitable[None]]
@dataclass(slots=True)
class _Subscription:
"""One registered subscriber: a handler, and the event kinds that it wants.
Attributes:
handler: The callback to call with matching events.
kinds: The event kinds to deliver. An empty set means all kinds.
"""
handler: EventHandler
kinds: frozenset = field(default_factory=frozenset)
def wants(self, kind: EventKind) -> bool:
"""Whether this subscription wants an event of ``kind``."""
return not self.kinds or kind in self.kinds
class EventHub:
"""Owns the event subscription to the device, and sends the events to subscribers.
Use :meth:`subscribe` or :meth:`stream` to get events. Use the async lifecycle methods
(:meth:`start`, :meth:`stop`, :meth:`aclose`) to control the pump.
"""
def __init__(self, ctx: AppContext) -> None:
"""Make an idle hub for an application context.
Args:
ctx: The shared application context. The hub uses it to open the device
connection and to log. The hub opens no device until a call to
:meth:`start`.
"""
self._ctx = ctx
self._device_unsubscribe: Unsubscribe | None = None
self._subs: list[_Subscription] = []
self._tasks: set[asyncio.Task] = set()
@property
def active(self) -> bool:
"""Whether the pump runs (with a subscription to the device)."""
return self._device_unsubscribe is not None
async def start(self) -> None:
"""Open the device subscription, and start the pump of events. Idempotent.
Opens the companion connection (which can raise an error if no device can be
selected), and subscribes to its observation stream. While the pump runs, all the
subscribers get events, if they registered before this call or after it.
Raises:
Exception: Each error from the device or the subscription goes to the caller.
The hub stays inactive, so that the caller can show the problem and try
again later.
"""
if self.active:
return
device = await self._ctx.device()
self._device_unsubscribe = await device.subscribe_events(self.publish)
self._ctx.log.info("event hub started")
async def stop(self) -> None:
"""Release the device subscription, and cancel all the scheduled handler tasks.
Idempotent. The registered subscribers stay, so a later :meth:`start` delivers to
them again.
"""
if self._device_unsubscribe is not None:
try:
self._device_unsubscribe()
finally:
self._device_unsubscribe = None
for task in list(self._tasks):
task.cancel()
self._tasks.clear()
self._ctx.log.info("event hub stopped")
def subscribe(self, handler: EventHandler, *kinds: EventKind) -> Unsubscribe:
"""Register ``handler`` for events, and return a callable that removes it.
Args:
handler: The callback that the hub calls with each matching :class:`MeshEvent`.
*kinds: The event kinds to get. Give none to get all kinds.
Returns:
A zero-argument callable that unregisters the subscription.
"""
sub = _Subscription(handler=handler, kinds=frozenset(kinds))
self._subs.append(sub)
def unsubscribe() -> None:
try:
self._subs.remove(sub)
except ValueError:
pass # already removed: unsubscribe is idempotent
return unsubscribe
def stream(self, *kinds: EventKind, maxsize: int = 0):
"""Return an async iterator that yields the matching events when they arrive.
An easy ``async for event in hub.stream(...)`` adapter on :meth:`subscribe`, with
an :class:`asyncio.Queue` below it. When the iterator closes, the subscription is
removed automatically (for example, when the ``async for`` loop breaks, or when the
consumer is cancelled).
Args:
*kinds: The event kinds to get. Give none to get all kinds.
maxsize: An optional limit on the size of the queue (``0`` = no limit).
Returns:
An async generator of :class:`MeshEvent`.
"""
queue: asyncio.Queue = asyncio.Queue(maxsize=maxsize)
unsubscribe = self.subscribe(queue.put_nowait, *kinds)
async def _iterator():
try:
while True:
yield await queue.get()
finally:
unsubscribe()
return _iterator()
def publish(self, event: MeshEvent) -> None:
"""Send ``event`` to each subscriber that wants its kind.
Delivery is synchronous and best-effort. When a handler raises an error, the hub
logs it and continues with the next handler. Thus one bad subscriber can never
stop the pump, or stop the delivery to the other subscribers. When a handler
returns a coroutine, the hub schedules it as a background task.
Args:
event: The event to deliver.
"""
for sub in list(self._subs):
if not sub.wants(event.kind):
continue
try:
result = sub.handler(event)
except Exception as exc: # noqa: BLE001 - one bad subscriber must not break the pump
self._ctx.log.debug("event hub: subscriber raised: %s", exc)
continue
if asyncio.iscoroutine(result):
self._schedule(result)
def _schedule(self, coro: Awaitable[None]) -> None:
"""Run the coroutine of an async handler as a tracked background task."""
task = asyncio.ensure_future(coro)
self._tasks.add(task)
task.add_done_callback(self._tasks.discard)
async def wait_for(
self,
*kinds: EventKind,
predicate: Callable[[MeshEvent], bool] | None = None,
timeout: float | None = None,
) -> MeshEvent | None:
"""Await the next event that matches ``kinds`` (and ``predicate``), or time out.
A one-shot helper for consumers that want to block for a specific event, instead
of a permanent handler. The method always removes the temporary subscription
before it returns.
Args:
*kinds: The event kinds to accept. Give none to accept all kinds.
predicate: An optional extra filter. To match, the event must also pass it.
timeout: The seconds to wait before the method stops, or ``None`` to wait with
no limit.
Returns:
The matching :class:`MeshEvent`, or ``None`` if the ``timeout`` ended first.
"""
loop = asyncio.get_running_loop()
future: asyncio.Future = loop.create_future()
def handler(event: MeshEvent) -> None:
if not future.done() and (predicate is None or predicate(event)):
future.set_result(event)
unsubscribe = self.subscribe(handler, *kinds)
try:
if timeout is None:
return await future
return await asyncio.wait_for(future, timeout)
except asyncio.TimeoutError:
return None
finally:
unsubscribe()
async def aclose(self) -> None:
"""Stop the pump at the end of the session (an alias for :meth:`stop`)."""
await self.stop()