From d3075c0aa48fe28eff103e9786745e76daa98098 Mon Sep 17 00:00:00 2001 From: Rob Ede Date: Sat, 4 Dec 2021 20:09:48 +0000 Subject: [PATCH] deprecate `start_with_{addr, protocols}` --- actix-web-actors/CHANGES.md | 3 +- actix-web-actors/src/ws.rs | 86 ++++++++++++++++++++----------------- 2 files changed, 48 insertions(+), 41 deletions(-) diff --git a/actix-web-actors/CHANGES.md b/actix-web-actors/CHANGES.md index 146b54fd9..898098ed8 100644 --- a/actix-web-actors/CHANGES.md +++ b/actix-web-actors/CHANGES.md @@ -1,7 +1,8 @@ # Changes ## Unreleased - 2021-xx-xx -* Add `ws:WsResponseBuilder` for building web socket session response. [#1920] +* Add `ws:WsResponseBuilder` for building WebSocket session response. [#1920] +* Deprecate `ws::{start_with_addr, start_with_protocols}`. [#1920] * Minimum supported Rust version (MSRV) is now 1.52. [#1920]: https://github.com/actix/actix-web/pull/1920 diff --git a/actix-web-actors/src/ws.rs b/actix-web-actors/src/ws.rs index 51280fe66..d3a40e537 100644 --- a/actix-web-actors/src/ws.rs +++ b/actix-web-actors/src/ws.rs @@ -70,6 +70,9 @@ where A: Actor> + StreamHandler>, T: Stream> + 'static, { + /// Construct a new `WsResponseBuilder` with actor, request, and payload stream. + /// + /// For usage example, see docs on [`WsResponseBuilder`] struct. pub fn new(actor: A, req: &'a HttpRequest, stream: T) -> Self { WsResponseBuilder { actor, @@ -89,16 +92,14 @@ where /// Set the max frame size for each message. /// - /// **Note**: This will override any given [`Codec`]'s - /// max frame size. + /// **Note**: This will override any given [`Codec`]'s max frame size. pub fn frame_size(mut self, frame_size: usize) -> Self { self.frame_size = Some(frame_size); self } - /// Set the [`Codec`] for the session. If [`Self::frame_size`] - /// is also set, the given [`Codec`]'s max frame size will be - /// overriden. + /// Set the [`Codec`] for the session. If [`Self::frame_size`] is also set, the given + /// [`Codec`]'s max frame size will be overridden. pub fn codec(mut self, codec: Codec) -> Self { self.codec = Some(codec); self @@ -128,9 +129,9 @@ where /// Create a new Websocket context from a request, an actor, and a codec. /// - /// Returns a pair, where the first item is an addr for the created actor, - /// and the second item is a stream intended to be set as part of the - /// response via `HttpResponseBuilder::streaming()`. + /// Returns a pair, where the first item is an addr for the created actor, and the second item + /// is a stream intended to be set as part of the response + /// via [`HttpResponseBuilder::streaming()`]. fn create_with_codec_addr( actor: A, stream: S, @@ -154,14 +155,14 @@ where /// Perform WebSocket handshake and start actor. /// - /// `req` is an [`HttpRequest`] that should be requesting a websocket - /// protocol change. `stream` should be a [`Bytes`] stream (such as - /// `actix_web::web::Payload`) that contains a stream of the body request. + /// `req` is an [`HttpRequest`] that should be requesting a websocket protocol change. + /// `stream` should be a [`Bytes`] stream (such as `actix_web::web::Payload`) that contains a + /// stream of the body request. /// /// If there is a problem with the handshake, an error is returned. /// - /// If successful, consume the [`WsResponseBuilder`] and return a - /// [`HttpResponse`] wrapped in a [`Result`]. + /// If successful, consume the [`WsResponseBuilder`] and return a [`HttpResponse`] wrapped in + /// a [`Result`]. pub fn start(mut self) -> Result { let mut res = self.handshake_resp()?; self.set_frame_size(); @@ -180,15 +181,14 @@ where /// Perform WebSocket handshake and start actor. /// - /// `req` is an [`HttpRequest`] that should be requesting a websocket - /// protocol change. `stream` should be a [`Bytes`] stream (such as - /// `actix_web::web::Payload`) that contains a stream of the body request. + /// `req` is an [`HttpRequest`] that should be requesting a websocket protocol change. + /// `stream` should be a [`Bytes`] stream (such as `actix_web::web::Payload`) that contains a + /// stream of the body request. /// /// If there is a problem with the handshake, an error is returned. /// - /// If successful, returns a pair where the first item is an address for the - /// created actor and the second item is the [`HttpResponse`] that should be - /// returned from the websocket request. + /// If successful, returns a pair where the first item is an address for the created actor and + /// the second item is the [`HttpResponse`] that should be returned from the websocket request. pub fn start_with_addr(mut self) -> Result<(Addr, HttpResponse), Error> { let mut res = self.handshake_resp()?; self.set_frame_size(); @@ -209,6 +209,8 @@ where } /// Perform WebSocket handshake and start actor. +/// +/// To customize options, see [`WsResponseBuilder`]. pub fn start(actor: A, req: &HttpRequest, stream: T) -> Result where A: Actor> + StreamHandler>, @@ -220,15 +222,15 @@ where /// Perform WebSocket handshake and start actor. /// -/// `req` is an HTTP Request that should be requesting a websocket protocol -/// change. `stream` should be a `Bytes` stream (such as -/// `actix_web::web::Payload`) that contains a stream of the body request. +/// `req` is an HTTP Request that should be requesting a websocket protocol change. `stream` should +/// be a `Bytes` stream (such as `actix_web::web::Payload`) that contains a stream of the +/// body request. /// /// If there is a problem with the handshake, an error is returned. /// -/// If successful, returns a pair where the first item is an address for the -/// created actor and the second item is the response that should be returned -/// from the WebSocket request. +/// If successful, returns a pair where the first item is an address for the created actor and the +/// second item is the response that should be returned from the WebSocket request. +#[deprecated(since = "4.0.0", note = "Prefer `WsResponseBuilder::start_with_addr`.")] pub fn start_with_addr( actor: A, req: &HttpRequest, @@ -246,6 +248,10 @@ where /// Do WebSocket handshake and start ws actor. /// /// `protocols` is a sequence of known protocols. +#[deprecated( + since = "4.0.0", + note = "Prefer `WsResponseBuilder` for setting protocols." +)] pub fn start_with_protocols( actor: A, protocols: &[&str], @@ -262,20 +268,19 @@ where /// Prepare WebSocket handshake response. /// -/// This function returns handshake `HttpResponse`, ready to send to peer. -/// It does not perform any IO. +/// This function returns handshake `HttpResponse`, ready to send to peer. It does not perform +/// any IO. pub fn handshake(req: &HttpRequest) -> Result { handshake_with_protocols(req, &[]) } /// Prepare WebSocket handshake response. /// -/// This function returns handshake `HttpResponse`, ready to send to peer. -/// It does not perform any IO. +/// This function returns handshake `HttpResponse`, ready to send to peer. It does not perform +/// any IO. /// -/// `protocols` is a sequence of known protocols. On successful handshake, -/// the returned response headers contain the first protocol in this list -/// which the server also knows. +/// `protocols` is a sequence of known protocols. On successful handshake, the returned response +/// headers contain the first protocol in this list which the server also knows. pub fn handshake_with_protocols( req: &HttpRequest, protocols: &[&str], @@ -422,8 +427,8 @@ impl WebsocketContext where A: Actor, { + /// Create a new Websocket context from a request and an actor. #[inline] - /// Create a new Websocket context from a request and an actor pub fn create(actor: A, stream: S) -> impl Stream> where A: StreamHandler>, @@ -433,12 +438,11 @@ where stream } - #[inline] /// Create a new Websocket context from a request and an actor. /// - /// Returns a pair, where the first item is an addr for the created actor, - /// and the second item is a stream intended to be set as part of the - /// response via `HttpResponseBuilder::streaming()`. + /// Returns a pair, where the first item is an addr for the created actor, and the second item + /// is a stream intended to be set as part of the response + /// via [`HttpResponseBuilder::streaming()`]. pub fn create_with_addr( actor: A, stream: S, @@ -459,7 +463,6 @@ where (addr, WebsocketContextFut::new(ctx, actor, mb, Codec::new())) } - #[inline] /// Create a new Websocket context from a request, an actor, and a codec pub fn with_codec( actor: A, @@ -724,9 +727,12 @@ where #[cfg(test)] mod tests { + use actix_web::{ + http::{header, Method}, + test::TestRequest, + }; + use super::*; - use actix_web::http::{header, Method}; - use actix_web::test::TestRequest; #[test] fn test_handshake() {