Struct Node 

pub struct Node { /* private fields */ }

A running FIPS node instance.

This is the top-level container holding all node state.

Peer Lifecycle

Peers go through two phases:

1. Connection phase (connections): Handshake in progress, indexed by LinkId
2. Active phase (peers): Authenticated, indexed by NodeAddr

The addr_to_link map enables dispatching incoming packets to the right connection before authentication completes.

Implementations

impl Node

pub async fn run_rx_loop(&mut self) -> Result<(), NodeError>

Run the receive event loop.

Processes packets from all transports, dispatching based on the phase field in the 4-byte common prefix:

• Phase 0x0: Encrypted frame (session data)
• Phase 0x1: Handshake message 1 (initiator -> responder)
• Phase 0x2: Handshake message 2 (responder -> initiator)

Also processes outbound IPv6 packets from the TUN reader for session encapsulation and routing through the mesh.

Also processes DNS-resolved identities for identity cache population.

Also runs a periodic tick (1s) to clean up stale handshake connections that never received a response. This prevents resource leaks when peers are unreachable.

This method takes ownership of the packet_rx channel and runs until the channel is closed (typically when stop() is called).

impl Node

pub async fn start(&mut self) -> Result<(), NodeError>

Start the node.

Initializes the TUN interface (if configured), spawns I/O threads, and transitions to the Running state.

pub async fn stop(&mut self) -> Result<(), NodeError>

Stop the node.

Shuts down TUN interface, stops I/O threads, and transitions to the Stopped state.

pub async fn adopt_established_traversal( &mut self, traversal: EstablishedTraversal, ) -> Result<BootstrapHandoffResult, NodeError>

Adopt an already-established UDP traversal and start the normal FIPS Noise handshake over it.

This is intended for integration with an external rendezvous runtime that has already completed relay signaling, STUN observation, and UDP hole punching. After handoff, the adopted socket is owned by FIPS.

impl Node

pub fn new(config: Config) -> Result<Self, NodeError>

Create a new node from configuration.

pub fn with_identity( identity: Identity, config: Config, ) -> Result<Self, NodeError>

Create a node with a specific identity.

This constructor validates cross-field config invariants before constructing the node, same as Node::new.

pub fn leaf_only(config: Config) -> Result<Self, NodeError>

Create a leaf-only node (simplified state).

pub fn identity(&self) -> &Identity

Get this node’s identity.

pub fn node_addr(&self) -> &NodeAddr

Get this node’s NodeAddr.

pub fn npub(&self) -> String

Get this node’s npub.

pub fn config(&self) -> &Config

Get the configuration.

pub fn effective_ipv6_mtu(&self) -> u16

Calculate the effective IPv6 MTU that can be sent over FIPS.

Delegates to upper::icmp::effective_ipv6_mtu() with this node’s transport MTU. Returns the maximum IPv6 packet size (including IPv6 header) that can be transmitted through the FIPS mesh.

pub fn transport_mtu(&self) -> u16

Get the transport MTU governing the global TUN-boundary MSS clamp.

Returns the minimum MTU across all operational transports, or 1280 (IPv6 minimum) as fallback. Used for initial TUN configuration where a specific egress transport isn’t yet known: the resulting effective_ipv6_mtu (transport_mtu - 77) and max_mss (effective_mtu - 60) form a conservative ceiling that fits ANY configured-transport’s egress, eliminating PMTU-D black holes that would otherwise occur when a flow’s actual egress is smaller than the clamp ceiling assumed at TUN init.

Returning the smallest (rather than the first-iterated, which used to vary across HashMap iteration order + async-startup race) makes the clamp deterministic across daemon restarts.

See ISSUE-2026-0011 for the empirical investigation.

pub fn state(&self) -> NodeState

Get the node state.

pub fn uptime(&self) -> Duration

Get the node uptime.

pub fn is_running(&self) -> bool

Check if node is operational.

pub fn is_leaf_only(&self) -> bool

Check if this is a leaf-only node.

pub fn tree_state(&self) -> &TreeState

Get the tree state.

pub fn tree_state_mut(&mut self) -> &mut TreeState

Get mutable tree state.

pub fn bloom_state(&self) -> &BloomState

Get the Bloom filter state.

pub fn bloom_state_mut(&mut self) -> &mut BloomState

Get mutable Bloom filter state.

pub fn estimated_mesh_size(&self) -> Option<u64>

Get the cached estimated mesh size.

pub fn coord_cache(&self) -> &CoordCache

Get the coordinate cache.

pub fn coord_cache_mut(&mut self) -> &mut CoordCache

Get mutable coordinate cache.

pub fn stats(&self) -> &NodeStats

Get the node statistics.

pub fn stats_history(&self) -> &StatsHistory

Get the stats history collector.

pub fn tun_state(&self) -> TunState

Get the TUN state.

pub fn tun_name(&self) -> Option<&str>

Get the TUN interface name, if active.

pub fn set_max_connections(&mut self, max: usize)

Set the maximum number of connections (handshake phase).

pub fn set_max_peers(&mut self, max: usize)

Set the maximum number of peers (authenticated).

pub fn set_max_links(&mut self, max: usize)

Set the maximum number of links.

pub fn connection_count(&self) -> usize

Number of pending connections (handshake in progress).

pub fn peer_count(&self) -> usize

Number of authenticated peers.

pub fn link_count(&self) -> usize

Number of active links.

pub fn transport_count(&self) -> usize

Number of active transports.

pub fn allocate_transport_id(&mut self) -> TransportId

Allocate a new transport ID.

pub fn get_transport(&self, id: &TransportId) -> Option<&TransportHandle>

Get a transport by ID.

pub fn get_transport_mut( &mut self, id: &TransportId, ) -> Option<&mut TransportHandle>

Get mutable transport by ID.

pub fn transport_ids(&self) -> impl Iterator<Item = &TransportId>

Iterate over transport IDs.

pub fn packet_rx(&mut self) -> Option<&mut PacketRx>

Get the packet receiver for the event loop.

pub fn allocate_link_id(&mut self) -> LinkId

Allocate a new link ID.

pub fn add_link(&mut self, link: Link) -> Result<(), NodeError>

Add a link.

pub fn get_link(&self, link_id: &LinkId) -> Option<&Link>

Get a link by ID.

pub fn get_link_mut(&mut self, link_id: &LinkId) -> Option<&mut Link>

Get a mutable link by ID.

pub fn find_link_by_addr( &self, transport_id: TransportId, addr: &TransportAddr, ) -> Option<LinkId>

Find link ID by transport address.

pub fn remove_link(&mut self, link_id: &LinkId) -> Option<Link>

Remove a link.

Only removes the addr_to_link reverse lookup if it still points to this link. In cross-connection scenarios, a newer link may have replaced the entry for the same address.

pub fn links(&self) -> impl Iterator<Item = &Link>

Iterate over all links.

pub fn add_connection( &mut self, connection: PeerConnection, ) -> Result<(), NodeError>

Add a pending connection.

pub fn get_connection(&self, link_id: &LinkId) -> Option<&PeerConnection>

Get a connection by LinkId.

pub fn get_connection_mut( &mut self, link_id: &LinkId, ) -> Option<&mut PeerConnection>

Get a mutable connection by LinkId.

pub fn remove_connection(&mut self, link_id: &LinkId) -> Option<PeerConnection>

Remove a connection.

pub fn connections(&self) -> impl Iterator<Item = &PeerConnection>

Iterate over all connections.

pub fn get_peer(&self, node_addr: &NodeAddr) -> Option<&ActivePeer>

Get a peer by NodeAddr.

pub fn get_peer_mut(&mut self, node_addr: &NodeAddr) -> Option<&mut ActivePeer>

Get a mutable peer by NodeAddr.

pub fn remove_peer(&mut self, node_addr: &NodeAddr) -> Option<ActivePeer>

Remove a peer.

pub fn peers(&self) -> impl Iterator<Item = &ActivePeer>

Iterate over all peers.

pub fn nostr_discovery_handle(&self) -> Option<&NostrDiscovery>

Reference to the Nostr discovery handle if discovery is enabled. Used by control queries (show_peers per-peer Nostr-traversal state) to read failure-state without taking shared ownership.

pub fn peer_ids(&self) -> impl Iterator<Item = &NodeAddr>

Iterate over all peer node IDs.

pub fn sendable_peers(&self) -> impl Iterator<Item = &ActivePeer>

Iterate over peers that can send traffic.

pub fn sendable_peer_count(&self) -> usize

Number of peers that can send traffic.

pub fn session_count(&self) -> usize

Number of end-to-end sessions.

pub fn identity_cache_len(&self) -> usize

Number of identity cache entries.

pub fn identity_cache_iter( &self, ) -> impl Iterator<Item = (&NodeAddr, &PublicKey, u64)>

Iterate over identity cache entries.

Returns (NodeAddr, PublicKey, last_seen_ms) for each cached identity. Used by the show_identity_cache control query.

pub fn identity_cache_max(&self) -> usize

Configured maximum identity cache size.

pub fn pending_lookup_count(&self) -> usize

Number of pending discovery lookups.

pub fn pending_lookups_iter( &self, ) -> impl Iterator<Item = (&NodeAddr, &PendingLookup)>

Iterate over pending discovery lookups for diagnostics.

pub fn recent_request_count(&self) -> usize

Number of recent discovery requests tracked.

pub fn pending_tun_destinations(&self) -> usize

Count of destinations with queued TUN packets awaiting session setup.

pub fn pending_tun_total_packets(&self) -> usize

Total TUN packets queued across all destinations.

pub fn retry_state_iter(&self) -> impl Iterator<Item = (&NodeAddr, &RetryState)>

Iterate over retry state for diagnostics.

pub fn find_next_hop( &mut self, dest_node_addr: &NodeAddr, ) -> Option<&ActivePeer>

Find next hop for a destination node address.

Routing priority:

1. Destination is self → None (local delivery)
2. Destination is a direct peer → that peer
3. Reply-learned routes in reply_learned mode. These are locally observed reverse paths, selected with weighted multipath plus periodic coordinate/tree exploration.
4. Bloom filter candidates with cached dest coords → among peers whose bloom filter contains the destination, pick the one that minimizes tree distance to the destination, with (link_cost, tree_distance_to_dest, node_addr) tie-breaking. The self-distance check ensures only peers strictly closer to the destination than us are considered (prevents routing loops).
5. Greedy tree routing fallback (requires cached dest coords)
6. No route → None

Both the bloom filter and tree routing paths require cached destination coordinates (checked in coord_cache). Without coordinates, the node cannot make loop-free forwarding decisions. The caller should signal CoordsRequired back to the source when None is returned for a non-local destination.

pub fn destination_in_filters(&self, dest: &NodeAddr) -> Vec<&ActivePeer>

Check if a destination is in any peer’s bloom filter.

pub fn tun_tx(&self) -> Option<&TunTx>

Get the TUN packet sender channel.

Returns None if TUN is not active or the node hasn’t been started.

pub fn attach_external_packet_io( &mut self, capacity: usize, ) -> Result<ExternalPacketIo, NodeError>

Attach app-owned packet I/O for embedded operation without a system TUN.

This must be called before Node::start and requires tun.enabled = false. Outbound packets sent to the returned sender are processed by the normal session pipeline. Inbound packets delivered by FIPS sessions are sent to the returned receiver with source attribution.

Trait Implementations

impl Debug for Node

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.