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.

Bases: Compartment

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

alias of TransportConfig

requires: tuple[str, ...] = ()
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

__init__(transport, strain=None, clock=None, node=None)[source]
Parameters:
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.

Parameters:

now (int)

Return type:

list[tuple[Any, …]]

FAULTS_SHOWN: int = 20
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.

Parameters:

now (int | None)

Return type:

list[Fault]

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.

Return type:

list[str]

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': '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'}}
live: tuple[str, ...] = ()

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.

Parameters:

pubkey (str)

Return type:

str

class fleetmesh_node.planes.transport.lan.compartment.Lan[source]

Bases: Compartment

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

alias of LanConfig

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))
EVERY: tuple[Any, ...] = (Every(seconds=60, run='_announce', name='_announce', report=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]
Parameters:
Return type:

None

property enabled: bool
property face_port: int
txt()[source]
Return type:

dict[str, str]

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.

Parameters:

ttl (int)

Return type:

list[Record]

start()[source]

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

Return type:

None

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:

Any

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:

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.

Return type:

list[str]

abstract: ClassVar[bool] = False
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'}}
live: tuple[str, ...] = ('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.

Parameters:

directory (str)

Return type:

str

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.

Parameters:

raw_ed25519 (bytes)

Return type:

str

fleetmesh_node.planes.transport.p2p.compartment.transport_key_of(desc)[source]

The raw Ed25519 transport key a descriptor publishes, or None.

Parameters:

desc (Mapping[str, Any] | None)

Return type:

bytes | 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.

Parameters:

desc (Mapping[str, Any] | None)

Return type:

tuple[str | None, str | None]

exception fleetmesh_node.planes.transport.p2p.compartment.P2PError[source]

Bases: SidecarError

Raised 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.

Parameters:
Return type:

Any

class fleetmesh_node.planes.transport.p2p.compartment.P2PTransport[source]

Bases: Bridge

optional: bool = True
enabled_by: str | None = 'p2p'

The direct libp2p transport compartment.

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

alias of P2PConfig

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)
CONSEQUENCE: str = 'direct libp2p connections are unavailable; falling back to relays'
LIFECYCLE: Lifecycle = Lifecycle(breaker=Breaker(failures=5, window=300, backoff=(30, 600)), restart=True, snapshot=0)
SIDECAR_REACHABLE: str = 'p2p.sidecar.reachable'
SIDECAR_UNREACHABLE: str = 'p2p.sidecar.unreachable'
SIDECAR_INCOMPATIBLE: str = 'p2p.sidecar.incompatible'
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=()))
__init__(directory, peers=None, transport=None, clock=None, node=None, ks=None)[source]
Parameters:
Return type:

None

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

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.

Return type:

Mapping[str, Any]

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]

tick(now)[source]

Periodic work. Runs due EVERY jobs when not overridden.

Parameters:

now (int)

Return type:

list[tuple[Any, …]]

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.

Parameters:

item (Mapping[str, Any])

Return type:

str | None

send_direct(target_multiaddr, payload)[source]

Deliver one sealed JWE to target_multiaddr; True only after the peer acked.

Parameters:
Return type:

tuple[bool, str]

drain_cmd()[source]
Return type:

Any

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')))
abstract: ClassVar[bool] = False
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'}}
live: tuple[str, ...] = ()
send_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

SendResult

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.

  1. 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.

  2. 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.

exception fleetmesh_node.planes.transport.bridge.compartment.BridgeError[source]

Bases: Exception

class fleetmesh_node.planes.transport.bridge.compartment.RelayBridgeWorker[source]

Bases: object

Manages an active subscription and streaming connection to a single external Nostr relay.

__init__(url, filters, on_event, auth_signer=None, timeout=15.0, stop_event=None)[source]
Parameters:
Return type:

None

start()[source]
Return type:

None

stop()[source]
Return type:

None

publish(ev)[source]

Publish one event directly to this relay, returning (accepted, reason).

Parameters:

ev (NostrEvent)

Return type:

tuple[bool, str]

stats()[source]
Return type:

RelayWorkerStats

class fleetmesh_node.planes.transport.bridge.compartment.RelayBridge[source]

Bases: Compartment

optional: bool = True
enabled_by: str | None = 'bridge'

The Universal Nostr Relay Bridge compartment.

name: str = 'bridge'
uses: tuple[str, ...] = ('p2p',)
reads: tuple[str, ...] = ('bridge', 'relays')
config_cls

alias of BridgeConfig

live: tuple[str, ...] = ('bridge',)
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=()),)
egress_queue: Ring[tuple[Any, ...]]
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=()))
TROUBLE_WINDOW: int = 1800
__init__(store_backend, face=None, relays=None, cfg=None, clock=None, node=None, p2p=None)[source]
Parameters:
Return type:

None

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.

Parameters:
Return type:

str

publish(ev, target_relays=None)[source]

Publish an event to external relays.

Returns {relay_url: (accepted, reason)}.

Parameters:
Return type:

dict[str, tuple[bool, str]]

enqueue_egress(ev, target_relays=None)[source]

Enqueue an event to be published out to external relays asynchronously.

Parameters:
Return type:

None

flush_egress()[source]

Process and send all queued egress events. Returns count of processed items.

Return type:

int

sync_query(filters, target_relays=None, timeout=15.0)[source]

Perform an ad-hoc query against external relays and ingest matching events.

Parameters:
Return type:

Mapping[str, Any]

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.

Parameters:
Return type:

Mapping[str, Any]

start()[source]

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

Return type:

None

stop()[source]

Anything that must be said before the node goes. Must not raise.

Return type:

list[tuple[str, str]]

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:

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.

Return type:

list[str]

publish_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Any

sync_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Any

reconcile_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Any

add_relay_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

remove_relay_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

abstract: ClassVar[bool] = False
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'}}
cursor_cmd()[source]
Return type:

Any

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: WireProtocol

The mediation compartment of meshnode (routing/2.0 & coordinate-mediation/2.0).

name: str | None = 'mediation'
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'))
reads: tuple[str, ...] = ('mediation', 'endpoints', 'relays')
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=()))
DB: str = 'mediation.sqlite'
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.

Parameters:
  • node (Any)

  • db_path (str | None)

  • mediator_did (str | None)

  • clock (Callable[[], int] | None)

  • transport (Any | None)

  • db (Any | None)

Return type:

None

show_cmd()[source]
Return type:

Mapping[str, Any]

grant_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Any

forward_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

bool

pickup_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Any

handle_forward(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …] | None

handle_mediate_request(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …] | None

handle_keylist_update(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …] | None

handle_pickup_delivery_request(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …] | None

handle_pickup_messages_received(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …] | None

abstract: ClassVar[bool] = False
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'}}
live: tuple[str, ...] = ()
stop()[source]

Safely close mediation persistence and worker state on shutdown.

Return type:

None