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
= { = "1.0.0-rc.8", = ["axum"] }
# after
= { = "apalis-rtui", = "0.1.0-rc.1", = ["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 ;
use Router;
let app = new
.register // Add backends
.register
.build;
let ui = new.with_api_base;
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'sRootViewtype is a worked example of this.
Live tracing events
let broadcaster = create;
let tracing_subscriber = new;
let tracing_layer = tracing_subscriber
.layer
.with_filter;
registry.with.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 = new.with_api_base;
Content-Security-Policy
No Content-Security-Policy header is sent unless a host opts in:
use ;
let ui = new.csp;
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 ;
use Router;
let = new.register_shared;
let api = api
.with_reschedule
.with_vacuum
.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:
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 = new
.max_body_size
.require_csrf_token
.register;
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:
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 RegisterLiveStatus;
let = new.register_shared;
let api = api.with_live_status;
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.