[Feature] : API ENDPOINTS PR 3 : System Status and Run Management Endpoints

[pulk17]

Please prefix your pull request with one of the following: [FEATURE] [FIX] [IMPROVEMENT].

In raising this pull request, I confirm the following (please check boxes):

• I have read and understood the contributors guide.
• I have checked that another pull request for this purpose does not exist.
• I have considered, and confirmed that this submission will be valuable to others.
• I accept that this submission may not be used, and the pull request closed at the will of the maintainer.
• I give this submission freely, and claim no ownership to its content.

My familiarity with the project is as follows (check one):

• I have never used the project.
• I have used the project briefly.
• I have used the project extensively, but have not contributed previously.
• I am an active contributor to the project.

---

Feature: System Status and Run Management Endpoints (PR 3/6)

Executive Summary

⚠️ Note for Reviewers: This PR is stacked on top of PR 2 (#). Please review PR 2 first.
Because this PR builds upon the foundation from PRs 1 & 2, GitHub currently shows the combined file changes. Once PR 2 is merged into master, this PR will automatically update to only show the System/Runs specific files.

This Pull Request is Part 3 of 6 in the initiative to introduce a fully-featured JSON REST API (superseding #1117).

This PR introduces the core domain logic for the platform: System Status Monitoring and CI Run Management. It enables CI runners and users to check platform health, fetch the available job queue, trigger new CI runs, and retrieve rich summaries of completed runs. Notably, this PR also re-introduces the global middleware tests which were deferred from PR 1, as the endpoints they test against now exist.

---

Architectural Additions & Enhancements

1. System Endpoints (mod_api/routes/system.py)

Mounted at /api/v1/system, this router exposes global platform capabilities:

• GET /health: Unauthenticated endpoint for load balancers and up-time monitors to verify API responsiveness.
• GET /queue: Allows CI runners with the system:read scope to query pending tests, with optional platform filtering (?platform=windows).
• GET /runs/<run_id>/artifacts: Given a completed run ID, this resolves and lists all accessible artifacts (logs, test outputs) checking both local disk and Google Cloud Storage (via the newly added storage service).

2. Run Management Endpoints (mod_api/routes/runs.py)

Mounted at /api/v1/runs, this handles the core CI lifecycle:

• POST / (Trigger Run): Allows users/bots with runs:write to trigger a new CI test run on specific commits. Enforces permissions (users can only trigger tests for their own forks unless they have admin/contributor status).
• GET / (List Runs): Cursor and offset paginated retrieval of historical CI runs with advanced filtering (?status=running, ?platform=linux).
• GET /<run_id>/summary: Aggregates a comprehensive JSON summary of a specific run, computing completion status, calculating duration, and aggregating infrastructure vs test failures (via the new error_service).
• POST /<run_id>/cancel: Securely aborts a running CI job.

3. Supporting Services

• storage.py: Handles cross-environment artifact resolution (Local file paths vs Google Cloud Storage blobs).
• error_service.py: Parses raw test results to deterministically attribute failures to either "infrastructure errors" (e.g. out of memory, timeout) or actual "test regressions".
• utils.py: Introduces pagination helpers and a highly secure _safe_resolve utility to prevent Path Traversal attacks when reading artifacts.

---

Testing & Quality Assurance

This PR significantly expands the active test suite:

• Middleware Integration Restored: The 4 critical global middleware tests (test_middleware_auth, error_handler, rate_limit, validation) deferred from PR 1 have been introduced and perfectly pass against the new system routes.
• Comprehensive Domain Coverage: 137 passing tests across the entire tests/api directory.
• Strict Permissions Verification: Tests explicitly assert that standard users cannot cancel others' runs, cannot trigger main-repository builds, and cannot query without appropriate token scopes.
• Linting & Type Safety: 100% CI compliance verified. isort, pydocstyle, pycodestyle, and mypy pass without errors.

Next Steps

Following the review and merge of this PR, PR 4 (Samples & Baseline Approvals) will be submitted, exposing endpoints to interact with individual media samples and manage baseline updates.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[cfsmp3]

HIGH:

• H2 — the C1 fix is only half-wired. The expected_outputs fix went into batch_get_run_data (run status), but get_run_summary and error_service still call the legacy is_dummy_row path (never matches). So for a run with missing output: derive_run_status says fail (right), but /summary counts it as pass with missing_output_count: 0, and /errors omits it. The endpoints contradict each other, and the headline bug resurfaces in the two endpoints users actually read. No test catches it.
• H3 — arbitrary-repo CI trigger (carryover #1117 H2). POST /runs: is_staff short-circuits ownership, repository is only regex-checked → a contributor can make the build VM clone+build any GitHub repo = arbitrary-code exec on CI infra. Gated by contributor role, but a real privilege expansion.
• H1 — migration still absent (3 PRs deep; all these routes are auth-gated so they need the token table too).

MEDIUM: cancel race (no row lock); status-filter 1000-cap drops rows + inconsistent total; summary total_samples never reconciles; _get_output_artifacts N+1 + paginates after full build; GCS signed URLs without blob.exists.

LOW/NIT: RunSummarySchema unused (raw dict, no contract); step:None dead field; queue hand-builds pagination; generic-exception→JSON path still untested.