Source code for fleetmesh_node.app.control

"""The operator's face of the node: the control-socket dispatcher, the
actions only the daemon can take, and the shims that forward to compartments.

A mixin, not a module of functions, because every method here reads and
writes the node's own state (`self.grants`, `self.peering`, `self.cfg`) and
tests and the CLI call them as NodeApp methods. NodeApp in core.py inherits
it; nothing else does.
"""
from __future__ import annotations

import collections
import threading
from typing import TYPE_CHECKING, Any, Callable, Mapping, MutableMapping, Optional, Sequence, TypedDict, cast

from ..interfaces import CommandSpec, VisibilityState

from fleetmesh_core.accounting import accounting, standing, window
from fleetmesh_core.identity import identity
from fleetmesh_core.network import grant as grant_mod, group as group_mod
from fleetmesh_core.services import lifecycle
from fleetmesh_core.storage import store as store_mod
from fleetmesh_core.wire.interfaces import GrantPayload, NostrEvent, StandingTellBody
from .. import (channels as channels_mod,
                release as release_mod, transport as transport_mod)
from ..planes.identity import visibility as visibility_mod
from ..config import VisibilityConfig
from ..channels.bus import BusEnvelope, BusState
from . import authority, enrol as enrol_mod, socket as control_mod
from ..storage import grants as grants_mod
from ..protocols.nostr import client as relay, descriptor  # noqa: E402
from ..channels.journal import line as _line, short as _short
from ..compartment.command import CommandError
from ..compartment import lifecycle as compartment_lifecycle
from .commands import NODE_COMMANDS_BY_KEY
from .config import CONTROL, save_config
from .views import GrantView, WindowView, _live_peers, grant_view, windows_view

if TYPE_CHECKING:
    from .. import compartment as compartment_mod, keystore
    from ..protocols.nostr import peers as peers_mod
    from ..planes.peering import budget as budget_mod, peering as peering_wire, reporter as reporter_mod
    from ..planes.store import sync as sync_wire
    from ..storage import accounts as accounts_mod
    from ..planes.identity.discovery import compartment as discovery_wire
from ..planes.identity.presence import compartment as presence_mod
from ..planes.operations.scheduler import compartment as scheduler_mod


MAX_PULL_TIMEOUT = 600          # an operator-driven pull holds a connection slot and a sync session this long at most


VersionResult = TypedDict('VersionResult', {
    'protocol': str,
    'fleetmesh': str,
    'digest': str,
    'release': Mapping[str, Optional[str]],
    'did': str,
    'pubkey': str,
    'class': str,
    'commands': list[str],
})


[docs]class CommandDetail(CommandSpec, total=False): name: str
[docs]class RepublishResult(TypedDict): descriptor: str relays: Mapping[str, tuple[bool, str]]
[docs]class EnrolResult(enrol_mod.Outcome): """`enrol` reply: the Outcome plus what went out (plan D18/D19).""" descriptor: Optional[str] # None only before start() built one heartbeat: Optional[str] relays: Mapping[str, tuple[bool, str]]
[docs]class EventsResult(BusState): topics: list[str] events: list[BusEnvelope]
[docs]class StandingResult(TypedDict): answer: str body: Optional[Mapping[str, Any]]
[docs]class ReportItem(TypedDict): reporter: str severity: Optional[str] admissible: bool reasons: list[str] weight: float id: str created_at: int
[docs]class ReportsResult(TypedDict): view: str reports: list[ReportItem]
[docs]class PeerGrantSummary(TypedDict): tier: Optional[str] status: str
[docs]class PeerPendingSummary(TypedDict): tier: Optional[str] from_epoch: int
[docs]class PeerEvaluationSummary(TypedDict): epoch: int severity: Optional[str] state: str
[docs]class PeerViewRow(TypedDict): peer: str issued: Optional[PeerGrantSummary] received: Optional[PeerGrantSummary] pending: Optional[PeerPendingSummary] last_evaluated: Optional[PeerEvaluationSummary] standing: Optional[StandingTellBody] zeroed_until: Optional[int] pulls: list[str] descriptor: Optional[str] shared: list[str] not_shared: list[str] digest: Optional[str] notices: list[str]
[docs]class RefusalResult(TypedDict): subsystem: str | None at: int kind: str subject: str | None why: str detail: Mapping[str, Any] | str
[docs]class SubsystemStateResult(TypedDict): name: str state: str
[docs]class RetireSteps(TypedDict, total=False): reason: str at: int did: list[list[Any]] peers: list[str] handed: int withdrawn: int revoked: bool
[docs]class TerminateResult(TypedDict): peer: str reason: str told: Mapping[str, Any] pulls_removed: int
def _arg_int(cmd: str, args: Mapping[str, Any], name: str, default: int) -> int: v = args.get(name) if v is None: return default if isinstance(v, bool) or not isinstance(v, (int, float, str)): raise control_mod.ControlError('%s: %s must be an integer' % (cmd, name)) try: out = int(v) except (TypeError, ValueError): raise control_mod.ControlError('%s: %s must be an integer, not %r' % (cmd, name, str(v)[:32])) if out < 0: raise control_mod.ControlError('%s: %s must not be negative' % (cmd, name)) return out def _arg_float(cmd: str, args: Mapping[str, Any], name: str, default: float) -> float: v = args.get(name) if v is None: return default if isinstance(v, bool) or not isinstance(v, (int, float, str)): raise control_mod.ControlError('%s: %s must be a number' % (cmd, name)) try: out = float(v) except (TypeError, ValueError): raise control_mod.ControlError('%s: %s must be a number, not %r' % (cmd, name, str(v)[:32])) if out != out or out in (float('inf'), float('-inf')): raise control_mod.ControlError('%s: %s must be finite' % (cmd, name)) return out def _arg_hex(cmd: str, args: Mapping[str, Any], name: str) -> str: """A 64-hex pubkey, lower-cased. Everything downstream keys tables on it.""" v = args.get(name) if not isinstance(v, str) or len(v) != 64: raise control_mod.ControlError('%s: %s must be a 64-hex pubkey' % (cmd, name)) try: bytes.fromhex(v) except ValueError: raise control_mod.ControlError('%s: %s must be a 64-hex pubkey' % (cmd, name)) return v.lower() def _topics_arg(raw: Any) -> set[str] | None: if raw is None or raw == []: return None if isinstance(raw, str): raw = [t for t in raw.split(',') if t] if not isinstance(raw, list) or not all(isinstance(t, str) for t in raw): raise control_mod.ControlError('topics is a list of topic names; `events` lists them') return set(raw)
[docs]class ControlMixin(object): # What the mixin reads off the node it is mixed into. Declarations only, # for the checker; NodeApp.__init__ and start() assign every one of them. if TYPE_CHECKING: dir: str cfg: MutableMapping[str, Any] clock: Callable[[], int] relays: list[str] ks: keystore.Keystore grants: grants_mod.GrantStore accounts: accounts_mod.AccountStore peers: peers_mod.Peers transport: transport_mod.TransportRouter ledger: standing.Ledger timeout: float _stop: threading.Event _built: bool subsystems: compartment_mod.Registry events: channels_mod.NodeEventBus peering: peering_wire.Peering budget: budget_mod.Budget sync: sync_wire.SyncPeer reporter: reporter_mod.Reporter discovery: discovery_wire.Discovery presence: presence_mod.Presence scheduler: scheduler_mod.Scheduler descriptor: Any revocation_lists: list[Mapping[str, Any]] groups: Any log: collections.deque[Any] counts: collections.Counter[str] GROUP_FRESH_SECONDS: int def _descriptor(self) -> NostrEvent: ... def public_descriptor(self) -> Optional[NostrEvent]: ... def publish_descriptor(self) -> Mapping[str, Any]: ... def visibility_config(self) -> VisibilityConfig: ... _published_public_id: Optional[str] def _network_relays(self) -> list[str]: ... def poll_group(self, now: int, force: bool = False, max_age: Optional[int] = None) -> int: ... def poll_revocations(self, authors: Sequence[str], now: int, max_age: Optional[int] = None) -> int: ... def build_descriptor(self) -> NostrEvent: ... def tick(self, now: int | None = None) -> list[tuple[Any, ...]]: ... def status(self) -> Mapping[str, Any]: ... def health(self) -> Mapping[str, Any]: ...
[docs] def control_request(self, cmd: str, args: Mapping[str, Any], actor: Any = None) -> Any: """Answer one control request, recording who asked. `actor` is built at the socket boundary (fleetmesh_node/control.py:actor_of), because SO_PEERCRED can only be read off a live connection and by the time a command runs the socket is gone. It is held in a ContextVar (fleetmesh_node/config/change.py:ACTING) for the length of this request, so a config change raised during the command is attributed to the person who caused it - and only to them. An attribute on the node was shared by every connection thread, so two concurrent requests could swap authors. Nothing here checks an ability. `Command.permission` and `Parameter.requires` are declared and unenforced on purpose: this socket is chmod 0o600, so everyone who can reach it is already the owner, and a check against that is a control which protects nothing while reading as though it does. Enforcement belongs with a principal that is not already the owner - a UCAN delegation over the wire, or a socket opened to several unix users - and the markers come off then. """ from ..config import change as change_mod # noqa: PLC0415 with change_mod.acting_as(actor): try: return self._answer_request(cmd, args) except CommandError as e: # The caller's mistake, checked against the declaration: a # refusal they read, kept out of the ring that counts bugs. raise control_mod.ControlError(str(e))
@property def acting(self) -> Any: """The actor of the request running on this thread, or None.""" from ..config import change as change_mod # noqa: PLC0415 return change_mod.acting() # ---- the wire ------------------------------------------------------------------
[docs] def operator_did(self) -> Optional[str]: """The operator DID this node publishes (plan D7): the descriptor's `operator` tag, the config's before the first build; None when unset.""" return authority.operator_of(getattr(self, 'descriptor', None), getattr(self, 'cfg', None))
[docs] def permission_of(self, cmd: str) -> Optional[str]: """The ability a command declares: '' when it declares none, None when the command does not exist. Read off the same declarations the table is built from, so it cannot name a command the table lacks.""" if cmd not in self.commands(): return None cmd_obj = NODE_COMMANDS_BY_KEY.get(cmd) if cmd_obj is not None: return str(getattr(cmd_obj, 'permission', '') or '') sub, _, key = cmd.partition('.') s = self.subsystems.get(sub) if self._built else None for declared in (getattr(s, 'COMMANDS', ()) or ()): if getattr(declared, 'key', None) == key: return str(getattr(declared, 'permission', '') or '') return ''
[docs] def wire_decide(self, cmd: str, sender: str, authenticated: bool, chain: Any, now: Optional[int] = None) -> authority.Verdict: """Whether `sender`, proven by the transport and carrying `chain`, may run `cmd` here: the verdict, never an exception. The revocation lists are the kind 30833s this node has been handed (`revocation_lists`) plus those in its ledger; before deciding, the lists signed by the operator and by every issuer in `chain` are refreshed from the relays when older than GROUP_FRESH_SECONDS, so a revocation counts at once.""" when = self.clock() if now is None else now op = self.operator_did() self.poll_revocations(authority.revocation_authors(op, chain), when, max_age=self.GROUP_FRESH_SECONDS) group_events: tuple[Mapping[str, Any], ...] = () early: tuple[str, ...] = () if op and op.startswith('did:group:'): # a member's revocation or a new epoch must count now, not at the next poll self.poll_group(when, max_age=self.GROUP_FRESH_SECONDS) # first sight of these copies is now, before the verdict (plan D20) if isinstance(chain, (list, tuple)) and chain and self.groups.add_copies(chain[0]): self.groups.save() group_events = tuple(self.groups.group_events()) early = tuple(self.groups.early(op, when)) return authority.decide(op, self.ks.node_pk, cmd, self.permission_of(cmd), sender, authenticated, chain, when, tuple(self.revocation_lists) + tuple(self.groups.revocations), group_events, early)
[docs] def wire_request(self, cmd: str, args: Mapping[str, Any], sender: str, authenticated: bool, chain: Any, now: Optional[int] = None, session: str = '') -> Any: """One control command that came through a transport (plan D7). `sender` and `authenticated` are what open_inbound established - the authcrypt skid, the seal's signer - and `chain` is the kind 30832 chain the message carried ([] when the sender is the operator). The command runs only when authority.decide accepts; a refusal is a ControlError whose text starts with `refused <code>`, and both are written to the log with the actor's ladder so the audit trail says what was checked. This is the one door for the wire: a transport handler that receives a control message calls this and nothing else, and the local socket (Node.control_request) stays the owner's. """ verdict = self.wire_decide(cmd, sender, authenticated, chain, now) actor = authority.actor_of(verdict, session=session, at=self.clock()) if not verdict['accepted']: self.log.append(('wire refused', cmd, verdict['code'], actor.describe())) self.counts['wire refused'] += 1 raise control_mod.ControlError(authority.refusal_text(verdict)) self.log.append(('wire accepted', cmd, verdict['via'], actor.describe())) self.counts['wire accepted'] += 1 return self.control_request(cmd, args, actor)
def _answer_request(self, cmd: str, args: Mapping[str, Any]) -> Any: """One request over the control socket, dispatched on CONTROL. Reads answer from the daemon's live state; actions are the things only the daemon can do. The config file is the way to change what the node is told to do.""" table = self.commands() if cmd not in table: raise control_mod.ControlError('unknown command %r; `commands` lists the %d this socket answers' % (str(cmd)[:32], len(table))) missing = [k for k, v in table[cmd]['args'].items() if v == 'required' and k not in args] if missing: raise control_mod.ControlError('%s needs %s' % (cmd, ', '.join(missing))) cmd_obj = NODE_COMMANDS_BY_KEY.get(cmd) if cmd_obj is not None: return cmd_obj.execute(self, args) if self._built and cmd in self.subsystems.commands(): return self.subsystems.dispatch(cmd, dict(args)) raise control_mod.ControlError('%s is in the table and not in the dispatcher' % cmd) # ---- node command handlers -----------------------------------------------------
[docs] def cmd_version(self) -> VersionResult: return {'protocol': control_mod.PROTOCOL, 'fleetmesh': descriptor.VERSION, 'digest': descriptor.DIGEST, 'release': release_mod.running().as_dict(), 'did': self.ks.did, 'pubkey': self.ks.node_pk, 'class': self.cfg['class'], 'commands': list(self.commands())}
[docs] def cmd_commands(self) -> list[CommandDetail]: return [dict(name=name, **spec) for name, spec in self.commands().items()]
[docs] def cmd_subsystems(self) -> Mapping[str, Mapping[str, Any]]: return self.subsystems.report()
[docs] def cmd_lifecycle(self) -> Mapping[str, compartment_lifecycle.LifecycleRecord]: return self.subsystems.lifecycle()
[docs] def cmd_tick(self) -> list[list[Any]]: return [list(d) for d in self.tick()]
[docs] def cmd_republish(self) -> RepublishResult: public = self.public_descriptor() return {'descriptor': (public or self._descriptor())['id'], 'relays': dict(self.publish_descriptor())}
LEDGER_MAX_EVENTS: int = 256
[docs] def cmd_ledger(self, args: Mapping[str, Any]) -> Mapping[str, Any]: """Signed revocation lists and circle documents handed over control (plan D26). Only events whose signature verifies are kept; the ledger applies the same rules as to fetched ones, so a hand-over can revoke only what its signer issued and can never grant anything.""" events = args.get('events') if not isinstance(events, list): raise control_mod.ControlError('events must be a list of signed nostr events') if len(events) > self.LEDGER_MAX_EVENTS: raise control_mod.ControlError('at most %d events at a time' % self.LEDGER_MAX_EVENTS) good = [e for e in events if isinstance(e, Mapping) and e.get('kind') in (30833, 30834) and store_mod.verify_event(e)] added = (self.groups.add_revocations([e for e in good if e['kind'] == 30833]) + self.groups.add_docs([e for e in good if e['kind'] == 30834])) if added: self.groups.save() self.check_enrolment() return {'received': len(events), 'verified': len(good), 'added': added}
[docs] def check_enrolment(self, now: Optional[int] = None) -> Optional[str]: """Plan D22: an enrolment lasts until it is revoked. When a kind 30833 the node holds names its enrolment's `token_id` - signed by the operator (a person), or for a circle by a controller of its current epoch - the node clears its operator and enrolment, saves the config and rebuilds its descriptor, and answers the old operator no more. Returns the operator it left, or None.""" enr = self.cfg.get('enrolment') if not isinstance(enr, Mapping): return None tid, op = enr.get('token_id'), enr.get('operator') if not isinstance(tid, str) or not tid or not isinstance(op, str) or not op: return None lists = tuple(self.revocation_lists) + tuple(self.groups.revocations) if not lists: return None when = self.clock() if now is None else now if op.startswith('did:group:'): try: g = group_mod.resolve(self.groups.group_events(), op, when) except group_mod.GroupRefused: return None # a circle that does not resolve cannot be heard revoking ended = group_mod.revoked(g, lists, tid) else: ended = grant_mod.revoked_by_issuer(lists, op, tid) if not ended: return None self.cfg['operator'] = None self.cfg.pop('enrolment', None) self.save_coverage() self.build_descriptor() self.log.append((when, 'enrolment revoked', op, tid)) self.counts['enrolment revoked'] += 1 _line(' enrolment revoked by', op, '(grant', _short(tid) + '…): this node has no operator now') return op
[docs] def cmd_enrol(self, args: Mapping[str, Any]) -> EnrolResult: return self.enrol(args.get('token'), bool(args.get('force', False)))
[docs] def enrol(self, token: Any, force: bool = False) -> EnrolResult: """Join the fleet an enrol token names (plan D18/D19; fleetmesh_node/app/enrol.py for the policy). The token is verified by fleetmesh_core's grant verifier against THIS node's key, the clock now and the kind 30833 lists seen; then the operator goes into config.json (`operator`, `enrolment`) so a restart keeps it, and the descriptor and a heartbeat go out at once so the operator's fleet shows the node without waiting for the next renewal.""" now = self.clock() try: v = enrol_mod.verify(token, self.ks.node_pk, now, tuple(self.revocation_lists) + tuple(self.groups.revocations)) previous = self.operator_did() changed = enrol_mod.plan(previous, v, force) except enrol_mod.EnrolRefused as e: self.counts['enrol refused'] += 1 self.log.append((now, 'enrol refused', e.code, e.detail)) raise control_mod.ControlError('refused %s%s' % (e.code, (': ' + e.detail) if e.detail else '')) if changed and enrol_mod.pin(self.groups, v): self.groups.save() out = cast(EnrolResult, dict(enrol_mod.outcome(v, changed, previous, force), descriptor=self.descriptor['id'] if self.descriptor is not None else None, heartbeat=None, relays={})) if not changed: return out enrol_mod.record(self.cfg, v, now) self.save_coverage() self.build_descriptor() out['descriptor'] = self._descriptor()['id'] out['relays'] = dict(self.publish_descriptor()) if self._built and self.cfg.get('heartbeat', True): out['heartbeat'] = self.presence.heartbeat_now(now)[1] self.log.append((now, 'enrolled', v['operator'], v['id'])) self.counts['enrolled'] += 1 _line(' enrolled under', v['operator'], 'via grant', _short(v['id']) + '…', ('leaving %s' % previous) if previous else '') return out
[docs] def cmd_set_visibility(self, args: Mapping[str, Any]) -> VisibilityState: return self.set_visibility(args.get('default'), args.get('overrides'))
[docs] def set_visibility(self, default: Any = None, overrides: Any = None) -> VisibilityState: """Set this node's public/private default and its per-unit overrides. The parameters mirror the two kind 11801 tags (plan D2): `default` is the `visibility` tag, and each entry of `overrides` is one `expose` tag. `overrides` is merged into the current settings - a value of null removes one. The block is validated like the config file (problems, not exceptions), persisted so a restart keeps it, and the descriptor rebuilt: the public copy is republished, or - when the change makes the node fully private - the last public descriptor is retracted (NIP-09). The reply is the resolved state: the default, the overrides, and which protocols and capabilities are public now. """ try: resolved = VisibilityConfig.merge(self.cfg.get('visibility'), default, overrides) except ValueError as e: raise control_mod.ControlError(str(e)) self.cfg['visibility'] = {'default': resolved.default, 'overrides': dict(resolved.overrides)} self.save_coverage() self.build_descriptor() relays = dict(self.publish_descriptor()) public = self.public_descriptor() out = self.visibility_state() out['descriptor'] = public['id'] if public is not None else None out['relays'] = relays _line(' visibility: default', resolved.default, '| public' if public is not None else '| fully private (no public descriptor)') return out
[docs] def visibility_state(self) -> VisibilityState: """The resolved visibility now: default, overrides, and whether each of this node's protocols and capabilities is public or private. What `status` carries and what a `set-visibility` reply answers.""" vis = self.visibility_config() protocols: dict[str, str] = {} capabilities: dict[str, str] = {} for t in (self.descriptor or {}).get('tags', []): if t and t[0] == 'c' and len(t) > 1: unit = str(t[1]) value = visibility_mod.resolve(vis.default, vis.overrides, unit) (protocols if unit.startswith('https://') else capabilities)[unit] = value return {'default': vis.default, 'overrides': dict(vis.overrides), 'public': self.public_descriptor() is not None, 'protocols': protocols, 'capabilities': capabilities}
[docs] def cmd_grant(self, args: Mapping[str, Any]) -> GrantView: return grant_view(self.grants, _arg_hex('grant', args, 'peer'))
[docs] def cmd_windows(self, args: Mapping[str, Any]) -> list[WindowView]: return windows_view(self.accounts, _arg_hex('windows', args, 'peer'), _arg_int('windows', args, 'last', 0))
[docs] def cmd_refusals(self, args: Mapping[str, Any]) -> list[RefusalResult]: return [{'subsystem': n, 'at': r.at, 'kind': r.kind, 'subject': (r.subject or '')[:16] or None, 'why': r.why, 'detail': r.detail} for n, r in self.subsystems.refusals(_arg_int('refusals', args, 'last', 5))]
[docs] def cmd_resume(self, args: Mapping[str, Any]) -> SubsystemStateResult: name = str(args.get('name') or '') actor = self.acting who = getattr(actor, 'operator', '') or 'the operator' try: state = self.subsystems.resume(name, why='resumed by %s' % who) except KeyError as e: raise control_mod.ControlError(str(e.args[0] if e.args else e)) return {'name': name, 'state': state}
[docs] def cmd_restart(self, args: Mapping[str, Any]) -> SubsystemStateResult: name = str(args.get('name') or '') who = getattr(self.acting, 'operator', '') or 'the operator' try: state = self.subsystems.restart(name, why='by %s' % who) except (KeyError, ValueError) as e: raise control_mod.ControlError(str(e.args[0] if e.args else e)) return {'name': name, 'state': state}
[docs] def cmd_events(self, args: Mapping[str, Any]) -> EventsResult: topics = _topics_arg(args.get('topics')) tap = self.events.tap assert tap is not None evs = tap.since(_arg_int('events', args, 'since', 0), topics, _arg_int('events', args, 'last', 0)) st = tap.state() return { 'seq': st['seq'], 'ring': st['ring'], 'ring_max': st['ring_max'], 'subscribers': st['subscribers'], 'oldest': st['oldest'], 'topics': sorted(channels_mod.WIRE), 'events': evs, }
[docs] def cmd_subscribe(self, args: Mapping[str, Any]) -> control_mod.Stream: topics = _topics_arg(args.get('topics')) tap = self.events.tap assert tap is not None sub = tap.subscribe(topics) backlog = collections.deque(tap.since(_arg_int('subscribe', args, 'since', 0), topics)) if args.get('since') is not None else collections.deque() def pull(timeout: float) -> Optional[BusEnvelope]: if backlog: return backlog.popleft() return sub.next(timeout) return control_mod.Stream({'seq': tap.seq, 'topics': sorted(topics) if topics else None, 'replaying': len(backlog)}, pull, lambda: tap.unsubscribe(sub))
[docs] def cmd_pull(self, args: Mapping[str, Any]) -> Mapping[str, Any]: peer, shard, filt = _arg_hex('pull', args, 'peer'), args.get('shard'), args.get('filter') if not isinstance(shard, str) or not isinstance(filt, dict): raise control_mod.ControlError('pull takes shard as a string and filter as an object') timeout = _arg_float('pull', args, 'timeout', 60.0) if not 0 < timeout <= MAX_PULL_TIMEOUT: raise control_mod.ControlError('pull timeout must be in (0, %d] seconds' % MAX_PULL_TIMEOUT) why = self.budget.throttled(peer) if why is not None and not args.get('force'): raise control_mod.ControlError('the grant does not cover a session now: %s (--force pulls anyway, and the window prices it)' % why) return self.pull(peer, shard, filt, timeout=timeout)
[docs] def cmd_terminate(self, args: Mapping[str, Any]) -> TerminateResult: return self.terminate(_arg_hex('terminate', args, 'peer'), str(args.get('reason') or 'operator')[:200])
[docs] def cmd_standing(self, args: Mapping[str, Any]) -> StandingResult: kind, body = self.reporter.ask_standing(_arg_hex('standing', args, 'peer'), _arg_hex('standing', args, 'target')) if kind is None: raise control_mod.ControlError('no answer from the peer') return {'answer': kind, 'body': body}
[docs] def cmd_reports(self, args: Mapping[str, Any]) -> ReportsResult: target = _arg_hex('reports', args, 'target') view, weighed = self.reporter.view(target) found = self.reporter.reports_about(target) return {'view': view, 'reports': [{'reporter': r['reporter'], 'severity': r['severity'], 'admissible': r['admissible'], 'reasons': r['reasons'], 'weight': self.reporter.weight_of(r['reporter']), 'id': r['event']['id'], 'created_at': r['event']['created_at']} for r in found]}
[docs] def cmd_retire(self, args: Mapping[str, Any]) -> RetireSteps: out = self.retire(str(args.get('reason') or 'operator')[:200], bool(args.get('revoke')), _arg_int('retire', args, 'lapses_in', 86400)) self._stop.set() # the tick loop ends; `run` calls stop, which says farewell return out
[docs] def commands(self) -> collections.OrderedDict[str, CommandSpec]: """Every command this socket answers: the node's own, and one per command each compartment declares. The compartments' were unreachable. `control_request` refused anything not in CONTROL before it ever looked at the registry, so the branch that dispatched `peering.show` could not be reached and no subsystem command had ever been answered. A dispatch table that documents itself has to be the same table the guard reads. """ built = getattr(self, '_built', False) sub_key = tuple(s.name for s in self.subsystems) if built else () cached = getattr(self, '_commands_cache', None) if cached is not None and cached[0] == built and cached[1] == sub_key: return collections.OrderedDict(cached[2]) table = collections.OrderedDict(CONTROL) if built: for name, spec in self.subsystems.commands().items(): table[name] = CommandSpec(args=spec.get('args', {}), does=spec.get('does', ''), reply=spec.get('reply', '')) self._commands_cache = (built, sub_key, table) return collections.OrderedDict(table)
[docs] def retire(self, reason: str = 'operator', revoke: bool = False, lapses_in: int = 86400) -> RetireSteps: """Leave the mesh in order, rather than by going quiet. `farewell` closed one of the four ways a node's departure cost its peers something: the accounting. Everything under the accounting was still left behind. The coverage claims kept pointing at a node that was gone, so every reader that believed one pulled and timed out; the shards this node held first-hand lost their authority, because nobody else may assert what it only replicated; and each of those peers recorded strain against a node that had done nothing but stop. Four steps, in this order, and the order is the whole of it: announce a heartbeat saying this is a departure, so the silence that follows is not priced as stress by anyone listening. close every asserted shard gets a range ending now. A handover signs for a closed set, so an open range cannot be passed on, and the shards worth passing on are exactly the ones nobody ever bounded. hand over the statement goes to every peer holding a live grant, stored. The peer keeps it only if it fingerprints to what the peer holds, so being wrong about who has the data costs nothing. withdraw every claim is republished best-effort with an expiration. After the handovers, never before: a withdrawal takes back the very claim a handover copies its terms from. farewell what `stop` already does, and it goes last because a receipt is the last thing this node has to say. This is a retirement and not a restart. A restart MUST NOT run it: the claims would come back on the next tick with their ranges closed and their authority given away, which is a fleet upgrade paying the price this exists to avoid. `meshnode retire` is a separate command for that reason, and `run` never calls it. Reversible up to the last step. A node that retires and is started again publishes its claims afresh; what it does not get back is the `until` it closed, which is a line in the config, and the handovers it signed, which are permanent by design. `revoke` is the one step that is not reversible at all, so it is off unless asked for. Nothing here may raise. A node that cannot retire cleanly must still stop. """ now = self.clock() did: list[tuple[Any, ...]] = [] steps: RetireSteps = {'reason': reason, 'at': now} try: # First, and before anything is given away: say this is a # departure. Under FLP nothing else distinguishes a node that went # from one that went quiet, so a peer holding a schedule against # this one would otherwise record a partition it was about to be # told about. did += self.presence.announce_retiring(now) except Exception as e: did.append(('announcement failed', '%s: %s' % (type(e).__name__, e))) try: did += self.discovery.close_ranges(now) except Exception as e: did.append(('close failed', '%s: %s' % (type(e).__name__, e))) peers_held = [p for p in _live_peers(self.grants) if (row := self.grants.get(p, grants_mod.ISSUED)) and row.get('status') == 'live'] try: did += self.sync.hand_over_all(peers_held, now) except Exception as e: did.append(('handover failed', '%s: %s' % (type(e).__name__, e))) try: did += self.discovery.withdraw_coverage(now, lapses_in=lapses_in) except Exception as e: did.append(('withdrawal failed', '%s: %s' % (type(e).__name__, e))) if revoke: try: ev = lifecycle.revocation(self.ks.node_pk, reason, now) signed = store_mod.make_signed_event(self.ks.node_sk, now, ev['kind'], ev['tags'], ev['content']) # Plan D2: a kind 11802 goes to the public relays only while a # public descriptor is outstanding (there is a public presence # to revoke, `_published_public_id` set), and always to this # node's network relays - a fully private node must not reveal # itself on the public relays to say it is leaving. urls: list[str] = list(self.relays) if self._published_public_id is not None else [] urls += [u for u in self._network_relays() if u not in urls] if urls: relay.publish_all(urls, signed, self.timeout) did.append(('revoked', signed['id'], reason)) except Exception as e: did.append(('revocation failed', '%s: %s' % (type(e).__name__, e))) for d in did: _line(' ' + ' '.join(_short(str(x)) for x in d)) steps['did'] = [list(d) for d in did] steps['peers'] = peers_held steps['handed'] = sum(1 for d in did if d[0] == 'handed over') steps['withdrawn'] = sum(1 for d in did if d[0] == 'coverage withdrawn') steps['revoked'] = bool(revoke and any(d[0] == 'revoked' for d in did)) return steps
[docs] def save_coverage(self) -> None: """Write the config back after a compartment changed what this node claims. One place, because a running node owns its directory and the file is what the next tick reads. Compartments reach it as `ctx.persist_cfg`; the node reaches it directly.""" save_config(self.dir, {k: v for k, v in self.cfg.items() if not k.startswith('_')})
[docs] def terminate(self, peer_pk: str, reason: str = 'operator') -> TerminateResult: """End a peering: zero both grants here, tell the peer, and stop pulling from it. The trust decision, if any, is left where it is.""" rows = [self.grants.get(peer_pk, d) for d in (grants_mod.ISSUED, grants_mod.RECEIVED)] if not any(r is not None and r['status'] == 'live' for r in rows): raise control_mod.ControlError('no live peering with %s' % peer_pk[:16]) msg = self.peering.host.terminate(peer_pk, reason=reason) self.grants.zero(peer_pk, self.clock()) sent: Mapping[str, Any] = {} try: sent = self.transport.send(msg, peer_pk, stored=True) except transport_mod.TransportError as e: sent = {'error': str(e)} before = len(self.cfg.get('peers', [])) self.cfg['peers'] = [p for p in self.cfg.get('peers', []) if p.get('pubkey') != peer_pk] if len(self.cfg['peers']) != before: self.save_coverage() _line(' terminated the peering with', _short(peer_pk), '-', reason) return {'peer': peer_pk, 'reason': reason, 'told': sent, 'pulls_removed': before - len(self.cfg['peers'])}
[docs] def peer_view(self) -> list[PeerViewRow]: """Every peer this node holds a grant with, as an operator reads it.""" out: list[PeerViewRow] = [] ours = set(identity.PROTOCOLS) for pk in sorted({g['peer'] for g in self.grants.list()}): desc = self.peers.descriptor(pk) theirs = identity.protocols_of(desc) if desc else set() shared = identity.shared_protocols(theirs, ours) if desc else set() issued = self.grants.get(pk, grants_mod.ISSUED) received = self.grants.get(pk, grants_mod.RECEIVED) pend = self.grants.pending(pk) evals = [r for r in self.budget.evaluations if r.peer == pk] out.append({'peer': pk, 'issued': {'tier': issued['payload'].get('tier'), 'status': issued['status']} if issued else None, 'received': {'tier': received['payload'].get('tier'), 'status': received['status']} if received else None, 'pending': {'tier': pend['payload'].get('tier'), 'from_epoch': pend['decided_epoch'] + 1} if pend else None, 'last_evaluated': ({'epoch': evals[-1].epoch, 'severity': evals[-1].severity, 'state': evals[-1].state} if evals else None), 'standing': self.ledger.tell(pk), 'zeroed_until': self.budget.zero_until.get(pk), 'pulls': [p['shard'] for p in self.cfg.get('peers', []) if p.get('pubkey') == pk], 'descriptor': desc.get('id') if desc else None, # What the two nodes can run with each other, and the # schema the peer declared when it differs from ours. 'shared': sorted(p[len(identity.FLEETMESH):] for p in shared), 'not_shared': sorted(p[len(identity.FLEETMESH):] for p in theirs - shared) if desc else [], 'digest': (self.peering.host.digest_mismatch.get(pk) or '')[:16] or None, 'notices': identity.notices(desc, digest=descriptor.DIGEST) if desc else []}) return out
# ---- actions ------------------------------------------------------------------- # A shard filter is a NIP-01 filter and routinely carries tag keys ('#t'); # fleetmesh_node.interfaces.NostrFilter names no tag keys, so the plain mapping is # the accurate type until that TypedDict grows them.
[docs] def propose(self, peer_pk: str, shard: str, filt: Mapping[str, Any], mode: str = 'both', timeout: float = 30.0) -> tuple[str, Mapping[str, Any]]: want = [{'shard': shard, 'filter': dict(filt), 'mode': mode}] return self.peering.propose(peer_pk, want, timeout=timeout)
[docs] def pull(self, peer_pk: str, shard: str, filt: Mapping[str, Any], timeout: float = 30.0) -> Mapping[str, Any]: return self.sync.pull(peer_pk, shard, dict(filt), timeout=timeout)
[docs] def regrant(self, peer_pk: str, tier: str, now: int | None = None) -> Optional[GrantPayload]: """Re-issue a live grant at a tier the operator has just decided on. A tier is only ever raised by a person, so the decision has to reach an existing peering as well as the next one. This writes a new grant at the new tier, publishes it as a fresh kind 30801 under the same blinded identifier, and tells the subject with peering/1.0/amend - the same path a window evaluation uses, because it is the same kind of change. """ now = now if now is not None else self.clock() row = self.grants.get(peer_pk, grants_mod.ISSUED) if row is None: return None # A person deciding is the one thing allowed to skip the earning. The # specification says an operator MAY seed a tier for a node it knows out # of band, recorded as a signed event and reversible, so a regrant opens # at the ceiling rather than at the opening fraction a stranger gets. held = row['payload'] payload = cast(GrantPayload, dict(held, tier=tier, limits={k: v for k, v in window.ceilings(tier).items() if k != 'dup_ratio'})) # And it lands at the boundary, like every other decision. Seeding a # tier mid-window published a new envelope while the subject was still # sending receipts against the old one; every one of those was refused # as naming a grant that did not govern that window, the window closed # on a claim one receipt short of what was measured, and the divergence # priced an honest peer S2. Seen on the mesh the first time a seed was # re-applied after the ladder had overridden it. decided = accounting.epoch(now, held.get('window') or 3600) out = self.peering.decide(peer_pk, payload, 'operator set the tier to %s' % tier, None, decided) _line(' granted', _short(peer_pk), 'tier', tier, '- in force from window', out['effective_from']) return payload
# ---- the node's own ceiling ---------------------------------------------------- def _amend(self, peer_pk: str, payload: Mapping[str, Any], reason: str, cause: str, now: int) -> tuple[NostrEvent, GrantPayload]: """Write and publish a grant, and tell the subject what changed it. The one place a grant leaves this node outside a window evaluation. `cause` is what separates a remedy from a shed from a person, and a subject that could not tell them apart would price its issuer for owning a small machine. """ # The one path that still lands inside the running window, and it is a # deliberate exception rather than the leftover the other two were. A # shed is the node saying it is over its own ceiling now; deferring the # lower limits to the next boundary would leave it carrying load it has # already decided it cannot carry, for up to an hour. The cost is the # one the other paths were changed to avoid - the subject's receipts for # the rest of this window name the grant it still holds, and the window # closes divergent - so a shed is worth an S2 against a peer that did # nothing wrong only because the alternative is the node falling over. # If that trade ever stops being worth it, this is the line to change. out = self.peering.issue(peer_pk, payload, cause, reason, effective_epoch=accounting.epoch(now, payload.get('window') or 3600), now=now) return out['envelope'], out['payload'] # ---- what the compartments do, reached from the node --------------------------- # Each of these is the compartment's, and each is kept here because a caller # outside the node - a test, the control socket - asks the node for it. They # forward and do nothing else; the state and the refusals live in the # compartment, which is the point.
[docs] def on_heartbeat(self, hb: NostrEvent) -> list[tuple[Any, ...]]: return self.presence.on_heartbeat(hb)
[docs] def publish_discovery(self, now: int | None = None) -> list[tuple[str, ...]]: return self.discovery.publish_discovery(now)
[docs] def publish_coverage(self, now: int | None = None) -> list[tuple[str, ...]]: return self.discovery.publish_coverage(now)
[docs] def forward_clock(self, key: str, now: int) -> int: return self.discovery.forward_clock(key, now)