Application lifecycle · Consumer

A handler invocation is part of a larger Consumer lifecycle. Configuration is loaded, dependencies are prepared, physical queues are registered, and each admitted delivery receives its own execution scope. Keeping these steps under one owner also makes startup failure and shutdown manageable.

Choose how to run#

Public API	Use	Shutdown trigger
`Consumer::run()`	Default standalone worker process	OS signals and runtime result
`Consumer::builder().run()`	Middleware, tracing, or other builder options	OS signals and runtime result
`.run_with_cancellation(token)`	Management through a parent application's token	Token, provider termination, or host shutdown
`.start_managed()`	Health observation and programmatic management	Requests through the handle and runtime result

Call these APIs within an existing Tokio runtime. Consumer does not use the HTTP .build().await?.start().await? chain. Token and managed modes install no OS signal listener; the parent application owns signal handling. An already cancelled token returns successfully before composition starts.

use lilyrs::consumer::{CancellationToken, Consumer, ConsumerError};

async fn run_worker(stopping: CancellationToken) -> Result<(), ConsumerError> {
    Consumer::builder().run_with_cancellation(stopping).await
}

After cancelling the token, the parent application also awaits run_worker or the task running it. Cancellation sends a request; the awaited result provides completion evidence.

What happens during startup?#

Builder ownership and pipeline construction timeout options are validated; the explicit tracing choice is applied.
Framework-owned DI is built or a caller-owned container is adopted. Singleton initialization may read configuration and perform I/O.
Queue runtime ownership is acquired; configuration, linked handlers, and pipeline declarations become one accepted plan.
Concrete middleware and guard types are constructed; configured physical queues are registered with the broker.
After the final cancellation check, the managed handle becomes available; a private runtime owner retains resources under supervision.

Startup is not an I/O-free preparation phase. DI initialization and broker registration may access external systems. Message admission is a queue runtime activity. One ready queue does not mean every registration or the entire application startup has completed.

If startup is interrupted, constructed resources transfer to rollback. A pending DI build retains its cleanup receipt but remains subject to Consumer's shared shutdown bound; rollback phases do not each receive a fresh independent 30 seconds.

Execution order for each delivery#

Contract check → scope → middleware before → guards
→ handler owner resolution → parts extractors → terminal payload → handler
→ middleware after (reverse) → scope disposal → settlement

After the metadata contract is accepted, a delivery scope opens. The handler owner is resolved within that active scope after middleware and guards complete. Scoped workers and Service<T> parameters therefore belong to the same delivery. The pipeline is not complete until the last normal middleware callback finishes.

Timeout or shutdown first signals cooperative cancellation; cleanup and settlement authority have separate bounds. See deadlines, middleware, and settlement for the detailed ordering.

Ownership continues through shutdown#

The framework closes new admission and reconciles accepted deliveries, scope cleanup, and settlement. Framework-owned DI can close after queue closure is established. Telemetry shutdown also depends on completion of the work using those resources. One root deadline bounds both graceful and forced phases.

ManagedConsumer is a shareable request and observation handle; the private runtime owner and supervisor hold the actual resources. Dropping the last handle requests shutdown but cannot await its asynchronous result. See managed Consumer and shutdown for .shutdown().await and report interpretation.