apalis-rtui 0.1.0-rc.1

A drop-in replacement for apalis-board: HTTP surface, live updates, and the apalis-tui dashboard
Documentation

apalis-rtui

A drop-in replacement for apalis-board: the same JSON API, the same ServeUI/ApiBuilder module paths, and a ratatui-based dashboard compiled to WebAssembly in place of the old Leptos frontend.

Drop-in

Change one line in Cargo.toml:

# before
apalis-board = { version = "1.0.0-rc.8", features = ["axum"] }

# after
apalis-board = { package = "apalis-rtui", version = "0.1.0-rc.1", features = ["axum"] }

Every path already in use keeps working: apalis_board::axum::framework::{ApiBuilder, RegisterRoute}, apalis_board::axum::sse::{TracingBroadcaster, TracingSubscriber}, apalis_board::axum::ui::ServeUI, apalis_board::axum::push_task, and the rest of the framework-agnostic handler set. apalis-rtui reproduces that exact module shape under its own name too, so a consumer who prefers not to rename the dependency writes the same paths under apalis_rtui instead of apalis_board.

Features

Feature Default What it wires
axum off The axum HTTP surface: apalis_rtui::axum::*.
actix off The actix-web HTTP surface: apalis_rtui::actix::*.
events on The /events server-sent-events stream (TracingBroadcaster/TracingSubscriber). Named sse upstream.
ui off Serves the embedded apalis-tui web bundle via ServeUI.
web off Deprecated alias of ui, kept so a source tree written against apalis-board's web feature still compiles.

Pick axum or actix (or both) depending on the host framework, and turn on ui to also serve the dashboard itself.

Usage

use apalis_rtui::axum::{
    framework::{ApiBuilder, RegisterRoute},
    ui::ServeUI,
};
use axum::Router;

let app = ApiBuilder::new(Router::new())
    .register(notification_store) // Add backends
    .register(email_store)
    .build();

let ui = ServeUI::new().with_api_base("/api/v1");

Root routes and multiple backend instances

The root aggregate routes, /queues, /tasks, /workers, /overview, /capabilities, and /events*, are mounted only by the first register/register_shared call on an ApiBuilder. Every later call adds that backend's own per-queue routes but does not add it to those root routes.

This is fine when every queue shares one backend instance, for example one SqliteStorage pool registered once per queue. list_queues and the other root-route queries already see the whole shared database, so the root routes already cover every queue.

It matters when a host registers two independent backend instances, for example two separate in-memory stores or two separate connection pools with no shared state. Then /queues and the Overview reflect only the first instance registered, and the other queue is reachable through its own per-queue routes but invisible to the root ones. Two ways around it:

  • Give the backend's own list_queues (and the other root-route methods) a view that already spans every queue, the way a shared connection pool does.
  • Write a small wrapper type that implements the root-route traits by merging results from each instance, then register the wrapper once for the root routes. apalis-rtui/examples/custom-backend-dashboard.rs's RootView type is a worked example of this.

Live tracing events

let broadcaster = TracingBroadcaster::create();

let tracing_subscriber = TracingSubscriber::new(&broadcaster);
let tracing_layer = tracing_subscriber
    .layer()
    .with_filter(EnvFilter::builder().parse("debug").unwrap());

tracing_subscriber::registry().with(tracing_layer).init();

Visiting /api/v1/events on the mounted router streams the task logs this layer captures.

Serving the dashboard behind a different mount point

ServeUI templates its configured API base into the served index.html at request time, so the compiled dashboard discovers where the API actually lives without a rebuild:

let ui = ServeUI::new().with_api_base("/backend/api/v1");

Content-Security-Policy

No Content-Security-Policy header is sent unless a host opts in:

use apalis_rtui::axum::ui::{CspPolicy, ServeUI};

let ui = ServeUI::new().csp(CspPolicy::default());

CspPolicy::default() is the policy this crate ships with, tuned to the bundle ServeUI serves: same-origin scripts and connections, 'wasm-unsafe-eval' for same-origin WebAssembly instantiation, 'unsafe-inline' styles for the dashboard's per-cell inline styling, and 'unsafe-inline' scripts because the shipped index.html boots the wasm module from an inline <script type="module"> and a static file has no request-time nonce to hand it. 'unsafe-eval' is never included. apalis-tui/tests/e2e serves the dashboard under this policy and fails on any violation Chromium reports. Pass CspPolicy::new("...") for a custom value instead.

Action routes and capabilities

Beyond the read-only JSON API, apalis-rtui exposes action routes for retrying, rescheduling, resuming, vacuuming, and updating tasks. Each optional action is gated on a trait: the backend either implements it or does not.

use apalis_rtui::axum::{
    capability::{RegisterReschedule, RegisterVacuum},
    framework::ApiBuilder,
};
use axum::Router;

let (api, handle) = ApiBuilder::new(Router::new()).register_shared(email_store);
let api = api
    .with_reschedule("emails", &handle)
    .with_vacuum("emails", &handle)
    .build();

register_shared mounts the same routes as register, plus the always-available POST .../retry and POST .../tasks/bulk routes, and returns the Arc<RwLock<B>> handle every with_*() capability builder needs. register itself is unchanged: call it instead when a queue needs no optional capability. Both are available under apalis_rtui::axum and apalis_rtui::actix. A .with_*() call naming a queue that no register/register_shared call mounted panics at startup, the same way an invalid queue name does, so a typo cannot leave a capability advertised and unwired.

On actix, build the ApiBuilder once per process rather than once per worker where you can. HttpServer::new calls its factory in every worker thread, and each ApiBuilder owns its own capability map, task_id -> queue index and event ring. The map agrees across workers, but the index does not: a GET /queues/{queue}/tasks/{id} served by one worker never teaches another, so whether a later task-status event carries a queue name depends on which worker answered, and the activity series is split the same way. actix_web::Scope is not Clone, so there is no way to hand one prebuilt router to every worker. Run HttpServer::new(...).workers(1) when one shared view matters. axum builds its Router once and has no equivalent split.

Method Path Mounted by
GET /capabilities register/register_shared
POST /queues/{queue}/tasks/{task_id}/retry register/register_shared
POST /queues/{queue}/tasks/bulk register/register_shared
PATCH /queues/{queue}/tasks/{task_id}/reschedule .with_reschedule()
POST /queues/{queue}/tasks/{task_id}/resume .with_resume()
POST /queues/{queue}/resume-abandoned .with_resume_abandoned()
POST /queues/{queue}/vacuum .with_vacuum()
PATCH /queues/{queue}/tasks/{task_id} .with_update()

retry prefers a true reschedule when .with_reschedule() was also called for that queue. Otherwise it pushes a new task with the same arguments. The response body's mode field says which one happened, so a client never labels a fallback as a real reschedule.

GET /capabilities reports which of these a queue actually supports, computed once when the backend is registered:

{
  "emails": {
    "reschedule": true,
    "resume_by_id": false,
    "resume_abandoned": false,
    "vacuum": true,
    "update": false,
    "register_worker": false,
    "live_status": false
  }
}

Fetch it once per session and use it to grey or hide a control, instead of probing the action route itself.

Body size and CSRF

let api = ApiBuilder::new(Router::new())
    .max_body_size(2 * 1024 * 1024)
    .require_csrf_token(true)
    .register(email_store);

max_body_size caps every mutating route's request body, 1 MiB by default. A request over the cap gets a 413. require_csrf_token is off by default. Turned on, it checks a csrf_token cookie against a matching x-csrf-token header on every mutating route, and rejects a mismatch with 403. Set both before calling register/register_shared/with_*(). A route already mounted keeps whatever settings were active when it was mounted.

Live task status

Beyond the raw /events log stream, apalis-rtui derives a small, typed task-status event from the same pipeline: a task_id, a queue, a status (Running, Done, or Failed), an attempt number, and, once terminal, done_in_ms/result.

GET /events/status streams these events. A client that connects late still sees what already happened: the server keeps a bounded buffer of the most recent events and replays it before switching to live delivery. ?queue=emails and ?task_id=01K7... filter the stream to one queue or one task. A : keep-alive comment arrives every 15 seconds so a client can tell an idle connection from a dropped one. There is no ?level=: a task-status event carries a status, an attempt number and a result, and no log level to match on. Levels belong to the raw log frames GET /events streams.

GET /events/activity reports the last 60 one-minute buckets of task.start/task.done/ task.failed counts, as plain JSON:

[{ "minute_epoch": 1732000020, "start": 3, "done": 2, "failed": 1 }]

Exactly 60 entries, oldest first, zero-filled for a minute with no activity. minute_epoch is Unix epoch seconds truncated to the minute, so consecutive entries are 60 apart and the last one is the current minute. This series is per-process. It resets on restart and is not shared across replicas.

GET /queues/{queue}/tasks/{task_id}/events streams status for one task. Without .with_live_status(), this is the same tracing-derived stream as /events/status?task_id=.... With it, the stream is backend-confirmed instead of inferred:

use apalis_rtui::axum::capability::RegisterLiveStatus;

let (api, handle) = ApiBuilder::new(Router::new()).register_shared(email_store);
let api = api.with_live_status("emails", &handle);

A backend-confirmed event has no attempt number: WaitForCompletion's result carries only a final status, so attempt is always 0 on that path. The tracing-derived path reports the real attempt.

queue on a task-status event needs the task's id to already have been looked up once, through GET /queues/{queue}/tasks/{task_id} (the route a task detail screen calls before it subscribes to that task's status). A task nobody has fetched by id yet reports an empty queue until it is.

Support

This crate depends on apalis-core and apalis-rtui-types (which re-exports apalis-board-types) only, never on a backend crate. Every route and control is gated on a trait bound the backend either implements or does not, never on a backend's name.