refactor(proxy): remove test-only and dead helpers from the handlers

Removes handler helpers nothing in production calls:

- _compact_openai_tool_schema_value (openai.py): no callers at all.
- StreamingMixin._parse_sse_usage: the single-chunk parser. Production only uses _parse_sse_usage_from_buffer; the two tests that called the chunk parser now drive the buffered one.
- _sse_contains_error_event (streaming.py): a wrapper over _sse_event_outcome used only by test_route_advice.py, which now carries it as a local helper.
- GeminiHandlerMixin._count_texts_offloaded: its tests now call headroom.proxy.token_counting.count_texts_offloaded directly with the proxy as owner.

Also drops test_codex_ws_emits_perf_log_with_cache_keys, which skipped
unconditionally, along with the fixtures only it used.

Evidence: grep across headroom, tests, crates, plugins, sdk, examples,
benchmarks, scripts, e2e, docs, wiki, .github and all consumer repos
finds no caller outside tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Assisted-by: claude-code:claude-opus-5-5
Headline-Session: 6e77a807-8dd4-4a77-a2fa-ddce6dc2515e
Headline-AI-Share: 7% strict / 7% weighted
This commit is contained in:
Tejas Chopra
2026-10-09 18:04:16 -07:00
co-authored by Claude Opus 5.5
parent a9815bbb5f
commit c15e679e85
8 changed files with 19 additions and 265 deletions
-5
View File
@@ -62,11 +62,6 @@ class GeminiHandlerMixin:
return await count_tokens_offloaded(self, model, messages)
async def _count_texts_offloaded(self, model, texts): # noqa: ANN001, ANN201
from headroom.proxy.token_counting import count_texts_offloaded
return await count_texts_offloaded(self, model, texts)
def _gemini_replay_forwarded_prefix(
self,
optimized_messages: list[dict],
-10
View File
@@ -898,16 +898,6 @@ def _shape_openai_responses_payload(
return [], False
def _compact_openai_tool_schema_value(
value: Any,
_parent_key: str | None = None,
) -> Any:
# Delegate to shared compaction logic.
from headroom.proxy.tool_schema_compaction import compact_tool_schema_value
return compact_tool_schema_value(value, _parent_key)
def _compact_openai_responses_tools(
payload: dict[str, Any],
) -> tuple[dict[str, Any], bool, int, int]:
-102
View File
@@ -132,15 +132,6 @@ def _sse_event_outcome(event_name: str | None, data_str: str, dialect: str) -> t
return failed, terminal
def _sse_contains_error_event(payload: bytes) -> bool:
from headroom.proxy.helpers import parse_sse_events_from_byte_buffer
return any(
_sse_event_outcome(event_name, data, "chat")[0]
for event_name, data in parse_sse_events_from_byte_buffer(bytearray(payload))
)
_ROUND_USAGE_KEYS = (
"input_tokens",
"output_tokens",
@@ -320,99 +311,6 @@ class StreamingMixin:
int(cache_creation.get("ephemeral_1h_input_tokens", 0) or 0),
)
def _parse_sse_usage(self, chunk: bytes, provider: str) -> dict[str, int] | None:
"""Parse usage information from SSE chunk.
For Anthropic: Looks for message_start (input tokens) and message_delta (output tokens)
For OpenAI: Looks for final chunk with usage object (requires stream_options.include_usage=true)
For Gemini: Looks for usageMetadata in each chunk
Returns dict with keys: input_tokens, output_tokens, cache_read_input_tokens,
cache_creation_input_tokens, cache_creation_ephemeral_5m_input_tokens,
cache_creation_ephemeral_1h_input_tokens
Returns None if no usage found in this chunk.
PR-A8 / P1-8: Decoded via the bytes-buffer SSE splitter so multi-byte
characters split across TCP reads do not corrupt downstream parsing.
Only complete events (terminated by ``\\n\\n``) are decoded; partial
bytes are dropped (this method is single-chunk only — the buffered
path is in ``_parse_sse_usage_from_buffer``).
"""
from headroom.proxy.helpers import parse_sse_events_from_byte_buffer
try:
buf = bytearray(chunk)
events = parse_sse_events_from_byte_buffer(buf)
for _event_name, data_str in events:
if not data_str or data_str == "[DONE]":
continue
try:
data = json.loads(data_str)
except json.JSONDecodeError:
continue
if not isinstance(data, dict):
continue
usage = {}
if provider == "anthropic":
# Anthropic sends message_start with input tokens
# and message_delta with output tokens
event_type = data.get("type", "")
if event_type == "message_start":
msg_usage = _sse_dict(_sse_dict(data.get("message")).get("usage"))
if msg_usage:
usage["input_tokens"] = msg_usage.get("input_tokens", 0)
usage["cache_read_input_tokens"] = msg_usage.get(
"cache_read_input_tokens", 0
)
usage["cache_creation_input_tokens"] = msg_usage.get(
"cache_creation_input_tokens", 0
)
cache_write_5m, cache_write_1h = (
self._extract_anthropic_cache_ttl_metrics(msg_usage)
)
usage["cache_creation_ephemeral_5m_input_tokens"] = cache_write_5m
usage["cache_creation_ephemeral_1h_input_tokens"] = cache_write_1h
elif event_type == "message_delta":
delta_usage = _sse_dict(data.get("usage"))
if delta_usage:
usage["output_tokens"] = delta_usage.get("output_tokens", 0)
elif provider == "openai":
# OpenAI sends usage in final chunk (when stream_options.include_usage=true)
chunk_usage = _sse_dict(data.get("usage"))
if chunk_usage:
usage["input_tokens"] = chunk_usage.get("prompt_tokens", 0)
usage["output_tokens"] = chunk_usage.get("completion_tokens", 0)
# OpenAI has cached tokens in prompt_tokens_details
details = _sse_dict(chunk_usage.get("prompt_tokens_details"))
usage["cache_read_input_tokens"] = details.get("cached_tokens", 0)
elif provider == "gemini":
# Gemini sends usageMetadata in each streaming chunk
# Format: {"usageMetadata": {"promptTokenCount": N, "candidatesTokenCount": M}}
usage_meta = _sse_dict(data.get("usageMetadata"))
if usage_meta:
usage["input_tokens"] = usage_meta.get("promptTokenCount", 0)
usage["output_tokens"] = gemini_output_tokens(usage_meta)
# Gemini also has cachedContentTokenCount for context caching
usage["cache_read_input_tokens"] = usage_meta.get(
"cachedContentTokenCount", 0
)
if usage:
return usage
except (UnicodeDecodeError, KeyError, TypeError) as e:
# Don't fail streaming on parse errors
logger.debug(f"SSE usage parsing error for {provider}: {e}")
return None
def _parse_sse_usage_from_buffer(
self, stream_state: dict[str, Any], provider: str
) -> dict[str, int] | None:
@@ -23,12 +23,9 @@ either bottleneck.
from __future__ import annotations
import concurrent.futures
import logging
import sys
import time
from pathlib import Path
from types import SimpleNamespace
from unittest.mock import MagicMock
import pytest
@@ -90,123 +87,6 @@ def test_no_per_call_threadpool_inside_compress_routed_units() -> None:
)
# ── PERF log emission from the Codex WS path ────────────────────────────
#
# Codex WS traffic was invisible to ``headroom perf`` pre-fix because
# ``handle_openai_responses_ws`` emitted no PERF line. This is structurally
# the same bug class as #327's "Cache write: 0" for backend-routed
# streaming — the request is processed correctly but the operator can't
# see it. The new PERF emit closes that visibility gap.
class _DirectLogCapture(logging.Handler):
"""Direct handler attached to ``headroom.proxy`` so the proxy's
propagation flip in ``_setup_file_logging`` does not strip records.
Same pattern as ``tests/test_backend_streaming_cache_metrics.py`` —
see that file for the rationale.
"""
def __init__(self) -> None:
super().__init__(level=logging.INFO)
self.records: list[logging.LogRecord] = []
def emit(self, record: logging.LogRecord) -> None:
self.records.append(record)
def _attach_proxy_log_capture() -> tuple[_DirectLogCapture, logging.Logger, int]:
handler = _DirectLogCapture()
target = logging.getLogger("headroom.proxy")
target.addHandler(handler)
prior_level = target.level
target.setLevel(logging.INFO)
return handler, target, prior_level
def _detach_proxy_log_capture(handler, target, prior_level) -> None:
target.removeHandler(handler)
target.setLevel(prior_level)
def _make_perf_log_test_handler():
"""Build a minimal handler that lets us drive the PERF emit code path
of ``handle_openai_responses_ws`` end-to-end without a real upstream.
Imported lazily so a collection-time import error in the proxy module
does not break the source-level regression guards above.
"""
from headroom.proxy.handlers.openai import OpenAIHandlerMixin
from headroom.proxy.ws_session_registry import WebSocketSessionRegistry
class _M(OpenAIHandlerMixin):
OPENAI_API_URL = "https://api.openai.com"
def __init__(self) -> None:
self.rate_limiter = None
self.metrics = SimpleNamespace(
record_request=lambda **kw: None,
record_stage_timings=lambda *a, **kw: None,
inc_active_ws_sessions=lambda: None,
dec_active_ws_sessions=lambda: None,
inc_active_relay_tasks=lambda n=1: None,
dec_active_relay_tasks=lambda n=1: None,
record_ws_session_duration=lambda *a, **kw: None,
record_codex_ws_unit=lambda **kw: None,
)
self.config = SimpleNamespace(
optimize=True,
retry_max_attempts=1,
retry_base_delay_ms=1,
retry_max_delay_ms=1,
connect_timeout_seconds=10,
log_full_messages=False,
)
self.usage_reporter = None
self.openai_provider = SimpleNamespace(
get_context_limit=lambda model: 128_000,
get_token_counter=lambda model: SimpleNamespace(
count_text=lambda text: max(1, len(text) // 4),
count_messages=lambda *a, **k: 0,
),
)
self.openai_pipeline = SimpleNamespace(apply=MagicMock(), transforms=[])
self.anthropic_backend = None
self.cost_tracker = None
self.memory_handler = None
self.ws_sessions = WebSocketSessionRegistry()
self.logger = None
self.compression_executor_calls = 0
async def _next_request_id(self) -> str:
return "req-perf-emit-test"
async def _run_compression_in_executor(self, fn, *, timeout: float):
self.compression_executor_calls += 1
return fn()
return _M()
@pytest.mark.asyncio
async def test_codex_ws_emits_perf_log_with_cache_keys() -> None:
"""``handle_openai_responses_ws`` must emit a PERF line so ``headroom
perf`` counts Codex traffic instead of reporting it as zero requests.
Asserts on the structured-PERF kv fragment used by ``headroom/perf/
analyzer.py`` (``cache_read=`` / ``cache_write=`` / ``cache_hit_pct=``)
so the analyzer parser actually picks it up.
"""
pytest.skip(
"Pending: full WS lifecycle harness for handle_openai_responses_ws "
"needs a fuller FakeWebSocket+FakeUpstream wire-up than this file "
"owns. The PERF emit is verified via Tier-3 replay + Tier-4 manual "
"smoke; the source-level guards above prevent the emit from being "
"removed silently. Re-enable when the WS lifecycle harness in "
"test_openai_codex_ws_lifecycle.py is reused as a fixture."
)
# ── Concurrency stress (Tier 2) ─────────────────────────────────────────
#
# The smoking gun: with the old code, 30 concurrent calls to
+1 -1
View File
@@ -313,7 +313,7 @@ def test_streaming_parser_extracts_anthropic_ttl_bucket_usage() -> None:
b'"cache_read_input_tokens":3,"cache_creation_input_tokens":9,'
b'"cache_creation":{"ephemeral_5m_input_tokens":4,"ephemeral_1h_input_tokens":5}}}}\n\n'
)
usage = proxy._parse_sse_usage(chunk, "anthropic")
usage = proxy._parse_sse_usage_from_buffer({"sse_buffer": bytearray(chunk)}, "anthropic")
assert usage is not None
assert usage["cache_creation_ephemeral_5m_input_tokens"] == 4
+11 -8
View File
@@ -26,6 +26,17 @@ class _Req:
DEFAULT = object() # stands in for the configured backend
def _sse_contains_error_event(payload: bytes) -> bool:
"""True when any complete SSE event in ``payload`` is a failure event."""
from headroom.proxy.handlers.streaming import _sse_event_outcome
from headroom.proxy.helpers import parse_sse_events_from_byte_buffer
return any(
_sse_event_outcome(event_name, data, "chat")[0]
for event_name, data in parse_sse_events_from_byte_buffer(bytearray(payload))
)
# --- reading what an extension published ------------------------------------
@@ -336,22 +347,16 @@ def test_stream_outcome_status_preserves_success_and_reclassifies_failure():
def test_sse_error_detection_handles_native_and_split_events():
from headroom.proxy.handlers.streaming import _sse_contains_error_event
assert _sse_contains_error_event(b'event: error\ndata: {"type":"error"}\n\n')
assert _sse_contains_error_event(b'data: {"type":"er' + b'ror"}\n\n')
assert not _sse_contains_error_event(b'data: {"type":"message"}\n\n')
def test_sse_error_text_in_response_content_is_not_an_error():
from headroom.proxy.handlers.streaming import _sse_contains_error_event
assert not _sse_contains_error_event(b'data: {"text":"event: error"}\n\n')
def test_responses_failed_envelope_is_an_error():
from headroom.proxy.handlers.streaming import _sse_contains_error_event
assert _sse_contains_error_event(
b'data: {"type":"response.failed","response":{"status":"failed",'
b'"error":{"code":"server_error"}}}\n\n'
@@ -476,8 +481,6 @@ def test_responses_terminal_semantics(event, data, expected_failed, expected_ter
@pytest.mark.parametrize("event_type", ['["error"]', '{"unexpected":true}', "7", "true"])
def test_malformed_event_type_is_not_interpreted_as_a_protocol_marker(event_type):
from headroom.proxy.handlers.streaming import _sse_contains_error_event
payload = ('data: {"type":' + event_type + "}\n\ndata: [DONE]\n\n").encode()
assert not _sse_contains_error_event(payload)
+4 -16
View File
@@ -1,7 +1,7 @@
"""Malformed-upstream tolerance for SSE event parsing.
Three parsers read upstream-controlled SSE bodies: ``_parse_sse_usage``,
``_parse_sse_usage_from_buffer`` and ``_parse_sse_to_response``. A valid-JSON
Two parsers read upstream-controlled SSE bodies: ``_parse_sse_usage_from_buffer``
and ``_parse_sse_to_response``. A valid-JSON
event of unexpected *shape* must be skipped rather than raise. In
``_parse_sse_to_response`` the raise escapes into ``_finalize_stream_response``
and tears down a stream the client is already reading.
@@ -233,11 +233,6 @@ def _usage(payload: str, provider: str = "anthropic") -> dict[str, int] | None:
)
def _usage_chunk(payload: str, provider: str = "anthropic") -> dict[str, int] | None:
"""Run the single-chunk usage parser (the third, previously unguarded one)."""
return _Handler()._parse_sse_usage(payload.encode(), provider)
def _response(payload: str, provider: str = "anthropic") -> dict[str, Any] | None:
return _Handler()._parse_sse_to_response(payload, provider)
@@ -552,7 +547,7 @@ def test_message_start_wrong_shape_still_yields_later_usage(bad: Any) -> None:
# ---------------------------------------------------------------------------
# The two usage parsers, across every provider branch.
# The usage parser, across every provider branch.
# ---------------------------------------------------------------------------
_USAGE_POSITIONS = [
@@ -573,18 +568,11 @@ def test_buffered_usage_parser_survives_wrong_shape(provider: str, build: Any, b
_usage(_frame("x", build(bad)), provider)
@pytest.mark.parametrize("provider,build", _USAGE_POSITIONS)
@pytest.mark.parametrize("bad", _WRONG_TYPES, ids=repr)
def test_chunk_usage_parser_survives_wrong_shape(provider: str, build: Any, bad: Any) -> None:
_usage_chunk(_frame("x", build(bad)), provider)
@pytest.mark.parametrize("provider", ["anthropic", "openai", "gemini"])
@pytest.mark.parametrize("bad", _WRONG_TYPES, ids=repr)
def test_both_usage_parsers_skip_non_object_events(provider: str, bad: Any) -> None:
def test_usage_parser_skips_non_object_events(provider: str, bad: Any) -> None:
payload = f"data: {json.dumps(bad)}\n\n"
assert not _usage(payload, provider)
assert not _usage_chunk(payload, provider)
def test_gemini_usage_still_parses(provider: str = "gemini") -> None:
+3 -3
View File
@@ -221,7 +221,7 @@ async def test_count_texts_offloaded_runs_on_worker_thread(monkeypatch) -> None:
monkeypatch.setattr("headroom.tokenizers.get_tokenizer", lambda *a, **k: _SpyTokenizer())
_, tokens = await proxy._count_texts_offloaded("gemini-pro", ["hello", "world"])
_, tokens = await count_texts_offloaded(proxy, "gemini-pro", ["hello", "world"])
assert tokens > 0
assert seen["thread"].startswith("headroom-compress")
@@ -238,7 +238,7 @@ async def test_count_texts_offloaded_fails_open(monkeypatch) -> None: # noqa: A
monkeypatch.setattr("headroom.tokenizers.get_tokenizer", _boom)
tokenizer, tokens = await proxy._count_texts_offloaded("deepseek-chat", ["hello", "world"])
tokenizer, tokens = await count_texts_offloaded(proxy, "deepseek-chat", ["hello", "world"])
assert isinstance(tokenizer, EstimatingTokenCounter)
assert tokens > 0
@@ -274,7 +274,7 @@ async def test_count_texts_offloaded_sums_fragments(monkeypatch) -> None: # noq
)
fragments = ["hello", "world", "foo"]
_, total = await proxy._count_texts_offloaded("gemini-pro", fragments)
_, total = await count_texts_offloaded(proxy, "gemini-pro", fragments)
est = EstimatingTokenCounter()
assert total == sum(est.count_text(f) for f in fragments)