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 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 (name or Tailscale ID) to the canonical Tailscale stable node ID.

Returns the input unchanged if it already matches a peer’s id. Falls back to searching by name (hostname).

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.

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