maintenance portlet | Implement fix assets and clean orphan assets polling APIs #35191

[hassandotcms]

Summary

Add 4 new REST endpoints to MaintenanceResource, replacing legacy DWR fix assets and clean assets operations with modern REST APIs for the Maintenance portlet Tools tab.

New endpoints:

• POST /api/v1/maintenance/_fixAssets — Runs all registered FixTask classes that check for and fix database inconsistencies. Executes synchronously and returns task results when complete.
• GET /api/v1/maintenance/_fixAssets — Polls current fix assets task results. Used by the UI to check progress while the process is running.
• POST /api/v1/maintenance/_cleanAssets — Starts a background thread that walks the assets directory structure, checks each directory against the contentlet database, and deletes orphan binary folders. Returns 409 Conflict if already running.
• GET /api/v1/maintenance/_cleanAssets — Polls clean assets background process status (totalFiles, currentFiles, deleted, running, status).

Implementation details:

• CleanAssetsStatusView (@Value.Immutable) with typed fields instead of BeanUtils.describe() string map
• 409 Conflict guard on POST /_cleanAssets prevents IllegalThreadStateException from calling .start() on an already-running thread
• FixTasksExecutor results returned as List<Map> (raw type from executor, cannot be typed further)
• ResponseEntityCleanAssetsStatusView typed wrapper for Swagger documentation

Test plan

• Integration tests pass: ./mvnw verify -pl :dotcms-integration -Dcoreit.test.skip=false -Dit.test=MaintenanceResourceIntegrationTest
• POST /_fixAssets as admin returns 200 with task results or null entity
• GET /_fixAssets returns current task results
• POST /_cleanAssets starts process and returns initial status with running: true
• GET /_cleanAssets returns current status with totalFiles, currentFiles, deleted, running, status fields
• POST /_cleanAssets while already running returns 409 Conflict
• Non-admin users get 403 on all endpoints

Closes #35200, Closes #35202

[claude]

Claude finished @hassandotcms's task in 3m 1s —— View job

---

PR Review

• Gather context
• Read changed files
• Analyze for issues
• Post review

---

Issues

1. POST /_fixAssets has no concurrency guard — shared state corruption risk

FixTasksExecutor is a singleton with a mutable instance field returnValue. At the top of execute(), it immediately does returnValue = new ArrayList<>(). Two concurrent POST requests will race on this: the second caller resets the list while the first is still populating it, silently discarding partial results. GET /_fixAssets polling during a concurrent run will return garbage.

POST /_cleanAssets has a 409 guard, but POST /_fixAssets has none despite running a comparably dangerous DB operation.

MaintenanceResource.java:752-765 — Fix this →

2. POST /_cleanAssets 409 check is not atomic

getInstance(true, true) creates a new thread+status if the current thread is dead. The isRunning() check happens after that. The running flag is set to true only inside run(), which executes asynchronously after thread.start(). There's a window where two concurrent POST requests both call getInstance(true, true), both see a not-alive thread, both get running=false, and both call start() on separate thread instances — bypassing the 409 entirely.

MaintenanceResource.java:843-854 / CleanAssetsThread.java:76-89

3. POST /_cleanAssets initial response shows running: false

thread.start() is called and then the status is immediately serialized. The thread hasn't had a chance to execute processStatus.setRunning(true) yet (that happens inside run() on the new thread). The first response to a client that just started the process will say running: false, which is wrong.

MaintenanceResource.java:853-855

4. FixTasksExecutor.execute() silently swallows all exceptions

In FixTasksExecutor.java:109-121, on exception it logs FATAL, throws DotDataException, then immediately catches it with an empty // TODO block. startFixAssets always returns HTTP 200 even when fix tasks completely fail. The caller cannot distinguish success from failure.

FixTasksExecutor.java:109-121 — This is pre-existing, but the new REST endpoint surfaces it as an observable correctness problem.

5. SecurityLogger missing from startFixAssets

All other destructive operations in this file (searchAndReplace, dropOldVersions, deletePushedAssets, startCleanAssets) call SecurityLogger.logInfo so the action appears in the security audit trail. startFixAssets only calls Logger.info.

MaintenanceResource.java:758-760 — Fix this →

---

Minor

• form.checkValid() double call (MaintenanceResource.java:573): SearchAndReplaceForm's constructor already calls checkValid(). Calling it again in the endpoint is redundant.
• null entity response: Both fix assets endpoints return new ResponseEntityView<>(results.isEmpty() ? null : results). Returning {"entity": null} before any tasks run is surprising for a polling endpoint — an empty list would be more consistent.
• test_startCleanAssets_asAdmin_startsProcess doesn't assert running: true — it only asserts status != null. Given issue Add .gitignore #3 above (the initial response may show running: false), this test would pass even if the thread never started.

[claude]

Rollback safety analysis complete. Safe To Rollback. Label applied.