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

@@ -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)
     )
 
 

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'"
+    )

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")