From 96ab199350b1692b3630086b8cb6e797853c1072 Mon Sep 17 00:00:00 2001 From: oddgrd <29732646+oddgrd@users.noreply.github.com> Date: Sun, 24 Sep 2023 16:21:21 +0200 Subject: [PATCH 1/3] docs(server): expand server connection docs --- src/server/conn/http1.rs | 7 +++++-- src/server/conn/http2.rs | 7 +++++-- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/src/server/conn/http1.rs b/src/server/conn/http1.rs index 09770cd3cb..50629cf4fe 100644 --- a/src/server/conn/http1.rs +++ b/src/server/conn/http1.rs @@ -22,9 +22,12 @@ type Http1Dispatcher = proto::h1::Dispatcher< >; pin_project_lite::pin_project! { - /// A future binding an http1 connection with a Service. + /// A [`Future`](core::future::Future) representing an HTTP/1 connection, bound to a + /// [`Service`](crate::service::Service), returned from + /// [`Builder::serve_connection`](struct.Builder.html#method.serve_connection). /// - /// Polling this future will drive HTTP forward. + /// To drive HTTP on this connection this future **must be polled**, typically with + /// `.await`. If it isn't polled, no progress will be made on this connection. #[must_use = "futures do nothing unless polled"] pub struct Connection where diff --git a/src/server/conn/http2.rs b/src/server/conn/http2.rs index f6f09f45f1..1cc351134b 100644 --- a/src/server/conn/http2.rs +++ b/src/server/conn/http2.rs @@ -16,9 +16,12 @@ use crate::service::HttpService; use crate::{common::time::Time, rt::Timer}; pin_project! { - /// A future binding an HTTP/2 connection with a Service. + /// A [`Future`](core::future::Future) representing an HTTP/2 connection, bound to a + /// [`Service`](crate::service::Service), returned from + /// [`Builder::serve_connection`](struct.Builder.html#method.serve_connection). /// - /// Polling this future will drive HTTP forward. + /// To drive HTTP on this connection this future **must be polled**, typically with + /// `.await`. If it isn't polled, no progress will be made on this connection. #[must_use = "futures do nothing unless polled"] pub struct Connection where From b94b559c0c7bf445111a85e083b5d8daaccf8b1a Mon Sep 17 00:00:00 2001 From: oddgrd <29732646+oddgrd@users.noreply.github.com> Date: Sun, 24 Sep 2023 16:23:07 +0200 Subject: [PATCH 2/3] docs(server): suggest hyper-util autoconnection util --- src/server/conn/mod.rs | 10 ++++++++-- src/service/service.rs | 2 +- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/src/server/conn/mod.rs b/src/server/conn/mod.rs index b7dea1b8c6..85d857e3cc 100644 --- a/src/server/conn/mod.rs +++ b/src/server/conn/mod.rs @@ -5,8 +5,14 @@ //! are not handled at this level. This module provides the building blocks to //! customize those things externally. //! -//! This module is split by HTTP version. Both work similarly, but do have -//! specific options on each builder. +//! This module is split by HTTP version, providing a connection builder for +//! each. They work similarly, but they each have specific options. +//! +//! If your server needs to support both versions, an auto connection builder is +//! provided in the [`hyper-util`](https://github.com/hyperium/hyper-util/tree/master) +//! crate. This builder wraps the HTTP/1 and HTTP/2 connection builders from this +//! module, allowing you to set configuration for both. The builder will then check +//! the version of the incoming connection and serve it accordingly. #[cfg(feature = "http1")] pub mod http1; diff --git a/src/service/service.rs b/src/service/service.rs index 005406f982..95024bee44 100644 --- a/src/service/service.rs +++ b/src/service/service.rs @@ -35,6 +35,6 @@ pub trait Service { /// - It's clearer that Services can likely be cloned /// - To share state across clones you generally need Arc> /// that means you're not really using the &mut self and could do with a &self - /// To see the discussion on this see: https://github.com/hyperium/hyper/issues/3040 + /// To see the discussion on this see: fn call(&self, req: Request) -> Self::Future; } From 733c5070d9599b93ac44319b379549d66379c72a Mon Sep 17 00:00:00 2001 From: oddgrd <29732646+oddgrd@users.noreply.github.com> Date: Sun, 24 Sep 2023 16:57:50 +0200 Subject: [PATCH 3/3] docs(server): use hyphen in auto-connection --- src/server/conn/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/server/conn/mod.rs b/src/server/conn/mod.rs index 85d857e3cc..54b309e88e 100644 --- a/src/server/conn/mod.rs +++ b/src/server/conn/mod.rs @@ -8,7 +8,7 @@ //! This module is split by HTTP version, providing a connection builder for //! each. They work similarly, but they each have specific options. //! -//! If your server needs to support both versions, an auto connection builder is +//! If your server needs to support both versions, an auto-connection builder is //! provided in the [`hyper-util`](https://github.com/hyperium/hyper-util/tree/master) //! crate. This builder wraps the HTTP/1 and HTTP/2 connection builders from this //! module, allowing you to set configuration for both. The builder will then check