arcature 2026.2.1

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

//! The health-check router and lifecycle layer (AP2.1-10).
//!
//! [`router`] returns a stateless [`axum::Router<()>`] — standalone-first
//! (AGENTS.md §16): an expert user mounts it on their own Axum app without a
//! runtime dependency on `arcature` beyond the [`Lifecycle`] handle. The
//! handlers ([`super::live`], [`super::ready`]) read the [`Lifecycle`] from an
//! Axum [`axum::Extension`] layer installed via [`lifecycle_layer`], so the
//! health router composes with any application state type `S` — it does not
//! require the app state to carry the lifecycle, and merging it into a
//! stateful router does not change the app's state type.
//!
//! The orchestrated paths ([`crate::Application::serve_with_health`] /
//! [`crate::Application::run_with_health`]) merge this router into the
//! application's routes before serving, installing [`lifecycle_layer`] so
//! the health handlers observe the same [`Lifecycle`] the orchestration
//! drives.

use crate::application::lifecycle::Lifecycle;
use crate::axum::Extension;
use crate::axum::Router;
use crate::routing::get;

/// The liveness path (`/up/live`).
pub const LIVE_PATH: &str = "/up/live";
/// The readiness path (`/up/ready`).
pub const READY_PATH: &str = "/up/ready";

/// Build the health router: `/up/live` and `/up/ready`, stateless (`()`)
/// so it composes with any application state via a merge/nest.
///
/// The handlers read the [`Lifecycle`] from an Axum [`Extension`]; install
/// [`lifecycle_layer`] on the router that serves this (or the merged app
/// router) so the handlers observe the live [`Lifecycle`].
///
/// Returns a raw [`axum::Router<()>`] — an expert user mounts it directly:
///
/// ```ignore
/// use arcature::health::router;
/// use arcature::Lifecycle;
///
/// let lifecycle = Lifecycle::new();
/// let health = router();
/// // mount `health` and layer the lifecycle onto your app, e.g.:
/// // Router::new().merge(health).layer(arcature::health::lifecycle_layer(lifecycle))
/// ```
pub fn router() -> Router<()> {
    Router::new()
        .route(LIVE_PATH, get(super::live::live))
        .route(READY_PATH, get(super::ready::ready))
}

/// The Axum layer that installs `lifecycle` into every request's extensions
/// so the [`router`] handlers (and any app handler that takes
/// `Extension<Lifecycle>`) can read it. Public so an expert user mounting
/// the health router on their own app wires the same lifecycle. `Extension`
/// implements `tower_layer::Layer`, so it is used directly as a layer.
///
/// `Extension<Lifecycle>` is already `#[must_use]` (axum), so the returned
/// layer is flagged if dropped — no redundant attribute here.
pub fn lifecycle_layer(lifecycle: Lifecycle) -> Extension<Lifecycle> {
    Extension(lifecycle)
}