[chopratejas]

Description

handle_openai_chat and handle_openai_responses validated x-headroom-base-url with the synchronous is_safe_upstream_url, which waits for the DNS lookup (up to HEADROOM_UPSTREAM_RESOLVE_TIMEOUT_S, 3 s by default) on the event-loop thread. Chat did this three times per request and responses twice, so one slow-resolving host held up every other in-flight request for several seconds. The other routes in headroom/providers/proxy_routes.py already use is_safe_upstream_url_async.

Both handlers now resolve the header once, through a new _resolve_openai_upstream_base_async that uses the async guard (lookup on a worker thread, pin scope opened on the request's task), and reuse that result for the destination and the extra-header decision.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• Performance improvement

Changes Made

• headroom/proxy/handlers/openai.py: header parsing split into _openai_base_url_candidate; sync _resolve_openai_upstream_base (kept for _resolve_openai_upstream) and new _resolve_openai_upstream_base_async share it; _openai_upstream_from(request, custom) picks the upstream from an already-resolved override; chat and responses call the async resolver once.
• tests/test_proxy/test_openai_upstream_guard_off_loop.py: asserts the guard runs once and not on the event-loop thread, for chat and responses.
• tests/test_proxy_openai_cache_key_integration.py: its stub now patches the async resolver the handler calls.

Sibling PRs that touch the same code (merge order note): fix/upstream-idna-pin-once adds the identical _openai_upstream_from and resolve-once hunks (this PR is a superset of that part); fix/openai-base-url-reject changes the rejection branch of _resolve_openai_upstream_base, which after this PR must be mirrored in _resolve_openai_upstream_base_async. Suggested order: idna-pin-once, then this PR, then reject (rebasing reject means raising the 400 from the shared rejection path in both resolvers).

Testing

• Unit tests pass (pytest)
• Linting passes (ruff check .)
• Type checking passes (mypy headroom)
• New tests added for new functionality
• Manual testing performed

Test Output

# New test on origin/main (c21b0813)
E   AssertionError: the guard ran on the event-loop thread
E   assert [True, True, True] == [False]      (chat)
E   assert [True, True] == [False]            (responses)
============================== 2 failed in 0.72s ===============================

# This branch: new test + cache-key integration
============================== 7 passed in 7.30s ===============================

# Area suites: test_upstream_guard, test_grok_shared_proxy_call_sites, test_proxy/test_openai_upstream_header,
# test_proxy_openai_cache_key_integration, test_upstream_credential_scoping, test_header_isolation,
# test_proxy_hardening, test_openai_codex_routing, test_proxy/test_openai_upstream_guard_off_loop
======================= 282 passed, 5 warnings in 56.32s =======================

$ ruff check / ruff format --check (0.17.3) on changed files
All checks passed!
3 files already formatted
$ mypy headroom/proxy/handlers/openai.py --ignore-missing-imports
Success: no issues found in 1 source file

Real Behavior Proof

• Environment: macOS, Python 3.12, full app from create_app driven through httpx.ASGITransport on one event loop; socket.getaddrinfo replaced so slow.example takes 2 s to answer (everything else real).
• Exact command / steps: start a /v1/chat/completions request with x-headroom-base-url: https://slow.example/v1, then 0.2 s later send GET /livez and time it.
• Observed result:

  == origin/main
  /livez sent 0.2s after a chat request naming a 2s-to-resolve host: HTTP 200 after 6.03s (0.20s if the loop is free)
  == this branch
  /livez sent 0.2s after a chat request naming a 2s-to-resolve host: HTTP 200 after 0.20s (0.20s if the loop is free)
  

• Not tested: under real slow DNS.

Runtime Rollout Safety

• Rollout-managed feature(s): none
• Minimum rollout channel: n/a
• Stable/default behavior changed: no change in which upstream is chosen; the lookup moves to a worker thread and happens once per request.
• Kill switch / disable path: none needed
• Unsafe override required: no
• Qualification impact: none
• Rollback path: revert

Review Readiness

• I have performed a self-review
• This PR is ready for human review

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I did not edit CHANGELOG.md — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this)

Additional Notes

Fix adapted from a proposal by HetCreep.

Follow-up, not in this PR: select_passthrough_base_url (headroom/providers/proxy_targets.py, Azure api-key branch) and headroom/providers/registry.py still call the sync guard; the passthrough route already checks the same header with the async guard first, so the sync call there is a second lookup on the loop.

🤖 Generated with Claude Code

---

Reported by @JoaoMarcos44. Thank you for your contribution! 🩵

[github-actions]

PR governance

This PR does not yet satisfy the required template fields:

• Fill in Real Behavior Proof → Observed result.

Please update the PR body, or move the PR back to draft while it is still in progress.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[JerrettDavis]

Review completed; approval remains pending the items below.

Reviewed head d4eb81585181e5ff5b86f1f7fc0534a5513fb588 against main 0368a872cdd5064b39888e13847200ff562ac192.

Qualification still required:

• Passing test evidence is missing
• Exact-source provenance review is incomplete

[JerrettDavis]

Review completed; approval remains pending the items below.

Reviewed head 1416d0d8c5276d1b84c7f09e1facaae97450a714 against main 0368a872cdd5064b39888e13847200ff562ac192.

Qualification still required:

• Hosted check evidence changed
• Exact-source provenance review is incomplete
• Check/run 132232314322 is not terminal
• Check/run 132232314308 is not terminal
• Check/run 132232314254 is not terminal
• Check/run 132232314208 is not terminal
• Check/run 43525780933 is not terminal

[JerrettDavis]

Reviewed 1416d0d against target 0368a87. The async guard preserves request-scoped pins and routing/header decisions; both image-compression pin findings are resolved. Local validation passed 17 handler/routing cases and 26 cache integration cases (the latter in documented Python-only mode because the worker lacks the native extension). Exact-head hosted CI, including all four test shards, is now successful. No blocking code issues found.

[JerrettDavis]

Reviewed 55828ed against target b324efb. The async guard preserves routing, header trust and request-scoped pins; both prior image-compression pin findings remain resolved. Fresh local validation passed 27 handler/routing cases and 26 ASGI cache cases in documented Python-only mode. The new off-loop regression fails on the recorded base for both handlers and passes on head. Staged exact-head CI is successful, including all four test shards. No blocking code issues found. Native compression and real DNS/provider traffic were not tested locally.

[chopratejas]

Jerrett: conflict-only merge with main (239f0de, plus 3582001 to take in your earlier merge commit; no content change from that one). Kept this PR's async resolver in the chat and responses handlers, and main's lapsed-pin re-check after image compression, which already goes through the async guard. Took main's resolve-once test. Area tests, ruff and mypy pass locally. Your approval was dismissed by the push, so I re-requested review.

[chopratejas]

The one red check, test (3), is tests/test_memory_tools_only_when_injected.py::test_memory_call_the_proxy_did_not_inject_reaches_the_client[not_injected-anthropic*], which fails the same way on main (fda75de) and passes locally on this branch.