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 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 const fn pool(&self) -> Option<&Pool<AsyncPgConnection>>

Returns the database connection pool.

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

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

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

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 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<AsyncPgConnection>) -> Self

Sets the database pool.

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

Sets the read-replica database pool.

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 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 fn uptime(&self) -> Duration

Returns how long the application has been running.

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 should select on this to clean up when the server is shutting down.

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) -> AppState

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 pool(&self) -> Option<&Pool<AsyncPgConnection>>

Returns the database connection pool, if configured.

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

Returns the read/replica connection pool, if configured.

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

Returns the pool used for read-only work.

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 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 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 ProvideActuatorState for AppState

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 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<AsyncPgConnection>>

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

fn a11y_posture(&self) -> A11yPosture

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

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<AsyncPgConnection>>

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

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

Returns an optional read-replica pool for readiness checks.

fn mark_startup_complete(&self)

Helper method to mark the application startup as complete.