6. Pluggable Protocol Packages (fleetmesh_node.protocols)

The fleetmesh_node.protocols package provides a modular runtime architecture enabling Fleetmesh nodes to speak multiple decentralized protocol dialects without monolithic coupling.

Every protocol suite implements the fleetmesh_core.wire.interfaces.ProtocolPackage contract, decoupling protocol-specific ingress, storage adapters, transport rungs, and identity models from the meshnode host daemon.

6.1. Protocol Lifecycle & Extension Points

A protocol package exposes the following capabilities to the node host:

  1. Declarative Configuration: Activated via the protocol_suites block in config.json. A disabled protocol consumes zero ports, zero threads, and zero storage.

  2. Ingress Mounting: Mounts HTTP and WebSocket routes onto fleetmesh_node.transport.host.ProtocolHost via longest-prefix path matching.

  3. Transport Ladder Rung: Contributes an outbound delivery rung to fleetmesh_node.transport.router.TransportRouter.

  4. Storage Adapter: Attaches native event, CAS blob, or append-only log databases.

  5. Identity Adapter: Translates Fleetmesh node keys (secp256k1, X25519, Ed25519) into native author identities.

  6. Descriptor Capabilities: Advertises native capabilities (e.g. ["c", "p2panda"], ["c", "rhio"]) on the node’s signed descriptor.

Protocol Suite

Standards

Transport Rank

Primary Features

p2panda

p2panda-v0.4.0

15 (Log Chain)

Append-only operation logs, canonical CBOR encoding, Ed25519 signatures, HTTP/CBOR ingress.

rhio

rhio-nats-v1, bao-tree-hash

12 (Cluster Sync)

Micro-datacenter cluster replication, Bao Merkle tree CAS storage, NATS JetStream sidecar bridge, MinIO/S3 sync.

nostr

NIP-01..77, BUD-01..04

30 (Relay Fallback)

Embedded relay server, event persistence, Blossom media storage, peer table synchronization.

atproto

ATProto v1, MST

20 (XRPC)

XRPC HTTP endpoints, Merkle Search Trees, DID resolution (did:plc, did:web), repo subscriptions.

activitypub

W3C ActivityPub, LD-Signatures

25 (Fediverse)

Actor model, WebFinger discovery, ActivityStreams 2.0 JSON-LD, HTTP Signatures.

ssb

SSB SHS, Box Stream

18 (P2P Log)

Secret Handshake (SHS), MuxRPC over TCP, append-only feed validation.

6.2. Package Registry & Manager

Pluggable protocol suites and package registry for Fleetmesh node.

Manages dynamic discovery, configuration, lifecycle, and multiplexing across all supported open protocol families: - Nostr & Blossom (fleetmesh-protocol-nostr) - AT Protocol (fleetmesh-protocol-atproto) - ActivityPub & ActivityStreams 2.0 (fleetmesh-protocol-activitypub) - Secure Scuttlebutt (fleetmesh-protocol-ssb) - p2panda (fleetmesh-protocol-p2panda) - Rhio (fleetmesh-protocol-rhio)

fleetmesh_node.protocols.register_protocol(name, package_cls)[source]

Register a custom or third-party protocol package class.

Parameters:
Return type:

None

fleetmesh_node.protocols.get_available_protocols()[source]

Return all currently registered protocol names.

Return type:

tuple[str, …]

fleetmesh_node.protocols.load_protocol_package_class(name)[source]

Dynamically load and return the ProtocolPackage class for a given name.

Parameters:

name (str)

Return type:

type[ProtocolPackage]

fleetmesh_node.protocols.create_protocol_package(name, **kwargs)[source]

Instantiate a protocol package by name with provided arguments.

Parameters:

name (str)

Return type:

ProtocolPackage

class fleetmesh_node.protocols.ProtocolManager[source]

Bases: object

Orchestrates configuration, lifecycle, and routing across all protocol packages.

__init__(node_dir=None, keystore=None, clock=None, name='meshnode')[source]
Parameters:
property packages: Mapping[str, ProtocolPackage]
get_package(name)[source]
Parameters:

name (str)

Return type:

ProtocolPackage | None

load_suites_config(suites_config, backend_store=None, blob_store=None, grants=None, node_instance=None, private_key=None, strain_ledger=None)[source]

Initialize protocol packages based on ProtocolSuitesConfig or mapping.

Parameters:
  • suites_config (Any)

  • backend_store (Any | None)

  • blob_store (Any | None)

  • grants (Any | None)

  • node_instance (Any | None)

  • private_key (Any | None)

  • strain_ledger (Any | None)

Return type:

dict[str, ProtocolPackage]

mount_ingress(host)[source]

Mount all active protocol packages onto the shared host multiplexer.

Parameters:

host (ProtocolHostRouter)

Return type:

None

mount_transport_rungs(router)[source]

Mount outbound rungs into TransportRouter ladder.

Parameters:

router (Any)

Return type:

list[Any]

start_all()[source]

Start all configured protocol packages.

Return type:

None

stop_all()[source]

Stop all configured protocol packages and unmount ingress.

Return type:

None

health()[source]

Collect health telemetry across all loaded protocol packages.

Return type:

dict[str, ProtocolHealth]

descriptor_capabilities()[source]

Aggregate descriptor capabilities from all active packages.

Return type:

tuple[tuple[str, str], …]

6.3. p2panda Protocol Suite (fleetmesh_node.protocols.p2panda)

Experimental

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

The p2panda package integrates the p2panda peer-to-peer protocol into Fleetmesh:

fleetmesh-protocol-p2panda: p2panda protocol package for Fleetmesh.

Conforms to ProtocolPackage (fleetmesh_core.wire.interfaces.ProtocolPackage). Mounts p2panda operation log ingress onto ProtocolHostRouter, provides P2PandaRung for TransportRouter ladder, and manages append-only SQLite persistence.

class fleetmesh_node.protocols.p2panda.package.P2PandaProtocolPackage[source]

Bases: BaseProtocolPackage

The p2panda protocol suite for Fleetmesh.

name: str = 'p2panda'
version: str = '0.4.0'
standards: tuple[str, ...] = ('p2panda-v0.4.0', 'cbor-rfc8949', 'ed25519-chain')
__init__(node_dir=None, keystore=None, blob_store=None, store=None, **kwargs)[source]
Parameters:
Return type:

None

configure(config)[source]
Parameters:

config (Mapping[str, Any])

Return type:

None

identity_adapter(keystore)[source]
Parameters:

keystore (Any)

Return type:

ProtocolIdentityAdapter | None

mount_ingress(host)[source]
Parameters:

host (ProtocolHostRouter)

Return type:

None

transport_rung(context)[source]
Parameters:

context (Any)

Return type:

Any | None

compartments()[source]
Return type:

tuple[type[Any], …]

start()[source]
Return type:

None

stop()[source]

Close any attached protocol store when stopping the package.

Return type:

None

health()[source]
Return type:

ProtocolHealth

descriptor_capabilities()[source]
Return type:

tuple[tuple[str, str], …]

p2panda SQLite persistent operation log store.

Standard library only. Manages persistence and chain verification for: - Append-only cryptographic operation logs. - Monotonic sequence numbers and backlink verification. - Author log indexing and query pagination.

exception fleetmesh_node.protocols.p2panda.store.P2PandaStoreError[source]

Bases: FleetmeshError

Base error for p2panda storage operations.

class fleetmesh_node.protocols.p2panda.store.P2PandaLogStore[source]

Bases: BaseSqliteStore

Append-only p2panda operation logs, one row per operation.

A SqliteStore rather than a hand-rolled connection: the base owns the connection, the lock, the per-store schema version, transaction control and the dialect that rewrites placeholders and upserts for another backend. This store opened its own connection per call and declared its schema as a SQL string, so it was SQLite-only and invisible to the locator - see docs/storage-backends.md.

SCHEMA: tuple[Any, ...] = (Table(name='p2panda_operations', columns=(Column(name='op_id', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='author', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='seq_num', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='backlink', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='previous_seq_num', type='INTEGER', nullable=True, primary_key=False, default=None, unique=False), Column(name='payload_size', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='payload_hash', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='timestamp', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='signature', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='version', type='INTEGER', nullable=False, primary_key=False, default='1', unique=False), Column(name='body', type='BLOB', nullable=True, primary_key=False, default=None, unique=False), Column(name='extensions_json', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='created_at', type='TEXT', nullable=False, primary_key=False, default=None, unique=False)), primary_key=(), indices=(Index(name='idx_p2p_ops_author_seq', columns=('author', 'seq_num'), table='p2panda_operations', unique=True), Index(name='idx_p2p_ops_backlink', columns=('backlink',), table='p2panda_operations', unique=False)), without_rowid=False),)
__init__(db_path=':memory:')[source]
Parameters:

db_path (str)

append_operation(op, verify_chain=True)[source]

Append an operation to the author’s log.

Validates cryptographic integrity and chain monotonicity if verify_chain is True. Returns True if newly inserted, False if idempotent duplicate.

Parameters:
Return type:

bool

get_operation(op_id)[source]

Fetch an operation by its op_id.

Parameters:

op_id (str)

Return type:

P2PandaOperation | None

get_operation_by_seq(author, seq_num)[source]

Fetch an operation by author public key and sequence number.

Parameters:
Return type:

P2PandaOperation | None

get_latest_operation(author)[source]

Fetch the latest operation in an author’s log.

Parameters:

author (str)

Return type:

P2PandaOperation | None

get_latest_seq(author)[source]

Return the highest seq_num for author, or -1 if no operations exist.

Parameters:

author (str)

Return type:

int

get_log(author, from_seq=0, limit=100)[source]

Return ordered operations for an author from from_seq onwards.

Parameters:
Return type:

list[P2PandaOperation]

count_operations()[source]

Return total count of operations across all authors.

Return type:

int

list_authors()[source]

Return a sorted list of unique authors with operations in store.

Return type:

list[str]

close()[source]

Safely close the underlying database connection.

Return type:

None

p2panda identity adapter for Fleetmesh.

Maps the node’s Ed25519 transport key to a p2panda author identity. Conforms to ProtocolIdentityAdapter (fleetmesh_core.wire.interfaces).

class fleetmesh_node.protocols.p2panda.identity.P2PandaIdentityAdapter[source]

Bases: Ed25519IdentityAdapter

Translates between Fleetmesh keys and p2panda author identities.

uri_prefixes: tuple[str, ...] = ('p2panda:', 'panda:')

p2panda transport rung for TransportRouter ladder.

Standard library only. Delivers messages wrapped as append-only p2panda operations to local log and sync peers.

class fleetmesh_node.protocols.p2panda.rung.P2PandaRung[source]

Bases: Rung

Outbound transport rung delivering through p2panda append-only operation chains.

name: str = 'p2panda'
rank: int = 15
__init__(store=None, identity=None, enabled=True, clock=None, allow_local_peers=False)[source]
Parameters:
Return type:

None

available()[source]

The local side of this rung is up and an identity is configured.

Return type:

bool

target_of(desc, theirs)[source]

Where this rung would reach the peer that published desc.

Parameters:
Return type:

str | None

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

Deliver message by signing and appending a p2panda operation to the log.

Parameters:
Return type:

dict[str, tuple[bool, str]]

health()[source]
Return type:

Mapping[str, Any] | None

fault_log()[source]
Return type:

FaultLog | None

6.4. Rhio Protocol Suite (fleetmesh_node.protocols.rhio)

Experimental

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

The rhio package integrates HIRO MicroDataCenters Rhio cluster synchronization:

fleetmesh-protocol-rhio: Rhio cluster sync protocol package for Fleetmesh.

Conforms to ProtocolPackage (fleetmesh_core.wire.interfaces.ProtocolPackage). Mounts Rhio cluster blob sync, NATS JetStream bridge, and Bao tree verification onto ProtocolHostRouter and provides RhioRung for the TransportRouter ladder.

class fleetmesh_node.protocols.rhio.package.RhioProtocolPackage[source]

Bases: BaseProtocolPackage

The Rhio cluster synchronization suite for Fleetmesh.

name: str = 'rhio'
version: str = '0.1.0'
standards: tuple[str, ...] = ('rhio-nats-v1', 'p2panda-v0.4.0', 'bao-tree-hash')
__init__(node_dir=None, keystore=None, blob_store=None, store=None, sidecar_client=None, auto_start_sidecar=False, **kwargs)[source]
Parameters:
  • node_dir (str | None)

  • keystore (Any | None)

  • blob_store (Any | None)

  • store (RhioBlobSync | None)

  • sidecar_client (Any | None)

  • auto_start_sidecar (bool)

  • kwargs (Any)

Return type:

None

configure(config)[source]
Parameters:

config (Mapping[str, Any])

Return type:

None

identity_adapter(keystore)[source]
Parameters:

keystore (Any)

Return type:

ProtocolIdentityAdapter | None

mount_ingress(host)[source]
Parameters:

host (ProtocolHostRouter)

Return type:

None

transport_rung(context)[source]
Parameters:

context (Any)

Return type:

Any | None

compartments()[source]
Return type:

tuple[type[Any], …]

start()[source]
Return type:

None

stop()[source]

Close any attached protocol store when stopping the package.

Return type:

None

health()[source]
Return type:

ProtocolHealth

descriptor_capabilities()[source]
Return type:

tuple[tuple[str, str], …]

Rhio blob storage and Bao-compatible chunked tree hashing.

Standard library only. Provides: - Bao chunked Merkle tree verification (1024-byte chunks). - Local CAS blob repository and SQLite synchronization metadata. - S3 / MinIO synchronization state tracking.

exception fleetmesh_node.protocols.rhio.store.FiberAccessError[source]

Bases: Exception

An HTTP-mappable refusal (status, machine-readable error) for fiber operations.

__init__(status, error)[source]
Parameters:
Return type:

None

class fleetmesh_node.protocols.rhio.store.RhioBaoTree[source]

Bases: object

Bao-compatible hierarchical chunked Merkle tree hashing.

CHUNK_SIZE: int = 1024
SUBTREE_POW: int = 13
SEGMENT_SIZE: int = 8388608
classmethod leaf_count(size_bytes, chunk_size=1024)[source]

Return the number of chunk_size-byte leaves for size_bytes (minimum 1).

Parameters:
  • size_bytes (int)

  • chunk_size (int)

Return type:

int

classmethod compute_root(data, chunk_size=1024)[source]

Compute the Bao-compatible Merkle root hex digest.

Parameters:
Return type:

str

classmethod compute_tree(data, chunk_size=1024)[source]

Compute Merkle tree root and leaf hashes for data (fleetmesh_core.textile.bao).

Parameters:
Return type:

tuple[str, list[bytes]]

classmethod promote_segment_root(segment_root_hex, segment_size, *, is_single_segment, chunk_size=1024, subtree_pow=13)[source]

Promote a standalone segment Bao root to its Level-subtree_pow subtree root.

Parameters:
  • segment_root_hex (str)

  • segment_size (int)

  • is_single_segment (bool)

  • chunk_size (int)

  • subtree_pow (int)

Return type:

str

classmethod combine_segment_roots(segments, *, chunk_size=1024, subtree_pow=13)[source]

Combine (segment_bao_root_hex, segment_byte_size) pairs into the global Bao tree root.

Parameters:
Return type:

str

classmethod compute_file_root(file_path, *, chunk_size=1024, subtree_pow=13, on_segment=None)[source]

Stream file_path in 2^subtree_pow * chunk_size (8 MiB) segments and return (sha256_hex, tree_root_hex, total_size).

Parameters:
Return type:

tuple[str, str, int]

classmethod verify(data, expected_root, chunk_size=1024)[source]

Verify that data produces expected Merkle tree root.

Parameters:
Return type:

bool

class fleetmesh_node.protocols.rhio.store.RhioBlobRecord[source]

Bases: TypedDict

hash: str
size: int
tree_root: str
synced_s3: bool
created_at: str
class fleetmesh_node.protocols.rhio.store.RhioBlobSync[source]

Bases: BaseSqliteStore

Metadata and CAS storage for Rhio cluster blobs.

A SqliteStore rather than a hand-rolled sqlite3.connect: the base owns the connection, the lock, the schema version (per store, not per database - which matters the moment two stores share one server), transaction control and the dialect that rewrites ? and INSERT OR IGNORE for PostgreSQL. This store opened its own connection per call and declared its schema as a SQL string, so it was SQLite-only and invisible to the locator - see docs/storage-backends.md.

SCHEMA: tuple[Any, ...] = (Table(name='rhio_blobs', columns=(Column(name='hash', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='size', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='tree_root', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='synced_s3', type='INTEGER', nullable=False, primary_key=False, default='0', unique=False), Column(name='created_at', type='TEXT', nullable=False, primary_key=False, default=None, unique=False)), primary_key=(), indices=(Index(name='idx_rhio_blobs_tree', columns=('tree_root',), table='rhio_blobs', unique=False),), without_rowid=False), Table(name='rhio_fiber_claims', columns=(Column(name='fiber_root', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='author_key', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='payload_json', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='created_at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=('fiber_root', 'author_key'), indices=(Index(name='idx_rhio_fiber_claims_root', columns=('fiber_root',), table='rhio_fiber_claims', unique=False), Index(name='idx_rhio_fiber_claims_author', columns=('author_key',), table='rhio_fiber_claims', unique=False)), without_rowid=False))
__init__(db_path=':memory:', cas_dir=None, overflow_cas_dirs=None)[source]
Parameters:
evict_errors: int
set_overflow_cas_dirs(dirs)[source]

Configure secondary/overflow CAS directories (e.g. attached block storage volumes).

Parameters:

dirs (Sequence[str])

Return type:

list[str]

get_overflow_cas_dirs()[source]
Return type:

list[str]

store_blob(data, *, sha256_hex=None, tree_root=None, chunk_count=None)[source]

Store blob, computing sha256 hash and Bao tree root if not provided.

Returns (sha256_hash, tree_root, size).

Parameters:
  • data (bytes)

  • sha256_hex (str | None)

  • tree_root (str | None)

  • chunk_count (int | None)

Return type:

tuple[str, str, int]

store_blob_from_file(file_path, *, sha256_hex=None, tree_root=None, size=None, move=False, chunk_count=None, on_segment=None)[source]

Store a file-backed blob into CAS without loading the full file into memory.

Parameters:
Return type:

tuple[str, str, int]

get_blob_path(blob_hash)[source]

Return the filesystem path of a stored CAS blob if backed by cas_dir, _overflow_cas_dirs, or an external file.

Parameters:

blob_hash (str)

Return type:

str | None

has_local_blob(blob_hash)[source]

Return True if the raw bytes for blob_hash are currently present on local/overflow disk or in memory.

Parameters:

blob_hash (str)

Return type:

bool

migrate_blob_to_overflow(blob_hash, target_dir=None)[source]

Move blob_hash from primary _cas_dir to an overflow CAS volume and return the new path.

Parameters:
  • blob_hash (str)

  • target_dir (str | None)

Return type:

str | None

evict_local_file(blob_hash, *, include_overflow=False)[source]

Evict the local file for blob_hash to free disk space while preserving its rhio_blobs metadata row.

Parameters:
  • blob_hash (str)

  • include_overflow (bool)

Return type:

int

get_blob(blob_hash)[source]

Retrieve blob bytes by sha256 hash.

Parameters:

blob_hash (str)

Return type:

bytes | None

get_blob_meta(blob_hash)[source]

Retrieve stored metadata (hash, size, tree_root, synced_s3, created_at) without reading the blob.

Parameters:

blob_hash (str)

Return type:

RhioBlobRecord | None

get_blob_slice(blob_hash, start, length)[source]

Read a byte range [start : start + length] directly from CAS disk without loading the full blob into RAM.

Parameters:
Return type:

bytes | None

get_blob_meta_by_root(tree_root)[source]

Retrieve stored blob metadata by its 1,024-byte-leaf Bao tree_root.

Parameters:

tree_root (str)

Return type:

RhioBlobRecord | None

get_blob_path_by_root(tree_root)[source]

Return the CAS filesystem path for the blob matching tree_root.

Parameters:

tree_root (str)

Return type:

str | None

get_blob_by_root(tree_root)[source]

Retrieve blob bytes by tree_root.

Parameters:

tree_root (str)

Return type:

bytes | None

get_blob_slice_by_root(tree_root, start, length)[source]

Read a byte range [start : start + length] by tree_root without loading the full blob into RAM.

Parameters:
Return type:

bytes | None

delete_blob(blob_hash)[source]

Delete an ephemeral blob from CAS disk/memory and metadata store.

Parameters:

blob_hash (str)

Return type:

bool

has_blob(blob_hash)[source]

Check if blob exists in storage.

Parameters:

blob_hash (str)

Return type:

bool

mark_s3_synced(blob_hash)[source]

Mark blob as synchronized with S3 / MinIO cluster storage.

Parameters:

blob_hash (str)

Return type:

None

count_blobs()[source]
Return type:

int

list_blobs(limit=100)[source]
Parameters:

limit (int)

Return type:

list[RhioBlobRecord]

has_fiber(root)[source]
Parameters:

root (str)

Return type:

bool

readable(root, principal=None)[source]
Parameters:
Return type:

bool

manifest(root, principal=None)[source]
Parameters:
Return type:

dict[str, Any] | None

get(root, principal=None)[source]
Parameters:
Return type:

tuple[bytes, dict[str, Any]] | None

list_own(principal)[source]
Parameters:

principal (Mapping[str, Any] | None)

Return type:

list[dict[str, Any]]

owner_bytes(principal)[source]
Parameters:

principal (Mapping[str, Any] | None)

Return type:

int

interaction_counts(target_strand_id)[source]

Public interaction claims on a strand, by kind (each actor’s like counts once).

Parameters:

target_strand_id (str)

Return type:

dict[str, int]

claim_blob(tree_root, principal, *, sha256_hex='', size=None, kind='binary', mime_type='', visibility='public', target_strand_id='', overwrite_visibility=True, created_at=None)[source]

Register or update an author’s fiber claim on an existing (or metadata-registered) blob.

Parameters:
  • tree_root (str)

  • principal (Mapping[str, Any] | None)

  • sha256_hex (str)

  • size (int | None)

  • kind (str)

  • mime_type (str)

  • visibility (str)

  • target_strand_id (str)

  • overwrite_visibility (bool)

  • created_at (int | None)

Return type:

dict[str, Any] | None

put(raw, principal, *, kind, mime_type='', visibility='vault_only', target_strand_id='', enforce_quota=True)[source]

Store raw (once) in RhioBlobSync and record the caller’s claim on it; returns the caller’s manifest.

Parameters:
Return type:

dict[str, Any]

set_visibility(root, principal, visibility)[source]
Parameters:
Return type:

dict[str, Any]

release(root, principal)[source]

Drop the caller’s claim; the underlying blob is deleted when no claims remain.

Parameters:
Return type:

bool

close()[source]

Safely close the underlying database connection.

Return type:

None

exception fleetmesh_node.protocols.rhio.store.RhioStoreError[source]

Bases: FleetmeshError

Base error for Rhio blob storage and tree hash verification.

fleetmesh_node.protocols.rhio.store.binary_http_response(raw, *, bao_root, sha256_hex, mime_type, public, filename, as_json, json_extra=None)[source]

Serve stored bytes so they can never render as an active page on the app’s origin.

Parameters:
Return type:

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

fleetmesh_node.protocols.rhio.store.handle_fiber_http(store, method, route, query='', body=None, principal=None, *, range_header='')[source]

Route /api/fibers*. principal must come from the server’s own session resolution.

Parameters:
Return type:

tuple[int, Any, str, dict[str, str]] | None

fleetmesh_node.protocols.rhio.store.is_fiber_route(route)[source]
Parameters:

route (str)

Return type:

bool

Rhio cluster transport ladder rung for TransportRouter.

Integrates Rhio NATS JetStream and cluster blob replication into the transport ladder: - Checks sidecar availability over local Unix domain socket (rhio.sock). - Resolves peer Rhio endpoints from node descriptors (scheme ‘rhio’). - Delivers messages to remote cluster peers via NATS JetStream pub/sub.

class fleetmesh_node.protocols.rhio.rung.RhioRung[source]

Bases: Rung

Transport rung delegating outbound deliveries to the Rhio cluster sidecar daemon.

name: str = 'rhio'
rank: int = 12
__init__(router=None, sidecar_client=None, socket_path=None, enabled=True, clock=None)[source]
Parameters:
property faults: FaultLog
fault_log()[source]
Return type:

FaultLog | None

available()[source]

Returns True if the Rhio sidecar socket is reachable and healthy.

Return type:

bool

target_of(desc, theirs)[source]

Extract Rhio endpoint target from descriptor.

Parameters:
Return type:

str | None

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

Attempt delivery of message to target Rhio endpoint via JetStream.

Parameters:
Return type:

dict[str, tuple[bool, str]]

health()[source]
Return type:

Mapping[str, Any] | None

6.5. Nostr Protocol Suite (fleetmesh_node.protocols.nostr)

fleetmesh-protocol-nostr: Decoupled Nostr & Blossom protocol package.

Conforms to ProtocolPackage (fleetmesh_core.wire.interfaces.ProtocolPackage). Wraps RelayServer and BlossomServer, allowing them to be mounted onto ProtocolHostRouter or operated with zero listening overhead when disabled.

class fleetmesh_node.protocols.nostr.package.NostrIdentityAdapter[source]

Bases: object

Identity and assertion adapter for Nostr (secp256k1 / BIP-340).

__init__(keystore)[source]
Parameters:

keystore (Any)

Return type:

None

resolve_id(uri)[source]
Parameters:

uri (str)

Return type:

str | None

sign_assertion(payload)[source]
Parameters:

payload (bytes)

Return type:

bytes

verify_assertion(payload, signature, pubkey)[source]
Parameters:
Return type:

bool

class fleetmesh_node.protocols.nostr.package.NostrProtocolPackage[source]

Bases: object

The Nostr & Blossom protocol suite for Fleetmesh.

name: str = 'nostr'
version: str = '1.0.0'
standards: tuple[str, ...] = ('NIP-01', 'NIP-11', 'NIP-40', 'NIP-42', 'NIP-44', 'NIP-59', 'NIP-77', 'BUD-01', 'BUD-02', 'BUD-04')
__init__(backend=None, blob_store=None, grants=None, node=None, clock=None, name='meshnode', pubkey=None)[source]
Parameters:
  • backend (Any | None)

  • blob_store (Any | None)

  • grants (Any | None)

  • node (Any | None)

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

  • name (str)

  • pubkey (str | None)

Return type:

None

configure(config)[source]
Parameters:

config (Mapping[str, Any])

Return type:

None

identity_adapter(keystore)[source]
Parameters:

keystore (Any)

Return type:

ProtocolIdentityAdapter | None

mount_ingress(host)[source]
Parameters:

host (ProtocolHostRouter)

Return type:

None

transport_rung(context)[source]
Parameters:

context (Any)

Return type:

Any | None

compartments()[source]
Return type:

tuple[type[Any], …]

start()[source]
Return type:

None

stop()[source]
Return type:

None

health()[source]
Return type:

ProtocolHealth

descriptor_capabilities()[source]
Return type:

tuple[tuple[str, str], …]

6.6. AT Protocol Suite (fleetmesh_node.protocols.atproto)

Experimental

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

fleetmesh-protocol-atproto: Decoupled AT Protocol & XRPC package.

Conforms to ProtocolPackage (fleetmesh_core.wire.interfaces.ProtocolPackage). Wraps XRPCRouter, FirehoseBroadcaster, and RepoManager, mounting them onto ProtocolHostRouter with zero external dependencies.

class fleetmesh_node.protocols.atproto.package.AtprotoProtocolPackage[source]

Bases: object

The AT Protocol (atproto) suite for Fleetmesh.

name: str = 'atproto'
version: str = '1.0.0'
standards: tuple[str, ...] = ('com.atproto.sync', 'com.atproto.repo', 'com.atproto.server', 'did:plc', 'did:web', 'dag-cbor', 'mst')
__init__(repo=None, keystore=None, service_domain='node.fleetmesh.local', firehose=None, blob_store=None)[source]
Parameters:
configure(config)[source]
Parameters:

config (Mapping[str, Any])

Return type:

None

identity_adapter(keystore)[source]
Parameters:

keystore (Any)

Return type:

ProtocolIdentityAdapter | None

mount_ingress(host)[source]
Parameters:

host (ProtocolHostRouter)

Return type:

None

transport_rung(context)[source]
Parameters:

context (Any)

Return type:

Any | None

compartments()[source]
Return type:

tuple[type[Any], …]

start()[source]
Return type:

None

stop()[source]
Return type:

None

health()[source]
Return type:

ProtocolHealth

descriptor_capabilities()[source]
Return type:

tuple[tuple[str, str], …]

AT Protocol Repository implementation.

Standard library only. Manages: - Commit chain (version 3) signed with secp256k1 ECDSA. - Monotonic Timestamp Identifiers (TID) per ATProto specification. - Merkle Search Tree (MST) record index. - CAR v1 archive export and import. - Content-addressed blob storage unified with Blossom BlobStore.

exception fleetmesh_node.protocols.atproto.repo.RepoError[source]

Bases: FleetmeshError

Base error for ATProto repository operations.

fleetmesh_node.protocols.atproto.repo.tid_now()[source]

Generate a monotonic 13-character Crockford Base32 TID.

Return type:

str

class fleetmesh_node.protocols.atproto.repo.Repo[source]

Bases: object

An ATProto account repository.

__init__(did, signing_key_hex=None, blockstore=None, blob_store=None)[source]
Parameters:
classmethod create(did, signing_key_hex, blockstore=None, blob_store=None)[source]

Initialize a new, empty repository with an initial genesis commit.

Parameters:
Return type:

Repo

put_record(collection, record, rkey=None)[source]

Insert or update a record in this repository.

Returns (rkey, record_cid, new_commit_cid).

Parameters:
Return type:

tuple[str, CIDLink, CIDLink]

get_record(collection, rkey)[source]

Fetch a record from the repository by collection and rkey.

Parameters:
Return type:

tuple[CIDLink, Mapping[str, Any]] | None

delete_record(collection, rkey)[source]

Remove a record and commit the updated MST. Returns new commit CID.

Parameters:
Return type:

CIDLink

list_records(collection='')[source]

List all records in the repository, optionally filtered by collection.

Returns list of (collection, rkey, cid, record_dict).

Parameters:

collection (str)

Return type:

list[tuple[str, str, CIDLink, Mapping[str, Any]]]

put_blob(data, mime_type='application/octet-stream')[source]

Store a binary blob, utilizing Blossom BlobStore if attached.

Returns standard ATProto blob JSON descriptor with $link CID.

Parameters:
Return type:

Mapping[str, Any]

get_blob(cid_or_str)[source]

Retrieve binary blob data.

Parameters:

cid_or_str (str | CIDLink)

Return type:

bytes | None

export_car()[source]

Export the entire repository state into a CAR v1 archive.

Return type:

bytes

classmethod from_car(car_bytes, signing_key_hex=None, blob_store=None)[source]

Reconstruct a repository from a CAR v1 archive.

Parameters:
  • car_bytes (bytes)

  • signing_key_hex (str | None)

  • blob_store (Any | None)

Return type:

Repo

AT Protocol XRPC (XML-less RPC) server and endpoint router.

Standard library only. Routes XRPC queries (GET) and procedures (POST) under /xrpc/<nsid>, handling core ATProto Lexicons: - com.atproto.server.describeServer - com.atproto.repo.describeRepo - com.atproto.repo.getRecord - com.atproto.repo.listRecords - com.atproto.repo.createRecord - com.atproto.repo.deleteRecord - com.atproto.sync.getRepo - com.atproto.sync.getLatestCommit - com.atproto.sync.getBlob

exception fleetmesh_node.protocols.atproto.xrpc.XRPCError[source]

Bases: FleetmeshError

Represents an XRPC error with HTTP status and Lexicon error string.

__init__(status, error, message)[source]
Parameters:
to_dict()[source]
Return type:

dict[str, str]

class fleetmesh_node.protocols.atproto.xrpc.XRPCRouter[source]

Bases: object

Dispatches XRPC queries and procedures to registered Lexicon handlers.

__init__(repo=None, service_domain='node.fleetmesh.local')[source]
Parameters:
  • repo (Repo | None)

  • service_domain (str)

register_query(nsid, handler)[source]

Register a GET XRPC query handler.

Parameters:
Return type:

None

register_procedure(nsid, handler)[source]

Register a POST XRPC procedure handler.

Parameters:
Return type:

None

handle_request(method, raw_path, body=b'')[source]

Dispatch HTTP request to XRPC handler.

Returns (status_code, headers_dict, body_bytes).

Parameters:
Return type:

tuple[int, Mapping[str, str], bytes]

AT Protocol Firehose WebSocket stream (com.atproto.sync.subscribeRepos).

Standard library only. Manages: - Event Stream binary framing: back-to-back DAG-CBOR (Header + Body). - Monotonic sequence numbering and subscribers. - Frame encoder and decoder for commit and error events. - WebSocket subscription lifecycle.

exception fleetmesh_node.protocols.atproto.firehose.FirehoseError[source]

Bases: FleetmeshError

Base error for Firehose event stream operations.

fleetmesh_node.protocols.atproto.firehose.encode_firehose_frame(header, body)[source]

Encode an ATProto event stream frame into two concatenated DAG-CBOR objects.

Parameters:
Return type:

bytes

fleetmesh_node.protocols.atproto.firehose.decode_firehose_frame(data)[source]

Decode an ATProto event stream frame into (header, body).

Parameters:

data (bytes)

Return type:

tuple[Mapping[str, Any], Mapping[str, Any]]

class fleetmesh_node.protocols.atproto.firehose.FirehoseBroadcaster[source]

Bases: object

Maintains active subscribers and broadcasts commit frames.

__init__(initial_seq=1)[source]
Parameters:

initial_seq (int)

property current_seq: int
property subscriber_count: int
subscribe(subscriber, cursor=None)[source]

Register a subscriber (e.g. WebSocket connection object).

Parameters:
  • subscriber (Any)

  • cursor (int | None)

Return type:

None

unsubscribe(subscriber)[source]

Remove a subscriber.

Parameters:

subscriber (Any)

Return type:

None

broadcast_commit(repo_did, commit_cid, prev_cid, rev, ops, blocks=b'', since=None)[source]

Format and broadcast a #commit frame to all subscribers.

Returns (seq_number, frame_bytes).

Parameters:
Return type:

tuple[int, bytes]

Bilateral budgeting, rate limiting, and Cashu NUT-24 paid fetch for ATProto.

Standard library only. Manages: - Token-bucket rate limiting per client IP or authenticated DID. - Cashu NUT-18 / NUT-24 402 Payment Required challenges for heavy sync requests

(getRepo, getBlob, subscribeRepos).

  • Token deposit parsing and validation via fleetmesh_core.accounting.cashu.

  • Bilateral peering capacity tracking between federating nodes.

exception fleetmesh_node.protocols.atproto.metering.MeteringError[source]

Bases: FleetmeshError

Base error for ATProto metering and payment checks.

class fleetmesh_node.protocols.atproto.metering.TokenBucket[source]

Bases: object

Standard token-bucket rate limiter.

__init__(capacity, refill_rate)[source]
Parameters:
capacity
refill_rate
tokens
last_refill
consume(amount=1.0)[source]

Attempt to consume tokens. Returns True if allowed, False if dry.

Parameters:

amount (float)

Return type:

bool

class fleetmesh_node.protocols.atproto.metering.AtprotoMetering[source]

Bases: object

Enforces rate limits and ecash settlement over XRPC and Firehose edges.

__init__(rate_limit_per_minute=60, burst=15, price_per_fetch_sat=1, mint_url=None, require_payment=False)[source]
Parameters:
  • rate_limit_per_minute (int)

  • burst (int)

  • price_per_fetch_sat (int)

  • mint_url (str | None)

  • require_payment (bool)

mint_url: str | None
deposit_cashu_token(client_id, token_str)[source]

Parse and credit a Cashu V3 (cashuA) or V4 (cashuB) token to client’s balance.

Parameters:
  • client_id (str)

  • token_str (str)

Return type:

int

get_balance(client_id)[source]

Return the current satoshi balance for a client.

Parameters:

client_id (str)

Return type:

int

check_request(client_id, nsid, headers)[source]

Evaluate rate limits and payment requirements for an incoming request.

Returns (allowed, status_code, response_headers, response_body).

Parameters:
Return type:

tuple[bool, int, dict[str, str], bytes | None]

6.7. ActivityPub Protocol Suite (fleetmesh_node.protocols.activitypub)

Experimental

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

fleetmesh-protocol-activitypub: ActivityPub & ActivityStreams 2.0 package.

Conforms to ProtocolPackage (fleetmesh_core.wire.interfaces.ProtocolPackage). Mounts WebFinger (RFC 7033), Actor profiles, S2S Inbox federation, Outbox feeds, and Blossom unified media onto ProtocolHostRouter.

class fleetmesh_node.protocols.activitypub.package.ActivityPubIdentityAdapter[source]

Bases: Ed25519IdentityAdapter

Translates between Fleetmesh Ed25519 identities and ActivityPub Actor URIs.

__init__(actor, private_key=None)[source]
Parameters:
resolve_id(uri)[source]

Resolve a protocol URI or raw 64-char hex public key to a canonical ID.

Parameters:

uri (str)

Return type:

str | None

verify_assertion(payload, signature, pubkey)[source]

Verify an assertion signature against an Ed25519 public key.

Parameters:
Return type:

bool

class fleetmesh_node.protocols.activitypub.package.ActivityPubProtocolPackage[source]

Bases: BaseProtocolPackage

The ActivityPub & ActivityStreams 2.0 suite for Fleetmesh.

name: str = 'activitypub'
version: str = '1.0.0'
standards: tuple[str, ...] = ('activitypub', 'activitystreams-2.0', 'RFC-7033', 'RFC-9421', 'rfc7033-webfinger', 'draft-cavage-http-signatures', 'rfc9421')
__init__(domain='node.fleetmesh.local', username='node', actor=None, store=None, private_key=None, blob_store=None, strain_ledger=None, keystore=None, allow_local_federation=False)[source]
Parameters:
  • domain (str)

  • username (str)

  • actor (Actor | None)

  • store (ActivityPubStore | None)

  • private_key (Any | None)

  • blob_store (Any | None)

  • strain_ledger (Any | None)

  • keystore (Any | None)

  • allow_local_federation (bool)

configure(config)[source]
Parameters:

config (Mapping[str, Any])

Return type:

None

identity_adapter(keystore)[source]
Parameters:

keystore (Any)

Return type:

ProtocolIdentityAdapter | None

mount_ingress(host)[source]
Parameters:

host (ProtocolHostRouter)

Return type:

None

transport_rung(context)[source]
Parameters:

context (Any)

Return type:

Any | None

compartments()[source]
Return type:

tuple[type[Any], …]

start()[source]
Return type:

None

stop()[source]

Close any attached protocol store when stopping the package.

Return type:

None

health()[source]
Return type:

ProtocolHealth

descriptor_capabilities()[source]
Return type:

tuple[tuple[str, str], …]

ActivityPub Actor and WebFinger (RFC 7033) service.

Standard library only. Manages: - WebFinger discovery (/.well-known/webfinger?resource=acct:user@domain). - Actor JSON-LD document generation with W3C Security Vocabulary. - Ed25519 and RSA SubjectPublicKeyInfo PEM encoding.

exception fleetmesh_node.protocols.activitypub.actor.ActorError[source]

Bases: FleetmeshError

Base error for ActivityPub actor operations.

fleetmesh_node.protocols.activitypub.actor.ed25519_pubkey_to_pem(raw_bytes)[source]

Format 32-byte Ed25519 raw public key as standard SubjectPublicKeyInfo PEM.

Parameters:

raw_bytes (bytes)

Return type:

str

fleetmesh_node.protocols.activitypub.actor.parse_acct_uri(uri)[source]

Parse an acct: URI into (username, domain).

Example: ‘acct:node@example.com’ -> (‘node’, ‘example.com’)

Parameters:

uri (str)

Return type:

tuple[str, str]

class fleetmesh_node.protocols.activitypub.actor.Actor[source]

Bases: object

An ActivityPub Actor profile.

__init__(domain, username='node', name='Fleetmesh Edge Node', summary='Autonomous Fleetmesh edge node', public_key_pem='', actor_type='Service', icon_url=None, use_https=True)[source]
Parameters:
  • domain (str)

  • username (str)

  • name (str)

  • summary (str)

  • public_key_pem (str)

  • actor_type (str)

  • icon_url (str | None)

  • use_https (bool)

property acct_uri: str
property id: str
property actor_url: str
property inbox_url: str
property outbox_url: str
property followers_url: str
property following_url: str
property shared_inbox_url: str
property public_key_id: str
to_jsonld()[source]

Produce W3C ActivityStreams 2.0 / ActivityPub Actor JSON-LD document.

Return type:

Mapping[str, Any]

class fleetmesh_node.protocols.activitypub.actor.WebFingerService[source]

Bases: object

Answers RFC 7033 WebFinger and Actor JSON-LD requests.

__init__(actor)[source]
Parameters:

actor (Any)

handle_webfinger_request(params)[source]

Dispatch GET /.well-known/webfinger.

Parameters:

params (dict[str, list[str]])

Return type:

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

handle_actor_request()[source]

Dispatch GET /users/<username>.

Return type:

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

handle_webfinger(params)

Dispatch GET /.well-known/webfinger.

Parameters:

params (dict[str, list[str]])

Return type:

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

ActivityPub Server-to-Server (S2S) Federation and Delivery.

Standard library only. Manages: - Inbound inbox request handling (/inbox, /users/<user>/inbox) with HTTP signature verification. - Actor key resolution (local cache & remote lookup). - Inbound activity routing: Follow, Accept, Create, Undo, Delete, Announce. - Outbox publishing and multi-recipient fanout delivery with Ed25519 / RSA HTTP signing. - Strain and abuse scoring: tracks signature verification failures and throttles abusive hosts.

exception fleetmesh_node.protocols.activitypub.federation.FederationError[source]

Bases: FleetmeshError

Base error for federation processing.

exception fleetmesh_node.protocols.activitypub.federation.StrainThrottledError[source]

Bases: FederationError

Raised when an abusive or high-strain host is temporarily throttled.

class fleetmesh_node.protocols.activitypub.federation.StrainScoreKeeper[source]

Bases: object

Tracks verification failures per peer host to mitigate DoS and invalid traffic.

Integrates optionally with Fleetmesh StrainLedger.

__init__(max_failures=5, window_seconds=300.0, strain_ledger=None)[source]
Parameters:
  • max_failures (int)

  • window_seconds (float)

  • strain_ledger (Any | None)

is_throttled(host)[source]

Check if a remote host currently exceeds allowable strain.

Parameters:

host (str)

Return type:

bool

record_failure(host)[source]

Record a signature verification failure or malformed request.

Parameters:

host (str)

Return type:

int

record_success(host)[source]

Reward valid request by decreasing recorded failures.

Parameters:

host (str)

Return type:

None

class fleetmesh_node.protocols.activitypub.federation.FederationService[source]

Bases: object

ActivityPub S2S Federation handler and outbound delivery engine.

__init__(store, local_actor, private_key, strain_score_keeper=None, remote_resolver=None, http_client=None, auto_accept_follows=True, allow_local_federation=False)[source]

allow_local_federation is the operator’s explicit opt-in for federating with a peer on a loopback/LAN address (a local dev fleet, or two nodes on one host). It defaults off: the actor document and inbox URLs we fetch come from remote signatures, so by default a peer must not be able to point this node at 127.0.0.1 or 169.254.169.254. It is passed to netfetch as allow_private for exactly those two fetches; nothing a remote peer sends can turn it on.

Parameters:
resolve_public_key(key_id)[source]

Resolve public key PEM string for a given keyId.

Parameters:

key_id (str)

Return type:

str | None

handle_inbox(method, path, headers, body)[source]

Process inbound HTTP request to shared or personal inbox.

Parameters:
Return type:

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

deliver_to_inbox(inbox_url, activity_dict)[source]

Sign and deliver an activity directly to a target inbox.

Parameters:
Return type:

tuple[int, bytes]

post_note(content, to=None, cc=None, in_reply_to=None, attachment=None)[source]

Publish a new Note, record Create activity, and fan out to followers/recipients.

Parameters:
Return type:

Mapping[str, Any]

follow(target_actor_url)[source]

Send a Follow request to a remote actor.

Parameters:

target_actor_url (str)

Return type:

Mapping[str, Any]

unfollow(target_actor_url)[source]

Send an Undo Follow request to a remote actor.

Parameters:

target_actor_url (str)

Return type:

Mapping[str, Any]

fleetmesh_node.protocols.activitypub.federation.is_safe_federation_url(url, allow_local=False)[source]

Validate whether an outbound federation target URL is safe against SSRF attacks.

This is the pre-netfetch check kept for callers that only want a cheap answer before doing work; the request itself still goes through netfetch.fetch, which re-checks scheme, address and redirects. With allow_local (operator opt-in for a local/LAN dev fleet) any http(s) URL passes here, and netfetch’s address policy is what actually refuses the private ones.

Parameters:
Return type:

bool

6.8. Secure Scuttlebutt Suite (fleetmesh_node.protocols.ssb)

Experimental

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

fleetmesh-protocol-ssb: Secure Scuttlebutt (SSB) protocol package.

Conforms to ProtocolPackage (fleetmesh_core.wire.interfaces.ProtocolPackage). Integrates the SSB sidecar daemon, client, MuxRPC routing, and SSBRung into the Fleetmesh protocol host and transport ladder.

class fleetmesh_node.protocols.ssb.package.SSBIdentityAdapter[source]

Bases: Ed25519IdentityAdapter

Identity and assertion adapter for Secure Scuttlebutt (@pubkey.ed25519).

__init__(private_key=None, feed_id=None)[source]
Parameters:
  • private_key (Any)

  • feed_id (str | None)

resolve_id(uri)[source]

Resolves SSB feed ID from raw feed ID or ssb: URI.

Parameters:

uri (str)

Return type:

str | None

verify_assertion(payload, signature, pubkey)[source]

Verify an assertion signature against an Ed25519 public key.

Parameters:
Return type:

bool

class fleetmesh_node.protocols.ssb.package.SSBProtocolPackage[source]

Bases: object

The Secure Scuttlebutt (SSB) protocol suite for Fleetmesh.

name: str = 'ssb'
version: str = '1.0.0'
standards: tuple[str, ...] = ('ssb', 'SSB-SHS', 'SSB-BoxStream', 'SSB-MuxRPC', 'secret-handshake', 'boxstream', 'muxrpc')
__init__(node_dir=None, socket_path=None, tcp_host='127.0.0.1', tcp_port=8008, network_key=b'\xd4\xa1\xcb\x88\xa6o\x02\xf8\xdbc\\\xe2dA\xcc]\xac\x1b\x08B\x0c\xea\xac#\x089\xb7U\x84Z\x9f\xfb', secret_key_bytes=None, sidecar_client=None, auto_start_sidecar=False, private_key=None)[source]
Parameters:
configure(config)[source]
Parameters:

config (Mapping[str, Any])

Return type:

None

property client: SSBSidecarClient | None
identity_adapter(keystore=None)[source]
Parameters:

keystore (Any)

Return type:

ProtocolIdentityAdapter | None

mount_ingress(host)[source]
Parameters:

host (ProtocolHostRouter)

Return type:

None

transport_rung(context=None)[source]
Parameters:

context (Any)

Return type:

Any | None

compartments()[source]
Return type:

tuple[type[Any], …]

start()[source]
Return type:

None

stop()[source]
Return type:

None

health()[source]
Return type:

ProtocolHealth

descriptor_capabilities()[source]
Return type:

tuple[tuple[str, str], …]

Secure Scuttlebutt (SSB) MuxRPC Protocol Framing and Method Dispatcher (SSB-MuxRPC).

Standard library only. Manages: - 9-byte packet framing (flags, body length, request ID) for SSB-MuxRPC. - Supported payload encodings: binary (00), UTF-8 text (01), JSON (10). - Procedure calls: async, sync, source, duplex, sink. - Feed history streaming (createHistoryStream) with stream termination. - Error propagation and stream completion flags.

exception fleetmesh_node.protocols.ssb.muxrpc.MuxRPCError[source]

Bases: FleetmeshError

Base error for MuxRPC operations.

class fleetmesh_node.protocols.ssb.muxrpc.MuxRPCMessage[source]

Bases: object

A single MuxRPC packet with a 9-byte binary header and body.

__init__(req, body, body_type=2, is_stream=False, is_end_err=False)[source]
Parameters:
property flags: int
property raw_body_bytes: bytes
encode()[source]

Encode to 9-byte header followed by body bytes.

Return type:

bytes

classmethod from_bytes(data)[source]

Decode message from wire bytes.

Returns (message, bytes_consumed) if a full message is available. Returns (None, 0) if more bytes are needed.

Parameters:

data (bytes)

Return type:

tuple[MuxRPCMessage | None, int]

fleetmesh_node.protocols.ssb.muxrpc.build_request(req_id, name, args, rpc_type='async')[source]

Build an outbound MuxRPC request message.

Parameters:
Return type:

MuxRPCMessage

fleetmesh_node.protocols.ssb.muxrpc.build_response(req_id, payload, is_stream=False, is_end_err=False, body_type=2)[source]

Build a standard response message (response req is negative).

Parameters:
Return type:

MuxRPCMessage

fleetmesh_node.protocols.ssb.muxrpc.build_error_response(req_id, message, is_stream=False)[source]

Build an error response packet with end_err=True.

Parameters:
Return type:

MuxRPCMessage

fleetmesh_node.protocols.ssb.muxrpc.build_stream_end(req_id)[source]

Build an end-of-stream indicator (JSON true with stream and end_err set).

Parameters:

req_id (int)

Return type:

MuxRPCMessage

class fleetmesh_node.protocols.ssb.muxrpc.MuxRPCRouter[source]

Bases: object

Dispatches MuxRPC procedure calls to registered handlers.

__init__(local_feed_id='@AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=.ed25519')[source]
Parameters:

local_feed_id (str)

register(name, handler)[source]

Register a procedure handler.

Parameters:
Return type:

None

handle_request(msg)[source]

Dispatch an incoming MuxRPC request and return zero or more response messages.

Parameters:

msg (MuxRPCMessage)

Return type:

list[MuxRPCMessage]

6.9. Protocol Sidecar Daemons (sidecar)

Rhio Cluster & P2P JetStream Sidecar Daemon.

fleetmesh-rhio DIR [–nats HOST:PORT] [–s3 URL] [–network-id ID] [–socket PATH]

Runs the Rhio micro-datacenter cluster sync daemon in a decoupled process: - Bridges Fleetmesh DIDComm messages with NATS JetStream messaging. - Verifies and stores streaming blobs with Bao-compatible tree hashes. - Coordinates cluster-level synchronization with S3/MinIO backends. - Communicates with meshnode over local Unix domain socket (rhio.sock) using

newline-delimited JSON IPC protocol fleetmesh-rhio/1.

class fleetmesh_node.sidecar.fleetmesh_rhio.RhioMessageLogEntry[source]

Bases: TypedDict

id: str
subject: str
message: Mapping[str, Any]
timestamp: int
class fleetmesh_node.sidecar.fleetmesh_rhio.RhioCommandResponse[source]

Bases: TypedDict

ok: bool
error: str
protocol: str
network_id: str
nats_endpoint: str
s3_endpoint: str
bind_port: int
http_bind_port: int
connected: bool
messages_count: int
blobs_count: int
id: str
subject: str
hash: str
size: int
data_b64: str
synced: bool
class fleetmesh_node.sidecar.fleetmesh_rhio.RhioSidecarClient[source]

Bases: object

IPC client used by meshnode compartments to communicate with the Rhio daemon.

__init__(socket_path, timeout=10.0)[source]
Parameters:
connect()[source]
Return type:

None

close()[source]
Return type:

None

send_command(cmd)[source]

Send a command dictionary and receive response.

Parameters:

cmd (Mapping[str, Any])

Return type:

Mapping[str, Any]

status()[source]
Return type:

Mapping[str, Any]

publish(subject, message)[source]
Parameters:
Return type:

Mapping[str, Any]

store_blob(data_bytes, name=None)[source]
Parameters:
Return type:

Mapping[str, Any]

get_blob(blob_hash)[source]
Parameters:

blob_hash (str)

Return type:

bytes | None

sync_state()[source]
Return type:

Mapping[str, Any]

class fleetmesh_node.sidecar.fleetmesh_rhio.RhioSidecarDaemon[source]

Bases: object

Rhio cluster sidecar daemon managing NATS streams, S3/MinIO sync, and local IPC.

__init__(node_dir, nats_endpoint='localhost:4222', s3_endpoint='http://localhost:9000', network_id='rhio-default-network-1', bind_port=9102, http_bind_port=3000, uds_path=None)[source]
Parameters:
  • node_dir (str)

  • nats_endpoint (str)

  • s3_endpoint (str)

  • network_id (str)

  • bind_port (int)

  • http_bind_port (int)

  • uds_path (str | None)

start()[source]

Start the IPC socket listener and background routines.

Return type:

None

stop()[source]

Stop daemon and cleanup IPC socket.

Return type:

None

fleetmesh_node.sidecar.fleetmesh_rhio.main()[source]
Return type:

None

Secure Scuttlebutt (SSB) Sidecar Daemon.

fleetmesh-ssb DIR [–port N] [–host ADDR] [–socket PATH] [–network-key HEX]

Runs the Secure Scuttlebutt peer-to-peer transport daemon in a decoupled process: - Listens on TCP (default port 8008) for inbound SSB peers. - Binds 127.0.0.1 by default; pass –host 0.0.0.0 (or set

FLEETMESH_SSB_BIND_HOST) to accept peers from other hosts.

  • Performs 4-phase Secret Handshake (SHS) mutual authentication.

  • Wraps connections in 34-byte Box Stream duplex encryption.

  • Multiplexes MuxRPC procedure calls (createHistoryStream, whoami, blobs).

  • Communicates with meshnode over local Unix domain socket (ssb.sock) using newline-delimited JSON IPC protocol fleetmesh-ssb/1.

class fleetmesh_node.sidecar.fleetmesh_ssb.SSBSidecarClient[source]

Bases: object

IPC client used by meshnode compartments to communicate with the SSB daemon.

__init__(socket_path, timeout=10.0)[source]
Parameters:
connect()[source]
Return type:

None

close()[source]
Return type:

None

send_command(cmd)[source]

Send a command dictionary and receive response.

Parameters:

cmd (Mapping[str, Any])

Return type:

Mapping[str, Any]

status()[source]
Return type:

Mapping[str, Any]

post(content)[source]
Parameters:

content (Mapping[str, Any])

Return type:

Mapping[str, Any]

dial(host, port, feed_id)[source]
Parameters:
Return type:

Mapping[str, Any]

class fleetmesh_node.sidecar.fleetmesh_ssb.SSBSidecarDaemon[source]

Bases: object

The Secure Scuttlebutt TCP listener, Box Stream router, and IPC daemon.

__init__(node_dir, tcp_port=8008, bind_host='127.0.0.1', uds_path=None, network_key=b'\xd4\xa1\xcb\x88\xa6o\x02\xf8\xdbc\\\xe2dA\xcc]\xac\x1b\x08B\x0c\xea\xac#\x089\xb7U\x84Z\x9f\xfb', secret_key_bytes=None)[source]
Parameters:
  • node_dir (str)

  • tcp_port (int)

  • bind_host (str)

  • uds_path (str | None)

  • network_key (bytes)

  • secret_key_bytes (bytes | None)

start()[source]

Start TCP listener and IPC Unix domain socket listener.

Return type:

None

stop()[source]

Stop daemon and close sockets.

Return type:

None

dial_peer(host, port, remote_feed_id)[source]

Dial a remote peer, execute SHS, and start MuxRPC loop.

Parameters:
Return type:

tuple[bool, str]

publish_post(content)[source]

Create and sign a new post message on the local feed.

Parameters:

content (Mapping[str, Any])

Return type:

Mapping[str, Any]

fleetmesh_node.sidecar.fleetmesh_ssb.main(argv=None)[source]
Parameters:

argv (Sequence[str] | None)

Return type:

int