diff --git a/content/docs/server.md b/content/docs/server.md index 011705c..b8c03a0 100644 --- a/content/docs/server.md +++ b/content/docs/server.md @@ -10,16 +10,12 @@ The [**HttpServer**][httpserverstruct] type is responsible for serving HTTP requ `HttpServer` accepts an application factory as a parameter, and the application factory must have `Send` + `Sync` boundaries. More about that in the _multi-threading_ section. -To bind to a specific socket address, [`bind()`][bindmethod] must be used, and it may be called multiple times. To bind ssl socket, [`bind_rustls()`][bindrusttls] or [`bind_openssl()`][bindopensslmethod] should be used. To run the HTTP server, use the `HttpServer::run()` method. +To start the web server it must first be bound to a network socket. Use [`HttpServer::bind()`][bindmethod] with a socket address tuple or string such as `("127.0.0.1", 8080)` or `"0.0.0.0:8080"`. This will fail if the socket is being used by another application. + +After the `bind` is successful, use [`HttpServer::run()`][httpserver_run] to return a [`Server`][server] instance. The `Server` must be `await`ed or `spawn`ed to start processing requests and will run until it receives a shutdown signal (such as, by default, a `ctrl-c`; [read more here](#graceful-shutdown)). {{< include-example example="server" section="main" >}} -The `run()` method returns an instance of the [`Server`][server] type. A `Server` must be `await`ed or `spawn`ed to start processing requests. It will complete when it receives a shutdown signal; Actix Web listens for system process signals by default. - -The following example shows how to start the HTTP server in a Tokio task with manual commands and shutdown using a server handle. - -{{< include-example example="server" file="signals.rs" section="signals" >}} - ## Multi-Threading `HttpServer` automatically starts a number of HTTP _workers_, by default this number is equal to the number of logical CPUs in the system. This number can be overridden with the [`HttpServer::workers()`][workers] method. @@ -28,9 +24,9 @@ The following example shows how to start the HTTP server in a Tokio task with ma Once the workers are created, they each receive a separate _application_ instance to handle requests. Application state is not shared between the threads, and handlers are free to manipulate their copy of the state with no concurrency concerns. -> Application state does not need to be `Send` or `Sync`, but application factories must be `Send` + `Sync`. +Application state does not need to be `Send` or `Sync`, but application factories must be `Send` + `Sync`. -To share state between worker threads, use an `Arc`. Special care should be taken once sharing and synchronization are introduced. In many cases, performance costs are inadvertently introduced as a result of locking the shared state for modifications. +To share state between worker threads, use an `Arc`/`Data`. Special care should be taken once sharing and synchronization are introduced. In many cases, performance costs are inadvertently introduced as a result of locking the shared state for modifications. In some cases these costs can be alleviated using more efficient locking strategies, for example using [read/write locks](https://doc.rust-lang.org/std/sync/struct.RwLock.html) instead of [mutexes](https://doc.rust-lang.org/std/sync/struct.Mutex.html) to achieve non-exclusive locking, but the most performant implementations often tend to be ones in which no locking occurs at all. @@ -56,7 +52,9 @@ The same limitation applies to extractors as well. When a handler function recei ## TLS / HTTPS -There are two features for the ssl server: `rustls` and `openssl`. The `rustls` feature is for `rustls` integration and `openssl` is for `openssl`. +Actix Web supports two TLS implementations out-of-the-box: `rustls` and `openssl`. + +The `rustls` crate feature is for `rustls` integration and `openssl` is for `openssl` integration. ```toml [dependencies] @@ -110,6 +108,7 @@ If the first option above is selected, then keep-alive is enabled for HTTP/1.1 r [server]: https://docs.rs/actix-web/4/actix_web/dev/struct.Server.html [httpserverstruct]: https://docs.rs/actix-web/4/actix_web/struct.HttpServer.html [bindmethod]: https://docs.rs/actix-web/4/actix_web/struct.HttpServer.html#method.bind +[httpserver_run]: https://docs.rs/actix-web/4/actix_web/struct.HttpServer.html#method.run [bindopensslmethod]: https://docs.rs/actix-web/4/actix_web/struct.HttpServer.html#method.bind_openssl [bindrusttls]: https://docs.rs/actix-web/4/actix_web/struct.HttpServer.html#method.bind_rustls [workers]: https://docs.rs/actix-web/4/actix_web/struct.HttpServer.html#method.workers diff --git a/examples/http2/src/main.rs b/examples/http2/src/main.rs index 21a4397..82003e6 100644 --- a/examples/http2/src/main.rs +++ b/examples/http2/src/main.rs @@ -8,7 +8,7 @@ async fn index(_req: HttpRequest) -> impl Responder { #[actix_web::main] async fn main() -> std::io::Result<()> { - // load ssl keys + // load TLS keys // to create a self-signed temporary cert for testing: // `openssl req -x509 -newkey rsa:4096 -nodes -keyout key.pem -out cert.pem -days 365 -subj '/CN=localhost'` let mut builder = SslAcceptor::mozilla_intermediate(SslMethod::tls()).unwrap(); diff --git a/examples/server/src/ssl.rs b/examples/server/src/ssl.rs index f30a4bc..8840660 100644 --- a/examples/server/src/ssl.rs +++ b/examples/server/src/ssl.rs @@ -11,7 +11,7 @@ async fn index(_req: HttpRequest) -> impl Responder { #[actix_web::main] async fn main() -> std::io::Result<()> { - // load ssl keys + // load TLS keys // to create a self-signed temporary cert for testing: // `openssl req -x509 -newkey rsa:4096 -nodes -keyout key.pem -out cert.pem -days 365 -subj '/CN=localhost'` let mut builder = SslAcceptor::mozilla_intermediate(SslMethod::tls()).unwrap();