Rename the CLI package to tsunagi and its executable to tsng

The command line package is now `tsunagi` and builds the `tsng` executable,
which the packages, the unit, the installers and the workflows install and
run. The core library package becomes `tsunagi-core`, keeping the library name
`tsunagi`, so no code changes `use tsunagi::...`. Directories follow
(crates/tsunagi-core, crates/tsunagi). Every command shown to a person is now
`tsng ...`.

Co-Authored-By: Claude <noreply@anthropic.com>

crates/tsunagi-core/src/dataplane/mod.rs

@@ -0,0 +1,496 @@
+//! Boundary between the control plane core and future IP plugins.
+//!
+//! The data plane is where actual IP connectivity is created. WireGuard is the
+//! first planned plugin; none is implemented here.
+//!
+//! Two rules shape this module:
+//!
+//! 1. **The core never parses plugin payloads.** A [`PluginCapability`] carries
+//!    a protocol id, a version, an enabled flag and a bounded opaque blob. The
+//!    core transports the blob and hands it to the matching plugin. It does not
+//!    know what a WireGuard configuration looks like.
+//! 2. **Plugin keys and lifecycle are separate from iroh identity and from the
+//!    network secret.** A plugin owns its own keys and its own system objects.
+//!
+//! An iroh address is *not* automatically a WireGuard address. A future plugin
+//! is expected to gather its own reachability information and ship it through
+//! the control plane as its announcement payload.
+//!
+//! A data plane failure never stops the daemon: errors returned here are
+//! recorded and surfaced, the control plane keeps running.
+
+pub mod relay;
+pub mod routing;
+pub mod transport;
+pub mod tunnel;
+
+use std::sync::Arc;
+
+use iroh::EndpointId;
+use tokio::sync::mpsc;
+
+use crate::BoxFuture;
+use crate::identity::NetworkId;
+
+pub use transport::{
+    MultiPacketTransport, PacketLink, PacketTransport, SharedLink, TransportError,
+};
+pub use tunnel::{GenericTunnelPlugin, TunnelCodec};
+
+/// Maximum length of a plugin protocol identifier.
+pub const MAX_PROTOCOL_ID_LEN: usize = 32;
+
+/// An announcement of one IP plugin's capability.
+///
+/// `data` is opaque to the core. Nothing in it may be interpreted as a shell
+/// command, a filesystem path or an OS setting by the core; a plugin that
+/// chooses to do so must validate it itself.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct PluginCapability {
+    /// Protocol identifier, e.g. `wg-quic`. Bounded by [`MAX_PROTOCOL_ID_LEN`].
+    pub protocol: String,
+    /// Version of the plugin's announcement format.
+    pub version: u16,
+    /// Whether the peer currently has this plugin enabled.
+    pub enabled: bool,
+    /// Opaque, bounded, plugin-defined payload.
+    pub data: Vec<u8>,
+}
+
+/// Where a protocol hands the packets it has decrypted.
+///
+/// A protocol proves *who* sent a packet; it does not know what that member
+/// is entitled to say, because entitlement is an address claim the system
+/// level holds. So a decrypted packet goes here rather than straight to an
+/// interface, and is checked on the way.
+pub trait PacketSink: Send + Sync + 'static {
+    /// Hands over one packet, attributed to the peer whose tunnel decrypted
+    /// it.
+    fn deliver<'a>(
+        &'a self,
+        network: NetworkId,
+        peer: EndpointId,
+        packet: bytes::Bytes,
+    ) -> BoxFuture<'a, ()>;
+}
+
+/// A sink that drops everything, for a protocol running without an interface.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct DiscardPackets;
+
+impl PacketSink for DiscardPackets {
+    fn deliver<'a>(
+        &'a self,
+        _network: NetworkId,
+        _peer: EndpointId,
+        _packet: bytes::Bytes,
+    ) -> BoxFuture<'a, ()> {
+        Box::pin(async move {})
+    }
+}
+
+/// One setting a protocol accepts.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ProtocolOption {
+    /// The key, as written in `key=value`.
+    pub key: &'static str,
+    /// A word for the value, for the help line: `BYTES`, `NAME`.
+    pub value: &'static str,
+    /// What it does.
+    pub help: &'static str,
+    /// What happens when it is not given.
+    pub default: Option<&'static str>,
+}
+
+/// Errors a plugin may return. They are recorded, never fatal for the agent.
+#[derive(Debug, thiserror::Error)]
+#[non_exhaustive]
+pub enum PluginError {
+    /// The plugin is not currently able to produce or apply configuration.
+    #[error("plugin unavailable: {0}")]
+    Unavailable(String),
+    /// A peer announcement was not acceptable to the plugin.
+    #[error("rejected peer announcement: {0}")]
+    Rejected(String),
+    /// Anything else.
+    #[error("plugin error: {0}")]
+    Other(String),
+}
+
+/// A request a plugin makes of the agent that owns it.
+#[derive(Debug)]
+pub enum PluginRequest {
+    /// Re-send this agent's announcement to every peer of a network.
+    Reannounce(NetworkId),
+    /// Surface a plugin error on the agent's event stream.
+    Error {
+        /// Network the error is scoped to.
+        network: NetworkId,
+        /// Plugin protocol id.
+        protocol: String,
+        /// Human readable reason, free of secrets.
+        reason: String,
+    },
+    /// A plugin reported that a data link or tunnel for a peer failed.
+    ProtocolFailure {
+        /// Network the failure occurred in.
+        network: NetworkId,
+        /// Peer whose protocol failed.
+        peer: EndpointId,
+        /// Protocol that failed.
+        protocol: String,
+        /// Human readable reason.
+        reason: String,
+    },
+}
+
+/// The agent-side handle a plugin is given when it is attached.
+///
+/// It is deliberately tiny: a plugin may ask for its announcement to be resent
+/// and may report an error. It cannot reach into agent state, cannot send
+/// arbitrary control messages and knows nothing about sessions.
+///
+/// All calls are non-blocking. If the agent is gone or its queue is full the
+/// request is dropped rather than stalling the plugin.
+#[derive(Clone)]
+pub struct PluginContext {
+    sender: Option<mpsc::Sender<PluginRequest>>,
+    local: Option<EndpointId>,
+    /// Where decrypted packets go. Absent when nothing is carrying traffic,
+    /// in which case a protocol still runs and its packets are discarded.
+    sink: Option<Arc<dyn PacketSink>>,
+}
+
+impl PluginContext {
+    pub(crate) fn new(
+        sender: mpsc::Sender<PluginRequest>,
+        local: EndpointId,
+        sink: Option<Arc<dyn PacketSink>>,
+    ) -> Self {
+        Self {
+            sender: Some(sender),
+            local: Some(local),
+            sink,
+        }
+    }
+
+    /// Where to hand a decrypted packet.
+    ///
+    /// Always answers: with no interface to write to, the packets are
+    /// discarded, which is what `--no-tun` means and is not an error.
+    pub fn packet_sink(&self) -> Arc<dyn PacketSink> {
+        match &self.sink {
+            Some(sink) => Arc::clone(sink),
+            None => Arc::new(DiscardPackets),
+        }
+    }
+
+    /// A context that discards everything, for plugins used outside an agent.
+    pub fn detached() -> Self {
+        Self {
+            sender: None,
+            local: None,
+            sink: None,
+        }
+    }
+
+    /// A context configured with a custom packet sink.
+    pub fn with_sink(sink: Arc<dyn PacketSink>) -> Self {
+        Self {
+            sender: None,
+            local: None,
+            sink: Some(sink),
+        }
+    }
+
+    /// A context configured with a channel for plugin requests and custom sink, for tests.
+    #[cfg(feature = "testing")]
+    pub fn for_test(
+        sender: mpsc::Sender<PluginRequest>,
+        local: EndpointId,
+        sink: Option<Arc<dyn PacketSink>>,
+    ) -> Self {
+        Self {
+            sender: Some(sender),
+            local: Some(local),
+            sink,
+        }
+    }
+
+    /// This agent's own endpoint id, when the context is attached.
+    ///
+    /// A plugin needs it to find itself in the agreed allocation.
+    pub fn local_endpoint_id(&self) -> Option<EndpointId> {
+        self.local
+    }
+
+    fn send(&self, request: PluginRequest) {
+        let Some(sender) = &self.sender else {
+            return;
+        };
+        if let Err(err) = sender.try_send(request) {
+            tracing::debug!(%err, "dropping plugin request");
+        }
+    }
+
+    /// Asks the agent to resend this agent's announcement in `network`.
+    ///
+    /// A plugin calls this when its own capability changed — it finished
+    /// starting up, its keys or reachability changed — so that peers learn the
+    /// new value without waiting for a reconnect.
+    pub fn request_reannounce(&self, network: NetworkId) {
+        self.send(PluginRequest::Reannounce(network));
+    }
+
+    /// Reports a plugin error on the agent's event stream.
+    ///
+    /// Plugin work happens in the plugin's own tasks, so errors cannot always
+    /// be returned from a trait call. They are never fatal for the agent.
+    pub fn report_error(
+        &self,
+        network: NetworkId,
+        protocol: impl Into<String>,
+        reason: impl Into<String>,
+    ) {
+        self.send(PluginRequest::Error {
+            network,
+            protocol: protocol.into(),
+            reason: reason.into(),
+        });
+    }
+
+    /// Reports that data plane connectivity or a tunnel for a peer has failed.
+    pub fn report_peer_protocol_failure(
+        &self,
+        network: NetworkId,
+        peer: EndpointId,
+        protocol: impl Into<String>,
+        reason: impl Into<String>,
+    ) {
+        self.send(PluginRequest::ProtocolFailure {
+            network,
+            peer,
+            protocol: protocol.into(),
+            reason: reason.into(),
+        });
+    }
+}
+
+impl std::fmt::Debug for PluginContext {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("PluginContext")
+            .field("attached", &self.sender.is_some())
+            .field("local", &self.local.map(|id| id.fmt_short().to_string()))
+            .finish()
+    }
+}
+
+/// The contract an IP plugin implements.
+///
+/// Implementations must be cheap and non-blocking: the agent calls them from
+/// its runtime tasks. Anything slow belongs in the plugin's own tasks.
+pub trait IpPlugin: Send + Sync + std::fmt::Debug + 'static {
+    /// Stable protocol identifier, e.g. `wg-quic`.
+    ///
+    /// Must be non-empty and at most [`MAX_PROTOCOL_ID_LEN`] bytes.
+    fn protocol_id(&self) -> &str;
+
+    /// The wire version of this protocol.
+    ///
+    /// Two peers carry traffic for each other only when they have the same
+    /// protocol at the same version. There is no negotiating a middle
+    /// ground: a protocol either speaks the same words at both ends or it
+    /// does not, and pretending otherwise produces a link that fails later
+    /// and less clearly.
+    ///
+    /// **Not the software version.** A plugin crate has its own version and
+    /// it is nobody else's business: two peers on different builds work
+    /// together for as long as the wire between them has not changed. This
+    /// number moves only when the bytes do, so it must never be derived from
+    /// `CARGO_PKG_VERSION` or anything else that moves with a release.
+    fn protocol_version(&self) -> u16;
+
+    /// The settings this protocol accepts, and what they mean.
+    ///
+    /// Declared rather than documented elsewhere, so the agent can list them
+    /// without knowing anything about the protocol.
+    fn options(&self) -> &'static [ProtocolOption] {
+        &[]
+    }
+
+    /// Called once, when the agent starts, before any network is activated.
+    ///
+    /// The plugin keeps the context to ask for re-announcements and to report
+    /// errors that happen in its own tasks.
+    fn attach(&self, context: PluginContext) {
+        let _ = context;
+    }
+
+    /// Produces this agent's announcement for a given network.
+    ///
+    /// Returning `Ok(None)` means "nothing to announce right now", which is
+    /// different from an error.
+    fn local_capability(
+        &self,
+        network: NetworkId,
+    ) -> std::result::Result<Option<PluginCapability>, PluginError>;
+
+    /// Called when a network is activated locally, before any peer appears.
+    ///
+    /// A plugin uses it to get its per-network state ready, so that the first
+    /// announcement already carries its capability.
+    fn on_network_activated(&self, network: NetworkId) {
+        let _ = network;
+    }
+
+    /// Called when a peer announces a capability for this plugin's protocol.
+    ///
+    /// The core has already bounded the payload size but has not interpreted it.
+    fn on_peer_capability(
+        &self,
+        network: NetworkId,
+        peer: EndpointId,
+        capability: &PluginCapability,
+    ) -> std::result::Result<(), PluginError>;
+
+    /// The overlay addresses the network has agreed on.
+    ///
+    /// Allocated rather than derived, and backed by the signed records in
+    /// [`crate::state`], so a participant keeps its address across restarts
+    /// and long absences. Called whenever the agreed picture changes.
+    fn on_address_allocation(
+        &self,
+        network: NetworkId,
+        range: crate::state::Ipv4Range,
+        allocations: &[(EndpointId, std::net::Ipv4Addr)],
+    ) {
+        let _ = (network, range, allocations);
+    }
+
+    /// Carries one packet to a peer, encrypting it however this protocol
+    /// does.
+    ///
+    /// `false` when it cannot right now — no link, no tunnel, not this
+    /// protocol's peer — which the caller reports rather than treats as an
+    /// error. The packet came off the one interface the agent owns, and
+    /// which protocol takes it is settled by asking.
+    ///
+    /// The default carries nothing, which is right for a plugin that only
+    /// announces something.
+    fn carry(&self, _network: NetworkId, _peer: EndpointId, _packet: bytes::Bytes) -> bool {
+        false
+    }
+
+    /// A data plane link to a peer is available for this plugin's protocol.
+    ///
+    /// The plugin moves its packets over this link and never learns how the
+    /// link is carried. A new link for a peer replaces any previous one.
+    fn on_peer_link(&self, network: NetworkId, peer: EndpointId, link: SharedLink) {
+        let _ = (network, peer, link);
+    }
+
+    /// Called when a peer's session in a network goes away.
+    ///
+    /// Any link handed to the plugin for that peer must be dropped here.
+    fn on_peer_gone(&self, network: NetworkId, peer: EndpointId);
+
+    /// Called when a network is deactivated locally.
+    ///
+    /// This is a local deactivation, not a signed revocation of membership.
+    /// The plugin is expected to remove whatever it created for that network.
+    fn on_network_deactivated(&self, network: NetworkId);
+
+    /// Called when this agent has left a network for good.
+    ///
+    /// Deactivation is temporary and keeps everything ready for next time;
+    /// this is the other one. Whatever the plugin holds *durably* for that
+    /// network — a key of its own, a file, a record — goes now, because the
+    /// agent is no longer a member and keeping it is keeping a secret for a
+    /// network it cannot rejoin without being told the secret again.
+    ///
+    /// Always preceded by [`IpPlugin::on_network_deactivated`], so this is
+    /// only about what outlives a session. Defaulted to nothing, for a
+    /// plugin that stores nothing.
+    fn on_network_forgotten(&self, _network: NetworkId) {}
+
+    /// Called once when the agent shuts down.
+    ///
+    /// The plugin removes the system objects it created and stops its tasks.
+    /// It must be bounded: the agent awaits it during shutdown.
+    fn shutdown<'a>(&'a self) -> BoxFuture<'a, ()> {
+        Box::pin(async {})
+    }
+}
+
+/// A shared handle to a plugin.
+pub type SharedPlugin = Arc<dyn IpPlugin>;
+
+/// A plugin used in tests and examples.
+///
+/// It announces an explicitly test-only protocol id, so nothing in this crate
+/// ever advertises WireGuard as an available transport before it exists.
+#[derive(Debug)]
+pub struct TestCapabilityPlugin {
+    protocol: String,
+    payload: Vec<u8>,
+    seen: std::sync::Mutex<Vec<(NetworkId, EndpointId, PluginCapability)>>,
+}
+
+impl TestCapabilityPlugin {
+    /// Creates a plugin announcing `protocol` with a fixed opaque payload.
+    pub fn new(protocol: impl Into<String>, payload: impl Into<Vec<u8>>) -> Self {
+        Self {
+            protocol: protocol.into(),
+            payload: payload.into(),
+            seen: std::sync::Mutex::new(Vec::new()),
+        }
+    }
+
+    /// Returns everything this plugin was handed so far.
+    pub fn observed(&self) -> Vec<(NetworkId, EndpointId, PluginCapability)> {
+        match self.seen.lock() {
+            Ok(guard) => guard.clone(),
+            Err(poisoned) => poisoned.into_inner().clone(),
+        }
+    }
+}
+
+impl IpPlugin for TestCapabilityPlugin {
+    fn protocol_id(&self) -> &str {
+        &self.protocol
+    }
+
+    fn protocol_version(&self) -> u16 {
+        1
+    }
+
+    fn local_capability(
+        &self,
+        _network: NetworkId,
+    ) -> std::result::Result<Option<PluginCapability>, PluginError> {
+        Ok(Some(PluginCapability {
+            protocol: self.protocol.clone(),
+            version: 1,
+            enabled: true,
+            data: self.payload.clone(),
+        }))
+    }
+
+    fn on_peer_capability(
+        &self,
+        network: NetworkId,
+        peer: EndpointId,
+        capability: &PluginCapability,
+    ) -> std::result::Result<(), PluginError> {
+        let mut guard = match self.seen.lock() {
+            Ok(guard) => guard,
+            Err(poisoned) => poisoned.into_inner(),
+        };
+        guard.push((network, peer, capability.clone()));
+        Ok(())
+    }
+
+    fn on_peer_gone(&self, _network: NetworkId, _peer: EndpointId) {}
+
+    fn on_network_deactivated(&self, _network: NetworkId) {}
+}

crates/tsunagi-core/src/dataplane/relay.rs

@@ -0,0 +1,506 @@
+//! Userspace forwarding. Topology updates publish immutable tables; the packet
+//! path takes no routing mutex, walks no graph and never inspects plugin bytes.
+//! Each transport reader forwards transit immediately, independently of the
+//! destination protocol's receive task. Only local delivery enters its inbox.
+
+use std::collections::{HashMap, HashSet};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::{Arc, Mutex};
+
+use arc_swap::ArcSwap;
+use bytes::Bytes;
+use iroh::EndpointId;
+use tokio::sync::{Notify, mpsc, watch};
+use tokio::task::JoinHandle;
+
+use super::routing::{FlowId, PeerId, RoutingTable, envelope, mix64};
+use super::transport::{PacketLink, SharedLink, TransportError};
+use crate::BoxFuture;
+use crate::config::{MAX_DATA_DATAGRAM, ROUTING_HOP_LIMIT};
+use crate::identity::NetworkId;
+
+/// Fixed routing header, subtracted from the logical transport MTU.
+pub const RELAY_OVERHEAD: usize = envelope::HEADER;
+const INBOX: usize = 256;
+
+/// Forwarding counters, shared by all protocols of one network.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct RelayCounters {
+    /// Datagrams originated here and sent through another member.
+    pub sent_via: u64,
+    /// Transit datagrams handed to the next transport link.
+    pub forwarded: u64,
+    /// Local datagrams received through another member.
+    pub received_via: u64,
+    /// Missing or failed next hop.
+    pub dropped_no_link: u64,
+    /// Malformed envelope or unknown member.
+    pub dropped_unknown: u64,
+    /// Exhausted hop limit, including loops during topology convergence.
+    pub dropped_hop_limit: u64,
+    /// Full local protocol inbox. Transit does not use this queue.
+    pub dropped_congested: u64,
+}
+
+#[derive(Debug, Default)]
+struct Tally {
+    sent_via: AtomicU64,
+    forwarded: AtomicU64,
+    received_via: AtomicU64,
+    dropped_no_link: AtomicU64,
+    dropped_unknown: AtomicU64,
+    dropped_hop_limit: AtomicU64,
+    dropped_congested: AtomicU64,
+}
+
+impl Tally {
+    fn snapshot(&self) -> RelayCounters {
+        RelayCounters {
+            sent_via: self.sent_via.load(Ordering::Relaxed),
+            forwarded: self.forwarded.load(Ordering::Relaxed),
+            received_via: self.received_via.load(Ordering::Relaxed),
+            dropped_no_link: self.dropped_no_link.load(Ordering::Relaxed),
+            dropped_unknown: self.dropped_unknown.load(Ordering::Relaxed),
+            dropped_hop_limit: self.dropped_hop_limit.load(Ordering::Relaxed),
+            dropped_congested: self.dropped_congested.load(Ordering::Relaxed),
+        }
+    }
+}
+
+#[derive(Debug)]
+struct NextHop {
+    peer: PeerId,
+    link: SharedLink,
+}
+
+#[derive(Debug)]
+struct ForwardRoute {
+    hops: u8,
+    next: Box<[NextHop]>,
+}
+
+impl ForwardRoute {
+    fn select(&self, source: &PeerId, flow: FlowId) -> Option<&NextHop> {
+        if self.next.len() == 1 {
+            return self.next.first().filter(|hop| !hop.link.is_closed());
+        }
+        let seed = u64::from_le_bytes(source[..8].try_into().ok()?);
+        let start = mix64(flow ^ seed) as usize % self.next.len();
+        // Stable fallback if a link closed just before its table was replaced.
+        (0..self.next.len())
+            .map(|i| &self.next[(start + i) % self.next.len()])
+            .find(|hop| !hop.link.is_closed())
+    }
+}
+
+#[derive(Debug, Default)]
+struct ForwardingTable {
+    routes: HashMap<PeerId, ForwardRoute>,
+    inboxes: HashMap<PeerId, mpsc::Sender<Bytes>>,
+    members: HashSet<PeerId>,
+}
+
+#[derive(Debug)]
+struct Plane {
+    local: PeerId,
+    table: ArcSwap<ForwardingTable>,
+    tally: Arc<Tally>,
+}
+
+impl Plane {
+    /// Synchronous hot path: one snapshot, bounded header decode, table lookup,
+    /// and transport send. An exclusively owned buffer is modified in place.
+    fn receive(&self, incoming: PeerId, frame: Bytes) {
+        let Some(header) = envelope::decode(&frame) else {
+            self.tally.dropped_unknown.fetch_add(1, Ordering::Relaxed);
+            return;
+        };
+        let table = self.table.load();
+        if !table.members.contains(&header.source) || header.source == self.local {
+            self.tally.dropped_unknown.fetch_add(1, Ordering::Relaxed);
+            return;
+        }
+        if header.destination == self.local {
+            let Some(inbox) = table.inboxes.get(&header.source) else {
+                self.tally.dropped_unknown.fetch_add(1, Ordering::Relaxed);
+                return;
+            };
+            if inbox.try_send(frame.slice(RELAY_OVERHEAD..)).is_err() {
+                self.tally.dropped_congested.fetch_add(1, Ordering::Relaxed);
+            } else if incoming != header.source {
+                self.tally.received_via.fetch_add(1, Ordering::Relaxed);
+            }
+            return;
+        }
+        if header.remaining <= 1 {
+            self.tally.dropped_hop_limit.fetch_add(1, Ordering::Relaxed);
+            return;
+        }
+        let hop = table
+            .routes
+            .get(&header.destination)
+            .and_then(|route| route.select(&header.source, header.flow));
+        let Some(hop) = hop else {
+            self.tally.dropped_no_link.fetch_add(1, Ordering::Relaxed);
+            return;
+        };
+        if hop.link.send(envelope::decrement(frame)).is_ok() {
+            self.tally.forwarded.fetch_add(1, Ordering::Relaxed);
+        } else {
+            self.tally.dropped_no_link.fetch_add(1, Ordering::Relaxed);
+        }
+    }
+}
+
+#[derive(Debug)]
+struct Protocol {
+    plane: Arc<Plane>,
+    graph: HashMap<PeerId, Vec<PeerId>>,
+    members: HashSet<PeerId>,
+    raw: HashMap<PeerId, SharedLink>,
+    readers: HashMap<PeerId, JoinHandle<()>>,
+    links: HashMap<PeerId, Arc<PeerLink>>,
+}
+
+impl Protocol {
+    fn publish(&self) {
+        let mut graph = self.graph.clone();
+        graph.insert(
+            self.plane.local,
+            self.raw
+                .iter()
+                .filter(|(_, link)| !link.is_closed())
+                .map(|(peer, _)| *peer)
+                .collect(),
+        );
+        let routing = RoutingTable::build(self.plane.local, &graph, ROUTING_HOP_LIMIT);
+        let routes = routing
+            .iter()
+            .filter_map(|(peer, route)| {
+                let next: Box<[_]> = route
+                    .next_hops
+                    .iter()
+                    .filter_map(|id| {
+                        self.raw.get(id).map(|link| NextHop {
+                            peer: *id,
+                            link: link.clone(),
+                        })
+                    })
+                    .collect();
+                (!next.is_empty()).then_some((
+                    *peer,
+                    ForwardRoute {
+                        hops: route.hops,
+                        next,
+                    },
+                ))
+            })
+            .collect();
+        let mut members = self.members.clone();
+        members.extend(self.raw.keys().copied());
+        self.plane.table.store(Arc::new(ForwardingTable {
+            routes,
+            members,
+            inboxes: self
+                .links
+                .iter()
+                .map(|(peer, link)| (*peer, link.inbox_tx.clone()))
+                .collect(),
+        }));
+    }
+}
+
+impl Drop for Protocol {
+    fn drop(&mut self) {
+        for task in self.readers.values() {
+            task.abort();
+        }
+        for link in self.links.values() {
+            link.close();
+        }
+        self.plane.table.store(Arc::default());
+    }
+}
+
+/// One network's transport links and independently published protocol tables.
+#[derive(Debug)]
+pub struct RelayHub {
+    network: NetworkId,
+    local: PeerId,
+    protocols: Mutex<HashMap<String, Protocol>>,
+    tally: Arc<Tally>,
+    changed: Arc<Notify>,
+}
+
+impl RelayHub {
+    /// Creates the router at this network's local endpoint.
+    pub fn new(network: NetworkId, local: EndpointId) -> Arc<Self> {
+        Arc::new(Self {
+            network,
+            local: *local.as_bytes(),
+            protocols: Mutex::default(),
+            tally: Arc::default(),
+            changed: Arc::default(),
+        })
+    }
+
+    fn protocols(&self) -> std::sync::MutexGuard<'_, HashMap<String, Protocol>> {
+        self.protocols
+            .lock()
+            .unwrap_or_else(|error| error.into_inner())
+    }
+
+    fn protocol<'a>(
+        &self,
+        protocols: &'a mut HashMap<String, Protocol>,
+        name: &str,
+    ) -> &'a mut Protocol {
+        protocols
+            .entry(name.to_owned())
+            .or_insert_with(|| Protocol {
+                plane: Arc::new(Plane {
+                    local: self.local,
+                    table: ArcSwap::from_pointee(ForwardingTable::default()),
+                    tally: self.tally.clone(),
+                }),
+                graph: HashMap::new(),
+                members: HashSet::new(),
+                raw: HashMap::new(),
+                readers: HashMap::new(),
+                links: HashMap::new(),
+            })
+    }
+
+    /// Wakes the control loop promptly when a transport reader ends.
+    pub async fn changed(&self) {
+        self.changed.notified().await;
+    }
+
+    /// Current counters.
+    pub fn counters(&self) -> RelayCounters {
+        self.tally.snapshot()
+    }
+
+    /// Publishes authenticated topology. Refreshing identical state is cheap.
+    pub fn set_topology(
+        &self,
+        protocol: &str,
+        graph: HashMap<PeerId, Vec<PeerId>>,
+        members: HashSet<PeerId>,
+    ) {
+        let mut protocols = self.protocols();
+        let state = self.protocol(&mut protocols, protocol);
+        if state.graph != graph || state.members != members {
+            state.graph = graph;
+            state.members = members;
+            state.publish();
+        }
+    }
+
+    /// Whether the current table has a path to this destination.
+    pub fn reachable(&self, peer: EndpointId, protocol: &str) -> bool {
+        self.protocols().get(protocol).is_some_and(|state| {
+            state
+                .plane
+                .table
+                .load()
+                .routes
+                .contains_key(peer.as_bytes())
+        })
+    }
+
+    /// Stable logical link, preserved across topology changes.
+    pub fn link(&self, peer: EndpointId, protocol: &str) -> Arc<PeerLink> {
+        let mut protocols = self.protocols();
+        let state = self.protocol(&mut protocols, protocol);
+        if let Some(link) = state.links.get(peer.as_bytes()) {
+            return link.clone();
+        }
+        let (inbox_tx, inbox_rx) = mpsc::channel(INBOX);
+        let (closed, _) = watch::channel(false);
+        let link = Arc::new(PeerLink {
+            network: self.network,
+            peer,
+            plane: state.plane.clone(),
+            inbox_tx,
+            inbox_rx: tokio::sync::Mutex::new(inbox_rx),
+            closed,
+        });
+        state.links.insert(*peer.as_bytes(), link.clone());
+        state.publish();
+        link
+    }
+
+    /// Whether the protocol already owns its logical link.
+    pub fn has_link(&self, peer: EndpointId, protocol: &str) -> bool {
+        self.protocols()
+            .get(protocol)
+            .is_some_and(|state| state.links.contains_key(peer.as_bytes()))
+    }
+
+    /// Installs a raw transport link and starts its independent ingress reader.
+    pub fn set_direct(&self, peer: EndpointId, protocol: &str, raw: SharedLink) {
+        if raw.network() != self.network || raw.peer() != peer {
+            return;
+        }
+        let mut protocols = self.protocols();
+        let state = self.protocol(&mut protocols, protocol);
+        let id = *peer.as_bytes();
+        if let Some(old) = state.readers.remove(&id) {
+            old.abort();
+        }
+        state.raw.insert(id, raw.clone());
+        state.publish();
+        let plane = state.plane.clone();
+        let changed = self.changed.clone();
+        state.readers.insert(
+            id,
+            tokio::spawn(async move {
+                let mut batch = 0;
+                while let Some(frame) = raw.recv().await {
+                    plane.receive(id, frame);
+                    batch += 1;
+                    if batch == 64 {
+                        tokio::task::yield_now().await;
+                        batch = 0;
+                    }
+                }
+                changed.notify_one();
+            }),
+        );
+    }
+
+    /// Removes a physical link without tearing down end-to-end protocol state.
+    pub fn clear_direct(&self, peer: EndpointId, protocol: &str) {
+        if let Some(state) = self.protocols().get_mut(protocol) {
+            state.raw.remove(peer.as_bytes());
+            if let Some(task) = state.readers.remove(peer.as_bytes()) {
+                task.abort();
+            }
+            state.publish();
+        }
+    }
+
+    /// Revokes all links and topology involving a departed authenticated peer.
+    pub fn remove_peer(&self, peer: EndpointId) {
+        for state in self.protocols().values_mut() {
+            state.raw.remove(peer.as_bytes());
+            if let Some(task) = state.readers.remove(peer.as_bytes()) {
+                task.abort();
+            }
+            if let Some(link) = state.links.remove(peer.as_bytes()) {
+                link.close();
+            }
+            state.members.remove(peer.as_bytes());
+            state.graph.remove(peer.as_bytes());
+            for neighbors in state.graph.values_mut() {
+                neighbors.retain(|id| id != peer.as_bytes());
+            }
+            state.publish();
+        }
+    }
+
+    /// Stops every reader and releases all transport handles.
+    pub fn close(&self) {
+        self.protocols().clear();
+    }
+}
+
+/// A protocol's end-to-end channel, independent of its current next hop.
+#[derive(Debug)]
+pub struct PeerLink {
+    network: NetworkId,
+    peer: EndpointId,
+    plane: Arc<Plane>,
+    inbox_tx: mpsc::Sender<Bytes>,
+    inbox_rx: tokio::sync::Mutex<mpsc::Receiver<Bytes>>,
+    closed: watch::Sender<bool>,
+}
+
+impl PeerLink {
+    fn close(&self) {
+        self.closed.send_replace(true);
+    }
+}
+
+impl PacketLink for PeerLink {
+    fn network(&self) -> NetworkId {
+        self.network
+    }
+    fn peer(&self) -> EndpointId {
+        self.peer
+    }
+    fn max_datagram_size(&self) -> usize {
+        MAX_DATA_DATAGRAM - RELAY_OVERHEAD
+    }
+    fn send(&self, payload: Bytes) -> Result<(), TransportError> {
+        self.send_flow(payload, 0)
+    }
+    fn send_flow(&self, payload: Bytes, flow: FlowId) -> Result<(), TransportError> {
+        if self.is_closed() {
+            return Err(TransportError::Closed);
+        }
+        if payload.len() > self.max_datagram_size() {
+            return Err(TransportError::TooLarge {
+                size: payload.len(),
+                limit: self.max_datagram_size(),
+            });
+        }
+        let table = self.plane.table.load();
+        let route = table
+            .routes
+            .get(self.peer.as_bytes())
+            .ok_or(TransportError::Closed)?;
+        let hop = route
+            .select(&self.plane.local, flow)
+            .ok_or(TransportError::Closed)?;
+        hop.link.send(envelope::encode(
+            self.plane.local,
+            *self.peer.as_bytes(),
+            flow,
+            &payload,
+        ))?;
+        if route.hops > 1 {
+            self.plane.tally.sent_via.fetch_add(1, Ordering::Relaxed);
+        }
+        Ok(())
+    }
+    fn recv(&self) -> BoxFuture<'_, Option<Bytes>> {
+        Box::pin(async move {
+            let mut closed = self.closed.subscribe();
+            if *closed.borrow_and_update() {
+                return None;
+            }
+            let mut inbox = self.inbox_rx.lock().await;
+            tokio::select! { biased; _ = closed.changed() => None, frame = inbox.recv() => frame }
+        })
+    }
+    fn closed(&self) -> BoxFuture<'_, ()> {
+        Box::pin(async move {
+            let mut closed = self.closed.subscribe();
+            if !*closed.borrow_and_update() {
+                let _ = closed.changed().await;
+            }
+        })
+    }
+    fn is_closed(&self) -> bool {
+        *self.closed.borrow()
+    }
+    fn path_description(&self) -> String {
+        let table = self.plane.table.load();
+        match table.routes.get(self.peer.as_bytes()) {
+            Some(route) if route.hops == 1 => route.next[0].link.path_description(),
+            Some(route) => format!(
+                "relay {} hops via {} ({} equal paths)",
+                route.hops,
+                hex::encode(route.next[0].peer),
+                route.next.len()
+            ),
+            None => "unreachable".into(),
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "relay_tests.rs"]
+mod tests;

crates/tsunagi-core/src/dataplane/relay_tests.rs

@@ -0,0 +1,287 @@
+#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+use super::*;
+use crate::identity::{NetworkKeys, NetworkName, NetworkSecret};
+use std::sync::atomic::AtomicBool;
+
+fn network() -> NetworkId {
+    NetworkKeys::derive(
+        &NetworkName::new("routing-tests").unwrap(),
+        &NetworkSecret::from_bytes([3; 32]).unwrap(),
+    )
+    .network_id()
+}
+fn peer(seed: u8) -> EndpointId {
+    iroh::SecretKey::from_bytes(&[seed; 32]).public()
+}
+fn id(seed: u8) -> PeerId {
+    *peer(seed).as_bytes()
+}
+
+#[derive(Debug)]
+struct Wire {
+    peer: EndpointId,
+    sent: Mutex<Vec<Bytes>>,
+    feed: mpsc::Sender<Bytes>,
+    inbound: tokio::sync::Mutex<mpsc::Receiver<Bytes>>,
+    dead: AtomicBool,
+    count: AtomicU64,
+    record: bool,
+}
+impl Wire {
+    fn new(seed: u8, record: bool) -> Arc<Self> {
+        let (feed, inbound) = mpsc::channel(32);
+        Arc::new(Self {
+            peer: peer(seed),
+            sent: Mutex::default(),
+            feed,
+            inbound: tokio::sync::Mutex::new(inbound),
+            dead: AtomicBool::new(false),
+            count: AtomicU64::new(0),
+            record,
+        })
+    }
+    fn take(&self) -> Vec<Bytes> {
+        std::mem::take(&mut self.sent.lock().unwrap())
+    }
+}
+impl PacketLink for Wire {
+    fn network(&self) -> NetworkId {
+        network()
+    }
+    fn peer(&self) -> EndpointId {
+        self.peer
+    }
+    fn max_datagram_size(&self) -> usize {
+        MAX_DATA_DATAGRAM
+    }
+    fn send(&self, frame: Bytes) -> Result<(), TransportError> {
+        if self.is_closed() {
+            return Err(TransportError::Closed);
+        }
+        self.count.fetch_add(1, Ordering::Relaxed);
+        if self.record {
+            self.sent.lock().unwrap().push(frame);
+        }
+        Ok(())
+    }
+    fn recv(&self) -> BoxFuture<'_, Option<Bytes>> {
+        Box::pin(async move { self.inbound.lock().await.recv().await })
+    }
+    fn closed(&self) -> BoxFuture<'_, ()> {
+        Box::pin(std::future::pending())
+    }
+    fn is_closed(&self) -> bool {
+        self.dead.load(Ordering::Relaxed)
+    }
+    fn path_description(&self) -> String {
+        "test-direct".into()
+    }
+}
+
+fn topology(hub: &RelayHub, protocol: &str, edges: &[(u8, &[u8])], members: &[u8]) {
+    hub.set_topology(
+        protocol,
+        edges
+            .iter()
+            .map(|(a, bs)| (id(*a), bs.iter().map(|b| id(*b)).collect()))
+            .collect(),
+        members.iter().map(|p| id(*p)).collect(),
+    );
+}
+
+#[tokio::test]
+async fn ecmp_is_per_flow_direct_wins_and_existing_tunnel_survives_changes() {
+    let hub = RelayHub::new(network(), peer(1));
+    let b = Wire::new(2, true);
+    let c = Wire::new(3, true);
+    hub.set_direct(peer(2), "ip", b.clone());
+    hub.set_direct(peer(3), "ip", c.clone());
+    topology(&hub, "ip", &[(2, &[4]), (3, &[4])], &[1, 2, 3, 4]);
+    let link = hub.link(peer(4), "ip");
+    let mut chosen = HashMap::new();
+    for _ in 0..8 {
+        for flow in 0..100 {
+            link.send_flow(Bytes::from_static(b"ciphertext"), flow)
+                .unwrap();
+        }
+        for (hop, wire) in [(2, &b), (3, &c)] {
+            for frame in wire.take() {
+                let header = envelope::decode(&frame).unwrap();
+                assert_eq!(header.source, id(1));
+                assert_eq!(header.destination, id(4));
+                if let Some(old) = chosen.insert(header.flow, hop) {
+                    assert_eq!(old, hop);
+                }
+            }
+        }
+    }
+    assert_eq!(
+        chosen.values().copied().collect::<HashSet<_>>(),
+        HashSet::from([2, 3])
+    );
+    let direct = Wire::new(4, true);
+    hub.set_direct(peer(4), "ip", direct.clone());
+    link.send_flow(Bytes::from_static(b"direct"), 8).unwrap();
+    assert_eq!(direct.take().len(), 1);
+    assert!(b.take().is_empty() && c.take().is_empty());
+    hub.clear_direct(peer(4), "ip");
+    b.dead.store(true, Ordering::Relaxed);
+    for flow in 0..100 {
+        link.send_flow(Bytes::from_static(b"fallback"), flow)
+            .unwrap();
+    }
+    assert_eq!(c.take().len(), 100);
+    hub.clear_direct(peer(2), "ip");
+    topology(&hub, "ip", &[(3, &[])], &[1, 2, 3, 4]);
+    assert!(link.send(Bytes::new()).is_err());
+    assert!(!link.is_closed());
+    assert!(Arc::ptr_eq(&link, &hub.link(peer(4), "ip")));
+    hub.remove_peer(peer(4));
+    assert!(link.is_closed());
+    tokio::time::timeout(std::time::Duration::from_secs(1), link.closed())
+        .await
+        .unwrap();
+    assert!(link.recv().await.is_none());
+    hub.close();
+}
+
+#[tokio::test]
+async fn transport_reader_forwards_without_any_plugin_reader_and_isolates_protocols() {
+    let hub = RelayHub::new(network(), peer(2));
+    let a = Wire::new(1, true);
+    let c = Wire::new(3, true);
+    hub.set_direct(peer(1), "ip", a.clone());
+    hub.set_direct(peer(3), "ip", c.clone());
+    topology(&hub, "ip", &[(3, &[4])], &[1, 2, 3, 4]);
+    let frame = envelope::encode(id(1), id(4), 91, b"end-to-end encrypted");
+    let pointer = frame.as_ptr();
+    a.feed.send(frame).await.unwrap();
+    tokio::time::timeout(std::time::Duration::from_secs(1), async {
+        while hub.counters().forwarded == 0 {
+            tokio::task::yield_now().await;
+        }
+    })
+    .await
+    .unwrap();
+    let sent = c.take();
+    assert_eq!(sent[0].as_ptr(), pointer);
+    assert_eq!(
+        envelope::decode(&sent[0]).unwrap().remaining,
+        ROUTING_HOP_LIMIT - 1
+    );
+    assert_eq!(&sent[0][RELAY_OVERHEAD..], b"end-to-end encrypted");
+    let isolated = hub.link(peer(4), "other-ip");
+    assert!(isolated.send(Bytes::new()).is_err());
+    assert_eq!(hub.counters().forwarded, 1);
+    hub.close();
+}
+
+#[tokio::test]
+async fn local_delivery_is_bounded_and_malformed_or_unknown_sources_are_dropped() {
+    let hub = RelayHub::new(network(), peer(2));
+    let a = Wire::new(1, true);
+    hub.set_direct(peer(1), "ip", a);
+    let link = hub.link(peer(1), "ip");
+    let plane = link.plane.clone();
+    for _ in 0..INBOX + 1 {
+        plane.receive(id(1), envelope::encode(id(1), id(2), 0, b"ip"));
+    }
+    assert_eq!(hub.counters().dropped_congested, 1);
+    for _ in 0..INBOX {
+        assert_eq!(link.recv().await.unwrap(), Bytes::from_static(b"ip"));
+    }
+    plane.receive(id(1), Bytes::from_static(b"broken"));
+    plane.receive(id(1), envelope::encode(id(9), id(2), 0, b"unknown member"));
+    assert_eq!(hub.counters().dropped_unknown, 2);
+    plane.receive(
+        id(1),
+        envelope::encode(id(1), id(9), 0, b"unknown destination"),
+    );
+    assert_eq!(hub.counters().dropped_no_link, 1);
+    hub.close();
+}
+
+#[tokio::test]
+async fn inconsistent_tables_cannot_loop_beyond_the_hop_limit() {
+    let a = RelayHub::new(network(), peer(1));
+    let b = RelayHub::new(network(), peer(2));
+    let ab = Wire::new(2, true);
+    let ba = Wire::new(1, true);
+    a.set_direct(peer(2), "ip", ab.clone());
+    b.set_direct(peer(1), "ip", ba.clone());
+    // Deliberately inconsistent snapshots while updates are in flight.
+    topology(&a, "ip", &[(2, &[4])], &[1, 2, 3, 4]);
+    topology(&b, "ip", &[(1, &[4])], &[1, 2, 3, 4]);
+    let ap = a.link(peer(4), "ip").plane.clone();
+    let bp = b.link(peer(4), "ip").plane.clone();
+    let mut frame = envelope::encode(id(3), id(4), 7, b"transit");
+    for turn in 0..ROUTING_HOP_LIMIT {
+        let (plane, incoming, wire) = if turn % 2 == 0 {
+            (&ap, id(2), &ab)
+        } else {
+            (&bp, id(1), &ba)
+        };
+        plane.receive(incoming, frame);
+        let sent = wire.take();
+        if turn == ROUTING_HOP_LIMIT - 1 {
+            assert!(sent.is_empty());
+            break;
+        }
+        assert_eq!(sent.len(), 1);
+        frame = sent.into_iter().next().unwrap();
+    }
+    assert_eq!(
+        a.counters().forwarded + b.counters().forwarded,
+        u64::from(ROUTING_HOP_LIMIT - 1)
+    );
+    assert_eq!(
+        a.counters().dropped_hop_limit + b.counters().dropped_hop_limit,
+        1
+    );
+    a.close();
+    b.close();
+}
+
+/// Measures the actual synchronous transit routine, including header checks,
+/// snapshot lookup, ECMP, in-place TTL update and mock transport submission.
+/// Packet construction, encryption and socket I/O are outside this measurement.
+#[tokio::test]
+#[ignore = "manual release-mode forwarding microbenchmark"]
+async fn forwarding_benchmark() {
+    let hub = RelayHub::new(network(), peer(2));
+    let wire = Wire::new(3, false);
+    hub.set_direct(peer(3), "ip", wire.clone());
+    let alternate = Wire::new(5, false);
+    hub.set_direct(peer(5), "ip", alternate.clone());
+    topology(&hub, "ip", &[(3, &[4]), (5, &[4])], &[1, 2, 3, 4, 5]);
+    let plane = hub.link(peer(4), "ip").plane.clone();
+    let source = id(1);
+    let destination = id(4);
+    let incoming = id(1);
+    for size in [64, 1280] {
+        let mut elapsed = std::time::Duration::ZERO;
+        const COUNT: usize = 10000;
+        const BATCHES: usize = 100;
+        for _ in 0..BATCHES {
+            let frames: Vec<_> = (0..COUNT)
+                .map(|flow| envelope::encode(source, destination, flow as u64, &vec![42; size]))
+                .collect();
+            let start = std::time::Instant::now();
+            for frame in frames {
+                plane.receive(incoming, std::hint::black_box(frame));
+            }
+            elapsed += start.elapsed();
+        }
+        let count = (COUNT * BATCHES) as f64;
+        println!(
+            "transit {size} B: {:.1} ns/packet, {:.2} Mpps (1M packets, two equal paths)",
+            elapsed.as_nanos() as f64 / count,
+            count / elapsed.as_secs_f64() / 1e6
+        );
+    }
+    assert_eq!(
+        wire.count.load(Ordering::Relaxed) + alternate.count.load(Ordering::Relaxed),
+        2000000
+    );
+    hub.close();
+}

crates/tsunagi-core/src/dataplane/routing/envelope.rs

@@ -0,0 +1,84 @@
+//! Fixed header. Transit changes one byte in an owned receive buffer.
+use super::{FlowId, PeerId};
+use crate::config::{MAX_DATA_DATAGRAM, ROUTING_HOP_LIMIT};
+use bytes::{BufMut, Bytes, BytesMut};
+
+pub(crate) const HEADER: usize = 2 + 32 + 32 + 8;
+const VERSION: u8 = 1;
+
+#[derive(Debug, PartialEq, Eq)]
+pub(crate) struct Header {
+    pub source: PeerId,
+    pub destination: PeerId,
+    pub remaining: u8,
+    pub flow: FlowId,
+}
+
+pub(crate) fn decode(bytes: &[u8]) -> Option<Header> {
+    if bytes.len() < HEADER
+        || bytes.len() > MAX_DATA_DATAGRAM
+        || bytes[0] != VERSION
+        || bytes[1] == 0
+        || bytes[1] > ROUTING_HOP_LIMIT
+    {
+        return None;
+    }
+    Some(Header {
+        source: bytes[2..34].try_into().ok()?,
+        destination: bytes[34..66].try_into().ok()?,
+        remaining: bytes[1],
+        flow: u64::from_be_bytes(bytes[66..74].try_into().ok()?),
+    })
+}
+
+pub(crate) fn encode(source: PeerId, destination: PeerId, flow: FlowId, payload: &[u8]) -> Bytes {
+    let mut bytes = BytesMut::with_capacity(HEADER + payload.len());
+    bytes.put_u8(VERSION);
+    bytes.put_u8(ROUTING_HOP_LIMIT);
+    bytes.extend_from_slice(&source);
+    bytes.extend_from_slice(&destination);
+    bytes.put_u64(flow);
+    bytes.extend_from_slice(payload);
+    bytes.freeze()
+}
+
+pub(crate) fn decrement(bytes: Bytes) -> Bytes {
+    let mut bytes = match bytes.try_into_mut() {
+        Ok(bytes) => bytes,
+        Err(bytes) => BytesMut::from(bytes.as_ref()),
+    };
+    // Called only after decode and after excluding remaining <= 1.
+    bytes[1] -= 1;
+    bytes.freeze()
+}
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+    use super::*;
+    #[test]
+    fn transit_reuses_the_buffer_and_rejects_invalid_headers() {
+        let frame = encode([1; 32], [2; 32], 17, &[42; 1280]);
+        let address = frame.as_ptr();
+        let frame = decrement(frame);
+        assert_eq!(
+            frame.as_ptr(),
+            address,
+            "no payload copy for an owned buffer"
+        );
+        assert_eq!(decode(&frame).unwrap().remaining, ROUTING_HOP_LIMIT - 1);
+        assert_eq!(&frame[HEADER..], &[42; 1280]);
+        for length in 0..HEADER {
+            assert!(decode(&frame[..length]).is_none());
+        }
+        for ttl in [0, ROUTING_HOP_LIMIT + 1] {
+            let mut bad = frame.to_vec();
+            bad[1] = ttl;
+            assert!(decode(&bad).is_none());
+        }
+        let mut bad = frame.to_vec();
+        bad[0] = 99;
+        assert!(decode(&bad).is_none());
+        assert!(decode(&vec![1; MAX_DATA_DATAGRAM + 1]).is_none());
+    }
+}

crates/tsunagi-core/src/dataplane/routing/flow.rs

@@ -0,0 +1,125 @@
+//! Optional IP flow classifier for IP plugins, called before encryption.
+//! The router itself treats this identifier and the payload as opaque.
+
+use super::FlowId;
+
+fn hash(parts: &[&[u8]]) -> FlowId {
+    let mut value = 0xcbf29ce484222325u64;
+    for part in parts {
+        for byte in *part {
+            value = (value ^ u64::from(*byte)).wrapping_mul(0x100000001b3);
+        }
+    }
+    value
+}
+
+/// Stable directional IP flow hash, independent of TCP sequence numbers,
+/// checksums and packet contents. Fragmented traffic uses addresses/protocol
+/// instead of ports: even non-initial fragments and subsequent fragmented
+/// datagrams stay together. This deliberately coalesces fragmented flows.
+/// Malformed packets get a coarse hash; parsing is bounded and never allocates.
+pub fn ip_flow(packet: &[u8]) -> FlowId {
+    match packet.first().map(|b| b >> 4) {
+        Some(4) if packet.len() >= 20 => {
+            let addresses = &packet[12..20];
+            let protocol = &packet[9..10];
+            let offset = usize::from(packet[0] & 15) * 4;
+            if u16::from_be_bytes([packet[6], packet[7]]) & 0x3fff != 0 {
+                return hash(&[addresses, protocol]);
+            }
+            if offset >= 20
+                && matches!(packet[9], 6 | 17)
+                && let Some(ports) = packet.get(offset..offset + 4)
+            {
+                return hash(&[addresses, protocol, ports]);
+            }
+            hash(&[addresses, protocol])
+        }
+        Some(6) if packet.len() >= 40 => {
+            let addresses = &packet[8..40];
+            let mut protocol = packet[6];
+            let mut offset = 40;
+            for _ in 0..8 {
+                match protocol {
+                    44 => {
+                        if let Some(fragment) = packet.get(offset..offset + 8) {
+                            return hash(&[addresses, &fragment[..1]]);
+                        }
+                        break;
+                    }
+                    0 | 43 | 60 | 51 => {
+                        let Some(header) = packet.get(offset..offset + 2) else {
+                            break;
+                        };
+                        let size = if protocol == 51 {
+                            (usize::from(header[1]) + 2) * 4
+                        } else {
+                            (usize::from(header[1]) + 1) * 8
+                        };
+                        protocol = header[0];
+                        offset += size;
+                    }
+                    6 | 17 => {
+                        if let Some(ports) = packet.get(offset..offset + 4) {
+                            return hash(&[addresses, &[protocol], ports]);
+                        }
+                        break;
+                    }
+                    _ => break,
+                }
+            }
+            hash(&[addresses, &[protocol]])
+        }
+        _ => 0,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn tcp_flow_ignores_packet_contents_but_distinguishes_ports() {
+        let mut packet = [0u8; 80];
+        packet[0] = 0x45;
+        packet[9] = 6;
+        packet[12..24].copy_from_slice(&[10, 0, 0, 1, 10, 0, 0, 2, 0, 22, 1, 2]);
+        let flow = ip_flow(&packet);
+        packet[4] = 123; // IP id changes for each unfragmented packet.
+        packet[24..].fill(47);
+        assert_eq!(flow, ip_flow(&packet));
+        packet[23] = 3;
+        assert_ne!(flow, ip_flow(&packet));
+        packet[6] = 0x20;
+        let fragment_flow = ip_flow(&packet);
+        packet[6] = 0;
+        packet[7] = 1;
+        packet[20..].fill(99);
+        assert_eq!(fragment_flow, ip_flow(&packet));
+        packet[4] = 97;
+        assert_eq!(fragment_flow, ip_flow(&packet));
+    }
+
+    #[test]
+    fn ipv6_extensions_and_fragments_are_bounded_and_stable() {
+        let mut packet = [0u8; 80];
+        packet[0] = 0x60;
+        packet[6] = 0;
+        packet[40] = 17;
+        packet[48..52].copy_from_slice(&[1, 2, 3, 4]);
+        let flow = ip_flow(&packet);
+        packet[52..].fill(5);
+        assert_eq!(flow, ip_flow(&packet));
+        packet[50] = 9;
+        assert_ne!(flow, ip_flow(&packet));
+        packet[6] = 44;
+        packet[40] = 6;
+        let flow = ip_flow(&packet);
+        packet[42] = 32;
+        packet[48..].fill(3);
+        assert_eq!(flow, ip_flow(&packet));
+        for len in 0..packet.len() {
+            let _ = ip_flow(&packet[..len]);
+        }
+    }
+}

crates/tsunagi-core/src/dataplane/routing/mod.rs

@@ -0,0 +1,131 @@
+//! Transport-independent routing over opaque identities. Tables are built on
+//! topology changes, never on the packet path. No WireGuard or iroh APIs here.
+pub(crate) mod envelope;
+pub mod flow;
+
+use std::collections::{BTreeSet, HashMap, VecDeque};
+
+/// Opaque authenticated identity; the transport adapter validates its keys.
+pub type PeerId = [u8; 32];
+/// Stable flow identifier, carried unchanged between transit routers.
+pub type FlowId = u64;
+
+/// A shortest route with all equal-cost first hops in stable order.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Route {
+    /// Number of transport links to the destination.
+    pub hops: u8,
+    /// Equal-cost first hops. Direct destinations have one entry.
+    pub next_hops: Box<[PeerId]>,
+}
+
+/// Immutable shortest-path table, replaced when connectivity changes.
+#[derive(Debug, Clone, Default)]
+pub struct RoutingTable {
+    routes: HashMap<PeerId, Route>,
+}
+
+impl RoutingTable {
+    /// Computes shortest directed paths bounded by `hop_limit`.
+    /// The caller supplies only authenticated, fresh, compatible edges.
+    pub fn build(local: PeerId, graph: &HashMap<PeerId, Vec<PeerId>>, hop_limit: u8) -> Self {
+        let mut distances = HashMap::from([(local, 0u8)]);
+        let mut first_hops: HashMap<PeerId, BTreeSet<PeerId>> = HashMap::new();
+        let mut pending = VecDeque::from([local]);
+        while let Some(node) = pending.pop_front() {
+            let distance = distances[&node];
+            if distance >= hop_limit {
+                continue;
+            }
+            let inherited = first_hops.get(&node).cloned().unwrap_or_default();
+            for &next in graph.get(&node).into_iter().flatten() {
+                let next_distance = distance + 1;
+                match distances.get(&next) {
+                    Some(&known) if known < next_distance => continue,
+                    None => {
+                        distances.insert(next, next_distance);
+                        pending.push_back(next);
+                    }
+                    _ => {}
+                }
+                let hops = first_hops.entry(next).or_default();
+                if node == local {
+                    hops.insert(next);
+                } else {
+                    hops.extend(inherited.iter().copied());
+                }
+            }
+        }
+        Self {
+            routes: first_hops
+                .into_iter()
+                .map(|(peer, hops)| {
+                    (
+                        peer,
+                        Route {
+                            hops: distances[&peer],
+                            next_hops: hops.into_iter().collect(),
+                        },
+                    )
+                })
+                .collect(),
+        }
+    }
+    /// Precomputed route to a destination.
+    pub fn get(&self, destination: &PeerId) -> Option<&Route> {
+        self.routes.get(destination)
+    }
+    /// All reachable destinations, excluding ourselves.
+    pub fn iter(&self) -> impl Iterator<Item = (&PeerId, &Route)> {
+        self.routes.iter()
+    }
+}
+
+/// Stable ECMP mixing, without random state or hashing the payload per hop.
+pub(crate) fn mix64(mut value: u64) -> u64 {
+    value ^= value >> 30;
+    value = value.wrapping_mul(0xbf58476d1ce4e5b9);
+    value ^= value >> 27;
+    value = value.wrapping_mul(0x94d049bb133111eb);
+    value ^ (value >> 31)
+}
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+    use super::*;
+    fn p(n: u8) -> PeerId {
+        [n; 32]
+    }
+    #[test]
+    fn shortest_paths_keep_equal_cost_hops_and_prefer_direct_links() {
+        let mut graph = HashMap::from([
+            (p(1), vec![p(3), p(2)]),
+            (p(2), vec![p(4)]),
+            (p(3), vec![p(4)]),
+            (p(4), vec![p(5)]),
+            (p(5), vec![p(1)]),
+        ]);
+        let routes = RoutingTable::build(p(1), &graph, 16);
+        assert_eq!(routes.get(&p(5)).unwrap().hops, 3);
+        assert_eq!(&*routes.get(&p(5)).unwrap().next_hops, &[p(2), p(3)]);
+        assert!(routes.get(&p(1)).is_none());
+        assert!(routes.get(&p(9)).is_none());
+        graph.get_mut(&p(1)).unwrap().push(p(5));
+        assert_eq!(
+            RoutingTable::build(p(1), &graph, 16).get(&p(5)).unwrap(),
+            &Route {
+                hops: 1,
+                next_hops: Box::new([p(5)])
+            }
+        );
+    }
+    #[test]
+    fn topology_removal_and_hop_budget_remove_impossible_routes() {
+        let mut graph = HashMap::from([(p(1), vec![p(2)]), (p(2), vec![p(3)]), (p(3), vec![p(4)])]);
+        assert!(RoutingTable::build(p(1), &graph, 2).get(&p(4)).is_none());
+        assert!(RoutingTable::build(p(1), &graph, 3).get(&p(4)).is_some());
+        graph.remove(&p(2));
+        assert!(RoutingTable::build(p(1), &graph, 16).get(&p(4)).is_none());
+    }
+}

crates/tsunagi-core/src/dataplane/transport/fragments.rs

@@ -0,0 +1,234 @@
+//! Bounded fragmentation of opaque transport payloads, below peer relaying.
+//!
+//! Data ALPN v3: u64 packet ID, u32 total length, u32 byte offset (big endian),
+//! followed by payload. Each QUIC connection owns its IDs and reassembly state.
+//! There is no retransmission: one missing fragment loses one datagram only.
+
+use std::collections::{HashMap, VecDeque};
+
+use bytes::{BufMut, Bytes, BytesMut};
+use tokio::time::Instant;
+
+use crate::config::{
+    DATA_REASSEMBLY_TTL, DATA_RECENT_IDS, MAX_DATA_ASSEMBLIES, MAX_DATA_DATAGRAM,
+    MAX_DATA_FRAGMENTS, MAX_DATA_REASSEMBLY_BYTES,
+};
+
+pub(super) const HEADER: usize = 16;
+
+pub(super) fn encode(id: u64, total: usize, offset: usize, payload: &[u8]) -> Bytes {
+    let mut frame = BytesMut::with_capacity(HEADER + payload.len());
+    frame.put_u64(id);
+    frame.put_u32(total as u32);
+    frame.put_u32(offset as u32);
+    frame.extend_from_slice(payload);
+    frame.freeze()
+}
+
+#[derive(Debug)]
+struct Assembly {
+    started: Instant,
+    bytes: Vec<u8>,
+    ranges: Vec<(usize, usize)>,
+    received: usize,
+}
+
+#[derive(Debug, Default)]
+pub(super) struct Reassembler {
+    packets: HashMap<u64, Assembly>,
+    buffered: usize,
+    recent: VecDeque<u64>,
+}
+
+impl Reassembler {
+    fn remember(&mut self, id: u64) {
+        if self.recent.len() == DATA_RECENT_IDS {
+            self.recent.pop_front();
+        }
+        self.recent.push_back(id);
+    }
+
+    fn remove(&mut self, id: u64) -> Option<Assembly> {
+        let packet = self.packets.remove(&id)?;
+        self.buffered -= packet.bytes.len();
+        self.remember(id);
+        Some(packet)
+    }
+
+    pub(super) fn expire(&mut self, now: Instant) {
+        let expired: Vec<_> = self
+            .packets
+            .iter()
+            .filter(|(_, p)| now.duration_since(p.started) >= DATA_REASSEMBLY_TTL)
+            .map(|(id, _)| *id)
+            .collect();
+        for id in expired {
+            self.remove(id);
+        }
+    }
+
+    pub(super) fn push(&mut self, frame: Bytes, now: Instant) -> Option<Bytes> {
+        self.expire(now);
+        let id = u64::from_be_bytes(frame.get(..8)?.try_into().ok()?);
+        let total = u32::from_be_bytes(frame.get(8..12)?.try_into().ok()?) as usize;
+        let offset = u32::from_be_bytes(frame.get(12..HEADER)?.try_into().ok()?) as usize;
+        let payload = frame.get(HEADER..)?;
+        let end = offset.checked_add(payload.len())?;
+        if total > MAX_DATA_DATAGRAM
+            || end > total
+            || (payload.is_empty() && total != 0)
+            || self.recent.contains(&id)
+        {
+            return None;
+        }
+        if !self.packets.contains_key(&id) {
+            if offset == 0 && end == total {
+                self.remember(id);
+                return Some(frame.slice(HEADER..));
+            }
+            // The length is validated before allocating. Drop the oldest
+            // incomplete packet when the per-link byte or entry budget is full.
+            while self.packets.len() >= MAX_DATA_ASSEMBLIES
+                || self.buffered + total > MAX_DATA_REASSEMBLY_BYTES
+            {
+                let oldest = self
+                    .packets
+                    .iter()
+                    .min_by_key(|(_, p)| p.started)
+                    .map(|(id, _)| *id)?;
+                self.remove(oldest);
+            }
+            self.packets.insert(
+                id,
+                Assembly {
+                    started: now,
+                    bytes: vec![0; total],
+                    ranges: Vec::new(),
+                    received: 0,
+                },
+            );
+            self.buffered += total;
+        }
+        let packet = self.packets.get_mut(&id)?;
+        if packet.bytes.len() != total {
+            self.remove(id);
+            return None;
+        }
+        for &(start, stop) in &packet.ranges {
+            if start == offset && stop == end && packet.bytes[offset..end] == *payload {
+                return None; // a duplicate does not reset the expiry time
+            }
+            if offset < stop && end > start {
+                self.remove(id); // conflicting or overlapping fragments
+                return None;
+            }
+        }
+        if packet.ranges.len() == MAX_DATA_FRAGMENTS {
+            self.remove(id);
+            return None;
+        }
+        packet.bytes[offset..end].copy_from_slice(payload);
+        packet.ranges.push((offset, end));
+        packet.received += payload.len();
+        if packet.received == total {
+            return self.remove(id).map(|p| Bytes::from(p.bytes));
+        }
+        None
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+    use super::*;
+
+    #[test]
+    fn reordered_duplicates_and_changing_fragment_sizes_reassemble_once() {
+        let mut rx = Reassembler::default();
+        let now = Instant::now();
+        let packet: Vec<u8> = (0..9000).map(|i| (i % 251) as u8).collect();
+        let mut parts = Vec::new();
+        let mut offset = 0;
+        for size in [1100, 700, 1100, 1100, 700, 1100, 1100, 1100, 1000] {
+            parts.push(encode(
+                7,
+                packet.len(),
+                offset,
+                &packet[offset..offset + size],
+            ));
+            offset += size;
+        }
+        assert_eq!(offset, packet.len());
+        for part in parts[1..].iter().rev() {
+            assert!(rx.push(part.clone(), now).is_none());
+            assert!(rx.push(part.clone(), now).is_none());
+        }
+        assert_eq!(rx.push(parts[0].clone(), now).unwrap().as_ref(), packet);
+        assert!(rx.push(parts[0].clone(), now).is_none());
+        assert_eq!(rx.buffered, 0);
+        assert!(rx.packets.is_empty());
+    }
+
+    #[test]
+    fn a_missing_fragment_never_blocks_the_next_packet_and_expires() {
+        let mut rx = Reassembler::default();
+        let now = Instant::now();
+        assert!(rx.push(encode(1, 1280, 0, &[1; 800]), now).is_none());
+        assert_eq!(
+            rx.push(encode(2, 4, 0, b"next"), now).unwrap(),
+            &b"next"[..]
+        );
+        rx.expire(now + DATA_REASSEMBLY_TTL);
+        assert!(rx.packets.is_empty());
+        assert_eq!(rx.buffered, 0);
+        assert!(
+            rx.push(encode(1, 1280, 800, &[1; 480]), now + DATA_REASSEMBLY_TTL)
+                .is_none()
+        );
+    }
+
+    #[test]
+    fn malformed_conflicting_and_oversized_fragments_are_bounded() {
+        let now = Instant::now();
+        let mut rx = Reassembler::default();
+        for len in 0..HEADER {
+            assert!(rx.push(Bytes::from(vec![0xff; len]), now).is_none());
+        }
+        assert!(
+            rx.push(encode(1, MAX_DATA_DATAGRAM + 1, 0, b"x"), now)
+                .is_none()
+        );
+        assert!(rx.push(encode(2, 100, 100, b"x"), now).is_none());
+        assert!(rx.push(encode(3, 100, 0, b""), now).is_none());
+        assert_eq!(rx.buffered, 0);
+        for (id, bad) in [
+            (4, encode(4, 100, 0, b"different")),
+            (5, encode(5, 100, 3, b"overlap")),
+            (6, encode(6, 101, 9, b"changed total")),
+        ] {
+            assert!(rx.push(encode(id, 100, 0, b"123456789"), now).is_none());
+            assert!(rx.push(bad, now).is_none());
+            assert_eq!(rx.buffered, 0);
+        }
+        for id in 100..400 {
+            assert!(
+                rx.push(encode(id, MAX_DATA_DATAGRAM, 0, b"x"), now)
+                    .is_none()
+            );
+            assert!(rx.buffered <= MAX_DATA_REASSEMBLY_BYTES);
+            assert!(rx.packets.len() <= MAX_DATA_ASSEMBLIES);
+            assert!(rx.recent.len() <= DATA_RECENT_IDS);
+        }
+    }
+
+    #[test]
+    fn excessive_fragment_counts_are_discarded() {
+        let mut rx = Reassembler::default();
+        let now = Instant::now();
+        for offset in 0..=MAX_DATA_FRAGMENTS {
+            assert!(rx.push(encode(1, 1000, offset, b"x"), now).is_none());
+        }
+        assert!(rx.packets.is_empty());
+        assert_eq!(rx.buffered, 0);
+    }
+}

crates/tsunagi-core/src/dataplane/transport/iroh_link.rs

@@ -0,0 +1,389 @@
+//! A data plane transport built on iroh.
+//!
+//! This is where the data plane gets NAT traversal from. iroh hole punches a
+//! direct path between two peers when it can and falls back to a relay when it
+//! cannot, so every plugin inherits that without implementing STUN, ICE or a
+//! relay of its own.
+//!
+//! Data connections are separate from control connections in every way that
+//! matters: their own ALPN ([`DATA_ALPN`]), their own QUIC connection, their
+//! own congestion control. They carry one plugin protocol for one network.
+//! A data connection that breaks or floods cannot disturb the control plane.
+//!
+//! Packets travel as QUIC datagrams: unreliable and unordered, which is what a
+//! tunnelled UDP protocol wants, and free of the head-of-line blocking a
+//! stream would add.
+//!
+//! The channel is authenticated exactly like a control connection — the same
+//! membership handshake, bound to the same network — so a data link cannot be
+//! opened by someone who does not know the network secret.
+
+use std::collections::HashMap;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use bytes::Bytes;
+use iroh::EndpointId;
+use iroh::endpoint::{Connection, RecvStream, SendStream};
+
+use crate::BoxFuture;
+use crate::config::{DATA_REASSEMBLY_TTL, Limits, MAX_DATA_DATAGRAM, MAX_DATA_FRAGMENTS};
+use crate::error::ProtocolError;
+use crate::identity::{NetworkId, NetworkKeys};
+use crate::net::EndpointAdapter;
+use crate::proto::handshake;
+use crate::proto::message::{
+    DATA_ALPN, DataOpen, DataOpenAck, MAX_DATA_PROTOCOL_LEN, decode, encode,
+};
+use crate::proto::{read_frame, write_frame};
+
+use super::fragments::{self, Reassembler};
+use super::{InboundLink, PacketLink, PacketTransport, SharedLink, TransportError};
+
+/// What the iroh transport needs from the agent.
+///
+/// Implemented by the agent, which is the only thing that knows which networks
+/// are active and which plugin protocols are served.
+pub trait TransportContext: Send + Sync + std::fmt::Debug + 'static {
+    /// Key material of every network that is active right now.
+    ///
+    /// Taken as one snapshot because the membership handshake resolves the
+    /// requested network synchronously, exactly as the control plane's accept
+    /// path does.
+    fn snapshot<'a>(&'a self) -> BoxFuture<'a, HashMap<NetworkId, NetworkKeys>>;
+
+    /// Whether a plugin protocol is served in a network.
+    fn serves<'a>(&'a self, network: NetworkId, protocol: &'a str) -> BoxFuture<'a, bool>;
+}
+
+/// One authenticated datagram channel over an iroh connection.
+#[derive(Debug)]
+pub struct IrohLink {
+    network: NetworkId,
+    peer: EndpointId,
+    conn: Connection,
+    max_datagram: usize,
+    next_packet: AtomicU64,
+    reassembly: tokio::sync::Mutex<Reassembler>,
+    // Kept alive so the peer sees the channel as open; the connection closes
+    // when the link is dropped.
+    _send: tokio::sync::Mutex<SendStream>,
+    _recv: tokio::sync::Mutex<RecvStream>,
+}
+
+impl IrohLink {
+    fn new(
+        network: NetworkId,
+        peer: EndpointId,
+        conn: Connection,
+        peer_limit: usize,
+        send: SendStream,
+        recv: RecvStream,
+    ) -> Self {
+        // The negotiated limit is for reassembled payloads, never a snapshot
+        // of the initial path (which may still be a relay or another VPN).
+        let max_datagram = MAX_DATA_DATAGRAM.min(peer_limit);
+        Self {
+            network,
+            peer,
+            conn,
+            max_datagram,
+            next_packet: AtomicU64::new(0),
+            reassembly: tokio::sync::Mutex::new(Reassembler::default()),
+            _send: tokio::sync::Mutex::new(send),
+            _recv: tokio::sync::Mutex::new(recv),
+        }
+    }
+}
+
+impl PacketLink for IrohLink {
+    fn network(&self) -> NetworkId {
+        self.network
+    }
+
+    fn peer(&self) -> EndpointId {
+        self.peer
+    }
+
+    fn max_datagram_size(&self) -> usize {
+        self.max_datagram
+    }
+
+    fn send(&self, payload: Bytes) -> Result<(), TransportError> {
+        if payload.len() > self.max_datagram {
+            return Err(TransportError::TooLarge {
+                size: payload.len(),
+                limit: self.max_datagram,
+            });
+        }
+        let id = self.next_packet.fetch_add(1, Ordering::Relaxed);
+        let mut offset: usize = 0;
+        let mut attempts = 0;
+        // Re-read the current path's capacity for every fragment. A migration
+        // can shrink it even between two send_datagram calls.
+        for _ in 0..MAX_DATA_FRAGMENTS {
+            loop {
+                let capacity = self
+                    .conn
+                    .max_datagram_size()
+                    .unwrap_or(0)
+                    .checked_sub(fragments::HEADER)
+                    .filter(|n| *n > 0)
+                    .ok_or_else(|| {
+                        TransportError::Other("QUIC path cannot carry data fragments".into())
+                    })?;
+                let end = offset.saturating_add(capacity).min(payload.len());
+                let frame = fragments::encode(id, payload.len(), offset, &payload[offset..end]);
+                match self.conn.send_datagram(frame) {
+                    Ok(()) => {
+                        offset = end;
+                        break;
+                    }
+                    Err(iroh::endpoint::SendDatagramError::TooLarge) if attempts < 3 => {
+                        attempts += 1;
+                    }
+                    Err(iroh::endpoint::SendDatagramError::ConnectionLost(_)) => {
+                        return Err(TransportError::Closed);
+                    }
+                    Err(err) => return Err(TransportError::Other(err.to_string())),
+                }
+            }
+            if offset == payload.len() {
+                return Ok(());
+            }
+        }
+        Err(TransportError::Other(
+            "QUIC path needs too many fragments".into(),
+        ))
+    }
+
+    fn recv(&self) -> BoxFuture<'_, Option<Bytes>> {
+        Box::pin(async move {
+            let mut reassembly = self.reassembly.lock().await;
+            loop {
+                match tokio::time::timeout(DATA_REASSEMBLY_TTL, self.conn.read_datagram()).await {
+                    Ok(Ok(frame)) => {
+                        if let Some(packet) = reassembly.push(frame, tokio::time::Instant::now()) {
+                            return Some(packet);
+                        }
+                    }
+                    Ok(Err(_)) => {
+                        *reassembly = Reassembler::default();
+                        return None;
+                    }
+                    Err(_) => reassembly.expire(tokio::time::Instant::now()),
+                }
+            }
+        })
+    }
+
+    fn closed(&self) -> BoxFuture<'_, ()> {
+        Box::pin(async move {
+            let _ = self.conn.closed().await;
+        })
+    }
+
+    fn is_closed(&self) -> bool {
+        self.conn.close_reason().is_some()
+    }
+
+    fn path_description(&self) -> String {
+        // Report what iroh actually knows, never a guess.
+        let snapshot = crate::net::snapshot_connection(&self.conn);
+        match snapshot.paths.iter().find(|path| path.is_selected) {
+            Some(path) => format!("{} via {}", snapshot.transport, path.remote),
+            None => format!("{}, no selected path yet", snapshot.transport),
+        }
+    }
+}
+
+/// Opens and accepts data plane links over iroh.
+#[derive(Debug, Clone)]
+pub struct IrohTransport {
+    adapter: EndpointAdapter,
+    limits: Arc<Limits>,
+    lookup: Arc<dyn TransportContext>,
+}
+
+impl IrohTransport {
+    /// Creates a transport on an existing endpoint.
+    pub fn new(
+        adapter: EndpointAdapter,
+        limits: Arc<Limits>,
+        lookup: Arc<dyn TransportContext>,
+    ) -> Self {
+        Self {
+            adapter,
+            limits,
+            lookup,
+        }
+    }
+
+    /// Completes an inbound data connection that the accept loop routed here.
+    ///
+    /// The membership handshake runs first, exactly as on a control
+    /// connection, so an unauthenticated caller never reaches a plugin.
+    pub async fn accept(&self, conn: Connection) -> Result<InboundLink, TransportError> {
+        let peer = conn.remote_id();
+        let (mut send, mut recv) = conn
+            .accept_bi()
+            .await
+            .map_err(|err| TransportError::Other(format!("no data channel stream: {err}")))?;
+
+        let local_id = self.adapter.endpoint_id();
+        let known = self.lookup.snapshot().await;
+        let outcome = handshake::respond(
+            &conn,
+            &mut send,
+            &mut recv,
+            local_id,
+            &self.limits,
+            |network| known.get(&network).cloned(),
+        )
+        .await
+        .map_err(|err| match err {
+            ProtocolError::UnknownNetwork => {
+                TransportError::Other("network is not active for the data plane".into())
+            }
+            other => TransportError::Other(other.to_string()),
+        })?;
+
+        let open: DataOpen = decode(
+            &read_frame(&mut recv, self.limits.max_frame_len)
+                .await
+                .map_err(|err| TransportError::Other(err.to_string()))?,
+        )
+        .map_err(|err| TransportError::Other(err.to_string()))?;
+
+        if open.protocol.is_empty() || open.protocol.len() > MAX_DATA_PROTOCOL_LEN {
+            return Err(TransportError::Other(
+                "data channel protocol id is out of bounds".into(),
+            ));
+        }
+
+        let serves = self.lookup.serves(outcome.network_id, &open.protocol).await;
+        if open.max_datagram == 0 || conn.max_datagram_size().is_none() {
+            return Err(TransportError::Other(
+                "data channel has no datagram support".into(),
+            ));
+        }
+        let ack = DataOpenAck {
+            accepted: serves,
+            max_datagram: MAX_DATA_DATAGRAM as u32,
+        };
+        write_frame(
+            &mut send,
+            &encode(&ack).map_err(|err| TransportError::Other(err.to_string()))?,
+            self.limits.max_frame_len,
+        )
+        .await
+        .map_err(|err| TransportError::Other(err.to_string()))?;
+
+        if !serves {
+            conn.close(4u32.into(), b"no plugin for this protocol");
+            return Err(TransportError::Declined(open.protocol));
+        }
+
+        let link = IrohLink::new(
+            outcome.network_id,
+            peer,
+            conn,
+            open.max_datagram as usize,
+            send,
+            recv,
+        );
+        Ok(InboundLink {
+            network: outcome.network_id,
+            peer,
+            protocol: open.protocol,
+            link: Arc::new(link),
+        })
+    }
+}
+
+impl PacketTransport for IrohTransport {
+    fn name(&self) -> &str {
+        "iroh"
+    }
+
+    fn as_any(&self) -> &dyn std::any::Any {
+        self
+    }
+
+    fn open<'a>(
+        &'a self,
+        network: NetworkId,
+        peer: EndpointId,
+        protocol: &'a str,
+    ) -> BoxFuture<'a, Result<SharedLink, TransportError>> {
+        Box::pin(async move {
+            if protocol.is_empty() || protocol.len() > MAX_DATA_PROTOCOL_LEN {
+                return Err(TransportError::Other(
+                    "data channel protocol id is out of bounds".into(),
+                ));
+            }
+            let keys = self
+                .lookup
+                .snapshot()
+                .await
+                .remove(&network)
+                .ok_or_else(|| TransportError::Other("network is not active".into()))?;
+
+            let addr = iroh::EndpointAddr::new(peer);
+            let conn = self
+                .adapter
+                .endpoint()
+                .connect(addr, DATA_ALPN)
+                .await
+                .map_err(|err| TransportError::Unreachable(err.to_string()))?;
+            let (mut send, mut recv) = conn
+                .open_bi()
+                .await
+                .map_err(|err| TransportError::Unreachable(err.to_string()))?;
+
+            handshake::initiate(
+                &conn,
+                &mut send,
+                &mut recv,
+                self.adapter.endpoint_id(),
+                &keys,
+                &self.limits,
+            )
+            .await
+            .map_err(|err| TransportError::Other(err.to_string()))?;
+
+            let open = DataOpen {
+                protocol: protocol.to_string(),
+                max_datagram: MAX_DATA_DATAGRAM as u32,
+            };
+            write_frame(
+                &mut send,
+                &encode(&open).map_err(|err| TransportError::Other(err.to_string()))?,
+                self.limits.max_frame_len,
+            )
+            .await
+            .map_err(|err| TransportError::Other(err.to_string()))?;
+
+            let ack: DataOpenAck = decode(
+                &read_frame(&mut recv, self.limits.max_frame_len)
+                    .await
+                    .map_err(|err| TransportError::Other(err.to_string()))?,
+            )
+            .map_err(|err| TransportError::Other(err.to_string()))?;
+
+            if !ack.accepted {
+                conn.close(4u32.into(), b"declined");
+                return Err(TransportError::Declined(protocol.to_string()));
+            }
+
+            if ack.max_datagram == 0 || conn.max_datagram_size().is_none() {
+                return Err(TransportError::Other(
+                    "data channel has no datagram support".into(),
+                ));
+            }
+
+            let link = IrohLink::new(network, peer, conn, ack.max_datagram as usize, send, recv);
+            Ok(Arc::new(link) as SharedLink)
+        })
+    }
+}

crates/tsunagi-core/src/dataplane/transport/mod.rs

@@ -0,0 +1,207 @@
+//! The data plane transport boundary.
+//!
+//! This is the seam that keeps the control protocol and the data plane
+//! independent. An [`IpPlugin`] never learns how its packets are moved: it is
+//! handed a [`PacketLink`] to a peer and writes datagrams into it. Whether
+//! that link runs over iroh today, a raw UDP socket, or something else
+//! entirely tomorrow is the transport's business alone.
+//!
+//! [`IpPlugin`]: crate::dataplane::IpPlugin
+//!
+//! # Why the transport may use iroh
+//!
+//! The separation between control and data is **logical**, not a ban on
+//! sharing technology. Refusing to use iroh for data would throw away exactly
+//! what iroh is good at — hole punching a direct path between two peers behind
+//! NAT, with a relay as fallback — and force the data plane to reimplement it.
+//! So the default transport is [`iroh_link::IrohTransport`], which gives every
+//! plugin that connectivity for free.
+//!
+//! What the separation does buy is that the control protocol in
+//! [`crate::proto`] knows nothing about packets, and this module knows nothing
+//! about WireGuard. Either side can be replaced on its own.
+//!
+//! # Semantics
+//!
+//! A link is an **unreliable, unordered datagram** channel, because that is
+//! what a tunnelled UDP protocol needs: no retransmission, no head-of-line
+//! blocking, loss is normal rather than an error. It is authenticated and
+//! encrypted by the transport, and scoped to exactly one network, one peer and
+//! one plugin protocol.
+
+mod fragments;
+pub mod iroh_link;
+
+use std::sync::Arc;
+
+use bytes::Bytes;
+use iroh::EndpointId;
+
+use crate::BoxFuture;
+use crate::identity::NetworkId;
+
+/// Why a data plane link failed.
+///
+/// None of these ever stop the control plane.
+#[derive(Debug, thiserror::Error)]
+#[non_exhaustive]
+pub enum TransportError {
+    /// The peer is not reachable for the data plane right now.
+    #[error("peer is unreachable: {0}")]
+    Unreachable(String),
+    /// The peer declined to open a channel for this protocol.
+    #[error("peer declined a data channel for protocol `{0}`")]
+    Declined(String),
+    /// The link is closed.
+    #[error("data link is closed")]
+    Closed,
+    /// A datagram was larger than the link can carry.
+    #[error("datagram of {size} bytes exceeds the {limit} byte link limit")]
+    TooLarge {
+        /// Size that was attempted.
+        size: usize,
+        /// Largest datagram this link accepts.
+        limit: usize,
+    },
+    /// Anything else.
+    #[error("data transport error: {0}")]
+    Other(String),
+}
+
+/// An authenticated datagram channel to one peer, for one plugin protocol.
+///
+/// Dropping the link closes it.
+pub trait PacketLink: Send + Sync + std::fmt::Debug + 'static {
+    /// The network this link belongs to.
+    fn network(&self) -> NetworkId;
+
+    /// The authenticated peer on the other end.
+    fn peer(&self) -> EndpointId;
+
+    /// The largest datagram this link can carry, in bytes.
+    ///
+    /// This is the logical payload limit. A transport can fragment underneath
+    /// it so path MTU changes do not force a plugin to resize the host interface.
+    fn max_datagram_size(&self) -> usize;
+
+    /// Sends one datagram.
+    ///
+    /// Delivery is not guaranteed. Returning `Ok` means the datagram was
+    /// handed to the transport, nothing more.
+    fn send(&self, payload: Bytes) -> Result<(), TransportError>;
+
+    /// Sends a datagram with an opaque stable flow identifier. Plugins derive
+    /// this before encryption; transports that do not route can ignore it.
+    fn send_flow(
+        &self,
+        payload: Bytes,
+        _flow: super::routing::FlowId,
+    ) -> Result<(), TransportError> {
+        self.send(payload)
+    }
+
+    /// Receives the next datagram, or `None` once the link is finished.
+    fn recv(&self) -> BoxFuture<'_, Option<Bytes>>;
+
+    /// Resolves once the link is closed, for whatever reason.
+    fn closed(&self) -> BoxFuture<'_, ()>;
+
+    /// Whether the link is already closed.
+    ///
+    /// Lets the owner notice a dead link and ask for a new one without
+    /// keeping a task parked on [`PacketLink::closed`].
+    fn is_closed(&self) -> bool;
+
+    /// A short description of the path in use, for diagnostics.
+    ///
+    /// Reports what the transport actually knows. It must not invent a value.
+    fn path_description(&self) -> String;
+}
+
+/// A shared handle to a link.
+pub type SharedLink = std::sync::Arc<dyn PacketLink>;
+
+/// An inbound link a peer opened towards us.
+#[derive(Debug)]
+pub struct InboundLink {
+    /// The network it belongs to.
+    pub network: NetworkId,
+    /// The peer that opened it.
+    pub peer: EndpointId,
+    /// The plugin protocol it carries.
+    pub protocol: String,
+    /// The link itself.
+    pub link: SharedLink,
+}
+
+/// Opens and accepts data plane links.
+///
+/// The agent owns one of these and hands links to plugins; plugins never call
+/// it directly.
+pub trait PacketTransport: Send + Sync + std::fmt::Debug + 'static {
+    /// A short name used in diagnostics.
+    fn name(&self) -> &str;
+
+    /// Lets the agent recover the concrete transport to drive its accept side.
+    ///
+    /// Accepting is inherently transport-specific — it starts from whatever
+    /// the transport's own listener produced — so it is not part of this
+    /// trait's uniform interface.
+    fn as_any(&self) -> &dyn std::any::Any;
+
+    /// Opens a link to `peer` in `network` for `protocol`.
+    fn open<'a>(
+        &'a self,
+        network: NetworkId,
+        peer: EndpointId,
+        protocol: &'a str,
+    ) -> BoxFuture<'a, Result<SharedLink, TransportError>>;
+}
+
+/// A composite packet transport that dispatches requests by protocol id.
+#[derive(Debug)]
+pub struct MultiPacketTransport {
+    default: Arc<dyn PacketTransport>,
+    by_protocol: std::collections::HashMap<String, Arc<dyn PacketTransport>>,
+}
+
+impl MultiPacketTransport {
+    /// Creates a new composite transport with a default fallback transport.
+    pub fn new(
+        default: Arc<dyn PacketTransport>,
+        by_protocol: std::collections::HashMap<String, Arc<dyn PacketTransport>>,
+    ) -> Self {
+        Self {
+            default,
+            by_protocol,
+        }
+    }
+
+    /// Access the default underlying transport.
+    pub fn default_transport(&self) -> &Arc<dyn PacketTransport> {
+        &self.default
+    }
+}
+
+impl PacketTransport for MultiPacketTransport {
+    fn name(&self) -> &str {
+        "multi"
+    }
+
+    fn as_any(&self) -> &dyn std::any::Any {
+        self
+    }
+
+    fn open<'a>(
+        &'a self,
+        network: NetworkId,
+        peer: EndpointId,
+        protocol: &'a str,
+    ) -> BoxFuture<'a, Result<SharedLink, TransportError>> {
+        if let Some(transport) = self.by_protocol.get(protocol) {
+            transport.open(network, peer, protocol)
+        } else {
+            self.default.open(network, peer, protocol)
+        }
+    }
+}

crates/tsunagi-core/src/dataplane/tunnel.rs

@@ -0,0 +1,380 @@
+//! Generic harness for IP tunnel plugins.
+//!
+//! Implementing [`super::IpPlugin`] directly requires managing per-peer background
+//! tasks, synchronization, packet queues, and graceful shutdown.
+//!
+//! [`TunnelCodec`] provides a simplified interface where a plugin author only
+//! defines cryptographic transformation and handshake payloads.
+//! [`GenericTunnelPlugin`] adapts any [`TunnelCodec`] into a full [`super::IpPlugin`].
+
+use std::collections::HashMap;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::{Arc, Mutex, RwLock};
+
+use bytes::Bytes;
+use iroh::EndpointId;
+use tokio::task::JoinHandle;
+
+use super::{IpPlugin, PluginCapability, PluginContext, PluginError, ProtocolOption, SharedLink};
+use crate::BoxFuture;
+use crate::identity::NetworkId;
+
+/// The simplified contract for an IP tunnel protocol implementation.
+///
+/// Implementors only handle key announcements, link lifecycle events,
+/// and packet encrypt/decrypt. Concurrency and task management are handled
+/// by [`GenericTunnelPlugin`].
+pub trait TunnelCodec: Send + Sync + 'static {
+    /// Protocol identifier, e.g. `tcp-tls`.
+    fn protocol_id(&self) -> &str;
+
+    /// Protocol wire version.
+    fn protocol_version(&self) -> u16;
+
+    /// Options accepted by the protocol.
+    fn options(&self) -> &'static [ProtocolOption] {
+        &[]
+    }
+
+    /// Generates local capability announcement data for a network.
+    fn local_capability_data(&self, network: NetworkId) -> Result<Vec<u8>, PluginError>;
+
+    /// Handles a peer's announced capability payload.
+    fn on_peer_capability_data(
+        &self,
+        network: NetworkId,
+        peer: EndpointId,
+        data: &[u8],
+    ) -> Result<(), PluginError>;
+
+    /// Called when an authenticated link to a peer is established.
+    fn on_peer_link_up(&self, network: NetworkId, peer: EndpointId, link: &SharedLink) {
+        let _ = (network, peer, link);
+    }
+
+    /// Called when a peer goes away.
+    fn on_peer_down(&self, network: NetworkId, peer: EndpointId) {
+        let _ = (network, peer);
+    }
+
+    /// Encrypts an outbound IP packet into a payload to send over the link.
+    fn encrypt(
+        &self,
+        network: NetworkId,
+        peer: EndpointId,
+        packet: &[u8],
+    ) -> Result<Bytes, PluginError>;
+
+    /// Decrypts an inbound payload from the link into an IP packet.
+    fn decrypt(
+        &self,
+        network: NetworkId,
+        peer: EndpointId,
+        payload: &[u8],
+    ) -> Result<Bytes, PluginError>;
+
+    /// Called during shutdown.
+    fn shutdown<'a>(&'a self) -> BoxFuture<'a, ()> {
+        Box::pin(async {})
+    }
+}
+
+struct TunnelPeerState {
+    link: SharedLink,
+    tx_packets: AtomicU64,
+    rx_packets: AtomicU64,
+    tx_bytes: AtomicU64,
+    rx_bytes: AtomicU64,
+    dropped: AtomicU64,
+    established_at: std::time::Instant,
+}
+
+/// Statistics and status for one active peer in [`GenericTunnelPlugin`].
+#[derive(Debug, Clone)]
+pub struct TunnelPeerReport {
+    /// Peer endpoint identity.
+    pub peer: EndpointId,
+    /// Protocol identifier.
+    pub protocol: String,
+    /// Human-readable path description.
+    pub path: String,
+    /// Packets successfully encrypted and sent.
+    pub tx_packets: u64,
+    /// Packets successfully received and decrypted.
+    pub rx_packets: u64,
+    /// Plaintext bytes successfully encrypted and sent.
+    pub tx_bytes: u64,
+    /// Plaintext bytes successfully received and decrypted.
+    pub rx_bytes: u64,
+    /// Packets dropped due to encryption/decryption/send failures.
+    pub dropped: u64,
+    /// Uptime in seconds since the data link was established.
+    pub uptime_secs: u64,
+}
+
+/// Generic wrapper that turns a [`TunnelCodec`] into a full [`IpPlugin`].
+pub struct GenericTunnelPlugin<C: TunnelCodec> {
+    codec: Arc<C>,
+    context: Mutex<Option<PluginContext>>,
+    links: RwLock<HashMap<(NetworkId, EndpointId), Arc<TunnelPeerState>>>,
+    tasks: Mutex<HashMap<(NetworkId, EndpointId), JoinHandle<()>>>,
+}
+
+impl<C: TunnelCodec> GenericTunnelPlugin<C> {
+    /// Wraps `codec` into an [`IpPlugin`].
+    pub fn new(codec: C) -> Self {
+        Self {
+            codec: Arc::new(codec),
+            context: Mutex::new(None),
+            links: RwLock::new(HashMap::new()),
+            tasks: Mutex::new(HashMap::new()),
+        }
+    }
+
+    /// Returns a reference to the underlying codec.
+    pub fn codec(&self) -> &C {
+        &self.codec
+    }
+
+    /// Returns the active peers with established data links for a network.
+    pub fn active_peers(&self, network: NetworkId) -> Vec<TunnelPeerReport> {
+        let guard = match self.links.read() {
+            Ok(g) => g,
+            Err(p) => p.into_inner(),
+        };
+        guard
+            .iter()
+            .filter(|((net, _), _)| *net == network)
+            .map(|((_, peer), state)| TunnelPeerReport {
+                peer: *peer,
+                protocol: self.codec.protocol_id().to_string(),
+                path: state.link.path_description(),
+                tx_packets: state.tx_packets.load(Ordering::Relaxed),
+                rx_packets: state.rx_packets.load(Ordering::Relaxed),
+                tx_bytes: state.tx_bytes.load(Ordering::Relaxed),
+                rx_bytes: state.rx_bytes.load(Ordering::Relaxed),
+                dropped: state.dropped.load(Ordering::Relaxed),
+                uptime_secs: state.established_at.elapsed().as_secs(),
+            })
+            .collect()
+    }
+}
+
+impl<C: TunnelCodec> std::fmt::Debug for GenericTunnelPlugin<C> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("GenericTunnelPlugin")
+            .field("protocol_id", &self.codec.protocol_id())
+            .field("protocol_version", &self.codec.protocol_version())
+            .finish()
+    }
+}
+
+impl<C: TunnelCodec> IpPlugin for GenericTunnelPlugin<C> {
+    fn protocol_id(&self) -> &str {
+        self.codec.protocol_id()
+    }
+
+    fn protocol_version(&self) -> u16 {
+        self.codec.protocol_version()
+    }
+
+    fn options(&self) -> &'static [ProtocolOption] {
+        self.codec.options()
+    }
+
+    fn attach(&self, context: PluginContext) {
+        if let Ok(mut guard) = self.context.lock() {
+            *guard = Some(context);
+        }
+    }
+
+    fn local_capability(
+        &self,
+        network: NetworkId,
+    ) -> Result<Option<PluginCapability>, PluginError> {
+        let data = self.codec.local_capability_data(network)?;
+        Ok(Some(PluginCapability {
+            protocol: self.codec.protocol_id().to_string(),
+            version: self.codec.protocol_version(),
+            enabled: true,
+            data,
+        }))
+    }
+
+    fn on_peer_capability(
+        &self,
+        network: NetworkId,
+        peer: EndpointId,
+        capability: &PluginCapability,
+    ) -> Result<(), PluginError> {
+        if capability.protocol != self.codec.protocol_id() {
+            return Ok(());
+        }
+        self.codec
+            .on_peer_capability_data(network, peer, &capability.data)
+    }
+
+    fn carry(&self, network: NetworkId, peer: EndpointId, packet: bytes::Bytes) -> bool {
+        let state = {
+            let guard = match self.links.read() {
+                Ok(g) => g,
+                Err(p) => p.into_inner(),
+            };
+            guard.get(&(network, peer)).cloned()
+        };
+
+        let Some(state) = state else {
+            return false;
+        };
+
+        match self.codec.encrypt(network, peer, &packet) {
+            Ok(ciphertext) => {
+                if state.link.send(ciphertext).is_ok() {
+                    state.tx_packets.fetch_add(1, Ordering::Relaxed);
+                    state
+                        .tx_bytes
+                        .fetch_add(packet.len() as u64, Ordering::Relaxed);
+                    true
+                } else {
+                    state.dropped.fetch_add(1, Ordering::Relaxed);
+                    false
+                }
+            }
+            Err(err) => {
+                state.dropped.fetch_add(1, Ordering::Relaxed);
+                tracing::debug!(%peer, %err, "tunnel encrypt failed");
+                false
+            }
+        }
+    }
+
+    fn on_peer_link(&self, network: NetworkId, peer: EndpointId, link: SharedLink) {
+        let state = Arc::new(TunnelPeerState {
+            link: Arc::clone(&link),
+            tx_packets: AtomicU64::new(0),
+            rx_packets: AtomicU64::new(0),
+            tx_bytes: AtomicU64::new(0),
+            rx_bytes: AtomicU64::new(0),
+            dropped: AtomicU64::new(0),
+            established_at: std::time::Instant::now(),
+        });
+        {
+            let mut guard = match self.links.write() {
+                Ok(g) => g,
+                Err(p) => p.into_inner(),
+            };
+            guard.insert((network, peer), Arc::clone(&state));
+        }
+
+        self.codec.on_peer_link_up(network, peer, &link);
+
+        let codec = Arc::clone(&self.codec);
+        let sink = match self.context.lock() {
+            Ok(g) => g.as_ref().map(|ctx| ctx.packet_sink()),
+            Err(p) => p.into_inner().as_ref().map(|ctx| ctx.packet_sink()),
+        };
+
+        let rx_link = Arc::clone(&link);
+        let rx_state = Arc::clone(&state);
+        let handle = tokio::spawn(async move {
+            while let Some(payload) = rx_link.recv().await {
+                match codec.decrypt(network, peer, &payload) {
+                    Ok(packet) => {
+                        rx_state.rx_packets.fetch_add(1, Ordering::Relaxed);
+                        rx_state
+                            .rx_bytes
+                            .fetch_add(packet.len() as u64, Ordering::Relaxed);
+                        if let Some(ref sink) = sink {
+                            sink.deliver(network, peer, packet).await;
+                        }
+                    }
+                    Err(err) => {
+                        rx_state.dropped.fetch_add(1, Ordering::Relaxed);
+                        tracing::debug!(%peer, %err, "tunnel decrypt failed");
+                    }
+                }
+            }
+        });
+
+        let mut guard = match self.tasks.lock() {
+            Ok(g) => g,
+            Err(p) => p.into_inner(),
+        };
+        if let Some(old) = guard.insert((network, peer), handle) {
+            old.abort();
+        }
+    }
+
+    fn on_peer_gone(&self, network: NetworkId, peer: EndpointId) {
+        {
+            let mut guard = match self.tasks.lock() {
+                Ok(g) => g,
+                Err(p) => p.into_inner(),
+            };
+            if let Some(task) = guard.remove(&(network, peer)) {
+                task.abort();
+            }
+        }
+        {
+            let mut guard = match self.links.write() {
+                Ok(g) => g,
+                Err(p) => p.into_inner(),
+            };
+            guard.remove(&(network, peer));
+        }
+        self.codec.on_peer_down(network, peer);
+    }
+
+    fn on_network_deactivated(&self, network: NetworkId) {
+        let keys_to_remove: Vec<(NetworkId, EndpointId)> = {
+            let guard = match self.tasks.lock() {
+                Ok(g) => g,
+                Err(p) => p.into_inner(),
+            };
+            guard
+                .keys()
+                .filter(|(net, _)| *net == network)
+                .copied()
+                .collect()
+        };
+
+        {
+            let mut guard = match self.tasks.lock() {
+                Ok(g) => g,
+                Err(p) => p.into_inner(),
+            };
+            for key in &keys_to_remove {
+                if let Some(task) = guard.remove(key) {
+                    task.abort();
+                }
+            }
+        }
+
+        {
+            let mut guard = match self.links.write() {
+                Ok(g) => g,
+                Err(p) => p.into_inner(),
+            };
+            guard.retain(|(net, _), _| *net != network);
+        }
+    }
+
+    fn shutdown<'a>(&'a self) -> BoxFuture<'a, ()> {
+        Box::pin(async move {
+            let mut tasks = Vec::new();
+            {
+                let mut guard = match self.tasks.lock() {
+                    Ok(g) => g,
+                    Err(p) => p.into_inner(),
+                };
+                for (_, task) in guard.drain() {
+                    tasks.push(task);
+                }
+            }
+            for task in tasks {
+                task.abort();
+            }
+            self.codec.shutdown().await;
+        })
+    }
+}