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