footing 0.6.5

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.
//!
//! For example, `http-stack` already includes `http` and `http-metrics`;
//! `password-tokio` includes `password` and `auth`. Features make APIs available;
//! applications explicitly install middleware, start workers, and initialize logs.
//!
//! ## HTTP
//!
//! | Feature | Capability and automatically enabled features |
//! | --- | --- |
//! | `http` | Axum request context, trusted proxies, safe extractors, problem responses, security headers, and endpoint contracts; enables `auth` and `net`. |
//! | `http-metrics` | Independent HTTP metrics, optional response-body observations, and Prometheus/OpenMetrics responses; enables `http` and `observability`. |
//! | `http-stack` | Middleware assembly, CORS, timeouts, concurrency, rate limiting, idempotency, metrics, and health responses; enables `http-metrics`, `pagination`, and `settings`. |
//! | `http-cookie` | Validated cookie policies, credential reads, and issuance/removal; enables `http`, `settings`, and `secrets`. |
//! | `http-locale` | Explicit language negotiation and response headers; enables `http`. |
//! | `http-static` | Filesystem-backed static sites and SPA fallback; enables `http`. |
//! | `http-client` | Reqx TLS trust integration; enables `tls`, independently of `http`. Applications declare Reqx and explicitly select its TLS backend. |
//! | `pagination` | Cursor and offset pagination; HTTP extractors are available with `http`. |
//! | `openapi` | Schemas, documented routes, and documentation pages; enables `http`. Renderer and asset source are selected explicitly. |
//! | `redoc-embedded`, `rapidoc-embedded` | Bundled documentation assets; each enables `openapi`. |
//!
//! ## Authentication and cryptography
//!
//! | Feature | Capability and automatically enabled features |
//! | --- | --- |
//! | `auth` | Principals, roles, scopes, permission guards, and explicit new-password admission checks; no password hashing or async runtime. |
//! | `password` | Argon2id password storage and verification; enables `auth`. Admission rules remain an explicit, separate call. |
//! | `password-common` | Bundled common-password list for explicit use by `PasswordPolicy`; enables `auth`, without Argon2 or Tokio. |
//! | `password-tokio` | Bounded Tokio scheduling for password work; enables `password` and `secrets`. |
//! | `crypto` | Secure tokens and cryptographic helpers; enables `secrets`. |
//!
//! ## Storage
//!
//! | Feature | Capability and automatically enabled features |
//! | --- | --- |
//! | `postgres` | SQLx PostgreSQL pools and startup helpers; enables `settings` and `secrets`. |
//! | `postgres-admin` | Destructive PostgreSQL administration; enables `postgres`. |
//! | `sqlite` | SQLx SQLite pools and startup helpers; enables `settings`. |
//! | `presence-postgres` | Shared heartbeat-based online user queries; enables `postgres` and `time`. |
//! | `presence-sqlite` | Online user queries in a local SQLite database; enables `sqlite` and `time`. |
//!
//! ## Runtime and observability
//!
//! | Feature | Capability and automatically enabled features |
//! | --- | --- |
//! | `runtime` | Ordered application lifecycle orchestration. |
//! | `worker` | Background workers, leases, and outbox primitives; enables `settings` and `observability`. |
//! | `event` | In-process domain event dispatch and hooks. |
//! | `diagnostics` | Startup resource probes and readiness diagnostics. |
//! | `observability` | Metrics, health reports, structured event values, and trace identifiers; no log subscriber or timestamp formatter. |
//! | `logging` | Log formatting, filters, and explicit subscriber initialization in `footing::logging`; independent of `observability`. |
//! | `testkit` | Fixtures and test assertions; enables `http` and `worker`. Intended for development dependencies. |
//!
//! ## Shared primitives and integrations
//!
//! | Feature | Capability |
//! | --- | --- |
//! | `serde` | Serialization support for the always-available result types. Enabled by higher-level capabilities as needed. |
//! | `settings` | Human-readable durations and component settings validation. |
//! | `tier` | Tier configuration metadata and validation adapters; enables `settings`. |
//! | `time` | UTC wall-clock abstractions using the `time` crate. |
//! | `net` | IP network parsing and matching. |
//! | `secrets` | Redacted secret values and secret sources. |
//! | `tls` | TLS trust configuration and certificate loading, independently of HTTP clients and crypto providers. |
//!
//! # 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 = "logging")]
#[cfg_attr(docsrs, doc(cfg(feature = "logging")))]
pub mod logging;
#[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;