Source code for fleetmesh_node.channels.bus

"""Internal publish/subscribe event bus for decoupled node communication.

Replaces cyclic cross-subsystem dependencies and monkey-patching with an
in-process event bus. Standard library only.

The bus is synchronous and in-process. The `Tap` is how it reaches outside:
every emit is also serialised through the topic's wire function in WIRE and
appended to a ring buffer with a sequence number, and each `Subscriber`
holds a bounded queue the control socket drains. The emitting thread never
waits on a reader: a full queue drops its oldest entry and the subscriber
is told how many went by. Nothing here is durable across a restart and
nothing claims to be - a reader that needs every event replays the relays.
"""
from __future__ import annotations

import collections
import json
import queue
import threading
import time
from typing import Any, Callable, Dict, List, Mapping, Optional, TypedDict

# Standard event bus topics
TOPIC_WINDOW_EVALUATED: str = 'window.evaluated'
TOPIC_WINDOW_REPRICED: str = 'window.repriced'
TOPIC_SESSION_COMPLETED: str = 'session.completed'
TOPIC_GRANT_ISSUED: str = 'grant.issued'
TOPIC_PEER_CONNECTED: str = 'peer.connected'
TOPIC_REPORT_ADMITTED: str = 'report.admitted'
TOPIC_META_DROPPED: str = 'meta.dropped'    # only on a subscriber's own stream: {count}


[docs]class MetaDroppedWire(TypedDict): count: int
[docs]class LossyWire(TypedDict, total=False): lossy: bool repr: str error: str
[docs]class WindowEvaluatedWire(TypedDict, total=False): peer: str epoch: int severity: str measured: Optional[Mapping[str, int]] claimed: Optional[Mapping[str, int]] closed: bool
[docs]class WindowRepricedWire(TypedDict): peer: str epoch: int was: str now: str
[docs]class SessionCompletedWire(TypedDict, total=False): peer: str role: str status: Optional[str] counters: Optional[Mapping[str, int | float]] findings: int
[docs]class GrantIssuedWire(TypedDict): peer: str cause: str envelope: str tier: Optional[str]
[docs]class PeerConnectedWire(TypedDict): peer: str role: str transport: Optional[str]
[docs]class ReportAdmittedWire(TypedDict): reporter: str target: str id: str admissible: bool contradicted: bool
WirePayload = ( WindowEvaluatedWire | WindowRepricedWire | SessionCompletedWire | GrantIssuedWire | PeerConnectedWire | ReportAdmittedWire | MetaDroppedWire | LossyWire | Mapping[str, Any] )
[docs]class BusEnvelope(TypedDict, total=False): seq: Optional[int] ts: int topic: str data: WirePayload
[docs]class BusState(TypedDict): seq: int ring: int ring_max: Optional[int] subscribers: int oldest: Optional[int]
EventHandler = Callable[..., Any] WireFn = Callable[..., WirePayload] def _wire_evaluated(rec: Any) -> WindowEvaluatedWire: rec = rec if isinstance(rec, dict) else {} return {k: rec.get(k) for k in ('peer', 'epoch', 'severity', 'measured', 'claimed', 'closed') if k in rec} # type: ignore[return-value] def _wire_repriced(peer: str, epoch: int, was: str, now: str) -> WindowRepricedWire: return {'peer': peer, 'epoch': epoch, 'was': was, 'now': now} def _wire_session(peer: str, role: str, result: Any) -> SessionCompletedWire: result = result if isinstance(result, dict) else {} return {'peer': peer, 'role': role, 'status': result.get('status'), 'counters': result.get('counters'), 'findings': len(result.get('findings') or ())} def _wire_grant(peer: str, cause: str, envelope_id: str, tier: Optional[str]) -> GrantIssuedWire: return {'peer': peer, 'cause': cause, 'envelope': envelope_id, 'tier': tier} def _wire_peer(peer: str, role: str, transport: Optional[str]) -> PeerConnectedWire: return {'peer': peer, 'role': role, 'transport': transport} def _wire_report(reporter: str, target: str, event_id: str, admissible: bool, contradicted: bool) -> ReportAdmittedWire: return {'reporter': reporter, 'target': target, 'id': event_id, 'admissible': admissible, 'contradicted': contradicted} # topic -> how its emit arguments go on the wire. Every topic a node emits # has an entry, so what a subscriber sees is a decision made next to the # emit, not whatever json.dumps(default=str) makes of a Python object. A # topic with no entry is still delivered, as {"lossy": true, "repr": ...}, # so a missing entry is visible rather than a silent drop. Plugins add # their own with register_wire; they may not replace one of these. WIRE: Dict[str, WireFn] = { TOPIC_WINDOW_EVALUATED: _wire_evaluated, TOPIC_WINDOW_REPRICED: _wire_repriced, TOPIC_SESSION_COMPLETED: _wire_session, TOPIC_GRANT_ISSUED: _wire_grant, TOPIC_PEER_CONNECTED: _wire_peer, TOPIC_REPORT_ADMITTED: _wire_report, }
[docs]def register_wire(topic: str, fn: WireFn) -> None: """A plugin's own topic, with how it goes on the wire. Adds, never replaces.""" if topic in WIRE: raise ValueError('topic %s already has a wire form; a plugin may add topics, not redefine them' % topic) WIRE[topic] = fn
[docs]def to_wire(topic: str, args: tuple, kwargs: dict) -> WirePayload: fn = WIRE.get(topic) if fn is None: return {'lossy': True, 'repr': repr((args, kwargs))[:512]} try: data = fn(*args, **kwargs) json.dumps(data) # prove it is wire-safe here, on the emitting side return data except Exception as e: # a wire function must never take the emitter down return {'lossy': True, 'repr': repr((args, kwargs))[:512], 'error': '%s: %s' % (type(e).__name__, e)}
[docs]class Subscriber(object): """One reader's bounded queue. `next(timeout)` blocks for one envelope or returns None; `dropped` is how many were pushed out by a full queue since the last one the reader took, reported to it as a meta.dropped envelope."""
[docs] def __init__(self, topics: Optional[set[str]], maxsize: int) -> None: self.topics: Optional[set[str]] = topics # None: every topic self.q: queue.Queue[BusEnvelope] = queue.Queue(maxsize=maxsize) self.dropped: int = 0 self._lock = threading.Lock()
[docs] def wants(self, topic: str) -> bool: return self.topics is None or topic in self.topics
[docs] def push(self, env: BusEnvelope) -> None: with self._lock: while True: try: self.q.put_nowait(env) return except queue.Full: try: self.q.get_nowait() self.dropped += 1 except queue.Empty: return
[docs] def next(self, timeout: float) -> Optional[BusEnvelope]: with self._lock: if self.dropped: n, self.dropped = self.dropped, 0 return {'seq': None, 'ts': int(time.time()), 'topic': TOPIC_META_DROPPED, 'data': {'count': n}} try: return self.q.get(timeout=timeout) except queue.Empty: return None
[docs]class Tap(object): """Sequence numbers, a ring of the last `ring` envelopes, and the live subscribers."""
[docs] def __init__(self, ring: int = 1000, queue_size: int = 1000, clock: Optional[Callable[[], int]] = None) -> None: self.seq: int = 0 self.ring: collections.deque[BusEnvelope] = collections.deque(maxlen=ring) self.queue_size: int = queue_size self.clock: Callable[[], int] = clock or (lambda: int(time.time())) self._subs: List[Subscriber] = [] self._lock = threading.Lock()
[docs] def record(self, topic: str, args: tuple, kwargs: dict) -> BusEnvelope: data = to_wire(topic, args, kwargs) with self._lock: self.seq += 1 env: BusEnvelope = {'seq': self.seq, 'ts': self.clock(), 'topic': topic, 'data': data} self.ring.append(env) subs = [s for s in self._subs if s.wants(topic)] for s in subs: s.push(env) return env
[docs] def subscribe(self, topics: Optional[set[str]] = None) -> Subscriber: s = Subscriber(topics, self.queue_size) with self._lock: self._subs.append(s) return s
[docs] def unsubscribe(self, s: Subscriber) -> None: with self._lock: if s in self._subs: self._subs.remove(s)
[docs] def since(self, seq: int, topics: Optional[set[str]] = None, last: int = 0) -> List[BusEnvelope]: """Envelopes after `seq` still in the ring, oldest first; `last` keeps only that many newest.""" with self._lock: out = [e for e in self.ring if (e.get('seq') or 0) > seq and (topics is None or e['topic'] in topics)] return out[-last:] if last else out
[docs] def state(self) -> BusState: with self._lock: return {'seq': self.seq, 'ring': len(self.ring), 'ring_max': self.ring.maxlen, 'subscribers': len(self._subs), 'oldest': self.ring[0]['seq'] if self.ring else None}
[docs]class NodeEventBus: """Thread-safe synchronous in-process event bus."""
[docs] def __init__(self) -> None: self._subscribers: Dict[str, List[EventHandler]] = collections.defaultdict(list) self._lock: threading.RLock = threading.RLock() self._emit_counts: collections.Counter[str] = collections.Counter() self.tap: Optional[Tap] = None # set by the node; tests may leave it None
[docs] def subscribe(self, topic: str, handler: EventHandler) -> None: """Subscribe a callable to a topic.""" with self._lock: if handler not in self._subscribers[topic]: self._subscribers[topic].append(handler)
[docs] def unsubscribe(self, topic: str, handler: EventHandler) -> bool: """Unsubscribe a callable from a topic. Returns True if removed.""" with self._lock: if topic in self._subscribers: try: self._subscribers[topic].remove(handler) return True except ValueError: return False return False
[docs] def emit(self, topic: str, *args: Any, **kwargs: Any) -> List[Any]: """Emit an event to all subscribers of the topic. Exceptions in handlers are caught and isolated so other subscribers still run. Returns a list of handler return values. """ with self._lock: self._emit_counts[topic] += 1 handlers = list(self._subscribers.get(topic, ())) if self.tap is not None: self.tap.record(topic, args, kwargs) results = [] for h in handlers: try: res = h(*args, **kwargs) results.append(res) except Exception: results.append(None) return results
[docs] def subscribers(self, topic: str) -> List[EventHandler]: """Return a snapshot list of subscribers for a topic.""" with self._lock: return list(self._subscribers.get(topic, ()))
[docs] def topics(self) -> List[str]: """Return all topics that have at least one active subscriber.""" with self._lock: return [t for t, subs in self._subscribers.items() if subs]
@property def counts(self) -> collections.Counter[str]: """Return emission counts by topic.""" with self._lock: return collections.Counter(self._emit_counts)
[docs] def clear(self) -> None: """Remove all subscriptions.""" with self._lock: self._subscribers.clear() self._emit_counts.clear()