c85abf7a87
## Description Fixes #2895 The repository-wide Ruff command failed on the bundled OAuth2 plugin. This change sorts the public export list, narrows the optional LiteLLM setup exception handling to expected failures, and replaces the silent HTTP error-body drain with explicit handling and debug logging. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Sorted headroom_oauth2.__all__ according to Ruff RUF022. - Replaced the blind install-time Exception catch with explicit ImportError, AttributeError, OSError, TypeError, and ValueError handling. - Replaced the silent HTTPError body-drain pass with explicit HTTPException, OSError, and ValueError handling plus debug logging. - Added regression coverage for body-drain failures and invalid LiteLLM header state. ## Testing - [x] Unit tests pass - [x] Linting passes (ruff check .) - [x] Type checking passes (mypy headroom) - [x] New tests added - [x] Manual testing performed ### Test Output ruff 0.15.17 ruff check . All checks passed! ruff format --check . 1382 files already formatted python -m mypy headroom Success: no issues found in 515 source files PYTHONPATH=plugins/headroom-oauth2/src python -m pytest -q plugins/headroom-oauth2/tests 39 passed in 11.12s Full Python pytest was attempted: 8,878 tests were collected, but collection stopped with 174 environment errors because the required compiled headroom._core extension is unavailable in this Windows checkout. 18 tests were skipped. ## Real Behavior Proof - Environment: Windows PowerShell, Python 3.12, Ruff 0.15.17. - Exact command / steps: Ran the OAuth2 test suite with PYTHONPATH pointing to plugins/headroom-oauth2/src. Its local HTTPServer fixture exercised real urllib token minting, cached refresh, HTTP error handling, and middleware injection. - Observed result: 39 tests passed, including real loopback token minting and the new failure-path tests; repository-wide Ruff completed with no diagnostics. - Not tested: External identity-provider traffic and the full Python suite after native extension build, because the local Windows toolchain cannot build headroom._core. ## 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 the code - [x] I have commented my code where needed - [ ] I have made corresponding changes to the documentation (not needed; behavior and lint handling are covered by existing comments/tests) - [x] My changes generate no new warnings - [x] I have added tests that prove the fix is effective - [ ] New and existing full-repository unit tests pass locally (blocked by missing native headroom._core) - [x] I did not edit CHANGELOG.md ## Additional Notes No dependencies or public API behavior changed. Expected environment and transport failures remain handled; unexpected programmer errors now propagate instead of being silently swallowed. The OAuth2 plugin remains standard-library-only. --------- Co-authored-by: Tejas Chopra <tejas@Tejass-MacBook-Pro.local> |
||
|---|---|---|
| .. | ||
| src/headroom_oauth2 | ||
| tests | ||
| CHANGELOG.md | ||
| LICENSE | ||
| pyproject.toml | ||
| README.md | ||
| SPEC.md | ||
headroom-oauth2
Generic OAuth2 client-credentials upstream-auth extension for the Headroom proxy.
When Headroom routes to an OpenAI-compatible backend that is protected by an
OAuth2 client-credentials flow (enterprise AI gateways, Azure AD / Entra, Okta,
Auth0, Keycloak, Cognito, …), this extension mints a bearer token from a
configurable token endpoint, caches + refreshes it (single-flight), and injects
Authorization: Bearer <token> on each upstream request. Optional static upstream
headers are sent via litellm. Fully vendor-neutral — no provider is hard-coded.
It plugs into Headroom's public headroom.proxy_extension entry-point seam, so it
is fully out-of-tree and opt-in.
Install & enable
pip install headroom-oauth2
headroom proxy --backend litellm-openai --proxy-extension oauth2
Configure (env; no-op unless HEADROOM_OAUTH2_TOKEN_URL is set)
| Env | Meaning |
|---|---|
HEADROOM_OAUTH2_TOKEN_URL |
token endpoint (client_credentials grant) |
HEADROOM_OAUTH2_CLIENT_ID / _CLIENT_SECRET |
credentials (secrets) |
HEADROOM_OAUTH2_SCOPES |
space/comma-separated scopes |
HEADROOM_OAUTH2_AUDIENCE |
optional audience |
HEADROOM_OAUTH2_GRANT_TYPE |
default client_credentials |
HEADROOM_OAUTH2_AUTH_STYLE |
post (form creds) or basic (HTTP Basic) |
HEADROOM_OAUTH2_HEADERS |
static upstream headers, K=V,K2=V2 |
Tokens are minted with the standard library (urllib, system cert store), which
works behind corporate SSL-inspection where bundled-root TLS stacks fail.
Effective backends: the injected bearer reaches the upstream only for OpenAI-compatible /
passthrough litellm providers. bedrock / vertex / sagemaker authenticate from env and
ignore it, so this extension is a no-op there (it logs a warning at startup).
Transport: token_url must be https (loopback http is allowed for tests; set
HEADROOM_OAUTH2_ALLOW_INSECURE=1 to override). Tokens are minted with the standard library
(urllib, system cert store), so a corporate-injected CA is trusted without bundling roots.