3.1.1. Identity Plane (fleetmesh_node.planes.identity)

The Identity Plane coordinates cryptographic identity, presence heartbeats, peer discovery across transports, and multi-protocol alias linking.

3.1.1.1. Announce Compartment

The gossipsub announce topic, reached through a sidecar, as a compartment.

Bridge 2 in the specification: a node republishes its descriptor on /fleetmesh/announce/1 so that nodes which have never shared a relay with it hear about it anyway. The relay path (bridge 1, discovery_wire.py) always works; this one reaches further.

It is a sidecar and not a library because of what a library would cost. fleetmesh_core/ is standard library only and fleetmesh_node/ depends on cryptography and nothing else - ws.py is a hand-rolled RFC 6455 for exactly that reason. Installing the one maintained Python libp2p pulls in sixty-three packages, eight of them compiled; it does not install on Python 3.14 at all; and it is trio where this node is threads. A second implementer reading the specification should not inherit that, so the libp2p stack lives in its own process with its own dependencies and this file speaks to it over a unix socket in the node’s directory, one JSON object per line, the same shape control.py already uses.

The node never starts the sidecar and never needs it. No socket is not an error, it is a node with one discovery bridge instead of two, and it is said once rather than once a tick.

Nothing here trusts the sidecar. Every row it hands over goes through admit - the same function the sidecar ran before gossipsub propagated anything - and then through peers.learn, exactly as a descriptor fetched from a relay does. The work floor is re-applied here because it is this node’s policy and not the sidecar’s.

The one check admit needs from the sidecar is which libp2p peer originated the message, because a Multikey is compared against it. A sidecar that lies about the originator can only make this node reject a descriptor it would have accepted; it cannot make it accept one, because the Multikey is inside an event the node key signed.

The pilot bridge (fleetmesh_node/sidecar_bridge): the link to the sidecar, saying it once each way, the version gate, the announce.sidecar and announce.probe commands and the restart all come from Bridge, as they will for every other sidecar. What is left here is what is announce’s own - the topic, admit, what a drain may teach this node.

fleetmesh_node.planes.identity.announce.compartment.socket_path(directory, configured=None)[source]

Where the sidecar listens. Same derivation as the control socket, for the same reason: macOS caps a unix socket path near a hundred bytes and a test’s temporary directory is longer than that.

Parameters:
  • directory (str)

  • configured (str | None)

Return type:

str

fleetmesh_node.planes.identity.announce.compartment.transport_multikey(desc)[source]

The key transport Multikey a descriptor declares, or None.

Parameters:

desc (NostrEvent)

Return type:

str | None

fleetmesh_node.planes.identity.announce.compartment.binds(desc, ed25519_hex)[source]

Whether the descriptor names this Ed25519 key as its transport key.

The gossipsub message was signed under StrictSign by the originator, and a forwarder does not re-sign, so this is the originator’s key and the descriptor must be the originator’s own. A descriptor relayed by a third node is still valid on a flood topic - the check is against what the descriptor claims, never against who handed it over.

Parameters:
Return type:

bool

fleetmesh_node.planes.identity.announce.compartment.admit(payload, origin, now, pow_bits=0, payload_max=20000)[source]

Whether the topic should carry this. (descriptor, None) or (None, why).

The whole of the defence on a flood channel with no grant in front of it, and the one place it is written. The sidecar calls this before gossipsub propagates anything, and the node calls it again on what the sidecar hands over, because a separate process is not a reason to believe a descriptor.

Ordered cheapest first: a size that needs no parse, a parse, a kind, a signature, the descriptor rules, the work, and last the binding, which is the only check that needs to know who sent it.

origin is the originator’s Ed25519 key - gossipsub StrictSign’s from, not the peer who handed the message over. A forwarder does not re-sign, and a descriptor relayed by a third node is still valid here.

Parameters:
  • payload (Any)

  • origin (str | None)

  • now (int)

  • pow_bits (int)

  • payload_max (int)

Return type:

tuple[NostrEvent | None, str | None]

fleetmesh_node.planes.identity.announce.compartment.call(path, cmd, timeout=5.0, **args)[source]

One request, one reply, one connection. Raises SidecarError for all of no sidecar, a sidecar that will not answer, and a sidecar that says no.

For a caller outside a node (a script, the sidecar’s own tests). Inside one, the sidecar is reached through the bridge - Announce.call - which also moves the link and checks the protocol the sidecar answered in.

Parameters:
Return type:

Any

class fleetmesh_node.planes.identity.announce.compartment.Announce[source]

Bases: Bridge

name: str = 'announce'
reads: tuple[str, ...] = ('announce',)
config_cls

alias of AnnounceConfig

SIDECAR: Sidecar | None = Sidecar(name='announce', protocol='fleetmesh-announce/1', upstream='py-libp2p gossipsub on /fleetmesh/announce/1', transport='unix', standalone='fleetmesh-announce NODE_DIR [--bootstrap MULTIADDR]', probe='status', supervised=False)
CONSEQUENCE: str = 'this node is discoverable over relays only'
SIDECAR_REACHABLE: str = 'announce.sidecar.reachable'
SIDECAR_UNREACHABLE: str = 'announce.sidecar.unreachable'
SIDECAR_INCOMPATIBLE: str = 'announce.sidecar.incompatible'
DESCRIPTOR_PUBLISHED: str = 'announce.descriptor.published'
PEERS_LEARNED: str = 'announce.peers.learned'
CHANNELS: tuple[Any, ...] = (Channel(name='announce.descriptor.published', description='The node descriptor was republished to the gossipsub announce topic.', level='info', wire=<function Announce.<lambda>>, say='published {id} on {topic}', tags=('announce', 'descriptor')), Channel(name='announce.peers.learned', description='New descriptors heard on the announce topic were verified and learned.', level='info', wire=<function Announce.<lambda>>, say='{learned} new peers learned from {heard} heard on {topic}', tags=('announce', 'peers')), Channel(name='announce.sidecar.reachable', description='The announce sidecar answered, in a protocol this bridge speaks.', level='info', wire=<function bridge_channels.<locals>.<lambda>>, say='sidecar up at {endpoint} ({protocol})', tags=('announce', 'sidecar', 'bridge')), Channel(name='announce.sidecar.unreachable', description='The announce sidecar did not answer, or refused; what needs it waits.', level='note', wire=<function bridge_channels.<locals>.<lambda>>, say='sidecar not reachable at {endpoint} ({why})', tags=('announce', 'sidecar', 'bridge')), Channel(name='announce.sidecar.incompatible', description='The announce sidecar answered in a protocol this bridge does not speak.', level='trouble', wire=<function bridge_channels.<locals>.<lambda>>, say='sidecar speaks {said}; this bridge speaks {wants}', tags=('announce', 'sidecar', 'bridge')))
METRICS: tuple[Any, ...] = (Metric(name='announce_published', description='Times this node published its descriptor on the announce topic.', kind='counter', unit='', labels=(), counts='announce.descriptor.published', sample=None, buckets=(), tags=('announce', 'descriptor')), Metric(name='announce_peers_learned', description='Times new peers were learned from the announce topic.', kind='counter', unit='', labels=(), counts='announce.peers.learned', sample=None, buckets=(), tags=('announce', 'peers')), Metric(name='announce_sidecar_reachable', description='Times the announce sidecar was found reachable.', kind='counter', unit='', labels=(), counts='announce.sidecar.reachable', sample=None, buckets=(), tags=('announce', 'sidecar')), Metric(name='announce_sidecar_unreachable', description='Times the announce sidecar was found unreachable.', kind='counter', unit='', labels=(), counts='announce.sidecar.unreachable', sample=None, buckets=(), tags=('announce', 'sidecar')), Metric(name='announce_sidecar_incompatible', description='Times the announce sidecar answered in a protocol this bridge does not speak.', kind='counter', unit='', labels=(), counts='announce.sidecar.incompatible', sample=None, buckets=(), tags=('announce', 'sidecar')))
COMMANDS: tuple[Any, ...] = (Command(key='show', name='Announce Status', description='the announce topic: whether the sidecar is there, what it has carried, and what this node refused off the topic', tags=('announce', 'sidecar', 'status'), parameters=(), permission='announce/show', process=('sidecar',), run='state', reply='{enabled, socket, connected, topic, peer_id, mesh_peers, published, heard, learned, sidecar}', reads=('totals',), writes=()), Command(key='sidecar', name='Announce sidecar', description='the sidecar this bridge fronts - what it wraps, the protocol it must speak, how to run it standalone - and the link to it as last found', tags=('announce', 'sidecar', 'bridge'), parameters=(), permission='announce/sidecar', process=(), run='bridge_state', reply='{sidecar, endpoint, link, since, protocol, last_error, calls, failures}', reads=(), writes=()), Command(key='probe', name='Probe announce sidecar', description='ask the sidecar now (its `status` request) rather than wait for the next tick', tags=('announce', 'sidecar', 'bridge'), parameters=(), permission='announce/probe', process=('announce',), run='probe', reply='{link, protocol, status | error}', reads=(), writes=()))
STORES: tuple[Store, ...] = (Store(key='totals', description='descriptors carried up the topic, learned, and echoed back', kind='counters', shape=<class 'fleetmesh_node.planes.identity.announce.types.AnnounceTotals'>, bound=0, evict='oldest', keyed_by='', persist='snapshot', sensitive=False, tags=()),)
LIFECYCLE: Lifecycle = Lifecycle(breaker=Breaker(failures=5, window=300, backoff=(30, 600)), restart=True, snapshot=1)
NEEDS: tuple[Any, ...] = (Need(key='peers', source='peers', block=None, late=False, getter=False, path=None, field=None), Need(key='directory', source='dir', block=None, late=False, getter=False, path=None, field=None), Need(key='timeout', source='timeout', block=None, late=False, getter=False, path=None, field=None), Need(key='descriptor', source='descriptor', block=None, late=False, getter=False, path=None, field=None), Need(key='public_descriptor', source='public_descriptor', block=None, late=False, getter=False, path=None, field=None))
__init__(peers, directory, clock=None, timeout=5.0, node=None, descriptor=None, public_descriptor=None)[source]
Parameters:
Return type:

None

property heard: int

Descriptors the sidecar carried up.

property learned: int

Of those, the ones this node did not already hold.

property echoed: int

And the ones that were this node’s own publish returning.

endpoint()[source]
Return type:

str

wanted()[source]
Return type:

bool

forget()[source]

What a reset link must take with it. Nothing, by default.

Return type:

None

property enabled: bool
property path: str
property pow_bits: int
tick(now)[source]

Periodic work. Runs due EVERY jobs when not overridden.

Parameters:

now (int)

Return type:

list[tuple[Any, …]]

abstract: ClassVar[bool] = False
commands: Mapping[str, CommandSpec] = {'probe': {'args': {}, 'does': 'ask the sidecar now (its `status` request) rather than wait for the next tick', 'reply': '{link, protocol, status | error}', 'subsystem': 'announce'}, 'show': {'args': {}, 'does': 'the announce topic: whether the sidecar is there, what it has carried, and what this node refused off the topic', 'reply': '{enabled, socket, connected, topic, peer_id, mesh_peers, published, heard, learned, sidecar}', 'subsystem': 'announce'}, 'sidecar': {'args': {}, 'does': 'the sidecar this bridge fronts - what it wraps, the protocol it must speak, how to run it standalone - and the link to it as last found', 'reply': '{sidecar, endpoint, link, since, protocol, last_error, calls, failures}', 'subsystem': 'announce'}}
live: tuple[str, ...] = ('announce',)
state()[source]

What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.

Return type:

AnnounceStateReport

trouble()[source]

What an operator should be told without having to ask for it.

Everything here is WRONG: a watcher reds on it and a deploy fails on it. Something worth reading that is not a fault goes in notes(). May return a list of strings or typed Trouble instances.

Return type:

list[str]

3.1.1.2. Discovery Compartment

What this node tells the mesh it is and what it holds, as a compartment.

Two publications with one shape: a kind 30166 per endpoint for NIP-66 readers, and a kind 30803 per shard for anything looking for data rather than for nodes. Both are addressable, both are republished only when what they say changes, and both can be refused - a discovery event that contradicts the descriptor, a coverage claim a leaf may not make.

Those refusals went into the tick’s return value and nowhere else. coverage claim refused was printed once and then gone: an operator who had added a shard to the config and never saw it claimed had the reason in a journal line that had already scrolled, and nothing to ask.

The forward clock lives here because both of these are addressable events under a stable d, and so is the report the reporter publishes, which borrows it.

class fleetmesh_node.planes.identity.discovery.compartment.DiscoveryConfig[source]

Bases: ParamBlock

DiscoveryConfig(DERIVED: ‘bool’ = False, coverage_interval: ‘int’ = 60, discovery_interval: ‘int’ = 300)

key: ClassVar[str] = 'discovery'
name = 'discovery'
DERIVED: bool = False
PARAMS: tuple[Parameter[Any], ...] = (Parameter(key='coverage_interval', name='Coverage Publication Interval', description='Seconds between coverage claim publications', type=<class 'int'>, default=60, must='', tags=('discovery', 'coverage'), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=10, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='discovery_interval', name='Discovery Publication Interval', description='Seconds between discovery endpoint publications', type=<class 'int'>, default=300, must='', tags=('discovery', 'announcement'), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=30, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True))
coverage_interval: int = 60
discovery_interval: int = 300
__init__(DERIVED=False, coverage_interval=60, discovery_interval=300)
Parameters:
  • DERIVED (bool)

  • coverage_interval (int)

  • discovery_interval (int)

Return type:

None

class fleetmesh_node.planes.identity.discovery.compartment.Discovery[source]

Bases: Compartment

requires: tuple[str, ...] = ('capacity',)
name: str = 'discovery'
reads: tuple[str, ...] = ('coverage', 'class')
config_cls

alias of DiscoveryConfig

live: tuple[str, ...] = ('coverage',)
CHANNELS: tuple[Any, ...] = (Channel(name='coverage_narrowed', description='Coverage claim narrowed under capacity pressure', level='note', wire=None, say='shard {shard} is no longer claimed while this node sheds: it is held through the mesh and the node is at its ceiling', tags=()), Channel(name='coverage_downgraded', description='Coverage completeness downgraded to best-effort', level='note', wire=None, say='shard {shard} is claimed best-effort, not asserted: some of it arrived through the mesh and this node cannot stand behind it', tags=()), Channel(name='handover_dropped', description='Handover chain dropped for shard', level='trouble', wire=None, say='shard {shard} handover from {from_peer} dropped: {why}', tags=()))
METRICS: tuple[Any, ...] = (Metric(name='discovery_coverage_narrowed', description='Times coverage claims were narrowed.', kind='counter', unit='', labels=(), counts='coverage_narrowed', sample=None, buckets=(), tags=('discovery', 'coverage')), Metric(name='discovery_coverage_downgraded', description='Times coverage claims were downgraded.', kind='counter', unit='', labels=(), counts='coverage_downgraded', sample=None, buckets=(), tags=('discovery', 'coverage')), Metric(name='discovery_handover_dropped', description='Times handover chains were dropped.', kind='counter', unit='', labels=(), counts='handover_dropped', sample=None, buckets=(), tags=('discovery', 'handover')))
EVERY: tuple[Any, ...] = (Every(seconds=60, run='publish_coverage', name='coverage', report=None), Every(seconds=300, run='publish_discovery', name='discovery', report=None))
NEEDS: tuple[Any, ...] = (Need(key='keystore', source='ks', block=None, late=False, getter=False, path=None, field=None), Need(key='store', source='stores.events', block=None, late=False, getter=False, path=None, field=None), Need(key='face', source='face', block=None, late=False, getter=False, path=None, field=None), Need(key='relays', source='relays', block=None, late=False, getter=False, path=None, field=None), Need(key='capacity', source='capacity', block=None, late=False, getter=False, path=None, field=None), Need(key='timeout', source='timeout', block=None, late=False, getter=False, path=None, field=None), Need(key='persist_cfg', source='persist_cfg', block=None, late=False, getter=False, path=None, field=None), Need(key='descriptor', source='descriptor', block=None, late=False, getter=False, path=None, field=None), Need(key='public_descriptor', source='public_descriptor', block=None, late=False, getter=False, path=None, field=None), Need(key='accounts', source='stores.accounts', block=None, late=False, getter=False, path=None, field=None), Need(key='cfg', source='cfg', block=None, late=False, getter=False, path=None, field=None))
STORES: tuple[Store, ...] = (Store(key='_discovery', description='d -> what was last put on the relays', kind='table', shape=None, bound=1024, evict='lru', keyed_by='d', persist='memory', sensitive=False, tags=()), Store(key='_coverage', description='shard -> (fingerprint, completeness, range) last published', kind='table', shape=None, bound=1024, evict='lru', keyed_by='shard', persist='memory', sensitive=False, tags=()), Store(key='_claims', description='shard -> the signed kind 30803 last published', kind='table', shape=None, bound=1024, evict='lru', keyed_by='shard', persist='memory', sensitive=False, tags=()), Store(key='_handed', description='shard -> pubkey of the peer whose handover the claim rests on', kind='table', shape=None, bound=1024, evict='lru', keyed_by='shard', persist='memory', sensitive=False, tags=()), Store(key='_narrowed', description='shard -> whether it is currently held back under pressure', kind='table', shape=None, bound=1024, evict='lru', keyed_by='shard', persist='memory', sensitive=False, tags=()), Store(key='_downgraded', description='shard -> the size at which it was last said to be best-effort', kind='table', shape=None, bound=1024, evict='lru', keyed_by='shard', persist='memory', sensitive=False, tags=()), Store(key='_forward', description='addressable coordinate -> last created_at stamped', kind='table', shape=None, bound=1024, evict='lru', keyed_by='coordinate', persist='memory', sensitive=False, tags=()))
COMMANDS: tuple[Any, ...] = (Command(key='show', name='Discovery', description='what this node has published about itself and about the shards it holds', tags=('discovery', 'status'), parameters=(), permission='discovery/show', process=(), run='state', reply='{discovery, coverage, handed, narrowed, downgraded}', reads=(), writes=()),)
__init__(keystore, store, face, relays, capacity=None, clock=None, timeout=15.0, node=None, persist_cfg=None, descriptor=None, public_descriptor=None, accounts=None, cfg=None, publisher=None)[source]
Parameters:
Return type:

None

publisher: Callable[[Sequence[str], Any, float], Any]
descriptor: Callable[[], NostrEvent | None]
public_descriptor: Callable[[], NostrEvent | None]
accounts: Any | None
ks: Any
store: Any
face: Any
relays: list[str]
capacity: Any | None
persist_cfg: Callable[[], None]
timeout: float
tick(now)[source]

Periodic work. Runs due EVERY jobs when not overridden.

Parameters:

now (int)

Return type:

list[tuple[Any, …]]

forward_clock(key, now)[source]

A timestamp strictly later than the last one used for this key.

Every addressable event a node republishes under a stable d - the grant envelope, the coverage claim, the report - replaces the last one at that coordinate, and NIP-01 breaks a created_at tie on the lower id. Two written in the same second therefore leave the relay holding whichever id happens to sort first, which is the older one about half the time. Supersession only runs forwards, so the clock this node stamps them with only runs forwards too.

Parameters:
Return type:

int

publish_discovery(now=None)[source]

The node’s face described for NIP-66 readers: one kind 30166 per ws or wss endpoint the descriptor declares. Bridge 1 in the specification. It says what the face is and accepts and measures nothing, so it changes only when the descriptor, the NIP-11 document or the claimed shards do, and is republished only then.

Parameters:

now (int | None)

Return type:

list[tuple[Any, …]]

publish_coverage(now=None)[source]

Tell the mesh which shards this node holds, as kind 30803.

Nothing published one of these before, so no peer could discover what any node held: the whole of data discovery, as distinct from node discovery, was missing.

asserted is a falsifiable claim - a peer may sample the shard, find a hole, and file an S3 with the missing event id as evidence - and the specification forbids asserting completeness over a shard held only through mesh replication, because that is how third-party replication launders unverified peer data into an authoritative record. So the operator’s asserted is a request and not a decision: it is honoured only when every event in the shard arrived here directly, and downgraded to best-effort otherwise, with the reason logged. A leaf publishes neither, having nothing to claim.

The one door through that is a handover: the first-hand holder’s signed statement over the set, received on the sync thread that pulled it and kept in the account store. With one held for the shard, and only while what this node holds over the handed range still fingerprints to what was handed, the claim goes out asserted over exactly that range with the handover inline. The moment the set moves - a late event in a closed range, a retention pass - the handover is stale, and a claim that carried it would be a false one, so it is dropped and the claim falls back to what this node can stand behind on its own.

Parameters:

now (int | None)

Return type:

list[tuple[Any, …]]

close_ranges(now=None)[source]

Give every asserted shard a bounded range that ends now, and publish.

A handover signs for a closed set, so a shard whose until is open or in the future cannot be handed to anybody. That is the right rule while a node is running and the wrong state to retire in: the shards worth passing on are exactly the ones nobody has ever bounded. Closing them is the first step of a retirement and the only one that changes what this node says about itself while it is still serving.

Written to the config, because the claim is republished from the config on the next tick and a range closed only in memory would reopen.

Parameters:

now (int | None)

Return type:

list[tuple[Any, …]]

withdraw_coverage(now=None, lapses_in=86400)[source]

Take back every claim this node published, so none outlives it.

A kind 30803 that outlives its node is the black hole: readers see a holder, pull, and time out, and every one of them records strain against a node that is simply gone. The claim is addressable, so a republication at the same d replaces it; the replacement says best-effort, which promises nothing, and carries an expiration so it lapses too.

Last of the retirement, after the handovers: a withdrawal before them would take back the very claim a handover copies its terms from.

Parameters:
  • now (int | None)

  • lapses_in (int)

Return type:

list[tuple[Any, …]]

asserted_claims()[source]

Every published claim this node may hand over: asserted, with a range that has closed. What close_ranges has just made of them.

Return type:

list[NostrEvent]

published_claim(shard)[source]

The signed kind 30803 this node last published for a shard, or None. What a handover copies its terms from: a node hands over what it has said in public and nothing else.

Parameters:

shard (str)

Return type:

NostrEvent | None

state()[source]

What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.

Return type:

DiscoveryStateReport

trouble()[source]

What an operator should be told without having to ask for it.

Everything here is WRONG: a watcher reds on it and a deploy fails on it. Something worth reading that is not a fault goes in notes(). May return a list of strings or typed Trouble instances.

Return type:

list[str]

abstract: ClassVar[bool] = False
commands: Mapping[str, CommandSpec] = {'show': {'args': {}, 'does': 'what this node has published about itself and about the shards it holds', 'reply': '{discovery, coverage, handed, narrowed, downgraded}', 'subsystem': 'discovery'}}

3.1.1.3. Linked Identities Compartment

The schema.org face of a node: what it publishes for strangers, projected as JSON-LD and served read-only over the relay face’s HTTP fallthrough.

Three documents, each a projection of a signed event (fleetmesh_core .linked_data) and never a second source of truth:

GET /.well-known/fleetmesh/service.jsonld the node’s kind 11801 as a

schema:Service, floor from its kind 10050

GET /.well-known/fleetmesh/blob/<sha256>.jsonld

one stored blob as a schema:MediaObject

GET /.well-known/fleetmesh/standing.jsonld the node’s own tier, as this

node’s accounts have it - an Organization with one PropertyValue, not a Review

Nothing here is signed and nothing here goes on a relay: the signed thing is the event, this is a reading of it. A consumer that wants proof fetches the event. That is why JSON-LD does not ride inside events (see CONTRIBUTING, “linked data”).

Every answer carries Cache-Control: no-store and the id of the event it was read from in X-Fleetmesh-Source, so a reader can go and check. No POST, no query strings, unknown paths fall through to the rest of the face.

class fleetmesh_node.planes.identity.linked.compartment.LinkedConfig[source]

Bases: ParamBlock

LinkedConfig(DERIVED: ‘bool’ = False, enabled: ‘bool’ = True)

key: ClassVar[str] = 'linked'
name = 'linked'
DERIVED: bool = False
PARAMS: tuple[Parameter[Any], ...] = (Parameter(key='enabled', name='Linked Data Enabled', description='Whether JSON-LD schema.org projections are served', type=<class 'bool'>, default=True, must='', tags=('linked', 'schema'), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True),)
enabled: bool = True
__init__(DERIVED=False, enabled=True)
Parameters:
Return type:

None

class fleetmesh_node.planes.identity.linked.compartment.LinkedFace[source]

Bases: Compartment

Mounted on the relay face’s HTTP fallthrough, before nsite.

name: str = 'linked'
optional: bool = False
requires: tuple[str, ...] = ('presence',)
uses: tuple[str, ...] = ()
reads: tuple[str, ...] = ()
live: tuple[str, ...] = ()
config_cls

alias of LinkedConfig

CHANNELS: tuple[Any, ...] = (Channel(name='doc_served', description='JSON-LD document served', level='info', wire=None, say='served JSON-LD {path}', tags=('linked', 'schema')),)
METRICS: tuple[Any, ...] = (Metric(name='linked_docs_served', description='Times JSON-LD projections were served.', kind='counter', unit='', labels=(), counts='doc_served', sample=None, buckets=(), tags=('linked', 'schema')),)
NEEDS: tuple[Any, ...] = (Need(key='face', source='face', block=None, late=False, getter=False, path=None, field=None), Need(key='blobs', source='stores.blobs', block=None, late=False, getter=False, path=None, field=None), Need(key='descriptor', source='descriptor', block=None, late=False, getter=False, path=None, field=None), Need(key='presence', source='presence', block=None, late=False, getter=False, path=None, field=None), Need(key='ledger', source='ledger', block=None, late=False, getter=False, path=None, field=None), Need(key='ks', source='ks', block=None, late=False, getter=False, path=None, field=None))
COMMANDS: tuple[Any, ...] = (Command(key='show', name='Linked Data Status', description='the projections this node serves and how often each was read', tags=('linked', 'status'), parameters=(), permission='linked/show', process=(), run='state', reply='paths and counts', reads=(), writes=()), Command(key='service', name='Service Document', description="this node's descriptor as a schema:Service (JSON-LD)", tags=('linked', 'service'), parameters=(), permission='linked/service', process=(), run='service_cmd', reply='the document, or refused when no descriptor yet', reads=(), writes=()), Command(key='standing', name='Standing Document', description="this node's own tier as a schema:Organization (JSON-LD)", tags=('linked', 'standing'), parameters=(), permission='linked/standing', process=(), run='standing_cmd', reply='the document, or refused when the ledger has nothing to say', reads=(), writes=()), Command(key='blob', name='Blob Document', description='one stored blob as a schema:MediaObject (JSON-LD)', tags=('linked', 'blob'), parameters=(Parameter(key='sha256', name='sha256', description='sha256 hex digest of blob', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True),), permission='linked/blob', process=(), run='blob_cmd', reply='the document, or refused when the blob is not here', reads=(), writes=()))
STORES: tuple[Store, ...] = (Store(key='served', description='linked data requests served by category', kind='counters', shape=<class 'fleetmesh_node.planes.identity.linked.types.LinkedTotals'>, bound=0, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()),)
__init__(node=None, face=None, blobs=None, descriptor=None, inbox=None, standing=None, clock=None, blossom_url=None, presence=None, ledger=None, ks=None)[source]
Parameters:
Return type:

None

served: Counters
start()[source]

Everything that needs the rest of the node to exist already.

Return type:

None

tick(now)[source]

Periodic work. Runs due EVERY jobs when not overridden.

Parameters:

now (int)

Return type:

list[tuple[Any, …]]

state()[source]

What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.

Return type:

LinkedState

service_cmd()[source]
Return type:

Mapping[str, Any]

standing_cmd()[source]
Return type:

Mapping[str, Any]

abstract: ClassVar[bool] = False
blob_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

commands: Mapping[str, CommandSpec] = {'blob': {'args': {'sha256': 'required'}, 'does': 'one stored blob as a schema:MediaObject (JSON-LD)', 'reply': 'the document, or refused when the blob is not here', 'subsystem': 'linked'}, 'service': {'args': {}, 'does': "this node's descriptor as a schema:Service (JSON-LD)", 'reply': 'the document, or refused when no descriptor yet', 'subsystem': 'linked'}, 'show': {'args': {}, 'does': 'the projections this node serves and how often each was read', 'reply': 'paths and counts', 'subsystem': 'linked'}, 'standing': {'args': {}, 'does': "this node's own tier as a schema:Organization (JSON-LD)", 'reply': 'the document, or refused when the ledger has nothing to say', 'subsystem': 'linked'}}
static paths()[source]
Return type:

list[str]

service()[source]
Return type:

tuple[MutableMapping[str, Any], str] | None

blob(sha)[source]
Parameters:

sha (str)

Return type:

tuple[MutableMapping[str, Any], str] | None

standing()[source]
Return type:

tuple[MutableMapping[str, Any], str] | None

handle_request(conn, req)[source]
Parameters:
Return type:

bool

3.1.1.4. Presence Heartbeat Compartment

What this node says it is alive, and what it makes of a peer saying so.

Three things that are one thing: the descriptor this node publishes, the heartbeat that says the descriptor is still true, and the subscription that reads a peer’s. All three ran loose in the node’s tick, and the pair of them that can find a fault - a heartbeat whose class contradicts the peer’s live descriptor, one whose endpoint digest says the descriptor has gone stale - fed a finding into the budget and recorded nothing an operator could read back.

class fleetmesh_node.planes.identity.presence.compartment.PresenceConfig[source]

Bases: ParamBlock

PresenceConfig(DERIVED: ‘bool’ = False, heartbeat: ‘bool’ = True, telemetry_window: ‘int’ = 3600)

key: ClassVar[str] = 'presence'
name = 'presence'
DERIVED: bool = False
PARAMS: tuple[Parameter[Any], ...] = (Parameter(key='heartbeat', name='Heartbeat Enabled', description='Whether to publish periodic heartbeat events', type=<class 'bool'>, default=True, must='', tags=('presence', 'heartbeat'), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='telemetry_window', name='Telemetry Window', description='Window size in seconds for telemetry aggregation', type=<class 'int'>, default=3600, must='', tags=('presence', 'telemetry'), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=60, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True))
heartbeat: bool = True
telemetry_window: int = 3600
__init__(DERIVED=False, heartbeat=True, telemetry_window=3600)
Parameters:
  • DERIVED (bool)

  • heartbeat (bool)

  • telemetry_window (int)

Return type:

None

class fleetmesh_node.planes.identity.presence.compartment.Presence[source]

Bases: Compartment

requires: tuple[str, ...] = ('budget', 'strain')
name: str = 'presence'
reads: tuple[str, ...] = ('heartbeat', 'class', 'telemetry')
config_cls

alias of PresenceConfig

NEEDS: tuple[Any, ...] = (Need(key='keystore', source='ks', block=None, late=False, getter=False, path=None, field=None), Need(key='peers', source='peers', block=None, late=False, getter=False, path=None, field=None), Need(key='grant_store', source='stores.grants', block=None, late=False, getter=False, path=None, field=None), Need(key='relays', source='relays', block=None, late=False, getter=False, path=None, field=None), Need(key='budget', source='budget', block=None, late=False, getter=False, path=None, field=None), Need(key='stop', source='stop', block=None, late=False, getter=False, path=None, field=None), Need(key='timeout', source='timeout', block=None, late=False, getter=False, path=None, field=None), Need(key='strain', source='strain', block=None, late=False, getter=False, path=None, field=None), Need(key='descriptor', source='descriptor', block=None, late=False, getter=False, path=None, field=None), Need(key='public_descriptor', source='public_descriptor', block=None, late=False, getter=False, path=None, field=None), Need(key='rebuild_descriptor', source='build_descriptor', block=None, late=False, getter=False, path=None, field=None), Need(key='transport', source='transport', block=None, late=False, getter=False, path=None, field=None))
TELEMETRY_WINDOW: int = 3600
CHANNELS: tuple[Any, ...] = (Channel(name='peer_retiring', description='Peer indicated graceful retirement', level='note', wire=None, say='peer {peer} says it is retiring; the partition that follows is not stress from that direction', tags=()), Channel(name='inbound_event', description='Inbound heartbeat event processed', level='info', wire=None, say='< {event}', tags=()))
METRICS: tuple[Any, ...] = (Metric(name='presence_peers_retiring', description='Times peers reported retirement.', kind='counter', unit='', labels=(), counts='peer_retiring', sample=None, buckets=(), tags=('presence', 'peers')), Metric(name='presence_events_inbound', description='Times heartbeat events were processed.', kind='counter', unit='', labels=(), counts='inbound_event', sample=None, buckets=(), tags=('presence', 'heartbeat')))
EVERY: tuple[Any, ...] = (Every(seconds=3600, run='_run_telemetry', name='_run_telemetry', report=None),)
WORKERS: tuple[Any, ...] = (Worker(run='_listen', name='presence-listen', timeout=1.0, daemon=True, when=None),)
STORES: tuple[Store, ...] = (Store(key='_seen', description='peer -> the id of the last heartbeat read from it', kind='table', shape=None, bound=1024, evict='lru', keyed_by='peer', persist='memory', sensitive=False, tags=()), Store(key='_retiring', description='peers that said they were going, and when', kind='table', shape=None, bound=1024, evict='lru', keyed_by='peer', persist='memory', sensitive=False, tags=()))
COMMANDS: tuple[Any, ...] = (Command(key='show', name='Presence', description='the descriptor this node publishes, when it expires, and the peers it has heard from', tags=('presence', 'status'), parameters=(), permission='presence/show', process=(), run='state', reply='{descriptor, expires, renews_at, last_heartbeat, inbox_relays, heard_from, retiring}', reads=(), writes=()),)
__init__(keystore, peers, grant_store, relays, budget=None, stop=None, clock=None, timeout=15.0, node=None, strain=None, descriptor=None, public_descriptor=None, rebuild_descriptor=None, transport=None, publisher=None)[source]
Parameters:
Return type:

None

publisher: Callable[[Sequence[str], Any], Any]
transport: Any | None
descriptor: Callable[[], NostrEvent | None]
public_descriptor: Callable[[], NostrEvent | None]
rebuild_descriptor: Callable[[], NostrEvent]
ks: Any
peers: Any
grants: Any
relays: list[str]
budget: Any | None
strain: Any | None
timeout: float
last_inbox: NostrEvent | None
publish_inbox(now)[source]

The kind 10050 that states this node’s relay floor: the relays it reads are where a stored wrap for it goes (NIP-17). Every node publishes one - the relay rung is the one way a node can always be reached, and this is where that is said, in the place any Nostr client already looks. Published on the first tick and again only when the set changes; None when nothing was due.

Plan D2: a fully private node says it on its network relays instead of the public relays - relay_destination() is the node’s answer to which - so its members still know where to reach it while the public relays learn nothing. A fully private node with no network has nowhere to say it and publishes none.

Parameters:

now (int)

Return type:

NostrEvent | None

tick(now)[source]

Periodic work. Runs due EVERY jobs when not overridden.

Parameters:

now (int)

Return type:

list[tuple[Any, …]]

heartbeat_now(now)[source]

Sign and publish one heartbeat now, off the current descriptor’s endpoints, and count it as the last. tick calls it when one is due; enrol calls it so the fleet sees the node under its operator at once rather than at the next due beat.

Plan D2: a heartbeat is this node’s liveness, so a fully private node still makes one - but to its network relays (relay_destination), where the members that share a private network with it listen, never to the public ones. With no public copy the endpoints come from the full descriptor, which is what a member resolves. A fully private node with no network has nowhere to say it and publishes none, which enrol reads as “nothing was published”. A public (or narrowed) node publishes to its configured relays exactly as before.

Parameters:

now (int)

Return type:

tuple[Any, …]

announce_retiring(now=None)[source]

Say this node is going, before it starts giving things away.

Published directly rather than through the tick’s due check: a retirement does not wait for the hour to come round, and the whole value of the flag is that it arrives before the silence it explains. A leaf publishes no heartbeat and so cannot announce one, which is correct - a leaf claims nothing and hands nothing over.

Ephemeral, like every heartbeat: only a peer listening now hears it. That is the right answer and it is why it is advisory. A peer that was itself down records the partition, and the partition is true.

Parameters:

now (int | None)

Return type:

list[tuple[Any, …]]

is_retiring(peer_pk)[source]

Did this peer tell us it was going? Read by anything that would otherwise price the silence that follows.

Parameters:

peer_pk (str)

Return type:

bool

on_heartbeat(hb)[source]

One kind 21801 from a peer, checked against what that peer published.

A node published one of these every hour and nothing ever read one, so two rules the reference already implements were dead. A heartbeat whose class contradicts the peer’s live descriptor is a misreport about itself and an S2. One whose endpoint digest differs from the descriptor’s says the descriptor has gone stale, which is the whole reason that digest is in there: a peer can tell without dialling every address it was given.

A heartbeat is ephemeral, so no relay stores one and none can be asked for after the fact. Liveness is a statement about now, and the only way to hear it is to be listening when it is made - which is why this is fed by a subscription and not by a query. A node that was down misses them, and that is the right answer.

Parameters:

hb (Any)

Return type:

list[tuple[Any, …]]

state()[source]

What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.

Return type:

PresenceStateReport

trouble()[source]

What an operator should be told without having to ask for it.

Everything here is WRONG: a watcher reds on it and a deploy fails on it. Something worth reading that is not a fault goes in notes(). May return a list of strings or typed Trouble instances.

Return type:

list[str]

abstract: ClassVar[bool] = False
commands: Mapping[str, CommandSpec] = {'show': {'args': {}, 'does': 'the descriptor this node publishes, when it expires, and the peers it has heard from', 'reply': '{descriptor, expires, renews_at, last_heartbeat, inbox_relays, heard_from, retiring}', 'subsystem': 'presence'}}
live: tuple[str, ...] = ()