Remove .close(), and document clean WebSocket closing (#2974)

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
 

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<u8>),
     /// 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<CloseFrame<'static>>),
 }