truffle_core/
lib.rs

1//! # truffle-core
2//!
3//! Clean architecture rebuild of truffle's core networking library.
4//!
5//! This crate implements the layered architecture described in RFC 012:
6//! - **Layer 3 (Network)**: Peer discovery, addressing, encrypted tunnels via Tailscale
7//! - **Layer 4 (Transport)**: WebSocket, TCP, QUIC protocol transports
8//! - **Layer 5 (Session)**: Peer registry, lazy connections, message routing
9//! - **Layer 6 (Envelope)**: Namespace-based message framing
10//! - **Node API**: Single public entry point wiring all layers together
11//!
12//! ## Quick start
13//!
14//! ```ignore
15//! use truffle_core::{Node, NodeBuilder};
16//!
17//! let node = Node::builder()
18//!     .name("my-app")
19//!     .sidecar_path("/usr/local/bin/truffle-sidecar")
20//!     .build()
21//!     .await?;
22//!
23//! let peers = node.peers().await;
24//! node.send(&peers[0].id, "chat", b"hello!").await?;
25//! ```
26//!
27//! ## Layer 3 — Network
28//!
29//! The [`NetworkProvider`](network::NetworkProvider) trait defines a generic interface for peer
30//! discovery and raw connectivity. The [`TailscaleProvider`](network::tailscale::TailscaleProvider)
31//! implementation wraps the Go sidecar (tsnet) to provide encrypted Tailscale tunnels.
32//!
33//! ## Layer 4 — Transport
34//!
35//! Three transport trait families sit on top of Layer 3:
36//!
37//! - [`StreamTransport`](transport::StreamTransport) + [`FramedStream`](transport::FramedStream):
38//!   Message-oriented bidirectional connections (WebSocket, future QUIC streams).
39//! - [`RawTransport`](transport::RawTransport): Raw byte streams (TCP).
40//! - [`DatagramTransport`](transport::DatagramTransport): Unreliable datagrams (future UDP/QUIC).
41//!
42//! ## Layer 5 — Session
43//!
44//! The [`PeerRegistry`](session::PeerRegistry) manages peer state and WebSocket connections.
45//! Peers exist in the registry when Layer 3 discovers them, even before any transport
46//! connections are established.
47//!
48//! ## Layer 6 — Envelope
49//!
50//! The [`Envelope`] struct wraps all application messages with a namespace string
51//! for routing and an opaque JSON payload that truffle-core never inspects.
52//!
53//! ## Node API
54//!
55//! The [`Node`] struct is the single public entry point. It exposes ~12 methods
56//! covering discovery, messaging, raw streams, and diagnostics.
57
58pub mod crdt_doc;
59pub mod envelope;
60pub mod file_transfer;
61pub mod identity;
62pub mod network;
63pub mod node;
64pub mod request_reply;
65pub mod session;
66pub mod synced_store;
67pub mod transport;
68
69// Re-export the main public types for convenience.
70pub use crdt_doc::{
71    CrdtBackend, CrdtDoc, CrdtDocError, CrdtDocEvent, CrdtFileBackend, CrdtSyncMessage,
72    MemoryCrdtBackend,
73};
74pub use envelope::Envelope;
75pub use file_transfer::{
76    FileOffer, FileTransfer, FileTransferEvent, FtMessage, OfferDecision, OfferResponder,
77    TransferDirection, TransferError, TransferProgress, TransferResult,
78};
79pub use identity::{slug, tailscale_hostname, AppId, DeviceId, DeviceName, IdentityError};
80pub use node::{NamespacedMessage, Node, NodeBuilder, NodeError, Peer};
81pub use request_reply::{send_and_wait, RequestError};
82pub use synced_store::{
83    FileBackend, MemoryBackend, Slice, StoreBackend, StoreEvent, SyncMessage, SyncedStore,
84};
truffle_core/lib.rs

truffle_core/
lib.rs
