2. Application Host & Subsystems (fleetmesh_node.app)
The fleetmesh_node.app package is the core orchestrator that bootstraps configuration,
initializes the storage engine, registers the 29 compartments, opens the control socket,
and manages the event loop.
2.1. Host Core
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.
- class fleetmesh_node.app.core.NodeApp[source]
Bases:
ControlMixin- 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
- load_descriptor()[source]
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.
- Return type:
NostrEvent | None
- visibility_config()[source]
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.
- Return type:
- destination_relays()[source]
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.
- public_descriptor()[source]
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.
- Return type:
NostrEvent | None
- publish_descriptor()[source]
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.
- redescribe()[source]
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.
- Return type:
- start()[source]
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:
_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.)
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.
- Return type:
- close()[source]
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).
- Return type:
None
- reload_config()[source]
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.
- Return type:
None
- published_operator()[source]
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 type:
str | None
- operator_relays()[source]
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.
- poll_group(now, force=False, max_age=None)[source]
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.
- poll_revocations(authors, now, max_age=None)[source]
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.
- PLANES: tuple[tuple[str, str, tuple[str, ...]], ...] = (('relays', 'link', ('relays',)), ('dropped', 'link', ('dropped',)), ('recent_faults', 'link', ('recent_faults',)), ('publish_refused_in_window', 'link', ('publish_refused_in_window',)), ('cooling', 'link', ('cooling',)), ('inbox', 'link', ('inbox',)), ('wraps_in', 'link', ('wraps_in',)), ('wraps_seen_again', 'link', ('wraps_seen_again',)), ('unfinished_envelopes', 'link', ('unfinished_envelopes',)), ('awaiting_ack', 'link', ('awaiting_ack',)), ('unacknowledged', 'link', ('unacknowledged',)), ('sessions_open', 'sync', ('open',)), ('sessions_refused', 'sync', ('refused',)), ('sync_unsent', 'sync', ('unsent',)), ('malformed_sync', 'sync', ('malformed',)), ('budget_rejected', 'budget', ('rejected',)), ('receipts_refused', 'budget', ('receipts_refused',)), ('malformed_complaints', 'reporter', ('malformed',)), ('peering_refused', 'peering', ('refusals', 'recent')), ('throttled', 'scheduler', ('throttled',)), ('capacity', 'capacity', ()), ('strain', 'strain', ()))
2.2. Configuration Assembler
The node’s configuration: the control-socket table, the defaults, and the file that carries them.
Separate from the node so meshnode init, peer and trust can read and write config.json without constructing a NodeApp.
- exception fleetmesh_node.app.config.ConfigError[source]
Bases:
ValueErrorconfig.json says something the node cannot run on. The message lists every problem, because an operator fixes a file once, not one line per restart.
- class fleetmesh_node.app.config.NodeConfig[source]
Bases:
BlockNodeConfig(cls_: ‘str’ = ‘edge’, name: ‘str’ = ‘meshnode’, relays: ‘tuple[str, …]’ = (), face: ‘FaceConfig’ = FaceConfig(host=’127.0.0.1’, port=0, future_seconds=900, roster_export_path=None), endpoints: ‘tuple[Endpoint, …]’ = (), protocols: ‘tuple[str, …]’ = (’https://fleetmesh.org/sync/1.0’,), capabilities: ‘tuple[str, …]’ = (‘relay’, ‘negentropy’), brands: ‘tuple[str, …]’ = (), operator: ‘Optional[str]’ = None, publish_operator: ‘bool’ = False, operator_relays: ‘tuple[str, …]’ = (), pow_bits: ‘Optional[int]’ = None, visibility: ‘VisibilityConfig’ = VisibilityConfig(default=’public’, overrides={}), policy: ‘PolicyConfig’ = PolicyConfig(open_enrolment=True, protocols=(), DERIVED=False), coverage: ‘tuple[CoverageClaim, …]’ = (), handover: ‘str’ = ‘offer’, retention: ‘dict[int, int]’ = <factory>, trust: ‘dict[str, TrustDecision]’ = <factory>, peers: ‘tuple[PeerPull, …]’ = (), tick_seconds: ‘int’ = 30, heartbeat: ‘bool’ = True, projection: ‘bool’ = True, telemetry: ‘bool’ = False, fetch_pricing: ‘FetchPricingConfig’ = FetchPricingConfig(default_msat=0, free_for_partners=True, free_bytes_per_day=None, max_account_fee_msat=0, grasp_session_msat=0, sidecar_session_msat={}, rules=(), cashu=CashuRail(mints=(), unit=’sat’, sweep_above_sat=0, sweep_to=None), DERIVED=False), bridge: ‘Optional[BridgeConfig]’ = None, announce: ‘AnnounceConfig’ = AnnounceConfig(enabled=False, socket=None, pow_bits=0), lan: ‘LanConfig’ = LanConfig(enabled=False), p2p: ‘Optional[P2PConfig]’ = None, gossip: ‘Optional[GossipConfig]’ = None, capacity: ‘CapacityConfig’ = CapacityConfig(total={}), compute: ‘Optional[ComputeConfig]’ = None, dvm: ‘Optional[DVMConfig]’ = None, nsite: ‘Optional[NsiteConfig]’ = None, settlement: ‘SettlementConfig’ = SettlementConfig(nwc_uri=None, live_cashu=False, mint_url=None), mediation: ‘MediationConfig’ = MediationConfig(), transport: ‘TransportConfig’ = TransportConfig(), blob_wire: ‘BlobWireConfig’ = BlobWireConfig(accept_from=’none’, chunk_bytes=None, bytes_per_day=None, max_concurrent=None, max_blob_bytes=None, max_total_bytes=None, DERIVED=False), blob_replication: ‘BlobReplicationConfig’ = BlobReplicationConfig(copies=2, allow_private=False, source_url=None, servers=(), DERIVED=False), storage: ‘StorageConfig’ = StorageConfig(max_bytes=None, allow_private_mirror=False), blobs: ‘BlobsConfig’ = BlobsConfig(max_storage_bytes=None, fanout=1, data_dir=None), sidecars: ‘SidecarsConfig’ = SidecarsConfig(entries={}, DERIVED=False), plugins: ‘PluginsConfig’ = PluginsConfig(specs=()), updates: ‘Optional[UpdatesConfig]’ = None, network: ‘Optional[NetworkConfig]’ = None, protocol_suites: ‘ProtocolSuitesConfig’ = ProtocolSuitesConfig(host=HostMultiplexerConfig(listen=’127.0.0.1’, port=0, public_url=None, bind_wait=10.0), nostr=NostrProtocolConfig(enabled=True, relays=(), require_auth=False, future_seconds=900), atproto=ATProtoProtocolConfig(enabled=False, handle=None, service_did=None, pds_enabled=True, firehose_subscribe=False, firehose_publish=True, relay_upstream=None, metered_peering=True), activitypub=ActivityPubProtocolConfig(enabled=False, domain=None, summary=’Fleetmesh Sovereign Edge Node’, rate_limit_per_inbox=60, allow_local_federation=False), ssb=SSBProtocolConfig(enabled=False, port=8008, caps=’d4a1da283c1e443e022da12bc6139952b324e4001f40fa38ba5754035a49807f’), p2panda=P2PandaProtocolConfig(enabled=False, port=9102, network_id=’fleetmesh-default’, discovery=True, allow_local_peers=False), rhio=RhioProtocolConfig(enabled=False, nats_endpoint=’localhost:4222’, s3_endpoint=’http://localhost:9000’, network_id=’rhio-default-network-1’, bind_port=9102, http_bind_port=3000)), extensions: ‘Mapping[str, Any]’ = <factory>)
- face: FaceConfig = FaceConfig(host='127.0.0.1', port=0, future_seconds=900, roster_export_path=None)
- visibility: VisibilityConfig = VisibilityConfig(default='public', overrides={})
- policy: PolicyConfig = PolicyConfig(open_enrolment=True, protocols=(), DERIVED=False)
- coverage: tuple[CoverageClaim, ...] = ()
- trust: dict[str, TrustDecision]
- fetch_pricing: FetchPricingConfig = FetchPricingConfig(default_msat=0, free_for_partners=True, free_bytes_per_day=None, max_account_fee_msat=0, grasp_session_msat=0, sidecar_session_msat={}, rules=(), cashu=CashuRail(mints=(), unit='sat', sweep_above_sat=0, sweep_to=None), DERIVED=False)
- bridge: BridgeConfig | None = None
- announce: AnnounceConfig = AnnounceConfig(enabled=False, socket=None, pow_bits=0)
- gossip: GossipConfig | None = None
- capacity: CapacityConfig = CapacityConfig(total={})
- compute: ComputeConfig | None = None
- settlement: SettlementConfig = SettlementConfig(nwc_uri=None, live_cashu=False, mint_url=None)
- mediation: MediationConfig = MediationConfig()
- transport: TransportConfig = TransportConfig()
- blob_wire: BlobWireConfig = BlobWireConfig(accept_from='none', chunk_bytes=None, bytes_per_day=None, max_concurrent=None, max_blob_bytes=None, max_total_bytes=None, DERIVED=False)
- blob_replication: BlobReplicationConfig = BlobReplicationConfig(copies=2, allow_private=False, source_url=None, servers=(), DERIVED=False)
- storage: StorageConfig = StorageConfig(max_bytes=None, allow_private_mirror=False)
- blobs: BlobsConfig = BlobsConfig(max_storage_bytes=None, fanout=1, data_dir=None)
- sidecars: SidecarsConfig = SidecarsConfig(entries={}, DERIVED=False)
- plugins: PluginsConfig = PluginsConfig(specs=())
- updates: UpdatesConfig | None = None
- network: NetworkConfig | None = None
- protocol_suites: ProtocolSuitesConfig = ProtocolSuitesConfig(host=HostMultiplexerConfig(listen='127.0.0.1', port=0, public_url=None, bind_wait=10.0), nostr=NostrProtocolConfig(enabled=True, relays=(), require_auth=False, future_seconds=900), atproto=ATProtoProtocolConfig(enabled=False, handle=None, service_did=None, pds_enabled=True, firehose_subscribe=False, firehose_publish=True, relay_upstream=None, metered_peering=True), activitypub=ActivityPubProtocolConfig(enabled=False, domain=None, summary='Fleetmesh Sovereign Edge Node', rate_limit_per_inbox=60, allow_local_federation=False), ssb=SSBProtocolConfig(enabled=False, port=8008, caps='d4a1da283c1e443e022da12bc6139952b324e4001f40fa38ba5754035a49807f'), p2panda=P2PandaProtocolConfig(enabled=False, port=9102, network_id='fleetmesh-default', discovery=True, allow_local_peers=False), rhio=RhioProtocolConfig(enabled=False, nats_endpoint='localhost:4222', s3_endpoint='http://localhost:9000', network_id='rhio-default-network-1', bind_port=9102, http_bind_port=3000))
- WRITTEN_BY_DEFAULT: ClassVar[tuple[str, ...]] = ('class', 'relays', 'face', 'endpoints', 'protocols', 'capabilities', 'brands', 'operator', 'pow_bits', 'policy', 'coverage', 'handover', 'retention', 'trust', 'peers', 'tick_seconds', 'heartbeat', 'projection', 'fetch_pricing')
- BLOCKS: ClassVar[dict[str, type[Block] | None]] = {'announce': <class 'fleetmesh_node.config.compartments.AnnounceConfig'>, 'blob_replication': <class 'fleetmesh_node.config.compartments.BlobReplicationConfig'>, 'blob_wire': <class 'fleetmesh_node.config.compartments.BlobWireConfig'>, 'blobs': <class 'fleetmesh_node.config.compartments.BlobsConfig'>, 'brands': None, 'bridge': <class 'fleetmesh_node.config.compartments.BridgeConfig'>, 'capabilities': None, 'capacity': <class 'fleetmesh_node.config.compartments.CapacityConfig'>, 'class': None, 'compute': <class 'fleetmesh_node.config.compartments.ComputeConfig'>, 'coverage': None, 'dvm': <class 'fleetmesh_node.config.compartments.DVMConfig'>, 'endpoints': None, 'enrolment': None, 'executors': None, 'extensions': None, 'face': <class 'fleetmesh_node.config.records.FaceConfig'>, 'fetch_pricing': <class 'fleetmesh_node.config.compartments.FetchPricingConfig'>, 'gossip': <class 'fleetmesh_node.config.compartments.GossipConfig'>, 'grasp': None, 'handover': None, 'heartbeat': None, 'lan': <class 'fleetmesh_node.config.compartments.LanConfig'>, 'magpie': None, 'mediation': <class 'fleetmesh_node.config.compartments.MediationConfig'>, 'name': None, 'ncontainer': None, 'network': <class 'fleetmesh_node.config.compartments.NetworkConfig'>, 'nsite': <class 'fleetmesh_node.config.compartments.NsiteConfig'>, 'operator': None, 'operator_relays': None, 'p2p': <class 'fleetmesh_node.config.compartments.P2PConfig'>, 'peers': None, 'plugins': <class 'fleetmesh_node.config.compartments.PluginsConfig'>, 'policy': <class 'fleetmesh_node.config.records.PolicyConfig'>, 'pow_bits': None, 'projection': None, 'protocol_suites': <class 'fleetmesh_node.config.protocols.ProtocolSuitesConfig'>, 'protocols': None, 'publish_operator': None, 'relays': None, 'retention': None, 'settlement': <class 'fleetmesh_node.config.compartments.SettlementConfig'>, 'sidecars': <class 'fleetmesh_node.config.compartments.SidecarsConfig'>, 'storage': <class 'fleetmesh_node.config.compartments.StorageConfig'>, 'telemetry': None, 'tick_seconds': None, 'transport': <class 'fleetmesh_node.config.compartments.TransportConfig'>, 'trust': None, 'updates': <class 'fleetmesh_node.config.compartments.UpdatesConfig'>, 'video': None, 'visibility': <class 'fleetmesh_node.config.records.VisibilityConfig'>}
- classmethod defaults_dict()[source]
What a fresh config.json carries: the file shape of NodeConfig(), one entry per WRITTEN_BY_DEFAULT key, each the JSON form of that field’s dataclass default (blocks via to_dict, tuples as lists).
- Return type:
NodeConfigDict
- __init__(cls_='edge', name='meshnode', relays=(), face=FaceConfig(host='127.0.0.1', port=0, future_seconds=900, roster_export_path=None), endpoints=(), protocols=('https://fleetmesh.org/sync/1.0', ), capabilities=('relay', 'negentropy'), brands=(), operator=None, publish_operator=False, operator_relays=(), pow_bits=None, visibility=VisibilityConfig(default='public', overrides={}), policy=PolicyConfig(open_enrolment=True, protocols=(), DERIVED=False), coverage=(), handover='offer', retention=<factory>, trust=<factory>, peers=(), tick_seconds=30, heartbeat=True, projection=True, telemetry=False, fetch_pricing=FetchPricingConfig(default_msat=0, free_for_partners=True, free_bytes_per_day=None, max_account_fee_msat=0, grasp_session_msat=0, sidecar_session_msat={}, rules=(), cashu=CashuRail(mints=(), unit='sat', sweep_above_sat=0, sweep_to=None), DERIVED=False), bridge=None, announce=AnnounceConfig(enabled=False, socket=None, pow_bits=0), lan=LanConfig(enabled=False), p2p=None, gossip=None, capacity=CapacityConfig(total={}), compute=None, dvm=None, nsite=None, settlement=SettlementConfig(nwc_uri=None, live_cashu=False, mint_url=None), mediation=MediationConfig(), transport=TransportConfig(), blob_wire=BlobWireConfig(accept_from='none', chunk_bytes=None, bytes_per_day=None, max_concurrent=None, max_blob_bytes=None, max_total_bytes=None, DERIVED=False), blob_replication=BlobReplicationConfig(copies=2, allow_private=False, source_url=None, servers=(), DERIVED=False), storage=StorageConfig(max_bytes=None, allow_private_mirror=False), blobs=BlobsConfig(max_storage_bytes=None, fanout=1, data_dir=None), sidecars=SidecarsConfig(entries={}, DERIVED=False), plugins=PluginsConfig(specs=()), updates=None, network=None, protocol_suites=ProtocolSuitesConfig(host=HostMultiplexerConfig(listen='127.0.0.1', port=0, public_url=None, bind_wait=10.0), nostr=NostrProtocolConfig(enabled=True, relays=(), require_auth=False, future_seconds=900), atproto=ATProtoProtocolConfig(enabled=False, handle=None, service_did=None, pds_enabled=True, firehose_subscribe=False, firehose_publish=True, relay_upstream=None, metered_peering=True), activitypub=ActivityPubProtocolConfig(enabled=False, domain=None, summary='Fleetmesh Sovereign Edge Node', rate_limit_per_inbox=60, allow_local_federation=False), ssb=SSBProtocolConfig(enabled=False, port=8008, caps='d4a1da283c1e443e022da12bc6139952b324e4001f40fa38ba5754035a49807f'), p2panda=P2PandaProtocolConfig(enabled=False, port=9102, network_id='fleetmesh-default', discovery=True, allow_local_peers=False), rhio=RhioProtocolConfig(enabled=False, nats_endpoint='localhost:4222', s3_endpoint='http://localhost:9000', network_id='rhio-default-network-1', bind_port=9102, http_bind_port=3000)), extensions=<factory>)
- Parameters:
cls_ (str)
name (str)
face (FaceConfig)
operator (str | None)
publish_operator (bool)
pow_bits (int | None)
visibility (VisibilityConfig)
policy (PolicyConfig)
coverage (tuple[CoverageClaim, ...])
handover (str)
trust (dict[str, TrustDecision])
tick_seconds (int)
heartbeat (bool)
projection (bool)
telemetry (bool)
fetch_pricing (FetchPricingConfig)
bridge (BridgeConfig | None)
announce (AnnounceConfig)
lan (LanConfig)
p2p (P2PConfig | None)
gossip (GossipConfig | None)
capacity (CapacityConfig)
compute (ComputeConfig | None)
dvm (DVMConfig | None)
nsite (NsiteConfig | None)
settlement (SettlementConfig)
mediation (MediationConfig)
transport (TransportConfig)
blob_wire (BlobWireConfig)
blob_replication (BlobReplicationConfig)
storage (StorageConfig)
blobs (BlobsConfig)
sidecars (SidecarsConfig)
plugins (PluginsConfig)
updates (UpdatesConfig | None)
network (NetworkConfig | None)
protocol_suites (ProtocolSuitesConfig)
- Return type:
None
- class fleetmesh_node.app.config.Problems[source]
Bases:
objectSentences about what is wrong, in file order.
- fleetmesh_node.app.config.config_from_manifests(meshnode, peerings=())[source]
A config from a MeshNode manifest and any Peering manifests (parsed YAML or JSON).
- fleetmesh_node.app.config.defaults()[source]
A fresh copy, nested values included.
DEFAULTS holds dicts and lists, and dict(DEFAULTS) copies only the top level: two nodes built from it shared one face dict, so the first to record its port set it for every node after. Anything that hands out defaults hands out copies.
- fleetmesh_node.app.config.typed_config(cfg)[source]
The typed view of a config that validate_config passed.
- Parameters:
- Return type:
2.3. Control Socket Server
The control socket: how an operator asks a running node to do something.
A running node owns its directory and its relay face port, so a second process cannot stand one up beside it to act on its behalf. Declarative state - peers, trust, coverage - goes through the config file, which the daemon re-reads every tick. An action - pull now, terminate a peering, ask a peer about a third node, force a tick - needs the daemon itself, and this is the channel: a unix socket in the node directory, one JSON object per line each way, readable and writable by the node’s own user and nobody else.
The protocol is named and versioned: meshnode-control/1. A request is {“cmd”: name, “args”: {…}}; a reply is {“ok”: true, “protocol”: …, “result”: …} or {“ok”: false, “protocol”: …, “error”: reason}. The commands, their arguments and what each answers are served by the socket itself under commands, from the same table the daemon dispatches on, so what it says about itself cannot drift from what it does. A field is only ever added to a reply within a major version; a field removed or renamed is meshnode-control/2.
The socket path is derived from the directory on both sides, so nothing has to be looked up. macOS limits a unix socket path to about a hundred bytes, and a test’s temporary directory is longer than that, so a directory whose path will not fit gets a socket in the temp directory named by the hash of the real path. An operator’s /var/lib/meshnode fits.
- class fleetmesh_node.app.socket.Stream[source]
Bases:
objectA dispatcher returns one of these for a verb that answers more than once. The server sends the ack line, then one line per envelope pull yields until the client closes or pull returns None past idle seconds of silence with the client gone. close runs once at the end. A streaming connection does not count against the request semaphore: a reader that holds on for an hour must not starve health.
- class fleetmesh_node.app.socket.Server[source]
Bases:
objectServes dispatch(cmd, args) -> result over the socket, one request per connection.
- fleetmesh_node.app.socket.stream(directory, cmd, timeout=None, **args)[source]
Ask for a streaming verb and yield each envelope as it arrives. The first value yielded is the ack (the request’s own result); then one per line until the node closes or the caller stops iterating. timeout is how long to wait for the next line, None forever.
- fleetmesh_node.app.socket.call(directory, cmd, timeout=90.0, request=None, **args)[source]
Ask the node running in directory to do one thing. Raises ControlError when there is no node to ask, or when the node says no.
timeout is how long this client waits. A request argument that shares the name (pull’s own timeout) goes in request, which is merged over args; before that, meshnode pull –timeout never reached the daemon.
- fleetmesh_node.app.socket.actor_of(conn, req)[source]
Who made this request, with every rung that answered recorded.
Built here because SO_PEERCRED can only be read off a live connection. The operator and session are whatever the caller sent - a claim, marked as one - and the peercred rung corroborates that a local user made the call without ever claiming to identify a DID.
Imported lazily: fleetmesh_node/control.py is reached by the CLI as well as the daemon, and the config package pulls in the whole typed config tree.
2.4. Control Request Dispatcher
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.
- class fleetmesh_node.app.control.CommandDetail[source]
Bases:
CommandSpec
- class fleetmesh_node.app.control.EnrolResult[source]
Bases:
Outcomeenrol reply: the Outcome plus what went out (plan D18/D19).
- class fleetmesh_node.app.control.PeerViewRow[source]
Bases:
TypedDict- issued: PeerGrantSummary | None
- received: PeerGrantSummary | None
- pending: PeerPendingSummary | None
- last_evaluated: PeerEvaluationSummary | None
- standing: StandingTellBody | None
- class fleetmesh_node.app.control.ControlMixin[source]
Bases:
object- ks: keystore.Keystore
- grants: grants_mod.GrantStore
- accounts: accounts_mod.AccountStore
- peers: peers_mod.Peers
- transport: transport_mod.TransportRouter
- ledger: standing.Ledger
- 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
- groups: Any
- log: collections.deque[Any]
- counts: collections.Counter[str]
- control_request(cmd, args, actor=None)[source]
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.
- operator_did()[source]
The operator DID this node publishes (plan D7): the descriptor’s operator tag, the config’s before the first build; None when unset.
- Return type:
str | None
- permission_of(cmd)[source]
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.
- wire_decide(cmd, sender, authenticated, chain, now=None)[source]
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.
- wire_request(cmd, args, sender, authenticated, chain, now=None, session='')[source]
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.
- cmd_ledger(args)[source]
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.
- check_enrolment(now=None)[source]
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.
- enrol(token, force=False)[source]
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.
- Parameters:
- Return type:
- set_visibility(default=None, overrides=None)[source]
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.
- visibility_state()[source]
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.
- Return type:
VisibilityState
- commands()[source]
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.
- Return type:
- retire(reason='operator', revoke=False, lapses_in=86400)[source]
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.
- Parameters:
- Return type:
- save_coverage()[source]
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.
- Return type:
None
- terminate(peer_pk, reason='operator')[source]
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.
- Parameters:
- Return type:
- regrant(peer_pk, tier, now=None)[source]
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.
- Parameters:
- Return type:
GrantPayload | None
2.5. Systemd Integration
sd_notify: the one line the node says to systemd.
Separate because it touches a socket and nothing else here does; the config module should not need socket.
2.6. Status Views
Views the CLI and the control socket share: a peer’s grants and windows.
Separate because meshnode peer reads them straight from the files when no daemon is running, and must not import the node to do so.
- class fleetmesh_node.app.views.GrantView[source]
Bases:
TypedDict- issued_history: list[HistoryRow]
- received_history: list[HistoryRow]
- pending: PendingRow | None
- fleetmesh_node.app.views.grant_view(grants, pk)[source]
Both grants with a peer, their history, the pending tier and the seed. The same structure whether read from the files or asked of the daemon.
- Parameters:
grants (GrantStore)
pk (str)
- Return type:
- fleetmesh_node.app.views.windows_view(source, pk, last=0)[source]
The windows this node priced for a peer, from an accounts database: measured against claimed in the issuer frame, receipts in and sent.
source is an AccountStore (its _all takes the store lock and closes the cursor before letting go - the daemon path) or a bare read-only sqlite3 connection (the CLI reading the file beside a stopped or running node). Either way every statement is finished and its cursor closed before the next; .fetchone() on its own leaves the statement live to be finalised by whichever thread the collector happens to run in.
- Parameters:
- Return type:
2.7. Internal Router
Declarative protocol message router for DIDComm PIURI dispatch.
Routes inbound envelopes to registered subsystem handlers based on their PIURI (Protocol Identification URI) prefix or exact message type. Standard library only.
- class fleetmesh_node.app.router.ProtocolRouter[source]
Bases:
objectDIDComm protocol router mapping message types to subsystem handlers.
- register(prefix, handler)[source]
Register a handler for a PIURI prefix (e.g. ‘https://fleetmesh.org/sync/1.0’).
- register_catchall(handler)[source]
Register a fallback handler invoked when no prefix matches or handler yields None.
- unregister(prefix_or_type)[source]
Remove a previously registered route.
- Parameters:
prefix_or_type (str)
- Return type:
None
2.8. App Commands
NODE_COMMANDS: what the node answers over the control socket, declared where it is.
The 29 operator-facing commands answered by NodeApp and the control socket: each a Command or an Alias under the node namespace. CONTROL is generated from them, and the socket dispatches on them.