Crate truffle_core

Expand description

§truffle-core

Clean architecture rebuild of truffle’s core networking library.

This crate implements the layered architecture described in RFC 012:

Layer 3 (Network): Peer discovery, addressing, encrypted tunnels via Tailscale
Layer 4 (Transport): WebSocket, TCP, QUIC protocol transports
Layer 5 (Session): Peer registry, lazy connections, message routing
Layer 6 (Envelope): Namespace-based message framing
Node API: Single public entry point wiring all layers together

§Quick start

use truffle_core::{Node, NodeBuilder};

let node = Node::builder()
    .name("my-app")
    .sidecar_path("/usr/local/bin/truffle-sidecar")
    .build()
    .await?;

let peers = node.peers().await;
node.send(&peers[0].id, "chat", b"hello!").await?;

§Layer 3 — Network

The NetworkProvider trait defines a generic interface for peer discovery and raw connectivity. The TailscaleProvider implementation wraps the Go sidecar (tsnet) to provide encrypted Tailscale tunnels.

§Layer 4 — Transport

Three transport trait families sit on top of Layer 3:

StreamTransport + FramedStream: Message-oriented bidirectional connections (WebSocket, future QUIC streams).
RawTransport: Raw byte streams (TCP).
DatagramTransport: Unreliable datagrams (future UDP/QUIC).

§Layer 5 — Session

The PeerRegistry manages peer state and WebSocket connections. Peers exist in the registry when Layer 3 discovers them, even before any transport connections are established.

§Layer 6 — Envelope

The Envelope struct wraps all application messages with a namespace string for routing and an opaque JSON payload that truffle-core never inspects.

§Node API

The Node struct is the single public entry point. It exposes ~12 methods covering discovery, messaging, raw streams, and diagnostics.

Re-exports§

pub use crdt_doc::CrdtBackend;
pub use crdt_doc::CrdtDoc;
pub use crdt_doc::CrdtDocError;
pub use crdt_doc::CrdtDocEvent;
pub use crdt_doc::CrdtFileBackend;
pub use crdt_doc::CrdtSyncMessage;
pub use crdt_doc::MemoryCrdtBackend;
pub use envelope::Envelope;
pub use file_transfer::FileOffer;
pub use file_transfer::FileTransfer;
pub use file_transfer::FileTransferEvent;
pub use file_transfer::FtMessage;
pub use file_transfer::OfferDecision;
pub use file_transfer::OfferResponder;
pub use file_transfer::TransferDirection;
pub use file_transfer::TransferError;
pub use file_transfer::TransferProgress;
pub use file_transfer::TransferResult;
pub use identity::slug;
pub use identity::tailscale_hostname;
pub use identity::AppId;
pub use identity::DeviceId;
pub use identity::DeviceName;
pub use identity::IdentityError;
pub use node::NamespacedMessage;
pub use node::Node;
pub use node::NodeBuilder;
pub use node::NodeError;
pub use node::Peer;
pub use request_reply::send_and_wait;
pub use request_reply::RequestError;
pub use synced_store::FileBackend;
pub use synced_store::MemoryBackend;
pub use synced_store::Slice;
pub use synced_store::StoreBackend;
pub use synced_store::StoreEvent;
pub use synced_store::SyncMessage;
pub use synced_store::SyncedStore;

Modules§

crdt_doc: CrdtDoc — CRDT document synchronization across the mesh.
envelope: Layer 6: Envelope — Namespace-routed message framing.
file_transfer: File transfer subsystem for truffle-core.
identity: Identity and namespacing primitives (RFC 017).
network: Layer 3: Network — Peer discovery, addressing, encrypted tunnels.
node: Node API — the single public entry point for all truffle functionality.
proxy: Reverse proxy subsystem.
request_reply: Request/reply utility for correlated message exchange.
session: Layer 5: Session — Peer identity, connection lifecycle, message routing.
synced_store: SyncedStore — device-owned state synchronization across the mesh.
transport: Layer 4: Transport — Protocol-specific connection management.