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
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
//! 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());
//! # }
//! ```
//!