"""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 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()