refactor(proxy): remove dead aliases and wrappers from helpers, body_forwarding, forwarded_headers (#4080)

## Description

When the policy modules were split out of `helpers.py`, it kept a
private alias for each policy constant and a thin wrapper for several
policy functions. About twenty of these are now read by nothing. This PR
removes them, along with the imports that only fed them. Two smaller
modules had the same leftovers: `body_forwarding.py` and
`forwarded_headers.py`.

One removal is worth calling out. `get_sse_event_max_bytes()` was the
only reader of `HEADROOM_SSE_BUFFER_MAX_BYTES`, and nothing called it.
So the per-event SSE cap that its comment describes was never enforced.
Removing it changes no behaviour. The knob is not documented anywhere.

Evidence: for each name I ran `grep -rnw <name>` across `headroom`,
`tests`, `crates`, `plugins`, `sdk`, `docs`, `wiki`, `scripts`,
`examples`, `benchmarks`, `.github`, `pyproject.toml` and the private
consumer repos. I also ran an AST scan for `from headroom.proxy.helpers
import <name>` and `helpers.<name>` access. The only hit for each name
was its own definition. None of them is in a lazy export map or an
entry-point group.

Refs #4136

## Type of Change

- [ ] 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
- [x] Code refactoring (no functional changes)

## Changes Made

- `helpers.py`: remove the following, and the now-unused imports
`merge_beta_tokens`, `BETA_HEADER_STICKY_DEFAULT`,
`BETA_TRACKER_MAX_SESSIONS_DEFAULT`, `INTERNAL_HEADER_PREFIX` and
`STRIP_INTERNAL_HEADERS_DEFAULT`:
  - `_CODEX_WIRE_REDACTED`, `_CODEX_WIRE_SECRET_KEYS`
  - `_should_redact_key`, `_redact_value`
  - `_MEMORY_INJECTION_MODE_DEFAULT`
- `_SSE_EVENT_MAX_BYTES_ENV`, `_SSE_EVENT_MAX_BYTES_DEFAULT`,
`get_sse_event_max_bytes`
  - `_BODY_TOO_LARGE_STATUS_DEFAULT`
- `_SSE_EVENT_TERMINATORS`, `_find_sse_event_terminator`,
`_SSE_EVENT_LINE_PREFIX`, `_SSE_DATA_LINE_PREFIX`
  - `_INTERNAL_HEADER_PREFIX`, `_STRIP_INTERNAL_HEADERS_DEFAULT`
  - `_BETA_HEADER_STICKY_DEFAULT`, `_BETA_TRACKER_MAX_SESSIONS_DEFAULT`
  - `_merge_beta_tokens`
  - `reset_core_tools_legacy_warn_state`
- `body_forwarding.py`: remove `_PYTHON_FORWARDER_MODE_DEFAULT` and
`_original_body_has_signed_thinking_blocks`. `prepare_outbound_body`
already does the same check on the body it has already parsed.
- `forwarded_headers.py`: remove `_header_first`, a wrapper over
`forwarded_policy.header_first`, and its import.
- Unchanged: the live callers use the policy modules directly, for
example `sse_byte_buffer_policy.find_sse_event_terminator` and
`request_limit_policy.resolve_body_too_large_status`. The public names
that consumer plugins import from `helpers` are untouched.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ pytest -q -p no:cacheprovider tests/test_proxy_byte_faithful_forwarding.py tests/test_forwarded_headers.py tests/test_forwarded_policy.py tests/test_anthropic_beta_session_sticky.py tests/test_openai_beta_session_sticky.py tests/test_tool_search_client_deferral.py tests/test_wire_debug_redaction_policy.py tests/test_sse_byte_buffer_policy.py tests/test_request_limit_policy.py tests/test_internal_header_policy.py tests/test_beta_header_policy.py tests/test_beta_header_merge.py
============================= 265 passed in 8.27s ==============================
$ uvx ruff@0.16.8 check headroom/proxy/helpers.py headroom/proxy/body_forwarding.py headroom/proxy/forwarded_headers.py
All checks passed!
$ grep -rnw <each removed name> headroom tests
(no output)
```

## Real Behavior Proof

- Environment: macOS, Python 3.12.13, branch checkout at b005f174, 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 with `HEADROOM_SSE_BUFFER_MAX_BYTES=1`.
It starts a real proxy from this checkout against a local fake upstream,
and sends one Anthropic and one OpenAI request carrying a compressible
tool result.
2. Ran a direct check: imported `headroom.proxy.server`, confirmed every
removed name is gone, and called the live policy paths that stay.
- Observed result:
```text
branch: cleanup/proxy-core-a-dead-aliases @ b005f174
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
$ python -c "import headroom.proxy.server, headroom.proxy.helpers as h, ...; print(removed names still present); print(h.get_body_too_large_status(), h.redact_for_wire_debug({...}))"
server imports ok; removed names still present: []
live callers: 413 {'authorization': '[REDACTED]', 'n': 1}
```
- Both providers return 200, with savings recorded, even though
`HEADROOM_SSE_BUFFER_MAX_BYTES=1` is set. That shows the knob is not
enforced, which is also the case on main.
  - The proxy imports cleanly with the removed names gone.
- The kept policy paths still work: the body-too-large status is 413,
and wire-debug redaction still applies.
- Two pre-existing offline-mode and Kompress-prefetch warnings are left
out of the smoke output.
- Not tested: Live provider traffic. No removed name was on any call
path.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A; dead-code removal.
- Stable/default behavior changed: No. `HEADROOM_SSE_BUFFER_MAX_BYTES`
was never read on any request path, so removing its only reader changes
nothing.
- 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
- [ ] 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.

Follow-up for whoever owns `request_limit_policy.py`: after this PR,
`resolve_sse_event_max_bytes` and `SSE_EVENT_MAX_BYTES_*` are used only
by `tests/test_request_limit_policy.py`. Either delete them or wire up
the cap if one is actually wanted.

Unchecked items: there is no type-signature change, so I did not run
mypy. No new tests were needed for a pure deletion. No docs mention
these names.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Tejas Chopra
2026-10-10 08:57:39 -07:00
committed by GitHub
co-authored by Claude Opus 5.5
parent de8969267c
commit 63cc9afa9d
3 changed files with 3 additions and 89 deletions
-7
View File
@@ -23,8 +23,6 @@ _PYTHON_FORWARDER_MODE_ENV = python_forwarder_mode_policy.PYTHON_FORWARDER_MODE_
PythonForwarderMode = python_forwarder_mode_policy.PythonForwarderMode
OutboundBodySource = Literal["passthrough", "canonical", "legacy"]
_PYTHON_FORWARDER_MODE_DEFAULT = python_forwarder_mode_policy.PYTHON_FORWARDER_MODE_DEFAULT
@dataclass(frozen=True, slots=True)
class OutboundBody:
@@ -148,11 +146,6 @@ def _parse_original_body(original_body_bytes: bytes | None) -> dict[str, Any] |
return original if isinstance(original, dict) else None
def _original_body_has_signed_thinking_blocks(original_body_bytes: bytes | None) -> bool:
original = _parse_original_body(original_body_bytes)
return original is not None and has_signed_thinking_blocks(original)
#: Allow canonical re-serialization on a thinking-bearing request when every
#: thinking block is provably unchanged. **Default ON**; set this to ``0`` (or
#: ``false``/``no``/``off``) to restore the previous blanket lock.
-12
View File
@@ -59,7 +59,6 @@ from typing import TYPE_CHECKING, Any
from headroom.proxy.forwarded_policy import (
ForwardedHeaderInputs,
header_first,
normalize_ip,
parse_cidr_list,
peer_is_trusted_gateway,
@@ -152,17 +151,6 @@ def _peer_host(request: Any) -> str | None:
return getattr(client, "host", None)
def _header_first(value: str) -> str:
"""Return the leftmost element of a comma-separated header value.
``X-Forwarded-For: client, proxy1, proxy2`` → ``"client"``. Empty
input returns ``""``. We intentionally do NOT walk the chain — the
leftmost hop is the only one whose authenticity the immediate
gateway can vouch for, and beyond that we have no trust signal.
"""
return header_first(value)
def _read_header(request: Any, name: str) -> str:
"""Read a header case-insensitively, ``""`` on miss."""
headers = getattr(request, "headers", None)
+3 -70
View File
@@ -41,17 +41,14 @@ from headroom.proxy import (
from headroom.proxy.beta_header_merge import (
merge_anthropic_beta as merge_anthropic_beta,
)
from headroom.proxy.beta_header_merge import (
merge_beta_tokens,
split_beta_tokens,
)
from headroom.proxy.beta_header_merge import (
merge_openai_beta as merge_openai_beta,
)
from headroom.proxy.beta_header_merge import (
split_beta_tokens,
)
from headroom.proxy.beta_header_policy import (
BETA_HEADER_STICKY_DEFAULT,
BETA_HEADER_STICKY_ENV,
BETA_TRACKER_MAX_SESSIONS_DEFAULT,
BETA_TRACKER_MAX_SESSIONS_ENV,
BetaHeaderStickyMode,
resolve_beta_header_sticky_mode,
@@ -81,8 +78,6 @@ from headroom.proxy.ccr_marker_policy import (
)
from headroom.proxy.ccr_session_tracker import SessionCcrTracker as _SessionCcrTracker
from headroom.proxy.internal_header_policy import (
INTERNAL_HEADER_PREFIX,
STRIP_INTERNAL_HEADERS_DEFAULT,
STRIP_INTERNAL_HEADERS_ENV,
StripInternalHeadersMode,
resolve_strip_internal_headers_mode,
@@ -125,8 +120,6 @@ logger = logging.getLogger("headroom.proxy")
_CODEX_WIRE_DEBUG_ENV = "HEADROOM_CODEX_WIRE_DEBUG"
_CODEX_WIRE_DEBUG_DIR_ENV = "HEADROOM_CODEX_WIRE_DEBUG_DIR"
_CODEX_WIRE_REDACTED = wire_debug_redaction_policy.WIRE_DEBUG_REDACTED
_CODEX_WIRE_SECRET_KEYS = wire_debug_redaction_policy.WIRE_DEBUG_SECRET_KEYS
def codex_wire_debug_enabled() -> bool:
@@ -147,14 +140,6 @@ def _codex_wire_debug_dir() -> Path:
return _paths.codex_wire_debug_dir()
def _should_redact_key(key: str) -> bool:
return wire_debug_redaction_policy.should_redact_key(key)
def _redact_value(value: Any) -> Any:
return wire_debug_redaction_policy.redact_for_wire_debug(value)
def redact_for_wire_debug(value: Any) -> Any:
"""Redact obvious secrets while preserving request/response shape."""
return wire_debug_redaction_policy.redact_for_wire_debug(value)
@@ -268,7 +253,6 @@ def capture_codex_wire_debug(
# "system_prompt" option — that path is permanently retired by I2 (cache hot
# zone never modified). See REALIGNMENT/02-architecture.md §2.2.
_MEMORY_INJECTION_MODE_ENV = memory_injection_mode_policy.MEMORY_INJECTION_MODE_ENV
_MEMORY_INJECTION_MODE_DEFAULT = memory_injection_mode_policy.MEMORY_INJECTION_MODE_DEFAULT
MemoryInjectionMode = memory_injection_mode_policy.MemoryInjectionMode
@@ -1319,25 +1303,6 @@ _DECOMPRESS_CHUNK_SIZE = 64 * 1024
# Maximum SSE buffer size (10MB - prevents memory exhaustion from malformed streams)
MAX_SSE_BUFFER_SIZE = 10 * 1024 * 1024
# Per-event SSE size cap (PR-A8 / P1-8). Configurable via
# HEADROOM_SSE_BUFFER_MAX_BYTES. Guards against pathological huge events
# (a single event > 1 MB by default is treated as an upstream protocol bug
# and surfaces loudly rather than silently growing the buffer).
_SSE_EVENT_MAX_BYTES_ENV = request_limit_policy.SSE_EVENT_MAX_BYTES_ENV
_SSE_EVENT_MAX_BYTES_DEFAULT = request_limit_policy.SSE_EVENT_MAX_BYTES_DEFAULT
def get_sse_event_max_bytes() -> int:
"""Return the per-event SSE size cap.
Read at request time so operators can flip the env var without a
restart. Negative values are rejected loudly (no silent fallback).
"""
return request_limit_policy.resolve_sse_event_max_bytes(
os.environ.get(_SSE_EVENT_MAX_BYTES_ENV)
)
# Well-known OpenAI-compatible upstreams, matched by host against the
# configured ``--openai-api-url``. Used only to label the dashboard/stats
# display provider — the internal provider key stays ``openai`` so pricing
@@ -1404,7 +1369,6 @@ def resolve_display_provider(
# Configurable via HEADROOM_PROXY_BODY_TOO_LARGE_STATUS for operators who need
# to override (no expected production use; documentation knob).
_BODY_TOO_LARGE_STATUS_ENV = request_limit_policy.BODY_TOO_LARGE_STATUS_ENV
_BODY_TOO_LARGE_STATUS_DEFAULT = request_limit_policy.BODY_TOO_LARGE_STATUS_DEFAULT
def get_body_too_large_status() -> int:
@@ -1414,18 +1378,6 @@ def get_body_too_large_status() -> int:
)
_SSE_EVENT_TERMINATORS = sse_byte_buffer_policy.SSE_EVENT_TERMINATORS
def _find_sse_event_terminator(buf: bytearray) -> tuple[int, int] | None:
"""Return the earliest complete SSE event terminator in ``buf``."""
return sse_byte_buffer_policy.find_sse_event_terminator(buf)
_SSE_EVENT_LINE_PREFIX = b"event:"
_SSE_DATA_LINE_PREFIX = b"data:"
def safe_decode_for_logging(raw: bytes, *, max_bytes: int | None = None) -> str:
"""Decode bytes to a string for **log/diagnostic display only**.
@@ -2017,9 +1969,7 @@ def is_anthropic_auth(headers: dict[str, str]) -> bool:
# tell its client about its own work. This helper only filters
# request-side headers.
_INTERNAL_HEADER_PREFIX = INTERNAL_HEADER_PREFIX
_STRIP_INTERNAL_HEADERS_ENV = STRIP_INTERNAL_HEADERS_ENV
_STRIP_INTERNAL_HEADERS_DEFAULT = STRIP_INTERNAL_HEADERS_DEFAULT
def get_strip_internal_headers_mode() -> StripInternalHeadersMode:
@@ -2164,10 +2114,7 @@ def log_outbound_headers(
# explicit per realignment build constraint #4 — NOT a silent fallback.
_BETA_HEADER_STICKY_ENV = BETA_HEADER_STICKY_ENV
_BETA_HEADER_STICKY_DEFAULT = BETA_HEADER_STICKY_DEFAULT
_BETA_TRACKER_MAX_SESSIONS_ENV = BETA_TRACKER_MAX_SESSIONS_ENV
_BETA_TRACKER_MAX_SESSIONS_DEFAULT = BETA_TRACKER_MAX_SESSIONS_DEFAULT
def get_beta_header_sticky_mode() -> BetaHeaderStickyMode:
@@ -2188,9 +2135,6 @@ def get_beta_tracker_max_sessions() -> int:
_split_beta_tokens = split_beta_tokens
_merge_beta_tokens = merge_beta_tokens
class SessionBetaTracker:
"""Bounded LRU tracker of beta-header tokens observed per (provider, session).
@@ -3742,17 +3686,6 @@ _core_tools_legacy_lock = threading.Lock()
_core_tools_legacy_warned = False
def reset_core_tools_legacy_warn_state() -> None:
"""Re-arm the legacy-variable warning. Test helper only.
Without this the flag leaks between tests in a process, so a caplog
assertion on this warning passes alone and fails depending on ordering.
"""
global _core_tools_legacy_warned
with _core_tools_legacy_lock:
_core_tools_legacy_warned = False
def _core_tools_override() -> str | None:
"""Return the resident-tool override from either env var, canonical first."""
global _core_tools_legacy_warned