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 network;
59pub mod transport;
60pub mod session;
61pub mod envelope;
62pub mod node;
63pub mod file_transfer;
64pub mod request_reply;
65pub mod synced_store;
66
67// Re-export the main public types for convenience.
68pub use node::{Node, NodeBuilder, Peer, NamespacedMessage, NodeError};
69pub use envelope::Envelope;
70pub use file_transfer::{
71 FileTransfer, FileTransferEvent, FileOffer, OfferResponder, OfferDecision,
72 TransferResult, TransferError, TransferProgress, TransferDirection,
73 FtMessage,
74};
75pub use request_reply::{send_and_wait, RequestError};
76pub use synced_store::{SyncedStore, Slice, StoreEvent, StoreBackend, MemoryBackend, SyncMessage};