Skip to content

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.

refactor(proxy): extract beta header policy (#1992)

JD Davis603f5bcfd663
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
+
+
[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)