docs(actix-web-actors): add `ws` module documentation

actix-web-actors/src/ws.rs

@@ -1,4 +1,60 @@
 //! Websocket integration.
+//! 
+//! # Examples
+//! 
+//! ```no_run
+//! use actix::{Actor, StreamHandler};
+//! use actix_web::{get, web, App, Error, HttpRequest, HttpResponse, HttpServer};
+//! use actix_web_actors::ws;
+//! 
+//! /// Define Websocket actor
+//! struct MyWs;
+//! 
+//! impl Actor for MyWs {
+//!     type Context = ws::WebsocketContext<Self>;
+//! }
+//! 
+//! /// Handler for ws::Message message
+//! impl StreamHandler<Result<ws::Message, ws::ProtocolError>> for MyWs {
+//!     fn handle(&mut self, msg: Result<ws::Message, ws::ProtocolError>, ctx: &mut Self::Context) {
+//!         match msg {
+//!             Ok(ws::Message::Ping(msg)) => ctx.pong(&msg),
+//!             Ok(ws::Message::Text(text)) => ctx.text(text),
+//!             Ok(ws::Message::Binary(bin)) => ctx.binary(bin),
+//!             _ => (),
+//!         }
+//!     }
+//! }
+//! 
+//! #[get("/ws")]
+//! async fn websocket(req: HttpRequest, stream: web::Payload) -> Result<HttpResponse, Error> {
+//!     ws::start(MyWs, &req, stream)
+//! }
+//! 
+//! const MAX_FRAME_SIZE: usize = 16_384; // 16KiB
+//! 
+//! #[get("/custom-ws")]
+//! async fn custom_websocket(req: HttpRequest, stream: web::Payload) -> Result<HttpResponse, Error> {
+//!     // Create a Websocket session with a specific max frame size, and protocols.
+//!     ws::WsResponseBuilder::new(MyWs, &req, stream)
+//!         .frame_size(MAX_FRAME_SIZE)
+//!         .protocols(&["A", "B"])
+//!         .start()
+//! }
+//! 
+//! #[actix_web::main]
+//! async fn main() -> std::io::Result<()> {
+//!     HttpServer::new(|| {
+//!             App::new()
+//!                 .service(websocket)
+//!                 .service(custom_websocket)
+//!         })
+//!         .bind(("127.0.0.1", 8080))?
+//!         .run()
+//!         .await
+//! }
+//! ```
+//! 
 
 use std::{
     collections::VecDeque,