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:
Declarative Configuration: Activated via the
protocol_suitesblock inconfig.json. A disabled protocol consumes zero ports, zero threads, and zero storage.Ingress Mounting: Mounts HTTP and WebSocket routes onto
fleetmesh_node.transport.host.ProtocolHostvia longest-prefix path matching.Transport Ladder Rung: Contributes an outbound delivery rung to
fleetmesh_node.transport.router.TransportRouter.Storage Adapter: Attaches native event, CAS blob, or append-only log databases.
Identity Adapter: Translates Fleetmesh node keys (secp256k1, X25519, Ed25519) into native author identities.
Descriptor Capabilities: Advertises native capabilities (e.g.
["c", "p2panda"],["c", "rhio"]) on the node’s signed descriptor.
Protocol Suite |
Standards |
Transport Rank |
Primary Features |
|---|---|---|---|
|
|
15 (Log Chain) |
Append-only operation logs, canonical CBOR encoding, Ed25519 signatures, HTTP/CBOR ingress. |
|
|
12 (Cluster Sync) |
Micro-datacenter cluster replication, Bao Merkle tree CAS storage, NATS JetStream sidecar bridge, MinIO/S3 sync. |
|
NIP-01..77, BUD-01..04 |
30 (Relay Fallback) |
Embedded relay server, event persistence, Blossom media storage, peer table synchronization. |
|
ATProto v1, MST |
20 (XRPC) |
XRPC HTTP endpoints, Merkle Search Trees, DID resolution ( |
|
W3C ActivityPub, LD-Signatures |
25 (Fediverse) |
Actor model, WebFinger discovery, ActivityStreams 2.0 JSON-LD, HTTP Signatures. |
|
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:
name (str)
package_cls (type[ProtocolPackage])
- Return type:
None
- fleetmesh_node.protocols.get_available_protocols()[source]
Return all currently registered protocol names.
- 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:
- fleetmesh_node.protocols.create_protocol_package(name, **kwargs)[source]
Instantiate a protocol package by name with provided arguments.
- Parameters:
name (str)
- Return type:
- class fleetmesh_node.protocols.ProtocolManager[source]
Bases:
objectOrchestrates configuration, lifecycle, and routing across all protocol packages.
- 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.
- mount_ingress(host)[source]
Mount all active protocol packages onto the shared host multiplexer.
- Parameters:
host (ProtocolHostRouter)
- Return type:
None
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:
Package & Ingress:
fleetmesh_node.protocols.p2panda.package.P2PandaProtocolPackagemountsGET /p2panda/statusandGET / POST /p2panda/operations(supporting JSON and CBOR, as well as REST permalinks/p2panda/operations/<op_id>and/p2panda/operations/<author>).Operation Log Store:
fleetmesh_node.protocols.p2panda.store.P2PandaLogStoremanages thread-safe SQLite persistence for operation headers, monotonic sequence numbers, and payload bodies.Identity Adapter:
fleetmesh_node.protocols.p2panda.identity.P2PandaIdentityAdaptertranslates the node’s Ed25519 transport key to a 64-character hex author ID.Transport Rung:
fleetmesh_node.protocols.p2panda.rung.P2PandaRungdelivers messages wrapped as signed p2panda operations at rank 15 in the transport ladder.
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:
BaseProtocolPackageThe p2panda protocol suite for Fleetmesh.
- __init__(node_dir=None, keystore=None, blob_store=None, store=None, **kwargs)[source]
- Parameters:
node_dir (str | None)
keystore (Any | None)
blob_store (Any | None)
store (P2PandaLogStore | None)
kwargs (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
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:
FleetmeshErrorBase error for p2panda storage operations.
- class fleetmesh_node.protocols.p2panda.store.P2PandaLogStore[source]
Bases:
BaseSqliteStoreAppend-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),)
- 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:
op (P2PandaOperation)
verify_chain (bool)
- Return type:
- 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.
- get_log(author, from_seq=0, limit=100)[source]
Return ordered operations for an author from from_seq onwards.
- Parameters:
- Return type:
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:
Ed25519IdentityAdapterTranslates between Fleetmesh keys and p2panda author identities.
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:
RungOutbound transport rung delivering through p2panda append-only operation chains.
- __init__(store=None, identity=None, enabled=True, clock=None, allow_local_peers=False)[source]
- Parameters:
store (P2PandaLogStore | None)
identity (P2PandaIdentityAdapter | None)
enabled (bool)
allow_local_peers (bool)
- Return type:
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:
Package & Ingress:
fleetmesh_node.protocols.rhio.package.RhioProtocolPackagemountsGET /rhio/status,GET / POST /rhio/blobs(supporting streaming binary blobs, base64 JSON, and permalinks/rhio/blobs/<hash>), andGET /rhio/sync.CAS Blob & Tree Sync:
fleetmesh_node.protocols.rhio.store.RhioBlobSyncmanages local Content-Addressable Storage (CAS) with SQLite metadata and S3/MinIO cluster synchronization state.Bao Merkle Tree Hashing:
fleetmesh_node.protocols.rhio.store.RhioBaoTreecomputes hierarchical chunked Merkle trees (1024-byte chunks) compatible with Bao for streaming verification.Transport Rung:
fleetmesh_node.protocols.rhio.rung.RhioRungdelivers messages to remote cluster peers via NATS JetStream pub/sub at rank 12.
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:
BaseProtocolPackageThe Rhio cluster synchronization suite for Fleetmesh.
- __init__(node_dir=None, keystore=None, blob_store=None, store=None, sidecar_client=None, auto_start_sidecar=False, **kwargs)[source]
- identity_adapter(keystore)[source]
- Parameters:
keystore (Any)
- Return type:
ProtocolIdentityAdapter | None
- mount_ingress(host)[source]
- Parameters:
host (ProtocolHostRouter)
- Return type:
None
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:
ExceptionAn HTTP-mappable refusal (status, machine-readable error) for fiber operations.
- class fleetmesh_node.protocols.rhio.store.RhioBaoTree[source]
Bases:
objectBao-compatible hierarchical chunked Merkle tree hashing.
- classmethod leaf_count(size_bytes, chunk_size=1024)[source]
Return the number of chunk_size-byte leaves for size_bytes (minimum 1).
- classmethod compute_root(data, chunk_size=1024)[source]
Compute the Bao-compatible Merkle root hex digest.
- classmethod compute_tree(data, chunk_size=1024)[source]
Compute Merkle tree root and leaf hashes for data (fleetmesh_core.textile.bao).
- 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.
- 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.
- class fleetmesh_node.protocols.rhio.store.RhioBlobSync[source]
Bases:
BaseSqliteStoreMetadata 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))
- set_overflow_cas_dirs(dirs)[source]
Configure secondary/overflow CAS directories (e.g. attached block storage volumes).
- 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).
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- mark_s3_synced(blob_hash)[source]
Mark blob as synchronized with S3 / MinIO cluster storage.
- Parameters:
blob_hash (str)
- Return type:
None
- interaction_counts(target_strand_id)[source]
Public interaction claims on a strand, by kind (each actor’s like counts once).
- 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.
- 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.
- exception fleetmesh_node.protocols.rhio.store.RhioStoreError[source]
Bases:
FleetmeshErrorBase 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.
- 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.
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:
RungTransport rung delegating outbound deliveries to the Rhio cluster sidecar daemon.
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:
objectIdentity and assertion adapter for Nostr (secp256k1 / BIP-340).
- class fleetmesh_node.protocols.nostr.package.NostrProtocolPackage[source]
Bases:
objectThe Nostr & Blossom protocol suite for Fleetmesh.
- 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]
- identity_adapter(keystore)[source]
- Parameters:
keystore (Any)
- Return type:
ProtocolIdentityAdapter | None
- mount_ingress(host)[source]
- Parameters:
host (ProtocolHostRouter)
- Return type:
None
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:
objectThe AT Protocol (atproto) suite for Fleetmesh.
- 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:
repo (Repo | None)
keystore (Any | None)
service_domain (str)
firehose (FirehoseBroadcaster | None)
blob_store (Any | None)
- identity_adapter(keystore)[source]
- Parameters:
keystore (Any)
- Return type:
ProtocolIdentityAdapter | None
- mount_ingress(host)[source]
- Parameters:
host (ProtocolHostRouter)
- Return type:
None
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:
FleetmeshErrorBase error for ATProto repository operations.
- fleetmesh_node.protocols.atproto.repo.tid_now()[source]
Generate a monotonic 13-character Crockford Base32 TID.
- Return type:
- class fleetmesh_node.protocols.atproto.repo.Repo[source]
Bases:
objectAn ATProto account repository.
- classmethod create(did, signing_key_hex, blockstore=None, blob_store=None)[source]
Initialize a new, empty repository with an initial genesis commit.
- put_record(collection, record, rkey=None)[source]
Insert or update a record in this repository.
Returns (rkey, record_cid, new_commit_cid).
- delete_record(collection, rkey)[source]
Remove a record and commit the updated MST. Returns new commit CID.
- list_records(collection='')[source]
List all records in the repository, optionally filtered by collection.
Returns list of (collection, rkey, cid, record_dict).
- 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.
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:
FleetmeshErrorRepresents an XRPC error with HTTP status and Lexicon error string.
- class fleetmesh_node.protocols.atproto.xrpc.XRPCRouter[source]
Bases:
objectDispatches XRPC queries and procedures to registered Lexicon handlers.
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:
FleetmeshErrorBase 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.
- fleetmesh_node.protocols.atproto.firehose.decode_firehose_frame(data)[source]
Decode an ATProto event stream frame into (header, body).
- class fleetmesh_node.protocols.atproto.firehose.FirehoseBroadcaster[source]
Bases:
objectMaintains active subscribers and broadcasts commit frames.
- subscribe(subscriber, cursor=None)[source]
Register a subscriber (e.g. WebSocket connection object).
- unsubscribe(subscriber)[source]
Remove a subscriber.
- Parameters:
subscriber (Any)
- Return type:
None
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:
FleetmeshErrorBase error for ATProto metering and payment checks.
- class fleetmesh_node.protocols.atproto.metering.TokenBucket[source]
Bases:
objectStandard token-bucket rate limiter.
- capacity
- refill_rate
- tokens
- last_refill
- class fleetmesh_node.protocols.atproto.metering.AtprotoMetering[source]
Bases:
objectEnforces 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]
- deposit_cashu_token(client_id, token_str)[source]
Parse and credit a Cashu V3 (cashuA) or V4 (cashuB) token to client’s balance.
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:
Ed25519IdentityAdapterTranslates between Fleetmesh Ed25519 identities and ActivityPub Actor URIs.
- class fleetmesh_node.protocols.activitypub.package.ActivityPubProtocolPackage[source]
Bases:
BaseProtocolPackageThe ActivityPub & ActivityStreams 2.0 suite for Fleetmesh.
- 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]
- identity_adapter(keystore)[source]
- Parameters:
keystore (Any)
- Return type:
ProtocolIdentityAdapter | None
- mount_ingress(host)[source]
- Parameters:
host (ProtocolHostRouter)
- Return type:
None
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:
FleetmeshErrorBase 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.
- 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’)
- class fleetmesh_node.protocols.activitypub.actor.Actor[source]
Bases:
objectAn 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]
- class fleetmesh_node.protocols.activitypub.actor.WebFingerService[source]
Bases:
objectAnswers RFC 7033 WebFinger and Actor JSON-LD requests.
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:
FleetmeshErrorBase error for federation processing.
- exception fleetmesh_node.protocols.activitypub.federation.StrainThrottledError[source]
Bases:
FederationErrorRaised when an abusive or high-strain host is temporarily throttled.
- class fleetmesh_node.protocols.activitypub.federation.StrainScoreKeeper[source]
Bases:
objectTracks verification failures per peer host to mitigate DoS and invalid traffic.
Integrates optionally with Fleetmesh StrainLedger.
- class fleetmesh_node.protocols.activitypub.federation.FederationService[source]
Bases:
objectActivityPub 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_federationis 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 asallow_privatefor exactly those two fetches; nothing a remote peer sends can turn it on.- Parameters:
store (ActivityPubStore)
local_actor (Actor)
private_key (Any)
strain_score_keeper (StrainScoreKeeper | None)
remote_resolver (Callable[[str], Mapping[str, Any] | None] | None)
http_client (Callable[[str, Mapping[str, str], bytes], tuple[int, bytes]] | None)
auto_accept_follows (bool)
allow_local_federation (bool)
- handle_inbox(method, path, headers, body)[source]
Process inbound HTTP request to shared or personal inbox.
- deliver_to_inbox(inbox_url, activity_dict)[source]
Sign and deliver an activity directly to a target inbox.
- 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.
- 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. Withallow_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.
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:
Ed25519IdentityAdapterIdentity and assertion adapter for Secure Scuttlebutt (@pubkey.ed25519).
- class fleetmesh_node.protocols.ssb.package.SSBProtocolPackage[source]
Bases:
objectThe Secure Scuttlebutt (SSB) protocol suite for Fleetmesh.
- 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]
- 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
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:
FleetmeshErrorBase error for MuxRPC operations.
- class fleetmesh_node.protocols.ssb.muxrpc.MuxRPCMessage[source]
Bases:
objectA single MuxRPC packet with a 9-byte binary header and body.
- fleetmesh_node.protocols.ssb.muxrpc.build_request(req_id, name, args, rpc_type='async')[source]
Build an outbound MuxRPC request message.
- 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).
- 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:
- 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:
- class fleetmesh_node.protocols.ssb.muxrpc.MuxRPCRouter[source]
Bases:
objectDispatches MuxRPC procedure calls to registered handlers.
- __init__(local_feed_id='@AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=.ed25519')[source]
- Parameters:
local_feed_id (str)
- handle_request(msg)[source]
Dispatch an incoming MuxRPC request and return zero or more response messages.
- Parameters:
msg (MuxRPCMessage)
- Return type:
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.RhioSidecarClient[source]
Bases:
objectIPC client used by meshnode compartments to communicate with the Rhio daemon.
- class fleetmesh_node.sidecar.fleetmesh_rhio.RhioSidecarDaemon[source]
Bases:
objectRhio cluster sidecar daemon managing NATS streams, S3/MinIO sync, and local IPC.
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:
objectIPC client used by meshnode compartments to communicate with the SSB daemon.
- class fleetmesh_node.sidecar.fleetmesh_ssb.SSBSidecarDaemon[source]
Bases:
objectThe 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]