Improve documentation for actix-web-actors (#2788)

actix-web-actors/Cargo.toml

@@ -29,6 +29,9 @@ tokio = { version = "1.13.1", features = ["sync"] }
 actix-rt = "2.2"
 actix-test = "0.1.0-beta.13"
 awc = { version = "3", default-features = false }
+actix-web = { version = "4", features = ["macros"] }
+
+mime = "0.3"
 
 env_logger = "0.9"
 futures-util = { version = "0.3.7", default-features = false }

actix-web-actors/src/context.rs

@@ -14,6 +14,58 @@ use futures_core::Stream;
 use tokio::sync::oneshot::Sender;
 
 /// Execution context for HTTP actors
+///
+/// # Example
+///
+/// A demonstration of [server-sent events](https://developer.mozilla.org/docs/Web/API/Server-sent_events) using actors:
+///
+/// ```no_run
+/// use std::time::Duration;
+///
+/// use actix::{Actor, AsyncContext};
+/// use actix_web::{get, http::header, App, HttpResponse, HttpServer};
+/// use actix_web_actors::HttpContext;
+/// use bytes::Bytes;
+///
+/// struct MyActor {
+///     count: usize,
+/// }
+///
+/// impl Actor for MyActor {
+///     type Context = HttpContext<Self>;
+///
+///     fn started(&mut self, ctx: &mut Self::Context) {
+///         ctx.run_later(Duration::from_millis(100), Self::write);
+///     }
+/// }
+///
+/// impl MyActor {
+///     fn write(&mut self, ctx: &mut HttpContext<Self>) {
+///         self.count += 1;
+///         if self.count > 3 {
+///             ctx.write_eof()
+///         } else {
+///             ctx.write(Bytes::from(format!("event: count\ndata: {}\n\n", self.count)));
+///             ctx.run_later(Duration::from_millis(100), Self::write);
+///         }
+///     }
+/// }
+///
+/// #[get("/")]
+/// async fn index() -> HttpResponse {
+///     HttpResponse::Ok()
+///         .insert_header(header::ContentType(mime::TEXT_EVENT_STREAM))
+///         .streaming(HttpContext::create(MyActor { count: 0 }))
+/// }
+///
+/// #[actix_web::main]
+/// async fn main() -> std::io::Result<()> {
+///     HttpServer::new(|| App::new().service(index))
+///         .bind(("127.0.0.1", 8080))?
+///         .run()
+///         .await
+/// }
+/// ```
 pub struct HttpContext<A>
 where
     A: Actor<Context = HttpContext<A>>,
@@ -210,7 +262,7 @@ mod tests {
         type Context = HttpContext<Self>;
 
         fn started(&mut self, ctx: &mut Self::Context) {
-            ctx.run_later(Duration::from_millis(100), |slf, ctx| slf.write(ctx));
+            ctx.run_later(Duration::from_millis(100), Self::write);
         }
     }
 
@@ -221,7 +273,7 @@ mod tests {
                 ctx.write_eof()
             } else {
                 ctx.write(Bytes::from(format!("LINE-{}", self.count)));
-                ctx.run_later(Duration::from_millis(100), |slf, ctx| slf.write(ctx));
+                ctx.run_later(Duration::from_millis(100), Self::write);
             }
         }
     }

actix-web-actors/src/lib.rs

@@ -1,4 +1,59 @@
 //! Actix actors support for Actix Web.
+//!
+//! # 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 index(req: HttpRequest, stream: web::Payload) -> Result<HttpResponse, Error> {
+//!     ws::start(MyWs, &req, stream)
+//! }
+//!
+//! #[actix_web::main]
+//! async fn main() -> std::io::Result<()> {
+//!     HttpServer::new(|| App::new().service(index))
+//!         .bind(("127.0.0.1", 8080))?
+//!         .run()
+//!         .await
+//! }
+//! ```
+//!
+//! # Documentation & Community Resources
+//! In addition to this API documentation, several other resources are available:
+//!
+//! * [Website & User Guide](https://actix.rs/)
+//! * [Documentation for `actix_web`](actix_web)
+//! * [Examples Repository](https://github.com/actix/examples)
+//! * [Community Chat on Discord](https://discord.gg/NWpN5mmg3x)
+//!
+//! To get started navigating the API docs, you may consider looking at the following pages first:
+//!
+//! * [`ws`]: This module provides actor support for WebSockets.
+//!
+//! * [`HttpContext`]: This struct provides actor support for streaming HTTP responses.
+//!
 
 #![deny(rust_2018_idioms, nonstandard_style)]
 #![warn(future_incompatible)]

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,
@@ -41,20 +97,51 @@ use tokio::sync::oneshot;
 ///
 /// # Examples
 ///
-/// Create a Websocket session response with default configuration.
+/// ```no_run
-/// ```ignore
+/// # use actix::{Actor, StreamHandler};
-/// WsResponseBuilder::new(WsActor, &req, stream).start()
+/// # use actix_web::{get, web, App, Error, HttpRequest, HttpResponse, HttpServer};
-/// ```
+/// # use actix_web_actors::ws;
+/// #
+/// # 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) {}
+/// # }
+/// #
+/// #[get("/ws")]
+/// async fn websocket(req: HttpRequest, stream: web::Payload) -> Result<HttpResponse, Error> {
+///     ws::WsResponseBuilder::new(MyWs, &req, stream).start()
+/// }
 ///
-/// Create a Websocket session with a specific max frame size, [`Codec`], and protocols.
-/// ```ignore
 /// const MAX_FRAME_SIZE: usize = 16_384; // 16KiB
 ///
-/// ws::WsResponseBuilder::new(WsActor, &req, stream)
+/// #[get("/custom-ws")]
-///     .codec(Codec::new())
+/// async fn custom_websocket(req: HttpRequest, stream: web::Payload) -> Result<HttpResponse, Error> {
-///     .protocols(&["A", "B"])
+///     // Create a Websocket session with a specific max frame size, codec, and protocols.
-///     .frame_size(MAX_FRAME_SIZE)
+///     ws::WsResponseBuilder::new(MyWs, &req, stream)
-///     .start()
+///         .codec(actix_http::ws::Codec::new())
+///         // This will overwrite the codec's max frame-size
+///         .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
+/// # }
 /// ```
 pub struct WsResponseBuilder<'a, A, T>
 where