fleetmesh-node 0.2.0__py3-none-any.whl

node/app/views.py

@@ -0,0 +1,204 @@
+"""Views the CLI and the control socket share: a peer's grants and windows.
+
+Separate because `meshnode peer` reads them straight from the files when no
+daemon is running, and must not import the node to do so.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Mapping, Optional, TypedDict
+
+from fleetmesh_core.accounting import accounting
+from fleetmesh_core.wire.wire_types import GrantRow, HistoryRow, PendingRow
+from ..storage import grants as grants_mod
+
+
+class GrantView(TypedDict, total=False):
+    peer: str
+    issued: Optional[GrantRow]
+    received: Optional[GrantRow]
+    issued_history: list[HistoryRow]
+    received_history: list[HistoryRow]
+    pending: Optional[PendingRow]
+    seed_applied: Optional[tuple[str, int]]
+
+
+class WindowView(TypedDict, total=False):
+    epoch: int
+    closed: int
+    severity: Optional[str]
+    measured: dict[str, int]
+    claimed: Optional[dict[str, int]]
+    receipts_in: int
+    my_usage: dict[str, int]
+    my_receipts_sent: int
+
+
+def _live_peers(grants: grants_mod.GrantStore) -> list[str]:
+    """GrantStore.peers() as a plain list of pubkeys. The store's own
+    annotation is unreadable to the checker because GrantStore.list shadows
+    the builtin in its class body (node/grants.py, not owned by this change)."""
+    raw: Any = grants.peers()
+    return [str(p) for p in raw]
+
+
+def grant_view(grants: grants_mod.GrantStore, pk: str) -> GrantView:
+    """Both grants with a peer, their history, the pending tier and the seed.
+    The same structure whether read from the files or asked of the daemon."""
+    return {
+        'peer': pk,
+        'issued': grants.get(pk, grants_mod.ISSUED),
+        'issued_history': grants.history(pk, grants_mod.ISSUED),
+        'received': grants.get(pk, grants_mod.RECEIVED),
+        'received_history': grants.history(pk, grants_mod.RECEIVED),
+        'pending': grants.pending(pk),
+        'seed_applied': grants.seed_applied(pk),
+    }
+
+
+def windows_view(source: Any, pk: str, last: int = 0) -> list[WindowView]:
+    """The windows this node priced for a peer, from an accounts database:
+    measured against claimed in the issuer frame, receipts in and sent.
+
+    `source` is an AccountStore (its `_all` takes the store lock and closes
+    the cursor before letting go - the daemon path) or a bare read-only
+    sqlite3 connection (the CLI reading the file beside a stopped or running
+    node). Either way every statement is finished and its cursor closed
+    before the next; `.fetchone()` on its own leaves the statement live to be
+    finalised by whichever thread the collector happens to run in.
+    """
+    def rows(q: str, args: tuple[Any, ...]) -> list[Any]:
+        if hasattr(source, '_all'):
+            return list(source._all(q, args))
+        cur = source.execute(q, args)
+        try:
+            return cur.fetchall()
+        finally:
+            cur.close()
+
+    def one(q: str, args: tuple[Any, ...]) -> Any:
+        got = rows(q, args)
+        return got[0] if got else None
+
+    def col(q: str, args: tuple[Any, ...]) -> list[Any]:
+        return [r[0] for r in rows(q, args)]
+
+    epochs = sorted(set(col('SELECT epoch FROM meters WHERE peer=?', (pk,)))
+                    | set(col('SELECT epoch FROM evaluated WHERE peer=?', (pk,))))
+    epochs = epochs[-last:] if last else epochs
+    out: list[WindowView] = []
+    for e in epochs:
+        sev = one('SELECT severity FROM evaluated WHERE peer=? AND epoch=?', (pk, e))
+        by = one("SELECT counters FROM meters WHERE peer=? AND epoch=? AND side='by'", (pk, e))
+        me = one("SELECT counters FROM meters WHERE peer=? AND epoch=? AND side='of_me'", (pk, e))
+        n_in = one('SELECT count(*) FROM receipts WHERE peer=? AND epoch=?', (pk, e))[0]
+        latest = one('SELECT body FROM receipts WHERE peer=? AND epoch=? ORDER BY seq DESC LIMIT 1', (pk, e))
+        chain = one('SELECT state FROM chain WHERE peer=? AND epoch=?', (pk, e))
+        out.append({'epoch': e, 'closed': accounting.window_bounds(e, 3600)[1],
+                    'severity': (sev[0] or None) if sev else 'open',
+                    'measured': json.loads(by[0]) if by else {},
+                    'claimed': json.loads(latest[0])['counters'] if latest else None,
+                    'receipts_in': n_in, 'my_usage': json.loads(me[0]) if me else {},
+                    'my_receipts_sent': json.loads(chain[0])['seq'] if chain else 0})
+    return out
+
+
+PLANES: tuple[tuple[str, str, tuple[str, ...]], ...] = (
+    ('relays',               'link',      ('relays',)),
+    ('dropped',              'link',      ('dropped',)),
+    ('recent_faults',        'link',      ('recent_faults',)),
+    ('publish_refused_in_window', 'link', ('publish_refused_in_window',)),
+    ('cooling',              'link',      ('cooling',)),
+    ('inbox',                'link',      ('inbox',)),
+    ('wraps_in',             'link',      ('wraps_in',)),
+    ('wraps_seen_again',     'link',      ('wraps_seen_again',)),
+    ('unfinished_envelopes', 'link',      ('unfinished_envelopes',)),
+    ('awaiting_ack',         'link',      ('awaiting_ack',)),
+    ('unacknowledged',       'link',      ('unacknowledged',)),
+    ('sessions_open',        'sync',      ('open',)),
+    ('sessions_refused',     'sync',      ('refused',)),
+    ('sync_unsent',          'sync',      ('unsent',)),
+    ('malformed_sync',       'sync',      ('malformed',)),
+    ('budget_rejected',      'budget',    ('rejected',)),
+    ('receipts_refused',     'budget',    ('receipts_refused',)),
+    ('malformed_complaints', 'reporter',  ('malformed',)),
+    ('peering_refused',      'peering',   ('refusals', 'recent')),
+    ('throttled',            'scheduler', ('throttled',)),
+    ('capacity',             'capacity',  ()),
+    ('strain',               'strain',    ()),
+)
+
+
+def node_health(app: Any) -> Mapping[str, Any]:
+    """Assemble the operator health report across all compartments and node planes."""
+    report = app.subsystems.report() if app._built else {}
+
+    def plane(name: str, path: tuple[str, ...]) -> Any:
+        d: Any = report.get(name)
+        if d is None:
+            return None
+        if not path:
+            return {k: v for k, v in d.items() if k != 'refusals'}
+        for key in path:
+            d = d.get(key) if isinstance(d, dict) else None
+        return d
+
+    h = {key: plane(name, path) for key, name, path in app.PLANES}
+    h.update({
+        'rejected': dict(app.rejected),
+        'handler_failures': app.counts['handler failed'],
+        'tick_failures': app.counts['tick failed'],
+        'close_failures': app.counts['close failed'],
+        'last_tick_error': app._last_tick_error,
+        'config_error': app._config_error,
+        'subsystems': report,
+        'control': app.control.state() if getattr(app, 'control', None) is not None else None,
+        'subsystem_trouble': app.subsystems.trouble() if app._built else [],
+        'subsystem_notes': app.subsystems.notes() if app._built else [],
+    })
+    return h
+
+
+def node_status(app: Any) -> Mapping[str, Any]:
+    """Assemble the complete status.json view for a running or stopped NodeApp."""
+    from .. import release as release_mod
+    from ..interfaces import EvaluationRow, GrantStatusRow, PendingGrantRow, RepricedRow
+
+    h = app.health()
+    subs = h['subsystems']
+
+    def has(name: str, key: str, default: int = 0) -> Any:
+        return (subs.get(name) or {}).get(key, default)
+
+    face_url = app.face.url if app.face is not None else (app.host.url if getattr(app, 'host', None) is not None else '')
+    st = {
+        'did': app.ks.did,
+        'class': app.cfg['class'],
+        'face': face_url,
+        'release': release_mod.running().as_dict(),
+        'relays': app.relays,
+        'descriptor': app.descriptor['id'] if app.descriptor else None,
+        'peers': _live_peers(app.grants),
+        'grants': [GrantStatusRow(peer=g['peer'][:16], direction=g['direction'], tier=g['payload'].get('tier'),
+                                  status=g['status']) for g in app.grants.list()],
+        'evaluations': [EvaluationRow(peer=r.peer[:16], epoch=r.epoch, severity=r.severity,
+                                      state=r.state) for r in app.budget.evaluations[-10:]] if app._built else [],
+        'repriced': [RepricedRow(peer=r.peer[:16], epoch=r.epoch, was=r.was,
+                                 severity=r.severity, remedy_cancelled=r.remedy_cancelled)
+                     for r in app.budget.repriced[-5:]] if app._built else [],
+        'pending_grants': [PendingGrantRow(peer=p[:16], tier=pend['payload'].get('tier'),
+                                           from_epoch=pend['decided_epoch'] + 1)
+                           for p in _live_peers(app.grants)
+                           if (pend := app.grants.pending(p)) is not None],
+        'refused_sessions': has('sync', 'refused'),
+        'reports_published': has('reporter', 'published'),
+        'pending_findings': has('reporter', 'pending'),
+        'events_stored': app.store.count(),
+        'at': app.clock(),
+        'health': h,
+    }
+    if app._last_tick:
+        st['last_tick'] = [list(map(str, d)) for d in app._last_tick]
+    return st
+
+

node/channels/__init__.py

@@ -0,0 +1,378 @@
+"""What a compartment says, declared where the compartment is.
+
+A package rather than a root module: node/*.py is held to a monotone
+baseline (fleetmesh.org/scripts/check-root.py) so the flat root stops
+growing, and this is new surface rather than one of the dozen things
+everything leans on.
+
+A node has two ways of saying something happened and they are not connected.
+`journal.line` prints a timestamped prose line to stderr - 45 call sites, each
+formatting its own text, no levels and no channel. `NodeEventBus.emit` carries
+a structured event through `WIRE` to the control socket's `Tap` - 6 call
+sites, seven topic names, all of them declared in eventbus.py rather than by
+the compartment that emits them.
+
+So a compartment chooses a path by hand, and the two carry different events.
+`pulled` is printed and invisible to the socket; `session.completed` is
+emitted and absent from the log. An operator reading `journalctl` and a
+dashboard reading the socket are looking at different nodes.
+
+A `Channel` is one event declared once, in the compartment that raises it,
+with both renderings attached: `wire` for a reader, `say` for a person. A
+compartment emits once. `Log` subscribes to every declared channel and fans
+out to the backends an operator configured. Nothing picks a path.
+
+That is the same move `Parameter` makes for config and the same reason: two
+expressions of one fact, kept in step by hand, is how a node comes to tell an
+operator something other than what it did.
+
+Backends are additive and each is cheap:
+
+    console   journal.line, the existing stderr format, unchanged
+    tap       the existing control-socket ring buffer
+    file      newline-delimited JSON at a configured path
+
+Standard library only, and the console backend keeps `journal.line`'s format
+exactly so no operator's eye or log scraper has to relearn anything.
+"""
+from __future__ import annotations
+
+import dataclasses
+import json
+import os
+import threading
+from typing import Any, Callable, Iterable, Mapping, Optional, Sequence, TypedDict, Union
+
+from . import bus, journal
+from .journal import line, short
+from .bus import (
+    TOPIC_WINDOW_EVALUATED, TOPIC_WINDOW_REPRICED, TOPIC_SESSION_COMPLETED,
+    TOPIC_GRANT_ISSUED, TOPIC_PEER_CONNECTED, TOPIC_REPORT_ADMITTED,
+    TOPIC_META_DROPPED, EventHandler, WireFn, WIRE, register_wire, to_wire,
+    Subscriber, Tap, NodeEventBus,
+)
+
+# Levels. Deliberately three, matching the vocabulary the node already uses in
+# `trouble()` and `notes()` rather than importing syslog's eight, none of which
+# this tree has ever distinguished.
+INFO, NOTE, TROUBLE = 'info', 'note', 'trouble'
+LEVELS: tuple[str, ...] = (INFO, NOTE, TROUBLE)
+
+
+class Record(TypedDict):
+    """One event as a backend receives it."""
+    channel: str
+    level: str
+    at: int
+    payload: Mapping[str, Any]
+    said: str
+
+
+class ChannelRecord(TypedDict, total=False):
+    """A channel as `meshnode channels` and the docs read it.
+
+    Named records rather than loose mappings, for the reason check-dicts.py
+    enforces it: a row an operator reads by field name is the case that rule
+    exists for. `compartment` is absent until `every_channel` adds it.
+    """
+    name: str
+    description: str
+    level: str
+    tags: list[str]
+    compartment: str
+
+
+class LogState(TypedDict):
+    """What the log itself is doing, for the health block."""
+    backends: list[str]
+    channels: int
+    undeclared: dict[str, int]
+    failures: dict[str, int]
+
+
+@dataclasses.dataclass(frozen=True)
+class Channel:
+    """One thing a compartment can say, with both of its renderings.
+
+    `wire` is the structured payload a reader gets, which is what `WIRE` in
+    eventbus.py already holds per topic. `say` is the line a person reads,
+    which is what the 45 `journal.line` call sites each build inline. Keeping
+    them together is the point: an event cannot now exist in one and not the
+    other.
+    """
+    name: str
+    description: str
+    level: str = INFO
+    wire: Optional[Callable[..., Mapping[str, Any]]] = None
+    # The human line. A format string is preferred and a callable is the
+    # fallback: a string is data, so it can be rendered into the docs,
+    # checked against the payload it formats, and changed without touching
+    # code. A callable is for a line that needs a conditional, which most do
+    # not.
+    say: Union[str, Callable[..., str], None] = None
+    tags: tuple[str, ...] = ()
+
+    def payload(self, *args: Any, **kw: Any) -> Mapping[str, Any]:
+        if self.wire is None:
+            return {'args': [journal.short(a) for a in args], **kw}
+        return self.wire(*args, **kw)
+
+    def said(self, *args: Any, **kw: Any) -> str:
+        """The human line, from the format string or the callable.
+
+        A format string is rendered against the wire payload, so the two
+        renderings cannot describe different fields. A field the payload does
+        not carry is reported in the line rather than raised: a log must not
+        be able to fail the thing it is logging.
+        """
+        if self.say is None:
+            return '%s %s' % (self.name, ' '.join(journal.short(a) for a in args))
+        if isinstance(self.say, str):
+            payload = self.payload(*args, **kw)
+            try:
+                return self.say.format(**payload)
+            except (KeyError, IndexError, ValueError) as e:
+                return '%s (unformattable line: %s) %s' % (self.name, e, dict(payload))
+        return self.say(*args, **kw)
+
+    def fields(self) -> tuple[str, ...]:
+        """The payload fields the format string names, for the docs and for a
+        check that a line and its payload agree."""
+        if not isinstance(self.say, str):
+            return ()
+        import string  # noqa: PLC0415
+        return tuple(f for _lit, f, _spec, _c in string.Formatter().parse(self.say) if f)
+
+    def describe(self) -> ChannelRecord:
+        return {'name': self.name, 'description': self.description,
+                'level': self.level, 'tags': list(self.tags)}
+
+
+def declared(obj: Any) -> tuple[Channel, ...]:
+    """The channels a compartment declares, or () for one not yet converted."""
+    return tuple(getattr(obj, 'CHANNELS', ()) or ())
+
+
+def every_channel(compartments: Sequence[Any]) -> list[ChannelRecord]:
+    """Every declared channel, for `meshnode channels` and the docs.
+
+    The companion of `every_parameter`: one list of what a node can say, as
+    that one is a list of what it can be told.
+    """
+    out: list[ChannelRecord] = []
+    for c in compartments:
+        for ch in declared(c):
+            row = ch.describe()
+            # A compartment names itself `name`; a config block names itself
+            # `key`. Both declare channels, so both spellings are read rather
+            # than one of them silently falling back to the class name.
+            row['compartment'] = (getattr(c, 'name', '') or getattr(c, 'key', '')
+                                  or getattr(c, '__name__', str(c)))
+            out.append(row)
+    return out
+
+
+# ---------------------------------------------------------------- backends
+
+class Backend:
+    """Somewhere a record goes. Subclasses implement `write`."""
+    name: str = 'backend'
+
+    def write(self, rec: Record) -> None:
+        raise NotImplementedError
+
+    def close(self) -> None:
+        pass
+
+
+class ConsoleBackend(Backend):
+    """`journal.line`, byte for byte as before.
+
+    The format is not re-invented: a node runs under systemd, an operator's
+    eye is trained on these lines and so is anything grepping them.
+    """
+    name = 'console'
+
+    def __init__(self, min_level: str = INFO) -> None:
+        self.floor: int = LEVELS.index(min_level) if min_level in LEVELS else 0
+
+    def write(self, rec: Record) -> None:
+        if LEVELS.index(rec['level']) < self.floor:
+            return
+        journal.line(rec['said'])
+
+
+class TapBackend(Backend):
+    """The control socket's ring buffer, which already exists.
+
+    Wrapping it rather than replacing it: the Tap holds the sequence numbers
+    and the bounded per-subscriber queues, and a reader that drains it today
+    keeps working.
+    """
+    name = 'tap'
+
+    def __init__(self, tap: Any) -> None:
+        self.tap = tap
+
+    def write(self, rec: Record) -> None:
+        if self.tap is not None:
+            self.tap.record(rec['channel'], (), dict(rec['payload']))
+
+
+class FileBackend(Backend):
+    """Newline-delimited JSON at a path, one record per line.
+
+    Opened append-only and flushed per record, because a log that loses its
+    tail on a crash loses exactly the part being asked about.
+    """
+    name = 'file'
+
+    def __init__(self, path: str, min_level: str = INFO) -> None:
+        self.path = path
+        self.floor: int = LEVELS.index(min_level) if min_level in LEVELS else 0
+        self._lock = threading.Lock()
+        d = os.path.dirname(os.path.abspath(path))
+        if d:
+            os.makedirs(d, exist_ok=True)
+
+    def write(self, rec: Record) -> None:
+        if LEVELS.index(rec['level']) < self.floor:
+            return
+        with self._lock:
+            with open(self.path, 'a', encoding='utf-8') as fh:
+                fh.write(json.dumps(rec, separators=(',', ':'), default=str) + '\n')
+
+
+class MemoryBackend(Backend):
+    """Keeps records in a list. For tests, and for asking what just happened."""
+    name = 'memory'
+
+    def __init__(self, cap: int = 1000) -> None:
+        self.records: list[Record] = []
+        self.cap = cap
+
+    def write(self, rec: Record) -> None:
+        self.records.append(rec)
+        if len(self.records) > self.cap:
+            del self.records[0]
+
+
+# -------------------------------------------------------------------- the log
+
+class Log:
+    """The one place a declared channel reaches a backend.
+
+    A compartment calls `log.say(channel, ...)` once. Where that goes is the
+    operator's configuration, not the compartment's decision, which is the
+    whole point: before this, choosing `journal.line` meant the socket never
+    saw it and choosing `emit` meant the journal never did.
+
+    A backend that raises is isolated and the others still run - the same rule
+    `NodeEventBus.emit` already applies to handlers, for the same reason: a
+    log that can take the node down is worse than no log.
+    """
+
+    def __init__(self, backends: Iterable[Backend] = (),
+                 clock: Optional[Callable[[], int]] = None,
+                 bus: Any = None, monitors: Any = None) -> None:
+        self.backends: list[Backend] = list(backends)
+        self.clock: Callable[[], int] = clock or (lambda: int(__import__('time').time()))
+        self.bus = bus
+        # The metrics registry, when the node has one. A counter declared
+        # against a channel is fed from here, so one declaration drives both
+        # the line and the count and the two cannot disagree about how many
+        # there were. See node/metrics.
+        self.monitors = monitors
+        self.registry: dict[str, Channel] = {}
+        self.unknown: dict[str, int] = {}
+        self.failures: dict[str, int] = {}
+
+    def register(self, channels: Iterable[Channel]) -> None:
+        """Declare channels. Called once per compartment at assembly."""
+        for ch in channels:
+            self.registry[ch.name] = ch
+
+    def register_from(self, compartments: Iterable[Any]) -> None:
+        for c in compartments:
+            self.register(declared(c))
+
+    def say(self, name: str, *args: Any, **kw: Any) -> Record:
+        """Raise `name`, rendering it once for every backend.
+
+        An unregistered channel is still carried, and counted. Dropping it
+        would make a compartment's new event silently invisible, which is the
+        failure this file exists to remove; counting it is how the gap gets
+        noticed.
+        """
+        ch = self.registry.get(name)
+        if ch is None:
+            self.unknown[name] = self.unknown.get(name, 0) + 1
+            ch = Channel(name=name, description='(undeclared)')
+        # Rendering is the caller's arguments meeting the channel's own
+        # functions, so it can fail - a raise site passing the wrong number of
+        # them is the obvious way. It must not fail the caller: a log that can
+        # take down the thing it is logging is worse than no log, and the
+        # moment it does so is the moment something was already going wrong.
+        # The record still goes out, carrying what the failure was.
+        try:
+            payload: Mapping[str, Any] = ch.payload(*args, **kw)
+        except Exception as e:
+            self.failures['payload'] = self.failures.get('payload', 0) + 1
+            payload = {'error': '%s: %s' % (type(e).__name__, e),
+                       'args': [journal.short(a) for a in args]}
+        try:
+            said = ch.said(*args, **kw)
+        except Exception as e:
+            self.failures['said'] = self.failures.get('said', 0) + 1
+            said = '%s (unsayable: %s: %s)' % (ch.name, type(e).__name__, e)
+        rec: Record = {'channel': ch.name, 'level': ch.level, 'at': self.clock(),
+                       'payload': payload, 'said': said}
+        for b in self.backends:
+            try:
+                b.write(rec)
+            except Exception:
+                self.failures[b.name] = self.failures.get(b.name, 0) + 1
+        if self.monitors is not None:
+            try:
+                self.monitors.observe(ch.name)
+            except Exception:
+                self.failures['monitors'] = self.failures.get('monitors', 0) + 1
+        if self.bus is not None:
+            # The in-process bus keeps working for anything that subscribed to
+            # a topic by name, so converting a compartment does not unsubscribe
+            # whatever was already listening.
+            try:
+                self.bus.emit(ch.name, **dict(rec['payload']))
+            except Exception:
+                self.failures['bus'] = self.failures.get('bus', 0) + 1
+        return rec
+
+    def state(self) -> LogState:
+        """What the log itself is doing, for the health block.
+
+        `undeclared` and `failures` are reported rather than kept quiet: a log
+        dropping records, or carrying channels nobody declared, is the kind of
+        thing that is invisible precisely when it matters.
+        """
+        out: LogState = {'backends': [b.name for b in self.backends],
+                         'channels': len(self.registry),
+                         'undeclared': dict(self.unknown),
+                         'failures': dict(self.failures)}
+        return out
+
+    def close(self) -> None:
+        for b in self.backends:
+            try:
+                b.close()
+            except Exception:
+                pass
+
+
+__all__ = ['Channel', 'ChannelRecord', 'Record', 'LogState', 'Log', 'Backend',
+           'ConsoleBackend', 'TapBackend',
+           'FileBackend', 'MemoryBackend', 'declared', 'every_channel',
+           'INFO', 'NOTE', 'TROUBLE', 'LEVELS',
+           'TOPIC_WINDOW_EVALUATED', 'TOPIC_WINDOW_REPRICED', 'TOPIC_SESSION_COMPLETED',
+           'TOPIC_GRANT_ISSUED', 'TOPIC_PEER_CONNECTED', 'TOPIC_REPORT_ADMITTED',
+           'TOPIC_META_DROPPED', 'EventHandler', 'WireFn', 'WIRE', 'register_wire', 'to_wire',
+           'Subscriber', 'Tap', 'NodeEventBus', 'bus', 'journal', 'line', 'short']