No actionable comments were generated in the recent review. 🎉

sequenceDiagram
  participant Client
  participant EchoMiddleware
  participant RequestSnapshotCapture
  participant ProviderFactory
  participant Provider
  participant UpstreamAPI

  Client->>EchoMiddleware: HTTP request
  EchoMiddleware->>RequestSnapshotCapture: capture snapshot context
  RequestSnapshotCapture->>RequestSnapshotCapture: filter passthrough headers
  EchoMiddleware->>ProviderFactory: create provider with header settings
  ProviderFactory->>Provider: pass HeaderOverrides and UserPathHeader
  Client->>Provider: ChatCompletion / Passthrough
  Provider->>UpstreamAPI: forward merged headers
  UpstreamAPI-->>Client: response

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands.}

Confidence Score: 4/5

This PR has one contained header-forwarding bug that should be fixed before merging.

The main header layering and provider plumbing are coherent, but the new passthrough path currently misses do_not_pass tagging rules because of a case-normalization mismatch.

internal/providers/headers.go

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant Client
participant Server as Echo middleware
participant Ctx as Request context
participant Provider as CompatibleProvider
participant Upstream

Client->>Server: HTTP request with headers
Server->>Ctx: RequestSnapshotCapture stores snapshot/user path
alt passthrough_user_headers enabled
    Server->>Ctx: PassthroughHeaderCapture stores filtered headers
end
Server->>Ctx: TaggingCapture stores labels and do_not_pass strip set
Server->>Provider: Route translated or passthrough request
Provider->>Provider: Set auth headers
Provider->>Provider: Apply provider defaults
Provider->>Provider: Apply custom_upstream_headers
Provider->>Ctx: Read passthrough headers and strip set
Provider->>Upstream: Send composed upstream request

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant Client
participant Server as Echo middleware
participant Ctx as Request context
participant Provider as CompatibleProvider
participant Upstream

Client->>Server: HTTP request with headers
Server->>Ctx: RequestSnapshotCapture stores snapshot/user path
alt passthrough_user_headers enabled
    Server->>Ctx: PassthroughHeaderCapture stores filtered headers
end
Server->>Ctx: TaggingCapture stores labels and do_not_pass strip set
Server->>Provider: Route translated or passthrough request
Provider->>Provider: Set auth headers
Provider->>Provider: Apply provider defaults
Provider->>Provider: Apply custom_upstream_headers
Provider->>Ctx: Read passthrough headers and strip set
Provider->>Upstream: Send composed upstream request

_{Reviews (2): Last reviewed commit: "Merge branch 'main' into feat/custom-ups..." | Re-trigger Greptile}

⚠️ 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!

@coderabbitai review

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

internal/providers/init.go (1)> 219-272: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Move the passthrough flag behind successful provider creation
anyPassthroughUserHeaders is set before factory.Create, so a config with passthrough_user_headers: true still turns on header capture even if that provider fails to initialize and never becomes active. Move the check after Create succeeds.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@internal/providers/init.go` around lines 219 - 272, The
passthrough-user-headers flag is being recorded before provider creation
succeeds, so failed providers can still enable header capture. In
initializeProviders, move the HeaderOverrides.PassthroughUserHeaders check to
after factory.Create returns successfully, and only then update
anyPassthroughUserHeaders for the provider that actually initialized.

The passthrough flag is already set after factory.Create succeeds in the current branch, so a failed provider cannot enable header capture. I added a regression test to keep it that way and updated additional tests for config.go to have broader test coverage.

Commit: a7af32cfd0a798dadd0edb514bab59cad641d3a3

@coderabbitai resume

#!/bin/bash
sed -n '190,280p' internal/providers/init.go

Confirmed — the factory.Create call happens on line before the err != nil check, which uses continue to skip failed providers, and the anyPassthroughUserHeaders flag is only set afterward, on the success path. So a failed provider indeed cannot set the flag. Thanks for the fix and the regression test.

Converting to draft to fix a bug with the OpenRouter implementation. It currently overwrites headers even when 'User Headers Passthrough' is enabled.

Note: Other providers' implementations are working perfectly based on my final manual E2E tests.

Actionable comments posted: 5

[!CAUTION]
Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

.env.template (1)

12-15: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

"Same header layer" claim contradicts the four-layer hierarchy.

The comment says identity headers from OPENROUTER_SITE_URL/OPENROUTER_APP_NAME are "in the same header layer as custom_upstream_headers." However, per the CompatibleProviderConfig.DefaultHeaders field comment and the four-layer precedence table in docs/features/custom-headers.mdx (lines 55-65), DefaultHeaders are layer 2 (provider defaults) while custom_upstream_headers are layer 3 (static overrides). They are in different layers, which is why static overrides take precedence. The precedence statement itself is correct, but "same header layer" is internally inconsistent with it and misleading.

📝 Suggested wording fix

 # OpenRouter-specific: OPENROUTER_SITE_URL and OPENROUTER_APP_NAME also set
 # identity headers (HTTP-Referer and X-OpenRouter-Title) upstream. These are
-# in the same header layer as custom_upstream_headers, so static config values
-# and caller passthrough headers take precedence over these env vars.
+# in the provider-default header layer (below custom_upstream_headers), so
+# static config values and caller passthrough headers take precedence over
+# these env vars.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.env.template around lines 12 - 15, Update the OpenRouter comment in
.env.template so it no longer says the identity headers are “in the same header
layer as custom_upstream_headers.” Align the wording with the four-layer
precedence model used by CompatibleProviderConfig.DefaultHeaders and
custom_upstream_headers: make clear that OPENROUTER_SITE_URL and
OPENROUTER_APP_NAME map to provider default headers, while
custom_upstream_headers are a higher-precedence override layer, and keep the
existing precedence explanation consistent with that distinction.

config/providers.go (1)

26-29: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider documenting the new header-override fields.

CustomUpstreamHeaders, PassthroughUserHeaders, PassthroughUserHeadersSkip, and PassthroughUserHeadersSkipMode have no doc comments, unlike APIKeys above them. A short comment (e.g., valid skip/allow values for SkipMode, default behavior) would help operators reading this struct directly, mirroring the existing APIKeys convention.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@config/providers.go` around lines 26 - 29, The new header-override fields in
the provider config struct are undocumented, unlike the existing APIKeys field,
so add concise doc comments for CustomUpstreamHeaders, PassthroughUserHeaders,
PassthroughUserHeadersSkip, and PassthroughUserHeadersSkipMode. Describe the
intended behavior and defaults, especially how passthrough is enabled/disabled,
what the skip list applies to, and the valid SkipMode values such as allow and
skip, so readers can understand the ProviderConfig fields directly.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@CLAUDE.md`:
- Line 136: The provider header env var docs in CLAUDE.md omit the
always-blocked header behavior, so add a short callout near the existing
CUSTOM_UPSTREAM_HEADERS/PASSTHROUGH_* description that certain credentials,
hop-by-hop/transport headers, and the user-path alias are never forwarded even
when configured. Reference the existing Custom Headers doc and make it explicit
that values like Authorization may be silently dropped by the blocklist so
operators know where to look.

In `@docs/features/custom-headers.mdx`:
- Around line 109-119: Update the OpenRouter scenario table in
custom-headers.mdx to reflect the default values returned by identityHeaders()
when one env var is unset. The current `—` entries are incorrect; in the `Only
OPENROUTER_SITE_URL set` row, `X-OpenRouter-Title` should show the default app
name, and in the `Only OPENROUTER_APP_NAME set` row, `HTTP-Referer` should show
the default site URL. Keep the rest of the `custom_upstream_headers` and
`passthrough_user_headers_skip` examples unchanged.

In `@internal/providers/headers_test.go`:
- Around line 776-794: The test case in HeaderOverridesConfig is not proving
that defaults are preserved when static headers do not override them, because
X-Default is redundantly set in both DefaultHeaders and CustomUpstreamHeaders.
Update the "static overrides defaults" case in
internal/providers/headers_test.go so X-Default is supplied only by
DefaultHeaders and verify the expected result still includes it, using the same
HeaderOverridesConfig and want map assertions.

In `@internal/providers/openai/compatible_provider.go`:
- Around line 121-138: Add a unit test covering the branch in buildHeaderMutator
where cfg.HeaderOverrides.DefaultHeaders is already populated so the guard
len(overrides.DefaultHeaders) == 0 prevents cfg.DefaultHeaders from overwriting
operator-supplied values. Exercise this through NewCompatibleProvider or
buildHeaderMutator in internal/providers/openai/compatible_provider.go, and
assert the resulting request headers preserve the explicit
HeaderOverrides.DefaultHeaders precedence described by the doc comment.
- Around line 96-100: The comment about per-request key rotation is stale in the
provider setup and is attached to the wrong assignment block. Move that note to
the key-selection logic in buildHeaderMutator, where keys.Next() actually
happens, or remove/reword it from the cfg.HeaderOverrides and cfg.UserPathAlias
section in compatible_provider.go so the documentation matches the code path.

---

Outside diff comments:
In @.env.template:
- Around line 12-15: Update the OpenRouter comment in .env.template so it no
longer says the identity headers are “in the same header layer as
custom_upstream_headers.” Align the wording with the four-layer precedence model
used by CompatibleProviderConfig.DefaultHeaders and custom_upstream_headers:
make clear that OPENROUTER_SITE_URL and OPENROUTER_APP_NAME map to provider
default headers, while custom_upstream_headers are a higher-precedence override
layer, and keep the existing precedence explanation consistent with that
distinction.

In `@config/providers.go`:
- Around line 26-29: The new header-override fields in the provider config
struct are undocumented, unlike the existing APIKeys field, so add concise doc
comments for CustomUpstreamHeaders, PassthroughUserHeaders,
PassthroughUserHeadersSkip, and PassthroughUserHeadersSkipMode. Describe the
intended behavior and defaults, especially how passthrough is enabled/disabled,
what the skip list applies to, and the valid SkipMode values such as allow and
skip, so readers can understand the ProviderConfig fields directly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: f8dfac1e-7239-424e-bd89-ed9aaa23d29f

📥 Commits

Reviewing files that changed from the base of the PR and between a7af32c and 5ad1fcd.

📒 Files selected for processing (19)

• .env.template
• CLAUDE.md
• config/config.example.yaml
• config/providers.go
• docs/features/custom-headers.mdx
• internal/providers/config.go
• internal/providers/factory.go
• internal/providers/headers.go
• internal/providers/headers_test.go
• internal/providers/keyring_config_test.go
• internal/providers/ollama/ollama.go
• internal/providers/ollama/ollama_test.go
• internal/providers/openai/compatible_provider.go
• internal/providers/openrouter/openrouter.go
• internal/providers/openrouter/openrouter_test.go
• internal/providers/vllm/vllm.go
• internal/providers/xai/xai_test.go
• internal/server/http_test.go
• run/lifecycle_test.go

Both should be fixed @coderabbitai