Files
romm/docs
27ddb88967 feat(api): Add a REST endpoint to start a library scan (#5014)
* Add a REST endpoint to start a library scan

POST /api/tasks/scan queues a scan with the options of the `scan` socket
event, so clients authenticating with a bearer or client token can
start one without a Socket.IO session. It answers 202 with the queued job,
409 while a library scan is queued or running, and 503 when no worker
listens on the scan queue.

The enqueue path moves into queue_scan, shared with the socket handler.
A short Redis lock now covers the in-flight check and the enqueue, so two
requests landing on different web workers cannot both queue a library
scan. The socket handler also answers scan:done_ko for an unknown scan
type instead of raising.

* Default a scan without apis to the enabled sources, lease the request lock

A scan request that leaves out `apis` now uses every enabled metadata
source, on the REST endpoint and the socket alike, as the scheduled scan
and the watcher do. An explicit empty list still means no sources. The
web UI always sends `apis`, so its scans are unchanged.

redis_lock takes an optional lease_seconds, and the library scan request
lock holds its key for 30s while waiters give up after 5s, so a slow
holder cannot lose the lock to a waiter that then queues a second scan.

* Narrow optional mock call args in the new scan tests

* pr-ready step 2 (code-review): narrow the scan lock timeout handling to acquiring the lock

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

* pr-ready step 3 (simplify): share the held-lock stub, read the task name off the queued job

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

* pr-ready step 4 (review-polish): drop a test comment that recorded old behaviour

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

* Validate socket scan options with ScanPayload and list workers once per scan request

The socket handler now parses its options with the same ScanPayload the REST
endpoint uses, so an unknown key, scan type or metadata source answers
scan:done_ko instead of falling back to a scan of everything. v1 callers that
could send a null platform id now send a real one or none.

queue_scan checks for a live scan worker itself, so the socket also refuses a
scan no worker would pick up, and it lists the workers once for that check and
the in-flight check. The blocking RQ calls run in a thread, off the event loop.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

* Rename useScanProviders' ScanPayload to ScanSourceOptions

It shared its name with the generated ScanPayload request type while holding
only the metadata source options.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

---------

Co-authored-by: Georges-Antoine Assi <[email protected]>
Co-authored-by: Claude Opus 5.5 (1M context) <[email protected]>
2026-10-02 18:46:28 -04:00
..