Struct ActivePeer 

pub struct ActivePeer { /* private fields */ }

A fully authenticated remote FIPS node.

Created only after successful Noise KK handshake. The identity is cryptographically verified at this point.

Note: ActivePeer intentionally does not implement Clone because it contains NoiseSession, which cannot be safely cloned (cloning would risk nonce reuse, a catastrophic security failure).

Implementations

impl ActivePeer

pub fn new( identity: PeerIdentity, link_id: LinkId, authenticated_at: u64, ) -> Self

Create a new active peer from verified identity.

Called after successful authentication handshake. For peers with Noise sessions, use with_session instead.

pub fn with_stats( identity: PeerIdentity, link_id: LinkId, authenticated_at: u64, link_stats: LinkStats, ) -> Self

Create from verified identity with existing link stats.

Used when promoting from PeerConnection, preserving handshake stats. For peers with Noise sessions, use with_session instead.

pub fn with_session( identity: PeerIdentity, link_id: LinkId, authenticated_at: u64, noise_session: NoiseSession, our_index: SessionIndex, their_index: SessionIndex, transport_id: TransportId, current_addr: TransportAddr, link_stats: LinkStats, is_initiator: bool, mmp_config: &MmpConfig, remote_epoch: Option<[u8; 8]>, ) -> Self

Create from verified identity with Noise session and index tracking.

This is the primary constructor for the wire protocol path. The NoiseSession provides encryption/decryption and replay protection.

pub fn identity(&self) -> &PeerIdentity

Get the peer’s verified identity.

pub fn node_addr(&self) -> &NodeAddr

Get the peer’s NodeAddr.

pub fn address(&self) -> &FipsAddress

Get the peer’s FIPS address.

pub fn pubkey(&self) -> XOnlyPublicKey

Get the peer’s public key.

pub fn npub(&self) -> String

Get the peer’s npub string.

pub fn link_id(&self) -> LinkId

Get the link ID.

pub fn connectivity(&self) -> ConnectivityState

Get the connectivity state.

pub fn can_send(&self) -> bool

Check if peer can receive traffic.

pub fn is_healthy(&self) -> bool

Check if peer is fully healthy.

pub fn is_disconnected(&self) -> bool

Check if peer is disconnected.

pub fn has_session(&self) -> bool

Check if this peer has a Noise session.

pub fn noise_session(&self) -> Option<&NoiseSession>

Get the Noise session, if present.

pub fn noise_session_mut(&mut self) -> Option<&mut NoiseSession>

Get mutable access to the Noise session.

pub fn our_index(&self) -> Option<SessionIndex>

Get our session index (they use this to send TO us).

pub fn their_index(&self) -> Option<SessionIndex>

Get their session index (we use this to send TO them).

pub fn set_their_index(&mut self, index: SessionIndex)

Update their session index (used during cross-connection resolution when the losing node keeps its inbound session but needs the peer’s outbound index).

pub fn replace_session( &mut self, new_session: NoiseSession, new_our_index: SessionIndex, new_their_index: SessionIndex, ) -> Option<SessionIndex>

Replace the Noise session and indices during cross-connection resolution.

When both nodes simultaneously initiate, each promotes its inbound handshake first. When the peer’s msg2 arrives, we learn the correct session — the outbound handshake that pairs with the peer’s inbound. This replaces the entire session so both nodes use matching keys.

Returns the old our_index so the caller can update peers_by_index. Also resets the replay suppression counter since the session changed.

pub fn transport_id(&self) -> Option<TransportId>

Get the transport ID for this peer.

pub fn current_addr(&self) -> Option<&TransportAddr>

Get the current transport address.

pub fn set_current_addr( &mut self, transport_id: TransportId, addr: &TransportAddr, ) -> bool

Update the current address (for roaming support).

Called when we receive a valid authenticated packet from a new address. Short-circuits when neither the transport_id nor the TransportAddr bytes changed — at multi-Gbps the same peer’s source 4-tuple is stable per session and the overwhelming majority of inbound packets hit this fast path. Saves both the redundant Option::take + Vec drop on the cached side and the caller’s .clone() allocation on the input side: the caller can pass &TransportAddr and we only .to_owned() when storing.

Returns true iff the stored (transport_id, current_addr) pair actually changed. The caller uses this signal to invalidate derived caches whose validity is bound to the peer’s 5-tuple — in particular the Linux per-peer connect()-ed UDP socket, which is pinned to one kernel route + neighbour entry and goes stale the moment the peer roams. (Clearing it here would force &mut self users into the wrong shape: the policy of when to rebuild the connected socket lives on Node, not on the peer state. Returning a bool keeps that policy where it belongs.)

pub fn set_handshake_msg2(&mut self, msg2: Vec<u8>)

Store wire-format msg2 for resend on duplicate msg1.

pub fn handshake_msg2(&self) -> Option<&[u8]>

Get stored msg2 bytes for resend.

pub fn clear_handshake_msg2(&mut self)

Clear stored msg2 (no longer needed after handshake window).

pub fn increment_replay_suppressed(&mut self) -> u32

Increment replay suppression counter. Returns the new count.

pub fn reset_replay_suppressed(&mut self) -> u32

Reset replay suppression counter, returning previous count.

pub fn replay_suppressed_count(&self) -> u32

Current replay suppression count.

pub fn increment_decrypt_failures(&mut self) -> u32

Increment consecutive decryption failure counter, returning new count.

pub fn reset_decrypt_failures(&mut self)

Reset consecutive decryption failure counter.

pub fn consecutive_decrypt_failures(&self) -> u32

Current consecutive decryption failure count.

pub fn remote_epoch(&self) -> Option<[u8; 8]>

Get the remote peer’s startup epoch (from handshake).

pub fn coords(&self) -> Option<&TreeCoordinate>

Get the peer’s tree coordinates, if known.

pub fn declaration(&self) -> Option<&ParentDeclaration>

Get the peer’s parent declaration, if known.

pub fn has_tree_position(&self) -> bool

Check if this peer has a known tree position.

pub fn inbound_filter(&self) -> Option<&BloomFilter>

Get the peer’s inbound filter, if known.

pub fn filter_sequence(&self) -> u64

Get the filter sequence number.

pub fn filter_is_stale( &self, current_time_ms: u64, stale_threshold_ms: u64, ) -> bool

Check if this peer’s filter is stale.

pub fn may_reach(&self, node_addr: &NodeAddr) -> bool

Check if a destination might be reachable through this peer.

pub fn needs_filter_update(&self) -> bool

Check if we need to send this peer a filter update.

pub fn link_stats(&self) -> &LinkStats

Get link statistics.

pub fn link_stats_mut(&mut self) -> &mut LinkStats

Get mutable link statistics.

pub fn mmp(&self) -> Option<&MmpPeerState>

Get MMP state (None for legacy peers without sessions).

pub fn mmp_mut(&mut self) -> Option<&mut MmpPeerState>

Get mutable MMP state.

pub fn link_cost(&self) -> f64

Link cost for routing decisions.

Returns a scalar cost where lower is better (1.0 = ideal). Computed as RTT-weighted ETX: etx * (1.0 + srtt_ms / 100.0).

Returns 1.0 (optimistic default) when MMP metrics are not yet available, matching depth-only parent selection behavior.

pub fn has_srtt(&self) -> bool

Whether this peer has at least one MMP RTT measurement.

pub fn authenticated_at(&self) -> u64

When this peer was authenticated.

pub fn last_seen(&self) -> u64

When this peer was last seen.

pub fn idle_time(&self, current_time_ms: u64) -> u64

Time since last activity.

pub fn connection_duration(&self, current_time_ms: u64) -> u64

Connection duration since authentication.

pub fn session_elapsed_ms(&self) -> u32

Session-relative elapsed time in milliseconds (for inner header timestamp).

Returns milliseconds since session establishment, truncated to u32. Wraps at ~49.7 days which is acceptable for session-relative timing.

pub fn session_start(&self) -> Instant

When this peer’s session started (for link-dead fallback timing).

pub fn last_heartbeat_sent(&self) -> Option<Instant>

When we last sent a heartbeat to this peer.

pub fn mark_heartbeat_sent(&mut self, now: Instant)

Record that we sent a heartbeat.

pub fn touch(&mut self, current_time_ms: u64)

Update last seen timestamp.

pub fn mark_stale(&mut self)

Mark peer as stale (no recent traffic).

pub fn mark_reconnecting(&mut self)

Mark peer as reconnecting.

pub fn mark_disconnected(&mut self)

Mark peer as disconnected.

pub fn mark_connected(&mut self, current_time_ms: u64)

Mark peer as connected (e.g., after successful reconnect).

pub fn set_link_id(&mut self, link_id: LinkId)

Update the link ID (e.g., on reconnect).

pub fn update_tree_position( &mut self, declaration: ParentDeclaration, ancestry: TreeCoordinate, current_time_ms: u64, )

Update peer’s tree position.

pub fn clear_tree_position(&mut self)

Clear peer’s tree position.

pub fn set_tree_announce_min_interval_ms(&mut self, ms: u64)

Set the minimum interval between TreeAnnounce messages (milliseconds).

pub fn last_tree_announce_sent_ms(&self) -> u64

Get the last tree announce send timestamp (for carrying across reconnection).

pub fn set_last_tree_announce_sent_ms(&mut self, ms: u64)

Set the last tree announce send timestamp (to preserve rate limit across reconnection).

pub fn can_send_tree_announce(&self, now_ms: u64) -> bool

Check if we can send a TreeAnnounce now (rate limiting).

pub fn record_tree_announce_sent(&mut self, now_ms: u64)

Record that we sent a TreeAnnounce to this peer.

pub fn mark_tree_announce_pending(&mut self)

Mark that a tree announce is pending (deferred due to rate limit).

pub fn has_pending_tree_announce(&self) -> bool

Check if a deferred tree announce is waiting to be sent.

pub fn update_filter( &mut self, filter: BloomFilter, sequence: u64, current_time_ms: u64, )

Update peer’s inbound filter.

pub fn clear_filter(&mut self)

Clear peer’s inbound filter.

pub fn mark_filter_update_needed(&mut self)

Mark that we need to send this peer a filter update.

pub fn clear_filter_update_needed(&mut self)

Clear the pending filter update flag.

pub fn session_established_at(&self) -> Instant

When the current Noise session was established.

pub fn current_k_bit(&self) -> bool

Current K-bit epoch value.

pub fn rekey_in_progress(&self) -> bool

Whether a rekey is currently in progress.

pub fn set_rekey_in_progress(&mut self)

Mark that a rekey has been initiated.

pub fn is_rekey_dampened(&self, dampening_secs: u64) -> bool

Check if rekey initiation is dampened (peer recently sent us msg1).

pub fn record_peer_rekey(&mut self)

Record that the peer initiated a rekey (for dampening).

pub fn pending_our_index(&self) -> Option<SessionIndex>

Get the pending new session’s our_index.

pub fn pending_their_index(&self) -> Option<SessionIndex>

Get the pending new session’s their_index.

pub fn previous_our_index(&self) -> Option<SessionIndex>

Get the previous session’s our_index (during drain).

pub fn previous_session(&self) -> Option<&NoiseSession>

Get the previous session for decryption fallback.

pub fn previous_session_mut(&mut self) -> Option<&mut NoiseSession>

Get mutable access to the previous session for decryption.

pub fn pending_new_session(&self) -> Option<&NoiseSession>

Get the pending new session (completed rekey, not yet cut over).

pub fn set_pending_session( &mut self, session: NoiseSession, our_index: SessionIndex, their_index: SessionIndex, )

Store a completed rekey session and its indices.

Called when the rekey handshake completes. The session is held as pending until the initiator flips the K-bit on the next outbound packet.

pub fn cutover_to_new_session(&mut self) -> Option<SessionIndex>

Cut over to the pending new session (initiator side).

Moves current session to previous (for drain), promotes pending to current, flips the K-bit. Returns the old our_index that should remain in peers_by_index during the drain window.

pub fn handle_peer_kbit_flip(&mut self) -> Option<SessionIndex>

Handle receiving a K-bit flip from the peer (responder side).

Promotes pending_new_session to current, demotes current to previous. Returns the old our_index for drain tracking.

pub fn drain_expired(&self, drain_secs: u64) -> bool

Check if the drain window has expired.

pub fn is_draining(&self) -> bool

Whether a drain is in progress.

pub fn complete_drain(&mut self) -> Option<SessionIndex>

Complete the drain: drop previous session and free its index.

Returns the previous our_index so the caller can remove it from peers_by_index and free it from the IndexAllocator.

pub fn abandon_rekey(&mut self) -> Option<SessionIndex>

Abandon an in-progress rekey.

Returns the rekey our_index so the caller can free it. Also clears any pending session state if the handshake was completed but not yet cut over.

pub fn set_rekey_state( &mut self, handshake: NoiseHandshakeState, our_index: SessionIndex, wire_msg1: Vec<u8>, next_resend_ms: u64, )

Store rekey handshake state after sending msg1.

pub fn rekey_our_index(&self) -> Option<SessionIndex>

Get the rekey our_index (for msg2 dispatch lookup).

pub fn complete_rekey_msg2( &mut self, msg2_bytes: &[u8], ) -> Result<NoiseSession, NoiseError>

Complete the rekey by processing msg2 (initiator side).

Takes the stored handshake state, reads msg2, and returns the completed NoiseSession. Clears the handshake-related fields but leaves rekey_our_index for set_pending_session to use.

pub fn needs_msg1_resend(&self, now_ms: u64) -> bool

Check if msg1 needs resending.

pub fn rekey_msg1(&self) -> Option<&[u8]>

Get msg1 bytes for resend (without consuming).

pub fn set_msg1_next_resend(&mut self, next_ms: u64)

Update next resend timestamp.

Trait Implementations

impl Debug for ActivePeer

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

Formats the value using the given formatter.