From c6e6b4ea32f4e052d0f169cc666a6c885e006f13 Mon Sep 17 00:00:00 2001 From: Sabrina Jewson Date: Fri, 11 Oct 2024 10:31:43 +0100 Subject: [PATCH] Remove `.close()`, and document clean WebSocket closing (#2974) --- axum/CHANGELOG.md | 3 +++ axum/src/extract/ws.rs | 23 ++++++++++++++++++----- 2 files changed, 21 insertions(+), 5 deletions(-) diff --git a/axum/CHANGELOG.md b/axum/CHANGELOG.md index 046f7d0967..b3529d19c9 100644 --- a/axum/CHANGELOG.md +++ b/axum/CHANGELOG.md @@ -13,10 +13,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 and `MethodRouter::connect[_service]` ([#2961]) - **fixed:** Avoid setting `content-length` before middleware ([#2897]). This allows middleware to add bodies to requests without needing to manually set `content-length` +- **breaking:** Remove `WebSocket::close` ([#2974]). + Users should explicitly send close messages themselves. [#2897]: https://github.com/tokio-rs/axum/pull/2897 [#2984]: https://github.com/tokio-rs/axum/pull/2984 [#2961]: https://github.com/tokio-rs/axum/pull/2961 +[#2974]: https://github.com/tokio-rs/axum/pull/2974 # 0.8.0 diff --git a/axum/src/extract/ws.rs b/axum/src/extract/ws.rs index ba686b6e60..6bf3b44628 100644 --- a/axum/src/extract/ws.rs +++ b/axum/src/extract/ws.rs @@ -507,11 +507,6 @@ impl WebSocket { .map_err(Error::new) } - /// Gracefully close this WebSocket. - pub async fn close(mut self) -> Result<(), Error> { - self.inner.close(None).await.map_err(Error::new) - } - /// Return the selected WebSocket subprotocol, if one has been chosen. pub fn protocol(&self) -> Option<&HeaderValue> { self.protocol.as_ref() @@ -615,6 +610,24 @@ pub enum Message { /// [unidirectional heartbeat](https://tools.ietf.org/html/rfc6455#section-5.5.3). Pong(Vec), /// A close message with the optional close frame. + /// + /// You may "uncleanly" close a WebSocket connection at any time + /// by simply dropping the [`WebSocket`]. + /// However, you may also use the graceful closing protocol, in which + /// 1. peer A sends a close frame, and does not send any further messages; + /// 2. peer B responds with a close frame, and does not send any further messages; + /// 3. peer A processes the remaining messages sent by peer B, before finally + /// 4. both peers close the connection. + /// + /// After sending a close frame, + /// you may still read messages, + /// but attempts to send another message will error. + /// After receiving a close frame, + /// axum will automatically respond with a close frame if necessary + /// (you do not have to deal with this yourself). + /// Since no further messages will be received, + /// you may either do nothing + /// or explicitly drop the connection. Close(Option>), }