Crate boson_axum 

HTTP admin API under /api/boson.

Requires a booted boson_runtime::Boson — see Getting started on the boson crate before mounting this router (§ 5).

Entry points

• boson_router — mount under NEST_PATH (/api/boson)
• BosonState / BosonStateBuilder — shared Axum state, optional AdminAuth
• AdminAuth, StaticTokenAdminAuth, REQUIRE_ADMIN_AUTH_ENV — host auth seam
• MAX_LIST_LIMIT — hard cap for list query limit

Owns / does not own

Owns: route table, DTO shaping (no actor_json / params_json on wire), list caps, default non-System HTTP enqueue actor, optional admin auth middleware.

Does not own: Soliton HMAC, mTLS, session cookies — hosts implement AdminAuth.

Handlers

Route	Module	Purpose
/tasks	handlers::tasks	List and inspect registered tasks
/jobs	handlers::jobs	Enqueue, list, cancel jobs
/runs	handlers::runs	Inspect run history
/tasks/{name}/config	handlers::config	Task config read/update (no idempotency_mode)
/tasks/{name}/config/revisions	handlers::config	Stub — always returns []; revision history not implemented

See examples/axum_admin.rs in the boson crate for a runnable server.

Example — completed setup with admin auth

use std::sync::Arc;

use axum::{extract::FromRef, Router};
use boson_axum::{
    boson_router, BosonAxumError, BosonState, StaticTokenAdminAuth, NEST_PATH,
};
use boson_runtime::Boson;

#[derive(Clone)]
struct AppState {
    boson: BosonState,
}

impl FromRef<AppState> for BosonState {
    fn from_ref(state: &AppState) -> Self {
        state.boson.clone()
    }
}

fn mount(boson: Boson) -> Result<Router<AppState>, BosonAxumError> {
    let state = BosonState::builder(Arc::new(boson))
        .admin_auth(Arc::new(StaticTokenAdminAuth::new("lab-token")))
        .require_admin_auth(true)
        .build()?;
    Ok(Router::new()
        .nest(NEST_PATH, boson_router())
        .with_state(AppState { boson: state }))
}

Structs

AdminAuthError

Rejection from AdminAuth::authorize.

AllowAllAdminAuth

Shared always-allow verifier for local tests (not for production).

BosonState

Extractable state holding a Boson runtime and optional admin auth.

BosonStateBuilder

Build BosonState with admin auth and actor overrides.

RequireAdmin

Extractor that enforces BosonState::admin_auth / require-flag before the handler runs.

StaticTokenAdminAuth

Header-based verifier: require x-boson-admin-token equal to the configured secret.

Enums

BosonAxumError

Errors from BosonStateBuilder::build.

Constants

DEFAULT_LIST_LIMIT

Default limit when the query omits it.

MAX_LIST_LIMIT

Hard maximum rows returned by list endpoints.

MAX_RETRY_ATTEMPTS

Maximum RetryPolicy::max_attempts accepted via HTTP config upsert.

MAX_RETRY_DELAY_MS

Maximum retry delay via HTTP (milliseconds).

MIN_RETRY_DELAY_MS

Minimum base_delay_ms / max_delay_ms via HTTP (milliseconds).

NEST_PATH

Nest path for the Boson API router (/api/boson).

REQUIRE_ADMIN_AUTH_ENV

Environment variable: when 1/true/yes, admin routes require a configured AdminAuth.

Traits

AdminAuth

Host-supplied verifier for Boson admin HTTP.

Functions

boson_router

Create the Boson API router (mount at NEST_PATH).

clamp_list_limit

Clamp an optional list limit into [1, MAX_LIST_LIMIT] (default DEFAULT_LIST_LIMIT).

clamp_retry_policy

Validate and clamp retry policy fields for HTTP upsert.

parse_require_admin_auth

Parse a require-admin-auth flag string (1 / true / yes, case-insensitive).

require_admin_auth_from_env

Read REQUIRE_ADMIN_AUTH_ENV: 1, true, or yes (case-insensitive) ⇒ required.

Type Aliases

HttpEnqueueActorProvider

Callback that supplies actor_json for HTTP enqueue (overrides the default service marker).