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)