refactor!: make OutgoingZeroRttConnection implement Clone (#3607)

## Description

This allows to get hold of a future that resolves with `ZeroRttStatus`
while doing work with the connection (e.g. opening streams) in parallel,
without having to give up ownership of the `OutgoingZeroRttConnection`.

Used in n0-computer/irpc#81

## Breaking Changes

* `OutgoingZeroRttConnection::handshake_completed()` now takes `&self`
instead of `self`

## Notes & open questions

<!-- Any notes, remarks or open questions you have to make about the PR.
-->

## Change checklist
<!-- Remove any that are not relevant. -->
- [x] Self-review.
- [x] Documentation updates following the [style
guide](https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#appendix-a-full-conventions-text),
if relevant.
- [x] Tests if relevant.
- [x] 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`](https://github.com/n0-computer/quic-rpc)
    - [ ] [`iroh-gossip`](https://github.com/n0-computer/iroh-gossip)
    - [ ] [`iroh-blobs`](https://github.com/n0-computer/iroh-blobs)
    - [ ] [`dumbpipe`](https://github.com/n0-computer/dumbpipe)
    - [ ] [`sendme`](https://github.com/n0-computer/sendme)

---------

Co-authored-by: “ramfox” <“kasey@n0.computer”>

Author: Frando

iroh/src/endpoint/connection.rs

@@ -26,6 +26,7 @@ use std::{
 };
 
 use ed25519_dalek::{VerifyingKey, pkcs8::DecodePublicKey};
+use futures_util::{FutureExt, future::Shared};
 use iroh_base::EndpointId;
 use n0_error::{e, stack_error};
 use n0_future::time::Duration;
@@ -396,7 +397,8 @@ impl Connecting {
                     accepted: ZeroRttAccepted {
                         inner: zrtt_accepted,
                         _discovery_drop_guard: self._discovery_drop_guard,
-                    },
+                    }
+                    .shared(),
                 })
             }
             Err(inner) => Err(Self {
@@ -524,6 +526,7 @@ impl Future for Accepting {
         }
     }
 }
+
 /// Future that completes when a connection is fully established.
 ///
 /// For clients, the resulting value indicates if 0-RTT was accepted. For servers, the resulting
@@ -560,13 +563,13 @@ impl Future for ZeroRttAccepted {
 ///
 /// Look at the [`OutgoingZeroRttConnection::handshake_completed`] method for
 /// more details.
-#[derive(Debug)]
+#[derive(Debug, Clone)]
 pub struct OutgoingZeroRttConnection {
     inner: quinn::Connection,
-    accepted: ZeroRttAccepted,
+    accepted: Shared<ZeroRttAccepted>,
 }
 
-/// Returned from a `OutgoingZeroRttConnection::handshake_complete` method.
+/// Returned from [`OutgoingZeroRttConnection::handshake_completed`].
 #[derive(Debug)]
 pub enum ZeroRttStatus {
     /// If the 0-RTT data was accepted, you can continue to use any streams
@@ -598,9 +601,9 @@ impl OutgoingZeroRttConnection {
     ///
     /// Thus, those errors should only occur if someone connects to you with a
     /// modified iroh endpoint or with a plain QUIC client.
-    pub async fn handshake_completed(self) -> Result<ZeroRttStatus, AuthenticationError> {
-        let accepted = self.accepted.await;
-        let conn = conn_from_quinn_conn(self.inner)?;
+    pub async fn handshake_completed(&self) -> Result<ZeroRttStatus, AuthenticationError> {
+        let accepted = self.accepted.clone().await;
+        let conn = conn_from_quinn_conn(self.inner.clone())?;
 
         Ok(match accepted {
             true => ZeroRttStatus::Accepted(conn),

iroh/src/protocol.rs

@@ -159,7 +159,21 @@ pub trait ProtocolHandler: Send + Sync + std::fmt::Debug + 'static {
     ///
     /// Can be implemented as `async fn on_accepting(&self, accepting: Accepting) -> Result<Connection>`.
     ///
-    /// This enables accepting 0-RTT data from clients, among other things.
+    /// Typically, this method is used as an early interception point to accept
+    /// or reject a connection.
+    ///
+    /// However, this method can also be used to implement the accept side of a
+    /// 0-RTT connection.
+    ///
+    /// ## 0-RTT
+    ///
+    /// `ProtocolHandler::on_accepting` allows you to take over the connection
+    /// state machine early in the handshake processes, by calling [`Accepting::into_0rtt`].
+    ///
+    /// When working with 0-RTT, you may want to implement all of your protocol
+    /// logic in `on_accepting`. This is fine because `on_accepting` can handle
+    /// long-running processes. In this case, the [`ProtocolHandler::accept`] method
+    /// can simply return `Ok(())`.
     fn on_accepting(
         &self,
         accepting: Accepting,