feat(s2n-quic-core) TLS offloading

examples/tls-offloading/Cargo.toml

@@ -0,0 +1,8 @@
+[package]
+name = "tls-offloading"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+s2n-quic = { version = "1", path = "../../quic/s2n-quic", features = ["unstable-offload-tls"]}
+tokio = { version = "1", features = ["full"] }

examples/tls-offloading/README.md

@@ -0,0 +1,25 @@
+# TLS offload
+
+s2n-quic is single-threaded by default. This can cause performance issues in the instance where many clients try to connect to a single s2n-quic server at the same time. Each incoming Client Hello will cause the s2n-quic server event loop to be blocked while the TLS provider completes the expensive cryptographic operations necessary to process the Client Hello. This has the potential to slow down all existing connections in favor of new ones. The TLS offloading feature attempts to alleviate this problem by moving each TLS connection to a separate async task, which can then be spawned by the runtime the user provides.
+
+To do this, implement the `offload::Executor` trait with the runtime of your choice. In this example, we use the `tokio::spawn` function as our executor: 
+```
+struct TokioExecutor;
+impl Executor for TokioExecutor {
+    fn spawn(&self, task: impl core::future::Future<Output = ()> + Send + 'static) {
+        tokio::spawn(task);
+    }
+}
+```
+
+# Warning
+The default offloading feature as-is may result in packet loss in the handshake, depending on how packets arrive to the offload endpoint. This packet loss will slow down the handshake, as QUIC has to detect the loss and the peer has to resend the lost packets. We have an upcoming feature that will combat this packet loss and will probably be required to achieve the fastest handshakes possible with s2n-quic: https://github.com/aws/s2n-quic/pull/2668. However, it is still in the PR process.
+
+# Set-up
+
+Currently offloading is disabled by default as it is still in development. It can be enabled by adding this line to your Cargo.toml file:
+
+```toml
+[dependencies]
+s2n-quic = { version = "1", features = ["unstable-offload-tls"]}
+```

examples/tls-offloading/src/bin/client.rs

@@ -0,0 +1,64 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+use s2n_quic::{
+    Client,
+    client::Connect,
+    provider::tls::{
+        default,
+        offload::{Executor, OffloadBuilder},
+    },
+};
+use std::{error::Error, net::SocketAddr};
+
+/// NOTE: this certificate is to be used for demonstration purposes only!
+pub static CERT_PEM: &str = include_str!(concat!(
+    env!("CARGO_MANIFEST_DIR"),
+    "/../../quic/s2n-quic-core/certs/cert.pem"
+));
+
+struct TokioExecutor;
+impl Executor for TokioExecutor {
+    fn spawn(&self, task: impl core::future::Future<Output = ()> + Send + 'static) {
+        tokio::spawn(task);
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>> {
+    let tls = default::Client::builder()
+        .with_certificate(CERT_PEM)?
+        .build()?;
+    let tls_endpoint = OffloadBuilder::new()
+        .with_endpoint(tls)
+        .with_executor(TokioExecutor)
+        .build();
+
+    let client = Client::builder()
+        .with_tls(tls_endpoint)?
+        .with_io("0.0.0.0:0")?
+        .start()?;
+
+    let addr: SocketAddr = "127.0.0.1:4433".parse()?;
+    let connect = Connect::new(addr).with_server_name("localhost");
+    let mut connection = client.connect(connect).await?;
+
+    // ensure the connection doesn't time out with inactivity
+    connection.keep_alive(true)?;
+
+    // open a new stream and split the receiving and sending sides
+    let stream = connection.open_bidirectional_stream().await?;
+    let (mut receive_stream, mut send_stream) = stream.split();
+
+    // spawn a task that copies responses from the server to stdout
+    tokio::spawn(async move {
+        let mut stdout = tokio::io::stdout();
+        let _ = tokio::io::copy(&mut receive_stream, &mut stdout).await;
+    });
+
+    // copy data from stdin and send it to the server
+    let mut stdin = tokio::io::stdin();
+    tokio::io::copy(&mut stdin, &mut send_stream).await?;
+
+    Ok(())
+}

examples/tls-offloading/src/bin/server.rs

@@ -0,0 +1,67 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+use s2n_quic::{
+    Server,
+    provider::tls::{
+        default,
+        offload::{Executor, OffloadBuilder},
+    },
+};
+use std::error::Error;
+
+/// NOTE: this certificate is to be used for demonstration purposes only!
+pub static CERT_PEM: &str = include_str!(concat!(
+    env!("CARGO_MANIFEST_DIR"),
+    "/../../quic/s2n-quic-core/certs/cert.pem"
+));
+/// NOTE: this certificate is to be used for demonstration purposes only!
+pub static KEY_PEM: &str = include_str!(concat!(
+    env!("CARGO_MANIFEST_DIR"),
+    "/../../quic/s2n-quic-core/certs/key.pem"
+));
+
+struct TokioExecutor;
+impl Executor for TokioExecutor {
+    fn spawn(&self, task: impl core::future::Future<Output = ()> + Send + 'static) {
+        tokio::spawn(task);
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>> {
+    let tls = default::Server::builder()
+        .with_certificate(CERT_PEM, KEY_PEM)?
+        .build()?;
+
+    let tls_endpoint = OffloadBuilder::new()
+        .with_endpoint(tls)
+        .with_executor(TokioExecutor)
+        .build();
+
+    let mut server = Server::builder()
+        .with_tls(tls_endpoint)?
+        .with_io("127.0.0.1:4433")?
+        .start()?;
+
+    while let Some(mut connection) = server.accept().await {
+        // spawn a new task for the connection
+        tokio::spawn(async move {
+            eprintln!("Connection accepted from {:?}", connection.remote_addr());
+
+            while let Ok(Some(mut stream)) = connection.accept_bidirectional_stream().await {
+                // spawn a new task for the stream
+                tokio::spawn(async move {
+                    eprintln!("Stream opened from {:?}", stream.connection().remote_addr());
+
+                    // echo any data back to the stream
+                    while let Ok(Some(data)) = stream.receive().await {
+                        stream.send(data).await.expect("stream should be open");
+                    }
+                });
+            }
+        });
+    }
+
+    Ok(())
+}

quic/s2n-quic-core/src/crypto/tls.rs

@@ -20,6 +20,9 @@ pub mod null;
 #[cfg(feature = "alloc")]
 pub mod slow_tls;
 
+#[cfg(feature = "std")]
+pub mod offload;
+
 /// Holds all application parameters which are exchanged within the TLS handshake.
 #[derive(Debug)]
 pub struct ApplicationParameters<'a> {