4. Transport Subsystem (fleetmesh_node.transport)

The fleetmesh_node.transport package implements the multi-rung transport ladder. Traffic automatically ascends through available rungs based on peer capabilities, firewall conditions, and cryptographic policies.

4.1. Transport Ladder Architecture

The Transport Router evaluates outbound routes across a prioritized ladder sorted by rank (lowest rank is attempted first):

  1. FIPS Rung (Rank 5, mTLS / Datagram): Hardware-enforced mutual authentication using NIST-approved curves and FIPS 140-3 validated cryptography.

  2. Iroh Rung (Rank 10, QUIC): Direct, encrypted point-to-point datagrams with ALPN negotiation, DERP relay hole punching, and high throughput.

  3. Rhio Rung (Rank 12, NATS JetStream): Micro-datacenter cluster synchronization delivering through local Unix domain socket IPC to the Rhio sidecar daemon.

  4. P2Panda Rung (Rank 15, Append-Only Operation Chains): Peer-to-peer delivery wrapping DIDComm messages into signed p2panda operations published to local append-only logs and synced peers.

  5. Relay Rung (Rank 30, WebSocket): Outbound-only fallback over public or private Nostr relays. Guarantees reachability behind strict firewalls and NATs.

4.1.1. Telemetry Metric Tags

The router reports successful deliveries via the metric_tags() method. Telemetry dynamically records delivery counts across all active rungs (including pluggable rungs whenever success_counts[rung] > 0), ensuring complete visibility into multi-protocol routing efficiency.

4.2. Transport Router

The router: TransportRouter, the ladder from direct rungs down to the gift-wrap rung.

Separate from the rungs because it is the only module that knows about all of them, and the direct rungs import from const.py without ever importing the router back.

class fleetmesh_node.transport.router.RefusalRow[source]

Bases: TypedDict

A direct rung’s refusal of one peer, for the ladder’s telemetry.

peer: str
transport: str
error: str
at: int
class fleetmesh_node.transport.router.LadderHealthRow[source]

Bases: TypedDict

Circuit breaker and availability status of one transport rung.

available: bool
circuit_breakers: dict[str, str]
failures: dict[str, int]
class fleetmesh_node.transport.router.NullTransport[source]

Bases: object

A null transport rung used when Nostr is disabled in configuration.

name: str = 'none'
health: Mapping[str, Any] = {}
awaiting: Mapping[str, Any] = {}
acked: Mapping[str, int] = {}
acks_in: int = 0
acks_out: int = 0
unacked: Sequence[Any] = ()
wraps_in: Mapping[str, int] = {}
wraps_seen_again: Mapping[str, int] = {}
cooldown: Any | None = None
listening()[source]
Return type:

tuple[str, …]

wait_listening(timeout=0)[source]
Parameters:

timeout (float)

Return type:

bool

start(since=0)[source]
Parameters:

since (int)

Return type:

None

stop()[source]
Return type:

None

unfinished()[source]
Return type:

list[Any]

sweep(now)[source]
Parameters:

now (int)

Return type:

list[Any]

take_unacked()[source]
Return type:

list[Any]

listen(thid)[source]
Parameters:

thid (str)

Return type:

None

unlisten(thid)[source]
Parameters:

thid (str)

Return type:

None

available()[source]
Return type:

bool

send(*args, **kwargs)[source]
Parameters:
Return type:

Mapping[str, Any]

class fleetmesh_node.transport.router.TransportRouter[source]

Bases: FipsRungMixin

The multi-transport router and ladder negotiator.

Implements TransportProtocol across all active transports: - fips-native: datagram flows through the fips sidecar (mesh-encrypted) - iroh: EXPERIMENTAL / unauthenticated. Direct TCP stream or the

iroh_live UDP framing; the wire itself is neither encrypted nor authenticated, only the DIDComm JWE inside is. Opt-in: built only when config names an iroh endpoint (see __init__).

  • libp2p: stream through the p2p sidecar, when the node builds one

  • nostr: NIP-59 gift-wrapped DIDComm over relays (Kinds 21059 / 1059)

The ladder in send() ranks fips-native, iroh, libp2p, nostr by preference; the rank says which is tried first, not which is safer. Every rung is held to the same envelope rule (didcomm_inbound).

Performs dynamic ladder negotiation (fleetmesh_core.storage.replication.negotiate) based on peer descriptor endpoints, automatically falling back down the ladder to Nostr when direct streams fail or are unavailable.

scheme: str = 'router'
__init__(keystore, peers, relay_urls=(), endpoints=None, clock=None, timeout=15.0, seen_store=None, ack_store=None, iroh_host='127.0.0.1', iroh_port=0, sidecar_dir=None, enable_iroh=None, iroh_mode='stream', fips_sock_path=None, enable_fips=True, fips_port=11801, fips_client=None, enable_nostr=True)[source]
Parameters:
Return type:

None

ks: Any
peers: Any
relays: list[str]
clock: Callable[[], int]
timeout: float
endpoints_cfg: list[Any]
enable_nostr: bool
nostr: Any
iroh: Any | None
fips_port: int
fips_sock_path: str | None
fips: Any | None
p2p: Any | None
transports: MutableMapping[str, Any]
inbox: Queue[Inbound]
success_counts: Counter[str]
refusals_log: Deque[RefusalRow]
faults: FaultLog
guard: InboundGuard
circuit_breakers: dict[str, CircuitBreaker]
rungs: list[RungProtocol]
register_rung(rung)[source]

Register a dynamic transport rung into the ladder.

Parameters:

rung (RungProtocol)

Return type:

None

add_rung(rung)[source]

Alias for register_rung to satisfy ProtocolManager.

Parameters:

rung (RungProtocol)

Return type:

None

unregister_rung(name)[source]

Remove a transport rung by name from the ladder.

Parameters:

name (str)

Return type:

RungProtocol | None

get_rung(name)[source]

Retrieve a registered transport rung by name.

Parameters:

name (str)

Return type:

RungProtocol | None

property health: Mapping[str, RelayHealthRow]
rung_health()[source]

Every rung’s own report, keyed by rung name; a rung whose daemon is not built is absent. The one view of the ladder’s state.

Return type:

dict[str, Mapping[str, int | str | bool | float]]

property ladder_health: dict[str, LadderHealthRow]

Circuit breaker and availability status across transport rungs.

fault_logs()[source]

The ladder’s own fault log and every rung’s that keeps one.

Return type:

list[FaultLog]

recent_faults(since=None)[source]

What every rung refused or lost, newest last, with reasons.

Parameters:

since (int | None)

Return type:

list[Fault]

property drop_counts: Counter[str]
property dropped: Deque[tuple[str, str | None]]
property cooldown: RelayCooldown | None

which relays are being rested after a rate-limit and until when. None for a relay-rung double that keeps none.

Type:

The relay rung’s cooldown ledger

property awaiting: dict[str, AwaitingEntry]
property acked: Counter[str]
property acks_in: int
property acks_out: int
property unacked: Deque[AckVerdict]
property wraps_in: Counter[int | None]
property wraps_seen_again: Counter[int | None]
unfinished()[source]
Return type:

int

sweep(now=None)[source]
Parameters:

now (int | None)

Return type:

list[AckVerdict]

take_unacked()[source]
Return type:

list[AckVerdict]

listening()[source]
Return type:

int

wait_listening(timeout=8.0)[source]
Parameters:

timeout (float)

Return type:

bool

start(since=None)[source]
Parameters:

since (int | None)

Return type:

TransportRouter

deliver_direct(scheme, payload, wrap_id, origin=None)[source]

One payload off a direct rung (fips-native, libp2p): a JWE, or nothing.

Returns None when the message was queued or was an empty ping, else the reason it was dropped, which is also recorded.

The daemon behind a direct rung proves for itself who the other end of a flow or stream is, but this node never sees that proof - it reads a payload off a local socket, and on a cluster daemon, a mock, or a shared host anyone with the socket can write one. So the payload is treated exactly as a stream off the internet is: it must be a JWE this node can open, and the sender is whoever the agreement proves, never the from field. A plaintext frame on this path used to arrive as an authenticated message from anyone it cared to name, and resolved whatever request() was waiting for; now it is a drop with a reason, and nothing else.

origin, when a sidecar reports one, is the raw Ed25519 transport key hex the remote stream authenticated with. It is a hint, not the sender: the sender’s descriptor publishes its transport key, and a message whose proven sender advertises a different one did not come from that sender’s node, so it is dropped rather than delivered as something it is not.

Nothing in here may raise: the reader loop ends on any exception, which would let one malformed frame take the flow down.

Parameters:
  • scheme (str)

  • payload (Any)

  • wrap_id (str)

  • origin (str | None)

Return type:

str | None

stop()[source]
Return type:

None

set_send_interceptor(interceptor)[source]

Register a send interceptor (e.g. for cluster partition and loss simulation).

Parameters:

interceptor (Callable[[...], dict[str, tuple[bool, str]]] | None)

Return type:

None

clear_send_interceptor()[source]

Remove any registered send interceptor.

Return type:

None

set_rung_interceptor(interceptor)[source]

Register a per-rung delivery interceptor (e.g. for directed partition and cascade testing).

Parameters:

interceptor (Callable[[str, DIDCommMessage | Mapping[str, Any], str, Any, bool], dict[str, tuple[bool, str]] | None] | None)

Return type:

None

clear_rung_interceptor()[source]

Remove any registered rung interceptor.

Return type:

None

send(message, to_pubkey, anonymous=False, stored=False)[source]

Dispatch a message over the top negotiated transport ladder rung.

stored=True requires store-and-forward relays (NIP-59 Kind 1059). Live messages negotiate fips-native or iroh if mutually supported, falling back down the ladder to relay gift-wraps if dialing fails.

Parameters:
Return type:

dict[str, tuple[bool, str]]

request(message, to_pubkey, timeout=30.0, anonymous=False)[source]

Send and wait for the reply threaded on this message’s id.

Parameters:
Return type:

Inbound | None

converse(message, to_pubkey, thid, timeout=30.0, anonymous=False)[source]

Send and wait for next message on thread across any active transport.

Parameters:
Return type:

Inbound | None

listen(thid)[source]

Route messages on this thread to a dedicated queue.

Parameters:

thid (str)

Return type:

Queue[Inbound]

unlisten(thid)[source]
Parameters:

thid (str)

Return type:

None

receive(timeout=None)[source]

Fetch next delivered message from unified inbox.

Parameters:

timeout (float | None)

Return type:

Inbound | None

metric_tags()[source]

Telemetry metric tags per spec section 6444.

Return type:

list[list[str]]

4.3. Ladder State Machine

Per-rung circuit breaker and the rung base class for the transport ladder.

The ladder itself - which rung is tried first for a peer, and in what order the rest follow - lives in router.py (TransportRouter); the order is fips-native, iroh, libp2p, nostr and is not decided here. This module holds the pieces every rung shares: a CircuitBreaker that stops the router from hanging on a target that keeps failing, a FaultLog so that what a rung dropped and why is readable rather than only countable. The rung contract itself (RungProtocol, Rung) is in rung.py. Standard library only.

class fleetmesh_node.transport.ladder.CircuitBreaker[source]

Bases: object

Per-target circuit breaker to avoid hanging on repeatedly failing transports.

STATE_CLOSED: str = 'closed'
STATE_OPEN: str = 'open'
STATE_HALF_OPEN: str = 'half_open'
__init__(failure_threshold=3, recovery_timeout=30.0)[source]
Parameters:
  • failure_threshold (int)

  • recovery_timeout (float)

Return type:

None

allow_attempt(target, now=None)[source]

Return True if an attempt to reach target is permitted.

Parameters:
Return type:

bool

record_success(target)[source]

Record successful transmission, resetting circuit to CLOSED.

Parameters:

target (str)

Return type:

None

record_failure(target, now=None)[source]

Record transmission failure, potentially tripping circuit to OPEN.

Parameters:
Return type:

None

state(target)[source]

Current state for target.

Parameters:

target (str)

Return type:

str

failures(target)[source]

Return current consecutive failure count for target.

Parameters:

target (str)

Return type:

int

reset(target=None)[source]

Reset circuit breaker for a target or all targets.

Parameters:

target (str | None)

Return type:

None

class fleetmesh_node.transport.ladder.Fault[source]

Bases: TypedDict

One thing a rung refused or lost, kept so an operator can read it.

at: int
rung: str
reason: str
ident: str | None
class fleetmesh_node.transport.ladder.FaultLog[source]

Bases: object

The most recent faults of one rung and a count per family, ever.

A count alone said ‘0 faults’ while every wrap was being refused; the reasons are what tell an operator the relay said ‘ephemeral event expired’. Thread-safe; readers get copies.

__init__(rung, clock=None, keep=200)[source]
Parameters:
Return type:

None

rung: str
clock: Any
counts: Counter[str]
record(reason, ident=None)[source]
Parameters:
  • reason (str)

  • ident (str | None)

Return type:

Fault

recent(since=None, family=None)[source]

Newest last. since keeps faults at or after that clock reading; family keeps the reason prefix (‘publish refused’).

Parameters:
  • since (int | None)

  • family (str | None)

Return type:

list[Fault]

property maxlen: int | None
fleetmesh_node.transport.ladder.merge_faults(logs, since=None)[source]

Faults across rungs in time order, for the ladder’s aggregate view.

Parameters:
Return type:

list[Fault]

4.4. Rung Base Contract

One rung of the transport ladder, and the four the node has.

The router used to know how every rung dials: four if-blocks, each with its own seal, its own breaker lookup, its own cascade note. Now a rung is one object that says whether it is up, whether it can reach a peer and where, and makes one delivery attempt; the router walks the ladder and keeps the books. A rung that is a compartment elsewhere (the relay rung, the libp2p transport) is reached through a thin adapter here so that it need not know the ladder exists.

Adapters read their daemon off the router at call time (router.fips, router.iroh, router.p2p) rather than at construction: a test swaps a fake in after the router is built, and a sidecar registers itself later.

Every rung answers the same four questions the same way - up?, where?, deliver, and what it did (health(), fault_log()) - so the router walks the ladder blindly for all of them. There is no rung the router knows by name.

class fleetmesh_node.transport.rung.FipsRung[source]

Bases: Rung

Datagram flows through the fips sidecar; mesh-encrypted by the daemon.

name: str = 'fips-native'
rank: int = 5
__init__(router, seal)[source]
Parameters:
Return type:

None

available()[source]
Return type:

bool

target_of(desc, theirs)[source]
Parameters:
Return type:

str | None

deliver(message, to_pubkey, target, anonymous)[source]
Parameters:
Return type:

dict[str, tuple[bool, str]]

health()[source]
Return type:

Mapping[str, Any] | None

class fleetmesh_node.transport.rung.IrohRung[source]

Bases: Rung

EXPERIMENTAL. A direct stream the wire itself neither encrypts nor authenticates; only the JWE inside does. Built only when configured.

name: str = 'iroh'
rank: int = 10
__init__(router)[source]
Parameters:

router (Any)

Return type:

None

available()[source]
Return type:

bool

target_of(desc, theirs)[source]
Parameters:
Return type:

str | None

deliver(message, to_pubkey, target, anonymous)[source]
Parameters:
Return type:

dict[str, tuple[bool, str]]

health()[source]
Return type:

Mapping[str, Any] | None

fault_log()[source]
Return type:

FaultLog | None

class fleetmesh_node.transport.rung.Libp2pRung[source]

Bases: Rung

A stream through the p2p sidecar; the target is derived from the descriptor’s transport key, so the dial is bound to what it signed.

name: str = 'libp2p'
rank: int = 20
__init__(router, seal)[source]
Parameters:
Return type:

None

available()[source]
Return type:

bool

target_of(desc, theirs)[source]
Parameters:
Return type:

str | None

deliver(message, to_pubkey, target, anonymous)[source]
Parameters:
Return type:

dict[str, tuple[bool, str]]

health()[source]
Return type:

Mapping[str, Any] | None

class fleetmesh_node.transport.rung.RelayRungAdapter[source]

Bases: Rung

The floor of the ladder: gift-wraps over the relays. Reaches every peer, so it never says no; the relay rung itself reports which relays took the wrap.

name: str = 'nostr'
rank: int = 100
__init__(router)[source]
Parameters:

router (Any)

Return type:

None

available()[source]
Return type:

bool

target_of(desc, theirs)[source]
Parameters:
Return type:

str | None

deliver(message, to_pubkey, target, anonymous)[source]
Parameters:
Return type:

dict[str, tuple[bool, str]]

health()[source]
Return type:

Mapping[str, Any] | None

fault_log()[source]
Return type:

FaultLog | None

class fleetmesh_node.transport.rung.RungHealth[source]

Bases: TypedDict

What a rung reports about itself; the daemon-backed rungs add their own keys.

available: bool
class fleetmesh_node.transport.rung.RungProtocol[source]

Bases: Protocol

What the ladder needs from a rung, and nothing it does not.

name: str
rank: int
available()[source]

The local side of this rung is up (daemon reachable, listener bound).

Return type:

bool

target_of(desc, theirs)[source]

Where this rung would reach the peer that published desc, or None when the descriptor does not advertise it. theirs is the peer’s scheme -> preference map already read from the descriptor.

Parameters:
Return type:

str | None

deliver(message, to_pubkey, target, anonymous)[source]

One attempt. Returns {scheme: (delivered, note)}; raises on failure so the ladder records it and moves on.

Parameters:
Return type:

dict[str, tuple[bool, str]]

health()[source]

What this rung reports about itself, or None when its daemon is not built; the router keys it by rung name.

Return type:

Mapping[str, Any] | None

fault_log()[source]

The log of what this rung refused or lost, or None when it keeps none; the router merges every log it is given.

Return type:

FaultLog | None

__init__(*args, **kwargs)
fleetmesh_node.transport.rung.endpoints_of(desc)[source]

A descriptor’s advertised rungs: (scheme -> preference, scheme -> address).

The ‘key’ tag with a fips transport key counts as a fips-native endpoint at the strongest preference, the way the handshake reads it.

Parameters:

desc (Mapping[str, Any] | None)

Return type:

tuple[dict[str, int], dict[str, str]]

4.5. Relay Rung Implementation

RelayRung: the relay rung’s state and construction. Behaviour is in the sibling mixins; this file is what an operator or a test instantiates.

class fleetmesh_node.transport.relay_rung.core.RelayRung[source]

Bases: OutboundMixin, ListenMixin, InboundMixin, LedgerMixin

scheme: str = 'nostr'
__init__(keystore, peers, relay_urls, clock=None, timeout=15.0, seen_store=None, ack_store=None, seen_max=20000)[source]
Parameters:
Return type:

None

unfinished()[source]

Envelopes half-arrived: fragments held with pieces still missing.

A number the operator reads, so it is asked for rather than reached in for. The compartment that reports it has no business in _partials.

Return type:

int

recent_faults(since=None)[source]

What this rung refused or lost, newest last, with reasons.

Parameters:

since (int | None)

Return type:

list[Fault]

property drop_counts: Counter[str]

Fault family -> how many, ever.

property dropped: Deque[tuple[str, str | None]]

(reason, wrap_id) of the most recent faults, oldest first.

4.6. Iroh QUIC Rung

Experimental

In the code and tested, but not supported in this alpha: it may change or go away. See Experimental features.

Iroh QUIC / stream transport adapter for fleetmesh.

Protocol ALPN: fleetmesh/didcomm/1 as specified in spec.html and schema/messages.json. Provides direct, low-latency, point-to-point DIDComm streaming between mesh nodes using Iroh NodeAddr tickets and Ed25519 transport identities.

Operates in two modes: 1. Pure Python In-Process Stream Server & Client (zero external C-dependencies):

Standard-library socket streaming with 4-byte big-endian framing over ALPN fleetmesh/didcomm/1, supporting instant bi-directional request/reply and direct peer-to-peer delivery.

  1. Iroh Sidecar Adapter Mode (iroh.sock): When an external Rust iroh daemon is running alongside the node, communicates via local UNIX domain socket to leverage full UDP hole-punching and DERP relay routing across NATs.

fleetmesh_node.transport.iroh_rung.core.sidecar_socket_path(directory)[source]

Derive unix socket path for the iroh sidecar.

Parameters:

directory (str)

Return type:

str

class fleetmesh_node.transport.iroh_rung.core.IrohTransport[source]

Bases: object

Iroh QUIC / stream transport adapter.

Manages ALPN fleetmesh/didcomm/1 listeners and outbound stream dispatch.

scheme: str = 'iroh'
__init__(keystore, peers, host='127.0.0.1', port=0, ticket=None, sidecar_dir=None, clock=None, timeout=5.0, mode='stream')[source]
Parameters:
Return type:

None

property ticket: str

The canonical ticket string for advertising in Kind 11801.

property health: IrohHealthReport

Health status for operator telemetry and health check commands.

start()[source]

Bind server socket and launch stream receiver.

Return type:

IrohTransport

stop()[source]

Shut down listener socket and background threads.

Return type:

None

send(message, to_pubkey, ticket=None, anonymous=False, timeout=None)[source]

Encrypt and dispatch a DIDComm envelope over an Iroh stream.

Returns { ‘iroh’: (True, ‘delivered via iroh quic stream’) }.

Parameters:
Return type:

dict[str, tuple[bool, str]]

request(message, to_pubkey, ticket=None, timeout=15.0, anonymous=False)[source]

Send a message and wait on the threaded response queue.

Parameters:
Return type:

Inbound | None

listen(thid)[source]

Route messages matching thread id to a dedicated queue.

Parameters:

thid (str)

Return type:

Queue[Inbound]

unlisten(thid)[source]

Deregister thread listener queue.

Parameters:

thid (str)

Return type:

None

receive(timeout=None)[source]

Fetch the next delivered message from the inbox.

Parameters:

timeout (float | None)

Return type:

Inbound | None

4.7. FIPS Transport Rung

Experimental

In the code and tested, but not supported in this alpha: it may change or go away. See Experimental features.

FIPS Native Datagram API Transport Client for Fleetmesh.

Spec reference: docs/fips-native-transport.md. Connects to the FIPS v0.5.1 native API socket (/var/run/fips/api.sock, ~/.fips/api.sock, …), requests FSP service flows and listener descriptors via SCM_RIGHTS, and exchanges binary-framed datagrams addressed to peer npub identities without requiring TUN/IPv6 adapters or root privileges.

fleetmesh_node.transport.fips_rung.core.find_api_socket()[source]

Find first existing and accessible FIPS Native API socket path, or None.

Return type:

str | None

exception fleetmesh_node.transport.fips_rung.core.FipsTransportError[source]

Bases: Exception

Raised when FIPS control or flow operations fail.

fleetmesh_node.transport.fips_rung.core.encode_frame(seq, payload, is_final=False, is_didcomm=True, compressed=False, ack_requested=False, flags=None, reserved=0)[source]

Pack payload with 8-byte binary framing header.

reserved carries the message id used to reassemble fragmented messages.

Parameters:
Return type:

bytes

fleetmesh_node.transport.fips_rung.core.decode_frame_ex(data)[source]

Like decode_frame but also returns the message id: (seq, flags, msg_id, payload).

Parameters:

data (bytes)

Return type:

tuple[int, int, int, bytes]

class fleetmesh_node.transport.fips_rung.core.Reassembler[source]

Bases: object

Rebuild messages split by FipsNativeTransport.send_message on one flow.

Frames with message id 0 are legacy single-frame messages and pass through. Frames arrive in order on a FIPS flow but may be lost. A message is delivered only when fragments 0..N arrive contiguously for one message id and fragment N has FLAG_FINAL; any gap discards the partial message.

__init__(timeout_s=30.0, max_fragments=64, clock=<built-in function monotonic>)[source]
Parameters:
Return type:

None

feed(seq, flags, msg_id, payload)[source]

Feed one frame; returns (flags, full_payload) when a message completes.

Parameters:
Return type:

tuple[int, bytes] | None

fleetmesh_node.transport.fips_rung.core.decode_frame(data)[source]

Unpack 8-byte binary framing header.

Returns:

(seq, flags, payload)

Parameters:

data (bytes)

Return type:

tuple[int, int, bytes]

fleetmesh_node.transport.fips_rung.core.pubkey_to_npub(pubkey)[source]

Normalize a pubkey (hex, did:nostr:, or npub) to standard npub format.

Takes object because config and CLI hand it whatever they parsed; a non-string is stringified rather than refused, as before.

Parameters:

pubkey (object)

Return type:

str

class fleetmesh_node.transport.fips_rung.core.FipsNativeTransport[source]

Bases: object

Manages bilateral datagram flows over FIPS Native Control API.

__init__(sock_path=None, node_pk=None)[source]
Parameters:
  • sock_path (str | None)

  • node_pk (str | None)

Return type:

None

is_available()[source]

Check if local FIPS control socket exists and is accessible.

Return type:

bool

connect()[source]

Connect to local FIPS Unix control socket.

Return type:

None

open_flow(peer_npub, port, timeout_s=5.0)[source]

Request connected FSP datagram flow descriptor from FIPS via SCM_RIGHTS.

Parameters:
Return type:

socket

listen_port(port, timeout_s=5.0)[source]

Register inbound listener on FSP port, receiving descriptor via SCM_RIGHTS.

Parameters:
Return type:

socket

accept_flow(listener_sock, timeout_s=5.0)[source]

Accept an incoming flow on a registered listener socket.

In FIPS v0.5.1, when a remote peer initiates a flow to a listening port, the listener descriptor receives an arrival notice datagram with SCM_RIGHTS carrying the new connected flow datagram socket.

Returns:

(flow_socket, arrival_info_dict)

Parameters:
Return type:

tuple[socket, FipsArrivalInfo]

accept_listener_event(listener_sock)[source]

Receive the next incoming event on a registered listener socket.

Returns:

(flow_sock, arrival_info, direct_msg) If an incoming flow arrived via SCM_RIGHTS: returns (flow_sock, arrival_info, b””) If a direct binary frame arrived: returns (None, {}, direct_msg) If empty/timeout: returns (None, {}, b””)

Parameters:

listener_sock (socket)

Return type:

tuple[socket | None, Mapping[str, Any], bytes]

max_payload_for(flow_sock)[source]

Largest datagram (header included) this flow will carry.

Parameters:

flow_sock (socket)

Return type:

int

send_message(flow_sock, payload, flags=0, max_fragments=64)[source]

Send one logical message, fragmenting it to fit the flow’s max_payload.

Every frame carries the same message id in the header’s reserved byte and a per-message fragment index in seq; the last frame sets FLAG_FINAL. Raises FipsTransportError before sending anything if the message would need more than max_fragments frames, so callers can fall back to a transport without a datagram ceiling. Returns the number of frames sent.

Parameters:
Return type:

int

send_framed(flow_sock, payload, seq=0, is_final=False, flags=None)[source]

Transmit binary-framed datagram over open flow socket.

Parameters:
Return type:

int

recv_framed(flow_sock, timeout_s=5.0)[source]

Receive and decode framed datagram. Returns (seq, is_final, payload_bytes).

Parameters:
Return type:

tuple[int, bool, bytes]

recv_raw_frame(flow_sock, timeout_s=5.0)[source]

Receive and decode raw frame with exact integer bitflags. Returns (seq, flags, payload_bytes).

Parameters:
Return type:

tuple[int, int, bytes]

close()[source]

Close all open flows, listeners, and control connection.

Return type:

None

4.8. mDNS Local Discovery

Enough of RFC 6762 and RFC 6763 for a node to find another on its own link.

Standard library only, like ws.py and for the same reason: this is the one discovery path that must work when there is no relay, no DNS and no internet, so it cannot be the path that needs a package index to install.

What is here is the DNS-SD subset a service advertisement uses and nothing else: PTR, SRV, TXT and A, a query for one service type, and the records that answer it. Name compression is decoded because other responders emit it, and never written, because a service advertisement is small and a pointer saves nothing worth the code.

The wire is the ordinary DNS message format on multicast. What makes it mDNS rather than DNS is where it goes - 224.0.0.251:5353, TTL 255, joined by every participant - and that an answer may arrive unsolicited, which is how a node that has just started announces itself to a link that never asked.

None of this authenticates anything and it is not supposed to. A TXT record is a routing hint: anyone on the link can claim any key. What proves a node is the descriptor fetched afterwards from the address the hint gave, which is signed. lan.py is where that happens.

exception fleetmesh_node.transport.mdns.MdnsError[source]

Bases: ValueError

fleetmesh_node.transport.mdns.encode_name(name)[source]

A dotted name as length-prefixed labels, terminated by a zero byte.

Parameters:

name (str)

Return type:

bytes

fleetmesh_node.transport.mdns.decode_name(buf, off)[source]

(name, offset after it). Follows compression pointers, and refuses a loop: a pointer must always point strictly backwards, so a packet that points forward or to itself is malformed rather than an infinite read.

Parameters:
Return type:

tuple[str, int]

class fleetmesh_node.transport.mdns.Record[source]

Bases: object

__init__(name, rtype, data, ttl=120)[source]
Parameters:
Return type:

None

name
rtype
ttl
data
fleetmesh_node.transport.mdns.encode_txt(pairs)[source]

DNS-SD TXT: one length-prefixed key=value string per entry, sorted so the same map always encodes to the same bytes.

Parameters:

pairs (dict[str, str])

Return type:

bytes

fleetmesh_node.transport.mdns.decode_txt(raw)[source]
Parameters:

raw (bytes)

Return type:

dict[str, str]

fleetmesh_node.transport.mdns.build(questions=None, answers=None, additionals=None, flush=True)[source]

One mDNS message. A message with answers is a response (QR set); one with only questions is a query. The id is zero: mDNS matches on content, never on a transaction id, because an answer may be unsolicited.

Parameters:
Return type:

bytes

class fleetmesh_node.transport.mdns.Message[source]

Bases: object

__init__(questions, answers, is_response)[source]
Parameters:
Return type:

None

questions
answers
is_response
fleetmesh_node.transport.mdns.parse(buf)[source]

A message, with every record this speaks decoded and the rest skipped.

A packet from the link is whatever anyone put on it, so every length is checked against the buffer before it is used and an unknown type is walked over by its own length rather than guessed at.

Parameters:

buf (bytes)

Return type:

Message

fleetmesh_node.transport.mdns.open_socket(bind_group=True)[source]

A socket on the mDNS group, shareable with every other responder here.

SO_REUSEPORT as well as SO_REUSEADDR, because two nodes on one machine is the arrangement this project already runs - lon1 has carried two since 2026-09-04 - and without it the second one cannot bind and the pair is invisible to each other and to everyone else.

Parameters:

bind_group (bool)

Return type:

socket

fleetmesh_node.transport.mdns.send(sock, packet)[source]

Put one packet on the group. Raises OSError if the link refuses it.

It used to swallow that, on the grounds that no route to the group is not this node’s fault. True, and the wrong layer to decide it: a joined socket is not a link that forwards, and a host with no route for 224.0.0.0/4 or a network that filters multicast - which is what a cloud private network usually is - refuses the send itself. Swallowed here, such a node advertised nothing, said nothing about it, and reported itself as advertising. This layer says what happened; Lan._say decides what it means and puts it where an operator reads it.

Parameters:
Return type:

None

fleetmesh_node.transport.mdns.receive(sock)[source]

Every message readable right now, with the address it came from.

Parameters:

sock (socket)

Return type:

Iterator[tuple[Message, str]]

fleetmesh_node.transport.mdns.local_address()[source]

This machine’s address on the interface that reaches the link.

Asked of a disconnected UDP socket, which chooses a route without sending anything: there is nothing to reach on a dead network, and this still answers because the kernel already knows which interface it would use.

Return type:

str | None

4.9. DNS TXT Resolution

A minimal DNS TXT lookup, because the standard library has none.

The nsite gateway binds a custom domain to a site through a TXT record at _nsite.<domain>. socket can resolve A/AAAA, not TXT, and pulling in a DNS library for one record type is not worth a dependency: this is a single UDP query (RFC 1035, with the RFC 1123 TCP fallback when the answer is truncated), to the resolvers /etc/resolv.conf names, following CNAMEs in the answer section.

Returned strings are the TXT character-strings of one record joined, one entry per record, decoded as UTF-8 with errors replaced. The caller decides what a value means.

exception fleetmesh_node.transport.dnstxt.DnsError[source]

Bases: Exception

The lookup could not be completed (network, malformed answer).

fleetmesh_node.transport.dnstxt.system_nameservers(path='/etc/resolv.conf')[source]
Parameters:

path (str)

Return type:

list[str]

fleetmesh_node.transport.dnstxt.lookup_txt(name, servers=None, timeout=3.0)[source]

TXT records at name. Empty list = the name has none (incl. NXDOMAIN). Raises DnsError when no resolver answered usably.

Parameters:
Return type:

list[str]

4.10. DIDComm Inbound Handler

Opening an inbound DIDComm envelope: one place, every transport.

Four paths carry a JWE into this node - a gift wrap off a relay, an iroh stream, an iroh QUIC stream, and a FIPS native flow - and until this module each of them opened the envelope its own way. Three of the four were wrong in the same direction: they took the plaintext’s from as the sender’s name without anything that proved it. A frame that was never encrypted, written by anyone who could reach the socket, arrived as a message from whoever it named, and on two of the paths it arrived marked authenticated. The transport that got it right was the relay one, which is the oldest, and its rule is the rule here: the names must agree, and a name nobody proved is not a name.

What proves a sender is the ECDH-1PU agreement. didcomm.decrypt only succeeds under authcrypt if the static key skid names took part in the key agreement, so a decrypted authcrypt message was written by the holder of that key. The plaintext’s from is then required to name the same node, and on the relay path the seal’s signer too. Anoncrypt has no skid and therefore no sender: the message is delivered with authenticated=False and its from is recorded as a claim, which is what first contact is.

Anything that is not a JWE is refused. There is no plaintext path, not for discovery and not for ping: a transport that wants an unauthenticated protocol runs it beside DIDComm, not inside the queue that request() waits on. The reason strings are the ones fleetmesh_node/transport/ has always recorded, so an operator who learned to read dropped reads the same words from every rung.

Replay. A JWE is a fixed string of bytes, and a direct rung (fips flow, iroh stream, libp2p stream) carries it as-is: anyone who captured one can write it to the socket again, and the agreement proves exactly what it proved the first time - the holder of the key wrote this message, once. The relay rung has always deduplicated by wrap id; the direct rungs had nothing. So each direct rung holds an InboundGuard and hands it to open_inbound, which refuses a message id it has already opened and a created_time outside the skew window the schema tolerates. A message with no created_time is still accepted (the id check alone covers it); the gift-wrap rung passes no guard because a stored wrap is legitimately delivered days late and the wrap id is already its replay key.

class fleetmesh_node.transport.didcomm_inbound.InboundGuard[source]

Bases: object

Per-rung replay and freshness state: a bounded id-LRU and a clock window.

One per transport instance (never module-level: two nodes in one process must not share what they have seen). refused counts by reason so an operator can tell a replaying peer from a drifting clock.

__init__(window=60, capacity=4096)[source]
Parameters:
Return type:

None

stale(created_time, now)[source]

None if created_time is absent or inside the window, else why not.

Parameters:
  • created_time (Any)

  • now (int)

Return type:

str | None

first_time(message_id)[source]

True and remembered if this id is new; False if it has been opened before.

Parameters:

message_id (str)

Return type:

bool

class fleetmesh_node.transport.didcomm_inbound.Inbound[source]

Bases: object

One delivered message: the plaintext, who sent it, and how it was sealed.

__init__(message, sender_pk, authenticated, wrap_id, sealed=False, wrap_kind=None)[source]
Parameters:
Return type:

None

property thid: str | None
fleetmesh_node.transport.didcomm_inbound.foreign(payload)[source]

Why a decrypted payload is not one of ours, in a few words.

A protocol that shares kind 21059 says whose message it is the same way DIDComm does, in a type, so that is what is named when there is one and it is the counted half of the reason. Nothing else about the payload is reported: it decrypted under this node’s key, so it may be somebody’s private traffic that merely arrived at the wrong daemon.

Parameters:

payload (Any)

Return type:

str

fleetmesh_node.transport.didcomm_inbound.is_jwe(payload)[source]

The shape didcomm.decrypt will look at. Anything else is not tried.

Parameters:

payload (Any)

Return type:

bool

fleetmesh_node.transport.didcomm_inbound.open_inbound(payload, keystore, peers, wrap_id, seal_pk=None, guard=None, now=None)[source]

Open one inbound envelope. Returns (Inbound, None) or (None, reason).

payload: the bytes off the wire, or the object a transport already parsed (the relay path parses before it can tell a fragment from a whole). seal_pk: on the relay path, the key that signed the seal, which every other name must then equal. Transports without a seal pass None and the agreement between skid and from is what is checked. guard: a direct rung’s InboundGuard. When given, a message id already opened through it is refused as a replay, and a created_time outside the guard’s window of now (the rung’s clock; time.time() if None) is refused as stale. The relay rung passes none: its wrap id is the key.

Exactly one of the pair is None, so a caller writes

inbound, why = open_inbound(…) if inbound is None: self._drop(why, wrap_id); return

and the reason it records is the same on every rung.

Parameters:
Return type:

tuple[Inbound | None, str | None]

4.11. Pluggable Protocol Host

ProtocolHostRouter: Unified multiplexer for HTTP and WebSocket protocol suites.

Standard library and ws.py only. Multiplexes foreign and native protocol suites (Nostr, ATProto, ActivityPub, Blossom CAS, Prometheus metrics) over a single public edge port (e.g. 8000 or 443 with TLS).

class fleetmesh_node.transport.host.HttpRoute[source]

Bases: object

HttpRoute(prefix: ‘str’, handler: ‘Callable[[socket.socket, ws.PlainHTTP], Any]’, methods: ‘tuple[str, …]’, owner: ‘str’ = ‘’)

prefix: str
handler: Callable[[socket, PlainHTTP], Any]
methods: tuple[str, ...]
owner: str = ''
__init__(prefix, handler, methods, owner='')
Parameters:
Return type:

None

class fleetmesh_node.transport.host.WebSocketRoute[source]

Bases: object

WebSocketRoute(path: ‘str’, handler: ‘Callable[[ws.WebSocket, str], Any]’, owner: ‘str’ = ‘’)

path: str
handler: Callable[[WebSocket, str], Any]
owner: str = ''
__init__(path, handler, owner='')
Parameters:
Return type:

None

class fleetmesh_node.transport.host.ProtocolHost[source]

Bases: object

Unified HTTP & WebSocket multiplexer mounted on the node’s public port.

__init__(host='127.0.0.1', port=0, name='meshnode', clock=None, bind_wait=10.0, max_body_bytes=16777216)[source]
Parameters:
Return type:

None

host: str
port: int
name: str
clock: Callable[[], int]
bind_wait: float
max_body_bytes: int
property url: str
property http_url: str
mount_route(prefix, handler, methods=('GET',), owner='')[source]

Mount an HTTP path prefix handler.

Longest prefix matches take precedence. Handler receives (conn, req: ws.PlainHTTP) and returns True if handled, or False to fall through.

Parameters:
Return type:

None

mount_websocket(path, handler, owner='')[source]

Mount a WebSocket handler for an exact path or prefix.

Parameters:
Return type:

None

unmount_all(owner)[source]

Remove all HTTP and WebSocket routes registered by owner.

Parameters:

owner (str)

Return type:

None

register_route(method, prefix, handler, owner='')[source]

Alias for mount_route for compatibility.

Parameters:
Return type:

None

register_websocket(path, handler, owner='')[source]

Alias for mount_websocket for compatibility.

Parameters:
Return type:

None

unregister_owner(owner)[source]

Alias for unmount_all for compatibility.

Parameters:

owner (str)

Return type:

None

start()[source]
Return type:

ProtocolHost

property server: Any | None

Underlying ws.Server instance, preserving socket address metadata even after stop.

stop()[source]
Return type:

None

health()[source]
Return type:

ProtocolHealth