feat(http2): implement 103 Early Hints support

Add complete HTTP/2 103 Early Hints implementation with client and server support:

- Add InformationalSender extension for server-side hint transmission via mpsc channel
- Create InformationalCallback system for client-side informational response handling
- Extend HTTP/2 client builder with informational_responses() configuration method
- Implement informational response polling in h2 client task with callback invocation
- Add server-side informational response forwarding using h2's send_informational API
- Include extensive integration tests covering multiple scenarios and edge cases
- Add `enable_informational` config field (defaults to false) and conditional channel creation per request
- Add complete working example with TLS, resource preloading, and performance monitoring
- Update Cargo.toml with local h2 dependency and example build configuration

The implementation enables servers to send resource preload hints before final responses,
allowing browsers to start downloading critical resources early and improve page load
performance. Clients can register callbacks to process 103 Early Hints and other
informational responses.

Closes #3980, #2426

Author: Apu Islam

Cargo.toml

@@ -67,6 +67,10 @@ tokio = { version = "1", features = [
 ] }
 tokio-test = "0.4"
 tokio-util = "0.7.10"
+# Additional dependencies for HTTP/2 Early Hints example
+rcgen = "0.12"
+tokio-rustls = "0.25"
+rustls-pemfile = "2.0"
 
 [features]
 # Nothing by default
@@ -86,7 +90,7 @@ http2 = ["dep:atomic-waker", "dep:futures-channel", "dep:futures-core", "dep:h2"
 
 # Client/Server
 client = ["dep:want", "dep:pin-project-lite", "dep:smallvec"]
-server = ["dep:httpdate", "dep:pin-project-lite", "dep:smallvec"]
+server = ["dep:httpdate", "dep:pin-project-lite", "dep:smallvec", "dep:futures-util"]
 
 # C-API support (currently unstable (no semver))
 ffi = ["dep:http-body-util", "dep:futures-util"]
@@ -304,6 +308,11 @@ name = "web_api"
 path = "examples/web_api.rs"
 required-features = ["full"]
 
+[[example]]
+name = "http2_early_hints"
+path = "examples/http2_early_hints.rs"
+required-features = ["full"]
+
 
 [[bench]]
 name = "body"

examples/README.md

@@ -38,6 +38,8 @@ futures-util = { version = "0.3", default-features = false }
 
 * [`echo`](echo.rs) - An echo server that copies POST request's content to the response content.
 
+* [`http2_early_hints`](http2_early_hints.rs) - An HTTP/2 server that sends 103 Early Hints.
+
 ## Going Further
 
 * [`gateway`](gateway.rs) - A server gateway (reverse proxy) that proxies to the `hello` service above.

examples/http2_early_hints.rs

@@ -0,0 +1,259 @@
+//! HTTP/2 server demonstrating 103 Early Hints
+//!
+//! This example shows the recommended approach: 103 Early Hints.
+//!
+//! Run with:
+//! ```
+//! cargo run --example http2_early_hints --features full
+//! ```
+
+use std::convert::Infallible;
+use std::fs;
+use std::net::SocketAddr;
+use std::time::Instant;
+
+use bytes::Bytes;
+use http::{Request, Response, StatusCode};
+use http_body_util::Full;
+use hyper::body::Incoming as IncomingBody;
+use hyper::ext::early_hints_pusher;
+use hyper::server::conn::http2;
+use hyper::service::service_fn;
+use tokio::net::TcpListener;
+use tokio_rustls::rustls::{
+    pki_types::{CertificateDer, PrivateKeyDer},
+    ServerConfig,
+};
+use tokio_rustls::TlsAcceptor;
+
+#[path = "../benches/support/mod.rs"]
+mod support;
+use support::{TokioExecutor, TokioIo};
+
+/// Load certificates from provided files
+fn load_certificates() -> Result<
+    (Vec<CertificateDer<'static>>, PrivateKeyDer<'static>),
+    Box<dyn std::error::Error + Send + Sync>,
+> {
+    // Read certificate file
+    let cert_pem = fs::read_to_string("/tmp/cert.txt")?;
+
+    // Parse certificate chain
+    let mut certs = Vec::new();
+    for cert in rustls_pemfile::certs(&mut cert_pem.as_bytes()) {
+        certs.push(cert?);
+    }
+
+    // Read private key file
+    let key_pem = fs::read_to_string("/tmp/key.txt")?;
+
+    // Parse private key
+    let mut key_reader = key_pem.as_bytes();
+    let key =
+        rustls_pemfile::private_key(&mut key_reader)?.ok_or("No private key found in key file")?;
+
+    Ok((certs, key))
+}
+
+/// Generate a self-signed certificate for testing (fallback)
+fn generate_self_signed_cert() -> (Vec<CertificateDer<'static>>, PrivateKeyDer<'static>) {
+    use rcgen::{Certificate as RcgenCert, CertificateParams, DistinguishedName};
+
+    let mut params = CertificateParams::new(vec!["localhost".to_string()]);
+    params.distinguished_name = DistinguishedName::new();
+
+    let cert = RcgenCert::from_params(params).unwrap();
+    let cert_der = cert.serialize_der().unwrap();
+    let private_key_der = cert.serialize_private_key_der();
+
+    (
+        vec![CertificateDer::from(cert_der)],
+        PrivateKeyDer::try_from(private_key_der).unwrap(),
+    )
+}
+
+/// HTTP service demonstrating 103 Early Hints
+async fn handle_request(
+    mut req: Request<IncomingBody>,
+) -> Result<Response<Full<Bytes>>, Infallible> {
+    let path = req.uri().path();
+    println!("Received request: {} {}", req.method(), req.uri());
+
+    // Handle static resources that we hinted about
+    match path {
+        "/css/critical.css" | "/css/layout.css" => {
+            return Ok(Response::builder()
+                .status(StatusCode::OK)
+                .header("content-type", "text/css")
+                .body(Full::new(Bytes::from("body { font-family: sans-serif; }")))
+                .unwrap());
+        }
+
+        "/js/app.js" | "/js/vendor.js" => {
+            return Ok(Response::builder()
+                .status(StatusCode::OK)
+                .header("content-type", "application/javascript")
+                .body(Full::new(Bytes::from("console.log('loaded');")))
+                .unwrap());
+        }
+
+        "/fonts/main.woff2" | "/fonts/icons.woff2" => {
+            return Ok(Response::builder()
+                .status(StatusCode::OK)
+                .header("content-type", "font/woff2")
+                .body(Full::new(Bytes::from(&b"WOFF2"[..])))
+                .unwrap());
+        }
+
+        "/images/hero.webp" => {
+            return Ok(Response::builder()
+                .status(StatusCode::OK)
+                .header("content-type", "image/webp")
+                .body(Full::new(Bytes::from(&b"RIFF"[..])))
+                .unwrap());
+        }
+
+        // Root path - serve HTML page with all the hinted resources
+        "/" => {
+            // Send 103 Early Hints using the early_hints_pusher API
+            if let Ok(mut pusher) = early_hints_pusher(&mut req) {
+                println!("Sending 103 Early Hints (all critical resources)");
+
+                let start_time = Instant::now();
+
+                let hints = Response::builder()
+                    .status(StatusCode::EARLY_HINTS)
+                    // Critical CSS (highest priority - render blocking)
+                    .header("link", "</css/critical.css>; rel=preload; as=style")
+                    .header("link", "</css/layout.css>; rel=preload; as=style")
+                    // Critical JavaScript (high priority - interaction)
+                    .header("link", "</js/app.js>; rel=preload; as=script")
+                    .header("link", "</js/vendor.js>; rel=preload; as=script")
+                    // Fonts (medium priority - text rendering)
+                    .header(
+                        "link",
+                        "</fonts/main.woff2>; rel=preload; as=font; crossorigin",
+                    )
+                    .header(
+                        "link",
+                        "</fonts/icons.woff2>; rel=preload; as=font; crossorigin",
+                    )
+                    // Hero image (medium priority - above fold)
+                    .header("link", "</images/hero.webp>; rel=preload; as=image")
+                    // Metadata for tracking
+                    .header("x-resource-count", "7")
+                    .header("x-priority-order", "css,js,fonts,images")
+                    .body(())
+                    .unwrap();
+
+                if let Err(e) = pusher.send_hints(hints).await {
+                    eprintln!("Failed to send hints: {}", e);
+                } else {
+                    let send_duration = start_time.elapsed();
+                    println!("103 Early Hints sent in: {:?}", send_duration);
+                    println!("   7 resources hinted in single response");
+                    println!("   Browser processes once, starts all preloads immediately");
+                }
+
+                // Simulate realistic server processing time
+                println!("Processing request (simulating database queries, template rendering...)");
+                tokio::time::sleep(tokio::time::Duration::from_millis(200)).await;
+            }
+
+            let html_content = r#"<!DOCTYPE html>
+<html>
+<head>
+    <title>103 Early Hints Demo</title>
+    <link rel="stylesheet" href="/css/critical.css">
+    <link rel="stylesheet" href="/css/layout.css">
+</head>
+<body>
+    <h1>HTTP/2 103 Early Hints</h1>
+    <p>The resources above were hinted via 103 before this response arrived.</p>
+    <script src="/js/app.js"></script>
+</body>
+</html>"#;
+
+            return Ok(Response::builder()
+                .status(StatusCode::OK)
+                .header("content-type", "text/html")
+                .body(Full::new(Bytes::from(html_content)))
+                .unwrap());
+        }
+
+        // Default 404 handler
+        _ => {
+            return Ok(Response::builder()
+                .status(StatusCode::NOT_FOUND)
+                .body(Full::new(Bytes::from("Not Found")))
+                .unwrap());
+        }
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+    // Initialize logging
+    pretty_env_logger::init();
+
+    let addr: SocketAddr = ([0, 0, 0, 0], 3000).into();
+
+    // Load provided certificates or fallback to self-signed
+    let (certs, key) = match load_certificates() {
+        Ok((certs, key)) => {
+            println!("Loaded certificates from /tmp/cert.txt and /tmp/key.txt");
+            (certs, key)
+        }
+        Err(e) => {
+            println!(
+                "Failed to load provided certificates ({}), generating self-signed certificate...",
+                e
+            );
+            generate_self_signed_cert()
+        }
+    };
+
+    // Configure TLS
+    let mut config = ServerConfig::builder()
+        .with_no_client_auth()
+        .with_single_cert(certs, key)?;
+
+    // Enable HTTP/2
+    config.alpn_protocols = vec![b"h2".to_vec(), b"http/1.1".to_vec()];
+
+    let tls_acceptor = TlsAcceptor::from(std::sync::Arc::new(config));
+
+    // Create TCP listener
+    let listener = TcpListener::bind(addr).await?;
+    println!("103 Early Hints Server listening on https://{}", addr);
+    println!("Test: curl -k --http2 -v https://localhost:3000/");
+    println!("Expected: 1 103 response + 1 final 200 response");
+    println!("Benefits: Minimal browser overhead, maximum performance");
+
+    loop {
+        let (tcp_stream, _) = listener.accept().await?;
+        let tls_acceptor = tls_acceptor.clone();
+
+        tokio::spawn(async move {
+            // Perform TLS handshake
+            let tls_stream = match tls_acceptor.accept(tcp_stream).await {
+                Ok(stream) => stream,
+                Err(e) => {
+                    eprintln!("TLS handshake failed: {}", e);
+                    return;
+                }
+            };
+
+            // Serve HTTP/2 connection with Early Hints support enabled
+            let service = service_fn(handle_request);
+
+            if let Err(e) = http2::Builder::new(TokioExecutor)
+                .enable_informational() // Enable 103 Early Hints support
+                .serve_connection(TokioIo::new(tls_stream), service)
+                .await
+            {
+                eprintln!("HTTP/2 connection error: {}", e);
+            }
+        });
+    }
+}

src/client/conn/http2.rs

@@ -14,6 +14,7 @@ use futures_core::ready;
 use http::{Request, Response};
 
 use super::super::dispatch::{self, TrySendError};
+use super::informational::InformationalConfig;
 use crate::body::{Body, Incoming as IncomingBody};
 use crate::common::time::Time;
 use crate::proto;
@@ -68,6 +69,7 @@ pub struct Builder<Ex> {
     pub(super) exec: Ex,
     pub(super) timer: Time,
     h2_builder: proto::h2::client::Config,
+    informational_config: InformationalConfig,
 }
 
 /// Returns a handshake future over some IO.
@@ -299,6 +301,7 @@ where
             exec,
             timer: Time::Empty,
             h2_builder: proto::h2::client::Config::default(),
+            informational_config: InformationalConfig::new(),
         }
     }
 
@@ -542,6 +545,50 @@ where
         self
     }
 
+    /// Configures handling of informational responses (1xx status codes).
+    ///
+    /// By default, informational responses are ignored. This method allows you to
+    /// provide a callback that will be invoked whenever an informational response
+    /// is received, such as 103 Early Hints.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use hyper::client::conn::http2::Builder;
+    /// use hyper::client::conn::informational::InformationalConfig;
+    /// use http::StatusCode;
+    ///
+    /// #[derive(Clone)]
+    /// struct TokioExecutor;
+    ///
+    /// impl<F> hyper::rt::Executor<F> for TokioExecutor
+    /// where
+    ///     F: std::future::Future + Send + 'static,
+    ///     F::Output: Send + 'static,
+    /// {
+    ///     fn execute(&self, fut: F) {
+    ///         tokio::task::spawn(fut);
+    ///     }
+    /// }
+    ///
+    /// let mut builder = Builder::new(TokioExecutor);
+    /// builder.informational_responses(
+    ///     InformationalConfig::new().with_callback(|response| {
+    ///         if response.status() == StatusCode::EARLY_HINTS {
+    ///             println!("Received 103 Early Hints");
+    ///             // Process Link headers for resource preloading
+    ///             for link in response.headers().get_all("link") {
+    ///                 println!("Preload: {:?}", link);
+    ///             }
+    ///         }
+    ///     })
+    /// );
+    /// ```
+    pub fn informational_responses(&mut self, config: InformationalConfig) -> &mut Self {
+        self.informational_config = config;
+        self
+    }
+
     /// Constructs a connection with the configured options and IO.
     /// See [`client::conn`](crate::client::conn) for more.
     ///
@@ -564,8 +611,15 @@ where
             trace!("client handshake HTTP/2");
 
             let (tx, rx) = dispatch::channel();
-            let h2 = proto::h2::client::handshake(io, rx, &opts.h2_builder, opts.exec, opts.timer)
-                .await?;
+            let h2 = proto::h2::client::handshake(
+                io,
+                rx,
+                &opts.h2_builder,
+                opts.exec,
+                opts.timer,
+                Some(opts.informational_config.clone()),
+            )
+            .await?;
             Ok((
                 SendRequest {
                     dispatch: tx.unbound(),