Struct PeerRegistry 

pub struct PeerRegistry<N: NetworkProvider + 'static> { /* private fields */ }

Manages peer state and WebSocket connections.

The PeerRegistry is the heart of Layer 5. It:

1. Tracks peers from Layer 3 discovery events — peers exist in the registry even with zero transport connections.
2. Manages lazy connections — the first send() to a peer triggers a WebSocket connection via Layer 4. Subsequent sends reuse the cached connection.
3. Routes messages — incoming messages from any peer are forwarded to subscribers via a broadcast channel.
4. Emits lifecycle events — PeerEvents for peer discovery changes and connection state changes.

Example

use std::sync::Arc;
use truffle_core::session::PeerRegistry;

let registry = PeerRegistry::new(network, ws_transport);
registry.start().await;

// Peers appear from Layer 3 discovery
let peers = registry.peers().await;

// First send lazily connects
registry.send("peer-id", b"hello").await?;

Implementations

impl<N: NetworkProvider + 'static> PeerRegistry<N>

pub fn new(network: Arc<N>, ws_transport: Arc<WebSocketTransport<N>>) -> Self

Create a new peer registry with default options (eager identity on).

• network: The Layer 3 network provider for peer discovery.
• ws_transport: The Layer 4 WebSocket transport for connections.

Call start() after creation to begin processing peer events and accepting incoming connections.

pub fn with_options( network: Arc<N>, ws_transport: Arc<WebSocketTransport<N>>, options: PeerRegistryOptions, ) -> Self

Create a peer registry with explicit options (RFC 022 Phase C).

pub async fn start(&self)

Start the peer registry.

This spawns two background tasks:

1. A task that subscribes to Layer 3 peer events and maintains the peer list (Joined/Left/Updated).
2. A task that listens for incoming WebSocket connections from peers and spawns connection tasks for each.

Call this once after constructing the registry.

pub async fn peers(&self) -> Vec<PeerState>

Return all known peers.

This returns peers discovered by Layer 3, including those with no active transport connections (ws_connected: false).

pub fn on_peer_change(&self) -> Receiver<PeerEvent>

Subscribe to peer change events.

Returns a broadcast receiver that yields PeerEvents for peer discovery changes (Joined/Left/Updated) and connection lifecycle changes (Connected/Disconnected).

pub async fn send(&self, peer_id: &str, data: &[u8]) -> Result<(), SessionError>

Send data to a specific peer.

If no WebSocket connection exists to the peer, one is lazily established via Layer 4. The connection is cached for subsequent sends. If the peer is unknown or offline, an error is returned.

Errors

• SessionError::UnknownPeer if the peer is not in the registry
• SessionError::PeerOffline if Layer 3 reports the peer as offline
• SessionError::ConnectFailed if the WS connection cannot be established
• SessionError::SendFailed if the send operation fails

pub async fn ensure_ws_connected( &self, peer_id: &str, ) -> Result<(), SessionError>

Ensure a WS session exists to peer_id (Tailscale routing key). Completes the RFC 017 hello and applies identity (RFC 022).

Used by app send and by eager-identity (Phase C). Idempotent when already connected.

pub async fn ensure_identity(&self, peer_id: &str) -> Result<(), SessionError>

One-shot identity exchange for an online peer (RFC 022 Phase C).

No-ops if identity is already published or the peer is offline.

pub async fn broadcast(&self, data: &[u8]) -> BroadcastReport

Broadcast data to all peers with active WebSocket connections.

Sends to all currently connected peers. Peers with no active connection are skipped (no lazy connect on broadcast). Errors from individual sends are logged but do not fail the broadcast.

pub fn subscribe(&self) -> Receiver<IncomingMessage>

Subscribe to incoming messages from any connected peer.

Returns a broadcast receiver that yields IncomingMessages. Messages include the sender’s peer ID and raw bytes — Layer 5 does not interpret the payload.

pub async fn disconnect(&self, peer_id: &str)

Disconnect a specific peer’s WebSocket connection.

Removes the cached connection and marks the peer as disconnected. Does not remove the peer from the registry (that only happens when Layer 3 emits a Left event).

pub async fn shutdown(&self)

Close all active WebSocket connections and mark every peer as disconnected. Called by Node::stop() during teardown. Safe to call multiple times — with no active connections it is a no-op.