feat: endpoint to trigger directory scans from external tools

[s0up4200]

Summary

This PR adds a webhook endpoint that allows external tools like Sonarr/Radarr custom scripts to trigger directory scans by providing a file path. The endpoint intelligently matches the provided path against configured scan directories using longest-prefix matching.

Key Changes

• New webhook endpoint: POST /api/dir-scan/webhook/scan accepts a JSON payload with a path field
• Path matching logic: Implements longest-prefix matching to find the best configured directory that contains the provided path
• Error handling: Returns appropriate HTTP status codes:
  • 202 Accepted when scan starts successfully
  • 404 Not Found when no matching directory is found
  • 409 Conflict when a scan is already in progress
  • 400 Bad Request for invalid input
• Query parameter authentication: Uses the same ?apikey= pattern as the cross-seed webhook for external tool integration
• Documentation: Added comprehensive guide with example Sonarr/Radarr custom script implementation

Implementation Details

• Path normalization using filepath.Clean() to handle various path formats consistently
• Longest-prefix matching ensures the most specific configured directory is selected when multiple directories could match
• Only enabled directories are considered for matching
• Logging includes directory ID, path, and run ID for debugging
• Response includes both runId and directoryId for external tools to track the scan

Summary by CodeRabbit

• New Features

  • Added webhook trigger for directory scans (Sonarr/Radarr/Lidarr/Readarr) via HTTP; responses include runId, directoryId and directoryPath with standard status codes.

• Documentation

  • Added comprehensive webhook docs (setup, auth, path-matching, response codes, curl examples); content was duplicated in two places.

• Tests

  • Added unit tests covering path-matching and webhook trigger behavior.

• Chores

  • Registered new webhook API route, updated OpenAPI, and simplified test command guidance.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Adds a new POST webhook endpoint /api/dir-scan/webhook/scan to trigger directory scans from Sonarr/Radarr/Lidarr/Readarr or simple {"path": "..."} payloads. The handler extracts and normalizes a path, selects the best matching configured directory by longest-prefix, starts a manual scan, and returns structured responses; includes OpenAPI, route, tests, and docs.

Changes

Cohort / File(s)	Summary
Documentation documentation/docs/features/cross-seed/dir-scan.md	Added comprehensive webhook trigger documentation (endpoint, payload shapes including Sonarr/Radarr/Lidarr/Readarr, path extraction, longest-prefix matching, split-mount caveats, response codes, curl "simple mode"); content duplicated in two places.
Webhook Handler Implementation internal/api/handlers/dirscan.go	New WebhookTriggerScan handler plus types (webhookTriggerScanPayload, dirScanTriggerResponse); helpers resolvedPath and pathMatchesDirectory; payload parsing for multiple formats, path normalization, longest-prefix directory selection, scan start, conflict handling, and structured responses.
Server Routing internal/api/server.go	Registered POST /api/dir-scan/webhook/scan route (guarded by API-key query auth and auth middleware) when dirScanHandler is present.
API Spec internal/web/swagger/openapi.yaml	Added /api/dir-scan/webhook/scan POST operation; request schemas for plain path and Sonarr/Radarr/Lidarr/Readarr payloads; updated DirScanTriggerResponse (runId -> int64, added directoryId and directoryPath); documented responses (202, 400, 404, 409, 500).
Tests internal/api/handlers/dirscan_webhook_test.go	Added tests for pathMatchesDirectory edge cases and an integration-style test that posts to the webhook, asserting 202 and returned runId, directoryId, and directoryPath, and that active runs clear.
Auxiliary AGENTS.md	Adjusted test guidance to use -count=1 for make test / testing instructions.

Sequence Diagram

sequenceDiagram
    participant Client as Webhook Client
    participant Server as HTTP Server
    participant Auth as Auth Middleware
    participant Handler as DirScanHandler
    participant Matcher as Path Matcher
    participant Scanner as Dir Scanner

    Client->>Server: POST /api/dir-scan/webhook/scan (API key & JSON)
    Server->>Auth: Validate API key & auth
    Auth-->>Server: OK / Reject
    Server->>Handler: WebhookTriggerScan(request)
    Handler->>Handler: Decode JSON & resolvedPath()
    Handler->>Matcher: Find best matching directory (longest-prefix)
    Matcher-->>Handler: directoryId or none
    alt Directory matched
        Handler->>Scanner: Start manual scan(directoryId)
        Scanner-->>Handler: runId
        Handler-->>Client: 202 Accepted (runId, directoryId, directoryPath)
    else No match
        Handler-->>Client: 404 Not Found
    else Conflict (scan active)
        Handler-->>Client: 409 Conflict
    else Invalid payload
        Handler-->>Client: 400 Bad Request
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested labels

enhancement

Poem

🐇 A webhook tip-taps at my burrow door,
I sniff the path and trace it to the floor,
I pick the longest-prefix trail with glee,
Nudge the scanner awake — seeds sprout free,
Hooray, cross-seed blooms for you and me! 🌱

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: endpoint to trigger directory scans from external tools' directly and clearly describes the main change: adding a webhook endpoint that allows external tools to trigger directory scans.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch claude/review-discussion-board-Xb7Xq

📝 Coding Plan

• Generate coding plan for human review comments

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (1)

internal/api/handlers/dirscan.go (1)

742-745: Use a typed response payload instead of map[string]any.

This response has a fixed schema, so a small struct keeps the contract explicit and aligned with the repo's Go guideline.

Suggested shape

type webhookTriggerScanResponse struct {
	RunID       int64 `json:"runId"`
	DirectoryID int   `json:"directoryId"`
}

-	RespondJSON(w, http.StatusAccepted, map[string]any{
-		"runId":       runID,
-		"directoryId": bestMatch.ID,
-	})
+	RespondJSON(w, http.StatusAccepted, webhookTriggerScanResponse{
+		RunID:       runID,
+		DirectoryID: bestMatch.ID,
+	})

As per coding guidelines, "Avoid map[string]interface{} — use proper structs in Go."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@internal/api/handlers/dirscan.go` around lines 742 - 745, Replace the
map[string]any payload used in the RespondJSON call with a typed struct: define
a webhookTriggerScanResponse struct (with RunID int64 `json:"runId"` and
DirectoryID int `json:"directoryId"`) near the handler, construct an instance
using runID and bestMatch.ID, and pass that instance to RespondJSON in the
handler where RespondJSON(w, http.StatusAccepted, ...) is called (look for the
RespondJSON invocation in the dirscan handler).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@documentation/docs/features/cross-seed/dir-scan.md`:
- Around line 271-277: The response table is missing the 400 case; update the
"Response codes" table to add a `400` | Bad Request row explaining that the
handler returns 400 for malformed JSON payloads and for requests that do not
include any supported path field (i.e., invalid/missing path in the payload), so
clients see this alongside the existing `202`, `404`, and `409` entries.
- Around line 242-244: Add language identifiers to the fenced code blocks
containing the POST call and the example URL: change the fence before "POST
/api/dir-scan/webhook/scan?apikey=YOUR_API_KEY" to ```http and change the fence
before "http://your-qui-host:7476/api/dir-scan/webhook/scan?apikey=YOUR_API_KEY"
to ```text (also apply the same fix to the other occurrence of the URL block
noted in the comment); this will satisfy markdownlint MD040.
- Around line 240-246: Update the documentation for the POST
/api/dir-scan/webhook/scan webhook to explicitly state that the matching logic
compares the incoming *arr webhook path against the Dir Scan "Directory Path"
configured in qui (not against any qBittorrent path prefixes), and note that in
split-mount setups the *arr service must expose the library using the same path
as qui for the webhook to match; apply the same clarification to the other
referenced paragraph(s) around lines 267-269.

In `@internal/api/handlers/dirscan.go`:
- Around line 714-716: The current containment check (using filepath.Clean on
dir.Path and strings.HasPrefix(cleanPath, dirPath+string(filepath.Separator)))
fails for filesystem roots because it produces a doubled separator; replace this
prefix logic with a filepath.Rel-based containment test: compute rel, err :=
filepath.Rel(dirPath, cleanPath) and treat the path as contained when err == nil
and rel != ".." and !strings.HasPrefix(rel, ".."+string(filepath.Separator));
keep the existing equality check (cleanPath == dirPath) or simply include that
case by accepting rel == "." as contained; update the condition where cleanPath
and dirPath are compared to use this Rel-based logic and retain use of
filepath.Clean on dir.Path.

---

Nitpick comments:
In `@internal/api/handlers/dirscan.go`:
- Around line 742-745: Replace the map[string]any payload used in the
RespondJSON call with a typed struct: define a webhookTriggerScanResponse struct
(with RunID int64 `json:"runId"` and DirectoryID int `json:"directoryId"`) near
the handler, construct an instance using runID and bestMatch.ID, and pass that
instance to RespondJSON in the handler where RespondJSON(w, http.StatusAccepted,
...) is called (look for the RespondJSON invocation in the dirscan handler).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 78537da8-c67c-4874-a25c-2429ed448dd7

📥 Commits

Reviewing files that changed from the base of the PR and between 13f9449 and 5a8f81a.

📒 Files selected for processing (3)

• documentation/docs/features/cross-seed/dir-scan.md
• internal/api/handlers/dirscan.go
• internal/api/server.go

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (1)

internal/api/handlers/dirscan.go (1)

754-757: Return a typed response here instead of an untyped map.

This payload shape is fixed, so a struct keeps the JSON contract compiler-checked and aligned with the documented response.

♻️ Suggested change

-	RespondJSON(w, http.StatusAccepted, map[string]any{
-		"runId":       runID,
-		"directoryId": bestMatch.ID,
-	})
+	RespondJSON(w, http.StatusAccepted, struct {
+		RunID       int64 `json:"runId"`
+		DirectoryID int   `json:"directoryId"`
+	}{
+		RunID:       runID,
+		DirectoryID: bestMatch.ID,
+	})

As per coding guidelines, "Avoid map[string]interface{} — use proper structs in Go."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@internal/api/handlers/dirscan.go` around lines 754 - 757, The response
currently uses an untyped map in the RespondJSON call; replace it with a
concrete response struct (e.g., DirectoryScanResponse or StartScanResponse) that
has fields RunID string `json:"runId"` and DirectoryID string
`json:"directoryId"`, populate it with the existing runID and bestMatch.ID
values, and pass that struct to RespondJSON so the payload shape is
compiler-checked (update any nearby type declarations or exports as needed).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@AGENTS.md`:
- Line 32: The test guidance was weakened by changing the Makefile test command
flags from "-race -count=3 -v" to "-race -count=1 -v"; revert or update the
AGENTS.md entry for the "make test" instruction so it explicitly uses "-race
-count=3 -v" (and any other occurrences of "make test" or the string "-count=1")
to enforce the project's policy of running Go tests with race detection and
three repetitions.

In `@documentation/docs/features/cross-seed/dir-scan.md`:
- Around line 273-280: The response table in dir-scan.md is missing the `500`
case; update the "Response codes" table to add a new row for status code `500`
with a clear meaning such as "Internal server error — scan could not be started
due to an internal failure" so the webhook contract documents the full error
surface; edit the table in documentation/docs/features/cross-seed/dir-scan.md
(the "Response codes" section) and insert the `| `500` | Internal server error —
scan could not be started due to an internal failure |` row.

In `@internal/web/swagger/openapi.yaml`:
- Around line 3342-3347: The OpenAPI response schema for the 202 on this
endpoint currently references DirScanTriggerResponse but the webhook actually
returns both runId and directoryId; update the components schema
(DirScanTriggerResponse) or replace the $ref so the response model includes both
runId and directoryId (with correct types and descriptions) to match the webhook
payload so generated client code will include directoryId alongside runId.
- Around line 3313-3340: Update the request schema in
internal/web/swagger/openapi.yaml to reflect the handler's validation by
replacing the permissive object with a oneOf that enforces at least one path
source: add three/four branches for (1) direct { path } with required: [path],
(2) Sonarr-style { series: { path } } with required: [series] and nested
required: [path], (3) Radarr-style { movie: { folderPath } } with required:
[movie] and nested required: [folderPath], and (4) other arr payloads like {
artist: { path } } and { author: { path } } each with the top-level required
property and nested required: [path]; this models the handler which returns 400
"Could not determine path" if none present. Also update the
DirScanTriggerResponse schema to include directoryId as an integer property and
mark both runId and directoryId as required so the documented response matches
the actual handler output.

---

Nitpick comments:
In `@internal/api/handlers/dirscan.go`:
- Around line 754-757: The response currently uses an untyped map in the
RespondJSON call; replace it with a concrete response struct (e.g.,
DirectoryScanResponse or StartScanResponse) that has fields RunID string
`json:"runId"` and DirectoryID string `json:"directoryId"`, populate it with the
existing runID and bestMatch.ID values, and pass that struct to RespondJSON so
the payload shape is compiler-checked (update any nearby type declarations or
exports as needed).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 8073cc62-8485-4938-af31-81ed67260a07

📥 Commits

Reviewing files that changed from the base of the PR and between 5a8f81a and c8ebe6f.

📒 Files selected for processing (5)

• AGENTS.md
• documentation/docs/features/cross-seed/dir-scan.md
• internal/api/handlers/dirscan.go
• internal/api/handlers/dirscan_webhook_test.go
• internal/web/swagger/openapi.yaml

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Keep the repo test guidance at -count=3.

This change weakens the project's stated Go test policy and makes it easier to miss flakes or race-dependent failures that only show up on repeated runs.

As per coding guidelines, "Always use -race and -count=3 flags when running Go tests to catch race conditions."

Also applies to: 88-88

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@AGENTS.md` at line 32, The test guidance was weakened by changing the
Makefile test command flags from "-race -count=3 -v" to "-race -count=1 -v";
revert or update the AGENTS.md entry for the "make test" instruction so it
explicitly uses "-race -count=3 -v" (and any other occurrences of "make test" or
the string "-count=1") to enforce the project's policy of running Go tests with
race detection and three repetitions.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

internal/web/swagger/openapi.yaml (1)

7589-7601: ⚠️ Potential issue | 🟠 Major

Fix the manual trigger response to match its OpenAPI contract.

The manual trigger handler at TriggerScan (line 371) returns only {"runId": runID}, but both endpoints (/api/dir-scan/directories/{directoryID}/scan and /api/dir-scan/webhook/scan) share the DirScanTriggerResponse schema which now requires both runId and directoryId. The webhook handler correctly returns both fields. Either update TriggerScan to return {runId, directoryId} or give each endpoint its own response schema.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@internal/web/swagger/openapi.yaml` around lines 7589 - 7601, TriggerScan
currently returns only {"runId": runID} but the shared OpenAPI schema
DirScanTriggerResponse requires both runId and directoryId; update the
TriggerScan handler to return an object including both runId and the matched
directoryId (the same shape returned by the webhook handler) so the response
matches DirScanTriggerResponse for the endpoints
/api/dir-scan/directories/{directoryID}/scan and /api/dir-scan/webhook/scan;
alternatively, if you prefer separate contracts, create a new response schema
for the manual TriggerScan endpoint and update its OpenAPI reference
accordingly.

🧹 Nitpick comments (1)

documentation/docs/features/cross-seed/dir-scan.md (1)

273-281: Show the 202 body here too.

The table lists the status codes, but external callers still need the actual success payload (runId and directoryId) to correlate the scan they just triggered. A tiny JSON example next to 202 would make this section self-contained.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@documentation/docs/features/cross-seed/dir-scan.md` around lines 273 - 281,
Add a small JSON success example for the `202` entry under the "Response codes"
table so callers see the response body used to correlate a started scan; update
the `202` row to include a tiny example payload showing {"runId": "<uuid>",
"directoryId": "<id>"} (or similar names used by the API) next to the
description for the `202` status in the "Response codes" section so consumers
know the exact fields to expect.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@internal/web/swagger/openapi.yaml`:
- Around line 7589-7601: TriggerScan currently returns only {"runId": runID} but
the shared OpenAPI schema DirScanTriggerResponse requires both runId and
directoryId; update the TriggerScan handler to return an object including both
runId and the matched directoryId (the same shape returned by the webhook
handler) so the response matches DirScanTriggerResponse for the endpoints
/api/dir-scan/directories/{directoryID}/scan and /api/dir-scan/webhook/scan;
alternatively, if you prefer separate contracts, create a new response schema
for the manual TriggerScan endpoint and update its OpenAPI reference
accordingly.

---

Nitpick comments:
In `@documentation/docs/features/cross-seed/dir-scan.md`:
- Around line 273-281: Add a small JSON success example for the `202` entry
under the "Response codes" table so callers see the response body used to
correlate a started scan; update the `202` row to include a tiny example payload
showing {"runId": "<uuid>", "directoryId": "<id>"} (or similar names used by the
API) next to the description for the `202` status in the "Response codes"
section so consumers know the exact fields to expect.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 2bf3d240-4b1f-470c-b510-b8721ce153ce

📥 Commits

Reviewing files that changed from the base of the PR and between c8ebe6f and 9429485.

📒 Files selected for processing (3)

• documentation/docs/features/cross-seed/dir-scan.md
• internal/api/handlers/dirscan.go
• internal/web/swagger/openapi.yaml

🚧 Files skipped from review as they are similar to previous changes (1)

• internal/api/handlers/dirscan.go

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@internal/api/handlers/dirscan.go`:
- Around line 371-375: The follow-up GetDirectory call after StartManualScan can
turn a successful scan start into a 500; instead, reuse the directory object you
already loaded during validation or load the directory before calling
StartManualScan so you never drop the successful start due to a later read
error. Concretely, in the dirscan handler replace the post-StartManualScan
GetDirectory usage with the previously validated directory variable (from your
validation step) or move the GetDirectory(dirID) call so it occurs before
calling h.service.StartManualScan; ensure StartManualScan remains responsible
for creating the run and only return a 500 if StartManualScan itself fails,
while returning success to the client when StartManualScan succeeds even if a
subsequent read would fail.

In `@internal/web/swagger/openapi.yaml`:
- Around line 3302-3308: The operation currently documents the apikey as a
normal optional query parameter named "apikey" but should model it as a security
alternative to the global SessionAuth; remove the regular parameter and add a
query apiKey security scheme (type: apiKey, in: query, name: apikey or apiKey)
in the OpenAPI components, then set this operation's security array to allow
either the existing SessionAuth or the new query ApiKey security scheme (e.g.,
security: - SessionAuth: [] - ApiKeyQuery: []); update references to the
parameter in this operation to use the security scheme and run make test-openapi
to validate the change.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 5d5493a1-3daf-4598-8d3b-899d2f02de23

📥 Commits

Reviewing files that changed from the base of the PR and between e582071 and 364191a.

📒 Files selected for processing (4)

• documentation/docs/features/cross-seed/dir-scan.md
• internal/api/handlers/dirscan.go
• internal/api/handlers/dirscan_webhook_test.go
• internal/web/swagger/openapi.yaml

🚧 Files skipped from review as they are similar to previous changes (1)

• internal/api/handlers/dirscan_webhook_test.go