frid/crates/federation-net/README.md

# federation-net

`federation-net` is a generic Rust networking engine for equal peers, built on
[iroh](https://iroh.computer). It establishes authenticated QUIC connections
through NATs, exchanges typed application messages, and exposes direct byte
streams for additional protocols.

The crate contains no music or application database logic. Applications own
their message schema and persistent domain state.

## Capabilities

- Persistent Ed25519/iroh identity.
- Self-contained, versioned peer tickets.
- Optional peer rendezvous through BEP44 records in the BitTorrent Mainline
  DHT.
- Network and message-schema isolation during handshake.
- Typed bidirectional messages with bounded framing and backpressure.
- Application-defined ALPN byte streams.
- Connection path and traffic statistics.
- Graceful disconnect and shutdown events.

## Basic usage

```rust,no_run
use federation_net::{NetworkConfig, NetworkEngine, NetworkEvent, NetworkId, SchemaId};

#[derive(Debug, serde::Serialize, serde::Deserialize)]
enum Message {
    Ping { nonce: u64 },
}

# async fn run() -> federation_net::Result<()> {
let config = NetworkConfig::builder()
    .data_dir("./peer-a")
    .network_id(NetworkId::from_name("example-network"))
    .schema_id(SchemaId::from_name("example-message-v1"))
    .build()?;

let (engine, mut events) = NetworkEngine::<Message>::start(config).await?;
println!("share this ticket: {}", engine.ticket().await?);

while let Some(event) = events.recv().await {
    if let NetworkEvent::PeerConnected { peer_id, .. } = event {
        engine.send(peer_id, &Message::Ping { nonce: 1 }).await?;
    }
}

engine.shutdown().await
# }
```

## Network and schema IDs

`NetworkId` selects an independent peer network. `SchemaId` selects the wire
format of the application's typed messages. Both are checked during the
application handshake; peers with mismatched values are rejected before
domain messages are decoded.

Treat a backwards-incompatible message change as a schema change. Derive a new
schema ID instead of attempting to decode incompatible payloads under the old
identifier.

## Discovery

Rendezvous is optional. When enabled, peers publish signed, expiring endpoint
records into a network-specific BEP44 record in the public Mainline DHT. A
shared network ID is enough to discover current participants; no
Frid-operated registry is involved.

```rust,no_run
# use federation_net::{NetworkConfig, NetworkId, RendezvousConfig, SchemaId};
# fn config() -> federation_net::Result<()> {
let config = NetworkConfig::builder()
    .data_dir("./peer-a")
    .network_id(NetworkId::from_name("example-network"))
    .schema_id(SchemaId::from_name("example-message-v1"))
    .rendezvous(RendezvousConfig::default())
    .build()?;
# drop(config);
# Ok(())
# }
```

The rendezvous record is discoverable by anyone who knows the network ID. It
provides discovery, not authorization. Applications that need restricted
membership must implement and enforce that policy in their own protocol.

Without rendezvous, peers can connect through tickets and operate on isolated
networks.

## Byte streams

Applications may register additional ALPNs in `NetworkConfig` and accept or
open authenticated streams through the same endpoint. This is how higher
layers add catalog, audio, or synchronization protocols without putting large
payloads into the typed message channel.

## Events and backpressure

The bounded event channel reports connection, disconnection, decoded message,
and protocol-error events. Consumers must drain it continuously. The engine
applies backpressure instead of allowing unbounded memory growth.

Per-connection protocol failures are reported without stopping the engine.

## Verification

From the workspace root:

```bash
cargo test -p federation-net
cargo clippy -p federation-net --all-targets -- -D warnings
```