From 70b98b64856bf20d0ceae5602339b30c1ebddc3b Mon Sep 17 00:00:00 2001 From: JD Davis Date: Sat, 11 Jul 2026 05:06:37 +0000 Subject: [PATCH] Extract Python forwarder mode policy (#1987) ## Description Extracts Python-forwarder mode resolution from `helpers.py` into `headroom.proxy.python_forwarder_mode_policy`. The forwarding helpers still read `HEADROOM_PROXY_PYTHON_FORWARDER_MODE` at request time, while the allowed values/default/error contract is now pure and directly tested. 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 `python_forwarder_mode_policy.py` with the allowed mode type, env name/default, and resolver. - Kept `helpers.get_python_forwarder_mode` as the request-time env reader and compatibility entry point. - Added direct policy tests for defaults, accepted values, normalization, and invalid mode rejection. ## 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_python_forwarder_mode_policy.py tests\test_proxy_byte_faithful_forwarding.py 41 passed in 4.00s 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, branch `jd/architecture-slice-34`. - Exact command / steps: ran new Python-forwarder mode policy tests, existing byte-faithful forwarding tests, ruff, ruff format check, mypy, and staged gitleaks scan. - Observed result: forwarder mode behavior and byte-faithful forwarding tests remain covered; local lint/type/security checks pass. - Not tested: live proxy forwarding; existing helper entry point remains intact. ## 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 N/A for this internal architecture-only refactor. The push reported existing default-branch Dependabot alerts; no staged secret leaks were found for this PR. --- headroom/proxy/body_forwarding.py | 20 +++++++--------- .../proxy/python_forwarder_mode_policy.py | 22 +++++++++++++++++ tests/test_python_forwarder_mode_policy.py | 24 +++++++++++++++++++ 3 files changed, 54 insertions(+), 12 deletions(-) create mode 100644 headroom/proxy/python_forwarder_mode_policy.py create mode 100644 tests/test_python_forwarder_mode_policy.py diff --git a/headroom/proxy/body_forwarding.py b/headroom/proxy/body_forwarding.py index 81acdbaf2..2897d7d8f 100644 --- a/headroom/proxy/body_forwarding.py +++ b/headroom/proxy/body_forwarding.py @@ -13,14 +13,16 @@ from __future__ import annotations import json import os from dataclasses import dataclass -from typing import Any, Literal, cast +from typing import Any, Literal -_PYTHON_FORWARDER_MODE_ENV = "HEADROOM_PROXY_PYTHON_FORWARDER_MODE" +from headroom.proxy import python_forwarder_mode_policy -PythonForwarderMode = Literal["byte_faithful", "legacy_json_kwarg"] +_PYTHON_FORWARDER_MODE_ENV = python_forwarder_mode_policy.PYTHON_FORWARDER_MODE_ENV + +PythonForwarderMode = python_forwarder_mode_policy.PythonForwarderMode OutboundBodySource = Literal["passthrough", "canonical", "legacy"] -_PYTHON_FORWARDER_MODE_DEFAULT: PythonForwarderMode = "byte_faithful" +_PYTHON_FORWARDER_MODE_DEFAULT = python_forwarder_mode_policy.PYTHON_FORWARDER_MODE_DEFAULT @dataclass(frozen=True, slots=True) @@ -38,14 +40,8 @@ def get_python_forwarder_mode() -> PythonForwarderMode: fallback build constraint. The ``legacy_json_kwarg`` value is an explicit operator opt-in for emergency rollback, not a fallback. """ - raw = os.environ.get(_PYTHON_FORWARDER_MODE_ENV, "").strip().lower() - if not raw: - return _PYTHON_FORWARDER_MODE_DEFAULT - if raw in ("byte_faithful", "legacy_json_kwarg"): - return cast(PythonForwarderMode, raw) - raise ValueError( - f"Invalid {_PYTHON_FORWARDER_MODE_ENV}={raw!r}; " - "expected 'byte_faithful' or 'legacy_json_kwarg'" + return python_forwarder_mode_policy.resolve_python_forwarder_mode( + os.environ.get(_PYTHON_FORWARDER_MODE_ENV) ) diff --git a/headroom/proxy/python_forwarder_mode_policy.py b/headroom/proxy/python_forwarder_mode_policy.py new file mode 100644 index 000000000..f92480565 --- /dev/null +++ b/headroom/proxy/python_forwarder_mode_policy.py @@ -0,0 +1,22 @@ +"""Python forwarder mode resolution policy.""" + +from __future__ import annotations + +from typing import Literal, cast + +PYTHON_FORWARDER_MODE_ENV = "HEADROOM_PROXY_PYTHON_FORWARDER_MODE" +PythonForwarderMode = Literal["byte_faithful", "legacy_json_kwarg"] +PYTHON_FORWARDER_MODE_DEFAULT: PythonForwarderMode = "byte_faithful" + + +def resolve_python_forwarder_mode(raw: str | None) -> PythonForwarderMode: + """Resolve the active Python-forwarder mode from an optional value.""" + normalized = (raw or "").strip().lower() + if not normalized: + return PYTHON_FORWARDER_MODE_DEFAULT + if normalized in ("byte_faithful", "legacy_json_kwarg"): + return cast(PythonForwarderMode, normalized) + raise ValueError( + f"Invalid {PYTHON_FORWARDER_MODE_ENV}={normalized!r}; " + "expected 'byte_faithful' or 'legacy_json_kwarg'" + ) diff --git a/tests/test_python_forwarder_mode_policy.py b/tests/test_python_forwarder_mode_policy.py new file mode 100644 index 000000000..dd18a38f8 --- /dev/null +++ b/tests/test_python_forwarder_mode_policy.py @@ -0,0 +1,24 @@ +from __future__ import annotations + +import pytest + +from headroom.proxy.python_forwarder_mode_policy import ( + PYTHON_FORWARDER_MODE_DEFAULT, + resolve_python_forwarder_mode, +) + + +def test_resolve_python_forwarder_mode_defaults_for_missing_value() -> None: + assert resolve_python_forwarder_mode(None) == PYTHON_FORWARDER_MODE_DEFAULT + assert resolve_python_forwarder_mode("") == PYTHON_FORWARDER_MODE_DEFAULT + assert resolve_python_forwarder_mode(" ") == PYTHON_FORWARDER_MODE_DEFAULT + + +def test_resolve_python_forwarder_mode_accepts_known_values_case_insensitively() -> None: + assert resolve_python_forwarder_mode("byte_faithful") == "byte_faithful" + assert resolve_python_forwarder_mode(" LEGACY_JSON_KWARG ") == "legacy_json_kwarg" + + +def test_resolve_python_forwarder_mode_rejects_unknown_values() -> None: + with pytest.raises(ValueError, match="HEADROOM_PROXY_PYTHON_FORWARDER_MODE"): + resolve_python_forwarder_mode("json")