Skip to content
Admin UI

Admin UI

The module bikesched-admin (package org.bikesched.admin.web) serves a small page showing what the jobs of a bikesched database are doing: jobs by name and state, a job with its steps, history, child jobs and last error, events with the jobs that published, received or still wait for them, and the nodes, online or offline, and the history of all of them. Failed jobs can be retried and active ones cancelled, and jobs scheduled and events published, from the page. It is embedded in the application that runs bikesched; there is no separate service.

Bikesched bikesched = Bikesched.builder(dataSource).build();

HttpServer server = HttpServer.create(new InetSocketAddress(8081), 0);
server.createContext("/bikesched", BikeschedAdmin.of(bikesched).httpHandler());
server.start();   // http://localhost:8081/bikesched/

The handler uses the JDK’s built-in com.sun.net.httpserver (module jdk.httpserver). The module depends on bikesched-core, SLF4J and nanojson for its JSON responses. The page is static HTML, CSS and JavaScript served from the jar (Preact and htm are bundled), reading a JSON API under api/; it loads nothing from other hosts.

The node serving the page does not need to poll: a node built with autoStartPolling(false) shows the jobs of every node on the database. Scheduling jobs from the page needs the job handlers registered on it, as newJob(name) does in code; any node handling the name runs the job. The runnable admin example serves the page next to a few demo jobs.

Dependencies and shaded jar

Choose one of the two artifacts, not both:

dependencies {
    implementation("org.bikesched:bikesched-admin:0.2.0-SNAPSHOT")
    // Or, with nanojson bundled and relocated to avoid application version conflicts:
    // implementation("org.bikesched:bikesched-admin-shaded:0.2.0-SNAPSHOT")
}

The regular jar uses nanojson as a normal runtime dependency. The shaded jar bundles only nanojson, relocated to org.bikesched.admin.web.internal.nanojson; core and SLF4J remain external dependencies. Its publication does not pull in the original nanojson artifact. Both expose the same admin API and include the same UI files. Shading does not affect the application’s payload mapper or add a JSON dependency to core.

The regular jar is a JPMS module. The shaded jar is an automatic module with the same name, org.bikesched.admin.web, and must not be used alongside the regular jar. Build both with ./gradlew :bikesched-admin:build; shadedTest also runs the admin tests against the shaded jar alongside an unrelocated nanojson dependency.

Options

BikeschedAdmin is immutable: every option returns a copy.

Option Default Effect
access(AdminAccess) AdminAccess.open() who may see the page and who may retry, cancel, schedule and publish, see Access
readOnly(true) false no retry, cancel, schedule or publish for anyone: every access level is capped at viewing
showPayloads(true) false shows job payloads and results and event payloads, see Payloads

Access

An AdminAccess (package org.bikesched.admin.web.access, with AccessGrant and AccessLevel) decides per request what it may do: NONE, VIEW (the page and every GET route) or OPERATE (also retry, cancel, schedule jobs and publish events). The default, AdminAccess.open(), lets every request operate: protect the path in the application (Spring Security, a reverse proxy) or pick one of the options below.

HTTP Basic authentication with operators and viewers is built in:

BikeschedAdmin.of(bikesched)
    .access(AdminAccess.basicAuth()
        .operator("ops", System.getenv("ADMIN_OPS_PASSWORD"))         // may change jobs, events
        .viewer("support", System.getenv("ADMIN_SUPPORT_PASSWORD"))   // read only
        .build());
  • Without valid credentials the admin answers 401 with a WWW-Authenticate challenge, so the browser shows its login dialog. A viewer’s retry, cancel, schedule or publish answers 403.
  • Passwords are kept as SHA-256 digests and compared in constant time. A failed login is logged with the user name and the client’s address, never with the password.
  • Basic authentication sends the password with every request: serve the admin over HTTPS (the JDK’s HttpsServer, or TLS at a reverse proxy). Over a plain HttpServer the handler logs a warning once.
  • There is no logout; closing the browser ends the session.

Any other scheme is a custom AdminAccess, e.g. trusting a header an authenticating proxy sets:

AdminAccess byProxy = request -> {
  String user = request.header("X-Forwarded-User");
  return user == null ? AccessGrant.none() : new AccessGrant(user, AccessLevel.VIEW);
};

A custom access without a challenge() answers denied requests with 403.

The user an access grant names (the Basic authentication user, or the custom access’s) is recorded on the history entries of the actions taken with the admin: the jobs it schedules, retries and cancels and the events it publishes name the user, so the history says “RETRIED by simon” (a name longer than 200 characters is cut). The open access names nobody: its actions are recorded as the application’s.

Retry, cancel, schedule and publish are POST requests that must carry the header X-Bikesched-Admin: 1, which the page sets. A form or image on another site cannot send it, so a signed-in browser cannot be made to change jobs or publish events from elsewhere. Every response carries a strict Content-Security-Policy (only the admin’s own files, no inline scripts or styles) and X-Content-Type-Options: nosniff.

Payloads

Payloads and results may hold personal or secret data, so they are hidden by default. The filter is on the server: without showPayloads(true) the admin never reads them from the database, and no response of the JSON API contains them. The page keeps its Data and Payload tabs and explains how to turn them on. Error messages, step names, event keys, idempotency keys and references are always shown.

The page

  • Header: the Jobs, Events, Nodes and History tabs, the first three with their number of jobs, unexpired events and registered nodes (with “1 offline” while a node has no heartbeat within the node timeout), and a reload button. Each tab returns to its list with the filters it was left with; the open tab clears them.
  • Job and event names: above the job list a select box with the job names and their number of jobs (and failed jobs or the recurrence), above the event list one with the event names and their number of unexpired events and waiting jobs (a name jobs wait for but nobody published yet is listed too). Both have a search field, so many names stay usable. A repeat icon marks recurring jobs.
  • Jobs: newest first (an arrow marks the column a list is sorted by, here Created), filtered by name and by one or more states; “Older jobs” loads the next page. A child job names its parent below its name; a run of a recurring job has the repeat icon and its recurrence there; a job with a reference shows it there too.
  • Search by id or reference: the job list and the event list each have a search field. It takes a full id or its last 8 characters (the short id the lists show: ids are time-ordered UUIDv7, so their start is their creation time and their end is random), with or without hyphens, or a reference (exact match, case- and whitespace-sensitive), and finds only jobs in the job list and only events in the event list: those whose id ends with the text and those with it as their reference. A single match opens its detail; the other filters are off while the search is active.
  • Job detail: all fields (the type says single, recurring or child job), the idempotency key, the reference (with links to the jobs and the events that have it), the last error, retry and cancel, the steps with their duration (a child job step links to the child, a child job shows the path to its parents), the history when recorded (each entry’s action, resulting state, who acted and its details), and a Data tab with the payload above the result. A running or waiting step’s duration counts up; a retried step shows its last attempt’s. A run of a recurring job has a Recurrence tab: the pending run (the next one with a countdown, or the current one while it runs or waits), then the last 10 ended runs with their state and how long they took from their scheduled time to their end. Jobs with the name scheduled without a recurrence are not runs and not listed. The tab refreshes every 3 seconds. While the job is open and has not ended, the detail refreshes every 3 seconds and updates the job’s row in the list; an unchanged job costs a 304 without a body.
  • Step detail: a step’s name in the job detail, in its history and on the event pages opens the step on its own (#/jobs/{jobId}/steps/{stepId}, keyed by the step’s id): its type, attempts (checks of a poll), times, deadline, failure handler runs, compensation, the node running it, its event or child job, the last error, its result (with showPayloads(true)) and its entries of the history. It refreshes every 3 seconds until its job ended.
  • Schedule job (operators): a form in the detail panel, opened by the button above the job list (with the name of the list filled in) or by “Schedule similar…” in a job’s detail (name, payload, priority and max attempts copied from that job). It offers only the job names the serving node has a handler for; picking one copies the payload of its latest job (only with showPayloads(true)). The job runs now or after a delay; priority, max attempts, timeout, an idempotency key and a reference are under “More options” (“Schedule similar…” also copies the reference). The payload must be JSON. For a recurring job it adds one run and leaves the recurrence as it is. Once scheduled, the new job’s detail opens; with an idempotency key a job with that name already has, that job opens instead and nothing is scheduled. The server logs every scheduled job with the user.
  • Events: newest first, by name and key prefix. The detail shows who published the event (a job’s step or outside a job), the jobs that received it, its payload and, when recorded, its history: the publish and what it caused (the steps that received it, the jobs it resumed); “latest” marks the event a new wait for its name and key would receive. The “Waiting jobs” tab lists the event waits still waiting for the name.
  • Publish event (operators): a form in the detail panel, opened by the button above the event list, by “Publish…” on a waiting job or “Publish event…” on a waiting step in a job’s detail (name and key filled in) or by “Publish similar” in an event’s detail (copied from that event). Picking a known name copies key and payload from its latest unexpired event (the payload only with showPayloads(true)); the keys jobs wait for are offered below the key. Before publishing, the form lists the jobs waiting for that name and key, which continue right away; the payload must be JSON. Retention (node default, 0, 1 hour, 1 day, 7 days), an idempotency key and a reference are optional (“Publish similar” also copies the reference). The server logs every published event with the user.
  • Nodes: every registered node by name, online or offline, with its start, last heartbeat and the number of jobs it runs. The list and the open node refresh every 3 seconds while the tab is visible. The node detail shows how long ago its last heartbeat was, its uptime and the jobs it runs, each linked, and its history when recorded (registered, stopped, removed, and the jobs released after it died); an offline node says that other nodes release its jobs and later remove it. A node that is no longer registered still opens while its history has entries. A running job’s Node field links to the node.
  • History: every entry of the history, newest first: time, subject (job, step, event or node, linked to its page), action, the state it led to, actor (a user’s name, “job”, “node” or “application”), the node that wrote it (by name, also after it was removed) and its details. Filters: actor (everyone, users, application, jobs, nodes), subject type, the actions of that type (several), and “Before” a time. Filters other than users, time and cause scan at most 5000 entries per page, so a page with a rare action can stop early: “Older entries” continues the scan. An entry’s detail shows its fields, its data and the entries its subject caused (a job’s child jobs, an event’s receivers, a dead node’s released jobs). The list is live: every 3 seconds it re-reads the minute before its newest entry and adds what is new, so an entry of a transaction that committed late still shows up. An entry of a transaction open for longer than that minute shows up only after Reload, and when more than 500 new entries arrive between two refreshes, live refresh stops and asks for a Reload. The tab says when the serving instance does not record the history; it still shows what other nodes recorded. Viewers see everything, user names and messages included.

Every view is a link (#/jobs?name=send-invoice&state=FAILED, #/jobs?search=order-4711, #/jobs/{id}, #/jobs/{id}/steps/{stepId}, #/events/{id}, #/events/new?pubName=payment-received&pubKey=order-42, #/nodes/{id}, #/history?actor=USER), so it can be shared or put into an alert. The page follows the browser’s light or dark mode.

Other HTTP servers

handle(AdminRequest) works with any framework: translate the request (method, path relative to the mount point, raw query string, headers, client address, body as text) and write the AdminResponse back. A servlet, for example:

BikeschedAdmin admin = BikeschedAdmin.of(bikesched);

protected void service(HttpServletRequest req, HttpServletResponse resp) throws IOException {
  Map<String, String> headers = new HashMap<>();
  Collections.list(req.getHeaderNames()).forEach(name -> headers.put(name, req.getHeader(name)));
  String path = req.getPathInfo() == null ? "/" : req.getPathInfo();
  AdminResponse response = admin.handle(new AdminRequest(
      req.getMethod(), path, req.getQueryString(), headers, req.getRemoteAddr(),
      new String(req.getInputStream().readNBytes(1024 * 1024), StandardCharsets.UTF_8)));
  resp.setStatus(response.status());
  response.headers().forEach(resp::setHeader);
  resp.getOutputStream().write(response.body());
}

Mount it so that the page’s URL ends with a slash (/bikesched/): its files are loaded relative to it.

JSON API

The page’s API can be used from scripts too. Paths are relative to the mount point; every response is JSON with Cache-Control: no-store and an ETag.

Method Path Returns
GET api/jobs?name=&state=&node=&reference=&before=&limit= {"jobs": [...], "next": cursor}: newest first; state takes several states separated by commas, node a node id (the jobs it runs now), reference a reference (exact match), before the previous page’s next, limit 1 to 500 (default 50)
GET api/jobs?id=&limit= {"jobs": [...], "next": null}: jobs whose id ends with id (at least 8 hex digits, or a full id), newest first; not combined with the other filters
GET api/jobs?search=&limit= {"jobs": [...], "next": null}: the page’s search, jobs whose id ends with search (if it is 8 to 32 hex digits) or whose reference is search, newest first; not combined with the other filters
GET api/jobs/{id} {"job", "ancestors", "steps", "history", "payloadsShown"}, plus payload and result with showPayloads(true)
GET api/steps/{id} {"step", "job", "history", "payloadsShown"}: one step by its id with its job’s summary and the step’s history entries, plus result with showPayloads(true)
GET api/job-names {"names": [{"name", "total", "counts", "recurrence", "handled"}]}: handled if the serving node has a handler for the name (handled names without jobs are listed too)
GET api/events?name=&key=&reference=&before=&limit= {"events": [...], "next": cursor}: unexpired events, newest first; key is a prefix, reference an exact match
GET api/events?id=&limit= {"events": [...], "next": null}: unexpired events whose id ends with id, as for jobs
GET api/events?search=&limit= {"events": [...], "next": null}: unexpired events whose id ends with search or whose reference is search, as for jobs
GET api/events/{id} {"event", "steps", "history", "payloadsShown"}, plus payload with showPayloads(true); history holds the event’s entries and those it caused
GET api/event-names {"names": [{"name", "count", "waiting"}]}: unexpired events and waiting steps per name
GET api/recurring-runs?name=&limit= {"name", "pending", "previous": [...]}: the pending run of a recurring job (null if none) and its latest ended runs, newest first
GET api/waiting?name=&key=&limit= {"steps": [...]}: event waits still waiting for the name, longest waiting first
GET api/nodes {"nodes": [{"id", "name", "startedAt", "lastHeartbeatAt", "alive", "runningJobs"}]}: by name
GET api/nodes/{id} {"node": {...}, "history": [...]}, the same fields, plus the node’s history entries and those it caused; once the node is removed node is null, and 404 without history entries
GET api/history?subject=&actor=&action=&since=&until=&causedBy=&after=&limit= {"entries": [...], "next": cursor, "subjects": {id: {"type", "name"}}, "recording"}: history entries of every subject, newest first; subject is JOB, STEP, EVENT or NODE, actor an actor type, action actions of the subject separated by commas, since (inclusive) and until (exclusive) ISO-8601 instants, causedBy the id of the job, event or node that caused the entries, after the previous page’s next; subjects names the writing nodes and the causing subjects, recording says whether the serving instance records the history
GET api/me {"user", "level", "readOnly", "payloadsShown"}
POST api/jobs/{id}/retry {"retried": true or false} (only failed jobs are retried)
POST api/jobs/{id}/cancel {"cancelled": true or false} (message “cancelled from the admin UI”, the user is on the history entry)
POST api/jobs {"id", "created"}: schedules a job from a form-encoded body (name, payload as JSON text, delay as ISO-8601 or at as an ISO-8601 instant, priority, maxAttempts, timeout as ISO-8601, idempotencyKey, reference); created is false when a job with that name has the idempotency key, whose id is returned
POST api/events {"id", "received"}: publishes an event from a form-encoded body (name, key, payload as JSON text, retention as ISO-8601, idempotencyKey, reference); received counts the steps that got it at once

A history entry in the JSON API has its id, subjectType, subjectId, stepId, state, attempt, at, action, actorType, actorName, nodeId, causedById and data (the entry’s JSON object, or null).

Errors are {"error": "..."} with 400 (malformed parameter, id, job or event, a job name without a handler on the serving node), 401/403 (access), 404 (unknown job, step, event or path), 405 (wrong method) or 503 (the database cannot be reached).

Lookups and actions in code

The page reads and acts through bikesched.admin(), lookups and actions in bikesched-core (package org.bikesched.admin) that also suit custom dashboards and support tools:

Admin admin = bikesched.admin();
List<JobSummary> failed = admin.findJobs(JobQuery.newest(50).withStates(JobState.FAILED));
List<JobSummary> older = admin.findJobs(JobQuery.newest(50).withStates(JobState.FAILED)
    .after(failed.getLast()));
List<StepInfo> steps = admin.findSteps(failed.getFirst().id());
Method Returns
findJobs(JobQuery) jobs by name, reference, states and the node running them, newest first, in pages (after(lastJob))
findJobsByIdSuffix(suffix, limit) jobs whose id ends with at least 8 hex digits (or a full id), newest first
findJob(id) one job’s summary: name, type, state, attempts, times, last error, parent, recurrence, idempotency key, reference, node
findJob(name, idempotencyKey) the job with a name and an idempotency key, the one scheduling with that key returns
findJobData(id) the payload and result as JSON text
findSteps(id) the job’s steps in the order they started, with event and child job details
findStep(stepId), findStepResult(stepId) one step by its id, its result as JSON text
findJobNames() every job name with its number of jobs per state and whether this node handles it (handled names without jobs too)
findRecurringJobRuns(name, limit) a recurring job’s pending run and its latest ended runs, newest first
findEvents(EventQuery) unexpired events by name, key prefix and reference, newest first, in pages
findEventsByIdSuffix(suffix, limit) unexpired events whose id ends with at least 8 hex digits
findEvent(id), findEventPayload(id) one event, its payload as JSON text
findEventNames() every event name with its number of unexpired events
findEventSteps(id) the steps that published or received the event
findWaitingSteps(name, keyPrefix, limit) event waits still waiting for the name
findNodes() the registered nodes, alive or not, with the number of jobs each runs
findNode(id) one registered node
findNodeHistory(id) a node’s history entries and those it caused, also after it was removed
findHistory(HistoryQuery) history entries of every subject by entry type, actor type, actions, cause and time, newest first, in pages (after(page.next())), with the writing nodes and causing subjects
isRecordingHistory() whether this instance records the history

Summaries never contain payloads or results; only findJobData and findEventPayload read them.

The actions do what Bikesched.cancel, retry and removeRecurringJob do, and can name the user acting on the history entry they record (Actor.user(name) from org.bikesched.history), as the admin does with the signed-in user:

Actor simon = Actor.user("simon");
admin.cancelJob(jobId).message("customer called").actor(simon).cancel();
admin.retryJob(jobId).actor(simon).retry();
admin.removeRecurringJob("report").actor(simon).remove();

Scheduling jobs and publishing events name a user with actor(…) on their builders (bikesched.newJob(…).actor(simon), bikesched.newEvent(…).actor(simon)).