arcature 2026.2.0

Arcature application framework: a high-level Application facade over the certified Arcature subsystems, with the low-level Axum/Tower escape hatch preserved.
Documentation 
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

// The high-level Application engine (engine phase). One responsibility per
// file (AGENTS.md §1). `mod.rs` declares child modules and re-exports the
// public surface; it contains no business logic.

mod builder;
mod error;
// AP2.1-10: the production lifecycle state machine, readiness gates, and
// drain hooks. The state machine is pure `std` (atomic + `Arc`) so it
// compiles with no feature flags; the `signal` sub-module is `macros`-gated
// internally. An expert user on a custom runtime can build a `Lifecycle` and
// mount the framework's `crate::health` routes; the orchestrated paths
// (`serve_with_health` / `run_with_health`) tie it to the certified Tokio
// runtime and the engine's subsystem startup/shutdown.
pub mod lifecycle;
// Lifecycle modules need the `macros` runtime + at least one lifecycle
// subsystem. Under `macros`-alone the `Resources` struct is empty and
// `startup`/`shutdown` are no-ops; the plain `run` path is correct there.
#[cfg(feature = "jobs")]
mod jobs_registry;
// Lifecycle modules need the `macros` runtime + at least one lifecycle
// subsystem. Under `macros`-alone the `Resources` struct is empty and
// `startup`/`shutdown` are no-ops; the plain `run` path is correct there.
mod into_router;
#[cfg(all(
    feature = "macros",
    any(
        feature = "db",
        feature = "cache",
        feature = "storage",
        feature = "mail",
        feature = "jobs"
    )
))]
mod resources;
mod serve;
// AP2.1-10: the health-managed serve path (testable lifecycle entry point).
// Gated like `serve_with_lifecycle` — needs the `macros` runtime + at
// least one lifecycle subsystem feature (db/cache/storage/mail/jobs).
#[cfg(all(
    feature = "macros",
    any(
        feature = "db",
        feature = "cache",
        feature = "storage",
        feature = "mail",
        feature = "jobs"
    )
))]
mod serve_with_health;
#[cfg(all(
    feature = "macros",
    any(
        feature = "db",
        feature = "cache",
        feature = "storage",
        feature = "mail",
        feature = "jobs"
    )
))]
mod serve_with_lifecycle;
#[cfg(all(
    feature = "macros",
    any(
        feature = "db",
        feature = "cache",
        feature = "storage",
        feature = "mail",
        feature = "jobs"
    )
))]
pub(crate) mod shutdown;
#[cfg(all(
    feature = "macros",
    any(
        feature = "db",
        feature = "cache",
        feature = "storage",
        feature = "mail",
        feature = "jobs"
    )
))]
pub(crate) mod startup;
mod ty;

// `run` binds a `TcpListener` on the certified Tokio runtime; gated by the
// `macros` feature, which brings in `tokio` (net + signal). An expert user
// without `macros` still serves via `Application::serve` on their own runtime.
#[cfg(feature = "macros")]
mod run;
// AP2.1-10: the health-managed run path (production default). Gated like
// `run_with_lifecycle` — needs the `macros` runtime + at least one
// lifecycle subsystem feature (db/cache/storage/mail/jobs). Under
// `macros`-alone the `Resources` type is empty and the plain `run` path is
// the correct entry point.
#[cfg(all(
    feature = "macros",
    any(
        feature = "db",
        feature = "cache",
        feature = "storage",
        feature = "mail",
        feature = "jobs"
    )
))]
mod run_with_health;
// `run_with_lifecycle` needs the `macros` runtime + at least one lifecycle
// subsystem feature (db/cache/storage/mail/jobs). Under `macros`-alone the
// `Resources` type is empty and the lifecycle is a no-op — the plain `run`
// path is the correct entry point there.
// `run_factory` produces the `arcature::run()` bootstrap builder. It only
// matters for the `macros` runtime path (the golden path calls
// `.run_with_lifecycle`), so gate it to avoid dead code under the bare
// engine. The factory itself reads no `macros`-only types, but its only
// consumer is a `macros` application.
#[cfg(feature = "macros")]
mod run_factory;
// `run_with_lifecycle` needs the `macros` runtime + at least one lifecycle
// subsystem feature (db/cache/storage/mail/jobs). Under `macros`-alone the
// `Resources` type is empty and the lifecycle is a no-op — the plain `run`
// path is the correct entry point there.
#[cfg(all(
    feature = "macros",
    any(
        feature = "db",
        feature = "cache",
        feature = "storage",
        feature = "mail",
        feature = "jobs"
    )
))]
mod run_with_lifecycle;

pub use builder::ApplicationBuilder;
pub use error::EngineError;
pub use error::Result;
// AP2.1-10: the production lifecycle handle and state machine. Always
// available (pure `std`); the orchestrated paths that use it with the
// certified Tokio runtime are `macros`-gated.
#[allow(unused_imports)]
pub use lifecycle::{DrainError, DrainHook, Lifecycle, LifecycleState, ReadinessCheck};
#[cfg(feature = "macros")]
pub use run_factory::run;
pub use ty::Application;
pub use ty::ProxyFn;

// Lifecycle types are only exported when the `macros` feature is on (the
// feature that brings the Tokio runtime + CancellationToken needed by
// `run_with_lifecycle`). Under `--no-default-features` these types have no
// use site — exporting them would be dead code.
//
// These re-exports are the public API surface for applications using
// `run_with_lifecycle`; clippy's `unused_imports` lint is suppressed because
// the imports are the API, not internal use sites.
#[cfg(all(
    feature = "macros",
    any(
        feature = "db",
        feature = "cache",
        feature = "storage",
        feature = "mail",
        feature = "jobs"
    )
))]
#[allow(unused_imports)]
pub use error::{ShutdownError, StartupError};
#[cfg(all(
    feature = "macros",
    any(
        feature = "db",
        feature = "cache",
        feature = "storage",
        feature = "mail",
        feature = "jobs"
    )
))]
pub use resources::Resources;