mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
fix(gateway): report why /v1/compress/response rejected a body (#4081)
## Description `POST /v1/compress/response` (the response half of the gateway contract) caught every body-read failure and answered `"Invalid JSON in request body."`. That covered malformed JSON, but also an oversize body, a failed decompression, invalid UTF-8 and a JSON array. A Kong or LiteLLM integrator debugging a 400 could not tell which one it was. The other handlers (anthropic, openai, gemini, batch; about 10 call sites) already use `helpers.invalid_request_body_message(exc)`. It picks a fixed string by exception type, so it never echoes the exception text that CodeQL's `py/stack-trace-exposure` flags, and it logs the exception type on the proxy side. This handler now uses it too. That gives specific messages for malformed JSON, a non-object, invalid UTF-8 and an oversize body. A failed decompression (for example a bad gzip stream) still gets the generic `Invalid request body`, as it does on every other handler. A separate decompression message would mean changing the shared helper for all handlers, so that is out of scope here. The `if not isinstance(body, dict)` branch that followed is removed. `_read_request_json` raises `RequestBodyNotObject` for a non-object before it can return one, so the branch could not be reached. Its case is now reported as `Invalid request body: must be a JSON object`. The status code (400) and the error `type` (`invalid_request`) are unchanged. Only the `message` text differs. No test, doc or consumer repo matched on the old string: I grepped `tests`, `docs`, `headroom` and the gateway integrations, which branch on the status code. Refs #4136 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/proxy/gateway_turn.py`: `handle_compress_response` answers 400 with `invalid_request_body_message(exc)`, and the unreachable non-dict check is gone. - `tests/gateway/test_contract_response_half.py`: add `test_invalid_body_400_says_why`, parametrized over three bodies. Each case asserts a 400, `invalid_request`, and a message that names the reason: - malformed JSON; - a JSON array; - invalid UTF-8. All three cases fail on main. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ pytest -q -p no:cacheprovider tests/gateway/test_contract_response_half.py -k invalid # before the fix FAILED tests/gateway/test_contract_response_half.py::test_invalid_body_400_says_why[malformed] FAILED tests/gateway/test_contract_response_half.py::test_invalid_body_400_says_why[not-object] FAILED tests/gateway/test_contract_response_half.py::test_invalid_body_400_says_why[not-utf8] ================== 3 failed, 6 passed, 28 deselected in 7.18s ================== $ pytest -q -p no:cacheprovider tests/gateway/ tests/test_gateway_turn_unit.py tests/test_invalid_request_body_message.py # after ================== 323 passed, 4 skipped in 171.41s (0:02:51) ================== $ uvx ruff@0.16.8 check headroom/proxy/gateway_turn.py tests/gateway/test_contract_response_half.py All checks passed! $ mypy headroom/proxy/gateway_turn.py --ignore-missing-imports Success: no issues found in 1 source file ``` ## Real Behavior Proof - Environment: macOS, Python 3.12.13, branch checkout atae6a419a, using the repo .venv. A temp HOME, workspace and CODEX_HOME were used, with offline mode on. - Exact command / steps: 1. Ran the shared smoke harness, which starts a real proxy from this checkout against a local fake upstream and sends one Anthropic and one OpenAI request. 2. Started a real proxy with `python -m headroom.cli proxy --port <p>` and used curl to POST five bodies to `http://127.0.0.1:<p>/v1/compress/response`: four bad ones, and one valid body with an unknown turn as a control. - Observed result: ```text branch: cleanup/proxy-core-a-compress-response-errors @ae6a419ahealth: 200 POST /v1/messages -> HTTP200 smoke-ok POST /v1/chat/completions -> HTTP200 smoke-ok stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82 proxy.log WARNING/ERROR lines (<tmp>): (smoke dir: <tmp>) ``` ```text malformed JSON -> {"error":{"type":"invalid_request","message":"Invalid request body: malformed JSON"}} HTTP400 JSON array -> {"error":{"type":"invalid_request","message":"Invalid request body: must be a JSON object"}} HTTP400 invalid UTF-8 -> {"error":{"type":"invalid_request","message":"Invalid request body: not valid UTF-8 (possibly compressed?)"}} HTTP400 bad gzip -> {"error":{"type":"invalid_request","message":"Invalid request body"}} HTTP400 valid, unknown turn -> {"error":{"type":"unknown_turn","message":"No pending turn 't-x' (never registered, already finished, or expired)."}} HTTP404 ``` Every bad body is a 400 with type `invalid_request`, and the message names the reason. The exception is bad gzip, which gets the generic message, as on every other handler. On main, all four said `Invalid JSON in request body.`. The control request still reaches turn lookup (404 `unknown_turn`). - Not tested: A live Kong or LiteLLM gateway. Both key on the status and `type`, which are unchanged. ## Runtime Rollout Safety - Rollout-managed feature(s): None (the gateway contract is controlled by `HEADROOM_GATEWAY_CONTRACT`, unchanged). - Minimum rollout channel: N/A; error-message text only. - Stable/default behavior changed: Only the `error.message` text on a 400 for a bad body. The status, error type and every success path are unchanged. - Kill switch / disable path: N/A. - Unsafe override required: No. - Qualification impact: None. - Rollback path: Revert this commit. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [ ] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Screenshots (if applicable) N/A ## Additional Notes Part of a maintainer-requested codebase cleanup (dead code, duplication, debuggability), split into small PRs for review. It is part of maintainer-requested cleanup #4136. No docs quote the old message, so none needed changing. The change is small and self-explanatory, so no new comments were added. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This commit is contained in:
@@ -1494,14 +1494,12 @@ async def handle_compress_response(proxy: Any, request: Any) -> Any:
|
||||
"""``POST /v1/compress/response`` — finish or re-drive a pending turn."""
|
||||
from fastapi.responses import JSONResponse
|
||||
|
||||
from headroom.proxy.helpers import _read_request_json
|
||||
from headroom.proxy.helpers import _read_request_json, invalid_request_body_message
|
||||
|
||||
try:
|
||||
body = await _read_request_json(request)
|
||||
except Exception:
|
||||
return _error(400, "invalid_request", "Invalid JSON in request body.")
|
||||
if not isinstance(body, dict):
|
||||
return _error(400, "invalid_request", "Request body must be a JSON object.")
|
||||
except Exception as exc:
|
||||
return _error(400, "invalid_request", invalid_request_body_message(exc))
|
||||
|
||||
turn_id = body.get("turn_id")
|
||||
if not isinstance(turn_id, str) or not turn_id.strip() or len(turn_id) > 128:
|
||||
|
||||
@@ -104,6 +104,26 @@ def test_invalid_json_is_400(headroom_client) -> None:
|
||||
assert resp.status_code == 400
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("content", "reason"),
|
||||
[
|
||||
(b"nope", "malformed JSON"),
|
||||
(b"[1, 2]", "must be a JSON object"),
|
||||
(b"\xff\xfe{}", "not valid UTF-8"),
|
||||
],
|
||||
ids=["malformed", "not-object", "not-utf8"],
|
||||
)
|
||||
def test_invalid_body_400_says_why(headroom_client, content: bytes, reason: str) -> None:
|
||||
"""The 400 names the reason, like every other handler's body errors."""
|
||||
resp = headroom_client.post(
|
||||
RESPONSE_HALF, content=content, headers={"content-type": "application/json"}
|
||||
)
|
||||
assert resp.status_code == 400
|
||||
error = resp.json()["error"]
|
||||
assert error["type"] == "invalid_request"
|
||||
assert reason in error["message"]
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"extra",
|
||||
[
|
||||
|
||||
Reference in New Issue
Block a user