chore(e2e): add Claude-driven real-provider test harness - #3
Merged
Conversation
Adds a top-level e2e/ test harness designed to be driven by Claude
Code: scripts are single-purpose Unix tools, scenarios live as
markdown runbooks (cases/*.md), no pytest framework lock-in.
Why this exists separate from tests/:
- tests/test_litellm/ uses mocks and never makes real provider calls,
so it cannot catch integration bugs where mock-based unit tests pass
but the real /metrics HTTP path or success-callback wiring is broken
- Real-provider tests cost money per run and depend on external API
availability — they must NEVER auto-run in `make test-unit` or CI
- Long-running development on this fork needs a reusable harness, not
one-off smoke scripts
Layout:
e2e/
├── README.md ← how to run, env contract
├── _config/
│ └── docker-compose.yml ← litellm built from local source + Postgres
├── tools/ ← Unix-style single-purpose CLIs
│ ├── proxy ← lifecycle: start|stop|status|logs|rebuild
│ ├── call ← one chat-completions request → JSON
│ ├── metrics ← /metrics: snapshot|diff|get
│ ├── keys ← virtual-key CRUD + hash
│ └── teams ← team CRUD
└── cases/
├── README.md ← case index
└── 01..12_*.md ← runbooks Claude executes
Configuration via e2e/.env (gitignored). Postgres is ephemeral by
design — every `proxy stop` wipes data so test runs are reproducible
and stale virtual keys can't poison later cases.
Initial case set (12 cases):
01-04: Anthropic prompt-cache metrics (5m/1h TTL, read, no-cache baseline)
05-06: OpenAI prompt-cache metrics (cached_tokens, no creation metric)
07: /metrics endpoint smoke
08-09: virtual-key + per-team label isolation (needs Postgres)
10: cost_breakdown must include cache_read_cost/cache_creation_cost
when the static model_cost entry has cache rates (GREEN guard)
11: spend_logs.error_information.error_message must not be silently
empty on auth failures — companion regression case for PR #2
12: custom_pricing path must not drop cache pricing when a
dashboard-added deployment lacks cache_*_input_token_cost in
litellm_params — currently RED, guards the future fix to
router.py:7237 (deployment-UUID entry merge)
Also documents the fork's branching strategy in CLAUDE.md: ship/v1.83.10
is the long-term ship branch (TAG + accumulated fix/* merges);
internal/v1.83.10-stable is the upstream-sync working branch (1700+
upstream commits, NOT to be used as fix base); litellm_internal_staging
is pure upstream tracking. All internal fix PRs target ship/v1.83.10.
.gitignore additions cover the rendered config (e2e/_config/
.litellm.rendered.yaml, produced by `proxy start` from .env values)
and tool pycache.
Test plan:
- Cases 01-07 verified GREEN against real Anthropic + OpenAI/GLM
providers (Bug #1 metrics fix)
- Case 11 GREEN after PR #2 merge (Bug #3 error_message fix)
- Case 10 GREEN against current ship state
- Case 12 deliberately RED — guards future router.py fix
- No changes to tests/test_litellm/ or any other ci-managed paths
8 tasks
songkuan-zheng
added a commit
that referenced
this pull request
Jun 4, 2026
* chore(e2e): add Claude-driven real-provider test harness
Adds a top-level e2e/ test harness designed to be driven by Claude
Code: scripts are single-purpose Unix tools, scenarios live as
markdown runbooks (cases/*.md), no pytest framework lock-in.
Why this exists separate from tests/:
- tests/test_litellm/ uses mocks and never makes real provider calls,
so it cannot catch integration bugs where mock-based unit tests pass
but the real /metrics HTTP path or success-callback wiring is broken
- Real-provider tests cost money per run and depend on external API
availability — they must NEVER auto-run in `make test-unit` or CI
- Long-running development on this fork needs a reusable harness, not
one-off smoke scripts
Layout:
e2e/
├── README.md ← how to run, env contract
├── _config/
│ └── docker-compose.yml ← litellm built from local source + Postgres
├── tools/ ← Unix-style single-purpose CLIs
│ ├── proxy ← lifecycle: start|stop|status|logs|rebuild
│ ├── call ← one chat-completions request → JSON
│ ├── metrics ← /metrics: snapshot|diff|get
│ ├── keys ← virtual-key CRUD + hash
│ └── teams ← team CRUD
└── cases/
├── README.md ← case index
└── 01..12_*.md ← runbooks Claude executes
Configuration via e2e/.env (gitignored). Postgres is ephemeral by
design — every `proxy stop` wipes data so test runs are reproducible
and stale virtual keys can't poison later cases.
Initial case set (12 cases):
01-04: Anthropic prompt-cache metrics (5m/1h TTL, read, no-cache baseline)
05-06: OpenAI prompt-cache metrics (cached_tokens, no creation metric)
07: /metrics endpoint smoke
08-09: virtual-key + per-team label isolation (needs Postgres)
10: cost_breakdown must include cache_read_cost/cache_creation_cost
when the static model_cost entry has cache rates (GREEN guard)
11: spend_logs.error_information.error_message must not be silently
empty on auth failures — companion regression case for PR #2
12: custom_pricing path must not drop cache pricing when a
dashboard-added deployment lacks cache_*_input_token_cost in
litellm_params — currently RED, guards the future fix to
router.py:7237 (deployment-UUID entry merge)
Also documents the fork's branching strategy in CLAUDE.md: ship/v1.83.10
is the long-term ship branch (TAG + accumulated fix/* merges);
internal/v1.83.10-stable is the upstream-sync working branch (1700+
upstream commits, NOT to be used as fix base); litellm_internal_staging
is pure upstream tracking. All internal fix PRs target ship/v1.83.10.
.gitignore additions cover the rendered config (e2e/_config/
.litellm.rendered.yaml, produced by `proxy start` from .env values)
and tool pycache.
Test plan:
- Cases 01-07 verified GREEN against real Anthropic + OpenAI/GLM
providers (Bug #1 metrics fix)
- Case 11 GREEN after PR #2 merge (Bug #3 error_message fix)
- Case 10 GREEN against current ship state
- Case 12 deliberately RED — guards future router.py fix
- No changes to tests/test_litellm/ or any other ci-managed paths
* chore(e2e): add --user-id sticky routing + master test runner
Two related improvements to the e2e test harness, both driven by
real-prod observations of the corp Anthropic gateway behavior:
1. `e2e/tools/call` learns `--user-id`. Forwarded to the proxy as the
OpenAI `user` field, which litellm in turn maps to Anthropic's
`metadata.user_id`. The corp gateway at maasapi.* uses this field
for sticky upstream-key load balancing — requests sharing the
same user_id land on the same upstream API key, so the second
request's prefix can read the first request's cache write. Without
sticky routing, the gateway round-robins anonymous requests across
~10+ upstream accounts each with its own cache namespace, and
cache_read never hits in test scenarios.
This was misdiagnosed initially as "gateway doesn't support cache
reads". Prod logs show that requests carrying device_id in their
end_user blob do achieve cache_read>0 (e.g. spend_logs entries
e0ab6f96 and eec6a70d both hitting cache_read=128k-135k tokens
under the same b0cb8e4d... device_id). Without device_id, the
same gateway shows cache_read=0 on subsequent calls.
2. All Anthropic e2e cases (01, 02, 03, 04, 08, 09) now pass
`--user-id` so cache-related assertions are deterministic
regardless of upstream-account routing. Case 03 (cache READ) flips
from SKIP-on-miss to required GREEN now that cache_read can be
reliably triggered.
3. `e2e/tools/run-all-cases` ships as a first-class tool (was a
/tmp scratch script). One PASS/FAIL/SKIP line per case, summary
at the bottom, exits 0 iff every case PASSes (SKIPs allowed).
Per-case logic split into `case_NN()` functions; adding a new case
means dropping a fixture + adding one function + one invocation.
Fixes a metric-snapshotting bug in the old runner: the previous
`snap()` returned the LAST matching `/metrics` series, which silently
compared two different series across before/after snapshots once
later cases minted new virtual keys / teams. New `snap_sum()` sums
across all series matching the label selector, giving stable totals
even as the series set grows. Case 01 now passes cleanly through
the runner.
`--skip-paid` flag skips real-provider cases (05, 06, 13) for a
~$0 smoke pass against the harness itself.
4. `e2e/cases/data/11_error_information_message_populated.sh` polls
spend_logs up to 20s instead of a flat 2s sleep — async logger lag
was producing flake.
Test plan
- `e2e/tools/run-all-cases` → 13/13 PASS
- Case 03 cache_read deterministically hits 1827 tokens with --user-id
- Case 01 no longer false-FAIL when runner is invoked after case 09
has minted virtual keys/teams
- Black 24.10.0 formatting clean on e2e/tools/call
* test(e2e): add case 16 — reset_budget_windows must not raise Prisma error
Verifies the cherry-pick of BerriAI#26346 at the full-stack
level: seed a key with `budget_limits` set, wait two ticks of the
background `ResetBudgetJob.reset_budget_windows`, then grep the
proxy container's logs for either the raw
`prisma.errors.MissingRequiredValueError` exception or the
"Failed to reset budget windows" wrapper line. Empty grep = PASS.
The case is intentionally key-path only — the team path is symmetric
and covered by unit tests
(`test_reset_budget_windows_resets_expired_team_window`,
`test_reset_budget_windows_query_error_does_not_break_team_path`).
Seeding a team via `/team/new` with `budget_limits` hits an unrelated
Prisma serialization bug in the team endpoint, which would mask the
result of this regression check.
Companion changes that the case relies on:
- `e2e/_config/docker-compose.yml`: pin
`PROXY_BUDGET_RESCHEDULER_MIN_TIME=10` /
`PROXY_BUDGET_RESCHEDULER_MAX_TIME=15`. Upstream default is ~600s
(10 min) which makes the case impossible to verify inside a sane
observation window; for dev/e2e there's no production reason to
wait that long. The fixture skips (exit 77, not fail) if a stale
container still has the upstream default — so an out-of-date
environment doesn't masquerade as a regression.
- `e2e/tools/proxy`: split rebuild into two commands. `build` is the
cached path (30-90s, default for source-only edits); `rebuild`
keeps the original `--no-cache` semantics (3-5 min, for Dockerfile
/ dep changes). The cached path was always implicitly possible via
`docker compose build`, but only `--no-cache` was surfaced through
the tool, forcing a full rebuild on every fix-and-verify cycle.
- `CLAUDE.md`: document that root-level `e2e/` is the project's
Claude-driven end-to-end harness, and that full-stack regression
verification (DB schema, background jobs, real HTTP flow) belongs
under `e2e/cases/` rather than under `tests/`.
songkuan-zheng
added a commit
that referenced
this pull request
Jun 10, 2026
…axonomy (#78) * fix(streaming): reset Anthropic message_start cursor (output_tokens=1) when no message_delta arrives The Anthropic streaming protocol emits `message_start.usage.output_tokens=1` as a placeholder cursor; the real cumulative output count only arrives in the final `message_delta` event. When a stream is cancelled before `message_delta` lands (common for thinking models on long-tail prompts), ChunkProcessor._calculate_usage_per_chunk's last-wins accumulator left completion_tokens stuck at 1. Because 1 is truthy, the `completion_tokens or token_counter(text=...)` fallback in calculate_usage() never fired, and requests were billed for 1 output token even when several thousand tokens of text had actually streamed. Fix: track whether any chunk's completion_tokens exceeded 1 (saw_non_cursor_completion). If the only update we saw was the cursor, reset completion_tokens to 0 so the text-based fallback estimates from the real completion content. Legitimate 1-token completions (model returns "Yes." etc.) are unaffected in practice — token_counter on a 1-token completion_output also yields ~1, so billing stays approximately correct. Tier: C (universal bug fix — affects every LiteLLM user calling Anthropic with streaming + cancel/timeout). Upstream PR candidate once landed here. Tests added: - TestAnthropicCursorBug (6 cases) — pins the post-fix behavior - TestNonAnthropicStreamingIntact (2 cases) — guards against regression on providers without the cursor pattern All 9 existing streaming_chunk_builder_utils tests still pass. * feat(spend_logs): add success_partial status + cancellation metadata fields Adds the schema scaffolding for tracking client-cancelled requests as a billable "success_partial" status (instead of dropping them into the failure bucket, which both pollutes the proxy failure rate metric and zeroes out billing for compute the upstream provider already charged us for). New StandardLoggingPayloadStatus value: - "success_partial": client disconnected mid-flight (or upstream cut early) but upstream consumed billable compute. Bills prompt + the output that was generated up to cancellation. Does NOT count toward the proxy failure rate. New Literal types in litellm/types/utils.py (used by PR #3 cancel-billing path to populate metadata fields): - CancelPhase: before_upstream | during_upstream | streaming_partial | during_parsing - CancelUsageSource: upstream_truth | tokenizer_estimate | upstream_completed_after_cancel | shield_timeout | no_completion New StandardLoggingMetadata + SpendLogsMetadata fields (all Optional, populated only when the cancel-billing path fires): - cancellation_indicator: client_disconnect | upstream_disconnect - cancel_phase: lifecycle phase when cancel was detected - bytes_delivered_to_client: total bytes ACK'd to client before disconnect - upstream_completed: whether upstream call ran to completion - usage_source: provenance of the recorded usage numbers DB compatibility: - LiteLLM_SpendLogs.status is `String?` (not enum) — accepts new value without migration. - LiteLLM_SpendLogs.metadata is `Json?` — new fields land inside the JSON blob, no migration required. - Existing `metadata.error_information.error_code` (used by nginx/ Prometheus dashboards) is unchanged; cancellation fields are additive. Tier: B (internal change to a TypedDict + helper init; downstream behavior change ships in PR #3). The success_partial status name and field semantics are coordinated with the upcoming cancel-billing module. Tests: - 10 new cases covering literal acceptance, None-init, round-trip, error_code coexistence, and enum value coverage. - All 73 existing spend_tracking tests pass. * feat(cancel): catch CancelledError + re-route streaming/non-stream cancels to success_partial path Closes the 499 black hole. asyncio.CancelledError is a BaseException subclass since Python 3.8 — every `except Exception` in LiteLLM was letting it slip through silently: * SpendLogs got no row for the cancelled request * No callback fired (Langfuse trace stuck "Running", Prometheus failed_requests counter not incremented) * The upstream provider continued generating after the client TCP close and billed us for compute that never reached our ledger This PR introduces a small finalize layer that catches the cancel signal, marks the Logging object with cancel_phase / cancellation metadata (matching PR #4's schema), dispatches the partial response through the normal async_success_handler path with the new status="success_partial" classification, and re-raises CancelledError so asyncio's cancellation contract is preserved. Files ----- * litellm/litellm_core_utils/cancel_finalize.py (new) Public helpers: - mark_logging_obj_cancelled(logging_obj, phase, indicator, bytes_delivered): idempotent dict mutation; pathological inputs (None logging_obj, missing model_call_details) are no-ops. - finalize_streaming_cancel(stream_wrapper, logging_obj, ...): runs stream_chunk_builder on accumulated chunks → dispatches through async_success_handler with success_partial intent. Shielded internally so the SpendLogs write completes even if the runtime injects more cancel signals during teardown. Falls back to post_call_failure_hook if there are zero chunks. - finalize_non_stream_cancel(upstream_task, logging_obj, ..., shield_timeout_s=60.0): shields the upstream call past the cancel and waits for real usage (strategy A). On timeout, cancels upstream and records usage_source="shield_timeout". * litellm/proxy/proxy_server.py — async_data_generator Added `except asyncio.CancelledError:` before `except Exception:` that calls finalize_streaming_cancel and re-raises. * litellm/proxy/common_request_processing.py — async_streaming_data_generator Same catch for the /v1/messages and /v1beta/...generateContent paths (Anthropic + Google). * litellm/litellm_core_utils/streaming_handler.py — __anext__ Defense-in-depth: if cancel reaches the stream wrapper directly (not via the proxy generator), mark the Logging object and re-raise so whoever does finalize the request gets the marker. * CLAUDE.md — Test discipline Added "No theater tests" rule: mock the boundary (httpx transport, DB cursor), not the unit under test. Use a small spy fake to capture handler args; assert on the captured data, not on `.called`. Example: instead of mocking `stream_chunk_builder`, pass real ModelResponseStream chunks in. The rule is enforced in this PR's test file. Tests (18 cases, all real — no mocking of the unit under test): * mark_logging_obj_cancelled: dict-mutation contract incl. idempotency, None handling, no-pollution-with-Nones * is_logging_obj_cancelled: marker detection * _get_accumulated_chunks: stream wrapper variants * finalize_streaming_cancel: - Real Anthropic-shaped chunks (message_start cursor=1 + content deltas, NO message_delta) run through real stream_chunk_builder → captured response.usage.completion_tokens > 1, exercising the cross-PR contract with PR #1's cursor reset - No-chunks edge: real post_call_failure_hook spy verifies fallback fires with a CancelledError, not a swallowed signal - Downstream success_handler raising must NOT propagate * finalize_non_stream_cancel: - Shield-wait happy path: real asyncio task, real response flows through to captured success kwargs - Shield timeout: upstream task actually cancelled - Upstream exception during shield window - No upstream task (before_upstream cancel) Cost computation for the partial response — the actual implementation of "modified strategy 5'" billing — lands in PR #3 (cancel_billing.py) which reads the markers this PR sets. Until PR #3 lands, the reassembled partial response runs through the existing cost calculator unchanged, which is already a significant improvement over the prior "drop everything" behavior because PR #1's cursor=1 fix produces sensible partial usage for Anthropic. Tier: C+D (Tier C for the BaseException catch fix — purely a bug; Tier D for the success_partial taxonomy — opinionated mechanism with billing implications we want carried in the fork until upstream agrees on semantics). * feat(cancel): compute partial cost + bridge cancel metadata to SpendLogs Completes the cancel-billing path started in PR #2. cancel_finalize was catching cancels and dispatching through async_success_handler with a reassembled partial response, but two gaps remained: 1. The cancellation markers written to logging_obj.model_call_details never reached SpendLogs — _get_spend_logs_metadata pulls fields from request_data.litellm_params.metadata, not from model_call_details. Result: SpendLogs rows existed (good, no more black hole) but had no cancel_phase / usage_source / etc., so dashboards couldn't tell normal vs partial. 2. The zero-chunk fallback path (finalize → failure hook) still wrote response_cost=0.0 — the upstream provider received the prompt and started processing, but our ledger said "free". For thinking models on long prompts this is a real $ leak ($0.003-$0.01 per 499 in production). Files ----- * litellm/litellm_core_utils/cancel_billing.py (new): - compute_prompt_only_cost(messages, model, custom_llm_provider): best-effort prompt-only $ via the real LiteLLM cost map. Returns 0.0 on any pricing failure — caller is in the failure hook and cannot afford an exception. Wraps token_counter + cost_per_token so the cost-map lookup path is exercised by real provider IDs. - enrich_request_metadata_with_cancel_markers(request_data, logging_obj): copies the five cancel markers from model_call_details into litellm_params.metadata. Idempotent; no-op when there's no marker (normal requests pay zero overhead). Overrides metadata.status to "success_partial". * litellm/litellm_core_utils/cancel_finalize.py: - finalize_streaming_cancel now calls enrich_request_metadata_with_cancel_markers right after mark_logging_obj_cancelled, so the partial response dispatched through async_success_handler carries the markers into the cost-tracking pipeline. - finalize_non_stream_cancel does the same bridge, AND a second bridge after the shield-wait outcome is known (upstream_completed / usage_source can change after the asyncio.wait_for resolves). * litellm/proxy/hooks/proxy_track_cost_callback.py: - async_post_call_failure_hook: when the failure is actually a CancelledError (i.e. the cancel-finalize fallback path because no chunks were received), compute the prompt-only cost via cancel_billing.compute_prompt_only_cost instead of the hardcoded 0.0. Other failures (provider 5xx, real timeouts) still write 0.0 — there's no compute on our side to bill in those cases. - Same hook also calls enrich_request_metadata_with_cancel_markers so failure-path SpendLogs rows tagged success_partial get the right metadata even when called by external code paths that didn't go through cancel_finalize first. Tests (12 new cases, no mocking of cost_per_token / token_counter): * TestComputePromptOnlyCost: - Real Anthropic & OpenAI pricing paths exercised → cost > 0 with sanity upper bound (catches both "always 0" and "wrong rate" regressions) - Unknown model degrades to 0.0 without raising - Long-prompt cost scales with token count (sanity that we're actually counting, not constants) * TestEnrichRequestMetadataWithCancelMarkers: - No-op when no marker (must not pollute normal requests) - All five markers + status override propagate - Creates missing litellm_params.metadata dict - Partial markers don't insert keys for absent ones - Overwrites stale status (success / failure → success_partial) All 43 Phase 1 tests pass together (cursor + schema + cancel_finalize + cancel_billing). 82 streaming + spend_tracking regression tests pass. Tier: D (mechanism with billing policy — bills > 0 for cancelled requests, which is a behavior change downstream consumers can observe). * test(e2e): add case 26 cancel-billing + plumb success_partial through SpendLogs Adds an e2e case that verifies the full Phase 1 cancel-billing chain end-to-end against the live proxy + Postgres, and fixes three real plumbing bugs the case exposed: 1. FallbackStreamWrapper.__anext__ did not accumulate chunks FallbackStreamWrapper inherits from CustomStreamWrapper but overrides __anext__ to delegate to its own async generator — bypassing the parent's `self.chunks.append(chunk)`. Result: any streaming request that went through the Router fallback wrapper had empty wrapper.chunks, so finalize_streaming_cancel's reassembly path saw "no chunks" and fell through to the failure-hook fallback. Fix: append in __anext__ to mirror the parent. 2. enrich_request_metadata_with_cancel_markers only touched one of two metadata dicts The proxy failure path reads metadata from request_data["litellm_params"]["metadata"]; the success path reads from logging_obj.litellm_params["metadata"]. These are usually the same object but can diverge after construction-time copies. Fix: update both. Detected via case 26 showing status="success" completion_tokens=200 with all cancel markers blank — the success path was getting the partial response but not the markers. 3. _get_status_for_spend_log only knew "success" / "failure" metadata.status was set to "success_partial" by the cancel-finalize bridge, but _get_status_for_spend_log collapsed any non-"failure" value back to "success" before writing the LiteLLM_SpendLogs.status column. Dashboards filtering `WHERE status='success_partial'` would have matched zero rows. Fix: widen the Literal to three values and pass success_partial through unchanged. 4. _ProxyDBLogger.async_post_call_failure_hook clobbered cancel markers and hardcoded status="failure" The failure hook rebuilt litellm_params.metadata from scratch, preserving only "tags" — cancel markers set by cancel_finalize were lost on the zero-chunk fallback path. Also hardcoded metadata.status = "failure" even for CancelledError. Fix: detect CancelledError and classify as success_partial; preserve the five cancel marker fields alongside the existing tags preservation. 5. time.time() vs datetime.now() in finalize success_handler calls async_success_handler expects datetime instances for start_time / end_time (it does arithmetic on them); passing time.time() floats raised TypeError in the cost calculator and silently dropped the row. Fix: datetime.now(). Test plan (live proxy + Postgres): * Case 26 C1: streaming cancel mid-flight → status=success_partial, completion_tokens=214, cancel_phase=streaming_partial * Case 26 C2: long stream cancelled near end → status=success_partial, completion_tokens=760 * Case 26 C3: zero-chunk cancel → status=success_partial, completion_tokens=14 * Full mock-only e2e suite: 17/17 pass, 0 fail, 8 skip (expected real-provider skips). No regression in cases 04, 06, 07, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 23, 25. Unit tests: * 43 Phase 1 tests still pass (cursor + schema + cancel_finalize + cancel_billing). * 82 streaming + spend_tracking regression tests still pass. Tier: C (FallbackStreamWrapper accumulation, _get_status_for_spend_log widening — universal bug fixes) + D (success_partial classification, metadata bridging policy). * test(e2e): cases 27-32 cancel-billing expansion + Phase 2 gaps documented Extends the cancel-billing e2e coverage with five new mock-only cases. Two PASS outright, three honestly SKIP with detailed deferral reasons that point at the remaining Phase 2 work. PASSING (new): 29 failure-not-polluted — Forces upstream 503; asserts SpendLogs row classifies as status=failure with error metadata populated. Critical regression guard: without this, the CancelledError check in proxy_track_cost_callback could silently grow to catch other exceptions and start polluting success_partial. 32 concurrent-cancels — Fires 10 concurrent stream cancels, asserts all 10 SpendLogs rows write with success_partial + the marker, and a control health probe returns in < 3s (no asyncio task leak under contention). DEFERRED (skip 77, with detailed runbook comments): 27 non-stream-cancel — finalize_non_stream_cancel exists and is unit-tested, but no caller wires it up. LiteLLM removed the check_request_disconnection polling task (it's dead code in proxy_server.py), so non-stream cancel detection requires a Phase 2 polling revive. Until then non-stream cancels look like normal successes from the proxy's view (which is at least billing-correct, just unclassified). 28 v1-messages-cancel — The CancelledError catch in common_request_processing.py IS firing (verified: SpendLogs row gets correct partial completion_tokens reflecting bytes received before cancel), but the success_partial markers don't propagate because response.logging_obj is None on the anthropic_messages path. Phase 2: pull logging_obj from request_data["litellm_logging_obj"] instead of from response. 30 shield-timeout — Depends on case 27 wiring. Implemented the LITELLM_CANCEL_SHIELD_TIMEOUT_S env var (default 60s, e2e sets 2s) so the case can run deterministically once polling is wired. Other changes: * e2e/_config/mock_provider.py: added time.sleep(ttft_ms) to the Anthropic non-stream path so case 27/30 can deterministically drive client-cancel timing once the proxy plumbing lands. * e2e/_config/docker-compose.yml: sets LITELLM_CANCEL_SHIELD_TIMEOUT_S=2 on the proxy container. * litellm/litellm_core_utils/cancel_finalize.py: reads LITELLM_CANCEL_SHIELD_TIMEOUT_S env var at module load for the DEFAULT_CANCEL_SHIELD_TIMEOUT_S knob. Suite outcome: 30 cases · 19 PASS · 0 FAIL · 11 SKIP (11 skips = 6 pre-existing Tier=real + 1 pre-existing thinking-signature + 1 pre-existing anthropic-beta-overrides + 3 new Phase-2-deferred). Tier: B (e2e infrastructure + documentation of Phase 2 gaps). * feat(cancel): Phase 2 — non-stream cancel detection + /v1/messages markers Closes the remaining Phase 2 gaps documented in commit 987df5f: 1. /v1/messages cancel markers didn't reach SpendLogs (case 28) The CancelledError catch in async_streaming_data_generator was firing correctly but `getattr(response, "logging_obj", None)` returned None on the Anthropic native path (response is an async iterator without that attribute), so mark_logging_obj_cancelled became a no-op. Additionally, `_get_litellm_metadata_from_kwargs` prefers the newer `litellm_metadata` dict over `metadata` — and the cancel markers were only written to the latter, so they were filtered out by the SpendLogs pipeline even when present on the Logging instance. 2. Non-stream cancel was a silent black hole (case 27, 30) No proxy code path detected client disconnect during non-stream LLM calls. The dead-code `check_request_disconnection` helper had been in proxy_server.py for ages but with zero callers. Fixes ----- litellm/proxy/proxy_server.py + litellm/proxy/common_request_processing.py Both streaming catches: when response.logging_obj is None, fall back to request_data["litellm_logging_obj"]. Required for /v1/messages, /v1beta/...streamGenerateContent and any other endpoint where the response object isn't a CustomStreamWrapper. litellm/litellm_core_utils/cancel_billing.py enrich_request_metadata_with_cancel_markers now writes to BOTH the `metadata` and `litellm_metadata` keys on each litellm_params dict (request_data + logging_obj.litellm_params). litellm_metadata is the newer-endpoint variant; without writing to it, /v1/messages cancellations couldn't surface success_partial markers because the cost callback's metadata extractor returns litellm_metadata when both are present. litellm/proxy/common_request_processing.py — base_process_llm_request Added a _disconnect_watcher task that polls request.is_disconnected() every second while the LLM call is in flight. On detection: * Records the disconnect time and KEEPS the LLM call running. We don't want to cancel it: the upstream provider has almost certainly started processing and will charge us regardless, so the right thing is to record real upstream usage. * If the LLM call completes within LITELLM_CANCEL_SHIELD_TIMEOUT_S (default 60s, env-tunable) of the disconnect, the row gets tagged with usage_source=upstream_completed_after_cancel and upstream_completed=True. * If the budget elapses with the LLM still running, give up waiting, synthesize an empty response so the handler can return, and tag usage_source=shield_timeout / upstream_completed=False. The real response (when it eventually comes back from upstream) will fire a SECOND SpendLogs row via the normal success path — that's acceptable because it preserves the upstream-billing alignment. Implemented as a `wait_for(shield(...), poll_interval)` loop rather than a single wait_for + shield, so the watcher task gets a chance to set disconnect_flag between polls without being interrupted by the timeout itself. Cleaned up via a finally that cancels the watcher task regardless of how the LLM call resolved. e2e/cases/27, 28, 30 Un-skipped; all three now PASS against the live proxy. Test plan (mock-only e2e suite, full run): * 30 cases · 22 PASS · 0 FAIL · 8 SKIP * 8 SKIP = 6 Tier=real + 1 thinking-signature (pre-existing) + 1 anthropic-beta-overrides (Tier=real, requires Bedrock). All cancel- related cases now PASS — no remaining Phase 2 deferrals. * 125 unit tests still pass (cancel_billing 12 + cancel_finalize 18 + cursor 8 + spend_logs metadata 5 + streaming regression 9 + spend tracking regression 73). Tier: C (universal bug fix — anyone relying on non-stream cancel detection or the /v1/messages cancel taxonomy was getting wrong rows) + D (the disconnect-watcher's shield-and-wait policy is opinionated billing behavior we want to carry until upstream agrees on semantics). * feat(cancel): Phase 3 — orthogonal delivery_status/billing_status taxonomy Replace the single `status='success_partial'` marker with two orthogonal dimensions derived at SpendLog write time from the five cancel markers plus the raw status: delivery_status ∈ {full, partial, none} # what reached the client billing_status ∈ {full, partial, none} # what we billed The top-level SpendLogs status filter stays binary (success | failure); cancellations carry `status='success'` with metadata markers and the UI surfaces them through the new derived columns. Callers that need to target the cancel slice in SQL can filter on `metadata::jsonb->>'delivery_status'` / `billing_status` directly. Scope: - core derivation in `spend_tracking_utils._derive_delivery_billing_status` is the single source of truth — no other writer sets these fields. - e2e cases 26–30 and 32 updated to assert both dimensions; case 33 (real-anthropic-cancel) added end-to-end. - UI: view_logs columns and filter_options surface the new fields. - Tests added for the new derivation and for the binary status filter (test_status_filter_condition). * docs(cancel): post-Phase-3 cleanup — rename case 26, refresh case 33 doc, harden case 30 preflight, log upstream PR candidates - e2e/cases/26 renamed: success_partial → partial (refactor dropped the three-valued status sentinel). Updated dispatcher reference in run-all-cases. - e2e/cases/26 + 33 .md docs rewritten to describe the new binary status + orthogonal delivery_status / billing_status taxonomy, including the failure-mode lookup table for case 33 (real Anthropic). - e2e/cases/data/30_shield_timeout.sh: add the mock-container healthcheck preflight that the other mock-only cases already have, so real-mode runs SKIP (rc=77) instead of FAIL. - UPSTREAM_PR_QUEUE.md: log two Tier-C candidates (cursor=1 reset + CancelledError catch) and the Phase 3 taxonomy as a Tier-D ISSUE-FIRST entry. Refresh Last reviewed. Tier: B (internal infra / docs). Tried upstream first: N/A — purely internal cleanup.
songkuan-zheng
pushed a commit
that referenced
this pull request
Jun 15, 2026
…suer-scoped JWT auth (BerriAI#28356) * fix(proxy): point /metrics 401 at the opt-out flag Operators upgrading past 35bbca60b0 (which made /metrics auth default-on) see "Malformed API Key passed in. Ensure Key has 'Bearer ' prefix." with no hint that litellm_settings.require_auth_for_metrics_endpoint: false restores the previous unauthenticated behavior. Append that discovery hint to the existing 401 body so a Prometheus scraper that breaks after upgrade has a clear migration path. No behavior change. * fix(proxy): bound budget reservation per request instead of pinning to remaining headroom reserve_budget_for_request fell back to reserving the entire remaining team/key/user headroom whenever a request omitted max_tokens, which pinned the spend counter at max_budget for the duration of the in-flight request and false-positive-blocked every concurrent or back-to-back request until the success callback reconciled. Surfaced as an integration-test team being budget-blocked at its $2000 cap while DB spend was $0.144. Switch the missing-max_tokens path to a fixed default of 16384 output tokens (mirrors parallel_request_limiter_v3's DEFAULT_MAX_TOKENS_ESTIMATE precedent), and clamp explicit max_tokens at the model's max_output_tokens for reservation accounting only. The outbound request body is unchanged, so providers see whatever the caller actually sent; only the local integer used to compute reservation cost is bounded. This also prevents a hostile max_tokens=999999999 from inflating one request's reservation up to the entire team headroom. For Opus 4.7 (output $25/M, max_output 128K) on a $2000 budget the worst-case per-request reservation drops from "everything left" to $3.20, raising admittable concurrency from 1 to ~625. * fix(proxy): reserve per-image cost for image-generation requests Image-generation routes (dall-e-3, flux, etc.) have no per-token output cost so they fell through to the no-reservation read-time-only path. Concurrent image requests against a depleted budget could all pass common_checks (counter exactly at max_budget passes the strict-`>` gate) and reach the provider before reconciliation caught up. Add per-image reservation in _estimate_request_max_cost_for_model: when the model has a per-image cost field, reserve `n × cost_per_image` upfront. The atomic counter increment serializes concurrent admissions, so the second request sees the post-first-reservation counter and raises BudgetExceededError instead of silently leaking through. Both `output_cost_per_image` and `input_cost_per_image` are honored — naming is inconsistent across providers (OpenAI dall-e-3 uses input_cost_per_image, aiml/dall-e-3 uses output_cost_per_image for the same per-generated-image price). Per-pixel pricing (DALL-E 2 size variants) and TTS/STT routes still fall through to read-time enforcement; those are follow-ups. * fix(proxy): gate image-gen reservation strictly on model mode The previous detection treated any model with input_cost_per_image or output_cost_per_image as image generation. Several chat and embedding models carry those fields to price multimodal vision input, not generated images: - gemini-3.1-pro-preview (mode=chat) has output_cost_per_image=0.00012 alongside input/output token pricing. - azure/gpt-realtime-* (mode=chat) has input_cost_per_image=5e-6. - amazon.titan-embed-image-v1 (mode=embedding) has input_cost_per_image=6e-5. For these models the image-gen branch fired first and reserved a fraction of a cent per request, short-circuiting the token-priced path entirely. Long Gemini chats reserved 1 × $0.00012 instead of the true token cost. Gate strictly on mode in {"image_generation", "image_edit"}. All 197 real image_generation entries and all 31 image_edit entries (Flux Kontext, Stability inpaint/outpaint, etc.) carry the right mode, so the field-presence fallback was unnecessary. Adds regression tests for the chat-model-with-image-cost-field case and for image_edit reservation. * build(packaging): relax core runtime pins to ranges Backport of #27241 onto litellm_1.84.0rc2. The 12 entries in `[project.dependencies]` were exact `==` pins, a side effect of the Poetry -> uv migration. This forces every downstream package that lists litellm as a dependency to downgrade common runtime libraries (openai, pydantic, aiohttp, click, jsonschema, ...) to the exact versions we ship. Switch to lower-bounded ranges with upper bounds where the upstream package is pre-1.0 or has a known breaking-major-version policy. Reproducibility for our Docker proxy and CI continues to come from `uv.lock`, which is regenerated here as a metadata-only diff. Conflict resolution vs upstream merge: - The upstream merge commit also surfaced unrelated context entries (nvidia-riva-client, soundfile/stt-nvidia-riva extra) that exist in staging but not in rc2. Those are not part of #27241's intent and were dropped from the resolution; the rc2 uv.lock keeps its existing entry set, only the 12 specifier strings changed. - `uv lock --check` passes (392 packages resolved, no drift). * build(packaging): raise jinja2 floor to 3.1.6 Our `uv.lock` already resolves jinja2 to 3.1.6, so Docker / CI installs get that version. The `pyproject.toml` floor was lagging at 3.1.0, which means downstream consumers using `--resolution=lowest-direct` or older constraint files can land on 3.1.0-3.1.5 instead of the version we actually test against. Aligns the declared floor with the resolved version so external installers see the same baseline our test matrix exercises. `uv lock` diff is metadata-only (no resolved-version drift). * fix(mcp): forward extra_headers for OpenAPI MCP tools OpenAPI-generated tools only applied static closure headers and BYOK Authorization via ContextVar. Copy MCPServer.extra_headers from the incoming MCP request into _request_extra_headers (set in server.py before local tool dispatch), merge in openapi_to_mcp_generator via a small helper. OAuth2 M2M: do not forward caller Authorization from raw_headers (same rule as _prepare_mcp_server_headers for managed MCP). Adds TestRequestExtraHeaders and clarifies mcp_server_manager registration comment. Fixes #26794 Co-authored-by: Cursor <cursoragent@cursor.com> * refactor(mcp): access has_client_credentials on MCPServer directly Greptile: getattr default was redundant; property exists on MCPServer and mcp_server is non-None inside the extra_headers forwarding block. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(mcp): static headers win over forwarded headers in OpenAPI MCP Match the existing MCP invariant in merge_mcp_headers and the managed MCP path: operator-configured static headers always override caller-forwarded headers on name conflict, with case-insensitive comparison so different casing cannot bypass the precedence. _request_auth_header (BYOK) still overrides Authorization last. Addresses Veria review on PR #27383. Co-authored-by: Mateo Wang <mateo-berri@users.noreply.github.com> * fix(proxy): always merge caller-supplied tags into request metadata Caller-supplied tags (`x-litellm-tags` header, body `tags`, `metadata.tags`) were silently dropped unless the key/team had `metadata.allow_client_tags: true` set. Restore the documented behavior: tags from the request always flow into `metadata.tags` and union with any admin-configured static tags from key/team/project metadata. Removes the `allow_client_tags` opt-in flag from the pre-call pipeline. The flag was only ever read here; it has no schema or endpoint footprint, so leftover values in existing key metadata are inert. Test cleanup mirrors the simplification: drop the three tests that verified the strip-when-not-opted-in path, drop the `allow_client_tags` fixture lines from the merge/union tests. * docs(proxy): refresh stale comments referencing removed tag strip The tag-strip block was removed in the parent commit but two surrounding comments still referenced "tags without opt-in" and "runs AFTER the strip". Update them to describe the remaining user_api_key_* and _pipeline_managed_guardrails strip that the snapshot/merge ordering actually protects against. * chore: reject bare str at file-input sinks to prevent local-file read (#27762) Cherry-pick of #27762 onto litellm_1.84.0rc2. * chore: reject bare str at file-input sinks to prevent local-file read (#27667) * fix: use os.PathLike in ocr sink and check truthy reasoningSummary for bridge - ocr/main.py: widen Path check to os.PathLike for consistency with other sinks - main.py: bridge condition checks truthiness of reasoning_summary, not just None * fix: remove unused pathlib.Path import in ocr/main.py Co-authored-by: yuneng-jiang <yuneng@berri.ai> Co-authored-by: ryan-crabbe-berri <ryan@berri.ai> Co-authored-by: stuxf <70670632+stuxf@users.noreply.github.com> * Strip SERVER_ROOT_PATH before lazy-feature prefix match LazyFeatureMiddleware compared the raw scope path against registered prefixes (e.g. /policies), so requests under a server root path like /api/v1/policies/... never matched, the feature never loaded, and the endpoint returned 404. Strip the configured root path before matching, normalizing trailing slashes and enforcing a component boundary so /api does not falsely match /apiv2. * Cache normalized SERVER_ROOT_PATH at middleware init SERVER_ROOT_PATH is a process-startup env var. Read it once in __init__ instead of calling get_server_root_path() + rstrip on every request that arrives before all lazy features have loaded. * chore(proxy): backport /key/regenerate ownership-rebind + premium-gate guards (#27793) Backport of #27793 onto litellm_1.84.0rc2. A non-admin caller could rebind their own key's user_id via /key/regenerate. _execute_virtual_key_regeneration had org/team guards but no user_id guard, and prepare_key_update_data did not strip the field — it survived model_dump(exclude_unset=True) into the Prisma update. On the next request, _return_user_api_key_auth_obj resolved the rebound user_id against litellm_usertable and returned PROXY_ADMIN whenever the target row's user_role was admin. /key/update had the equivalent guard inline at _validate_update_key_data; extract it to a shared helper _validate_caller_can_change_key_ownership and call from both /key/update and _execute_virtual_key_regeneration. Also tighten the premium gate that allowed the master-key rotation branch to skip the enterprise check. The previous predicate was a field-presence test, not an identity check. Verify the caller actually holds the master key via _is_master_key before allowing the non-premium path. Block explicit-null user_id and empty-string user_id as removal attempts; both 403-reject for non-admin callers. * fix(proxy): expose db status on public /health/readiness Backport of #27866 onto litellm_1.84.0rc2. External readiness probes consumed the legacy detailed payload's `db` field to drive alerting and pod-rotation decisions. Stripping the body to {"status": "healthy"} broke those probes silently — the HTTP code still flipped to 503, but probes checking body.db == "connected" treated the response as healthy. Add `db` back to the unauthenticated payload. The rest of the diagnostic fields (litellm_version, callbacks, cache, log_level) stay behind /health/readiness/details so the recon-leak gate from #26912 holds. Values match the legacy contract: "connected", "disconnected", "Not connected". The 503-on-DB-disconnect behavior from LIT-2607 is preserved. * fix(ui): fetch version + debug flag from /health/readiness/details The proxy moved `litellm_version`, `is_detailed_debug`, and other diagnostic fields off the public `/health/readiness` payload behind an auth-gated `/health/readiness/details` endpoint. The navbar version tag and the detailed-debug-mode banner stopped working because they were still reading those fields from the unauthed response, which no longer contains them. Replace `useHealthReadiness` with a `useHealthReadinessDetails` hook that takes an `accessToken` argument and sends a Bearer header to the auth-gated endpoint. The hook stays disabled while `accessToken` is falsy, so the navbar can keep rendering on the public model hub (where the token is null) without triggering an auth redirect or a 401-loop. * fix(ui): disable retries on readiness/details + cover token forwarding Two small follow-ups on the readiness/details migration: - Set `retry: false` on the query. The payload feeds a passive navbar tag and a debug banner; a 401 from an expired token shouldn't fan out into three retries against the proxy. - Add navbar specs that assert the `accessToken` prop is forwarded into the hook (matches the DebugWarningBanner spec). Without this, the navbar could silently regress to passing `undefined` and the existing tests wouldn't catch it. * chore: update Next.js build artifacts (2026-05-14 03:52 UTC, node v20.20.2) * Merge pull request #27898 from stuxf/chore/banned-params-extra-body-cover chore(proxy): cover extra_body + azure_ad_token in banned-params check (cherry picked from commit a6a9d8edf024a7d808ba18df4aace4815e5f5925) * Merge pull request #27801 from stuxf/chore/get-instance-fn-runtime-s3-gate chore(proxy): refuse remote-URL instance-fn loads outside config-file path (cherry picked from commit e3e5209f51a605d49f4c1ef9b010ed5fdd1812c6) * fix: block client-side pricing injection via request body Authenticated clients could supply CustomPricingLiteLLMParams fields (input_cost_per_token, output_cost_per_token, etc.) in the request body. These were forwarded to register_model() in main.py, permanently mutating the shared global litellm.model_cost dict for all users on the instance. Adds all CustomPricingLiteLLMParams fields to _BANNED_REQUEST_BODY_PARAMS so is_request_body_safe() rejects them before they reach completion(). New pricing fields added to CustomPricingLiteLLMParams are auto-covered. Admin opt-in via allow_client_side_credentials or configurable_clientside_auth_params still works as before. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> * fix: block SSRF fields in RAG ingest vector_store config aws_sts_endpoint, aws_web_identity_token, and aws_bedrock_runtime_endpoint in ingest_options.vector_store were passed directly to the Bedrock ingestion class, which reads them into boto3 STS client construction. Any authenticated caller could redirect AssumeRole calls to an attacker-controlled server, leaking the proxy's instance profile credentials. Calls is_request_body_safe() on ingest_options["vector_store"] before forwarding to litellm.aingest(). Same banned-params list and admin opt-in escape hatch (allow_client_side_credentials) as the /chat/completions path. ValueError from the safety check is caught and re-raised as HTTP 400. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> * fix: harden /key/update authorization checks (#27878) * fix: patch Host-header auth bypass in get_request_route Starlette reconstructs request.url from the Host header. A malformed Host like `localhost/?x=1` causes Starlette to build the full URL as `http://localhost/?x=1/health`, which url-parses to path="/". Since "/" is in LiteLLMRoutes.public_routes, all protected routes became reachable without authentication. Fix: read scope["path"] (set by uvicorn from the HTTP request line, not derivable from headers) instead of request.url.path. Sub-path deployments are handled via scope["app_root_path"] / scope["root_path"], mirroring Starlette's own base_url construction logic. Affected variants confirmed fixed: Host: localhost/?x=1 Host: localhost:4000/?x=1 Host: localhost/#test Host: localhost:4000/#test Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> * style: reduce comments in route fix Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> * fix: block credential fields in RAG ingest vector_store options Credential fields (vertex_credentials, aws_access_key_id, api_key, etc.) in ingest_options.vector_store are now rejected at the API boundary with a 400 error. Credentials must be configured server-side. Previously any authenticated user could supply a vertex_credentials dict with type=external_account pointing credential_source.file at an arbitrary path (e.g. /proc/1/environ) and token_url at an attacker-controlled server. google-auth's identity_pool.Credentials refresh() would read the file and POST its contents to the attacker. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> * fix: block /key/update self-escalation by assigned users Non-admin users who were assigned a key (created_by != caller) could update any non-budget field — models, rpm_limit, guardrails, etc. — without admin authorization, allowing privilege self-escalation. Gate: only the key creator (created_by == caller) may edit their own key without admin check; budget changes always require admin regardless of creator status. All other callers must pass _check_key_admin_access. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> * fix: block user-controlled api_base in RAG ingest vector_store options A user-supplied api_base in ingest_options.vector_store caused the server to forward its configured provider credentials (Gemini, OpenAI) to an attacker-controlled endpoint via SSRF. Add api_base to the blocked credential params set alongside api_key and the existing credential fields. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> * fix: restrict /utils/transform_request to PROXY_ADMIN and apply body safety check Any authenticated internal_user could POST arbitrary provider config (aws_sts_endpoint, api_base, etc.) to /utils/transform_request and have the server forward its credentials to an attacker-controlled endpoint. - Gate the endpoint on PROXY_ADMIN role (403 for all other roles) - Call is_request_body_safe() to reject banned params even for admins - Convert ValueError from safety check to HTTP 400 Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> * fix: apply banned-param check to /utils/transform_request Without is_request_body_safe(), any authenticated user could pass aws_sts_endpoint, api_base, or aws_web_identity_token to /utils/transform_request and have the server forward its configured provider credentials to an attacker-controlled endpoint during SDK credential resolution. Applies the same banned-param blocklist already used by LLM endpoints. Endpoint remains accessible to all authenticated users. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> * fix: block SSRF via api_base in /prompts/test dotprompt YAML frontmatter Any frontmatter key not in ["model","input","output"] flowed into optional_params and was merged into the LLM call data dict, bypassing is_request_body_safe. An attacker with any bearer key could set api_base in YAML to redirect the outbound LLM request — including the provider API key — to an attacker-controlled host. Fix: call is_request_body_safe on the constructed data dict after optional_params are merged, before invoking ProxyBaseLLMRequestProcessing. ValueError from the banned-param check is surfaced as HTTP 400. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> * Update litellm/proxy/rag_endpoints/endpoints.py Co-authored-by: veria-ai[bot] <224490171+veria-ai[bot]@users.noreply.github.com> * fix: coerce nested config strings before banned-param check _NESTED_CONFIG_KEYS descent used isinstance(nested, dict) which silently skipped litellm_embedding_config when delivered as a JSON string via multipart/form-data. Banned params (api_base, aws_sts_endpoint, etc.) nested inside the stringified value were invisible to is_request_body_safe. _NESTED_METADATA_KEYS already used _coerce_metadata_to_dict which parses JSON strings before checking. Apply the same coercion to _NESTED_CONFIG_KEYS. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> * fix: replace substring match with prefix match in is_llm_api_route mapped_pass_through_routes used `_llm_passthrough_route in route` (substring) so any admin-only path whose URL contained a provider name (openai, anthropic, azure, bedrock, etc.) was misclassified as an LLM API route and bypassed the admin gate in non_proxy_admin_allowed_routes_check. Confirmed live: non-admin key could GET /credentials/by_name/openai (read masked provider API key) and DELETE /credentials/openai (delete credential). Fix: use exact match or startswith(prefix + "/") — the same pattern used everywhere else in RouteChecks — so only routes that actually start with a passthrough prefix are allowed through. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> * fix: stabilize PR #27878 test failures - key_management_endpoints: extend can_skip_admin_check to team keys so team members with /key/update permission can update non-budget fields. can_team_member_execute_key_management_endpoint already validates team membership + permission and raises if unauthorized; reaching the admin check on a team key means the caller was authorized. - test: set created_by on mock key in test_update_key_non_budget_fields_allowed_for_internal_user so caller_is_creator resolves correctly (MagicMock default ≠ user_id). - auth_utils.get_request_route: guard against non-dict request.scope (e.g. MagicMock in unit tests) to prevent a MagicMock leaking into UserAPIKeyAuth.request_route and failing Pydantic validation. - ci: assign test_multipart_bypass_repro.py to the proxy-runtime shard in test-unit-proxy-db.yml to satisfy the shard-coverage check. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> * fix(lint): add explicit str() cast in get_request_route for MyPy scope.get() returns Any|None which MyPy cannot coerce to str implicitly. Wrap both scope.get() calls in str() to satisfy the type checker. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> * fix: guard bare-/ root_path strip + make total_spend migration idempotent auth_utils.get_request_route: when Starlette sets scope["app_root_path"] to "/" (e.g. behind some middleware), the old stripping logic would remove the leading slash from every path ("/team/new" → "team/new"), breaking route matching and causing auth to misclassify protected routes. Skip stripping when root_path is bare "/". migration: add IF NOT EXISTS to total_spend ALTER TABLE so the migration is safe to replay when a prior partial run already created the column. Without this guard, prisma migrate deploy fails on CI DBs that were partially migrated, causing all subsequent DB operations (including /team/new) to 500. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> * fix: require creator still owns key for personal-key bypass in /key/update caller_is_creator now requires both created_by == caller AND user_id == caller. Previously checking only created_by let a demoted admin who originally created a key for another user continue editing non-budget fields on it after reassignment, bypassing _check_key_admin_access. Adds regression test: creator whose key was reassigned is blocked (403). Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> * fix: extract auth checks to fix PLR0915 + broaden max_budget assertion internal_user_endpoints._update_single_user_helper exceeded 50 statements (PLR0915). Extract authorization checks into _check_user_update_authz helper to bring statement count under the limit. test_validate_max_budget: assert "negative" (substring of both the local "cannot be negative" and the CI "non-negative finite number" messages) so the test is stable regardless of which exact wording the function uses. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: veria-ai[bot] <224490171+veria-ai[bot]@users.noreply.github.com> * bump: version 0.4.71 → 0.4.72 * uv lock * feat(mcp): support OAuth passthrough discovery * fix(mcp): support OAuth browser auth * fix(mcp): refine upstream OAuth metadata fallback * feat(proxy): support issuer-scoped JWT auth * fix(mcp): validate oauth callback redirect sink * feat(proxy): support issuer-scoped JWT auth * test(mcp): align trusted proxy fixtures * style(mcp): satisfy black formatting * chore(ui): bump next to 16.2.6 * fix(mcp): address oauth passthrough review findings * test(mcp): split oauth passthrough regressions * fix(interactions): align openapi response fields * security: prevent forwarding litellm api keys to upstream mcp servers - Strip Authorization header from extra_headers for pass-through servers - Pass-through servers (auth_type=None with extra_headers: [Authorization]) must not receive the user's LiteLLM API key - Only OAuth2 M2M and pass-through servers skip Authorization header - Other headers (x-request-id, x-trace-id) are still forwarded normally - Fixes credential leakage / authentication bypass in MCP pass-through mode * fix(interactions): remove steps field not in google openapi spec The steps field was added but is not present in the current Google Interactions OpenAPI specification. Revert to using only the fields that are actually defined in the spec. * fix(mcp): forward Authorization in pass-through when x-litellm-api-key is admission Commit 3753970cc9 widened the Authorization strip to cover all is_oauth_passthrough servers — protecting against the LiteLLM admission key leaking upstream when the caller used Authorization for admission, but also silently stripping legitimate upstream OAuth bearers when the caller used x-litellm-api-key for admission. That broke transparent OAuth pass-through (EAI-506 V5/V6): standards- compliant MCP clients (OpenCode, Claude Code, mcp-inspector) complete PKCE against the upstream IdP and send the resulting token as plain Authorization: Bearer per the MCP spec — with the wider strip in place, that token never reaches the upstream and tools/list returns empty. Narrow the strip: skip Authorization for pass-through servers only when the caller did NOT supply x-litellm-api-key. When x-litellm-api-key is present, admission is unambiguous and Authorization is free to carry the upstream OAuth bearer. The original security guarantee is preserved — a client that sends only Authorization (no x-litellm-api-key) still has it stripped, so the LiteLLM key cannot leak upstream via that path. Tests: - new: forwards Authorization when x-litellm-api-key is present - new: still strips Authorization when only Authorization is present - existing pass-through + M2M tests unchanged Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(interactions): align status enum with openapi spec * fix(mcp,jwt): address greptile review concerns - Cache _get_agent_object_permission via user_api_key_cache (sentinel for no-permission rows) so MCP requests from agent keys don't hit the DB on every tool-list / tool-call. - Re-raise HTTPException in handle_sse_mcp so 401 + WWW-Authenticate challenges (and other HTTP errors) propagate to SSE clients instead of being swallowed as 500. - Normalise booleans in _validate_token_response so admin rules written as JSON-style "true" / "false" match upstream responses that return Python True / False. - Treat configured JWT issuer claim mappings as advisory: when a mapped field is absent or empty, leave the normalised claim unset instead of raising, matching the global litellm_jwtauth path. Co-authored-by: Claude <noreply@anthropic.com> * test: replace dall-e-3 with gpt-image-1 in health check and router tests (#27813) OpenAI returns 'The model dall-e-3 does not exist' for the test account, breaking test_openai_img_gen_health_check and test_image_generation. Switch to gpt-image-1, matching the existing TestOpenAIGPTImage1 pattern. (cherry picked from commit aee58db88057b274eab70388dce72eac31ea014f) * fix(tests): drop dall-e-only test classes; route live image tests via gpt-image-1 Second wave of failures from the 2026-05-12 DALL-E shutdown: - tests/image_gen_tests/test_image_edits.py::TestOpenAIImageEditDallE2 and tests/image_gen_tests/test_image_generation.py::TestOpenAIDalle3 are explicitly named for the deprecated models and can't pass; remove. gpt-image-1 coverage already exists in sibling classes. - tests/local_testing/test_router.py image gen tests use dall-e-3 only as a routing example; swap to gpt-image-1. - tests/local_testing/test_custom_callback_input.py image_generation success/failure paths swapped to gpt-image-1. (cherry picked from commit 945b10ded467e53fc3c9b8df0329dbc55591a56e) * test(fireworks): replace deprecated llama-v3p3-70b-instruct model Fireworks removed llama-v3p3-70b-instruct from serverless, so every live test using it now fails with NotFoundError ("Model not found, inaccessible, and/or not deployed"). Swap the 6 references (3 files) to the currently-served accounts/fireworks/models/deepseek-v3p1 — the canonical model in Fireworks' current docs examples and present in LiteLLM's cost map. test_get_model_params_fireworks_ai is a pure pricing-heuristic test (no network) asserting the >16b branch, so it uses llama-v3p1-70b- instruct instead to keep the "fireworks-ai-above-16b" assertion and branch coverage intact. (cherry picked from commit 39a1d438f23f88d1c88f3e74930ab221b3e450de) * test(fireworks): mock remaining live smoke tests test_completion_fireworks_ai and test_completion_cost_fireworks_ai made real Fireworks calls and broke whenever Fireworks rotated its serverless catalog (no externally-verifiable model list exists). They also asserted nothing — just printed. Mock the HTTP post and assert real behavior instead: the request is built with the right model/messages and the OpenAI-compatible response parses back; the cost path yields a non-zero cost against the local cost map. No network, no model dependency, stronger than the old smoke checks. (cherry picked from commit b5db7ed37da21818c4defe030e3762447fe62e15) * fix(tests): replace shut-down gpt-4o-audio-preview with gpt-audio-1.5 (#28281) * fix(tests): replace shut-down gpt-4o-audio-preview with gpt-audio-1.5 OpenAI shut down gpt-4o-audio-preview on 2026-05-07, so the live audio calls in test_stream_chunk_builder_openai_audio_output_usage and test_standard_logging_payload_audio now hard-fail with a model-not-found error on every PR. The error was not "openai-internal", so the except block swallowed it and execution fell through to an unbound completion/response (UnboundLocalError). Switch both tests to gpt-audio-1.5, OpenAI's recommended successor (GA, not deprecated, already present in the litellm cost map so the response_cost assertion still resolves). Also broaden the except to skip with the real error in the reason instead of crashing, so a transient upstream blip can't reintroduce the UnboundLocalError. * fix(tests): narrow audio-test skip to model-not-found, re-raise the rest Address review feedback: an unconditional skip on any exception would silently mask a litellm-internal regression in the audio path (broken param transformation, serialization, bad header) instead of failing CI. Skip only on the upstream-unavailable class (model_not_found / "does not exist" / openai-internal) and re-raise everything else, so genuine regressions still fail loudly. The UnboundLocalError is still fixed because the handler either skips or raises - it never falls through. * fix(tests): add budget_exceeded to expected Interaction status enum Staging added budget_exceeded to the Interaction OpenAPI status enum; the staging merge into this branch picked up the spec change but not the matching test update, so test_status_enum_values failed in CI. Align the test's expected list (exact-match by design) with the live spec. * fix(tests): mock HTTP fetch in test_img_url_token_counter The test parameterized a live third-party image URL (blog.purpureus.net) which now 404s, causing get_image_dimensions to fall through to its base64 decode path and crash with 'not enough values to unpack' on every PR run. Mock safe_get with a tiny 1x1 PNG so the URL branch is still exercised without any network dependency. * fix(tests): swap gpt-4o-audio-preview to gpt-audio-1.5 in test_gpt4o_audio OpenAI shut down gpt-4o-audio-preview on 2026-05-07, so both live tests in test_gpt4o_audio.py (test_audio_output_from_model and test_audio_input_to_model) hard-fail model_not_found on every PR. Swap the hardcoded model to OpenAI's successor gpt-audio-1.5 (same chat-completions audio surface; already in the litellm cost map). Mirror the narrowed-skip pattern from the prior audio fixes: skip on model_not_found / does-not-exist / openai-internal, re-raise everything else so genuine litellm regressions still fail CI loudly. (cherry picked from commit 92de7423efca5756a2cb1bcf3228812628f91960) * fix(tests): migrate realtime + rerank tests off shut-down upstream models (#28191) * fix(tests): use gpt-realtime in realtime guardrails test OpenAI shut down gpt-4o-realtime-preview-2024-12-17 on 2026-05-07, so the live OpenAI realtime guardrails integration test now fails with model_not_found (session.created never arrives, _wait_for_event times out). Point OPENAI_REALTIME_URL at the current GA model, gpt-realtime. Scope limited to this test: the pricing-catalog JSON keeps the retired entries intentionally (historical cost calc + separate Azure timeline), and the Azure realtime cost-calc test is unaffected. * fix(tests): mock nvidia_nim rerank instead of hitting EOL'd endpoint NVIDIA reached end-of-life for the hosted nvidia/llama-3.2-nv-rerankqa-1b-v2 rerank API on 2026-05-18 with no published replacement, so the live BaseLLMRerankTest.test_basic_rerank for nvidia_nim now returns HTTP 410 ("Gone"). NVIDIA's hosted catalog rotates on a schedule, so swapping in another live model would only defer the failure. Override test_basic_rerank in TestNvidiaNim to mock the sync/async HTTP transport (same pattern as test_nvidia_nim_rerank_ranking_endpoint in this file) and inject a fake NVIDIA_NIM_API_KEY via monkeypatch. The request/response transformation and cost calculation stay covered offline. Scope limited to nvidia_nim; other BaseLLMRerankTest providers untouched. * fix(tests): migrate remaining realtime tests off shut-down gpt-4o-realtime-preview OpenAI's 2026-05-07 shutdown removed the entire gpt-4o-realtime-preview family, including the undated 'gpt-4o-realtime-preview' alias (not just the dated snapshot fixed earlier). Three live tests still connected with the dead alias and failed with messages_received=1 (an error event instead of session.created): - test_openai_realtime_simple.py: get_model() -> gpt-realtime (drives TestOpenAIRealtime.test_realtime_connection / test_realtime_with_query_params) - test_openai_realtime.py: test_openai_realtime_direct_call_no_intent and test_openai_realtime_direct_call_with_intent -> openai/gpt-realtime (the with_intent test shares the same dead alias even though it was not in the failing set this run) Mocked unit tests (test_realtime_query_params_construction, test_realtime_query_params_use_normalized_model_name) are left as-is: they never hit the network and assert string plumbing only. Also fixes test_text_message_blocked_by_guardrail_no_ai_response, which now connects (the earlier URL swap worked) but tripped a model-wording-brittle assertion. The guardrail flow asks the model to voice the block message verbatim; gpt-4o-realtime-preview complied (output contained 'blocked'), gpt-realtime refuses verbatim-repeat instructions ('I'm sorry, but I can't repeat that message.'). Since the original user message is blocked before it reaches OpenAI, the refusal is still a safe outcome. Assertion #3 now accepts both voicing and refusal, and adds a hard check that the blocked phrase never leaks into AI output. (cherry picked from commit ce87c411bfb33a8b37acaa630a39e4e4c8685add) * fix(model_prices): register mistral/ministral-8b-2512 Mistral's API now returns model='ministral-8b-2512' when 'mistral-tiny' is requested, so test_completion_mistral_api fails with 'This model isn't mapped yet'. Adding the entry so completion_cost can resolve the cost for that response. Author: Claude <noreply@anthropic.com> * fix(mcp,auth): address greptile review concerns - handle_sse_mcp now calls _raise_preemptive_401_for_unauthenticated_servers so SSE clients to pass-through OAuth MCP servers receive the RFC 9728 401 + WWW-Authenticate challenge that the streamable-HTTP path already emits. - get_request_route strips a trailing slash from root_path before length-based prefix removal so non-canonical ASGI root_path values like "/litellm/" don't strip the leading slash from the returned route. - _mcp_oauth_user_api_key_auth's cookie JWT decode now passes options={"verify_aud": False} so a future revision of the UI session JWT containing an aud claim cannot silently downgrade the request to unauthenticated. Co-authored-by: Claude <claude@anthropic.com> * fix(tests): backfill local model_cost into remote-fetched map litellm.model_cost is loaded at import time from LITELLM_MODEL_COST_MAP_URL (pinned to main), so pricing entries that exist only in this branch (e.g. mistral/ministral-8b-2512, freshly added because Mistral's API now returns this id from mistral-tiny) are absent at test time and completion_cost lookups raise 'This model isn't mapped yet'. Backfill the in-tree backup into litellm.model_cost in the local_testing conftest so cassette-driven cost calculations resolve against the entries that ship with the branch under test. Fixes local_testing_part1 failures on test_completion_mistral_api and test_completion_mistral_api_modified_input. * fix(mcp,jwt): address greptile concurrency and code-quality concerns - _apply_issuer_claim_mappings now builds a new dict and reads from the original token, rather than mutating its input. The change is behaviour-preserving (caller passes a fresh jwt.decode result), but avoids the surprise-mutation pattern flagged by greptile. - is_network_error uses isinstance(exc, httpx.TransportError) instead of matching type(exc).__name__ against a hand-maintained string set, so ReadError / WriteError / ProxyError / etc. are also treated as transport-level failures and surfaced as HTTP 502. - fetch_upstream_oauth_protected_resource now coalesces concurrent discovery requests per (server_id, resource_url) through an asyncio.Lock so concurrent .well-known calls share a single upstream fetch + cache write. - Drop the redundant 'if trusted_ranges:' branch in get_mcp_client_ip; it is always true on the path that reaches it (the prior 'if not trusted_ranges:' early-returns). Co-authored-by: Claude <claude@anthropic.com> * fix(jwt,mcp): fall back to global JWKS on unknown issuer; prune fetch locks - handle_jwt._get_configured_issuer now returns None for tokens whose 'iss' is not in the configured issuers list, letting auth_jwt fall through to the legacy JWT_PUBLIC_KEY_URL path instead of hard-raising. This keeps existing tokens from non-configured IdPs working when an operator adds the new 'issuers' list to a live deployment. - discoverable_endpoints._prune_oauth_metadata_cache now also prunes entries in _OAUTH_METADATA_FETCH_LOCKS whose cache entry has been evicted and whose lock isn't currently held, bounding the locks dict to match the cache it guards. Co-authored-by: Claude <claude@anthropic.com> * fix(mcp,auth): restore client_ip in oauth2 target check, drop from delegate check The merge of staging into the PR branch (d42a66adb6) misplaced the client_ip=client_ip kwarg: it landed inside _target_servers_delegate_auth_to_upstream (which never accepted client_ip and isn't called with it), while the sibling _target_servers_use_oauth2 has client_ip in its signature but stopped passing it through to get_mcp_server_by_name. That left ruff flagging F821 on the undefined name and lint failing. Move client_ip back into _target_servers_use_oauth2's lookup (matching the call site that already forwards IPAddressUtils.get_mcp_client_ip) and drop it from _target_servers_delegate_auth_to_upstream so its body matches its signature again. * fix(mcp): respect client ip for delegated auth * fix(auth): address remaining greptile style findings - get_request_route: require root_path to match whole path segments before stripping, so '/apifoo' isn't truncated to 'foo' when root_path='/api'. - get_mcp_client_ip: collapse the two trusted-proxy validation branches into a single is_request_from_trusted_proxy call so the return value drives control flow instead of being discarded for the side-effect warning. Co-authored-by: Claude <claude@anthropic.com> * fix(jwt): strip internal _litellm_* claims in global JWKS auth path Prevents identity spoofing where a token signed by the global JWKS could inject _litellm_jwt_issuer and other _litellm_* claims that downstream getters trust. The issuer-scoped path already strips these via _apply_issuer_claim_mappings; mirror that behavior for the global fallback path. Co-authored-by: Yassin Kortam <yassin@berri.ai> * fix(mcp): surface MCPUpstreamAuthError as 401 in SSE/HTTP transport handlers Both handle_sse_mcp and handle_streamable_http_mcp only caught HTTPException to preserve 401 + WWW-Authenticate challenges, but MCPUpstreamAuthError (raised when a pass-through server's upstream rejects a bearer token mid-session) inherits from Exception. It was falling through to the generic handler and surfacing as an opaque 500. Mirror the REST endpoint behavior: translate MCPUpstreamAuthError into an HTTPException(status_code=e.status_code) with the upstream www-authenticate header so standards-compliant MCP clients trigger the upstream OAuth flow. Co-authored-by: Yassin Kortam <yassin@berri.ai> * fix(mcp): add upstream auth pre-flight in SSE handler Mirror handle_streamable_http_mcp by calling _check_passthrough_upstream_auth after the cold-start 401 emitter so expired/invalid upstream tokens surface a proper 401 + WWW-Authenticate challenge before the SSE session commits 200 headers, instead of letting list_tools silently return [] when the upstream rejects the token. Co-authored-by: Claude <noreply@anthropic.com> * fix(mcp): tighten cold-start bypass against CSV paths + dedupe upstream auth probe - Return None from _parse_mcp_server_names_from_path for CSV multi-server paths (/mcp/a,b). The regex previously truncated at the first comma and silently passed a single server name to the cold-start gate. - Switch _is_mcp_passthrough_cold_start to all-targets semantics, matching _target_servers_use_oauth2: one non-passthrough target in a co-targeted set must not flip the anonymous-admission bypass open for the others. - Drop the redundant HTTPStatusError block in _extract_upstream_auth_failure - any HTTPStatusError carries a .response, so the preceding generic block already handles 401/403 detection. Co-authored-by: Yassin Kortam <yassin@berri.ai> * fix(mcp,tests): sync stubs and cold-start assertions with delegate-check The merge of base-branch _target_servers_delegate_auth_to_upstream into process_mcp_request inserts an additional get_mcp_server_by_name(name) lookup ahead of the cold-start path, which breaks two test patterns: 1. lookup_by_name(name) side-effect stubs in TestMCPDelegateAuthToUpstream are called positionally by the delegate check, then again by the cold-start path with client_ip=... — raising TypeError: unexpected keyword argument 'client_ip'. Accept **_kwargs to match the real signature. 2. TestMCPPassthroughColdStartAdmission assertions count the lookup exactly once with client_ip=..., but the delegate check now adds a positional-only call ahead of it. Switch assert_called_once_with to assert_any_call for the cold-start invocation, and assert client_ip was *not* passed for the aggregate /mcp test where cold-start must not fire. Both updates align with CLAUDE.md guidance to keep monkeypatch stubs in sync with the real signature when an optional parameter is added. Co-authored-by: Claude <claude@anthropic.com> * fix(mcp): correct passthrough probe 401 + slashed-name cold start parser - _check_passthrough_upstream_auth now emits 'Bearer resource_metadata="..."' pointing at the gateway's oauth-protected-resource well-known URL, mirroring the pre-emptive 401 path. Pass-through servers don't use the gateway as an authorization server, so the previous 'authorization_uri=' challenge sent clients to the wrong metadata endpoint. - _parse_mcp_server_names_from_path now accepts server names that contain a single slash (e.g. custom_solutions/user_123), mirroring MCPRequestHandler._extract_target_server_names_from_path. Without this, the cold-start bypass missed slashed-name servers and the generic admission error propagated instead of the spec-compliant 401 challenge. - _is_mcp_passthrough_cold_start drops the unused scope parameter from its signature. Co-authored-by: Yassin Kortam <yassin@berri.ai> * style(mcp): format discoverable endpoints * refactor(mcp): dedupe MCPUpstreamAuthError->HTTPException + thread client_ip into delegate-auth gate Co-authored-by: Yassin Kortam <yassin@berri.ai> * fix(mcp): handle passthrough OAuth metadata and startup auth errors - discoverable_endpoints: For pass-through MCP servers, when upstream oauth-protected-resource returns a non-200/non-dict response, raise HTTP 502 instead of falling through to default gateway metadata. Falling through would direct MCP clients at the gateway, which is not the authorization server for pass-through configs. - mcp_server_manager: Wrap _get_tools_from_server in startup tool name mapping with try/except. Since _get_tools_from_server now re-raises MCPUpstreamAuthError, an upstream 401 from a pass-through server at startup (when no user token is present) would otherwise abort the loop and leave subsequent servers unmapped. Co-authored-by: Yassin Kortam <yassin@berri.ai> * fix(mcp): restrict passthrough probe challenge to OAuth passthrough servers The probe filter previously matched any server with Authorization in extra_headers, including gateway-managed OAuth2 servers. Those would then receive the resource_metadata= WWW-Authenticate challenge meant for pass-through servers, instead of the authorization_uri= challenge pointing at the gateway AS metadata. Use srv.is_oauth_passthrough so only genuine pass-through servers get the resource-metadata challenge. Co-authored-by: Yassin Kortam <yassin@berri.ai> * test(proxy): cover issuer-scoped JWT auth * fix(mcp): use resource metadata for passthrough reauth * fix(mcp,tests): assert cold-start helper directly for aggregate /mcp Threading client_ip into _target_servers_delegate_auth_to_upstream made get_mcp_server_by_name(name, client_ip=...) also fire from the delegate-auth check, so the call_args_list assertion on client_ip-in-kwargs no longer uniquely signals a cold-start lookup. Patch _is_mcp_passthrough_cold_start and assert it is not invoked, which is the actual contract the test is pinning. * fix(mcp,jwt): drop unneeded async helper + suppress misleading unscoped JWT warning - _build_oauth_authorization_server_response: revert to sync (no awaits in body). The function only does dict construction and synchronous registry lookups; async added coroutine creation overhead per discovery call without need. - _build_decode_kwargs: accept has_issuer_config so the global path's 'JWT auth is unscoped' warning is suppressed when LiteLLM_JWTAuth.issuers provides per-issuer scoping. Previously the warning fired spuriously for admins who intentionally use only the new issuers config. * fix(jwt,mcp): clarify issuers fallthrough + add TTL on mcp permission cache - LiteLLM_JWTAuth.issuers docs now state explicitly that unlisted issuers fall back to the global JWT_AUDIENCE/JWT_ISSUER path; the field is additive routing, not an allow-list. Matches actual control flow in handle_jwt.auth_jwt and the regression tests asserting backwards compatibility with the global JWKS path. - MCPRequestHandler._get_{org,agent}_object_permission now pass ttl=DEFAULT_MANAGEMENT_OBJECT_IN_MEMORY_CACHE_TTL on async_set_cache, mirroring the auth_checks.py pattern so the cache TTL is explicit on both DualCache layers. * fix(tests): align merged JWT and MCP cold-start assertions Update the tests carried over from PR #28008 to match the assertions on the staging branch: - tests/test_litellm/proxy/auth/test_handle_jwt.py: unknown issuers now fall back to the legacy JWT_PUBLIC_KEY_URL path (per litellm_feat/v1.84.0-mcp-gateway-jwt-auth's '\''fall back to global JWKS on unknown issuer'\''), and mapped issuer claims that are absent no longer fail closed — they simply leave the normalised LiteLLM internal claim absent. - tests/test_litellm/proxy/_experimental/mcp_server/auth/test_user_api_key_auth_mcp.py: the aggregate '\''/mcp'\'' route still triggers the delegate-auth-to-upstream lookup once for the header-supplied server name; cold-start admission must NOT fire on top of that. Tighten the assertion to assert_called_once_with so a future regression that re-enters cold-start is caught. Co-authored-by: Mateo Wang <mateo-berri@users.noreply.github.com> * fix(jwt): guard litellm_jwtauth access in auth_jwt global path JWTHandler() can be constructed without update_environment() being called (tests do this directly), in which case self.litellm_jwtauth does not exist. Accessing it raises AttributeError before getattr can fall back. Use the same safe pattern other call sites use. * Gate MCP OAuth pass-through on delegate_auth_to_upstream flag Sameer's review on #28356/#28008 flagged that the new pass-through behaviors (preemptive 401 challenges, /.well-known/oauth-protected- resource proxying, upstream 401/403 propagation as MCPUpstreamAuthError, and Authorization-stripping when no x-litellm-api-key is supplied) were implicitly enabled for every server with auth_type=none plus Authorization in extra_headers. Existing users doing static bearer pass-through for non-OAuth reasons would have silently regressed. Make the detection rule explicit: extend the existing delegate_auth_to_upstream flag (previously oauth2-only) to also gate is_oauth_passthrough. Now requires flag + auth_type=None + Authorization in extra_headers, per Sameer's suggested detection rule. The UI toggle now appears for both modes (oauth2 PKCE passthrough and auth_type=none OAuth pass-through) with mode-appropriate copy. Update test fixtures to set the flag where the test intent is to exercise OAuth pass-through behavior, and add negative tests covering the new default-false case. * fix(mcp): route org object_permission lookup through shared auth helpers Replace the bespoke litellm_organizationtable.find_unique + dedicated cache key in _get_org_object_permission with get_org_object + get_object_permission so MCP requests share the same user_api_key_cache entries as the rest of the proxy and no longer fragment org-row caching. * fix(mcp): wrap get_object_permission call in shared try/except Ensure exceptions from get_object_permission in _get_org_object_permission are caught and return None, preserving the original fail-safe semantics. Co-authored-by: Yassin Kortam <yassin@berri.ai> * fix(jwt): validate issuer audience at config load + dedicated key-miss exception - Move JWTIssuerConfig audience-required guard into a Pydantic model_validator so misconfiguration fails at startup instead of on the first request. - Replace the string-match `No matching public key found` filter in get_public_key's multi-URL fallback with a dedicated NoMatchingJWTPublicKeyError; only that specific exception triggers continuation, every other error still surfaces. * fix(mcp): admit and forward Authorization for passthrough OAuth return For pass-through MCP servers (auth_type=none with delegate_auth_to_upstream) the RFC 9728 cold-start flow sends the client back with only "Authorization: Bearer <upstream-token>" after upstream OAuth discovery. Previously this path 1) was rejected in process_mcp_request because the oauth2_headers fallback only covered auth_type=oauth2 targets, and 2) had the Authorization header stripped by _prepare_mcp_server_headers when no x-litellm-api-key was present, treating the upstream token as a potential LiteLLM key leak. - Extend the elif oauth2_headers fallback to also admit anonymously when every target is a pass-through server. - Pass user_api_key_auth into _prepare_mcp_server_headers so it can forward Authorization for pass-through servers when admission did not consume the bearer as a LiteLLM key (api_key is unset). Co-authored-by: Yassin Kortam <yassin@berri.ai> * fix(mcp): consistent www-authenticate casing + SSE toolset scoping - Normalize the WWW-Authenticate header key emitted by _check_passthrough_upstream_auth to lowercase to match the other 401 emitters in the OAuth pass-through flow. - Mirror the streamable HTTP handler's toolset scoping in handle_sse_mcp: strip client-supplied x-mcp-toolset-id and apply _apply_toolset_scope before _check_passthrough_upstream_auth so the upstream probe list is derived from the fully-authorized server set. - Tighten _has_client_supplied_mcp_auth signature so mcp_server_auth_headers is Optional, matching its caller in process_mcp_request. Co-authored-by: Yassin Kortam <yassin@berri.ai> * security(mcp): strip Authorization in call_tool when LiteLLM admission used legacy header Mirror the OAuth pass-through admission check from _prepare_mcp_server_headers (list-tools path) in _call_regular_mcp_tool (tool-call path): when the server is OAuth pass-through and the caller did not supply x-litellm-api-key, Authorization on the inbound request may itself be the LiteLLM API key — so strip it before forwarding instead of leaking the gateway credential upstream. When x-litellm-api-key is present, admission is unambiguous and Authorization continues to carry the upstream OAuth bearer (transparent pass-through). * refactor(mcp): centralize caller Authorization strip decision Extracted the security-sensitive logic that decides whether the caller's Authorization header is forwarded to (or stripped from) an outgoing MCP request into a single helper, _should_strip_caller_authorization, in mcp_server_manager.py. Previously the same condition was duplicated across _call_regular_mcp_tool (mcp_server_manager.py) and _prepare_mcp_server_headers (server.py). Keeping two copies of this check risked future divergence and credential-leak / broken-passthrough bugs. Both call sites now share the helper, preserving exact behavior. Co-authored-by: Yassin Kortam <yassin@berri.ai> * log MCP OAuth discovery diagnostics for unmatched paths and non-transport upstream errors * fix(jwt): include issuer-normalized team id in get_all_jwt_team_ids The aggregator for team IDs only consulted the issuer-normalized claim for the plural (team_ids) path and fell back to the global config for the singular path. When an operator configures team_id_jwt_field only at the issuer level, get_team_id correctly returned the mapped value but get_all_jwt_team_ids silently dropped it, causing membership reconciliation to disagree with request routing. Co-authored-by: Yassin Kortam <yassin@berri.ai> * fix(mcp/jwt): dedupe cold-start path parser; reject conflicting audience flags - _parse_mcp_server_names_from_path now delegates to MCPRequestHandler._extract_target_server_names_from_path so the names used by the cold-start passthrough bypass cannot drift from the names used by downstream routing. - JWTIssuerConfig now rejects the combination of audience and disable_audience_validation=True at validation time instead of silently ignoring the flag. * fix(mcp): restrict passthrough cold-start bypass to 401 only The new elif passthrough cold-start branch reused is_auth_error which matches both 401 and 403. A 403 from user_api_key_auth indicates the LiteLLM key WAS recognized but is forbidden (e.g. over budget / rate limited); falling through to anonymous UserAPIKeyAuth() in that case bypasses spend and rate-limit controls on passthrough servers. Only trigger the cold-start anonymous admission on 401, which is the signal that the bearer is an upstream OAuth token rather than a recognized LiteLLM key. Co-authored-by: Yassin Kortam <yassin@berri.ai> * fix(jwt/mcp): warn on unscoped JWT fallback; route agent permission lookup through shared helper - _build_decode_kwargs no longer suppresses the unscoped-fallback warning when LiteLLM_JWTAuth.issuers is set: tokens whose iss does not match any configured issuer still fall through to the global path, and that fallback is itself unscoped when JWT_AUDIENCE/JWT_ISSUER are absent. - _get_agent_object_permission now caches the agent_id -> object_permission_id mapping and delegates the permission lookup to the shared get_object_permission helper, so the agent path reuses the same cache entries as the org / team / key paths. * fix(mcp): fabricate resource_metadata challenge when upstream 401 omits WWW-Authenticate When an upstream pass-through MCP server returns 401 without a WWW-Authenticate header (non-compliant per RFC 7235 §3.1), to_http_exception() now produces a synthetic Bearer challenge pointing at the gateway's standard-pattern oauth-protected-resource well-known endpoint for that server. This keeps MCP clients on the RFC 9728 discovery flow instead of receiving a bare 401 with no recovery hint. * fix(jwt): make _get_decode_options explicitly control verify_iss Previously, _get_decode_options only set verify_aud based on whether audience was provided. The issuer JWT path relied on always passing issuer=issuer_config.issuer to trigger PyJWT's default verify_iss=True, making the helper's behavior implicitly dependent on caller behavior. Now _get_decode_options accepts issuer as well, mirroring the verify_aud handling and matching the dimensions handled by _build_decode_kwargs. Co-authored-by: Yassin Kortam <yassin@berri.ai> * fix(mcp): emit absolute resource_metadata URI in fabricated 401 challenge Per RFC 9728 §3.2 the resource_metadata Bearer challenge must be an absolute URI; strict MCP clients reject relative URIs and fail to initiate discovery. MCPUpstreamAuthError.to_http_exception now accepts the gateway base URL and prepends it when the upstream omitted WWW-Authenticate, and all four call sites (streamable HTTP, SSE, and the two REST tool-list paths) supply it. * fix(mcp): correct 403 detail text and remove dead _list_tools_for_single_server duplicate - MCPUpstreamAuthError.to_http_exception() now returns detail='Forbidden' for 403 upstream responses (and 'Unauthorized' for 401), matching the _check_passthrough_upstream_auth pre-flight probe. - Remove the shadowed first definition of _list_tools_for_single_server in rest_endpoints.py; the second definition was the live one and the dead copy was a maintenance trap. Co-authored-by: Yassin Kortam <yassin@berri.ai> * fix: address potential bugs in auth_utils, mcp discoverable endpoints, and mcp auth - auth_utils.get_request_route: return '/' instead of empty string when raw_path exactly equals root_path so downstream route allowlist checks still see a leading slash - discoverable_endpoints.fetch_upstream_oauth_protected_resource: also cache negative results (no upstream metadata) for a shorter TTL so we don't re-fetch on every discovery request and so the per-key fetch lock can be pruned - user_api_key_auth_mcp: guard the oauth2_headers 401 cold-start passthrough bypass with _has_client_supplied_mcp_auth, matching the parallel bypass in the no-Authorization branch so MCP-auth-bearing requests don't silently downgrade to anonymous admission Co-authored-by: Yassin Kortam <yassin@berri.ai> * test(vertex): tolerate transient InternalServerError in google maps tool test test_gemini_google_maps_tool_simple makes live calls to Vertex AI's Google Maps grounding backend, which intermittently returns 500 INTERNAL ("Please retry") — a transient upstream failure, not a LiteLLM bug. The test already passes on RateLimitError; treat InternalServerError the same way so transient Vertex-side failures don't fail CI. * refactor(mcp): drop redundant has_client_credentials filter on passthrough probe is_oauth_passthrough already requires auth_type in (None, MCPAuth.none), which is mutually exclusive with has_client_credentials (auth_type == MCPAuth.oauth2), so the extra guard was always True and only added confusion about whether a server could be both passthrough and M2M. Co-authored-by: Yassin Kortam <yassin@berri.ai> * fix: restore unreachable InternalServerError skip handler in vertex test Co-authored-by: Yassin Kortam <yassin@berri.ai> * feat(mcp): add dedicated oauth_passthrough flag for non-oauth2 pass-through Previously is_oauth_passthrough reused delegate_auth_to_upstream — a flag scoped to oauth2 servers (PKCE bypass) — to gate OAuth pass-through for auth_type=none servers. Overloading it risked regressing existing deployments that set delegate_auth_to_upstream, since the same flag would silently start driving pass-through (discovery proxying, 401 challenges, upstream 401/403 propagation) on non-oauth2 servers. Introduce a separate oauth_passthrough opt-in so the two behaviors never imply each other: - MCPServer.is_oauth_passthrough now requires oauth_passthrough (not delegate_auth_to_upstream). - Persist oauth_passthrough on LiteLLM_MCPServerTable (new column + migration) and wire it through config/DB load and API responses. - UI splits the single toggle into two: "Delegate auth to upstream (PKCE passthrough)" for oauth2 and "OAuth pass-through" for auth_type=none servers forwarding Authorization. Adds backend tests (property, round-trip, and a regression guard that delegate_auth_to_upstream alone never enables pass-through) and UI tests for the toggle split. * fix(mcp): reconcile cold-start bypass with x-mcp-servers header and skip non-absolute WWW-Authenticate fabrication - _parse_mcp_server_names_from_path now fails closed when the x-mcp-servers header introduces any target not present in the path-derived target set, closing a header/path mismatch where the cold-start passthrough bypass could otherwise admit anonymously while the header advertises a non-passthrough server. - MCPUpstreamAuthError.to_http_exception no longer emits a relative resource_metadata URI when base_url is missing; per RFC 9728 3.2 the URI must be absolute, so we skip fabrication entirely rather than send a challenge strict MCP clients will reject. Co-authored-by: Yassin Kortam <yassin@berri.ai> * fix(mcp): fabricate path-aware resource_metadata URI for upstream 401 When MCPUpstreamAuthError.to_http_exception fabricates a `WWW-Authenticate: Bearer resource_metadata=...` challenge (because the upstream 401 omitted one), the URL now matches the inbound MCP transport pattern the client originally used: - /mcp/{server_name} -> /.well-known/oauth-protected-resource/mcp/{server_name} - /{server_name}/mcp -> /.well-known/oauth-protected-resource/{server_name}/mcp This mirrors the path-aware behaviour of _get_passthrough_resource_metadata_url in server.py so strict RFC 9728 \xA73.2 clients on legacy routes get a resource_metadata URI aligned with the resource pattern they originally targeted. Co-authored-by: Yassin Kortam <yassin@berri.ai> * fix(jwt+mcp): tighten issuer-scoped claim type handling, RFC-quote authorization_uri, surface MCP upstream auth errors, defense-in-depth on decode options - handle_jwt: when an issuer-scoped _litellm_team_ids claim exists but has an unexpected type, return [] instead of falling through to the global team_ids_jwt_field path (different claim semantically). - handle_jwt: _get_decode_options/_decode_jwt_with_public_key now take an explicit disable_audience_validation flag; passing audience=None without it raises, so audience checks can't silently disappear if the model validator is ever bypassed. _auth_jwt_with_issuer forwards the flag from JWTIssuerConfig. - mcp_server: quote the authorization_uri WWW-Authenticate parameter value (RFC 6750 / 9728 auth-param must be quoted-string), matching the pass-through path. - mcp_server: in _fetch_and_filter_server_tools, re-raise MCPUpstreamAuthError so the outer streamable-HTTP handler can surface a proper 401 + WWW-Authenticate challenge instead of returning an empty tool list. Co-authored-by: Yassin Kortam <yassin@berri.ai> * chore(docker): align Dockerfile.non_root/Dockerfile.database to current wolfi-base SHA The older sha256:3258be... pin has been intermittently returning 500/not-found from cgr.dev, breaking the test-server-root-path GitHub Action and the build_docker_database_image CircleCI job. Move both Dockerfiles onto the same sha256:31da65... digest already in use by Dockerfile, gateway/Dockerfile, backend/Dockerfile, and migrations/Dockerfile so the base image is consistent across the repo. * ci(docker): bump wolfi-b…
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a top-level
e2e/test harness for verifying the litellm proxyagainst real provider APIs. Designed to be driven by Claude Code:
scripts are single-purpose Unix tools, scenarios live as markdown
runbooks. No pytest framework lock-in.
Why this is needed separately from
tests/tests/test_litellm/uses mocks and never makes real provider calls,so it cannot catch integration bugs where:
/metricsHTTP outputprompt_tokens_detailsdifferently from what unit-test fixtures assumeReal-provider tests cost money per run and depend on external API availability — they MUST NEVER auto-run in
make test-unitor CI. Hence top-levele2e/, not undertests/.What ships
Case set (12 runbooks)
/metricsendpoint smokecost_breakdownincludes cache fields when staticmodel_costis completespend_logs.error_information.error_messagenon-empty on auth failures — companion regression case for PR #2 (Bug #3)custom_pricingpath must not drop cache pricing for dashboard-added deployments — guards the future fix torouter.py:7237Case 12 is intentionally RED — it documents a known production bug
(
cache_breakdownunder-bills by ~93% on/model/new-registereddeployments) and provides the regression assertion for the upcoming fix.
Cost discipline
Per-case cost is < $0.01 with default prompt sizes. The runbooks are
intentionally short (one or two calls each). Postgres is ephemeral —
every
proxy stopwipes data so virtual keys / spend logs from onecase never pollute later cases.
Branching strategy doc
CLAUDE.mdis updated to document the fork's actual branching layout:ship/v1.83.10— long-term ship branch (TAG + merged fix/* PRs); PR target for all internal fixesinternal/v1.83.10-stable— upstream-sync working branch (1700+ upstream commits); NOT a fix baselitellm_internal_staging— pure upstream trackerfix/<name>— per-bug feature branches, branch fromship/v1.83.10This codifies the path we ended up with after the
internal/*branchturned out to have an upstream-sync function distinct from "ship".
Test plan
.pytools)litellm/ortests/— pure additive harness.gitignoreonly covers rendered config and tool pycache; never accidentally ignores real test code