actix-extras/guide/src/qs_3_5.md

# Server

[*HttpServer*](../actix_web/struct.HttpServer.html) type is responsible for 
serving http requests. *HttpServer* accept applicaiton factory as a parameter, 
Application factory must have `Send` + `Sync` bounderies. More about that in 
*multi-threading* section. To bind to specific socket address `bind()` must be used.
This method could be called multiple times. To start http server one of the *start*
methods could be used. `start()` method start simple server, `start_tls()` or `start_ssl()`
starts ssl server. *HttpServer* is an actix actor, it has to be initialized
within properly configured actix system:

```rust
# extern crate actix;
# extern crate actix_web;
use actix::*;
use actix_web::*;

fn main() {
    let sys = actix::System::new("guide");

    HttpServer::new(
        || Application::new()
            .resource("/", |r| r.h(httpcodes::HTTPOk)))
        .bind("127.0.0.1:59080").unwrap()
        .start();

#     actix::Arbiter::system().send(actix::msgs::SystemExit(0));
    let _ = sys.run();
}
```

It is possible to start server in separate thread with *spawn()* method. In that
case server spawns new thread and create new actix system in it. To stop
this server send `StopServer` message.

Http server is implemented as an actix actor. It is possible to communicate with server
via messaging system. All start methods like `start()`, `start_ssl()`, etc returns
address of the started http server. Actix http server accept several messages:

* `PauseServer` - Pause accepting incoming connections
* `ResumeServer` - Resume accepting incoming connections
* `StopServer` - Stop incoming connection processing, stop all workers and exit

```rust
# extern crate futures;
# extern crate actix;
# extern crate actix_web;
# use futures::Future;
use actix_web::*;

fn main() {
    let addr = HttpServer::new(
        || Application::new()
             .resource("/", |r| r.h(httpcodes::HTTPOk)))
        .bind("127.0.0.1:0").expect("Can not bind to 127.0.0.1:0")
        .spawn();
        
    let _ = addr.call_fut(dev::StopServer{graceful: true}).wait();  // <- Send `StopServer` message to server.
}
```

## Multi-threading

Http server automatically starts number of http workers, by default
this number is equal to number of logical cpu in the system. This number
could be overridden with `HttpServer::threads()` method.

```rust
# extern crate actix_web;
# extern crate tokio_core;
# use tokio_core::net::TcpStream;
# use std::net::SocketAddr;
use actix_web::*;

fn main() {
    HttpServer::<TcpStream, SocketAddr, _, _>::new(
        || Application::new()
            .resource("/", |r| r.h(httpcodes::HTTPOk)))
        .threads(4); // <- Start 4 workers
}
```

Server create separate application instance for each created worker. Application state
is not shared between threads, to share state `Arc` could be used. Application state
does not need to be `Send` and `Sync` but application factory must be `Send` + `Sync`.

## SSL

There are two `tls` and `alpn` features for ssl server. `tls` feature is for `native-tls`
integration and `alpn` is for `openssl`.

```toml
[dependencies]
actix-web = { git = "https://github.com/actix/actix-web", features=["alpn"] }
```

```rust,ignore
use std::fs::File;
use actix_web::*;

fn main() {
    let mut file = File::open("identity.pfx").unwrap();
    let mut pkcs12 = vec![];
    file.read_to_end(&mut pkcs12).unwrap();
    let pkcs12 = Pkcs12::from_der(&pkcs12).unwrap().parse("12345").unwrap();

    HttpServer::new(
        || Application::new()
            .resource("/index.html", |r| r.f(index)))
        .bind("127.0.0.1:8080").unwrap()
        .serve_ssl(pkcs12).unwrap();
}
```

Note on *HTTP/2.0* protocol over tls without prior knowledge, it requires
[tls alpn](https://tools.ietf.org/html/rfc7301). At the moment only
`openssl` has `alpn ` support.

Please check [example](https://github.com/actix/actix-web/tree/master/examples/tls) 
for full example.

## Keep-Alive

Actix can wait for requests on a keep-alive connection. *Keep alive*
connection behavior is defined by server settings.

 * `Some(75)` - enable 75 sec *keep alive* timer according request and response settings.
 * `Some(0)` - disable *keep alive*.
 * `None` - Use `SO_KEEPALIVE` socket option.

```rust
# extern crate actix_web;
# extern crate tokio_core;
# use tokio_core::net::TcpStream;
# use std::net::SocketAddr;
use actix_web::*;

fn main() {
    HttpServer::<TcpStream, SocketAddr, _, _>::new(||
        Application::new()
            .resource("/", |r| r.h(httpcodes::HTTPOk)))
        .keep_alive(None); // <- Use `SO_KEEPALIVE` socket option.
}
```

If first option is selected then *keep alive* state
calculated based on response's *connection-type*. By default
`HttpResponse::connection_type` is not defined in that case *keep alive*
defined by request's http version. Keep alive is off for *HTTP/1.0*
and is on for *HTTP/1.1* and "HTTP/2.0".

*Connection type* could be change with `HttpResponseBuilder::connection_type()` method.

```rust
# extern crate actix_web;
# use actix_web::httpcodes::*;
use actix_web::*;

fn index(req: HttpRequest) -> HttpResponse {
    HTTPOk.build()
        .connection_type(headers::ConnectionType::Close) // <- Close connection
        .force_close()                                   // <- Alternative method
        .finish().unwrap()
}
# fn main() {}
```