refactor(api): deduplicate sources router

[lfnovo]

What

Pure structural deduplication of api/routers/sources.py (1113 → 1075 lines; −318/+280 in the router). No behavior change: same status codes, same error messages, same response shapes.

Deduplications

• _source_to_response() — the SourceResponse(...) constructor with the nested AssetModel(...) if source.asset else None ternary was hand-rolled 5× (async create, sync create, get, update, retry). Any new response field required five edits. Endpoint-specific fields (command_id, status, processing_info, notebooks, file_available) are passed as overrides.
• _cleanup_uploaded_file() — the if file_path and upload_file: try: os.unlink(...) ritual was pasted 6× inside create_source(). The three copies inside the sync/async branches were redundant: every failure path re-raises into the outer exception handlers, which perform the same (idempotent, error-swallowing) cleanup. Now there are exactly the three outer call sites.
• create_source() split (was 293 lines): notebook/transformation validation stays in the endpoint; type-specific input validation moved to _build_content_state() (this is where the SSRF and LFI guards live); the two processing branches became _create_source_async_path() / _create_source_sync_path().
• Unified paginated list query in get_sources() — the with/without-notebook-filter queries were identical except for the FROM clause and bound params.

Security checks preserved verbatim

This file contains deliberate security code, all kept exactly as-is (code + issue-referencing comments):

• Atomic filename claim via touch(exist_ok=False) (O_EXCL) in generate_unique_filename() — covered by tests/test_upload_toctou_race.py
• Path-traversal validation on write (generate_unique_filename) and read (_resolve_source_file, _is_source_file_available) — covered by tests/test_source_path_containment.py and tests/test_upload_type_mitigations.py
• SSRF guard (validate_url) and LFI uploads-directory containment in the (moved, not modified) content-state builder — covered by tests/test_sources_api.py / tests/test_source_create_array_limits.py paths
• Blanket except-blocks' semantics intentionally untouched (candidate for a separate PR)

Verification

• uv run pytest tests/ — 403 passed (including the TOCTOU race, path-containment and upload-mitigation regression suites)
• ruff check . — clean; ruff format --check — clean
• mypy api/routers/sources.py — 25 pre-existing errors in dependencies, 0 in this file, identical count on main (no regression)

[cubic-dev-ai]

1 issue found across 2 files

Confidence score: 5/5

• In api/routers/sources.py, the router refactor is missing its ADR and approved-issue linkage, which could make the design rationale hard to recover later and slow future maintenance or rollback decisions; add the ADR and link the assigned issue before merging.

_{You’re at about 92% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="api/routers/sources.py">

<violation number="1" location="api/routers/sources.py:337">
P3: This sizeable structural router refactor lacks the required decision record and approved-issue reference. Add the ADR (and link the assigned issue) before merging so the new router structure and rationale are traceable.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: This sizeable structural router refactor lacks the required decision record and approved-issue reference. Add the ADR (and link the assigned issue) before merging so the new router structure and rationale are traceable.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At api/routers/sources.py, line 337:

<comment>This sizeable structural router refactor lacks the required decision record and approved-issue reference. Add the ADR (and link the assigned issue) before merging so the new router structure and rationale are traceable.</comment>

<file context>
@@ -348,6 +334,251 @@ async def get_sources(
         raise HTTPException(status_code=500, detail="Error fetching sources")
 
 
+def _source_to_response(
+    source: Source, embedded_chunks: int = 0, **extras: Any
+) -> SourceResponse:
</file context>