From 603f5bcfd663d2fe71f11e0aabc76c8993a0456b Mon Sep 17 00:00:00 2001 From: JD Davis Date: Sun, 12 Jul 2026 16:18:53 +0000 Subject: [PATCH] refactor(proxy): extract beta header policy (#1992) ## Description Extracts beta-header stickiness configuration parsing from `headroom.proxy.helpers` into a focused policy module. This keeps the environment-driven mode and LRU bound validation independently testable while preserving the helper functions used by the session beta tracker. Closes # ## 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 - Added `headroom.proxy.beta_header_policy` for beta sticky mode and tracker session limit resolution. - Kept `get_beta_header_sticky_mode()` and `get_beta_tracker_max_sessions()` as compatibility wrappers in `helpers.py`. - Added direct unit tests for defaults, accepted values, and loud rejection of invalid operator configuration. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text python -m pytest tests/test_beta_header_policy.py tests/test_anthropic_beta_session_sticky.py tests/test_openai_beta_session_sticky.py 52 passed in 0.41s python -m ruff check . All checks passed! python -m ruff format --check . 1069 files already formatted python -m mypy headroom --ignore-missing-imports Success: no issues found in 410 source files gitleaks protect --staged --no-banner --redact no leaks found ``` ## Real Behavior Proof - Environment: Windows, Python 3.13.13 - Exact command / steps: Ran focused beta policy tests, existing Anthropic/OpenAI beta sticky suites, full ruff, format check, mypy, and staged gitleaks scan. - Observed result: Existing beta sticky behavior remains green while extracted policy parsing is covered directly. - Not tested: Full repository pytest suite locally; CI covers the broader matrix. ## 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 - [ ] I have updated the CHANGELOG.md if applicable ## Screenshots (if applicable) N/A ## Additional Notes Documentation and changelog updates are not applicable for this internal refactor. The default-branch Dependabot alerts reported during push are pre-existing and unrelated to this PR. --------- Co-authored-by: Tejas Chopra --- headroom/proxy/beta_header_policy.py | 44 ++++++++++++++++++++++++++++ headroom/proxy/helpers.py | 38 ++++++++++-------------- tests/test_beta_header_policy.py | 42 ++++++++++++++++++++++++++ 3 files changed, 101 insertions(+), 23 deletions(-) create mode 100644 headroom/proxy/beta_header_policy.py create mode 100644 tests/test_beta_header_policy.py diff --git a/headroom/proxy/beta_header_policy.py b/headroom/proxy/beta_header_policy.py new file mode 100644 index 000000000..fa7dda3db --- /dev/null +++ b/headroom/proxy/beta_header_policy.py @@ -0,0 +1,44 @@ +"""Policy helpers for beta-header stickiness configuration.""" + +from __future__ import annotations + +from typing import Literal, cast + +BETA_HEADER_STICKY_ENV = "HEADROOM_BETA_HEADER_STICKY" +BetaHeaderStickyMode = Literal["enabled", "disabled"] +BETA_HEADER_STICKY_DEFAULT: BetaHeaderStickyMode = "enabled" + +BETA_TRACKER_MAX_SESSIONS_ENV = "HEADROOM_BETA_TRACKER_MAX_SESSIONS" +BETA_TRACKER_MAX_SESSIONS_DEFAULT = 1000 + + +def resolve_beta_header_sticky_mode(raw: str | None) -> BetaHeaderStickyMode: + """Resolve beta-header stickiness mode from an environment value.""" + + normalized = (raw or "").strip().lower() + if not normalized: + return BETA_HEADER_STICKY_DEFAULT + if normalized in ("enabled", "disabled"): + return cast(BetaHeaderStickyMode, normalized) + raise ValueError( + f"Invalid {BETA_HEADER_STICKY_ENV}={normalized!r}; expected 'enabled' or 'disabled'" + ) + + +def resolve_beta_tracker_max_sessions(raw: str | None) -> int: + """Resolve the positive LRU session bound for beta-header tracking.""" + + normalized = (raw or "").strip() + if not normalized: + return BETA_TRACKER_MAX_SESSIONS_DEFAULT + try: + value = int(normalized) + except ValueError as exc: + raise ValueError( + f"Invalid {BETA_TRACKER_MAX_SESSIONS_ENV}={normalized!r}; expected positive int" + ) from exc + if value <= 0: + raise ValueError( + f"Invalid {BETA_TRACKER_MAX_SESSIONS_ENV}={normalized!r}; expected positive int" + ) + return value diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.py index 94d0768f3..0ccd3cfda 100644 --- a/headroom/proxy/helpers.py +++ b/headroom/proxy/helpers.py @@ -33,6 +33,15 @@ from headroom.proxy import ( wire_debug_format_policy, wire_debug_redaction_policy, ) +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, + resolve_beta_tracker_max_sessions, +) from headroom.proxy.body_forwarding import ( BodyMutationTracker as BodyMutationTracker, # noqa: F401 - compatibility export ) @@ -1530,12 +1539,11 @@ def log_outbound_headers( # the tracker (returns the client value verbatim). That mode is loud and # explicit per realignment build constraint #4 — NOT a silent fallback. -_BETA_HEADER_STICKY_ENV = "HEADROOM_BETA_HEADER_STICKY" -BetaHeaderStickyMode = Literal["enabled", "disabled"] -_BETA_HEADER_STICKY_DEFAULT: BetaHeaderStickyMode = "enabled" +_BETA_HEADER_STICKY_ENV = BETA_HEADER_STICKY_ENV +_BETA_HEADER_STICKY_DEFAULT = BETA_HEADER_STICKY_DEFAULT -_BETA_TRACKER_MAX_SESSIONS_ENV = "HEADROOM_BETA_TRACKER_MAX_SESSIONS" -_BETA_TRACKER_MAX_SESSIONS_DEFAULT = 1000 +_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: @@ -1545,28 +1553,12 @@ def get_beta_header_sticky_mode() -> BetaHeaderStickyMode: restart. Unknown values raise loudly per the no-silent-fallback build constraint. """ - raw = os.environ.get(_BETA_HEADER_STICKY_ENV, "").strip().lower() - if not raw: - return _BETA_HEADER_STICKY_DEFAULT - if raw in ("enabled", "disabled"): - return cast(BetaHeaderStickyMode, raw) - raise ValueError(f"Invalid {_BETA_HEADER_STICKY_ENV}={raw!r}; expected 'enabled' or 'disabled'") + return resolve_beta_header_sticky_mode(os.environ.get(_BETA_HEADER_STICKY_ENV)) def get_beta_tracker_max_sessions() -> int: """Return the LRU bound for `SessionBetaTracker` (sessions cap).""" - raw = os.environ.get(_BETA_TRACKER_MAX_SESSIONS_ENV, "").strip() - if not raw: - return _BETA_TRACKER_MAX_SESSIONS_DEFAULT - try: - value = int(raw) - except ValueError as exc: - raise ValueError( - f"Invalid {_BETA_TRACKER_MAX_SESSIONS_ENV}={raw!r}; expected positive int" - ) from exc - if value <= 0: - raise ValueError(f"Invalid {_BETA_TRACKER_MAX_SESSIONS_ENV}={raw!r}; expected positive int") - return value + return resolve_beta_tracker_max_sessions(os.environ.get(_BETA_TRACKER_MAX_SESSIONS_ENV)) def _split_beta_tokens(value: str | None) -> list[str]: diff --git a/tests/test_beta_header_policy.py b/tests/test_beta_header_policy.py new file mode 100644 index 000000000..b8e7c018e --- /dev/null +++ b/tests/test_beta_header_policy.py @@ -0,0 +1,42 @@ +from __future__ import annotations + +import pytest + +from headroom.proxy.beta_header_policy import ( + BETA_HEADER_STICKY_ENV, + BETA_TRACKER_MAX_SESSIONS_DEFAULT, + BETA_TRACKER_MAX_SESSIONS_ENV, + resolve_beta_header_sticky_mode, + resolve_beta_tracker_max_sessions, +) + + +def test_resolve_beta_header_sticky_mode_defaults_to_enabled() -> None: + assert resolve_beta_header_sticky_mode(None) == "enabled" + assert resolve_beta_header_sticky_mode(" ") == "enabled" + + +def test_resolve_beta_header_sticky_mode_accepts_known_values() -> None: + assert resolve_beta_header_sticky_mode("ENABLED") == "enabled" + assert resolve_beta_header_sticky_mode(" disabled ") == "disabled" + + +def test_resolve_beta_header_sticky_mode_rejects_unknown_values() -> None: + with pytest.raises(ValueError, match=BETA_HEADER_STICKY_ENV): + resolve_beta_header_sticky_mode("maybe") + + +def test_resolve_beta_tracker_max_sessions_defaults() -> None: + assert resolve_beta_tracker_max_sessions(None) == BETA_TRACKER_MAX_SESSIONS_DEFAULT + assert resolve_beta_tracker_max_sessions(" ") == BETA_TRACKER_MAX_SESSIONS_DEFAULT + + +def test_resolve_beta_tracker_max_sessions_accepts_positive_int() -> None: + assert resolve_beta_tracker_max_sessions("42") == 42 + assert resolve_beta_tracker_max_sessions(" 7 ") == 7 + + +@pytest.mark.parametrize("raw", ["0", "-1", "not-int", "1.5"]) +def test_resolve_beta_tracker_max_sessions_rejects_invalid_values(raw: str) -> None: + with pytest.raises(ValueError, match=BETA_TRACKER_MAX_SESSIONS_ENV): + resolve_beta_tracker_max_sessions(raw)