Struct Node 

pub struct Node<N: NetworkProvider + 'static> { /* private fields */ }

The main truffle node — single public entry point for all functionality.

Generic over N: NetworkProvider so that tests can inject a mock provider without Tailscale. In production, use the concrete type Node<TailscaleProvider> (created via NodeBuilder).

Lifecycle

1. Create via Node::builder() + .build().await
2. Use peers(), send(), subscribe(), open_tcp(), etc.
3. Call stop() to shut down

Implementations

impl<N: NetworkProvider + 'static> Node<N>

pub fn builder() -> NodeBuilder

Create a new NodeBuilder for configuring and constructing a node.

pub fn file_transfer(&self) -> FileTransfer<'_, N>

Access the file transfer subsystem.

Returns a FileTransfer handle that provides methods for sending, receiving, and pulling files.

pub fn synced_store<T>(self: &Arc<Self>, store_id: &str) -> Arc<SyncedStore<T>>

where T: Serialize + DeserializeOwned + Clone + Send + Sync + 'static,

Create a synchronized store for device-owned state.

Returns an Arc<SyncedStore<T>> that syncs data across the mesh on namespace "ss:{store_id}". The caller owns the returned Arc; the background sync task also holds one.

Requires self to be wrapped in an Arc because the sync task needs to outlive this call.

pub fn synced_store_with_backend<T>( self: &Arc<Self>, store_id: &str, backend: Arc<dyn StoreBackend>, ) -> Arc<SyncedStore<T>>

where T: Serialize + DeserializeOwned + Clone + Send + Sync + 'static,

Create a synchronized store with a custom persistence backend.

Same as synced_store but restores persisted data on startup and writes through to the backend on every change.

pub async fn crdt_doc( self: &Arc<Self>, doc_id: &str, ) -> Result<Arc<CrdtDoc>, CrdtDocError>

Create a CRDT document synchronized across the mesh.

Returns an Arc<CrdtDoc> that syncs on namespace "crdt:{doc_id}". Uses the default MemoryCrdtBackend (no persistence).

pub async fn crdt_doc_with_backend( self: &Arc<Self>, doc_id: &str, backend: Arc<dyn CrdtBackend>, ) -> Result<Arc<CrdtDoc>, CrdtDocError>

Create a CRDT document with a custom persistence backend.

Same as crdt_doc but restores persisted data on startup and writes through to the backend on every change.

pub fn state_dir(&self) -> &Path

The state directory for persistence backends.

Returns an empty path for test nodes created via from_parts.

pub async fn stop(&self)

Stop the node and all underlying layers.

After calling stop(), the node should not be used for further operations. Peer connections are closed and the network provider is shut down.

pub fn local_info(&self) -> NodeIdentity

Return the local node’s identity (stable ID, hostname, name).

pub async fn peers(&self) -> Vec<Peer>

Return all known peers.

Includes peers that are online but not yet connected (no active WS). This information comes from Layer 3 peer discovery.

pub fn on_peer_change(&self) -> Receiver<PeerEvent>

Subscribe to peer change events (joined, left, connected, etc.).

pub async fn resolve_peer_id(&self, peer_id: &str) -> Result<String, NodeError>

Resolve a peer identifier to the canonical per-device ULID (device_id) from the RFC 017 hello envelope.

Accepts any of:

• the stable device_id (full ULID)
• a unique prefix of the device_id (at least 4 characters; must match exactly one known peer)
• the human-readable device_name from the hello
• the Layer 3 Tailscale hostname (the sanitised slug) — legacy
• the Tailscale stable ID — escape hatch for diagnostics

The returned string is always a device_id, so it is safe to feed back into Node::send or any other method that takes a peer identifier.

pub async fn ping(&self, peer_id: &str) -> Result<PingResult, NodeError>

Ping a peer via the network layer.

Resolves the peer ID to an IP address and pings via Layer 3. Accepts the same identifier forms as resolve_peer_id.

pub async fn health(&self) -> HealthInfo

Return health information from the network layer.

pub async fn send( &self, peer_id: &str, namespace: &str, data: &[u8], ) -> Result<(), NodeError>

Send a namespaced message to a specific peer.

The data is wrapped in a Layer 6 Envelope with the given namespace and a "message" type, then serialized and sent via the session layer. If no WebSocket connection exists, one is lazily established.

pub async fn send_typed( &self, peer_id: &str, namespace: &str, msg_type: &str, payload: &Value, ) -> Result<(), NodeError>

Send a namespaced message with an explicit msg_type and JSON payload.

Unlike send, this method takes a pre-built serde_json::Value payload and a caller-chosen msg_type instead of raw bytes with a hardcoded "message" type. Used by subsystems (file transfer, synced store, request/reply) that define their own wire protocol message types.

pub async fn broadcast_typed( &self, namespace: &str, msg_type: &str, payload: &Value, )

Broadcast a namespaced message with an explicit msg_type and JSON payload to all connected peers.

pub async fn broadcast(&self, namespace: &str, data: &[u8])

Broadcast a namespaced message to all connected peers.

Only peers with active WebSocket connections receive the broadcast. No lazy connections are established.

pub fn subscribe(&self, namespace: &str) -> Receiver<NamespacedMessage>

Subscribe to messages in a specific namespace.

Returns a broadcast receiver that yields NamespacedMessages matching the given namespace. Multiple subscribers to the same namespace share the same underlying channel.

pub async fn open_tcp( &self, peer_id: &str, port: u16, ) -> Result<TcpStream, NodeError>

Open a raw TCP stream to a peer on the given port.

Resolves the peer ID to an IP address via the session’s peer list, then dials via the network layer. Accepts the same identifier forms as resolve_peer_id. Returns a plain TcpStream for byte-oriented I/O.

pub async fn listen_tcp(&self, port: u16) -> Result<RawListener, NodeError>

Listen for incoming TCP connections on a port.

Returns a RawListener that yields raw TcpStreams. The caller is responsible for accepting connections in a loop.

pub async fn open_quic(&self, _peer_id: &str) -> Result<(), NodeError>

Open a QUIC connection to a peer.

Stub — returns NotImplemented until Phase 8.

pub async fn open_udp( &self, _peer_id: &str, ) -> Result<NetworkUdpSocket, NodeError>

Open a UDP datagram socket to a peer.

Stub — returns NotImplemented until Phase 8.