threadmill-dashboard-spring
Spring MVC/Security adapter for the Threadmill dashboard.
The portable dashboard service and DTOs live in threadmill-dashboard-api.
This module exposes them over Spring MVC at /threadmill/api/** by default.
Authentication stays in the host; Threadmill adds a scoped dashboard security
chain, redaction, audit hooks, and state-machine enforcement for operator
actions.
If the threadmill-dashboard-ui asset jar is also on the classpath, this
adapter mounts those static assets under /threadmill. The UI remains a
portable static app and can be reused by other framework adapters.
Security
Section titled “Security”DashboardAuthorizer maps the current Spring Authentication to dashboard
permissions. The default implementation grants permissions from authorities
named THREADMILL_<PERMISSION> or ROLE_THREADMILL_<PERMISSION>; ADMIN or
ROLE_THREADMILL_ADMIN grants all dashboard permissions.
By default, Threadmill registers a SecurityFilterChain for the configured API
path and /threadmill/**, covering both JSON endpoints and mounted UI assets.
It requires authentication and CSRF tokens for mutating requests, using
CookieCsrfTokenRepository.withHttpOnlyFalse() so the static UI can send the
token back in the configured header. Set
threadmill.dashboard.security.auto-configure=false to provide a custom chain.
If no SecurityFilterChain exists, startup fails unless unsafe read-only local
mode is enabled.
When the host declares no SecurityFilterChain, Threadmill also installs a
fallback catch-all chain requiring authentication, with form login, HTTP Basic,
and default CSRF protection. This preserves protection for host endpoints when
the scoped dashboard chain makes Boot’s default chain back off. If the host
provides any custom chain, this fallback backs off and the host owns its route
coverage. Setting threadmill.dashboard.security.auto-configure=false disables
both Threadmill chains, leaving the configuration to the host and Spring Boot.
Sensitive fields are redacted by default: payload arguments, metadata, logs,
results, and failure messages. Full detail requires both
DashboardOptions.exposeSensitiveDetails=true and
VIEW_SENSITIVE_DETAILS.
Configuration
Section titled “Configuration”| Property | Default | Purpose |
|---|---|---|
threadmill.dashboard.api.base-path |
/threadmill/api |
Base path for every API endpoint. |
threadmill.dashboard.security.auto-configure |
true |
Register scoped dashboard security and a host authentication fallback when no custom chains exist. |
threadmill.dashboard.expose-sensitive-details |
false |
Allow full payload / metadata / log / result exposure when the user also has VIEW_SENSITIVE_DETAILS. |
threadmill.dashboard.allow-unsafe-read-only-without-authentication |
false |
Local-only escape hatch for read-only unauthenticated access. |
The default audit sink is a noop and logs a startup warning. Production
applications should provide a DashboardAuditSink bean that writes operator
actions to the host audit pipeline.
Operator Actions
Section titled “Operator Actions”The controller exposes pause/resume queue, requeue, retry scheduling, soft-delete, pending-job replacement, recurring trigger/update/delete, and node/queue/job read endpoints. Actions always re-check permissions server-side and reject illegal state transitions.
REPLACE_JOB covers operational edits to a pending job’s queue, priority, or
scheduled time. Supplying handlerType or arguments crosses an executable-code
boundary and requires ADMIN, even when the supplied value matches the current
definition. The Spring adapter loads the named class without initialization,
requires it to implement JobHandler, resolves its declared JobPayload type,
and rejects missing, extra, or incompatible payload arguments before any store
write. A host may provide a custom DashboardJobDefinitionValidator bean to add
an application-specific handler allowlist. The default validator requires one
unambiguous JobSerializer; if it is ambiguous or unavailable,
executable-definition edits return 501 and no write is attempted. Definition changes are emitted to the audit sink as
replace_job_definition with permission ADMIN; operational edits remain
replace_job with permission REPLACE_JOB.
The same boundary applies to recurring tasks. Trigger, queue, priority, missed-run
policy, zone, and enabled-state edits require UPDATE_RECURRING; supplying
handlerType or payloadArgument requires ADMIN, uses the same validator, and
is audited as update_recurring_definition.
Recurring trigger, update, and delete actions take the same per-task store mutex as the maintenance materializer. When another node is already mutating the task, the API returns a conflict and the operator can retry; it never proceeds with an unguarded schedule-state write.