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