feat(iroh): add new protocols to router at runtime

[Frando]

Description

This allows adding new protocols and removing protocols to an iroh Router after the router is built.
Also adds a timeout to shutdown for a protocol handler of 30s.

Also wrote a test for this.

Breaking Changes

Notes & open questions

Change checklist

• Self-review.
• Documentation updates following the style guide, if relevant.
• Tests if relevant.

[github-actions]

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

Last updated: 2025-06-26T11:14:04Z

[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: 0fcccf4

[flub]

largely looks good to me, nice to have this!

[flub]

"router actor" is something rather internal, no? Can we not say "the router closed" or maybe even "the endpoint closed"?

[flub]

"yields" or returns? As far as I read the code it should be "returns"?

[flub]

Can you elaborate more on what happens to existing connections? Will they all be closed by the old handler? How does that work? If you're repeating how handlers shut down connections that's fine, docs should repeat things.

[flub]

Can you call out the differences in behaviour with calling accept where a previous handler was already handling this protocol?

[Frando]

@flub Thanks for the review, clarified the docs. LMK if there's still something unclear from reading the docs.

[TheButlah]

unsure if I should post here or open an issue. is there some way that we can allow end-users to have a Box<dyn DynProtocolHandler>? Or at least, introduce a BoxedProtocolHandler type? Those types appear private rn.

Use case: facilitating third-party routers, or facilitating storing protocol handlers in structs, such as for the purposes of configuration:

#[derive(Debug, bon::Builder)]
pub struct Agent {
    #[builder(field)]
    handlers: HashMap<Alpn, Box<dyn ProtocolHandler>>,
    /// Provide a specific secret key for mTLS, instead of dynamically generating one
    secret_key: Option<iroh::SecretKey>,
    #[builder(default)]
    discovery: EnabledDiscoveryServices,
    /// in QUIC, the ALPN allows for multiple connections on same port, and it is ideal
    /// to circumvent firewalls to always use port 443 (same as https). You can also set
    /// this to 0 to dynamically choose a port.
    #[builder(default = 443)]
    port: u16,
}

impl<S: agent_builder::State> AgentBuilder<S> {
    fn router(
        mut self,
        alpn: &'static str,
        router: impl Into<Box<dyn ProtocolHandler>>,
    ) -> Self {
        self.handlers.insert(Alpn(alpn), router.into());
        self
    }
}

//...

        let mut router = iroh::protocol::Router::builder(endpoint);
        for (alpn, handler) in self.handlers {
            router = router.accept(alpn.0, handler);
        }

[Frando]

unsure if I should post here or open an issue. is there some way that we can allow end-users to have a Box<dyn DynProtocolHandler>? Or at least, introduce a BoxedProtocolHandler type? Those types appear private rn.

That's valid, IMO. I opened #3366.