"""NodeApp: what `meshnode run` starts. Construction, the compartment
assembly in start(), the run loop, the inbound door and status.json.
Separate from control.py so the file that registers the compartments - the
one scripts/check-cli.py reads for tick order - holds nothing else.
"""
from __future__ import annotations
import collections
import json
import os
import threading
import time
from typing import Any, Callable, Mapping, MutableMapping, Optional, Sequence, cast
from ..config.node import NodeConfigDict
from fleetmesh_core.accounting import standing
from fleetmesh_core.identity import identity
from fleetmesh_core.network import brand as brand_mod
from fleetmesh_core.peering import peering
from .. import (channels as channels_mod, compartment as compartment_mod,
keystore, metrics as metrics_mod, transport as transport_mod)
from ..planes.identity import visibility as visibility_mod
from ..channels import journal
from fleetmesh_core.storage import store as store_mod
from fleetmesh_core.wire import validate
from ..protocols.nostr import blobstore as blobstore_mod, eventstore, peers as peers_mod
from ..storage import accounts as accounts_mod, grants as grants_mod
from ..protocols import ProtocolManager
from ..transport.host import ProtocolHost
from . import authority as authority_mod, groups as groups_mod, router as router_mod
from ..compartment import context as context_mod
from ..metrics import adapters as metrics_adapters
from ..metrics.face import face_metrics
from ..protocols.nostr import client as relay, descriptor
from ..planes.identity.announce import compartment as announce_mod
from ..planes.identity.discovery import compartment as discovery_wire
from ..planes.identity.presence import compartment as presence_mod
from ..planes.identity.linked import compartment as linked_mod
from ..planes.identity.network import compartment as network_mod
from ..planes.store.sync import core as sync_wire
from ..planes.store.retention import compartment as retention_mod
from ..planes.store.blob_wire import core as blob_wire_mod
from ..planes.store.blob_replication import compartment as blob_repl_mod
from ..planes.peering.trust import compartment as trust_mod
from ..planes.peering.strain import compartment as strain_mod
from ..planes.peering.peering import core as peering_wire
from ..planes.peering.budget import core as budget_mod
from ..planes.peering.capacity import compartment as capacity_mod
from ..planes.peering.reporter import core as reporter_mod
from ..planes.transport.link import compartment as link_mod
from ..planes.transport.lan import compartment as lan_mod
from ..planes.transport.p2p import compartment as p2p_wire
from ..planes.transport.mediation import compartment as mediation_mod
from ..planes.transport.bridge import compartment as bridge_mod
from ..planes.services.gossip import core as gossip_wire
from ..planes.services.compute import compartment as compute_mod
from ..planes.services.compute_wire import compartment as compute_wire_mod
from ..planes.services.settle import compartment as settlement_mod
from ..planes.services.paidfetch import compartment as fetch_pricing_mod
from ..planes.services.sidecars import compartment as sidecars_mod
from ..planes.services.dvm import gateway as dvm_mod
from ..planes.services.nsite import compartment as nsite_mod
from ..planes.services.video import compartment as video_mod
from ..planes.operations.remote import compartment as remote_mod
from ..planes.operations.scheduler import compartment as scheduler_mod
from ..planes.operations.updates import core as updates_mod
from ..compartment import lifecycle as lifecycle_mod
from . import socket as control_mod
from ..config import NodeConfig, VisibilityConfig
from ..interfaces import NostrEvent
from .config import _blob_storage_cap, load_config, typed_config
from .control import ControlMixin
from .plugins import load_plugins, plugin_sidecars
from .systemd import sd_notify
from .views import PLANES as _VIEW_PLANES, node_health, node_status
# How anything in the node says something an operator will read, and how a
# trust entry is understood. Both live where a compartment can reach them
# without importing the node that imports the compartment.
_line, _short = journal.line, journal.short
trust_decision, trust_tiers = trust_mod.decision, trust_mod.tiers
# The node's compartments in tick order. This is the one list scripts/check-cli.py,
# the `subsystems` command and the docs agree on. The order is a decision, not
# a derivation: the relay journal first, so a subscription that dropped is said
# before anything that depends on it; then the operator's decisions, which
# outrank the ladder; then the mechanisms; then what the node publishes about
# itself; then the pulls, which are the only load it chooses; then the paid and
# fronted services, which are inert until configured. Optional compartments sit
# where they tick and are built only when their config section is present.
MANIFEST: tuple[type[compartment_mod.Compartment], ...] = (
link_mod.Link,
trust_mod.Trust,
strain_mod.StrainLedger,
peering_wire.Peering,
budget_mod.Budget,
capacity_mod.Capacity,
sync_wire.SyncPeer,
reporter_mod.Reporter,
discovery_wire.Discovery,
announce_mod.Announce,
lan_mod.Lan,
p2p_wire.P2PTransport, # optional: cfg['p2p']
gossip_wire.GossipMesh, # optional: cfg['gossip']
presence_mod.Presence,
linked_mod.LinkedFace, # the schema.org face; reads presence's 10050 and budget's ledger
network_mod.Network, # always built, idle without cfg['network']; after linked, splits the descriptor built above (plan D6/D11)
retention_mod.Retention,
scheduler_mod.Scheduler,
compute_mod.Compute, # optional: cfg['compute']
compute_wire_mod.ComputeWire, # optional: cfg['compute']
bridge_mod.RelayBridge, # optional: cfg['bridge']
settlement_mod.Settlement,
mediation_mod.Mediation,
blob_wire_mod.BlobWire,
blob_repl_mod.Replication,
fetch_pricing_mod.PaidFetch,
sidecars_mod.Sidecars,
remote_mod.Remote, # control/1.0 over the wire; every command goes through wire_request (plan D7/D20)
dvm_mod.DVMGateway, # optional: cfg['dvm']
nsite_mod.NsiteGateway, # optional: cfg['nsite']; after bridge, which it uses for manifests
video_mod.VideoTransitCompartment, # optional: cfg['video']; after nsite, the other HTTP face
updates_mod.Updates, # optional: cfg['updates']; last - it reports on all the above
)
[docs]class NodeApp(ControlMixin):
# The compartments, set on the node by Registry.assemble() under each
# class's `attr` (or `name`). Declared so the node's surface is stated,
# and so the checker knows it: setattr is invisible to mypy. The six (6)
# optional ones - p2p, gossip, network, compute, bridge, dvm, updates - are absent
# on a node whose config does not enable them.
manifest: tuple[type[compartment_mod.Compartment], ...] # MANIFEST plus any configured plugins
link: link_mod.Link
trust: trust_mod.Trust
strain: strain_mod.StrainLedger
peering: peering_wire.Peering
budget: budget_mod.Budget
capacity: capacity_mod.Capacity
sync: sync_wire.SyncPeer
reporter: reporter_mod.Reporter
discovery: discovery_wire.Discovery
announce: announce_mod.Announce
lan: lan_mod.Lan
p2p: p2p_wire.P2PTransport
gossip: gossip_wire.GossipMesh
presence: presence_mod.Presence
retention: retention_mod.Retention
scheduler: scheduler_mod.Scheduler
compute: compute_mod.Compute
compute_wire: compute_wire_mod.ComputeWire
bridge: bridge_mod.RelayBridge
settlement: settlement_mod.Settlement
mediation: mediation_mod.Mediation
blob_wire: blob_wire_mod.BlobWire
blob_replication: blob_repl_mod.Replication
paid_fetch: fetch_pricing_mod.PaidFetch
sidecars: sidecars_mod.Sidecars
remote: remote_mod.Remote
dvm: dvm_mod.DVMGateway
video: video_mod.VideoTransitCompartment
network: network_mod.Network
[docs] def __init__(self, directory: str, cfg: Mapping[str, Any] | None = None,
clock: Callable[[], int] | None = None,
relays_override: Sequence[str] | None = None) -> None:
self.dir: str = directory
self.cfg: MutableMapping[str, Any] = dict(cfg if cfg is not None else load_config(directory))
# The typed view of the same file. Compartments get their block through
# NodeContext.block(); the ambient keys the node itself reads are below.
self.settings: NodeConfig = typed_config(self.cfg)
self.clock: Callable[[], int] = clock or (lambda: int(time.time()))
self.relays: list[str] = list(relays_override if relays_override is not None else self.cfg['relays'])
self.ks: keystore.Keystore = keystore.Keystore.load_or_generate(directory)
self.store: eventstore.NodeStore = eventstore.NodeStore(os.path.join(directory, 'events.sqlite'))
self.grants: grants_mod.GrantStore = grants_mod.GrantStore(os.path.join(directory, 'grants.sqlite'))
self.accounts: accounts_mod.AccountStore = accounts_mod.AccountStore(os.path.join(directory, 'accounts.sqlite'))
blobs_cfg = self.settings.blobs
self.blobs: blobstore_mod.BlobStore = blobstore_mod.BlobStore(
os.path.join(directory, 'blobs'), max_storage_bytes=_blob_storage_cap(self.cfg),
fanout=blobs_cfg.fanout, data_dir=blobs_cfg.data_dir)
# What this node measures, declared by the compartments rather than
# written out here. Built before the face so the face's
# `metrics_provider` can close over it; the declarations arrive later,
# at assemble(), and `read()` walks whatever is registered when a
# scrape happens.
self.monitors: metrics_mod.Monitors = metrics_mod.Monitors()
# The unified protocol host multiplexer
host_cfg = self.settings.protocol_suites.host
host_ip = host_cfg.listen if (host_cfg.listen != '127.0.0.1' or not self.settings.face.host) else self.settings.face.host
host_port = host_cfg.port if (host_cfg.port != 0 or not self.settings.face.port) else self.settings.face.port
self.host: ProtocolHost = ProtocolHost(
host=host_ip,
port=host_port,
name=self.settings.name,
clock=self.clock,
)
# The protocol manager orchestrating all active suites
self.protocols: ProtocolManager = ProtocolManager(
node_dir=directory,
keystore=self.ks,
clock=self.clock,
name=self.settings.name,
)
self.protocols.load_suites_config(
self.settings.protocol_suites,
backend_store=self.store,
blob_store=self.blobs,
grants=self.grants,
node_instance=self,
strain_ledger=getattr(self, 'strain', None),
)
self.protocols.mount_ingress(self.host)
nostr_pkg = self.protocols.get_package('nostr')
relay_srv = getattr(nostr_pkg, 'relay_server', None) if nostr_pkg is not None else None
self.face: Any = relay_srv
if relay_srv is not None:
relay_srv.metrics_provider = metrics_adapters.provider(self.monitors)
self.monitors.register(face_metrics(relay_srv), owner='face')
# Plan D2: the relay and Blossom doors consult the node's live
# visibility - a private `relay`/`blossom` unit serves only a key
# one of this node's private networks admits, at the door itself,
# not merely by hiding from the descriptor.
relay_srv.admit = lambda pk, unit='relay': self._face_admits(unit, pk)
if relay_srv.blossom is not None:
apm = self.settings.storage.allow_private_mirror
relay_srv.blossom.allow_private_mirror = list(apm) if isinstance(apm, tuple) else apm
relay_srv.blossom.admit = lambda pk, unit='blossom': self._face_admits(unit, pk)
# The FULL descriptor: every protocol and capability, the visibility
# default and one expose tag per override (plan D2). What goes to the
# public relays is `self.public_copy`, a filtered copy of it; the
# network compartment cuts the private copy from the full.
self.descriptor: NostrEvent | None = None
self.public_copy: NostrEvent | None = None
# The id of the last public descriptor this node published, kept so
# that going fully private can delete it (a NIP-09 kind 5) rather than
# let it expire. Read back from disk on start so a restart that begins
# private still retracts the descriptor the last run left on a relay.
self._published_public_id: str | None = None
# When the last public descriptor was retracted (a kind 5's created_at),
# so a descriptor built in the same second is stamped one second later:
# a store refuses a version created at or before the deletion that
# named its coordinate, and going public again must not be a no-op.
self._retracted_at: int | None = None
# Kind 30833 revocation lists this node has been handed; what the
# wire door (app/control.py wire_request) checks grant chains against.
self.revocation_lists: list[Mapping[str, Any]] = []
# What this node has seen of a did:group operator (plan D20): controller
# documents and quorum copies in first-seen order, and the revocation
# lists fetched from relays (the circle's, and those of person issuers).
self.groups: groups_mod.GroupLedger = groups_mod.GroupLedger(os.path.join(self.dir, groups_mod.FILE))
self._group_polled_at: int = 0
self._revocations_polled_at: dict[str, int] = {} # issuer key -> when its 30833s were last fetched
self.timeout: float = 15.0
self.peers: peers_mod.Peers = peers_mod.Peers(self.relays, clock=self.clock)
self.transport: transport_mod.TransportRouter = transport_mod.TransportRouter(
self.ks, self.peers, self.relays,
endpoints=self.cfg.get('endpoints', []),
clock=self.clock,
seen_store=(self.accounts.seen_wrap, self.accounts.put_seen_wrap),
ack_store=self.accounts,
sidecar_dir=self.dir,
enable_nostr=(nostr_pkg is not None),
)
self.protocols.mount_transport_rungs(self.transport)
pol = self.settings.policy
self.policy: peering.Policy = peering.Policy(pow_bits=self.settings.pow_bits, open_enrolment=pol.open_enrolment,
protocols=list(pol.protocols),
tiers=trust_tiers(self.cfg.get('trust')))
self.ledger: standing.Ledger = standing.Ledger()
self.events: channels_mod.NodeEventBus = channels_mod.NodeEventBus()
self.events.tap = channels_mod.Tap(clock=self.clock)
# What this node says, fanned out from one declaration per event.
# After `self.events`, because the bus is one of the places a record
# goes: anything already subscribed to a topic by name keeps working.
# Not `self.log`: that name is already a 500-entry deque of tick and
# handler failures (below), and shadowing it would have silently
# replaced one with the other. `says` is what this does.
self.says: channels_mod.Log = channels_mod.Log(
backends=[channels_mod.ConsoleBackend()], clock=self.clock,
bus=self.events, monitors=self.monitors)
self.stores: context_mod.NodeStores = context_mod.NodeStores(
events=self.store,
grants=self.grants,
accounts=self.accounts,
blobs=self.blobs,
)
self.router: router_mod.ProtocolRouter = router_mod.ProtocolRouter()
self._stop: threading.Event = threading.Event()
self.context: context_mod.NodeContext = context_mod.NodeContext(
dir=self.dir, ks=self.ks, cfg=cast(NodeConfigDict, self.cfg), clock=self.clock, events=self.events,
stores=self.stores, relays=self.relays, transport=self.transport, router=self.router,
face=self.face, host=self.host, peers=self.peers, policy=self.policy, ledger=self.ledger,
timeout=self.timeout, stop=self._stop, node=self, persist_cfg=self.save_coverage,
redescribe=self.redescribe,
regrant=self.regrant,
propose=self.propose,
pull=self.pull,
amend=self._amend,
wire_request=self.wire_request,
build_descriptor=self.build_descriptor,
says=self.says,
)
# What was a dozen dicts here is now the state of the compartment that
# keeps it: the pulls belong to the scheduler, the publications to
# discovery, the descriptor and the heartbeats to presence, the relay
# journal to link. The node keeps only what the node owns.
self.log: collections.deque[Any] = collections.deque(maxlen=500)
self.counts: collections.Counter[str] = collections.Counter() # handler failed, tick failed, config rejected
self.rejected: collections.Counter[str] = collections.Counter() # messages refused at the door, by reason
self._last_said: dict[str, float] = {} # rate limit on repeated log lines
self._last_tick: Sequence[tuple[Any, ...]] = () # what the last tick did, for status.json
self._last_tick_error: str | None = None
self._config_error: str | None = None
self._tick_lock: threading.RLock = threading.RLock() # the run loop and the control socket both tick
self._built: bool = False
self._stopped: bool = False
# Config blocks edited on disk that wait for a node restart, as last
# said: their owner does not declare restart, so the edit is reported
# once per change rather than once a tick.
self._waiting: MutableMapping[str, Any] = {}
# ---- assembly ----------------------------------------------------------------
DESCRIPTOR_FILE: str = 'descriptor.json'
# Present while descriptor.json holds a descriptor no relay has accepted
# yet. start() mines before it assembles (peering reads the descriptor at
# assembly) but publishes only once the compartments have started, so a
# refused start leaves a mined, unpublished descriptor behind. Reusing it
# keeps the proof of work; this marker is what makes the next start that
# does succeed publish it, rather than assume the relays already have it.
PENDING_FILE: str = 'descriptor.pending'
# The id of the last public descriptor this node published, one line, so a
# restart that comes up fully private can still retract it (a NIP-09 kind
# 5). Absent: nothing public is outstanding.
PUBLIC_ID_FILE: str = 'descriptor.public'
def _endpoints(self) -> list[tuple[str, str, int]]:
"""What the descriptor advertises, which is what the operator configured.
It used to fall back to this node's own relay face, and the face binds
loopback on an ephemeral port by default: the descriptor then advertised
an address no peer could reach, and one that changed on every restart,
so the proof of work could never be reused either. `endpoint` is
optional on a kind 11801. A node with nothing reachable to advertise
says nothing, and is still reachable over the nostr transport, which is
the binding the specification says always works.
"""
return [(e['transport'], e['address'], e.get('priority', 50)) for e in self.cfg['endpoints']]
[docs] def load_descriptor(self) -> NostrEvent | None:
"""The descriptor this node published last time, if it is still the one
it would publish now.
A descriptor costs a NIP-13 proof of work to mine - twenty bits, which
took fourteen seconds on a small droplet - and it is a replaceable
event, so republishing a fresh one on every start burns that work and
churns the relay for nothing. The first two-machine run re-mined on
every service restart because nothing here read the file back. It is
reused only when it would still be published unchanged: valid under the
digest this node speaks, not yet inside its renewal window, and
describing the same class and endpoints the config now asks for.
"""
path = os.path.join(self.dir, self.DESCRIPTOR_FILE)
if not os.path.exists(path):
return None
try:
with open(path, encoding='utf-8') as f:
d = json.load(f)
except (ValueError, OSError):
return None
now = self.clock()
if identity.validate_descriptor(d, now=now, digest=descriptor.DIGEST):
return None
exp = int([t for t in d['tags'] if t[0] == 'expiration'][0][1])
if now >= exp - (exp - d['created_at']) // 10:
return None
want = [['endpoint', s, a, str(p)] for s, a, p in sorted(self._endpoints(), key=lambda e: (int(e[2]), e[0]))]
if [t for t in d['tags'] if t[0] == 'endpoint'] != want:
return None
cls = [t[1] for t in d['tags'] if t[0] == 'class'][0]
# Optional protocols (the sidecar capabilities) are declared by the
# compartment that verifies them, after start, and are not config:
# they neither qualify nor disqualify a reuse here. `sidecars` brings
# the descriptor into agreement with the live self-tests itself.
optional = set(identity.CONSTANTS['descriptor'].get('optional_protocols', ()))
if cls != self.cfg['class'] or identity.protocols_of(d) - optional != set(self.cfg['protocols']) | set(identity.REQUIRED_PROTOCOLS):
return None
# The operator is the declaration the independence model reads, and
# the plain capabilities are what a leaf searches for. Both are
# config; a change to either is a new descriptor, not a reused one.
operator = [t[1] for t in d['tags'] if t[0] == 'operator']
want_operator = self.published_operator()
if operator != ([want_operator] if want_operator else []):
return None
hints = {t[1] for t in d['tags'] if t[0] == 'c' and len(t) > 1 and not t[1].startswith('https://')}
if hints != set(self.cfg.get('capabilities') or ()):
return None
# Visibility is config too: a descriptor mined before the operator
# changed the default or an override is not the one this node would
# publish now, so it is rebuilt rather than reused.
vis = self.visibility_config()
if [t for t in d['tags'] if t[0] in ('visibility', 'expose')] != visibility_mod.visibility_tags(vis.default, vis.overrides):
return None
self.descriptor = d
self.public_copy = self._derive_public(d)
return d
def _descriptor(self) -> NostrEvent:
"""The descriptor once start() has loaded or mined it. Reaching for it
earlier is a programming error, not a state the node should paper over."""
if self.descriptor is None:
raise RuntimeError('the descriptor is not built yet; start() mines or loads it')
return self.descriptor
def _brand_tags(self) -> list[list[str]]:
"""The node's brand self-label (plan D28): one NIP-32 L/l pair per
configured brand strand id, ``["L", "org.fleetmesh.brand"]`` and
``["l", <strand id>, "org.fleetmesh.brand"]``. The node CLAIMS each
brand; the authority's kind 1985 endorsement (`meshctl brand endorse`)
is the other half, and a brand shows on this node only when both exist
(fleetmesh_core/network/brand). Public: never a private tag, so it
survives into the public copy `_derive_public` builds."""
ns = brand_mod.NAMESPACE
out: list[list[str]] = []
for brand_id in self.cfg.get('brands') or ():
text = str(brand_id).strip()
if text:
out += [['L', ns], ['l', text, ns]]
return out
[docs] def build_descriptor(self) -> NostrEvent:
# Any built compartment may add capability identifiers (`c` tags) and
# descriptor tags: sidecars declare the protocols they front, paid_fetch
# its prices, a plugin the dialect it speaks. Before start() assembles
# the compartments none have anything to add, which is also right.
protocols = list(self.cfg['protocols'])
extra_tags: list[list[str]] = []
subs = getattr(self, 'subsystems', None)
for sub in (subs or ()):
add = getattr(sub, 'capability_protocols', None)
if callable(add):
protocols += [p for p in add() if p not in protocols]
tags = getattr(sub, 'descriptor_tags', None)
if callable(tags):
extra_tags += list(tags())
capabilities = list(self.cfg.get('capabilities', ()))
if getattr(self, 'settings', None) is not None and not self.settings.protocol_suites.nostr.enabled:
capabilities = [c for c in capabilities if c not in ('relay', 'negentropy', 'blossom')]
if getattr(self, 'protocols', None) is not None:
for tag in self.protocols.descriptor_capabilities():
tag_list = list(tag)
if len(tag_list) == 2 and tag_list[0] == 'c' and tag_list[1] in capabilities:
continue
if tag_list not in extra_tags:
extra_tags.append(tag_list)
# Plan D2: the FULL descriptor carries every protocol and capability,
# the `visibility` default (only when private - absent means public)
# and one `expose` tag per override. What reaches the public relays is
# the public copy, derived below; the `expose`/`network` tags reach
# only the private copy, as descriptor_split guarantees (plan D11).
vis = self.visibility_config()
extra_tags = list(extra_tags) + self._brand_tags() + visibility_mod.visibility_tags(vis.default, vis.overrides)
now = self.clock()
if self._retracted_at is not None and now <= self._retracted_at:
# Strictly newer than the deletion that named this coordinate, or a
# relay that honours NIP-09 refuses it as deleted (see _retract_public).
now = self._retracted_at + 1
prev = self.descriptor
if prev is not None and isinstance(prev.get('created_at'), int) and now <= prev['created_at']:
# Strictly newer than the descriptor it replaces: kind 11801 is
# replaceable, and on an equal created_at NIP-01 keeps the LOWER
# id, so a redescription in the same second as the last one could
# lose to it at every relay and leave the old descriptor standing.
now = prev['created_at'] + 1
self.descriptor = descriptor.build(self.ks, self.cfg['class'], self._endpoints(), self.published_operator(),
protocols, now=now,
capabilities=capabilities, bits=self.cfg.get('pow_bits'),
extra_tags=extra_tags)
self.public_copy = self._derive_public(self.descriptor)
path = os.path.join(self.dir, self.DESCRIPTOR_FILE)
tmp = path + '.tmp'
with open(tmp, 'w', encoding='utf-8') as f:
json.dump(self.descriptor, f, indent=2)
os.replace(tmp, path)
return self.descriptor
[docs] def visibility_config(self) -> VisibilityConfig:
"""This node's visibility settings, read live from the config dict so a
`set-visibility` command takes effect at once rather than at a restart.
An absent block is the default: public, nothing overridden."""
raw = self.cfg.get('visibility')
if raw is None:
return VisibilityConfig()
return VisibilityConfig.from_dict(raw)
def _unit_visibility(self, unit: str) -> str:
"""Whether one protocol or capability of this node resolves public or
private now (plan D2): its override, else the default. Live, so a
`set-visibility` flips the doors without a restart."""
vis = self.visibility_config()
return visibility_mod.resolve(vis.default, vis.overrides, unit)
def _face_admits(self, unit: str, pubkey: Optional[str]) -> bool:
"""Whether this node's `relay` or `blossom` door may serve `pubkey`
(None = a request with no authenticated key). A unit that resolves
public - the default - serves anyone, exactly as before. A private one
serves only a key one of this node's private networks admits (plan D2):
a private relay is the node's own face, turned away from a stranger."""
if self._unit_visibility(unit) == visibility_mod.PUBLIC:
return True
if not pubkey:
return False
return self._network_member(pubkey)
def _network_relays(self) -> list[str]:
"""This node's private-network relays (plan D2/D11): the relays of the
networks it is configured for, plus any the operator named in
`operator_relays`. Never the public relays."""
out: list[str] = [str(u) for u in (self.cfg.get('operator_relays') or [])]
net = self.subsystems.get('network') if getattr(self, '_built', False) else None
if net is not None and hasattr(net, 'network_relays'):
try:
out += [str(u) for u in net.network_relays() if str(u) not in out]
except Exception as e: # noqa: BLE001 - a network compartment in trouble yields no relays, not a crash
self._say_once('network-relays', '! the network compartment named no relays:', e)
return out
[docs] def destination_relays(self) -> list[str]:
"""Where this node's own signed, peer-directed events go (plan D2): its
public relays normally; its network relays while it is fully private and
publishes no public descriptor, so it still tells the members it shares
a private network with without revealing itself on the public relays. An
empty list means nowhere - a fully private node with no network."""
if self.public_descriptor() is None:
return self._network_relays()
return list(self.relays)
def _derive_public(self, full: NostrEvent) -> Optional[NostrEvent]:
"""The public copy of the FULL descriptor, or None when fully private.
A filtered copy: the `expose` tags are dropped and every `c` tag whose
unit resolves private is removed - the required protocols stay, because
a valid kind 11801 keeps them. When nothing is hidden the copy IS
`full` (the same event, the same id), so a public node's descriptor is
byte for byte what it was. A filtered copy is mined with the same proof
of work, since a public peer checks the work of whatever it sees."""
vis = self.visibility_config()
if not visibility_mod.has_public_presence(vis.default, vis.overrides):
return None
if not visibility_mod.hides_any(full['tags'], vis.default, vis.overrides, identity.REQUIRED_PROTOCOLS):
# Nothing hidden: the public copy IS the full descriptor, byte for
# byte, so a public node is unchanged.
return full
tags = visibility_mod.public_tags(full['tags'], vis.default, vis.overrides, identity.REQUIRED_PROTOCOLS)
base = [t for t in tags if t[0] != 'nonce']
bits = self.cfg.get('pow_bits')
bits = identity.CONSTANTS['descriptor']['default_pow_bits'] if bits is None else bits
if bits:
base, _ = descriptor.mine(self.ks.node_pk, int(full['created_at']), descriptor.KIND, base, full['content'], bits)
return store_mod.make_signed_event(self.ks.node_sk, int(full['created_at']), descriptor.KIND, base, full['content'])
[docs] def public_descriptor(self) -> Optional[NostrEvent]:
"""WHAT GOES TO THE PUBLIC RELAYS: the public copy, or None for a node
that publishes no public descriptor at all.
Every public-relay publication - the descriptor and everything derived
from it (a heartbeat, an announce, a coverage claim) - goes through
this one accessor, so a fully private node reaches none of them."""
if self.public_copy is None and self.descriptor is not None:
self.public_copy = self._derive_public(self.descriptor)
return self.public_copy
[docs] def publish_descriptor(self) -> Mapping[str, Any]:
"""Publish the public copy to the public relays, or retract the last one.
The one place the public descriptor is (re)published: start's pending
publish, `redescribe`, `republish` and `enrol`. When the public copy is
gone - the node went fully private - a NIP-09 kind 5 deletion retracts
the last one now rather than letting it expire; kind 11801 is
replaceable, so the deletion names the event id and the coordinate."""
cur = self.public_descriptor()
if cur is None:
return dict(self._retract_public())
out: Mapping[str, Any] = {}
if self.relays:
out = relay.publish_all(self.relays, cur, self.timeout)
if any(ok for ok, _ in out.values()):
self._remember_public(str(cur['id']))
return dict(out)
def _remember_public(self, descriptor_id: str) -> None:
"""Remember the public descriptor id, on disk so a restart can retract it."""
self._published_public_id = descriptor_id
try:
with open(self._public_id_path(), 'w', encoding='utf-8') as f:
f.write(descriptor_id + '\n')
except OSError as e:
# A marker that cannot be written costs the next start its chance
# to retract a restart that begins private; said, not swallowed.
self.counts['public marker failed'] += 1
_line(' could not record the public descriptor id:', str(e))
def _forget_public(self) -> None:
self._published_public_id = None
try:
os.unlink(self._public_id_path())
except OSError as e:
if not isinstance(e, FileNotFoundError):
_line(' could not clear the public descriptor marker:', str(e))
def _public_id_path(self) -> str:
return os.path.join(self.dir, self.PUBLIC_ID_FILE)
def _load_public_id(self) -> None:
try:
with open(self._public_id_path(), encoding='utf-8') as f:
value = f.read().strip()
except OSError:
return
if value:
self._published_public_id = value
def _retract_public(self) -> Mapping[str, Any]:
"""Delete the last public descriptor from the public relays (NIP-09)."""
last = self._published_public_id
if last is None or not self.relays:
return {}
deletion = store_mod.make_signed_event(
self.ks.node_sk, self.clock(), 5,
[['e', last], ['a', '11801:%s:' % self.ks.node_pk], ['k', '11801']], '')
out = dict(relay.publish_all(self.relays, deletion, self.timeout))
if any(ok for ok, _ in out.values()):
self._forget_public()
self._retracted_at = int(deletion['created_at'])
_line(' retracted the public descriptor', last[:12] + '…', '(kind 5)')
return out
[docs] def redescribe(self) -> NostrEvent:
"""Rebuild the descriptor from what the compartments say NOW and
publish it. For a compartment whose declaration changed after start
(a sidecar's self-tests began passing, or stopped): the kind 11801
must say what is true, and a replaceable event costs one proof of
work to correct - cheaper than a leaf dialling a protocol nothing
here answers."""
d = self.build_descriptor()
self.publish_descriptor()
return d
[docs] def start(self) -> NodeApp:
"""Bring the node up. All or nothing: a start that raises leaves no
bound face, no running transport and no started compartment behind.
Audit L1, option c - both halves:
a. `_start` puts every point that can refuse - assemble, wire, the
plugin-origin check, route, and each compartment's start() -
before anything another machine can see. The face starts serving
only after the router exists, and a freshly mined descriptor is
published only after Registry.start returns. (The face's socket
is bound when the RelayServer is constructed, which is earlier;
the `from_context` readers hold that object and read its port
lazily, so none of them needs it serving.)
b. This wrapper is the backstop. With Registry.start's own unwinding,
a refused start releases its port at once rather than at process
exit, and no compartment that started is left running.
A refused start therefore publishes nothing. What it mined stays on
disk under PENDING_FILE and is published by the next start that
succeeds.
"""
try:
return self._start()
except BaseException:
self._abandon_start()
raise
def _abandon_start(self) -> None:
"""Release whatever a failed start had taken. Every step is guarded:
the raise that brought us here is the one the operator must see."""
self._stop.set()
steps: list[Callable[[], Any]] = []
if getattr(self, 'control', None) is not None:
steps.append(self.control.stop)
if self._built:
steps.append(self.subsystems.stop)
steps += [self.transport.stop]
if self.face is not None:
steps.append(self.face.stop)
if getattr(self, 'protocols', None) is not None:
steps.append(self.protocols.stop_all)
if getattr(self, 'host', None) is not None:
steps.append(self.host.stop)
for step in steps:
try:
step()
except Exception as e:
_line(' while abandoning the start:', '%s: %s' % (type(e).__name__, e))
self._stopped = True
def _start(self) -> NodeApp:
_line('starting', self.ks.did[:22] + '…', 'class', self.cfg['class'])
pending = os.path.join(self.dir, self.PENDING_FILE)
if self.descriptor is None and self.load_descriptor() is None:
mined = self.build_descriptor()
if self.public_descriptor() is not None:
with open(pending, 'w', encoding='utf-8') as f:
f.write(mined['id'] + '\n')
_line(' mined a descriptor', mined['id'][:12] + '…',
'(%d bits)' % identity.pow_bits(mined['id']))
elif os.path.exists(pending):
_line(' reusing a descriptor no relay has accepted yet',
self._descriptor()['id'][:12] + '…')
else:
_line(' reusing the descriptor it already published',
self._descriptor()['id'][:12] + '…')
# What it published publicly last time, if anything: a start that comes
# up fully private retracts it (see _publish_pending).
self._load_public_id()
# The compartments, built from one context in the declared tick order.
# Each class says what it needs (`requires`) and the assembler refuses
# a manifest that contradicts it; what each one takes from the node is
# in its own `from_context`, not here. See MANIFEST for the order and
# the reasons behind it.
self.subsystems = compartment_mod.Registry(say=self.says.say)
self.context.descriptor = self._descriptor
self.context.public_descriptor = self.public_descriptor
self.context.digest = descriptor.DIGEST
self.manifest = load_plugins(self.settings.plugins.specs, MANIFEST)
self.subsystems.assemble(self.context, self.manifest)
# Every edge that runs against tick order (link records into strain,
# peering refuses through capacity, budget reports through the
# reporter, the face asks paid_fetch for a price ...) is named by the
# compartment that owns it, in its `wire()`, and reached here once
# the whole manifest exists. The node no longer holds that list.
self.subsystems.wire(self.context)
# Every compartment's declared channels and metrics, in one place. A
# rejected metric is kept in the registry's state rather than raised:
# one malformed declaration must not stop a node booting, and it is
# reported by `meshnode health` instead of vanishing.
self.says.register_from(list(self.subsystems))
self.monitors.register_from(list(self.subsystems))
# And the lifecycle's own: every compartment moves through the same
# machine, so its transitions are the registry's to say and count.
self.says.register(lifecycle_mod.CHANNELS)
self.monitors.register(self.subsystems.lifecycle_metrics(), owner='lifecycle')
# And every declared store's size, bound and counts, labelled by
# compartment: memory metered without a compartment writing a metric.
self.monitors.register(self.subsystems.store_metrics(), owner='stores')
self.settle_engine: settlement_mod.SettlementEngine = self.settlement.engine
self.mediator: mediation_mod.MediatorService = self.mediation.service
# The router is a dumb ladder: each compartment declares the
# protocols it speaks (`piuris`, `exact_types`) and the registry
# puts its `handle` behind them. A plugin speaks its own origin; one
# that claims fleetmesh.org's is refused before it is routed. One
# that fronts a sidecar declares its manifest(s) as `sidecars`
# (dicts, or '@/path.json'); they join the registry before the
# sidecars compartment runs its first self-test below.
for cls in self.manifest:
if cls in MANIFEST:
continue
for piuri in getattr(cls, 'piuris', ()) or ():
if piuri.startswith(identity.FLEETMESH):
raise ValueError('plugin %s claims fleetmesh.org protocol %s; plugins speak their own origin' % (cls.name, piuri))
for sc in plugin_sidecars(cls):
self.sidecars.declare(sc)
self.router = router_mod.ProtocolRouter()
self.subsystems.route(self.router)
# What the last process left for the compartments that declare
# `snapshot`, handed back before any of them starts. Never raises; a
# refusal is recorded on the compartment's lifecycle and it starts
# fresh. The file is discarded only once the start succeeds, so a
# refused start does not cost the next one its continuity.
saved, saved_at, why_not = lifecycle_mod.read_snapshots(self.dir, self.clock())
if why_not:
_line(' ' + why_not)
for name, what in self.subsystems.restore(saved, saved_at).items():
_line(' %s: %s' % (name, what))
# Everything above can refuse and none of it is visible off this
# machine. From here on the node starts being seen: the face serves
# (before the compartments start, because some of them dial it), the
# transport subscribes, and - once they have started - the
# descriptor is published.
self.host.start()
self.protocols.start_all()
if self.face is not None:
self.face.start()
self.strain.record('restart')
self.transport.start()
wait_listen_timeout = float(self.cfg.get('wait_listening_timeout', 5.0))
if self.relays and wait_listen_timeout > 0 and not self.transport.wait_listening(wait_listen_timeout):
# Said, not waited on for ever. Until a relay acknowledges the
# subscription this node cannot receive a live wrap and would not
# know it had missed one, because kind 21059 is ephemeral and no
# relay keeps a copy. Starting anyway is right - the stored kind
# replays, the compartments have work that needs no inbox, and
# `link` will keep saying so - but starting silently is not.
_line(' no relay has acknowledged the inbox subscription yet;',
'live messages sent before it does are lost')
if not self.settings.face.port and not self.settings.protocol_suites.host.port:
# Port 0 asks the kernel for any free port, which is right for a test
# and wrong for a node an operator runs: the relay face moved on every
# restart, so every client holding its address lost it. Record what we
# were given, once.
port_assigned = self.host.port if self.host is not None else (self.face.server.port if self.face and self.face.server else 0)
self.cfg['face'] = dict(self.cfg.get('face') or {}, port=port_assigned)
self.save_coverage()
_line(' recorded the edge face port', port_assigned, 'so it survives a restart')
edge_url = self.face.url if self.face is not None else self.host.url
_line(' edge face', edge_url, '| relays', ', '.join(self.relays) or '(none)',
'| descriptor', self._descriptor()['id'][:12] + '…')
if not self.cfg['endpoints']:
_line(' no endpoint configured: reachable over the nostr transport only')
_line(' peers configured:', len(self.cfg.get('peers', [])),
'| grants held:', len(self.grants.list()))
# The registry's own lifecycle verb, which nothing called: presence
# holds the heartbeat subscription open and had no way to say so.
# It unwinds itself when a required compartment cannot start, so
# `_built` - which tells stop() to stop the compartments - is set only
# once they have (audit L1: it used to be set before, and a failed
# start then sent the budget's farewell for a node that never served).
self.subsystems.start()
self._built = True
lifecycle_mod.discard_snapshots(self.dir)
self._publish_pending(pending)
self.control = control_mod.Server(self.dir, self.control_request).start()
threading.Thread(target=self._serve, daemon=True).start()
sd_notify('READY=1\nSTATUS=Fleetmesh node active')
self._start_watchdog()
return self
def _publish_pending(self, pending: str) -> None:
"""Publish the public descriptor a start just mined or reused, and - the
other direction - retract the last one when the node comes up fully
private. The marker goes only when a relay accepted it: a node with no
relays configured, or none reachable, publishes on the next start
instead of believing it already had."""
if not self.relays:
return
cur = self.public_descriptor()
if cur is None:
# Fully private: nothing to publish, and any public descriptor the
# last run left on a relay is retracted now rather than left to
# expire. There is nothing pending to accept.
self._retract_public()
if os.path.exists(pending):
os.unlink(pending)
return
if not os.path.exists(pending):
return
out = relay.publish_all(self.relays, cur, self.timeout)
if any(ok for ok, _ in out.values()):
self._remember_public(str(cur['id']))
os.unlink(pending)
else:
_line(' no relay accepted the descriptor yet; the next start publishes it')
def _start_watchdog(self) -> None:
watchdog_usec = os.environ.get('WATCHDOG_USEC')
if watchdog_usec:
try:
usec = int(watchdog_usec)
if usec > 0:
interval = (usec / 1_000_000.0) / 2.0
threading.Thread(target=self._watchdog_loop, args=(interval,), daemon=True).start()
except (ValueError, TypeError):
pass
def _watchdog_loop(self, interval: float) -> None:
while not self._stop.is_set():
if self._stop.wait(interval):
break
sd_notify('WATCHDOG=1')
[docs] def run(self) -> None:
"""Tick on the configured cadence until stop()."""
while not self._stop.is_set():
try:
for d in self.tick():
_line(' ', ' '.join(_short(x) for x in d))
except Exception as e: # one bad tick must not stop the node
self.log.append(('tick failed', str(e)))
self.counts['tick failed'] += 1
self._last_tick_error = '%s: %s' % (type(e).__name__, e)
_line(' tick failed:', e)
self._stop.wait(self.cfg.get('tick_seconds', 30))
[docs] def stop(self) -> None:
# Once. `meshnode run` stops from the SIGTERM handler and again from
# its finally:, and each pass said goodbye: every peer got the same
# window's farewell at two sequence numbers a few seconds apart, and
# whichever end saw the second first read the first as a receipt the
# wire had dropped. The three-continent mesh reported that gap on two
# of three nodes after its first restart.
if self._stopped:
return
self._stopped = True
sd_notify('STOPPING=1\nSTATUS=Fleetmesh node shutting down')
self._stop.set()
# Before the transport goes, tell every peer what this node used. A node
# that simply vanishes leaves its issuer with traffic measured and no
# receipt, which is active silence and an S2 - and an S2 drops the tier
# to probation, which only a person can raise again. That made the
# fleet-wide restart a digest change requires cost every peering its
# tier, every time.
if getattr(self, '_built', False):
# The registry stops every compartment, and the budget's stop is the
# farewell. Calling it here as well sent every peer two receipts for
# the same window at two sequence numbers - valid, and pointless.
for name, did in self.subsystems.stop():
for d in (did or []):
_line(' ' + ' '.join(str(x) for x in d))
# After stop(), so the snapshot is what each compartment ended
# with. Only on a clean stop: a process that died wrote nothing,
# and the next one starts its compartments fresh.
snaps = self.subsystems.snapshot()
if snaps:
try:
lifecycle_mod.write_snapshots(self.dir, self.clock(), snaps)
_line(' kept the state of', ', '.join(snaps), 'for the next start')
except OSError as e:
_line(' could not keep compartment state:', '%s: %s' % (type(e).__name__, e))
if getattr(self, 'control', None) is not None:
self.control.stop()
self.transport.stop()
if self.face is not None:
self.face.stop()
if getattr(self, 'protocols', None) is not None:
self.protocols.stop_all()
if getattr(self, 'host', None) is not None:
self.host.stop()
[docs] def close(self) -> None:
"""Safely stop node workers and close all persistent database connections.
A close that fails is counted and said. The four stores here are shut
in turn and a failure in one must not leave the other three open, so
the exception is still caught - but it is no longer discarded: a store
that cannot close (a locked database, a disk full at commit) is
exactly the one an operator needs told about at restart, and
`except Exception: pass` told nobody (audit 2026-10-07, L5)."""
self.stop()
for name in ('store', 'accounts', 'grants', 'blobs', 'video'):
st = getattr(self, name, None)
if st is not None and hasattr(st, 'close'):
try:
st.close()
except Exception as e:
self.log.append(('close failed', '%s: %s' % (name, e)))
self.counts['close failed'] += 1
_line(' closing %s failed:' % name, '%s: %s' % (type(e).__name__, e))
# ---- inbound -------------------------------------------------------------------
# The door's refusal code for a private unit served to a stranger: the same
# code the network's own admission uses (fleetmesh_core.network.join).
NOT_MEMBER: str = 'not_member'
def _declared_protocol_of(self, msg_type: str) -> Optional[str]:
"""The declared protocol a message type belongs to, or None.
The unit is a `c` tag value of this node's descriptor: a message whose
type starts with it is a request on that protocol. A message on
something the node does not declare - control/1.0, a mediator's, a
dialect's - belongs to no unit and is not gated by visibility (it has
its own authorisation, or none)."""
desc = self.descriptor
if not isinstance(desc, Mapping):
return None
best: Optional[str] = None
for unit in identity.protocols_of(desc):
if msg_type.startswith(unit) and (best is None or len(unit) > len(best)):
best = unit
return best
def _visible_refusal(self, msg_type: str, sender: str) -> Optional[str]:
"""Whether this request may be served to `sender`, as a refusal code.
Plan D2: a request on a protocol that resolves private is served only
to a node on a private network this one is on; anyone else is refused
as `not_member`. A public protocol - the default - behaves exactly as
before. None means serve it."""
unit = self._declared_protocol_of(msg_type)
if unit is None:
return None
vis = self.visibility_config()
if visibility_mod.resolve(vis.default, vis.overrides, unit) == visibility_mod.PUBLIC:
return None
if self._network_member(sender):
return None
return self.NOT_MEMBER
def _network_member(self, sender: str) -> bool:
"""Whether the network compartment's rosters name `sender` on a network
this node is configured for. False before the node is built, and for a
network compartment that cannot answer: admitting nobody is the safe
reading of "the roster does not say yes"."""
if not sender or not getattr(self, '_built', False):
return False
registry = getattr(self, 'subsystems', None)
net = registry.get('network') if registry is not None else None
if net is None or not hasattr(net, 'member_of_any'):
return False
try:
return bool(net.member_of_any(sender))
except Exception: # noqa: BLE001 - a network compartment in trouble admits nobody
return False
def _say_once(self, key: str, *parts: Any, every: float = 60) -> None:
"""One log line per key per minute. A peer that sends the same
malformed message forever must not own the journal."""
now = time.time()
if now - self._last_said.get(key, 0) < every:
return
self._last_said[key] = now
if len(self._last_said) > 500:
self._last_said = {k: v for k, v in self._last_said.items() if now - v < every}
_line(*parts)
def _serve(self) -> None:
while not self._stop.is_set():
inbound = self.transport.receive(timeout=0.5)
if inbound is None:
continue
# The door. A message without the shape of its type is dropped here
# with a reason, counted, and never reaches a handler; what a handler
# had done before it raised on a bad field used to stay done.
why = validate.check(inbound.message)
if why is not None:
self.rejected[why] += 1
self._say_once('rejected:' + why, '! rejected', _short(inbound.sender),
str(inbound.message.get('type'))[-40:], '-', why)
continue
# Visibility enforcement (plan D2): a request on a protocol this
# node offers privately is served only to a member of a private
# network it is on. The same door, counted the same way, with the
# code the network's own admission uses.
denied = self._visible_refusal(inbound.message.get('type') or '', inbound.sender)
if denied is not None:
self.rejected[denied] += 1
self._say_once('rejected:' + denied, '! refused', _short(inbound.sender),
str(inbound.message.get('type'))[-40:], '-', denied)
continue
try:
done = self.router.dispatch(inbound)
except Exception as e:
self.log.append(('handler failed', inbound.message.get('type'), str(e)))
self.counts['handler failed'] += 1
self._say_once('handler:' + str(inbound.message.get('type')),
'! handler failed on', inbound.message.get('type'), '-', e)
done = ('error',)
if done is not None:
self.log.append(done)
if done[0] not in ('ignored',):
_line('<', ' '.join(_short(x) for x in done[:3]))
# What an operator may change while the node runs. The rest - class, keys,
# relays - is what the node is. Every live key belongs to the compartment
# that reads it, and this is what is left over: nothing.
LIVE_KEYS: tuple[str, ...] = ()
[docs] def reload_config(self) -> None:
"""Take up whatever the operator has written since the last tick.
Every command writes the config and nothing else, because a running node
owns its directory and its relay face port and a second process cannot
stand one up beside it. So the file is the interface, and it is read in
one place: `trust` was being re-read and `coverage` was not, which meant
a shard added to the file was never claimed until the node restarted.
Neither is named here now. A compartment declares the keys it re-reads
and the registry collects them, so the list cannot fall behind the
mechanism that depends on it.
"""
try:
fresh = load_config(self.dir) or {}
except (OSError, ValueError) as e:
# The last good config stays in force. Said once a minute, not once
# a tick, and shown in status so an operator finds it without the log.
self._config_error = str(e)
self.counts['config rejected'] += 1
self._say_once('config', '! config.json is not usable, keeping the last good one:', e)
return
self._config_error = None
for key in tuple(self.LIVE_KEYS) + self.subsystems.live_keys():
if key in fresh:
self.cfg[key] = fresh[key]
# Plan D28: `brands` is not a live key a compartment re-reads - it is the
# node's own descriptor self-label, so a change to it REDESCRIBES the
# node: rebuild the descriptor and republish the public copy, the same
# shape a `set-visibility` takes. A no-op on most ticks.
if list(fresh.get('brands') or []) != list(self.cfg.get('brands') or []):
self.cfg['brands'] = list(fresh.get('brands') or [])
if self._built:
self.build_descriptor()
self.publish_descriptor()
if self._built and self.capacity.set_total(self.cfg.get('capacity')):
_line(' aggregate ceiling is now',
', '.join('%s %s' % kv for kv in sorted(self.capacity.total.items()))
or 'undeclared - this node will accept load until it fails')
if self._built:
self._reconfigure(fresh)
def _reconfigure(self, fresh: Mapping[str, Any]) -> list[str]:
"""Take up a changed config block that is not live, by restarting its owner.
A live key is copied above and its compartment re-reads it. Any other
block used to wait silently for the next node restart. Now, when the
compartment that owns it declares `Lifecycle(restart=True)`, the new
block is parsed first - the running settings stay if it does not
parse - then adopted, and the compartment restarted in place. One that
does not declare restart keeps the running settings and the operator
is told, once a minute, that the edit waits for the node.
Returns the names restarted.
"""
done: list[str] = []
for s in self.subsystems:
blk = getattr(s, 'config_cls', None)
own = getattr(blk, 'key', '') if blk is not None else ''
if blk is None or not own or own in s.live or fresh.get(own) == self.cfg.get(own):
continue
name = s.name or ''
if not self.subsystems.restartable(name):
# Once per edit: the running settings are right until the
# node restarts, so this is news when it changes, not weather.
if self._waiting.get(own) != fresh.get(own):
self._waiting[own] = fresh.get(own)
_line(' %s changed in config.json;' % own, name, 'takes it up when the node restarts')
continue
try:
blk.from_dict(fresh.get(own) or {})
except Exception as e:
self._say_once('config:' + own, '! %s in config.json is not usable, keeping the running one:' % own, e)
continue
if own in fresh:
self.cfg[own] = fresh[own]
else:
self.cfg.pop(own, None)
state = self.subsystems.restart(name, 'its %s block changed' % own)
_line(' %s restarted for its new %s settings:' % (name, own), state)
done.append(name)
return done
[docs] def tick(self, now: int | None = None) -> list[tuple[Any, ...]]:
with self._tick_lock:
return self._tick(now)
GROUP_POLL_SECONDS: int = 300
GROUP_FRESH_SECONDS: int = 30 # a wire decision refreshes the circle's documents when older than this
[docs] def published_operator(self) -> Optional[str]:
"""The operator this node's public descriptor names: none unless the
config sets `publish_operator` (plan D26 - ownership is blinded by
default; a public anchor or mediator may declare it for the
independence model). The node's own authority never reads this."""
return self.cfg.get('operator') if self.cfg.get('publish_operator') else None
[docs] def operator_relays(self) -> list[str]:
"""Where operator-specific material is fetched (plan D26): the relays
of the node's private networks and any the operator named in
`operator_relays` - never the node's public relays, where a query by
the operator's key or DID would link this node to its operator."""
out = [str(u) for u in (self.cfg.get('operator_relays') or [])]
net = self.subsystems.get('network') if getattr(self, '_built', False) else None
if net is not None and hasattr(net, 'network_relays'):
try:
out += [u for u in net.network_relays() if u not in out]
except Exception as e: # noqa: BLE001 - a network compartment in trouble yields no relays, not a crash
self._say_once('network-relays', '! the network compartment named no relays:', e)
return out
[docs] def poll_group(self, now: int, force: bool = False, max_age: Optional[int] = None) -> int:
"""When the operator is a did:group, fetch its controller documents and
revocation lists from operator_relays() (plan D26) into the ledger, at most every
GROUP_POLL_SECONDS. A new epoch or a member's revocation reaches the
node this way. Returns how many events were new; a relay down is not
an error."""
op = self.operator_did()
relays_for_op = self.operator_relays()
if not op or not op.startswith('did:group:') or not relays_for_op:
return 0
if not force and now - self._group_polled_at < (self.GROUP_POLL_SECONDS if max_age is None else max_age):
return 0
self._group_polled_at = now
try:
events = relay.query_all(relays_for_op, [{'kinds': [30834], '#g': [op]}, {'kinds': [30833], '#d': [op]}],
timeout=self.timeout)
except Exception as e: # a relay down is state, not a crash
self._say_once('group-poll', '! cannot reach the relays for the circle documents:', e)
return 0
events = sorted(events, key=lambda ev: (int(ev.get('created_at', 0)), str(ev.get('id'))))
added = self.groups.add_docs([e for e in events if e.get('kind') == 30834])
added += self.groups.add_revocations([e for e in events if e.get('kind') == 30833 and store_mod.verify_event(e)])
if added:
self.groups.save()
return added
[docs] def poll_revocations(self, authors: Sequence[str], now: int, max_age: Optional[int] = None) -> int:
"""Fetch the kind 30833 lists these keys signed from operator_relays() (plan D26)
into the ledger, each key at most every GROUP_POLL_SECONDS (or
`max_age`). This is how a person operator's revocation, or one by an
issuer further down a grant chain, reaches the node; a circle's arrive
with poll_group. Only lists whose signature verifies are kept: relays
hand events back unverified, and a forged list would revoke grants its
author never named. Returns how many lists were new; a relay down is
not an error."""
relays_for_op = self.operator_relays()
if not relays_for_op:
return 0
window = self.GROUP_POLL_SECONDS if max_age is None else max_age
polled = self._revocations_polled_at
due = sorted({a for a in authors if isinstance(a, str) and (a not in polled or now - polled[a] >= window)})
if not due:
return 0
for a in due:
polled[a] = now
try:
events = relay.query_all(relays_for_op, [{'kinds': [30833], 'authors': due}], timeout=self.timeout)
except Exception as e: # a relay down is state, not a crash
self._say_once('revocation-poll', '! cannot reach the relays for revocation lists:', e)
return 0
lists = [e for e in events if e.get('kind') == 30833 and e.get('pubkey') in due and store_mod.verify_event(e)]
added = self.groups.add_revocations(sorted(lists, key=lambda ev: (int(ev.get('created_at', 0)), str(ev.get('id')))))
if added:
self.groups.save()
return added
def _tick(self, now: int | None = None) -> list[tuple[Any, ...]]:
"""One tick: take up the config, run every compartment, write the status.
This was a hundred and thirty lines with five mechanisms in it. What is
left is the three things the node itself owns - the config file, the
registry, and status.json - and one line about clock drift, which is
read here because it is the operator's to act on at both ends and not
one node's to fix.
"""
now = now if now is not None else self.clock()
seen_drift = len(self.budget.clock_drift)
self.reload_config()
self.poll_group(now)
self.poll_revocations(authority_mod.revocation_authors(self.operator_did()), now)
self.check_enrolment(now) # plan D22: an enrolment ends when it is revoked
did = self.subsystems.tick(now)
self._last_tick = did
for peer, epoch, drift, _at in self.budget.clock_drift[seen_drift:]:
_line(' a receipt from', _short(peer), 'is timed %ds from this clock' % drift,
'- check NTP on both ends before reading any divergence')
self.write_status(did)
sd_notify('WATCHDOG=1')
return did
# ---- status --------------------------------------------------------------------
PLANES: tuple[tuple[str, str, tuple[str, ...]], ...] = _VIEW_PLANES
[docs] def status(self) -> Mapping[str, Any]:
return node_status(self)
[docs] def health(self) -> Mapping[str, Any]:
"""What is failing, and how often: the operator's view of every error
plane the node has. Nothing here is a finding about a peer."""
return node_health(self)
[docs] def write_status(self, did: Sequence[tuple[Any, ...]] | None = None) -> Mapping[str, Any]:
if did:
self._last_tick = did
st = self.status()
path = os.path.join(self.dir, 'status.json')
tmp = path + '.tmp'
with open(tmp, 'w', encoding='utf-8') as f:
json.dump(st, f, indent=2)
os.replace(tmp, path)
return st