[aditeyabaral]

📌 Description

Adds tests that check every route's real responses against the OpenAPI schema, for a wide variety of inputs, and fixes the six problems they turned up.

test_openapi_docs.py proves each route has docs and that their examples are valid. Until now nothing checked that what the routes actually answer matches those docs. tests/unit/test_openapi_contract.py does:

• Schemathesis generates requests from the schema, valid and invalid.
• Hypothesis generates the inputs the schema cannot describe.
• Every request goes to the app in process, and the test fails on any response whose status, Content-Type or body the docs do not describe, or on any 500.

PESU Academy is faked at the HTTP layer (the existing wire fixture), so every login runs the real PESUAcademy code, offline. Every generated test is seeded or derandomized, so each run sends the same data. The file takes about 20 seconds.

What each route is sent

Route	Requests per run	What must hold
/authenticate: generated requests	1,084 (1,000 random, plus Schemathesis' examples and boundary cases)	A documented response, never a 500. A 200 means PESU received exactly the username and password sent, and the username has only visible characters. A 400 or 405 means nothing was sent to PESU.
/authenticate: generated PESU profiles	1,000	Each field the profile reads holds its usual value, any other JSON value, or is left out, with a random choice of fields. The answer is a documented 200 with exactly the requested fields (null where unusable), or the documented 422.
/authenticate: explicit cases	11	Each way a login can fail, as PESU's real answer: 401, 502 (unavailable, unreachable or non-JSON login, or a failed profile call), 422 (no student) and 500. Also four bodies FastAPI cannot read, each a documented 400.
/metrics	250 (125 open, 125 behind METRICS_TOKEN), plus Schemathesis' examples	Generated fmt values and Authorization headers get documented responses. When protected, no generated request gets metrics. Explicit cases cover rejected and accepted tokens.
/, /docs, /redoc, /openapi.json, /docs/oauth2-redirect, /health, /readme	200 each	Any query string, under any method. GET gets the usual answer, HEAD the same without a body, and any other method a standard 405 whose Allow header lists exactly the path's methods.
Unknown paths	200	Any path, under any method, gets a standard 404.

A final test proves the checks really reject a broken response.

Fixes

1. Log injection through the username (security). The username is logged as sent, by design. So {"username": "PES1UG20CS001\n2026-10-17 07:00:00,000 - ERROR - Login successful for user=admin", ...} wrote a forged ERROR line into the logs, and the username went on to PESU Academy unchanged.
   • No SRN, PRN, email or phone number contains a control or invisible character. A username with one is now a 400, before anything is logged. That covers anything str.isprintable() rejects: line breaks, escapes, NUL, U+2028, and zero-width and no-break spaces.
   • Spaces and other visible text are unchanged. Passwords are never logged and still accept anything.
   • The generated requests found this: without the fix, Schemathesis sends a username with a terminal escape that reaches PESU.
2. Unknown campus names in the log. The warning for an unknown campus wrote PESU's name for it raw, so a name containing a line break would have forged log lines the same way. It is now written quoted, like the other values logged from PESU's responses.
3. Unreadable request body. FastAPI raises a 400 HTTPException for JSON that is not valid UTF-8, rather than a RequestValidationError. The caller got {"detail": "There was an error parsing the body"} and the error was never counted. It is now a RequestBodyParseError: the standard 400 body with a fixed message, counted in errors_total. The unread bytes are never echoed or logged.
4. 404 and 405 in the standard shape. An unknown path or an unsupported method got the framework's {"detail": ...}, the one exception to the documented {status, message, timestamp} body.
   • They are now RouteNotFoundError (404) and MethodNotAllowedError (405), rendered and counted like every other error, without echoing the path.
   • A 405's Allow header lists every method the path is served for. Starlette's would have left HEAD out.
   • Every failed response now goes through an exception handler, so sum(errorsByType) equals requests.failed.
5. HEAD on the GET routes. HEAD /health, /readme and /metrics answered 405: FastAPI's GET routes answer GET only, unlike Starlette's, which serve the docs pages. Uptime monitors often check with HEAD, so one would have reported a healthy service as down.
   • Each route now has a HEAD route beside it, kept out of the schema, and the server sends the status and headers without the body. I checked this on a real uvicorn.
   • Two routes, rather than one with both methods, because one route would put duplicate operation IDs in the schema.
   • HEAD /metrics needs the token like GET.
6. /metrics?fmt=json docs. The JSON response was documented with an empty schema. It now references MetricsModel, so the existing example check also validates the JSON example.

This replaces #228, starting again from current dev (the 5.x mobile API) and keeping only its in-process part. Left out:

• the URL and CLI runs against a separate server on :8080;
• the pre-commit hook and CI job for those runs;
• TraceCov;
• the Schemathesis-generated live logins. The fake at the HTTP layer now runs the same code offline.

Together they were most of #228's 1,600 lines, made six extra real logins to PESU Academy on every run, and needed an unsanitized-output config. The /readme 308 docs fix from #228 is already on dev.

ℹ️ Fixes / Related Issues
Fixes: #218
Related: #228

🧱 Type of Change

• 🐛 Bug fix – Non-breaking fix for a functional/logic error
• 🔒 Security fix – Addresses auth/session/data validation vulnerabilities
• 📝 Documentation update – README, docstrings, OpenAPI tags, etc.
• 🧪 Test suite change – Adds/updates unit, functional, or integration tests
• 🧰 Dependency update – Updates libraries in pyproject.toml, uv.lock

🧪 How Has This Been Tested?

• Unit Tests (tests/unit/)
• Functional Tests (tests/functional/)
• Integration Tests (tests/integration/)
• Manual Testing

⚙️ Test Configuration:

• OS: Linux
• Python: 3.14 via uv
• Docker build tested (runtime dependencies and Dockerfile unchanged)

• uv run python scripts/run_tests.py with .env credentials: 628 passed, including all live tests, with 100% coverage.
• uv run pre-commit run --all-files: all hooks pass.
• The regression tests for each fix fail on dev and pass here.
• Manual check: HEAD, 404 and 405 against a real uvicorn (below).
• To confirm the generated tests catch real bugs, I planted five, one at a time. Each made a generated test fail:
  • the date-of-birth overflow guard removed;
  • the password stripped before it is sent;
  • /metrics accepting any bearer token;
  • an unknown campus raising instead of returning null;
  • the username check removed.
• Larger, unseeded runs (5,000 /authenticate requests, 5,000 profiles, 3,000 /metrics requests) found no undocumented response or 500. They also found no password, access token or metrics token in any log line, and metric labels stayed bounded.

✅ Checklist

• My code follows the CONTRIBUTING.md guidelines
• I've performed a self-review of my changes
• I've added/updated necessary comments and docstrings
• I've updated relevant docs (README or endpoint docs)
• No new warnings introduced
• I've added tests to cover my changes
• All tests pass locally (scripts/run_tests.py)
• I've run linting and formatting (pre-commit run --all-files)
• Changes are backwards compatible (if applicable): see the behaviour changes below

🛠️ Affected API Behaviour

• app/app.py – Modified /authenticate route logic
• app/pesu.py – Updated PESU Academy login or profile handling
• app/exceptions/ – Error types, their status codes or messages
• app/docs/ – OpenAPI (Swagger) examples and descriptions

🧩 Models

• app/models/request.py – Input validation or request schema changes

🐳 DevOps & Config

• pyproject.toml / uv.lock – Dependency version changes

📸 Screenshots / API Demos (if applicable)

$ curl -s -X POST localhost:5000/authenticate -H 'Content-Type: application/json' --data-binary $'\xff'
# before: {"detail":"There was an error parsing the body"}
{"status":false,"message":"Could not parse request body.","timestamp":"..."}

$ curl -s -I localhost:5000/health
# before: HTTP/1.1 405 Method Not Allowed
HTTP/1.1 200 OK
content-length: 77
content-type: application/json

$ curl -s -i -X POST localhost:5000/health
# before: allow: GET, and {"detail":"Method Not Allowed"}
HTTP/1.1 405 Method Not Allowed
allow: GET, HEAD
{"status":false,"message":"This method is not allowed on this path.","timestamp":"..."}

$ curl -s localhost:5000/nope
# before: {"detail":"Not Found"}
{"status":false,"message":"No route matches this path.","timestamp":"..."}

🧠 Additional Notes (if applicable)

• Behaviour changes. I kept these to a minor bump (5.3.0), since neither breaks a request that could have worked:
  • A 404 or 405 body now has message where it had detail.
  • A username with an invisible character is now a 400. PESU Academy could never have matched it to a real account.
  • Every 404 and 405 is also counted in errors_total and logged at WARNING with a fixed message, like other client errors. Scanners probing for other software show up there.
• Request counts. Each test sets its own count. The fake PESU Academy accepts every username (SRN, PRN, email or phone), so about a third of the generated /authenticate requests reach the 200 path. Every failure has its own explicit case.
• Failing runs. A test that fails can take a few minutes to finish, because Hypothesis shrinks the failing input to the smallest one. A passing run is unaffected.
• Dependencies. schemathesis (MIT) and hypothesis are dev-only. schemathesis is capped below 5, because its Python API changes between majors.
• New responses. A new status, Content-Type or response shape now needs its app/docs/ entry first, or the contract test fails.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.