update h2c docs

actix-web/CHANGES.md

@@ -4,6 +4,7 @@
 
 ### Added
 
+- Add `HttpServer::{bind,listen}_auto_h2c()` method.
 - Add `Resource::{get, post, etc...}` methods for more concisely adding routes that don't need additional guards.
 
 ### Changed

actix-web/examples/on-connect.rs

@@ -4,8 +4,6 @@
 //! For an example of extracting a client TLS certificate, see:
 //! <https://github.com/actix/examples/tree/master/https-tls/rustls-client-cert>
 
-#![allow(clippy::uninlined_format_args)]
-
 use std::{any::Any, io, net::SocketAddr};
 
 use actix_web::{
@@ -24,8 +22,7 @@ struct ConnectionInfo {
 async fn route_whoami(req: HttpRequest) -> impl Responder {
     match req.conn_data::<ConnectionInfo>() {
         Some(info) => HttpResponse::Ok().body(format!(
-            "Here is some info about your connection:\n\n{:#?}",
-            info
+            "Here is some info about your connection:\n\n{info:#?}",
         )),
         None => {
             HttpResponse::InternalServerError().body("Missing expected request extension data")
@@ -54,8 +51,8 @@ async fn main() -> io::Result<()> {
 
     HttpServer::new(|| App::new().default_service(web::to(route_whoami)))
         .on_connect(get_conn_info)
-        .bind(bind)?
-        .workers(1)
+        .bind_auto_h2c(bind)?
+        .workers(2)
         .run()
         .await
 }

actix-web/src/server.rs

@@ -41,10 +41,19 @@ struct Config {
 ///
 /// Create new HTTP server with application factory.
 ///
-/// # HTTP/2
-/// Currently, HTTP/2 is only supported when using TLS (HTTPS). See `bind_rustls` or `bind_openssl`.
+/// # Automatic HTTP Version Selection
+///
+/// There are two ways to select the HTTP version of an incoming connection:
+///
+/// - One is to rely on the ALPN information that is provided when using a TLS (HTTPS); both
+///   versions are supported automatically when using either of the `.bind_rustls()` or
+///   `.bind_openssl()` methods.
+/// - The other is to read the first few bytes of the TCP stream. This is the only viable approach
+///   for supporting H2C, which allows the HTTP/2 protocol to work over plaintext connections. Use
+///   the `.bind_auto_h2c()` method to enable this behavior.
 ///
 /// # Examples
+///
 /// ```no_run
 /// use actix_web::{web, App, HttpResponse, HttpServer};
 ///
@@ -347,6 +356,8 @@ where
         Ok(self)
     }
 
+    /// Resolves socket address(es) and binds server to created listener(s) for plaintext HTTP/1.x
+    /// or HTTP/2 connections.
     pub fn bind_auto_h2c<A: net::ToSocketAddrs>(mut self, addrs: A) -> io::Result<Self> {
         let sockets = bind_addrs(addrs, self.backlog)?;
 
@@ -444,7 +455,8 @@ where
         Ok(self)
     }
 
-    fn listen_auto_h2c(mut self, lst: net::TcpListener) -> io::Result<Self> {
+    /// Binds to existing listener for accepting incoming plaintext HTTP/1.x or HTTP/2 connections.
+    pub fn listen_auto_h2c(mut self, lst: net::TcpListener) -> io::Result<Self> {
         let cfg = self.config.clone();
         let factory = self.factory.clone();
         let addr = lst.local_addr().unwrap();