fleetmesh-node 0.2.0__py3-none-any.whl

node/channels/bus.py

@@ -0,0 +1,331 @@
+"""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}
+
+
+class MetaDroppedWire(TypedDict):
+    count: int
+
+
+class LossyWire(TypedDict, total=False):
+    lossy: bool
+    repr: str
+    error: str
+
+
+class WindowEvaluatedWire(TypedDict, total=False):
+    peer: str
+    epoch: int
+    severity: str
+    measured: Optional[Mapping[str, int]]
+    claimed: Optional[Mapping[str, int]]
+    closed: bool
+
+
+class WindowRepricedWire(TypedDict):
+    peer: str
+    epoch: int
+    was: str
+    now: str
+
+
+class SessionCompletedWire(TypedDict, total=False):
+    peer: str
+    role: str
+    status: Optional[str]
+    counters: Optional[Mapping[str, int | float]]
+    findings: int
+
+
+class GrantIssuedWire(TypedDict):
+    peer: str
+    cause: str
+    envelope: str
+    tier: Optional[str]
+
+
+class PeerConnectedWire(TypedDict):
+    peer: str
+    role: str
+    transport: Optional[str]
+
+
+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]
+)
+
+
+class BusEnvelope(TypedDict, total=False):
+    seq: Optional[int]
+    ts: int
+    topic: str
+    data: WirePayload
+
+
+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,
+}
+
+
+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
+
+
+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)}
+
+
+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."""
+
+    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()
+
+    def wants(self, topic: str) -> bool:
+        return self.topics is None or topic in self.topics
+
+    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
+
+    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
+
+
+class Tap(object):
+    """Sequence numbers, a ring of the last `ring` envelopes, and the live subscribers."""
+
+    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()
+
+    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
+
+    def subscribe(self, topics: Optional[set[str]] = None) -> Subscriber:
+        s = Subscriber(topics, self.queue_size)
+        with self._lock:
+            self._subs.append(s)
+        return s
+
+    def unsubscribe(self, s: Subscriber) -> None:
+        with self._lock:
+            if s in self._subs:
+                self._subs.remove(s)
+
+    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
+
+    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}
+
+
+class NodeEventBus:
+    """Thread-safe synchronous in-process event bus."""
+
+    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
+
+    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)
+
+    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
+
+    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
+
+    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, ()))
+
+    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)
+
+    def clear(self) -> None:
+        """Remove all subscriptions."""
+        with self._lock:
+            self._subscribers.clear()
+            self._emit_counts.clear()

node/channels/journal.py

@@ -0,0 +1,46 @@
+"""How a node says things to its journal.
+
+These two lived in app.py, where a compartment could not reach them without
+importing the node that imports the compartment. They are not the node's:
+they are how anything in the node writes a line an operator will read.
+"""
+from __future__ import annotations
+
+import sys
+import time
+from typing import Any
+
+
+def line(*parts: Any) -> None:
+    """One timestamped line on stderr, flushed.
+
+    A node runs under systemd, where both streams are the journal, and the
+    first deployment of two of these found them completely silent: `journalctl
+    -u meshnode` held one line, the one systemd wrote itself. An operator could
+    not tell whether the node had peered, pulled, been declined or crashed
+    without reading a JSON file it had never been told about. A daemon that
+    does work says what it did.
+
+    It says it on **stderr**, and that is not cosmetic. It used to go to
+    stdout, which is also where `meshnode <cmd> --json` writes its answer, and
+    a node busy enough to say something while a command was answering put a
+    line like
+
+        2026-09-05T21:56:24Z  < acked-out 67dd799a6be0… accepted
+        [{"epoch": 496527, ...}]
+
+    on one stream. The reader got `Extra data: line 1 column 5`. node/README.md
+    offers `--json` and the control socket to "a dashboard, a metrics exporter,
+    a fleet script"; a stream that is usually parseable is not an API. So
+    stdout is the answer to what was asked, stderr is the running commentary,
+    and systemd captures both exactly as before.
+    """
+    print('%s  %s' % (time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime()),
+                      ' '.join(str(p) for p in parts)), file=sys.stderr, flush=True)
+
+
+def short(x: Any) -> str:
+    """Long hex is unreadable in a log and its first bytes identify it."""
+    s = str(x)
+    return s[:12] + '…' if len(s) > 16 and all(c in '0123456789abcdef' for c in s) else s
+

node/commands/__init__.py

@@ -0,0 +1,140 @@
+"""Pluggable command providers for the meshnode CLI.
+
+Each module under node/commands owns a group of subcommands and exposes one
+provider class with a `register(subparsers)` classmethod. PROVIDERS, in the
+order below, is the complete parser: meshnode.main iterates it and registers
+nothing else, and scripts/check-cli.py builds the same parser to hold the
+documentation to it. Command functions are imported from their own module
+(`from node.commands.transport_cmds import cmd_fips`), not re-exported here.
+
+The modules that share a name with a top-level package (compute, transport,
+cluster) carry a `_cmds` suffix. Inside this package `from .compute import X`
+and `from ..compute import X` are one character apart and name different
+modules; the suffix keeps the relative import from ever shadowing the package
+it wraps.
+
+A plugin (docs/extending.md) may bring verbs of its own. It declares them as
+a class attribute `cli = (('verb', register_fn), ...)`; `register_fn(sub)` is
+handed the same subparsers object every provider gets. `plugin_cli_classes`
+finds the plugins a `meshnode VERB DIR ...` invocation refers to by reading
+DIR's config.json (the first argument that is a node directory), or the
+`FLEETMESH_PLUGINS` environment variable (comma-separated refs) when the
+command has no directory yet; `register_plugin_cli` adds their verbs. A verb
+that collides with a core command is refused by name, like a plugin whose
+compartment name collides.
+"""
+from __future__ import annotations
+
+import argparse
+import importlib
+import os
+from typing import Any, Iterable, Protocol, Sequence, Type
+
+from .cluster_cmds import ClusterCommandProvider
+from .compute_cmds import ComputeCommandProvider
+from .core import CoreCommandProvider
+from .gossip_cmds import GossipCommandProvider
+from .nsite_cmds import NsiteCommandProvider
+from .peering import PeeringCommandProvider
+from .plugin_cmds import PluginCommandProvider
+from .sync import SyncCommandProvider
+from ..compartment import Alias, BoundCommand, Command, CommandRecord, declared, every_command
+from .sidecar_cmds import SidecarsCommandProvider
+from .transport_cmds import TransportCommandProvider
+from .video_cmds import VideoCommandProvider
+
+
+class CommandProvider(Protocol):
+    """Protocol for modular CLI command providers."""
+
+    @classmethod
+    def register(cls, subparsers: argparse._SubParsersAction) -> None:
+        """Register subcommands and argument definitions."""
+        ...
+
+
+PROVIDERS: tuple[Type[CommandProvider], ...] = (
+    CoreCommandProvider,
+    PeeringCommandProvider,
+    SyncCommandProvider,
+    ComputeCommandProvider,
+    GossipCommandProvider,
+    TransportCommandProvider,
+    ClusterCommandProvider,
+    NsiteCommandProvider,
+    SidecarsCommandProvider,
+    PluginCommandProvider,
+)
+
+PLUGINS_ENV = 'FLEETMESH_PLUGINS'
+
+
+def _import_ref(ref: str) -> Any:
+    mod_name, _, cls_name = ref.partition(':')
+    try:
+        mod = importlib.import_module(mod_name)
+    except ImportError as e:
+        raise ValueError('plugin %s: cannot import %s (%s)' % (ref, mod_name, e)) from e
+    cls = getattr(mod, cls_name, None)
+    if cls is None:
+        raise ValueError('plugin %s: %s has no %s' % (ref, mod_name, cls_name))
+    return cls
+
+
+def plugin_refs_for(argv: Sequence[str] | None) -> list[str]:
+    """The plugin refs an invocation refers to: DIR's config.json `plugins`
+    block when an argument is a node directory, else FLEETMESH_PLUGINS."""
+    refs: list[str] = []
+    for arg in (argv or ()):
+        if os.path.isfile(os.path.join(str(arg), 'config.json')):
+            try:
+                from ..app.config import load_config
+                raw = load_config(str(arg)).get('plugins') or []
+            except Exception:
+                raw = []
+            for e in raw:
+                ref = e if isinstance(e, str) else (e or {}).get('ref')
+                if isinstance(ref, str) and ref not in refs:
+                    refs.append(ref)
+            break
+    for ref in (os.environ.get(PLUGINS_ENV) or '').split(','):
+        ref = ref.strip()
+        if ref and ref not in refs:
+            refs.append(ref)
+    return refs
+
+
+def plugin_cli_classes(argv: Sequence[str] | None) -> list[Any]:
+    """The plugin classes that declare a `cli` hook, for this invocation."""
+    out: list[Any] = []
+    for ref in plugin_refs_for(argv):
+        cls = _import_ref(ref)
+        if getattr(cls, 'cli', None):
+            out.append(cls)
+    return out
+
+
+def register_plugin_cli(sub: argparse._SubParsersAction, classes: Iterable[Any]) -> list[str]:
+    """Add every `cli` verb the classes declare; returns the verbs added."""
+    added: list[str] = []
+    for cls in classes:
+        for verb, register in (getattr(cls, 'cli', None) or ()):
+            if verb in sub.choices:
+                raise ValueError('plugin %s: command %r already exists' % (getattr(cls, 'name', cls.__name__), verb))
+            register(sub)
+            added.append(verb)
+    return added
+
+
+# A literal list, not built from splats: pyflakes reads __all__ statically and
+# only a literal tells it these re-exports are used. Same reason
+# node/config/__init__.py keeps one.
+__all__ = [
+    # the declarative command surface, re-exported for compartments
+    'Alias', 'BoundCommand', 'Command', 'CommandRecord', 'declared', 'every_command',
+    # the CLI providers
+    'CommandProvider', 'PROVIDERS', 'CoreCommandProvider', 'GossipCommandProvider',
+    'NsiteCommandProvider', 'PeeringCommandProvider', 'PluginCommandProvider',
+    'SidecarsCommandProvider', 'SyncCommandProvider', 'TransportCommandProvider',
+    'VideoCommandProvider', 'register_plugin_cli',
+]