pub enum Item {
+ FirstText(Bytes),
+ FirstBinary(Bytes),
+ Continue(Bytes),
+ Last(Bytes),
+}A WebSocket continuation item.
+Subscriber to this type, returning a
+[WithDispatch] wrapper. Read morepub enum Message {
Text(ByteString),
Binary(Bytes),
- Continuation(Item),
+ Continuation(Item),
Ping(Bytes),
Pong(Bytes),
Close(Option<CloseReason>),
@@ -9,7 +9,7 @@
}A WebSocket message.
Text message.
Binary message.
-Continuation.
+Continuation.
Ping message.
Pong message.
Close message with optional reason.
diff --git a/actix_ws/index.html b/actix_ws/index.html index dbc613504..6cb9eada3 100644 --- a/actix_ws/index.html +++ b/actix_ws/index.html @@ -1,3 +1,3 @@WebSockets for Actix Web, without actors.
For usage, see documentation on handle().
pub struct MessageStream { /* private fields */ }A stream of Messages from a websocket client
Messages can be accessed via the stream’s .next() method
Wait for the next item from the message stream
+pub struct Session { /* private fields */ }A handle into the websocket session.
+pub struct Session { /* private fields */ }A handle into the websocket session.
This type can be used to send messages into the websocket.
-Send text into the websocket
+Send text into the websocket
-if session.text("Some text").await.is_err() {
+if session.text("Some text").await.is_err() {
// session closed
}
-Send raw bytes into the websocket
+Send raw bytes into the websocket
-if session.binary(b"some bytes").await.is_err() {
+if session.binary(&b"some bytes"[..]).await.is_err() {
// session closed
}
-Ping the client
For many applications, it will be important to send regular pings to keep track of if the client has disconnected
-if session.ping(b"").await.is_err() {
+if session.ping(b"").await.is_err() {
// session is closed
}
-Pong the client
-match msg {
+match msg {
Message::Ping(bytes) => {
let _ = session.pong(&bytes).await;
}
_ => (),
}
-Send a close message, and consume the session
+Manually control sending continuations
+Be wary of this method. Continuations represent multiple frames that, when combined, are +presented as a single message. They are useful when the entire contents of a message are +not avilable all at once. However, continuations MUST NOT be interrupted by other Text or +Binary messages. Control messages such as Ping, Pong, or Close are allowed to interrupt a +continuation.
+Continuations must be initialized with a First variant, and must be terminated by a Last +variant, with only Continue variants sent in between.
+ +session.continuation(Item::FirstText("Hello".into())).await?;
+session.continuation(Item::Continue(b", World"[..].into())).await?;
+session.continuation(Item::Last(b"!"[..].into())).await?;pub struct StreamingBody { /* private fields */ }A response body for Websocket HTTP Requests
-U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nPing the client\nPong the client\nWait for the next item from the message stream\nSend text into the websocket")
\ No newline at end of file
+searchState.loadedDescShard("actix_ws", 0, "WebSockets for Actix Web, without actors.\nIndicates an abnormal closure. If the abnormal closure was …\nIndicates that the server is overloaded and the client …\nIndicates that an endpoint is “going away”, such as a …\nBad opcode.\nBinary message.\nClose message with optional reason.\nStatus code used to indicate why an endpoint is closing …\nReason for closing the connection\nThe error representing a closed websocket session\nContinuation.\nUnknown continuation fragment.\nContinuation has not started.\nReceived new continuation but it is already started.\nIndicates that a server is terminating the connection …\nIndicates that an endpoint (client) is terminating the …\nIndicates that an endpoint is terminating the connection …\nInvalid control frame length\nEncountered invalid opcode.\nI/O error.\nA WebSocket continuation item.\nReceived a masked frame from server.\nA WebSocket message.\nA stream of Messages from a websocket client\nNo-op. Useful for low-level services.\nIndicates a normal closure, meaning that the purpose for …\nA payload reached size limit.\nPing message.\nIndicates that an endpoint is terminating the connection …\nPong message.\nIndicates that an endpoint is terminating the connection …\nWebSocket protocol errors.\nIndicates that the server is restarting. A client may …\nA handle into the websocket session.\nIndicates that an endpoint is terminating the connection …\nA response body for Websocket HTTP Requests\nText message.\nReceived an unmasked frame from client.\nIndicates that an endpoint is terminating the connection …\nSend raw bytes into the websocket\nSend a close message, and consume the session\nExit code\nManually control sending continuations\nOptional description of the exit code\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nBegin handling websocket traffic\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nPing the client\nPong the client\nWait for the next item from the message stream\nSend text into the websocket")
\ No newline at end of file
diff --git a/settings.html b/settings.html
index fe551eac5..d2a480464 100644
--- a/settings.html
+++ b/settings.html
@@ -1 +1 @@
-use std::{
collections::VecDeque,
future::poll_fn,
@@ -248,10 +251,13 @@
/// Wait for the next item from the message stream
///
- /// ```rust,ignore
+ /// ```rust,no_run
+ /// # use actix_ws::MessageStream;
+ /// # async fn test(mut stream: MessageStream) {
/// while let Some(Ok(msg)) = stream.recv().await {
/// // handle message
/// }
+ /// # }
/// ```
pub async fn recv(&mut self) -> Option<Result<Message, ProtocolError>> {
poll_fn(|cx| Pin::new(&mut *self).poll_next(cx)).await
diff --git a/src/actix_ws/lib.rs.html b/src/actix_ws/lib.rs.html
index 710d041f0..9782d2531 100644
--- a/src/actix_ws/lib.rs.html
+++ b/src/actix_ws/lib.rs.html
@@ -92,7 +92,7 @@
#![doc(html_favicon_url = "https://actix.rs/favicon.ico")]
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
-pub use actix_http::ws::{CloseCode, CloseReason, Message, ProtocolError};
+pub use actix_http::ws::{CloseCode, CloseReason, Item, Message, ProtocolError};
use actix_http::{
body::{BodyStream, MessageBody},
ws::handshake,
diff --git a/src/actix_ws/session.rs.html b/src/actix_ws/session.rs.html
index ca780b8d7..d70adf8e7 100644
--- a/src/actix_ws/session.rs.html
+++ b/src/actix_ws/session.rs.html
@@ -141,12 +141,59 @@
141
142
143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
use std::sync::{
atomic::{AtomicBool, Ordering},
Arc,
};
-use actix_http::ws::{CloseReason, Message};
+use actix_http::ws::{CloseReason, Item, Message};
use actix_web::web::Bytes;
use bytestring::ByteString;
use tokio::sync::mpsc::Sender;
@@ -188,10 +235,13 @@
/// Send text into the websocket
///
- /// ```rust,ignore
+ /// ```rust,no_run
+ /// # use actix_ws::Session;
+ /// # async fn test(mut session: Session) {
/// if session.text("Some text").await.is_err() {
/// // session closed
/// }
+ /// # }
/// ```
pub async fn text(&mut self, msg: impl Into<ByteString>) -> Result<(), Closed> {
self.pre_check();
@@ -207,10 +257,13 @@
/// Send raw bytes into the websocket
///
- /// ```rust,ignore
- /// if session.binary(b"some bytes").await.is_err() {
+ /// ```rust,no_run
+ /// # use actix_ws::Session;
+ /// # async fn test(mut session: Session) {
+ /// if session.binary(&b"some bytes"[..]).await.is_err() {
/// // session closed
/// }
+ /// # }
/// ```
pub async fn binary(&mut self, msg: impl Into<Bytes>) -> Result<(), Closed> {
self.pre_check();
@@ -229,10 +282,13 @@
/// For many applications, it will be important to send regular pings to keep track of if the
/// client has disconnected
///
- /// ```rust,ignore
+ /// ```rust,no_run
+ /// # use actix_ws::Session;
+ /// # async fn test(mut session: Session) {
/// if session.ping(b"").await.is_err() {
/// // session is closed
/// }
+ /// # }
/// ```
pub async fn ping(&mut self, msg: &[u8]) -> Result<(), Closed> {
self.pre_check();
@@ -248,13 +304,16 @@
/// Pong the client
///
- /// ```rust,ignore
+ /// ```rust,no_run
+ /// # use actix_ws::{Message, Session};
+ /// # async fn test(mut session: Session, msg: Message) {
/// match msg {
/// Message::Ping(bytes) => {
/// let _ = session.pong(&bytes).await;
/// }
/// _ => (),
/// }
+ /// # }
pub async fn pong(&mut self, msg: &[u8]) -> Result<(), Closed> {
self.pre_check();
if let Some(inner) = self.inner.as_mut() {
@@ -267,12 +326,47 @@
}
}
+ /// Manually control sending continuations
+ ///
+ /// Be wary of this method. Continuations represent multiple frames that, when combined, are
+ /// presented as a single message. They are useful when the entire contents of a message are
+ /// not avilable all at once. However, continuations MUST NOT be interrupted by other Text or
+ /// Binary messages. Control messages such as Ping, Pong, or Close are allowed to interrupt a
+ /// continuation.
+ ///
+ /// Continuations must be initialized with a First variant, and must be terminated by a Last
+ /// variant, with only Continue variants sent in between.
+ ///
+ /// ```rust,no_run
+ /// # use actix_ws::{Item, Session};
+ /// # async fn test(mut session: Session) -> Result<(), Box<dyn std::error::Error>> {
+ /// session.continuation(Item::FirstText("Hello".into())).await?;
+ /// session.continuation(Item::Continue(b", World"[..].into())).await?;
+ /// session.continuation(Item::Last(b"!"[..].into())).await?;
+ /// # Ok(())
+ /// # }
+ /// ```
+ pub async fn continuation(&mut self, msg: Item) -> Result<(), Closed> {
+ self.pre_check();
+ if let Some(inner) = self.inner.as_mut() {
+ inner
+ .send(Message::Continuation(msg))
+ .await
+ .map_err(|_| Closed)
+ } else {
+ Err(Closed)
+ }
+ }
+
/// Send a close message, and consume the session
///
/// All clones will return `Err(Closed)` if used after this call
///
- /// ```rust,ignore
+ /// ```rust,no_run
+ /// # use actix_ws::{Closed, Session};
+ /// # async fn test(mut session: Session) -> Result<(), Closed> {
/// session.close(None).await
+ /// # }
/// ```
pub async fn close(mut self, reason: Option<CloseReason>) -> Result<(), Closed> {
self.pre_check();