From c1a8103cbced840c379342a4df77e624fc77fc03 Mon Sep 17 00:00:00 2001 From: Maxim Vorobjov Date: Tue, 28 Jan 2020 14:36:35 +0300 Subject: [PATCH] Architecture diagrams of HttpServer and Connection lifecycle (#148) * add arch diagrams and menu * fix colors for arch diagrams * refine architecture diagrams, ready for review * capitalize titles and add mmdc instruction * apply code review requested changes * Add links to accept, worker and dispatcher too --- README.md | 12 ++++++ content/docs/conn_lifecycle.md | 42 +++++++++++++++++++++ content/docs/http_server_init.md | 23 +++++++++++ layouts/docs/baseof.html | 11 ++++++ static/img/diagrams/connection_accept.mmd | 28 ++++++++++++++ static/img/diagrams/connection_accept.svg | 4 ++ static/img/diagrams/connection_overview.mmd | 34 +++++++++++++++++ static/img/diagrams/connection_overview.svg | 4 ++ static/img/diagrams/connection_request.mmd | 29 ++++++++++++++ static/img/diagrams/connection_request.svg | 4 ++ static/img/diagrams/connection_worker.mmd | 34 +++++++++++++++++ static/img/diagrams/connection_worker.svg | 4 ++ static/img/diagrams/http_server.mmd | 32 ++++++++++++++++ static/img/diagrams/http_server.svg | 4 ++ 14 files changed, 265 insertions(+) create mode 100644 content/docs/conn_lifecycle.md create mode 100644 content/docs/http_server_init.md create mode 100644 static/img/diagrams/connection_accept.mmd create mode 100644 static/img/diagrams/connection_accept.svg create mode 100644 static/img/diagrams/connection_overview.mmd create mode 100644 static/img/diagrams/connection_overview.svg create mode 100644 static/img/diagrams/connection_request.mmd create mode 100644 static/img/diagrams/connection_request.svg create mode 100644 static/img/diagrams/connection_worker.mmd create mode 100644 static/img/diagrams/connection_worker.svg create mode 100644 static/img/diagrams/http_server.mmd create mode 100644 static/img/diagrams/http_server.svg diff --git a/README.md b/README.md index caed786..8391a0d 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,18 @@ hugo server Then visit [http://localhost:1313](http://localhost:1313). +## Updating diagrams + +Diagrams are located under [/static/css/img/diagrams/](https://github.com/actix/actix-website/tree/master/static/img/diagrams) and built with [Mermaid CLI](https://github.com/mermaidjs/mermaid.cli). + +For instance to edit `connection_overview` diagram: +```sh +cd static/css/img/diagrams +vi connection_overview.mmd +# Compile diagrams: +mmdc -i connection_overview.mmd -o connection_overview.svg +``` + # License Pretty murky. Right now a massive clone of the tokio website. Will get this diff --git a/content/docs/conn_lifecycle.md b/content/docs/conn_lifecycle.md new file mode 100644 index 0000000..6675111 --- /dev/null +++ b/content/docs/conn_lifecycle.md @@ -0,0 +1,42 @@ +--- +title: Connection Lifecycle +menu: docs_architecture +weight: 20 +--- + + +# Architecture overview + +After Server has started listening to all sockets, [`Accept`][Accept] and [`Worker`][Worker] are two main loops responsible for processing incoming client connections. + +Once connection accepted Application level protocol processing happens in a protocol specific [`Dispatcher`][Dispatcher] loop spawned from [`Worker`][Worker]. + + Please note, below diagrams are outlining happy-path scenarios only. + +![](/img/diagrams/connection_overview.svg) + +## Accept loop in more detail + +![](/img/diagrams/connection_accept.svg) + +Most of code implementation resides in [`actix-server`][server] crate for struct [`Accept`][Accept]. + +## Worker loop in more detail + +![](/img/diagrams/connection_worker.svg) + +Most of code implementation resides in [`actix-server`][server] crate for struct [`Worker`][Worker]. + +## Request loop roughly + +![](/img/diagrams/connection_request.svg) + +Most of code implementation for request loop resides in [`actix-web`][web] and [`actix-http`][http] crates. + + +[server]: https://crates.io/crates/actix-server +[web]: https://crates.io/crates/actix-web +[http]: https://crates.io/crates/actix-http +[Accept]: https://github.com/actix/actix-net/blob/master/actix-server/src/accept.rs +[Worker]: https://github.com/actix/actix-net/blob/master/actix-server/src/worker.rs +[Dispatcher]: https://github.com/actix/actix-web/blob/master/actix-http/src/h1/dispatcher.rs \ No newline at end of file diff --git a/content/docs/http_server_init.md b/content/docs/http_server_init.md new file mode 100644 index 0000000..2f3cb4b --- /dev/null +++ b/content/docs/http_server_init.md @@ -0,0 +1,23 @@ +--- +title: Http Server Initialization +menu: docs_architecture +weight: 10 +--- + +## Architecture overview + +Below is a diagram of HttpServer initalization, which happens on the following code +```rust +#[actix_rt::main] +async fn main() -> std::io::Result<()> { + HttpServer::new(|| { + App::new() + .route("/", web::to(|| HttpResponse::Ok())) + }) + .bind("127.0.0.1:8088")? + .run() + .await +} +``` + +![](/img/diagrams/http_server.svg) diff --git a/layouts/docs/baseof.html b/layouts/docs/baseof.html index 626433b..9f3960c 100644 --- a/layouts/docs/baseof.html +++ b/layouts/docs/baseof.html @@ -75,6 +75,17 @@ +
Diagrams
+
+ +
+
API Documentation