Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
refactor(proxy): extract beta header policy (#1992)
JD Davis603f5bcfd663
diff --git a/headroom/proxy/beta_header_policy.py b/headroom/proxy/beta_header_policy.pynew file mode 100644index 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 valuediff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.pyindex 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_DEFAULTdef 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-fallbackbuild 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.pynew file mode 100644index 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++[email protected]("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)