Skip to content

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.

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.

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.

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.