Crate truffle_core 

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

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.

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.