[Feature] : API ENDPOINTS PR 6 : Errors, Logs, and OpenAPI Documentation

[pulk17]

[FEATURE]

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.

---

Overview

Sixth PR of the CI API stack (#1130 → #1141, merge bottom-up). The debugging surface — structured errors and raw logs — plus the OpenAPI contract for the whole API and a contract-test suite that validates the implementation against it.

Endpoints

• GET /runs/{id}/errors — one structured ErrorItem per detected failure: exit_code_mismatch, diff_mismatch, or missing_output, each with severity, ids, and a human-readable message. There's no error table in the schema — errors are derived from result rows, using the same derivation as /runs/{id}/summary, so the two can never disagree on counts.
• GET /runs/{id}/error-summary — the same errors bucketed by ?group_by=type|sample_id|severity, with per-bucket counts, worst-seen severity, and first/last-seen timestamps. Useful for "what kind of failure dominates this run".
• GET /runs/{id}/infrastructure-errors — best-effort classification of canceled-run progress messages (VM provisioning, checkout, build, worker, storage). Explicitly excludes user-initiated cancellations. Best-effort because the CI worker has no structured error protocol yet — this is honest keyword matching, labeled as such.
• GET /runs/{id}/logs and GET /runs/{id}/samples/{sid}/logs — build and per-sample logs with cursor pagination (cursor = line offset; valid because logs are append-only). Log reads fall back utf-8 → cp1252 with errors='replace', so a stray byte can't 500 the endpoint.

The contract

• openapi-ci-api.yaml is the source of truth for the API. It documents every endpoint, parameter, response shape, and error body in the stack. The yaml defines its own component schemas; marshmallow schemas exist in code only where routes actually serialize through them — there is deliberately no parallel shadow copy of the contract in Python.

• scripts/verify_schemathesis.py runs property-based contract tests against the live app: broad fuzzing of every operation, per-endpoint response validation, negative auth testing (missing/invalid/expired/readonly tokens), and response invariants. It is not wired into CI — schemathesis is an unpinned, hypothesis-based dependency and would add flake risk to every PR. Run it locally:

  pip install schemathesis pytest
  TESTING=true pytest scripts/verify_schemathesis.py -x -v
  

Testing

21 new tests; 185 total at this layer. Error derivation (rc mismatch, diff, missing output — with and without expected-output rows), summary bucketing and severity escalation, infra-error classification and the via-API exclusion, log pagination cursors, and encoding fallbacks.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud