From 14e57fab0991470b225a9819b00d3a4f2b560546 Mon Sep 17 00:00:00 2001 From: lihan3238 Date: Wed, 13 May 2026 02:31:33 +0800 Subject: [PATCH] docs: document cancel safety for client send_request futures Per discussion in #4054: hyper futures are cancel safe via drop. Document the protocol-specific behavior on cancellation: - HTTP/1: dropping closes the underlying connection (no in-protocol per-request abort) - HTTP/2: dropping resets the stream with RST_STREAM (CANCEL); shared connection stays usable for other in-flight and future requests Also adds a brief crate-level Cancel safety section pointing readers at the per-future docs, per seanmonstar suggestion in the issue. Refs #4054 --- src/client/conn/http1.rs | 9 +++++++++ src/client/conn/http2.rs | 9 +++++++++ src/lib.rs | 8 ++++++++ 3 files changed, 26 insertions(+) diff --git a/src/client/conn/http1.rs b/src/client/conn/http1.rs index 696aa005b3..72d50c7698 100644 --- a/src/client/conn/http1.rs +++ b/src/client/conn/http1.rs @@ -195,6 +195,15 @@ where /// /// This is however not enforced or validated and it is up to the user /// of this method to ensure the `Uri` is correct for their intended purpose. + /// + /// # Cancel safety + /// + /// Dropping the returned future is the supported way to cancel an + /// in-flight HTTP/1 request. Because HTTP/1 has no in-protocol way to + /// abort a single request without affecting the shared connection, + /// hyper closes the underlying connection when a request future is + /// dropped before completion. Any subsequent calls on the same + /// [`SendRequest`] will return a `canceled` error. pub fn send_request( &mut self, req: Request, diff --git a/src/client/conn/http2.rs b/src/client/conn/http2.rs index f1bc4b1ecc..5426ab2c94 100644 --- a/src/client/conn/http2.rs +++ b/src/client/conn/http2.rs @@ -138,6 +138,15 @@ where /// /// Absolute-form `Uri`s are not required. If received, they will be serialized /// as-is. + /// + /// # Cancel safety + /// + /// Dropping the returned future is the supported way to cancel an + /// in-flight HTTP/2 request. The stream is reset with `RST_STREAM` + /// (`CANCEL` error code); the shared connection remains usable for + /// other in-flight and future requests. The peer is notified + /// immediately rather than continuing to send a response body that + /// would be discarded. pub fn send_request( &mut self, req: Request, diff --git a/src/lib.rs b/src/lib.rs index 4683fd6597..7be9926076 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -30,6 +30,14 @@ //! If looking for just a convenient HTTP client, consider the //! [reqwest](https://crates.io/crates/reqwest) crate. //! +//! # Cancel safety +//! +//! Futures returned by hyper are cancel safe: dropping a future before it +//! completes is the supported way to cancel the operation. See the +//! documentation on individual futures — for example `SendRequest::send_request` +//! in `client::conn::http1` and `client::conn::http2` — for the protocol- +//! specific behavior on cancellation. +//! //! # Optional Features //! //! hyper uses a set of [feature flags] to reduce the amount of compiled code.