docs: document cancel safety for client send_request futures

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<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<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.