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 at ae6a419a, 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 @ ae6a419a
health: 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:
Tejas Chopra
2026-10-10 09:05:53 -07:00
committed by GitHub
parent f14906e046
commit 5cac7ab693
2 changed files with 23 additions and 5 deletions
+3 -5
View File
@@ -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",
[