3.1.6. Transport Plane (fleetmesh_node.planes.transport)
The Transport Plane houses the compartments that monitor connection liveness, discover peers on local networks, establish P2P circuits, bridge sidecars, and mediate multi-hop routes.
3.1.6.1. Link Watchdog Compartment
The relay links this node holds open, as a compartment.
The transport keeps the sockets and counts what it drops. Nothing watched it: the tick read transport.health directly to decide what to say to the journal, and health() read six more of its counters by name. A subscription that dropped was therefore visible in two hand-written places and in no refusal channel at all, so meshnode refusals - the one view that answers “what has this node been saying no to” - could not show a relay that had been refusing this node for an hour.
This compartment owns what the journal has already been told, so it says a transition once and not once a tick, and it records the drop as a refusal like every other no.
It also records the transport’s verdicts on stored messages. A kind 1059 the relay accepted and never served used to be indistinguishable from one that arrived; now every stored message asks for an acknowledgment, and a peer that has spoken since and not acknowledged is a stored: unacknowledged refusal here, with the message type and the relays it went through, so meshnode refusals can show the day the control plane went quiet.
- class fleetmesh_node.planes.transport.link.compartment.Link[source]
Bases:
Compartment- config_cls
alias of
TransportConfig
- NEEDS: tuple[Any, ...] = (Need(key='transport', source='transport', block=None, late=False, getter=False, path=None, field=None), Need(key='strain', source='strain', block=None, late=True, getter=False, path=None, field=None))
- COMMANDS: tuple[Any, ...] = (Command(key='show', name='Link', description='every relay subscription, what it has dropped, what is waiting to be read, and the stored messages still waiting to be acknowledged', tags=('link', 'status'), parameters=(), permission='link/show', process=(), run='state', reply='{relays, dropped, recent_faults, publish_refused_in_window, cooling, inbox, wraps_in, wraps_seen_again, unfinished_envelopes, awaiting_ack, acked, acks_in, acks_out, unacknowledged}', reads=(), writes=()),)
- STORES: tuple[Store, ...] = (Store(key='_up', description='last reported connection state per relay url', kind='table', shape=<class 'bool'>, bound=1024, evict='lru', keyed_by='url', persist='memory', sensitive=False, tags=()), Store(key='_said', description='last reported unreachable reason per relay url', kind='table', shape=None, bound=1024, evict='lru', keyed_by='url', persist='memory', sensitive=False, tags=()), Store(key='_ack', description='last reported subscription-acknowledged state per relay url', kind='table', shape=<class 'bool'>, bound=1024, evict='lru', keyed_by='url', persist='memory', sensitive=False, tags=()))
- CHANNELS: tuple[Any, ...] = (Channel(name='relay_up', description='Relay subscription connected', level='info', wire=None, say='relay {url} subscription up', tags=()), Channel(name='relay_down', description='Relay subscription disconnected', level='trouble', wire=None, say='relay {url} subscription down ({reason}), reconnecting', tags=()), Channel(name='relay_unreachable', description='Relay not reachable', level='trouble', wire=None, say='relay {url} not reachable ({reason}), retrying', tags=()), Channel(name='unacknowledged', description='Stored message was never acknowledged', level='note', wire=None, say='stored {peer} {type} never acknowledged; the peer has spoken since via {relays}', tags=()), Channel(name='relay_deaf', description='Relay holds the socket but never acknowledged the subscription', level='trouble', wire=None, say='relay {url} took the subscription and never acknowledged it ({reason})', tags=()), Channel(name='relay_acked', description='Relay acknowledged the subscription', level='info', wire=None, say='relay {url} acknowledged the subscription', tags=()))
- METRICS: tuple[Any, ...] = (Metric(name='link_relays_connected', description='Times a relay connection came up.', kind='counter', unit='', labels=(), counts='relay_up', sample=None, buckets=(), tags=('link', 'relay')), Metric(name='link_relays_dropped', description='Times a relay connection dropped.', kind='counter', unit='', labels=(), counts='relay_down', sample=None, buckets=(), tags=('link', 'relay')), Metric(name='link_relays_unreachable', description='Times a relay was unreachable.', kind='counter', unit='', labels=(), counts='relay_unreachable', sample=None, buckets=(), tags=('link', 'relay')), Metric(name='link_unacknowledged', description='Times a stored message was unacknowledged.', kind='counter', unit='', labels=(), counts='unacknowledged', sample=None, buckets=(), tags=('link', 'transport')))
- bind(strain)[source]
The ledger a reconnect is recorded into. Bound after both exist because strain ticks after link and the assembler builds in tick order.
- Parameters:
strain (Any)
- Return type:
None
- tick(now)[source]
Say what changed, once each way it changed.
A relay that is down stays down, and saying so every thirty seconds buries everything else in the journal. A transition is news; a state is not.
- publish_refused(now=None)[source]
Wraps a relay refused within TROUBLE_WINDOW: the fault the OK reports and nothing else shows, because a refused wrap is counted as sent by the caller that published it.
- state()[source]
What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.
- Return type:
LinkState
- notes()[source]
What an operator would want to read, that is not a fault.
A relay cooling after a rate-limit, a peer that announced it is leaving: the node behaving, and the reason a quiet mesh is quiet. Kept apart from trouble() so no reader has to classify prose. May return a list of strings or typed Note instances.
- 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.
- commands: Mapping[str, CommandSpec] = {'show': {'args': {}, 'does': 'every relay subscription, what it has dropped, what is waiting to be read, and the stored messages still waiting to be acknowledged', 'reply': '{relays, dropped, recent_faults, publish_refused_in_window, cooling, inbox, wraps_in, wraps_seen_again, unfinished_envelopes, awaiting_ack, acked, acks_in, acks_out, unacknowledged}', 'subsystem': 'link'}}
3.1.6.2. LAN Discovery Compartment
Finding a node on the same link, with no relay and nothing configured.
Bridge 5, and the only one that needs nothing outside the room. The specification’s four bootstrap paths all start somewhere else: a relay holds the descriptor, gossipsub needs a peer to reach the topic, and an operator typing an address has to know one. fleetmesh_core/tests/test_unplug.py passes with every relay gone, but only because the peers were already in the config - two nodes that had never met could not have found each other, which is the part of the unplug claim nothing was demonstrating.
A node advertises _fleetmesh._tcp.local. over multicast DNS, carrying its pubkey, the protocol digest it speaks, and the port of its own relay face. It browses for the same, and for each answer it does the thing that makes the hint worth having: it asks that face for the advertiser’s kind 11801.
That is the whole trick. Every node already serves a relay face, a descriptor is an ordinary event on it, and descriptor.resolve takes any relay URL. So the peer’s own face is the relay, the descriptor it serves is signed by the key the advert claimed, and peers.learn refuses it if the two disagree. A stranger on the link may advertise any pubkey it likes and gets nowhere: it cannot produce a descriptor signed by a key it does not hold.
The digest does not filter. Since 0.3 two nodes built from different schemas peer on the protocols they share (fleetmesh_core/identity.shared_protocols), so an advert with a different digest is a candidate like any other. The advert still carries the digest: it is provenance, kept per node in meshnode lan so an operator can see a link drifting onto several schemas without dialling anyone.
Discovery ends at a validated descriptor. Peering is the scheduler’s business and an operator’s decision, as it is for every other bridge.
- fleetmesh_node.planes.transport.lan.compartment.instance_name(pubkey)[source]
The DNS-SD instance: this node’s key, short, under the service type.
Sixteen hex is enough to be unique on a link and short enough to read in dns-sd -B. The full key travels in the TXT, which is what is acted on.
- class fleetmesh_node.planes.transport.lan.compartment.Lan[source]
Bases:
Compartment- 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='face', source='face', block=None, late=False, getter=False, path=None, field=None), Need(key='node_class', source='node_class', 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))
- COMMANDS: tuple[Any, ...] = (Command(key='show', name='Lan', description='what this node advertises on its link and what it has heard there', tags=('lan', 'status'), parameters=(), permission='lan/show', process=(), run='state', reply='{enabled, service, advertising, address, port, seen, learned, refused}', reads=(), writes=()),)
- STORES: tuple[Store, ...] = (Store(key='_seen', description='LAN peers seen via broadcast beacon', kind='table', shape=<class 'dict'>, bound=1024, evict='lru', keyed_by='peer', persist='memory', sensitive=False, tags=()), Store(key='_resolved', description='when peer descriptor was last fetched over LAN', kind='table', shape=<class 'int'>, bound=1024, evict='lru', keyed_by='peer', persist='memory', sensitive=False, tags=()))
- CHANNELS: tuple[Any, ...] = (Channel(name='socket_error', description='Cannot join mDNS multicast group', level='trouble', wire=None, say='cannot join the mDNS group ({error}); the other bridges are unaffected', tags=()), Channel(name='advertising', description='Local node mDNS service advertisement started', level='info', wire=None, say='advertising {instance} on port {port}', tags=()), Channel(name='send_error', description='Multicast link cannot carry advertisement', level='trouble', wire=None, say='the link will not carry an advertisement ({error}); nothing else is affected', tags=()))
- METRICS: tuple[Any, ...] = (Metric(name='lan_advertisements', description='Times mDNS advertisement was started.', kind='counter', unit='', labels=(), counts='advertising', sample=None, buckets=(), tags=('lan', 'mdns')), Metric(name='lan_socket_errors', description='Times mDNS socket join failed.', kind='counter', unit='', labels=(), counts='socket_error', sample=None, buckets=(), tags=('lan', 'mdns', 'error')), Metric(name='lan_send_errors', description='Times mDNS packet send failed.', kind='counter', unit='', labels=(), counts='send_error', sample=None, buckets=(), tags=('lan', 'mdns', 'error')))
- __init__(keystore, peers, face, digest=None, node_class='edge', clock=None, timeout=5.0, node=None)[source]
- records(ttl=120)[source]
The four records one advertisement is: what exists, where it is, what it says about itself, and the address behind the name.
- stop()[source]
Say goodbye before going, so a listener forgets this node at once rather than holding a dead address until the record expires.
- Return type:
- state()[source]
What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.
- Return type:
LanStateReport
- 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.
- commands: Mapping[str, CommandSpec] = {'show': {'args': {}, 'does': 'what this node advertises on its link and what it has heard there', 'reply': '{enabled, service, advertising, address, port, seen, learned, refused}', 'subsystem': 'lan'}}
3.1.6.3. P2P Hole Punching Compartment
Direct libp2p P2P transport, reached through a sidecar, as a compartment.
Protocol: /fleetmesh/didcomm/1.0.0 as declared in schema/messages.json. One stream carries one JWE; the other side answers one ack line once it has queued the message for its node. The libp2p process is fleetmesh_node/sidecar/fleetmesh_p2p.py, talked to over p2p.sock in the node’s directory, and it holds the Ed25519 transport key: its PeerId is the key transport Multikey the descriptor publishes, which is how a dial is bound to a descriptor and not to whatever multiaddr the descriptor happened to carry (see target_of).
What this compartment does with a stream it drained is what the FIPS path does with a datagram: hands the bytes to the router’s one envelope-opening rule (didcomm_inbound.open_inbound). The sidecar’s word on who wrote a stream is a hint the router checks against the sender’s descriptor, never a proof of who sent the message; that proof is the ECDH-1PU agreement or nothing.
Like fleetmesh_node/announce.py, if the sidecar is absent the node operates over the relays, which is the rung the specification says always works.
- fleetmesh_node.planes.transport.p2p.compartment.socket_path(directory)[source]
Derive the unix socket path for the p2p sidecar.
- fleetmesh_node.planes.transport.p2p.compartment.peer_id_of(raw_ed25519)[source]
The libp2p PeerId of an Ed25519 public key: the key itself, inlined.
A 32-byte key fits under the identity multihash, so the id is the protobuf PublicKey{Type: Ed25519, Data: key} wrapped as multihash(0x00, len, pb) and base58btc-encoded - the 12D3KooW… form. No hashing, so a descriptor’s key transport Multikey and a stream’s remote PeerId are the same 32 bytes spelled two ways.
- fleetmesh_node.planes.transport.p2p.compartment.transport_key_of(desc)[source]
The raw Ed25519 transport key a descriptor publishes, or None.
- fleetmesh_node.planes.transport.p2p.compartment.target_of(desc)[source]
The multiaddr to dial for a descriptor, or why there is none.
Returns (target, None) or (None, reason). The target always ends in /p2p/<PeerId> derived from the descriptor’s own key transport: the libp2p handshake then refuses any host at that address that does not hold the key the descriptor signed over. A descriptor whose endpoint already names a PeerId must name the same one; a different one is a descriptor that contradicts itself, and is not dialled.
- exception fleetmesh_node.planes.transport.p2p.compartment.P2PError[source]
Bases:
SidecarErrorRaised when communication with the p2p sidecar fails.
- fleetmesh_node.planes.transport.p2p.compartment.ask_sidecar(directory, cmd, timeout=5.0, **args)[source]
Send one request to the p2p sidecar over its unix domain socket.
- class fleetmesh_node.planes.transport.p2p.compartment.P2PTransport[source]
Bases:
Bridge- SIDECAR: Sidecar | None = Sidecar(name='p2p', protocol='fleetmesh-p2p/1', upstream='py-libp2p stream transport on /fleetmesh/didcomm/1.0.0', transport='unix', standalone='fleetmesh-p2p NODE_DIR', probe='status', supervised=False)
- LIFECYCLE: Lifecycle = Lifecycle(breaker=Breaker(failures=5, window=300, backoff=(30, 600)), restart=True, snapshot=0)
- NEEDS: tuple[Any, ...] = (Need(key='directory', source='dir', 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='transport', source='transport', 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))
- STORES: tuple[Store, ...] = (Store(key='egress_queue', description='outbound frames queued for libp2p sidecar', kind='ring', shape=<class 'bytes'>, bound=1024, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()),)
- COMMANDS: tuple[Any, ...] = (Command(key='status', name='P2P Status', description='display libp2p sidecar connectivity and stream counters', tags=('p2p', 'status'), parameters=(), permission='p2p/status', process=(), run='state', reply='dict', reads=(), writes=()), Command(key='drain', name='Drain P2P Streams', description='drain inbound direct P2P messages from the sidecar', tags=('p2p', 'drain'), parameters=(), permission='p2p/drain', process=(), run='drain_cmd', reply='dict', reads=(), writes=()), Command(key='send', name='Send P2P Message', description='dispatch one already-sealed JWE over a libp2p stream', tags=('p2p', 'send'), parameters=(Parameter(key='target', name='target', description='target multiaddr', 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), Parameter(key='payload', name='payload', description='sealed JWE payload', type=<class 'dict'>, default=<class 'dict'>, 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='p2p/send', process=(), run='send_cmd', reply='dict', reads=(), writes=()), Command(key='sidecar', name='P2p 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=('p2p', 'sidecar', 'bridge'), parameters=(), permission='p2p/sidecar', process=(), run='bridge_state', reply='{sidecar, endpoint, link, since, protocol, last_error, calls, failures}', reads=(), writes=()), Command(key='probe', name='Probe p2p sidecar', description='ask the sidecar now (its `status` request) rather than wait for the next tick', tags=('p2p', 'sidecar', 'bridge'), parameters=(), permission='p2p/probe', process=('p2p',), run='probe', reply='{link, protocol, status | error}', reads=(), writes=()))
- state()[source]
What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.
- Return type:
P2PState
- sections()[source]
What a KIND of compartment adds to every report of its kind - a bridge, its link - so that a subclass’s own state() stays its own.
- 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.
- deliver(item)[source]
One drained stream to the router. Returns None, or why it was refused.
injected items are what the sidecar’s test hook queued: no stream was authenticated, so no origin key is asserted for them.
- send_direct(target_multiaddr, payload)[source]
Deliver one sealed JWE to target_multiaddr; True only after the peer acked.
- CHANNELS: tuple[Any, ...] = (Channel(name='p2p.sidecar.reachable', description='The p2p sidecar answered, in a protocol this bridge speaks.', level='info', wire=<function bridge_channels.<locals>.<lambda>>, say='sidecar up at {endpoint} ({protocol})', tags=('p2p', 'sidecar', 'bridge')), Channel(name='p2p.sidecar.unreachable', description='The p2p 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=('p2p', 'sidecar', 'bridge')), Channel(name='p2p.sidecar.incompatible', description='The p2p 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=('p2p', 'sidecar', 'bridge')))
- METRICS: tuple[Any, ...] = (Metric(name='p2p_sidecar_reachable', description='Times the p2p sidecar was found reachable.', kind='counter', unit='', labels=(), counts='p2p.sidecar.reachable', sample=None, buckets=(), tags=('p2p', 'sidecar')), Metric(name='p2p_sidecar_unreachable', description='Times the p2p sidecar was found unreachable.', kind='counter', unit='', labels=(), counts='p2p.sidecar.unreachable', sample=None, buckets=(), tags=('p2p', 'sidecar')), Metric(name='p2p_sidecar_incompatible', description='Times the p2p sidecar answered in a protocol this bridge does not speak.', kind='counter', unit='', labels=(), counts='p2p.sidecar.incompatible', sample=None, buckets=(), tags=('p2p', 'sidecar')))
- commands: Mapping[str, CommandSpec] = {'drain': {'args': {}, 'does': 'drain inbound direct P2P messages from the sidecar', 'reply': 'dict', 'subsystem': 'p2p'}, 'probe': {'args': {}, 'does': 'ask the sidecar now (its `status` request) rather than wait for the next tick', 'reply': '{link, protocol, status | error}', 'subsystem': 'p2p'}, 'send': {'args': {'payload': 'required', 'target': 'required'}, 'does': 'dispatch one already-sealed JWE over a libp2p stream', 'reply': 'dict', 'subsystem': 'p2p'}, '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': 'p2p'}, 'status': {'args': {}, 'does': 'display libp2p sidecar connectivity and stream counters', 'reply': 'dict', 'subsystem': 'p2p'}}
3.1.6.4. Sidecar Bridge Compartment
Universal Nostr Relay Bridge for fleetmesh.
Bridges external standard Nostr relays (strfry, nostr-rs-relay, khatru, coracle, damus) with the local fleetmesh node: 1. Ingress Engine: Connects to designated external relays over WebSocket (via Relay/ws),
subscribes to shard topics (#t), mesh control kinds (11801, 11803, 30803, etc.) or user content kinds (0, 1, 3, 7, 1059, etc.), cryptographically verifies BIP-340 signatures, enforces future timestamp and expiry limits, deduplicates, and ingests into the local NodeStore with origin recorded.
Egress Engine: Queues and publishes verified events (produced locally or across the mesh) out to designated external relays, tracking acceptance, handling NIP-42 auth challenges, and retrying on transient errors.
Flow Control & Capacity: Sliding-window rate limiting per relay to protect node memory and disk from upstream relay flooding, integrated with the Compartment refusal and trouble reporting interfaces.
- class fleetmesh_node.planes.transport.bridge.compartment.RelayBridgeWorker[source]
Bases:
objectManages an active subscription and streaming connection to a single external Nostr relay.
- publish(ev)[source]
Publish one event directly to this relay, returning (accepted, reason).
- Parameters:
ev (NostrEvent)
- Return type:
- class fleetmesh_node.planes.transport.bridge.compartment.RelayBridge[source]
Bases:
Compartment- config_cls
alias of
BridgeConfig
- NEEDS: tuple[Any, ...] = (Need(key='store_backend', 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='cfg', source=None, block=<class 'fleetmesh_node.config.compartments.BridgeConfig'>, late=False, getter=False, path=None, field=None), Need(key='p2p', source='p2p', block=None, late=False, getter=False, path=None, field=None))
- STORES: tuple[Store, ...] = (Store(key='egress_queue', description='events queued for broadcast to external relays', kind='ring', shape=None, bound=1000, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()),)
- CHANNELS: tuple[Any, ...] = (Channel(name='ingress_stored', description='An event received from an external relay was verified and stored', level='note', wire=None, say='bridge stored event {id} from {relay}', tags=('bridge', 'ingress')), Channel(name='ingress_refused', description='An event received from an external relay was refused', level='trouble', wire=None, say='bridge refused event from {relay}: {reason}', tags=('bridge', 'ingress', 'refused')), Channel(name='egress_sent', description='An event was published to external relays', level='note', wire=None, say='bridge published event {id} to {relay}', tags=('bridge', 'egress')), Channel(name='egress_failed', description='Failed to publish event to an external relay', level='trouble', wire=None, say='bridge failed to publish to {relay}: {reason}', tags=('bridge', 'egress', 'failed')))
- METRICS: tuple[Any, ...] = (Metric(name='bridge_ingress_stored', description='Events received from external relays and stored.', kind='counter', unit='', labels=(), counts='ingress_stored', sample=None, buckets=(), tags=('bridge', 'ingress')), Metric(name='bridge_ingress_refused', description='Events received from external relays and refused.', kind='counter', unit='', labels=(), counts='ingress_refused', sample=None, buckets=(), tags=('bridge', 'ingress')), Metric(name='bridge_egress_sent', description='Events published to external relays.', kind='counter', unit='', labels=(), counts='egress_sent', sample=None, buckets=(), tags=('bridge', 'egress')), Metric(name='bridge_egress_failed', description='Events that failed publication to external relays.', kind='counter', unit='', labels=(), counts='egress_failed', sample=None, buckets=(), tags=('bridge', 'egress')))
- COMMANDS: tuple[Any, ...] = (Command(key='show', name='Bridge Status', description='display bridge status and connected relays', tags=('bridge', 'status'), parameters=(), permission='bridge/show', process=(), run='state', reply='dict', reads=(), writes=()), Command(key='publish', name='Publish Event', description='publish a nostr event to external relays', tags=('bridge', 'publish'), parameters=(Parameter(key='event', name='event', description='nostr event object', type=<class 'dict'>, default=<class 'dict'>, 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), Parameter(key='relays', name='relays', description='target relays list', type=<class 'list'>, default=None, must='', tags=(), 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)), permission='bridge/publish', process=(), run='publish_cmd', reply='dict', reads=(), writes=()), Command(key='sync', name='Sync Query', description='query external relays for matching events', tags=('bridge', 'sync'), parameters=(Parameter(key='filter', name='filter', description='subscription filter', type=<class 'object'>, default=None, must='', tags=(), 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='relay', name='relay', description='target relay URL', type=<class 'str'>, default=None, must='', tags=(), 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)), permission='bridge/sync', process=(), run='sync_cmd', reply='dict', reads=(), writes=()), Command(key='reconcile', name='Reconcile With Relay', description='reconcile events with a target relay', tags=('bridge', 'reconcile'), parameters=(Parameter(key='relay', name='relay', description='target relay URL', type=<class 'str'>, default=None, must='', tags=(), 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='filter', name='filter', description='subscription filter', type=<class 'object'>, default=None, must='', tags=(), 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='since', name='since', description='start timestamp', type=<class 'int'>, default=None, must='', tags=(), 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='until', name='until', description='end timestamp', type=<class 'int'>, default=None, must='', tags=(), 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='limit', name='limit', description='max events', type=<class 'int'>, default=500, must='', tags=(), 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)), permission='bridge/reconcile', process=(), run='reconcile_cmd', reply='dict', reads=(), writes=()), Command(key='add_relay', name='Add Relay', description='add an external relay URL to bridge', tags=('bridge', 'relay'), parameters=(Parameter(key='url', name='url', description='relay ws:// or wss:// URL', 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='bridge/add_relay', process=(), run='add_relay_cmd', reply='dict', reads=(), writes=()), Command(key='remove_relay', name='Remove Relay', description='remove an external relay URL from bridge', tags=('bridge', 'relay'), parameters=(Parameter(key='url', name='url', description='relay URL to remove', 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='bridge/remove_relay', process=(), run='remove_relay_cmd', reply='dict', reads=(), writes=()), Command(key='cursor', name='Bridge Cursors', description='query persistent relay checkpoint cursors', tags=('bridge', 'cursor'), parameters=(), permission='bridge/cursor', process=(), run='cursor_cmd', reply='list', reads=(), writes=()), Command(key='cursors', name='Bridge Cursors Alias', description='query persistent relay checkpoint cursors (alias)', tags=('bridge', 'cursor'), parameters=(), permission='bridge/cursor', process=(), run='cursor_cmd', reply='list', reads=(), writes=()))
- handle_ingress_event(ev, relay_url)[source]
Ingest, validate, and store an event received from an external relay.
Returns one of: stored, duplicate, rate_limited, invalid, future_skew, expired.
- publish(ev, target_relays=None)[source]
Publish an event to external relays.
Returns {relay_url: (accepted, reason)}.
- enqueue_egress(ev, target_relays=None)[source]
Enqueue an event to be published out to external relays asynchronously.
- Parameters:
ev (NostrEvent)
- Return type:
None
- flush_egress()[source]
Process and send all queued egress events. Returns count of processed items.
- Return type:
- sync_query(filters, target_relays=None, timeout=15.0)[source]
Perform an ad-hoc query against external relays and ingest matching events.
- reconcile_with_relay(relay_url, filter_spec=None, since=None, until=None, limit=500)[source]
Perform a range-bounded reconciliation against an external relay to backfill historical events.
- state()[source]
What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.
- Return type:
BridgeStateReport
- 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.
- commands: Mapping[str, CommandSpec] = {'add_relay': {'args': {'url': 'required'}, 'does': 'add an external relay URL to bridge', 'reply': 'dict', 'subsystem': 'bridge'}, 'cursor': {'args': {}, 'does': 'query persistent relay checkpoint cursors', 'reply': 'list', 'subsystem': 'bridge'}, 'cursors': {'args': {}, 'does': 'query persistent relay checkpoint cursors (alias)', 'reply': 'list', 'subsystem': 'bridge'}, 'publish': {'args': {'event': 'required', 'relays': 'optional'}, 'does': 'publish a nostr event to external relays', 'reply': 'dict', 'subsystem': 'bridge'}, 'reconcile': {'args': {'filter': 'optional', 'limit': 'optional', 'relay': 'optional', 'since': 'optional', 'until': 'optional'}, 'does': 'reconcile events with a target relay', 'reply': 'dict', 'subsystem': 'bridge'}, 'remove_relay': {'args': {'url': 'required'}, 'does': 'remove an external relay URL from bridge', 'reply': 'dict', 'subsystem': 'bridge'}, 'show': {'args': {}, 'does': 'display bridge status and connected relays', 'reply': 'dict', 'subsystem': 'bridge'}, 'sync': {'args': {'filter': 'optional', 'relay': 'optional'}, 'does': 'query external relays for matching events', 'reply': 'dict', 'subsystem': 'bridge'}}
3.1.6.5. Mediation & Multi-Hop Circuit Compartment
The Mediation compartment: the operator commands and the inbound door for the three mediation PIURIs, acting for the proven sender.
- class fleetmesh_node.planes.transport.mediation.compartment.Mediation[source]
Bases:
WireProtocolThe mediation compartment of meshnode (routing/2.0 & coordinate-mediation/2.0).
- piuris: tuple[str, ...] = ('https://didcomm.org/coordinate-mediation/2.0', 'https://didcomm.org/routing/2.0', 'https://didcomm.org/messagepickup/2.0')
- OUTBOUND: tuple[Outbound, ...] = (Outbound('mediate-grant'), Outbound('mediate-deny'), Outbound('keylist-update-response'), Outbound('delivery'), Outbound('status'))
- config_cls
alias of
MediationConfig
- SCHEMA: tuple[Any, ...] = (Table(name='leaves', columns=(Column(name='leaf_did', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='admitted_at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='status', type='TEXT', nullable=False, primary_key=False, default="'active'", unique=False)), primary_key=(), indices=(), without_rowid=False), Table(name='keylist', columns=(Column(name='recipient_key', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='leaf_did', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='registered_at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=(), indices=(Index(name='idx_keylist_leaf', columns=('leaf_did',), table='keylist', unique=False),), without_rowid=False), Table(name='inbox', columns=(Column(name='msg_id', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='recipient_key', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='sender_did', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='payload', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='enqueued_at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='delivered', type='INTEGER', nullable=False, primary_key=False, default=0, unique=False)), primary_key=(), indices=(Index(name='idx_inbox_recip', columns=('recipient_key', 'delivered'), table='inbox', unique=False),), without_rowid=False))
- STORES: tuple[Store, ...] = (Store(key='handled', description='messages handled by protocol message type', kind='table', shape=<class 'int'>, bound=64, evict='lru', keyed_by='msg_type', persist='memory', sensitive=False, tags=()),)
- CHANNELS: tuple[Any, ...] = (Channel(name='message_forwarded', description='Mediation forward message queued for leaf', level='info', wire=None, say='forward message queued for recipient {recipient}', tags=('mediation', 'forward')), Channel(name='forward_refused', description='Mediation forward message refused or dropped', level='trouble', wire=None, say='forward message refused for recipient {recipient}', tags=('mediation', 'forward')), Channel(name='mediation_granted', description='Mediation admission granted to leaf', level='info', wire=None, say='mediation admission granted to {leaf}', tags=('mediation', 'admission')), Channel(name='messages_drained', description='Queued messages picked up by leaf', level='info', wire=None, say='picked up {count} messages for {leaf}', tags=('mediation', 'pickup')), Channel(name='sender_unauthenticated', description='Mediation message sender not authenticated', level='trouble', wire=None, say='mediation request refused: sender not authenticated', tags=('mediation', 'security')))
- METRICS: tuple[Any, ...] = (Metric(name='mediation_messages_forwarded', description='Messages buffered for mediated leaves.', kind='counter', unit='', labels=(), counts='message_forwarded', sample=None, buckets=(), tags=('mediation', 'forward')), Metric(name='mediation_forward_refused', description='Forward messages refused or dropped.', kind='counter', unit='', labels=(), counts='forward_refused', sample=None, buckets=(), tags=('mediation', 'forward')), Metric(name='mediation_admissions_granted', description='Leaves admitted into mediation.', kind='counter', unit='', labels=(), counts='mediation_granted', sample=None, buckets=(), tags=('mediation', 'admission')), Metric(name='mediation_messages_drained', description='Batches of messages drained by leaves.', kind='counter', unit='', labels=(), counts='messages_drained', sample=None, buckets=(), tags=('mediation', 'pickup')), Metric(name='mediation_unauthenticated', description='Mediation messages from unauthenticated senders.', kind='counter', unit='', labels=(), counts='sender_unauthenticated', sample=None, buckets=(), tags=('mediation', 'security')))
- HANDLERS: tuple[Handler, ...] = (Handler(kind='forward', run='handle_forward', schema=None, doc='buffer inbound routing/2.0 forward envelope for mobile leaf', exact=False, reads=(), writes=()), Handler(kind='mediate-request', run='handle_mediate_request', schema=None, doc='grant coordinate-mediation admission', exact=False, reads=(), writes=('mediation',)), Handler(kind='keylist-update', run='handle_keylist_update', schema=None, doc='update leaf routing keys', exact=False, reads=(), writes=('mediation',)), Handler(kind='delivery-request', run='handle_pickup_delivery_request', schema=None, doc='drain queued messages for leaf', exact=False, reads=('mediation',), writes=()), Handler(kind='messages-received', run='handle_pickup_messages_received', schema=None, doc='acknowledge and purge delivered messages', exact=False, reads=(), writes=('mediation',)))
- COMMANDS: tuple[Any, ...] = (Command(key='show', name='Mediation Status', description='display active mediated leaves and queue depth', tags=('mediation', 'status'), parameters=(), permission='mediation/show', process=(), run='show_cmd', reply='dict', reads=(), writes=()), Command(key='grant', name='Grant Mediation', description='admit leaf into mediation and grant routing keys', tags=('mediation', 'grant'), parameters=(Parameter(key='leaf', name='leaf', description='did of the leaf to admit', 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='mediation/grant', process=(), run='grant_cmd', reply='dict', reads=(), writes=()), Command(key='forward', name='Forward Message', description='buffer inbound routing/2.0 forward envelope for mobile leaf', tags=('mediation', 'forward'), parameters=(Parameter(key='message', name='message', description='forward envelope (dict or json string)', type=<class 'object'>, default=<class 'dict'>, 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='mediation/forward', process=(), run='forward_cmd', reply='bool', reads=(), writes=()), Command(key='pickup', name='Pickup Messages', description='drain queued forwarded envelopes for mobile leaf', tags=('mediation', 'pickup'), parameters=(Parameter(key='leaf', name='leaf', description='did of the leaf to drain for', 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), Parameter(key='limit', name='limit', description='max envelopes to drain', type=<class 'int'>, default=10, must='', tags=(), 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)), permission='mediation/pickup', process=(), run='pickup_cmd', reply='dict', reads=(), writes=()))
- NEEDS: tuple[Any, ...] = (Need(key='db_path', source=None, block=None, late=False, getter=False, path='DB', field=None), Need(key='mediator_did', source='did', 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))
- __init__(node=None, db_path=None, mediator_did=None, clock=None, transport=None, db=None)[source]
Built by from_context in a node. The bare Mediation() and Mediation(node=fake) forms the tests use still work: with no path the store is in memory, and with no DID the one on node.ks is used if there is one.
- commands: Mapping[str, CommandSpec] = {'forward': {'args': {'message': 'required'}, 'does': 'buffer inbound routing/2.0 forward envelope for mobile leaf', 'reply': 'bool', 'subsystem': 'mediation'}, 'grant': {'args': {'leaf': 'required'}, 'does': 'admit leaf into mediation and grant routing keys', 'reply': 'dict', 'subsystem': 'mediation'}, 'pickup': {'args': {'leaf': 'required', 'limit': 'optional'}, 'does': 'drain queued forwarded envelopes for mobile leaf', 'reply': 'dict', 'subsystem': 'mediation'}, 'show': {'args': {}, 'does': 'display active mediated leaves and queue depth', 'reply': 'dict', 'subsystem': 'mediation'}}