feat!: make Connection::remote_id and Connection::alpn infallible

[ramfox]

Description

This PR refactors the connection API to make Connection::remote_id() and Connection::alpn() infallible. Previously, these methods could fail if called before the handshake completed or if the handshake data was unavailable. Now, Connection guarantees that it represents a fully authenticated connection with verified remote identity and ALPN protocol, since it now can only be constructed after successful handshake completion and authentication, eliminating the need for fallible accessors.

0-RTT API Improvements

The 0-RTT API has been restructured with clearer types and semantics:

• Use Incoming::accept to return an Accepting. Use Accepting::into_0rtt to return an IncomingZeroRttConnection

• Use Connecting::into_0rtt to return a OutgoingZeroRttConnection

• OutgoingZeroRttConnection: Represents client-side 0-RTT connections created via Connecting::into_0rtt(). Allows sending 0-RTT data before the handshake completes. Call handshake_completed() to get a ZeroRttStatus indicating whether the 0-RTT data was accepted or rejected by the server.

• IncomingZeroRttConnection: Represents server-side 0-RTT/0.5-RTT connections created via Accepting::into_0rtt(). Allows receiving 0-RTT data from clients or sending 0.5-RTT data before the handshake completes. Call handshake_completed() to get a fully authenticated Connection.

• ZeroRttStatus enum: Returned by OutgoingZeroRttConnection::handshake_completed() to indicate whether the server accepted or rejected the 0-RTT data:

  • ZeroRttStatus::Accepted(Connection): 0-RTT data was accepted, streams opened before handshake remain valid
  • ZeroRttStatus::Rejected(Connection): 0-RTT data was rejected, pre-handshake streams will error and data must be resent

These types replace the previous the previous version of Connection & the ZeroRttAccepted type and provide a more explicit API for handling 0-RTT connection states and outcomes.

Error Handling

• Connection authentication failures now return AuthenticationError during the conversion between a quinn:Connection (which can exist before the handshake completes) and an iroh::Connection. This error may occur if the remote endpoint is not using the expected TLS cryptography or if the remote endpoint is a plain quinn connection. You may also see these errors after calling the handshake_completed method on IncomingZeroRttConnection or OutgoingZeroRttConnection, if the connection was closed before the handshake completed.
• New ConnectingError type for errors during handshake completion

Breaking Changes

• iroh
  • changed
    • ConnectError::Connection - fields changed
    • AcceptError::Connection - fields changed
    • AcceptError::MissingRemoteEndpointId - fields changed
    • AcceptError::NotAllowed - fields changed
    • AcceptError::User - fields changed
    • Connecting::into_0rtt -> returns Result<OutgoingZeroRttConnection, Connecting>
  • removed
    • ProtocolHandler::on_connecting() removed - implement on_accepting() instead, which takes Accepting rather than Connecting
    • DynProtocolHandler::on_connecting() removed - implement on_accepting() instead
    • iroh::endpoint::IncomingFuture - use Accepting instead
    • iroh::endpoint::ZeroRttAccepted - replaced by explicit 0-RTT connection types

[github-actions]

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

Last updated: 2025-11-04T13:19:27Z

[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: 74a9dbd

[ramfox]

Still some open questions around the server side of the ZeroRttConnection!

[ramfox]

Okay, this latest version has ZeroRttClientConnection, ZeroRttServerConnection, ZeroRtt::Accepted and ZeroRtt::Rejected.

Besides bikeshedding the names ZeroRttClientConnection and ZeroRttServerConnection, how do we feel about this?

I think we either go this route, or a route that combines both sides into ZeroRttConnection & the annoying bit is that the server side also returns a ZeroRtt rather than just a Connection.

[ramfox]

Separated everything about Connection (Connecting, Accept, Incoming, any 0-rtt stuff) into iroh/src/endpoint/connection.rs

All structs are still exported from the endpoint mod so it's just an internal organizational change.

[matheus23]

I love the new API :) Infallible remote_id and ALPN are great!

Having a server and client version of ZeroRttConn is perfectly fine, perhaps I'd even extend that to Connecting (I wrote more about this in a comment).

Some comments and one thing to figure out (making 0-RTT work with ProtocolHandler).