boson_axum/lib.rs
1//! HTTP admin API under `/api/boson`.
2//!
3//! Requires a booted [`boson_runtime::Boson`] — see
4//! [Getting started](https://docs.rs/uf-boson/latest/boson/index.html#getting-started) on the
5//! [`boson`](https://docs.rs/uf-boson) crate before mounting this router
6//! ([§ 5](https://docs.rs/uf-boson/latest/boson/index.html#5-mount-http-admin-optional)).
7//!
8//! ## Entry points
9//!
10//! - [`boson_router`] — mount under [`NEST_PATH`] (`/api/boson`)
11//! - [`BosonState`] — shared Axum state holding [`boson_runtime::Boson`]
12//!
13//! ## Handlers
14//!
15//! | Route | Module | Purpose |
16//! |-------|--------|---------|
17//! | `/tasks` | `handlers::tasks` | List and inspect registered tasks |
18//! | `/jobs` | `handlers::jobs` | Enqueue, list, cancel jobs |
19//! | `/runs` | `handlers::runs` | Inspect run history |
20//! | `/tasks/{name}/config` | `handlers::config` | Task config read/update (no `idempotency_mode`) |
21//! | `/tasks/{name}/config/revisions` | `handlers::config` | **Stub** — always returns `[]`; revision history not implemented |
22//!
23//! See `examples/axum_admin.rs` in the `boson` crate for a runnable server.
24//!
25//! ## Example
26//!
27//! ```rust,no_run
28//! use std::sync::Arc;
29//!
30//! use axum::{extract::FromRef, Router};
31//! use boson_axum::{boson_router, BosonState, NEST_PATH};
32//! use boson_runtime::Boson;
33//!
34//! #[derive(Clone)]
35//! struct AppState {
36//! boson: BosonState,
37//! }
38//!
39//! impl FromRef<AppState> for BosonState {
40//! fn from_ref(state: &AppState) -> Self {
41//! state.boson.clone()
42//! }
43//! }
44//!
45//! fn mount(boson: Boson) -> Router<AppState> {
46//! Router::new()
47//! .nest(NEST_PATH, boson_router())
48//! .with_state(AppState {
49//! boson: BosonState::new(Arc::new(boson)),
50//! })
51//! }
52//! ```
53
54mod handlers;
55mod router;
56mod state;
57
58pub use router::{boson_router, NEST_PATH};
59pub use state::BosonState;