Files
headroom/tests/test_proxy/test_transformations_feed.py
gglucass 46ac52d39d feat(proxy): let /transformations/feed omit message bodies for number-only pollers (#3672)
## Description

`/transformations/feed` always returns `request_messages`,
`compressed_messages` and `response_content` for every entry, and
`RequestLogger.get_recent_with_messages` builds them with `asdict()`,
which deep-copies each transcript first. A poller that only reads the
per-request numbers (tokens, model, transforms) still pays for a full
copy and a multi-MB JSON serialization on the event loop for each pull.
Measured on a desktop client polling every 20 s: a `limit=100` pull is
~44 MB, of which ~400 bytes per entry are read, and three concurrent
pulls take `/stats?cached=1` from 45 ms to 1.3 s.

This adds `?include_messages=0` (default `1`, byte-identical output to
today). When off, the three body fields are omitted from the response
and never walked server-side.

Closes #

## Type of Change

- [x] Performance improvement

## Changes Made

- `RequestLogger.get_recent_with_messages(n, include_messages=True)`:
when `False`, builds each entry from the dataclass fields minus the
three payload fields, deep-copying only what it returns (same idiom as
#3613 for `get_recent`).
- `/transformations/feed` accepts `include_messages: bool = True` and
omits the three body keys when it is off. Everything else in the item,
including `log_full_messages`, is unchanged.
- Each item also carries `uncached_input_tokens`, `cache_write_tokens`
and `cache_read_tokens` (already stored on `RequestLog`, never exposed
by the feed). A number-only poller can then rate `tokens_saved` against
new input (uncached + cache_write) the way `/stats`
`new_input_savings_percent` does; the item's full-transcript
`savings_percent` is unchanged. Present in both the full and the slim
response.
- Tests: logger test proves the payloads are not traversed (a leaf whose
`__deepcopy__` raises); endpoint test proves the slim item equals the
full item minus the three keys and carries the cache split.

## 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
$ uv run --frozen --extra dev pytest tests/test_proxy/test_transformations_feed.py tests/test_proxy/test_request_logger.py -q
9 passed in 4.53s
$ uvx ruff check headroom/proxy/request_logger.py headroom/proxy/server.py tests/test_proxy/test_transformations_feed.py tests/test_proxy/test_request_logger.py
All checks passed!
$ uv run --frozen --extra dev mypy headroom/proxy/request_logger.py headroom/proxy/server.py
Success: no issues found in 2 source files
```

## Real Behavior Proof

- Environment: macOS 15, Python 3.12, this branch, in-process
`RequestLogger` seeded with 100 entries carrying ~160 KB of messages
each (the size of a mid-session Claude Code turn).
- Exact command / steps: `get_recent_with_messages(100)` and
`get_recent_with_messages(100, include_messages=False)`, timed, then
`json.dumps` of each result, timed and sized.
- Observed result: include_messages=True: copy 29.4 ms, json 56.5 ms,
24.45 MB. include_messages=False: copy 1.3 ms, json 1.9 ms, 0.05 MB.
Same 100 entries, same numeric fields.
- Not tested: the dashboard UI (it does not pass the parameter, so it
gets the default, unchanged response).

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a (opt-in query parameter)
- Stable/default behavior changed: additive only; without the parameter
every existing key is byte-identical, and three integer keys are added
to each item
- Kill switch / disable path: callers stop passing `include_messages=0`
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the commit; no persisted state or schema
involved

## 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
- [x] 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

- Documentation: the endpoint has no reference page; the parameter is
documented in the handler docstring.
- Overlaps #3613 on the `_HEAVY_FIELDS` constant and the import lines;
both hunks are identical so either merge order applies cleanly.
2026-09-23 23:12:15 -05:00

123 lines
4.5 KiB
Python

"""Tests for the /transformations/feed endpoint in the proxy server."""
import pytest
# Skip if fastapi not available
pytest.importorskip("fastapi")
from httpx import ASGITransport, AsyncClient
from headroom.proxy.models import RequestLog
from headroom.proxy.server import create_app
@pytest.fixture
def app():
return create_app()
@pytest.mark.asyncio
async def test_transformations_feed_endpoint_returns_list(app):
"""The endpoint should return a list of recent transformations."""
async with AsyncClient(
transport=ASGITransport(app=app, client=("127.0.0.1", 12345)),
base_url="http://127.0.0.1",
) as client:
response = await client.get("/transformations/feed")
assert response.status_code == 200
data = response.json()
assert isinstance(data, dict)
assert "transformations" in data
assert isinstance(data["transformations"], list)
@pytest.mark.asyncio
async def test_transformations_feed_returns_messages(app):
"""Each transformation exposes both the original request and the
post-compression form that was actually sent upstream, plus the response.
The pre/post pair is what makes compression legible: consumers can diff
the two to see what the pipeline stripped, replaced, or kept.
"""
async with AsyncClient(
transport=ASGITransport(app=app, client=("127.0.0.1", 12345)),
base_url="http://127.0.0.1",
) as client:
response = await client.get("/transformations/feed")
data = response.json()
transformations = data["transformations"]
for t in transformations:
assert "request_messages" in t
assert t["request_messages"] is None or isinstance(t["request_messages"], list)
assert "compressed_messages" in t
assert t["compressed_messages"] is None or isinstance(t["compressed_messages"], list)
assert "response_content" in t
assert t["response_content"] is None or isinstance(t["response_content"], str)
@pytest.mark.asyncio
async def test_transformations_feed_respects_limit(app):
"""The endpoint should respect a ?limit= query parameter."""
async with AsyncClient(
transport=ASGITransport(app=app, client=("127.0.0.1", 12345)),
base_url="http://127.0.0.1",
) as client:
response = await client.get("/transformations/feed?limit=5")
data = response.json()
assert len(data["transformations"]) <= 5
@pytest.mark.asyncio
async def test_transformations_feed_can_omit_message_bodies(app):
"""``?include_messages=0`` is for pollers that only read the numbers: the
three body fields are absent (not null) and every other field is the same
as the full response."""
app.state.proxy.logger.log(
RequestLog(
request_id="r1",
timestamp="2026-04-24T10:00:00Z",
provider="anthropic",
model="claude-sonnet-4-6",
input_tokens_original=100,
input_tokens_optimized=40,
output_tokens=10,
tokens_saved=60,
savings_percent=60.0,
optimization_latency_ms=1.0,
total_latency_ms=20.0,
tags={},
cache_hit=False,
transforms_applied=["kompress:user:0.4"],
cache_read_tokens=1000,
cache_write_tokens=5,
uncached_input_tokens=30,
request_messages=[{"role": "user", "content": "hi"}],
compressed_messages=[{"role": "user", "content": "hi"}],
response_content="ok",
)
)
async with AsyncClient(
transport=ASGITransport(app=app, client=("127.0.0.1", 12345)),
base_url="http://127.0.0.1",
) as client:
full = (await client.get("/transformations/feed?limit=1")).json()
slim = (await client.get("/transformations/feed?limit=1&include_messages=0")).json()
full_item = full["transformations"][0]
slim_item = slim["transformations"][0]
assert full_item["request_messages"] == [{"role": "user", "content": "hi"}]
bodies = {"request_messages", "compressed_messages", "response_content"}
assert not bodies & slim_item.keys()
# The prefix-cache split rides along, so a poller can rate tokens_saved
# against new input (uncached + cache_write) like /stats does.
assert (
slim_item["uncached_input_tokens"],
slim_item["cache_write_tokens"],
slim_item["cache_read_tokens"],
) == (30, 5, 1000)
assert {k: v for k, v in full_item.items() if k not in bodies} == slim_item
assert slim["log_full_messages"] == full["log_full_messages"]