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

[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.

---

{pull request content here}# Feature: Errors, Logs, and OpenAPI Documentation (PR 6/6)

Executive Summary

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

This Pull Request is Part 6 of 6, marking the grand finale of the JSON REST API initiative! 🎉

This final piece introduces the endpoints necessary for diagnosing deep CI failures: the Errors & Logs services. It allows clients to query infrastructure errors, summarize failure metrics, and cleanly paginate through massive standard output logs without crashing the server.

Most importantly, it introduces the OpenAPI 3.1 Specification (openapi-ci-api.yaml), which fully documents the 25+ endpoints we have built across the previous 5 PRs, acting as the official contract for the platform.

---

Architectural Additions & Enhancements

1. Errors & Logs Endpoints (mod_api/routes/errors_logs.py)

Mounted at /api/v1/runs, this router finishes the diagnostic capabilities:

• GET /runs/<run_id>/errors: Fetches all structured test failures for a run, with extensive filtering (e.g., ?category=infrastructure, ?test_id=10).
• GET /runs/<run_id>/infrastructure-errors: Dedicated endpoint to pull critical platform-level faults (e.g., Out Of Memory, Network Timeouts) that ruined a CI run but aren't strictly algorithmic regressions.
• GET /runs/<run_id>/error-summary: Aggregates and buckets errors by type/code, allowing the UI to render charts (e.g., "50 tests failed due to 'Missing Output'").
• GET /runs/<run_id>/logs & /runs/<run_id>/samples/<sample_id>/logs: Exposes cursor-paginated access to the raw runner stdout/stderr logs (powered by the new log_service).

2. Log Service (mod_api/services/log_service.py)

• Safely reads large .log files off disk/storage without loading them entirely into memory.
• Implements line-based cursor pagination and string-contains filtering.

3. API Contract & Documentation

• openapi-ci-api.yaml: The definitive OpenAPI specification. Documents every route, expected status code, parameter, JSON schema, and OAuth2/Bearer Token security definition.
• verify_schemathesis.py: A massive 900+ line property-based testing suite utilizing schemathesis to formally verify that our actual API endpoints strictly adhere to the rules defined in our OpenAPI spec.

---

Testing & Quality Assurance

• The Final Test Count: The standard pytest suite sits at 189 perfectly passing tests.
• Contract Verification: The new verify_schemathesis.py test script performs rigorous stateful fuzz-testing against the endpoints using the OpenAPI spec as its rulebook. (Note: Since it requires schemathesis and hypothesis dependencies, it is currently intended to be run manually/separately, and is deliberately not auto-collected by standard pytest).
• Linting & Type Safety: 100% CI compliance verified. isort, pydocstyle, pycodestyle, and mypy pass perfectly across the entire mod_api/ and tests/api/ directories.

Conclusion

With this PR, the core CI Platform API is structurally complete! Clients, runners, and automated bots can now fully orchestrate the CI pipeline natively via HTTP/JSON. Thank you to all the reviewers who have pushed through these 6 PRs!

[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