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//! // Prefer a Peer handle once RFC 022 Phase B lands; string queries still work.
25//! node.send(&peers[0].tailscale_id, "chat", b"hello!").await?;
26//! ```
27//!
28//! ## Layer 3 — Network
29//!
30//! The [`NetworkProvider`](network::NetworkProvider) trait defines a generic interface for peer
31//! discovery and raw connectivity. The [`TailscaleProvider`](network::tailscale::TailscaleProvider)
32//! implementation wraps the Go sidecar (tsnet) to provide encrypted Tailscale tunnels.
33//!
34//! ## Layer 4 — Transport
35//!
36//! Three transport trait families sit on top of Layer 3:
37//!
38//! - [`StreamTransport`](transport::StreamTransport) + [`FramedStream`](transport::FramedStream):
39//! Message-oriented bidirectional connections (WebSocket, future QUIC streams).
40//! - [`RawTransport`](transport::RawTransport): Raw byte streams (TCP).
41//! - [`DatagramTransport`](transport::DatagramTransport): Unreliable datagrams (future UDP/QUIC).
42//!
43//! ## Layer 5 — Session
44//!
45//! The [`PeerRegistry`](session::PeerRegistry) manages peer state and WebSocket connections.
46//! Peers exist in the registry when Layer 3 discovers them, even before any transport
47//! connections are established.
48//!
49//! ## Layer 6 — Envelope
50//!
51//! The [`Envelope`] struct wraps all application messages with a namespace string
52//! for routing and an opaque JSON payload that truffle-core never inspects.
53//!
54//! ## Node API
55//!
56//! The [`Node`] struct is the single public entry point. It exposes ~12 methods
57//! covering discovery, messaging, raw streams, and diagnostics.
58
59pub mod envelope;
60pub mod file_transfer;
61pub mod identity;
62pub mod network;
63pub mod node;
64pub mod proxy;
65pub mod request_reply;
66pub mod session;
67pub mod synced_store;
68pub mod transport;
69
70// Re-export the main public types for convenience.
71pub use envelope::Envelope;
72pub use file_transfer::{
73 FileOffer, FileTransfer, FileTransferEvent, FtMessage, OfferDecision, OfferResponder,
74 TransferDirection, TransferError, TransferProgress, TransferResult,
75};
76pub use identity::{slug, tailscale_hostname, AppId, DeviceId, DeviceName, IdentityError};
77pub use node::{NamespacedMessage, Node, NodeBuilder, NodeError, Peer};
78pub use request_reply::{send_and_wait, RequestError};
79pub use session::BroadcastReport;
80pub use synced_store::{
81 FileBackend, MemoryBackend, Slice, StoreBackend, StoreEvent, SyncMessage, SyncedStore,
82};