1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
//! 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-metrics`: independent HTTP metrics middleware, optional response-body
//! observations, and Prometheus/OpenMetrics responses; implies `http` and
//! `observability`.
//! - `http-stack`: complete HTTP middleware assembly, concurrency limits, rate
//! limiting, idempotency, metrics, and health responses; implies `http-metrics`,
//! `pagination`, and `settings`.
//! - `http-cookie`: validated cookie policies, unambiguous credential reads, and
//! consistent issuance/removal; implies `http`, `settings`, and `secrets`.
//! - `http-locale`: bounded language negotiation, request-scoped selections, and
//! localized response headers; implies `http`, without a translation engine.
//! - `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());
//! # }
//! ```
//!