pub struct Node<N: NetworkProvider + 'static> { /* private fields */ }Expand description
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
- Create via
Node::builder()+.build().await - Use
peers(),send(),subscribe(),open_tcp(), etc. - Call
stop()to shut down
Implementations§
Source§impl<N: NetworkProvider + 'static> Node<N>
impl<N: NetworkProvider + 'static> Node<N>
Sourcepub fn builder() -> NodeBuilder
pub fn builder() -> NodeBuilder
Create a new NodeBuilder for configuring and constructing a node.
Sourcepub fn file_transfer(&self) -> FileTransfer<'_, N>
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.
Sourcepub fn proxy(&self) -> Proxy<'_, N>
pub fn proxy(&self) -> Proxy<'_, N>
Access the reverse proxy subsystem.
Returns a Proxy handle that provides
methods for adding, removing, and listing reverse proxies.
Sourcepub fn synced_store<T>(self: &Arc<Self>, store_id: &str) -> Arc<SyncedStore<T>>
pub fn synced_store<T>(self: &Arc<Self>, store_id: &str) -> Arc<SyncedStore<T>>
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.
Sourcepub fn synced_store_with_backend<T>(
self: &Arc<Self>,
store_id: &str,
backend: Arc<dyn StoreBackend>,
) -> Arc<SyncedStore<T>>
pub fn synced_store_with_backend<T>( self: &Arc<Self>, store_id: &str, backend: Arc<dyn StoreBackend>, ) -> Arc<SyncedStore<T>>
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.
Sourcepub fn state_dir(&self) -> &Path
pub fn state_dir(&self) -> &Path
The state directory for persistence backends.
Returns an empty path for test nodes created via from_parts.
Sourcepub async fn stop(&self)
pub async fn stop(&self)
Stop the node and all underlying layers.
Closes every active WebSocket connection (Layer 5) and shuts down the
network provider (Layer 3 — sidecar + bridge). After stop() returns,
send and send_typed fail with
NodeError::Stopped, and broadcast /
broadcast_typed become no-ops.
Idempotent: calling stop() more than once is safe — subsequent calls
return immediately without repeating teardown.
When stop() returns, all node-scoped background work has stopped:
the envelope router, the file-transfer dispatch task, and in-flight
per-transfer tasks are cancelled and drained (with a bounded wait
that hard-aborts stragglers, so stop() cannot hang). Session and
provider background loops are torn down by their own layers.
Sourcepub fn local_info(&self) -> NodeIdentity
pub fn local_info(&self) -> NodeIdentity
Return the local node’s identity (stable ID, hostname, name).
Sourcepub async fn peers(&self) -> Vec<Peer>
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.
Sourcepub fn on_peer_change(&self) -> Receiver<PeerEvent>
pub fn on_peer_change(&self) -> Receiver<PeerEvent>
Subscribe to peer change events (joined, left, connected, etc.).
Sourcepub async fn peer(
&self,
query: &str,
wait_ms: Option<u64>,
) -> Result<Option<Peer>, NodeError>
pub async fn peer( &self, query: &str, wait_ms: Option<u64>, ) -> Result<Option<Peer>, NodeError>
Resolve a query to a public Peer handle view (RFC 022).
- Not found →
Ok(None)after optional wait - Ambiguous (multiple name / short-prefix hits) →
NodeError::AmbiguousPeer
wait_ms: when set, block until the query becomes resolvable or the
timeout elapses (then Ok(None)). Useful for rehydrating a saved ULID
whose owner has not completed hello yet.
Sourcepub async fn resolve_peer_ip(&self, peer_ref: &str) -> Result<IpAddr, NodeError>
pub async fn resolve_peer_ip(&self, peer_ref: &str) -> Result<IpAddr, NodeError>
Resolve a peer identifier to the peer’s Tailscale IP address.
Accepts the same identifier forms as
resolve_peer_id. Used by the FFI layers
to address datagram sends by peer name.
Sourcepub async fn resolve_peer_id(&self, peer_id: &str) -> Result<String, NodeError>
pub async fn resolve_peer_id(&self, peer_id: &str) -> Result<String, NodeError>
Resolve a peer query to a string safe to pass to send
and other peer-addressed methods.
Prefer the published durable ULID when known and not suppressed;
otherwise return the Tailscale stable id (routing key). This is the
legacy string path — RFC 022 Phase B replaces it with peer() handles.
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_namefrom the hello - the bare device name of a peer that has not helloed yet (matched
via the
truffle-{app_id}-{slug}hostname convention) - the Layer 3 Tailscale hostname (the sanitised slug)
- the Tailscale stable ID
- the Tailscale IP address (e.g.
100.x.x.x)
Sourcepub async fn ping(&self, peer_id: &str) -> Result<PingResult, NodeError>
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.
Sourcepub async fn health(&self) -> HealthInfo
pub async fn health(&self) -> HealthInfo
Return health information from the network layer.
Sourcepub async fn send(
&self,
peer_id: &str,
namespace: &str,
data: &[u8],
) -> Result<(), NodeError>
👎Deprecated since 0.7.0: wire type depends on data contents; use send_json or send_bytes
pub async fn send( &self, peer_id: &str, namespace: &str, data: &[u8], ) -> Result<(), NodeError>
wire type depends on data contents; use send_json or send_bytes
Send a namespaced message to a specific peer.
Deprecated: the wire representation depends on the contents of
data — bytes that parse as UTF-8 JSON are sent as that JSON value
(b"123" → number, b"null" → null), anything else becomes a JSON
array of byte values. Use send_json for
structured payloads or send_bytes for opaque
binary data instead.
Returns NodeError::Stopped if stop has been called.
Sourcepub async fn send_json(
&self,
peer_id: &str,
namespace: &str,
payload: &Value,
) -> Result<(), NodeError>
pub async fn send_json( &self, peer_id: &str, namespace: &str, payload: &Value, ) -> Result<(), NodeError>
Send a JSON payload to a specific peer.
The payload is wrapped in a Layer 6 Envelope with the given
namespace and a "message" type — subscribers observe it unchanged
as NamespacedMessage::payload. If no WebSocket connection
exists, one is lazily established.
Sourcepub async fn send_bytes(
&self,
peer_id: &str,
namespace: &str,
data: &[u8],
) -> Result<(), NodeError>
pub async fn send_bytes( &self, peer_id: &str, namespace: &str, data: &[u8], ) -> Result<(), NodeError>
Send opaque binary data to a specific peer.
The bytes travel base64-encoded in a "bytes"-typed envelope with
payload shape {"encoding":"base64","data":"…"}; receivers decode
with NamespacedMessage::payload_bytes. Unlike the deprecated
send, the wire representation never depends on the
data’s contents.
Sourcepub async fn send_typed(
&self,
peer_id: &str,
namespace: &str,
msg_type: &str,
payload: &Value,
) -> Result<(), NodeError>
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.
Sourcepub async fn broadcast_typed(
&self,
namespace: &str,
msg_type: &str,
payload: &Value,
)
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.
Sourcepub async fn broadcast(&self, namespace: &str, data: &[u8])
👎Deprecated since 0.7.0: wire type depends on data contents and failures are hidden; use broadcast_json or broadcast_bytes
pub async fn broadcast(&self, namespace: &str, data: &[u8])
wire type depends on data contents and failures are hidden; use broadcast_json or broadcast_bytes
Broadcast a namespaced message to all connected peers.
Deprecated: the wire representation depends on the contents of
data (see send), and delivery failures are
silently discarded. Use broadcast_json or
broadcast_bytes, which return a
BroadcastReport.
Sourcepub async fn broadcast_json(
&self,
namespace: &str,
payload: &Value,
) -> Result<BroadcastReport, NodeError>
pub async fn broadcast_json( &self, namespace: &str, payload: &Value, ) -> Result<BroadcastReport, NodeError>
Broadcast a JSON payload to all connected peers.
Only peers with an active WebSocket connection receive the message —
no lazy connections are established. Returns a
BroadcastReport: “queued” means
handed to the peer’s connection task, not confirmed delivery.
Sourcepub async fn broadcast_bytes(
&self,
namespace: &str,
data: &[u8],
) -> Result<BroadcastReport, NodeError>
pub async fn broadcast_bytes( &self, namespace: &str, data: &[u8], ) -> Result<BroadcastReport, NodeError>
Broadcast opaque binary data to all connected peers.
Same wire shape as send_bytes; same report
semantics as broadcast_json.
Sourcepub fn subscribe(&self, namespace: &str) -> Receiver<NamespacedMessage>
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.
Sourcepub async fn open_tcp(
&self,
peer_id: &str,
port: u16,
) -> Result<TcpStream, NodeError>
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.
The stream is raw even on port 443 — the sidecar’s legacy auto-TLS wrap for 443 dials is disabled on this path.
Sourcepub async fn listen_tcp(&self, port: u16) -> Result<RawListener, NodeError>
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. Port 0 binds an
ephemeral port (advertise the resolved RawListener::port in-band,
like the file transfer subsystem does). The session WebSocket port
(default 9417) is reserved.
Sourcepub async fn listen_tcp_opts(
&self,
port: u16,
opts: ListenOpts,
) -> Result<RawListener, NodeError>
pub async fn listen_tcp_opts( &self, port: u16, opts: ListenOpts, ) -> Result<RawListener, NodeError>
As listen_tcp, with options (RFC 023 §7.1).
tls: true terminates TLS in the sidecar with automatic MagicDNS
certificates (requires MagicDNS + HTTPS enabled on the tailnet);
accepted streams then carry plaintext HTTP over the loopback bridge.
Sourcepub async fn unlisten_tcp(&self, port: u16) -> Result<(), NodeError>
pub async fn unlisten_tcp(&self, port: u16) -> Result<(), NodeError>
Stop listening on a previously opened TCP port.
Dropping the RawListener alone stops local delivery but leaves
the tsnet port bound in the sidecar; this releases it.
Sourcepub async fn connect_quic(
&self,
peer_id: &str,
port: u16,
) -> Result<QuicConnection, NodeError>
pub async fn connect_quic( &self, peer_id: &str, port: u16, ) -> Result<QuicConnection, NodeError>
Open a raw QUIC connection to a peer on the given port.
The connection carries multiple concurrent bidirectional byte
streams (QuicConnection::open_stream) with no head-of-line
blocking between them. App scoping is enforced at the TLS layer via
ALPN (truffle-raw.{app_id}) — peers from a different app fail the
handshake. Accepts the same identifier forms as
resolve_peer_id.
Sourcepub async fn listen_quic(&self, port: u16) -> Result<QuicListener, NodeError>
pub async fn listen_quic(&self, port: u16) -> Result<QuicListener, NodeError>
Listen for raw QUIC connections on a port.
Returns a QuicListener that yields QuicConnections. Only
same-app peers can complete the handshake (ALPN scoping). The
session WebSocket port (default 9417) is reserved, and port 0 is
not yet supported over the tsnet relay (the relay cannot report the
actual ephemeral port back).
Sourcepub async fn bind_udp(&self, port: u16) -> Result<DatagramSocket, NodeError>
pub async fn bind_udp(&self, port: u16) -> Result<DatagramSocket, NodeError>
Bind a UDP datagram socket on a port.
Datagrams are relayed through the network provider (tsnet) with
boundaries preserved; the transport falls back to a direct host
socket only when the provider has no UDP support (tests). Returns a
DatagramSocket supporting send_to / recv_from with tailnet
addresses. IPv4 (100.x) peers only; keep payloads ≤ ~1200 bytes
to stay under the tailnet MTU. Port 0 binds an ephemeral relay
port — suitable for client-style sockets that send first.