Actix Documentation

Actix provides several example projects demonstrating the use of various async database adapters:

• Postgres: Example Link
• SQLite: Example Link
• MongoDB: Example Link

The Actix ecosystem is open source and hosted under the @actix GitHub organization. You can find the core web framework, additional crates, and practical usage examples in the following repositories:

• actix-web: The core web framework. API documentation.
• actix-extras: A collection of additional crates for the Actix ecosystem.
• examples: A dedicated repository containing various implementation examples.

By default, Actix Actors run on the System's Arbiter thread using its event loop. For CPU-bound workloads or highly concurrent workloads where you need to process tasks in parallel, you should use a SyncArbiter.

A SyncArbiter launches multiple instances of a single Actor type across a pool of OS threads. Note that a SyncArbiter can only host one specific type of Actor; you must create a separate SyncArbiter for every different Actor type you wish to run in a thread pool.

The HttpServer supports graceful shutdown when it receives a stop signal. Upon receiving a signal, workers are given a specific amount of time to finish serving active requests before being force-dropped.

• Default Timeout: 30 seconds.
• Configure Timeout: Use HttpServer::shutdown_timeout() to change this value.
• Supported Signals:
  • CTRL-C (all OSes)
  • SIGINT (Force shutdown)
  • SIGTERM (Graceful shutdown)
  • SIGQUIT (Force shutdown)
• Disable Signals: Use HttpServer::disable_signals() if you want to manage signal handling manually.

Scopes allow you to group routes that share a common root path. Scopes can be nested to create hierarchical URL structures. Variable path segments within a scope are accessible via HttpRequest::match_info() or the Path extractor.

// Example of scoping routes
App::new().service(
    web::scope("/users")
        .route("/show", web::get().to(show_user))
        .route("/{id}/profile", web::get().to(user_profile))
);

The Context is the internal execution environment for an Actor. It provides the interface for an actor to interact with the Actix runtime. Through the Context, an actor can:

• Manage its Mailbox (capacity and message flow).
• Access its own Address (Addr).
• Control its Lifecycle (e.g., stopping execution via stop()).

Every actor implementation must define its Context type, typically as Context<Self>.

The Actix connection lifecycle is driven by three primary loops that manage the transition from a listening socket to a processed HTTP request:

1. Accept Loop: Responsible for listening to sockets and accepting incoming client connections. This is primarily implemented in the actix-server crate via the Accept struct.
2. Worker Loop: Once a connection is accepted, it is handed off to a Worker. The worker loop manages the lifecycle of that specific connection. This is also implemented in actix-server via the Worker struct.
3. Dispatcher Loop: Within the Worker loop, a protocol-specific Dispatcher is spawned to handle application-level protocol processing (e.g., HTTP). This loop is responsible for the actual request/response handling.

Understanding this flow helps in debugging connection issues, optimizing worker counts, or implementing custom protocol dispatchers.

To prevent leaking sensitive system information, divide your application errors into two categories:

1. User-facing errors: Errors intended to be read by the client (e.g., ValidationError). These should implement ResponseError and use messages that are helpful to the user.
2. Internal errors: Errors that occur within the server environment (e.g., database connection timeouts, template rendering failures). These should be mapped to a generic InternalError before being returned to the user, ensuring specific technical details remain hidden.

Pattern: Use map_err to transform internal failures into a generic user-facing error type.

Actix Web can automatically compress payloads using the Compress middleware. Supported codecs include:

• Brotli
• Gzip
• Deflate
• Identity

Automatic Compression

By default, a response's Content-Encoding header is set to ContentEncoding::Auto. This performs automatic negotiation based on the client's Accept-Encoding request header.

Disabling Compression

To explicitly disable compression for a specific handler, set the Content-Encoding header to Identity.

Serving Pre-compressed Assets

If you are serving a body that is already compressed (e.g., pre-compressed static assets), manually set the Content-Encoding header on the response to bypass the automatic compression middleware.

Actors can be started using Actor::start() (if the instance can be created immediately) or Actor::create() (if you need access to the context during creation). Both methods return an address object used for communication.

• addr.send(msg): Sends a message and returns a future that resolves to the result.
• addr.do_send(msg): Sends a message without waiting for a response.

// Start the actor
let addr = MyActor { count: 10 }.start();

// Send a message and await the result
let res = addr.send(Ping(10)).await;