diff --git a/actix-web-actors/CHANGES.md b/actix-web-actors/CHANGES.md index 37ca2c955..8791853b2 100644 --- a/actix-web-actors/CHANGES.md +++ b/actix-web-actors/CHANGES.md @@ -1,7 +1,9 @@ # Changes ## Unreleased - 2021-xx-xx -* Add `ws:WsResponseBuilder` for building web socket session response. +* Add `ws:WsResponseBuilder` for building web socket session response. [#1920] + +[#1920]: https://github.com/actix/actix-web/pull/1920 ## 4.0.0-beta.1 - 2021-01-07 diff --git a/actix-web-actors/src/ws.rs b/actix-web-actors/src/ws.rs index acae88fa3..9ebd036b4 100644 --- a/actix-web-actors/src/ws.rs +++ b/actix-web-actors/src/ws.rs @@ -30,6 +30,24 @@ use futures_core::Stream; use tokio::sync::oneshot::Sender; /// Builder for Websocket Session response. +/// +/// # Examples +/// +/// Create a Websocket session response with default configs. +/// ```rust +/// WsResponseBuilder::new(WsActor, &req, stream).start() +/// ``` +/// +/// Create a Websocket session with a specific max frame size, +/// a [`Codec`] or protocols. +/// ```rust +/// const MAX_FRAME_SIZE: usize = 10_000; // in bytes. +/// ws::WsResponseBuilder::new(WsActor, &req, stream) +/// .codec(Codec::new()) // optional +/// .protocols(&["A", "B"]) // optional +/// .frame_size(MAX_FRAME_SIZE) // optional +/// .start() +/// ``` pub struct WsResponseBuilder<'a, A, T> where A: Actor> @@ -50,7 +68,6 @@ where + StreamHandler>, T: Stream> + 'static, { - #[inline] pub fn new(actor: A, req: &'a HttpRequest, stream: T) -> Self { WsResponseBuilder { actor, @@ -62,25 +79,29 @@ where } } - #[inline] + /// Set the protocols for the session. pub fn protocols(mut self, protocols: &'a [&'a str]) -> Self { self.protocols = Some(protocols); self } - #[inline] + /// Set the max frame size for each message. + /// + /// **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 } - #[inline] + /// Set the [`Codec`] for the session. If [`Self::frame_size`] + /// is also set, the given [`Codec`]'s max frame size will be + /// overriden. pub fn codec(mut self, codec: Codec) -> Self { self.codec = Some(codec); self } - #[inline] fn handshake_resp(&self) -> Result { match self.protocols { Some(protocols) => handshake_with_protocols(self.req, protocols), @@ -88,7 +109,6 @@ where } } - #[inline] fn set_frame_size(&mut self) { if let Some(frame_size) = self.frame_size { match &mut self.codec { @@ -104,7 +124,6 @@ where } } - #[inline] /// Perform WebSocket handshake and start actor. /// /// `req` is an [`HttpRequest`] that should be requesting a websocket @@ -132,7 +151,6 @@ where } } - #[inline] /// Perform WebSocket handshake and start actor. /// /// `req` is an [`HttpRequest`] that should be requesting a websocket