Application Runtime

caelix provides Application for production and TestApplication for in-process HTTP tests on both the Actix and Axum backends (see Testing). The Axum adapter is documented in Axum and Tower.

#![allow(unused)]
fn main() {
use caelix::Application;

Application::new::<AppModule>()
    .await
    ?
    .listen("127.0.0.1:8080")
    .await
}

Application::new returns startup failures as caelix::Result<Application>.

#![allow(unused)]
fn main() {
let app = Application::new::<AppModule>().await?;
app.listen("127.0.0.1:8080").await?;
}

Startup builds the container from module metadata, logs controller routes, runs bootstrap hooks, and stores the adapter route registration function.

Body Limits and Upload Storage

The default JSON body limit is 1 MiB. Override it before listen:

#![allow(unused)]
fn main() {
Application::new::<AppModule>()
    .await
    ?
    .body_limit(2 * 1024 * 1024)
    .listen("127.0.0.1:8080")
    .await
}

The same limit applies to multipart controller routes. Oversized JSON or multipart bodies return 413 Payload Too Large; malformed JSON or multipart data returns 400 Bad Request. Configure the isolated directory used to stage multipart file parts with upload_temp_dir:

#![allow(unused)]
fn main() {
Application::new::<AppModule>()
    .await?
    .body_limit(10 * 1024 * 1024)
    .upload_temp_dir("/var/tmp/my-service/uploads")
    .listen("127.0.0.1:8080")
    .await?;
}

See Multipart Uploads for route-level upload limits, file ownership, and typed form binding.

Workers

Application starts the Actix server with one worker by default. Increase it before listen when the process should run multiple Actix workers:

#![allow(unused)]
fn main() {
Application::new::<AppModule>()
    .await
    ?
    .workers(4)
    .listen("127.0.0.1:8080")
    .await
}

Logging

The runtime logs startup, route mapping, listening, and shutdown. Application logging, levels, Actix access formats, buffering, and Axum differences are covered in the dedicated Logging guide.

Shutdown

Application::listen runs provider on_shutdown hooks after the Actix server exits. If binding the socket fails after startup has completed, shutdown hooks are also attempted before returning the bind error.

#![allow(unused)]
fn main() {
Application::new::<AppModule>()
    .await
    ?
    .listen("0.0.0.0:8080")
    .await
}

Shutdown hook errors are converted into std::io::Error after the server stops.

Actix Adapter Behavior

The adapter installs:

• Shared Arc<Container> application data.
• Shared request configuration with the Caelix body limit, normalized JSON and multipart errors, typed multipart DTO binding, temporary upload storage, and JSON body parsing for #[body] routes even when the client omits the Content-Type header.
• Generated controller routes from module metadata.
• A request logging wrapper, enabled only when access logging is explicitly requested.

Controller route wrappers are generated by #[controller]. Plain routes call the controller directly. Routes that use guards, interceptors, or #[user] build a RequestContext, run guards, run interceptors, call the controller method, convert the result to a Caelix response, then convert it to actix_web::HttpResponse.