feat: provide access to connection Waker to datagram Endpoint (#1598)

* Remove Default for datagram (Pre)ConnectionInfo structs

It doesn't make much sense for there to be default values for these, and
as more fields are added a Default may become awkward or impossible.

This removes the ability to construct these outside of s2n-quic, but
doing so is awkward if there's no reasonable default value for some of
the fields. (The next commit adds such a value for ConnectionInfo).

* Add Waker to datagram ConnectionInfo

This waker allows datagram receiver/senders to wake up the connection,
which will re-poll the connection for interest in sending. When
implementing a custom datagram Receiver which wants to schedule a reply
datagram, this Waker or something like it is necessary to indirect the
wakeup of the connection and subsequent call to the Sender's
on_transmit.

This is a waker and not a connection handle for two reasons:

* The Waker does not directly extend the lifetime of the connection,
  which avoids keeping the connection data indefinitely alive for cases
  where the Waker is stored within the Sender or Receiver.
* s2n-quic calling datagram Endpoint::new_connection doesn't have easy
  access to an application handle to the connection.

Note that applications still must retain the Connection or a Handle to
it: when the last application handle closes, the connection is also
closed, even if there are Wakers for that connection still around.

In practice this seems useful as it allows bounding the number of active
connections with an Endpoint and the extra waste of connection handles
is unlikely to be significant.

Author: Mark-Simulacrum

quic/s2n-quic-core/src/datagram/default.rs

@@ -554,12 +554,13 @@ mod tests {
     use super::*;
     use crate::datagram::WriteError;
     use core::task::{Context, Poll};
-    use futures_test::task::new_count_waker;
+    use futures_test::task::{new_count_waker, noop_waker};
 
     #[test]
     fn send_datagram_forced() {
         let conn_info = ConnectionInfo {
             max_datagram_payload: 100,
+            waker: noop_waker(),
         };
         // Create a default sender queue that only holds two elements
         let mut default_sender = Sender::builder()
@@ -598,6 +599,7 @@ mod tests {
     fn send_datagram() {
         let conn_info = ConnectionInfo {
             max_datagram_payload: 100,
+            waker: noop_waker(),
         };
         // Create a default sender queue that only holds two elements
         let mut default_sender = Sender::builder()
@@ -636,7 +638,7 @@ mod tests {
 
     #[test]
     fn poll_send_datagram() {
-        let conn_info = ConnectionInfo::new(100);
+        let conn_info = ConnectionInfo::new(100, noop_waker());
         let mut default_sender = Sender::builder()
             .with_capacity(2)
             .with_connection_info(&conn_info)
@@ -708,6 +710,7 @@ mod tests {
     fn retain_datagrams() {
         let conn_info = ConnectionInfo {
             max_datagram_payload: 100,
+            waker: noop_waker(),
         };
         let mut default_sender = Sender::builder()
             .with_capacity(3)
@@ -752,7 +755,7 @@ mod tests {
     // Check that our default on_transmit function doesn't continue to pop datagrams
     // off the send queue if the remaining packet space is too small to send datagrams.
     fn has_written_test() {
-        let conn_info = ConnectionInfo::new(100);
+        let conn_info = ConnectionInfo::new(100, noop_waker());
         let mut default_sender = Sender::builder()
             .with_connection_info(&conn_info)
             .build()

quic/s2n-quic-core/src/datagram/traits.rs

@@ -1,6 +1,8 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+use core::task::Waker;
+
 use crate::connection;
 
 /// The datagram endpoint trait provides a way to implement custom unreliable datagram
@@ -17,49 +19,46 @@ pub trait Endpoint: 'static + Send {
     fn max_datagram_frame_size(&self, info: &PreConnectionInfo) -> u64;
 }
 
-/// ConnectionInfo contains the peer's limit on the size of datagrams
-/// they accept
-///
-/// Sending a datagram larger than this will result in an error
+/// Information about the accepted connection for which the Sender/Receiver are being created.
 #[non_exhaustive]
 #[derive(Debug)]
 pub struct ConnectionInfo {
+    /// The peer's limit on the size of datagrams they will accept. Datagrams larger than this will
+    /// result in an error.
     pub max_datagram_payload: u64,
+
+    /// The `waker` associated with this connection. When woken, the connection will check the
+    /// interest in sending ([`Sender::has_transmission_interest`]), and send packets if necessary.
+    ///
+    /// This is useful for applications that wish to enqueue packets with `Sender` without calling
+    /// `datagram_mut`, perhaps because they don't have an available handle to the connection when
+    /// enqueuing packets, or wish to avoid incurring the lock/unlock required by `datagram_mut`.
+    pub waker: Waker,
 }
 
 impl ConnectionInfo {
     #[doc(hidden)]
-    pub fn new(max_datagram_payload: u64) -> Self {
+    pub fn new(max_datagram_payload: u64, waker: Waker) -> Self {
         ConnectionInfo {
             max_datagram_payload,
+            waker,
         }
     }
 }
 
-impl Default for ConnectionInfo {
-    fn default() -> Self {
-        ConnectionInfo::new(0)
-    }
-}
-
 /// PreConnectionInfo will contain information needed to determine whether
 /// or not a provider will accept datagrams.
 #[non_exhaustive]
 pub struct PreConnectionInfo(());
 
 impl PreConnectionInfo {
     #[doc(hidden)]
+    #[allow(clippy::new_without_default)]
     pub fn new() -> Self {
         PreConnectionInfo(())
     }
 }
 
-impl Default for PreConnectionInfo {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
 /// ReceiveContext contains information about the connection.
 #[non_exhaustive]
 #[derive(Debug)]

quic/s2n-quic-transport/src/space/session_context.rs

@@ -399,7 +399,8 @@ impl<'a, Config: endpoint::Config, Pub: event::ConnectionPublisher>
             self.limits.max_keep_alive_period(),
         );
 
-        let conn_info = ConnectionInfo::new(datagram_limits.max_datagram_payload);
+        let conn_info =
+            ConnectionInfo::new(datagram_limits.max_datagram_payload, self.waker.clone());
         let (datagram_sender, datagram_receiver) = self.datagram.create_connection(&conn_info);
         let datagram_manager = datagram::Manager::new(
             datagram_sender,