Crate mlua_swarm_server

Expand description

the server lib: axum Router + handler set. Split out as a library so it can be used from both main.rs (CLI) and integration tests.

§Endpoints

GET /v1/healthz
POST /v1/sessions / DELETE /v1/sessions (= operator attach / detach, Bearer sid)
POST /v1/tasks (= unified Flow-form entry, Operator inject supported; operator_sid explicitly pins the task to a registered Operator session, S2)
POST /v1/operators / GET /v1/operators/:sid / DELETE /v1/operators/:sid / GET /v1/operators/:sid/ws (WS upgrade) — REST-like Operator login flow, Bearer-mandatory; the sole WS Operator session route. See operator_ws::login module doc.

The Enhance issue axis (/issues) lives in the issues module; callers merge build_issues_router to integrate it into the same server.

§The 3 faces of the Operator role (= registered directly on the engine SoT)

The engine stateless-executor refactor removed the three AppState registries (former HookRegistry / BridgeRegistry / OperatorRegistry); all registration now goes directly to the engine SoT via engine.register_spawn_hook / register_senior_bridge / register_operator. WSOperatorSession (in the operator_ws module) registers all three traits simultaneously under a single sid — one WS connection covers all 3 faces of the Operator role, the canonical pattern.

§`build_*` family

build_router — minimal entry (= default_registry())
build_router_with — caller provides a SpawnerRegistry and optional BlueprintStore

The engine should be started with default_layer_registry (= Engine::new_with_layers); otherwise Blueprint.spawner_hints is ignored.

Re-exports§

pub use blueprints::build_blueprints_router;
pub use blueprints::build_blueprints_router_with_refs;
pub use enhance_log::build_enhance_log_router;
pub use enhance_settings::build_enhance_settings_router;
pub use issues::build_issues_router;
pub use issues::GetIssueResponse;
pub use issues::PostIssueRequest;
pub use issues::PostIssueResponse;
pub use operator_ws::operators_create;
pub use operator_ws::operators_delete;
pub use operator_ws::operators_info;
pub use operator_ws::operators_ws_connect;
pub use operator_ws::ClientMsg;
pub use operator_ws::OperatorSessionEntry;
pub use operator_ws::ServerMsg;
pub use operator_ws::WSOperatorSession;
pub use worker::worker_prompt;
pub use worker::worker_result;
pub use worker::PromptQuery;
pub use worker::WorkerResultReq;

Modules§

blueprints: HTTP surface for inspecting/registering Blueprint state (/v1/blueprints/*). HTTP surface for inspecting Blueprint state (= for debug / animation verification). /v1/blueprints/:id/head returns the head Blueprint JSON; /v1/blueprints/:id/history returns the commit-version list. Callers pass a shared Store via Arc and mount the router.
config: Server config file support (~/.mse/config.toml, CLI > file > default merge). Server config file support (~/.mse/config.toml by default).
data: /v1/data/* endpoints (v9 Big Response handling, Store-owner direct path). HTTP /v1/data/* endpoints (v9 Data path, for Big Response handling).
doctor: GET /v1/doctor — read-only startup config / Store snapshot. GET /v1/doctor — server-side infra info snapshot.
enhance_log: HTTP surface for the /v1/enhance/log axis. HTTP surface for the /v1/enhance/log axis.
enhance_settings: EnhanceSetting HTTP CRUD (/v1/enhance-settings*). EnhanceSetting HTTP CRUD (= K-V store entry + BPStore commit orchestration).
issues: HTTP surface for the Enhance issue axis (/v1/issues*). HTTP surface for the Enhance issue axis (current design).
operator_ws: WebSocket Operator Callback IF (/v1/operators*).
worker: /v1/worker/* endpoints (SubAgent self-fetch path). HTTP /v1/worker/* endpoints (SubAgent self-fetch path).

Structs§

ApiError: Uniform error response type for the handlers in this module. Converts to a JSON {"error": message} body with the given status via IntoResponse.
AppState: Shared axum handler state for the whole router. Cloned per-request (all fields are Arc/cheap-clone), constructed once in build_router_with_ws_factory.
SessionStore: In-memory sid → CapToken map backing /v1/sessions attach/detach.

Functions§

build_router: Minimal entry point: builds a router with default_registry and no BlueprintStore (Inline-only mode) or ws_operator_factory.
build_router_with: Build form where the caller supplies a registry and an optional BlueprintStore. The Operator callback path (= external HTTP / WS callers acting as an Operator) must be pre-registered via engine.register_* (= the engine is the SoT). See the operator_ws module doc and OperatorInfo (engine-side ctx.rs) for details.
build_router_with_ws_factory: 4-argument variant of build_router_with. Passing ws_operator_factory = Some(arc) causes each WS connect to auto-register a new WSOperatorSession under its sid name with the factory (= a kind=operator AgentDef with operator_ref: <sid> can then bind to the WS client backend). Callers are expected to also install the same Arc into the SpawnerRegistry via reg.register::<OperatorSpawnerFactory>(arc.clone()).
build_router_with_ws_factory_and_output: 5-argument variant of build_router_with_ws_factory. Passing output_store = Some(arc) swaps the default InMemoryOutputStore for a caller-supplied backend (a SqliteOutputStore, for instance). None preserves the historical behaviour (fresh in-memory store per call).
default_layer_registry: Default LayerRegistry for the server. Hint keys:
default_registry: Default registry = Subprocess + RustFn (baseline identity worker pre-baked) + empty Operator factory.
default_registry_with_enhance_flow: Opt-in registry that merges default_registry with the enhance flow (Lua factory + AgentBlock factory).