feat(multipath): allow to monitor all connections

[Frando]

Description

Based on #3614, which adds ConnectionInfo, a weak reference to a connection.

This PR builds on that and adds a hook to the endpoint builder which allows implementors to observe all connections accepted or initiated by the endpoint.

The connection monitor is a new trait ConnectionMonitor with a single, synchronous method on_connection(&self, connection: ConnectionInfo). This is called for each incoming or outgoing connection. It is only called once the connection has handshaked. The trait is also implemented for Fn(ConnectionInfo) so you can also pass a closure to the endpoint builder function.

Why a hook in the builder? We considered two other approaches:

• A broadcast stream where you can subscribe to. This means that the stream can lag, though, which is not necessarily a nice API, and something downstream users have to deal with.
• A watcher over a list of connections (possibly per remote). This means we'd have to maintain a quite expensive watchable datastructure, and allocate the full list again on each change or become fancy with persistent data structure. This has a quite high complexity cost.

With the hook, the question of how to deal with this is up to implementors. You get a synchronous callback that may not block, and can make your own tradeoffs: Send over an unbounded channel, send over a broadcast channel, insert into a RwLock'd data structre, ...

With the hook being on the builder and not the endpoint, this trade-off is quite explicit because it can only be implemented once. If you need to monitor connections from multiple places, you have to dispatch yourself and decide what tradeoffs are good for your app.

The latest commit in this branch uses n0-computer/quinn#153 to add a closed method to the ConnectionInfo. This allows to get the ConnectionStats at the time when the connection closes, without keeping the connection alive by awaiting the future. It is used in the monitor-connection example to show the final stats for connections once they are closed.

Breaking Changes

Notes & open questions

Change checklist

• Self-review.
• Documentation updates following the style guide, if relevant.
• Tests if relevant.
• All breaking changes documented.
  • List all breaking changes in the above "Breaking Changes" section.
  • Open an issue or PR on any number0 repos that are affected by this breaking change. Give guidance on how the updates should be handled or do the actual updates themselves. The major ones are:
    • quic-rpc
    • iroh-gossip
    • iroh-blobs
    • dumbpipe
    • sendme

[github-actions]

Documentation for this PR has been generated and is available at: https://n0-computer.github.io/iroh/pr/3610/docs/iroh/

Last updated: 2025-11-06T11:26:05Z

[github-actions]

Netsim report & logs for this PR have been generated and is available at: LOGS
This report will remain available for 3 days.

Last updated for commit: 60c7efc

[flub]

Firstly, there's nothing here that I think is problematic. I could live with this, and the ConnectionInfo stuff is also reasonable on its own. Though the exposed stats have some questions that I raised in the other PR. But that doesn't mean I'm not going to question things :)

Why a hook in the builder? We considered two other approaches:

• A broadcast stream where you can subscribe to. [...]
• A watcher over a list of connections (possibly per remote). [...]

Main downside of a hook is that a user can mess up the magicsock itself by misbehaving. OTOH a broadcast stream would pub a tokio type in our public API. Perhaps overall the callback is the right tradeoff, though I'd like to check if we already have any established patterns for this in the API and see what other's opinions are.

 /// Called for each new connection the endpoint accepts or initiates.
 ///
 /// This is only called when a connection is fully established.
 fn on_connection(&self, connection: ConnectionInfo);

This immediately makes me wonder how soon folks will ask for something similar but earlier, on Incoming. Which leads to the question (and I apologise, I feel like we've had this discussion already) of why can't this be done by the protocol router? It has control of the Endpoint's accept loop. It could call protocol-independent hooks for all incoming connections?

Would it be that bad to force anyone that wants to observe connections from a protocol they don't control to use the router?

[flub]

This immediately makes me wonder how soon folks will ask for something similar but earlier, on Incoming. Which leads to the question (and I apologise, I feel like we've had this discussion already) of why can't this be done by the protocol router?

Oh, now I remember: it's outgoing connections that you can't track from the router.