Struct AppState 

#[non_exhaustive]
pub struct AppState { /* private fields */ }

Shared application state passed to all route handlers.

Holds framework-managed resources such as the database connection pool. Axum requires handler state to be Clone, so internal resources use Arc or are already cheaply cloneable (deadpool::Pool is Arc-wrapped internally).

This struct is normally constructed by crate::app::AppBuilder::run and should not need to be created manually. It is public so that custom Axum extractors can access framework resources via State<AppState>.

Examples

use autumn_web::AppState;

// State without a database (e.g., for testing)
let state = AppState::for_test().with_profile("dev");

Implementations

impl AppState

pub fn insert_extension<T>(&self, value: T)

where T: Any + Send + Sync + 'static,

Install or replace a typed runtime extension.

Integrations use this to publish typed runtime resources, such as background-worker handles or dedicated storage pools, after startup.

Panics

Panics if the internal extension map mutex is poisoned.

pub fn session_rotation_hooks(&self) -> SessionRotationHooks

The shared SessionRotationHooks registry, created on first use.

Hooks registered here run after each stored session-id rotation.

Panics

Panics if the internal extension map mutex is poisoned.

pub fn extension<T>(&self) -> Option<Arc<T>>

where T: Any + Send + Sync + 'static,

Borrow a typed runtime extension if it has been installed.

The returned Arc is cloned out of the internal registry so callers do not hold the state mutex while using the value.

Panics

Panics if the internal extension map mutex is poisoned.

pub fn tenant_cell_registry(&self) -> Option<Arc<TenantCellRegistry>>

Return the process-wide cooperative tenant-memory registry, if tenancy middleware has installed it. Request arenas resolved from this registry never use a second, implicit registry or accounting domain.

pub fn live_state<T>(&self) -> Option<LiveStateHandle<T>>

where T: LiveState,

Borrow the app’s designated live-state block, if one was registered with AppBuilder::with_live_state.

This is the block an in-place upgrade carries into the next build; see upgrade.

Examples

if let Some(stats) = state.live_state::<Stats>() {
    let hits = stats.read(|s| s.hits);
    let _ = hits;
}

pub fn extension_or_insert_with<T>(&self, f: impl FnOnce() -> T) -> Arc<T>

where T: Any + Send + Sync + 'static,

Fetch the extension of type T, inserting f()’s result if absent. Atomic get-or-insert under the write lock: concurrent callers share one value. Used to lazily register process-wide registries.

Panics

Panics if the internal extension map mutex is poisoned.

pub const fn pool(&self) -> Option<&Pool<RuntimeConnection>>

Returns the database connection pool.

pub const fn replica_pool(&self) -> Option<&Pool<RuntimeConnection>>

Returns the read-replica database connection pool, if configured.

pub const fn shards(&self) -> Option<&ShardSet>

Returns the configured shard set, when [[database.shards]] entries exist.

The control roles (pool/replica_pool) are unaffected by sharding; framework state lives there.

pub fn read_pool(&self) -> Option<&Pool<RuntimeConnection>>

Returns the pool used for read-only work.

pub const fn metrics(&self) -> &MetricsCollector

Returns the metrics collector.

pub const fn log_levels(&self) -> &LogLevels

Returns the log levels configuration.

pub const fn task_registry(&self) -> &TaskRegistry

Returns the task registry.

pub const fn job_registry(&self) -> &JobRegistry

Returns the job registry.

pub const fn config_props(&self) -> &ConfigProperties

Returns the config properties.

pub const fn metrics_source_registry(&self) -> &MetricsSourceRegistry

Returns the registry of plugin-contributed metrics sources.

pub const fn health_indicator_registry(&self) -> &HealthIndicatorRegistry

Returns the registry of custom health indicators.

pub fn config(&self) -> AutumnConfig

Returns the resolved crate::config::AutumnConfig from the extension map.

Falls back to a default config if no config has been installed (typically only in tests that don’t wire the full startup pipeline).

This hands back an owned, independently mutable snapshot, which costs a deep clone of every config section; on request paths use config_arc instead.

Panics

Panics if the internal extension map mutex is poisoned, inherited from extension.

pub fn config_arc(&self) -> Arc<AutumnConfig>

Returns the resolved crate::config::AutumnConfig as a shared handle.

The cheap accessor: it clones only the Arc, never the configuration behind it, so callers pay a refcount bump instead of a deep copy of every config section. Prefer this over config on request paths, and reach for config() only when an owned, independently mutable snapshot is genuinely needed.

When no config extension has been installed (typically only in tests that don’t wire the full startup pipeline) this yields a handle to a shared default-valued config, so the fallback is free too. That fallback is never written back into the extension map, so a config installed afterwards is still observed.

Panics

Panics if the internal extension map mutex is poisoned, inherited from extension.

pub const fn probes(&self) -> &ProbeState

Returns the shared probe lifecycle state.

pub fn mark_startup_complete(&self)

Mark startup as complete so readiness can become healthy.

pub fn begin_shutdown(&self)

Mark the application as draining so readiness flips unhealthy.

pub fn with_pool(self, pool: Pool<RuntimeConnection>) -> Self

Sets the database pool.

pub fn with_replica_pool(self, pool: Pool<RuntimeConnection>) -> Self

Sets the read-replica database pool.

pub fn with_shards(self, shards: ShardSet) -> Self

Sets the shard set.

pub fn with_extension<T>(self, value: T) -> Self

where T: Any + Send + Sync + 'static,

Install a typed runtime extension while building test or ad-hoc state.

pub fn cache(&self) -> Option<Arc<dyn Cache>>

Returns the registered global cache backend, if any.

Checks the extension map first (populated at runtime by startup hooks via Self::set_cache) so that a plugin replacing a build-time backend is always visible. Falls back to shared_cache (set at build time via Self::with_cache).

pub fn with_cache(self, cache: Arc<dyn Cache>) -> Self

Register a global cache backend (builder / test helper, build-time).

pub fn clock(&self) -> &dyn ClockSource

Returns the active clock source wired into this state.

Handlers should prefer the crate::time::Clock extractor; this accessor exists for framework internals (middleware, storage) that need the time without going through Axum’s extractor machinery.

pub fn with_clock(self, clock: Arc<dyn ClockSource>) -> Self

Replace the clock (builder / test helper).

Also re-stamps the app’s start instant from the new clock, so uptime is measured on the timeline that is actually installed. Without this, a state built with the default SystemClock and then handed a virtual clock would compare a virtual now against a real origin and report a nonsense uptime.

A construction-time builder: it also gives the state a fresh job registry on clock, so a state’s clock and the queue gauges judged by it can never belong to different timelines. A state cloned before this call keeps its own clock and its own registry, equally consistent — the two simply stop sharing queue gauges from here on.

Call this before starting a job runtime

Once job::start_runtime has run, the runtime holds its own clone of the registry and keeps recording into it, and no behaviour here is correct:

if with_clock …	then
re-clocks this handle only	the runtime’s clone judges shared marks on the old clock
re-clocks a shared cell	the runtime stamps with the old clock into gauges moved to the new one
takes a fresh registry (what it does)	the runtime keeps writing to the old one, and this state’s gauges stay empty

The operation is simply not meaningful after initialization, so rather than pick the least-bad wrong answer this asserts in debug builds and logs at error in release. It is not silently tolerated.

pub fn monotonic(&self) -> MonotonicInstant

Returns the current instant on the injected clock’s monotonic timeline — the deterministic replacement for std::time::Instant::now when measuring how long something took.

Framework internals and app code alike should bracket work with two of these and take the difference via MonotonicInstant::saturating_duration_since. Handlers can reach the same value through the crate::time::Clock extractor’s monotonic.

pub fn entropy(&self) -> &dyn Entropy

Returns the active entropy source wired into this state.

Handlers should prefer the crate::entropy::Rng extractor; this accessor exists for framework internals (id-minting subsystems) that need randomness without going through Axum’s extractor machinery.

pub fn with_entropy(self, entropy: Arc<dyn Entropy>) -> Self

Replace the entropy source (builder / simulation helper).

Pass a crate::entropy::SeededEntropy to make every framework-minted identifier reproducible under a fixed seed. Mirrors Self::with_clock.

pub fn set_cache(&self, cache: Arc<dyn Cache>)

Install or replace the global cache backend at runtime (e.g. from a startup hook).

Updates both the process-level global (used by #[cached] functions) and the extension map (used by CacheResponseLayer::from_app and state.cache()).

pub fn with_profile(self, profile: impl Into<String>) -> Self

Sets the active profile.

pub const fn policy_registry(&self) -> &PolicyRegistry

Returns a reference to the PolicyRegistry.

pub fn policy<R: Send + Sync + 'static>(&self) -> Option<Arc<dyn Policy<R>>>

Resolve the registered Policy for resource R, if any.

pub fn scope<R: Send + Sync + 'static>(&self) -> Option<Arc<dyn Scope<R>>>

Resolve the registered Scope for resource R, if any.

pub const fn forbidden_response(&self) -> ForbiddenResponse

Configured deny-response shape. See ForbiddenResponse for the trade-off between 403 and 404 defaults.

pub fn auth_session_key(&self) -> &str

Session key used to resolve the authenticated user id for PolicyContext.

pub fn profile(&self) -> &str

Returns the active profile name, or "default" if none is set.

pub const fn role(&self) -> ProcessRole

Returns the resolved ProcessRole for this replica.

This is the role after config parsing and the AUTUMN_ROLE env override — the exact same value the framework uses to gate the job runtime, scheduler, and commit-hook worker. Use it from state_initializer, on_startup/on_shutdown hooks, plugins, and request handlers to self-gate app-owned background work:

if state.role().runs_workers() {
    // start an embedded worker loop only on replicas that run workers
}

serves_http and runs_workers are reachable on the returned value.

pub fn uptime(&self) -> Duration

Returns how long the application has been running.

Measured on the injected clock’s monotonic timeline, so it is immune to wall-clock jumps in production and moves with Sim::advance under a #[sim_test].

pub fn uptime_display(&self) -> String

Format uptime as a human-readable string (e.g., “2h 15m”).

pub const fn channels(&self) -> &Channels

Returns a reference to the broadcast channel registry.

Shorthand for accessing self.channels directly.

pub fn broadcast(&self) -> Broadcast

Returns a high-level broadcast facade for raw and htmx HTML payloads.

pub fn shutdown_token(&self) -> CancellationToken

Returns a child cancellation token for the server shutdown signal.

WebSocket handlers and the crate::extract::ShutdownToken extractor use it. Select on it to clean up when the server stops.

pub fn detached() -> Self

Create a minimal detached AppState without an HTTP server.

This is useful for background runtimes or helper processes that still need framework-managed resources such as typed extensions, metrics, or WebSocket channel registries.

pub fn for_test() -> Self

Create an AppState suitable for testing, with sensible defaults for all fields. Database pool is None.

Trait Implementations

impl Clone for AppState

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl DbState for AppState

Available on crate feature db only.

fn clock(&self) -> Arc<dyn ClockSource>

Returns the app’s injected clock, used to time connection checkouts and individual statements.

fn metrics(&self) -> Option<&MetricsCollector>

Returns the metrics collector, if configured.

fn pool(&self) -> Option<&Pool<RuntimeConnection>>

Returns the database connection pool, if configured.

fn replica_pool(&self) -> Option<&Pool<RuntimeConnection>>

Returns the read/replica connection pool, if configured.

fn db_capture_gap(&self) -> Option<Arc<str>>

Why failure-capsule capture cannot record this app’s database traffic, when its pool topology carries a gap (see DatabaseTopology::capture_gap). Defaults to None: the pools record, or capture is off entirely.

fn read_pool(&self) -> Option<&Pool<RuntimeConnection>>

Returns the pool used for read-only work.

fn shards(&self) -> Option<&ShardSet>

Returns the configured shard set, when [[database.shards]] entries exist. Defaults to None so unsharded states need no changes.

fn db_interceptors(&self) -> Vec<Arc<dyn DbConnectionInterceptor>>

Returns any registered database connection checkout interceptors.

fn statement_timeout(&self) -> Option<Duration>

Returns the global statement timeout, if configured.

fn idle_in_transaction_timeout(&self) -> Option<Duration>

Returns the global idle_in_transaction_session_timeout, if configured (#3057).

fn slow_query_threshold(&self) -> Duration

Returns the slow query threshold.

impl Debug for AppState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromRequest<AppState> for SignedWebhook

type Rejection = AutumnError

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request( req: Request, state: &AppState, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl FromRequestParts<AppState> for Impersonation

type Rejection = !

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( parts: &mut Parts, state: &AppState, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl FromRequestParts<AppState> for AutumnConfig

type Rejection = AutumnError

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( _parts: &mut Parts, state: &AppState, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl FromRequestParts<AppState> for Rng

type Rejection = !

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( _parts: &mut Parts, state: &AppState, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl FromRequestParts<AppState> for ShutdownToken

type Rejection = !

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( _parts: &mut Parts, state: &AppState, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl FromRequestParts<AppState> for Mailer

type Rejection = AutumnError

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( _parts: &mut Parts, state: &AppState, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl FromRequestParts<AppState> for ShardedDb

type Rejection = AutumnError

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( parts: &mut Parts, state: &AppState, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl FromRequestParts<AppState> for ShardedReadDb

type Rejection = AutumnError

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( parts: &mut Parts, state: &AppState, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl FromRequestParts<AppState> for Client

type Rejection = !

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( _parts: &mut Parts, state: &AppState, ) -> Result<Self, Infallible>

Perform the extraction.

impl FromRequestParts<AppState> for Notifications

type Rejection = !

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( _parts: &mut Parts, state: &AppState, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl FromRequestParts<AppState> for WebPush

type Rejection = !

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( _parts: &mut Parts, state: &AppState, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl FromRequestParts<AppState> for Sla

type Rejection = AutumnError

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( _parts: &mut Parts, state: &AppState, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl FromRequestParts<AppState> for Tenant

type Rejection = AutumnError

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( parts: &mut Parts, state: &AppState, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl FromRequestParts<AppState> for Clock

type Rejection = !

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( _parts: &mut Parts, state: &AppState, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl FromRequestParts<AppState> for TimeZone

type Rejection = !

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( parts: &mut Parts, state: &AppState, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl FromRequestParts<AppState> for Events

type Rejection = AutumnError

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( _parts: &mut Parts, state: &AppState, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl FromRequestParts<AppState> for Experiments

type Rejection = AutumnError

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( parts: &mut Parts, state: &AppState, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl FromRequestParts<AppState> for Flags

type Rejection = AutumnError

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( parts: &mut Parts, state: &AppState, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl FromRequestParts<AppState> for Outbox

type Rejection = AutumnError

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( _parts: &mut Parts, state: &AppState, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl ProvideActuatorState for AppState

fn shadow(&self) -> Option<ShadowHandle>

The shadow-mirroring handle, installed into the runtime extension map when the framework router assembled a mirror layer for this app.

Read from extensions rather than stored as an AppState field because the mirror is built during router assembly — after the state exists — and because an app that never enables [shadow] should carry no extra bytes for it.

fn metrics(&self) -> &MetricsCollector

Returns a reference to the crate::middleware::MetricsCollector tracking current HTTP traffic metrics.

fn log_levels(&self) -> &LogLevels

Returns a reference to the dynamic LogLevels configuration allowing runtime adjustment of tracing filters.

fn task_registry(&self) -> &TaskRegistry

Returns a reference to the TaskRegistry holding status and metadata for async scheduled background tasks.

fn job_registry(&self) -> &JobRegistry

Returns a reference to the JobRegistry holding queue and failure information for ad-hoc background jobs.

fn config_props(&self) -> &ConfigProperties

Returns a reference to the ConfigProperties snapshot, providing active configuration state for the environment endpoint.

fn profile(&self) -> &str

Returns the currently active execution profile (e.g. “dev”, “prod”) which modifies what sensitive endpoints are exposed.

fn uptime_display(&self) -> String

Returns a human-readable string displaying how long the application has been running (e.g., “2d 4h 13m”).

fn metrics_source_registry(&self) -> Option<&MetricsSourceRegistry>

Returns the registry of plugin-contributed MetricsSource implementations.

fn health_indicator_registry(&self) -> Option<&HealthIndicatorRegistry>

Returns the registry of HealthIndicator implementations.

fn health_detailed(&self) -> bool

Returns whether detailed health information should be included in responses.

fn architecture_graph_json(&self) -> Option<Bytes>

Returns the serialized architecture graph served at /actuator/graph.

fn data_capsules(&self) -> Result<CapsuleService, DataCapsuleError>

Returns the data-capsule service of {prefix}/capsules/* (issue #1811).

fn cost_signal(&self) -> Option<CostSignal>

Returns the cost signal (issue #1720). The default returns None.

fn cost_accountant(&self) -> Option<CostAccountant>

Returns the cost accountant (issue #1720). The default returns None, and {prefix}/cost then reports "enabled": false.

fn deploy_version(&self) -> String

Returns the deploy-version label for this replica (e.g. "stable" or "canary"), used to tag Prometheus metrics so a canary controller can compare canary vs. stable cohorts.

fn channels(&self) -> &Channels

Returns a reference to the system crate::channels::Channels which broadcasts operational events to WebSocket streams.

fn shutdown_token(&self) -> CancellationToken

Returns the main cancellation token that triggers a graceful framework shutdown.

fn pool(&self) -> Option<&Pool<RuntimeConnection>>

Returns an optional reference to the database connection pool, used to expose database connection metrics in the /actuator/metrics endpoint.

fn probe_state(&self) -> Option<&ProbeState>

Returns the probe state that holds the cached primary database ping.

fn shards(&self) -> Option<&ShardSet>

Returns the configured shard set, used to expose per-shard pool metrics in the /actuator/metrics endpoint. Defaults to None.

fn replica_pool(&self) -> Option<&Pool<RuntimeConnection>>

Returns the read-replica pool, used to export its gauges on /actuator/prometheus with pool="replica". Defaults to None.

fn webhook_outbound(&self) -> Option<WebhookOutboundManager>

Returns the optional webhook outbound manager if enabled/registered.

fn log_buffer(&self) -> Option<LogBuffer>

Returns the in-memory log capture buffer, if capture is enabled.

fn a11y_posture(&self) -> A11yPosture

Returns the scaffold-level accessibility posture reported by /actuator/a11y.

impl ProvideAuthorizationState for AppState

fn policy_registry(&self) -> &PolicyRegistry

fn auth_session_key(&self) -> &str

fn forbidden_response(&self) -> &ForbiddenResponse

fn pool(&self) -> Option<&Pool<RuntimeConnection>>

impl ProvideProbeState for AppState

fn probes(&self) -> &ProbeState

Returns a reference to the shared ProbeState that tracks lifecycle phases (startup, ready, draining).

fn health_detailed(&self) -> bool

Returns whether detailed health information (e.g., uptime, pool stats) should be included in the response.

fn profile(&self) -> &str

Returns the currently active execution profile (e.g. “dev”, “prod”).

fn uptime_display(&self) -> String

Returns a human-readable string displaying how long the application has been running (e.g., “2d 4h 13m”).

fn pool(&self) -> Option<&Pool<RuntimeConnection>>

Returns an optional reference to the database connection pool, used to evaluate database connectivity during a readiness check.

fn replica_pool(&self) -> Option<&Pool<RuntimeConnection>>

Returns an optional read-replica pool for readiness checks.

fn health_indicator_registry(&self) -> Option<&HealthIndicatorRegistry>

Returns the registry of crate::actuator::HealthIndicator implementations.

fn mark_startup_complete(&self)

Helper method to mark the application startup as complete.