Struct FipsEndpoint 

pub struct FipsEndpoint { /* private fields */ }

A running embedded FIPS endpoint.

Implementations

impl FipsEndpoint

pub fn builder() -> FipsEndpointBuilder

Create a builder for an embedded endpoint.

pub fn npub(&self) -> &str

Local endpoint npub.

pub fn node_addr(&self) -> &NodeAddr

Local FIPS node address.

pub fn address(&self) -> FipsAddress

Local FIPS IPv6-compatible address.

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

Application-level discovery scope, if configured.

pub async fn send( &self, remote_npub: impl Into<String>, data: impl Into<Vec<u8>>, ) -> Result<(), FipsEndpointError>

Send application-owned endpoint data to a remote npub.

Fire-and-forget: enqueues the Send command on the node task and returns once the command channel accepts it. The node task’s send result is discarded — TCP and the upper protocol handle loss recovery, and the per-packet oneshot round-trip the previous design used for error reporting added several hundred microseconds of queueing latency under load (measured: 456ms avg ping under iperf3 saturation → 1ms after this change, 430× lower).

PeerIdentity for remote_npub is cached after first resolution to avoid the secp256k1 EC point parse on every packet.

pub async fn recv(&self) -> Option<FipsEndpointMessage>

Receive the next source-attributed endpoint data message.

Translation from the internal NodeEndpointEvent::Data shape to the public FipsEndpointMessage shape happens inline here — the rx_loop pushes directly onto this channel, no relay task in between, no extra cross-task hop per packet.

pub fn blocking_send( &self, remote_npub: impl Into<String>, data: impl Into<Vec<u8>>, ) -> Result<(), FipsEndpointError>

Synchronous blocking send — parks the calling OS thread on the FIPS endpoint command channel until the runtime accepts the send. MUST be called only from a thread spawned via std::thread::spawn, not from inside a tokio runtime.

Companion to Self::blocking_recv for control-frame replies (e.g. responding to a Ping with a Pong) issued from the dedicated TUN-write thread. Failures are returned via FipsEndpointError::Closed if the runtime has stopped.

pub fn blocking_recv(&self) -> Option<FipsEndpointMessage>

Synchronous blocking receive — parks the calling OS thread on the channel until an event arrives or the channel closes.

MUST NOT be called from inside a tokio runtime; use this only from a thread spawned via std::thread::spawn so the tokio scheduler doesn’t deadlock.

The motivation is the bench’s CLI receive task: when run as a regular tokio task each recv().await is a full task-wake on the runtime (~1–3 µs scheduler bookkeeping), and at 113 kpps that’s ~10–30% of one core spent in plumbing the wake-up rather than writing the packet to TUN. A dedicated OS thread blocked on the channel via blocking_recv parks on a futex directly — the wake is a single futex_wake() with no scheduler involvement, an order of magnitude cheaper.

pub fn try_recv(&self) -> Option<FipsEndpointMessage>

Non-blocking receive — returns the next ready endpoint message if one is queued, otherwise None. Pair with recv() to drain follow-on packets without paying a scheduler wake per packet:

// wake on the first packet, then drain everything ready
while let Some(msg) = endpoint.recv().await { process(msg); }
while let Some(msg) = endpoint.try_recv() { process(msg); }

On the bench’s FIPS-tunnel receive path the kernel UDP socket delivers packets in recvmmsg-sized bursts, so after a .recv() await there are typically 5–30 packets queued waiting. Draining them inline with try_recv saves N-1 scheduler hops per burst at line rate, freeing the consumer task to spend its time on the TUN write syscall instead of cross-task plumbing.

Returns None if the channel is empty, closed, or briefly contested by another consumer.

pub async fn peers(&self) -> Result<Vec<FipsEndpointPeer>, FipsEndpointError>

Snapshot authenticated peers known by the endpoint.

pub async fn send_ip_packet( &self, packet: impl Into<Vec<u8>>, ) -> Result<(), FipsEndpointError>

Send an outbound IPv6 packet into the FIPS session pipeline.

pub async fn recv_ip_packet(&self) -> Option<NodeDeliveredPacket>

Receive the next source-attributed IPv6 packet delivered by FIPS.

pub async fn shutdown(self) -> Result<(), FipsEndpointError>

Shut down the endpoint and wait for the node task to stop.