footing 0.6.1

Feature-gated foundations for Rust backend services
Documentation
//! Shared Rust service foundation for application backends.
//!
//! `footing` is intentionally small and feature-gated. It collects reusable
//! infrastructure concerns such as principal authorization, password storage,
//! pagination, HTTP request context, RFC 9457 problem responses, database pool
//! configuration, and tracing setup without depending on an application's domain
//! model.
//!
//! # Feature layout
//!
//! No features are enabled by default. Enable only the capabilities needed by
//! your application; feature dependencies are enabled automatically.
//!
//! - `serde`: serialization support shared by higher-level capabilities.
//! - `auth`: principals, roles, scopes, and permission guards.
//! - `password`: Argon2id password hashing built on top of `auth`.
//! - `password-policy`: synchronous new-password admission rules, independent of
//!   password hashing and login verification; implies `auth`.
//! - `password-common`: bundled common-password list for explicit use by a
//!   `PasswordPolicy`; implies `password-policy`, without Argon2 or Tokio.
//! - `password-tokio`: bounded Tokio scheduling for password work, with shared
//!   concurrency and queue limits; implies `password` and `secrets`.
//! - `net`: IP network parsing and matching primitives.
//! - `pagination`: cursor and offset pagination primitives; adds HTTP extractors
//!   when `http` is also enabled.
//! - `http`: Axum request context, safe extractors, problem responses, trusted
//!   proxies, browser origin checks, security headers, and endpoint contracts.
//! - `http-stack`: complete HTTP middleware assembly, concurrency limits, rate
//!   limiting, idempotency, metrics, and health responses; implies `http`,
//!   `pagination`, `settings`, and `observability`.
//! - `http-cookie`: validated cookie policies, unambiguous credential reads, and
//!   consistent issuance/removal; implies `http`, `settings`, and `secrets`.
//! - `http-static`: filesystem-backed static sites and explicit SPA fallback;
//!   implies `http`, without OpenAPI or embedded frontend assets.
//! - `openapi`: OpenAPI schemas, documented routes, and documentation pages with
//!   an explicitly selected renderer and asset source; no embedded UI bundle or
//!   middleware stack. Pagination adapters require `pagination`.
//! - `redoc-embedded`: fixed, self-contained ReDoc assets; implies `openapi`.
//! - `rapidoc-embedded`: fixed RapiDoc assets; implies `openapi`.
//! - `settings`: human-readable duration and component settings validation.
//! - `tier`: optional Tier metadata and validation adapters.
//! - `postgres`: SQLx PostgreSQL pool and startup helpers.
//! - `postgres-admin`: explicitly gated destructive PostgreSQL administration.
//! - `presence-postgres`: shared, heartbeat-based online user queries in PostgreSQL.
//! - `presence-sqlite`: heartbeat-based online user queries in a local SQLite database.
//! - `sqlite`: SQLx SQLite pool and startup helpers.
//! - `observability`: health, metrics, and tracing subscriber helpers.
//! - `worker`: background worker, lease, and outbox primitives.
//! - `runtime`: ordered application lifecycle orchestration.
//! - `secrets`: redacted secret values and secret sources.
//! - `crypto`: secure tokens and small cryptographic helpers.
//! - `diagnostics`: startup resource probes and readiness diagnostics.
//! - `event`: in-process domain event dispatch and hooks.
//! - `tls`: outbound TLS trust store configuration and loading.
//! - `tls-reqx`: Reqx adapter for the validated TLS trust configuration.
//! - `time`: UTC wall-clock abstractions and timestamp support.
//! - `testkit`: fixtures, HTTP helpers, and test assertions.
//!
//! # Examples
//!
//! Principal checks:
//!
//! ```rust
//! # #[cfg(feature = "auth")]
//! # {
//! use footing::auth::{Principal, PrincipalRequirement};
//!
//! let principal = Principal::user("usr_01")
//!     .unwrap()
//!     .with_scopes(["users:*"])
//!     .unwrap();
//! PrincipalRequirement::scope("users:read")
//!     .unwrap()
//!     .check(&principal)
//!     .unwrap();
//! # }
//! ```
//!
//! Password hashing:
//!
//! ```rust
//! # #[cfg(feature = "password")]
//! # {
//! use footing::auth::PasswordService;
//!
//! let service = PasswordService::new();
//! let hash = service.hash_password("correct horse battery staple").unwrap();
//! let verification = service
//!     .verify_and_assess("correct horse battery staple", &hash)
//!     .unwrap();
//!
//! assert!(verification.verified());
//! assert!(!verification.needs_rehash());
//! # }
//! ```
//!
#![forbid(unsafe_code)]
#![deny(missing_docs)]
#![cfg_attr(
    not(test),
    deny(
        clippy::expect_used,
        clippy::dbg_macro,
        clippy::panic,
        clippy::todo,
        clippy::unimplemented,
        clippy::unreachable,
        clippy::unwrap_used
    )
)]
#![warn(rustdoc::broken_intra_doc_links)]
#![cfg_attr(docsrs, feature(doc_cfg))]

#[cfg(any(feature = "crypto", feature = "pagination"))]
mod signing;

#[cfg(any(feature = "worker", feature = "postgres"))]
mod jitter;

#[cfg(any(feature = "diagnostics", feature = "observability", feature = "event"))]
mod text;

#[cfg(feature = "auth")]
#[cfg_attr(docsrs, doc(cfg(feature = "auth")))]
pub mod auth;
pub mod clock;
#[cfg(feature = "crypto")]
#[cfg_attr(docsrs, doc(cfg(feature = "crypto")))]
pub mod crypto;
#[cfg(any(feature = "postgres", feature = "sqlite"))]
#[cfg_attr(docsrs, doc(cfg(any(feature = "postgres", feature = "sqlite"))))]
pub mod db;
#[cfg(feature = "diagnostics")]
#[cfg_attr(docsrs, doc(cfg(feature = "diagnostics")))]
pub mod diagnostics;
#[cfg(feature = "event")]
#[cfg_attr(docsrs, doc(cfg(feature = "event")))]
pub mod event;
#[cfg(feature = "http")]
#[cfg_attr(docsrs, doc(cfg(feature = "http")))]
pub mod http;
#[cfg(feature = "net")]
#[cfg_attr(docsrs, doc(cfg(feature = "net")))]
pub mod net;
#[cfg(feature = "observability")]
#[cfg_attr(docsrs, doc(cfg(feature = "observability")))]
pub mod observability;
#[cfg(feature = "pagination")]
#[cfg_attr(docsrs, doc(cfg(feature = "pagination")))]
pub mod pagination;
#[cfg(any(feature = "presence-postgres", feature = "presence-sqlite"))]
#[cfg_attr(
    docsrs,
    doc(cfg(any(feature = "presence-postgres", feature = "presence-sqlite")))
)]
pub mod presence;
pub mod result;
#[cfg(feature = "runtime")]
#[cfg_attr(docsrs, doc(cfg(feature = "runtime")))]
pub mod runtime;
#[cfg(feature = "secrets")]
#[cfg_attr(docsrs, doc(cfg(feature = "secrets")))]
pub mod secret;
#[cfg(feature = "settings")]
#[cfg_attr(docsrs, doc(cfg(feature = "settings")))]
pub mod settings;
#[cfg(feature = "testkit")]
#[cfg_attr(docsrs, doc(cfg(feature = "testkit")))]
#[allow(
    clippy::expect_used,
    clippy::panic,
    clippy::todo,
    clippy::unimplemented,
    clippy::unreachable,
    clippy::unwrap_used
)]
pub mod testkit;
#[cfg(feature = "tls")]
#[cfg_attr(docsrs, doc(cfg(feature = "tls")))]
pub mod tls;
#[cfg(feature = "worker")]
#[cfg_attr(docsrs, doc(cfg(feature = "worker")))]
pub mod worker;