From 064855203bffa57650c5e2cfcca3e0985b20a327 Mon Sep 17 00:00:00 2001 From: SabrinaJewson Date: Thu, 10 Oct 2024 10:33:17 +0100 Subject: [PATCH 1/5] Remove `.close()`, and document clean WebSocket closing --- axum/src/extract/ws.rs | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/axum/src/extract/ws.rs b/axum/src/extract/ws.rs index ba686b6e60..3160ac51e2 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 any attempts to send a message will error. + /// After receiving a close frame, + /// the server 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, + /// so you may either do nothing + /// or explicitly drop the connection. Close(Option>), } From 677c34658bea943dd13696c70374e10ccd46ec7a Mon Sep 17 00:00:00 2001 From: SabrinaJewson Date: Thu, 10 Oct 2024 10:39:05 +0100 Subject: [PATCH 2/5] Add CHANGELOG entry --- axum/CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) 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 From 2958f194456a75a0f84a08a70c687802e5bffe60 Mon Sep 17 00:00:00 2001 From: Sabrina Jewson Date: Fri, 11 Oct 2024 09:13:24 +0100 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Jonas Platte --- axum/src/extract/ws.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/axum/src/extract/ws.rs b/axum/src/extract/ws.rs index 3160ac51e2..91b6229787 100644 --- a/axum/src/extract/ws.rs +++ b/axum/src/extract/ws.rs @@ -621,12 +621,12 @@ pub enum Message { /// /// After sending a close frame, /// you may still read messages, - /// but any attempts to send a message will error. + /// but any attempts to send another message will error. /// After receiving a close frame, - /// the server will automatically respond with a close frame if necessary + /// 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, - /// so you may either do nothing + /// you may either do nothing /// or explicitly drop the connection. Close(Option>), } From 9419513922a8bfae0b14efa2c51a49c7c2ce8982 Mon Sep 17 00:00:00 2001 From: SabrinaJewson Date: Fri, 11 Oct 2024 09:14:30 +0100 Subject: [PATCH 4/5] Grammar changes --- axum/src/extract/ws.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/axum/src/extract/ws.rs b/axum/src/extract/ws.rs index 91b6229787..6983e0080e 100644 --- a/axum/src/extract/ws.rs +++ b/axum/src/extract/ws.rs @@ -621,9 +621,9 @@ pub enum Message { /// /// After sending a close frame, /// you may still read messages, - /// but any attempts to send another message will error. + /// but attempts to send another message will error. /// After receiving a close frame, - /// axum will automatically respond with a close frame if necessary + /// 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 From 935e1491a4009635128677c60c3fae3b74ece346 Mon Sep 17 00:00:00 2001 From: Jonas Platte Date: Fri, 11 Oct 2024 10:56:15 +0200 Subject: [PATCH 5/5] Lowercase axum --- axum/src/extract/ws.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/axum/src/extract/ws.rs b/axum/src/extract/ws.rs index 6983e0080e..6bf3b44628 100644 --- a/axum/src/extract/ws.rs +++ b/axum/src/extract/ws.rs @@ -623,7 +623,7 @@ pub enum Message { /// 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 + /// 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