feat(ui): show an optional currency estimate on the Usage spend card (#51979)

* feat(ui): show the usage spend total in another currency at ECB reference rates

Adds GET /get/reference_exchange_rates, which returns the current ECB
reference rates as USD per unit for every feed currency. It refreshes at
most once a day under a lock, keeps fresh rates when a refresh fails and
answers 503 instead of serving rates older than seven days.

The usage overview's spend card gets a Spend display selector. It asks for
rates only once opened and then shows an estimated amount with the rate date
under the unchanged USD total. Every other figure stays in USD.

* fix(ui): fall back to USD when spend display rates stop being usable

The selector now shows USD whenever no estimate can be shown, so a failed
refetch never leaves EUR selected beside a USD-only notice, and an opened
selector refreshes its rates hourly. The endpoint gets its HTTP client
inside the async fetch so the client belongs to the serving event loop.

* fix(proxy): import the ECB rates endpoint HTTP client helper at module level

Binds get_async_httpx_client at import so its type is known. The client is
still built inside the awaited fetch on the serving event loop.

* fix(proxy): fetch display rates with a short-lived handler closed after each refresh

Builds an AsyncHTTPHandler inside the refresh fetch and closes it when the
fetch ends, and drops the descriptive comment on the spend display component.

* chore(ui): regenerate API types for the reference exchange rates endpoint

* fix(proxy): use the cached async client factory for display rate refreshes

Direct AsyncHTTPHandler construction fails the async client check, so the
refresh fetch goes back to get_async_httpx_client, called inside the awaited
fetch, with a named type suppression for the factory's untyped params.

* fix(ui): tidy spend display helper, hook options and fallback test

Groups the rate snapshot into one estimatedSpend argument, names the rates
query options, names the missing-estimate condition, and waits for the
unavailable notice before asserting the USD fallback.

* chore(ui): drop a restating comment on the spend estimate helper

* test(proxy): prove concurrent first rate requests share one ECB fetch

* fix(proxy): wait a minute before retrying a failed display rate refresh

A failed ECB refresh left rates due, so every request after it waited on
the lock and fetched again, and N queued callers paid N timeouts during an
outage. The endpoint now skips refreshing for 60 seconds after a failed
attempt, serving held rates or a 503, and retries on the first request
after that. Concurrent waiters share the failed attempt. Also drops the
usd_rates docstring.

* fix(ui): retry unavailable currency estimates on reopen

* refactor(ui): name the currency selector open handler

* style(ui): format currency selector props

---------

Co-authored-by: Joshua Valluru <326636767+joshua-berri@users.noreply.github.com>
This commit is contained in:
joshua-berri 2026-11-16 16:00:20 -08:00 • committed by GitHub
parent 653c28426c
commit f94c79290c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
15 changed files with 775 additions and 1 deletions

View file

@ -237,3 +237,9 @@ class EcbReferenceRates:
rate_date=snapshot.rate_date,
source="ecb",
)
def usd_rates(self) -> Mapping[str, UsdRate]:
state: Final = self._state
currencies: Final = () if state is None else tuple(c for c in state.snapshot.units_per_eur if c != "USD")
lookups: Final = tuple(self.usd_per_unit(currency) for currency in currencies)
return MappingProxyType({rate.currency: rate for rate in lookups if isinstance(rate, UsdRate)})

View file

@ -631,6 +631,7 @@ class LiteLLMRoutes(enum.Enum):
"/sso/get/ui_settings",
"/get/user_banner",
"/get/latest_release_info",
"/get/reference_exchange_rates",
]
# NOTE: ROUTES ONLY FOR MASTER KEY - only the Master Key should be able to Reset Spend

View file

@ -1058,6 +1058,9 @@ from litellm.proxy.ui_crud_endpoints.proxy_setting_endpoints import (
from litellm.proxy.ui_crud_endpoints.proxy_setting_endpoints import (
sync_ui_settings_to_general_settings,
)
from litellm.proxy.ui_crud_endpoints.reference_rates_endpoints import (
router as reference_rates_endpoints_router,
)
from litellm.proxy.ui_crud_endpoints.user_banner_endpoints import (
router as user_banner_endpoints_router,
)
@ -23160,6 +23163,7 @@ app.include_router(ui_crud_endpoints_router)
app.include_router(moyai_router)
app.include_router(user_banner_endpoints_router)
app.include_router(latest_release_endpoints_router)
app.include_router(reference_rates_endpoints_router)
app.include_router(team_callback_router)
app.include_router(budget_management_router)
app.include_router(model_management_router)

View file

@ -0,0 +1,105 @@
import asyncio
import time
from collections.abc import Awaitable, Callable, Mapping
from datetime import date, datetime, timezone
from typing import Annotated, Final, Literal, TypeAlias
from fastapi import APIRouter, Depends, HTTPException, status
from pydantic import ConfigDict
from litellm.litellm_core_utils.ecb_reference_rates import (
EcbFeedRejected,
EcbFetchFailed,
EcbReferenceRates,
EcbRefreshResult,
fetch_ecb_daily_feed,
)
from litellm.llms.custom_httpx.http_handler import (
get_async_httpx_client, # pyright: ignore[reportUnknownVariableType] # shared HTTP factory has an untyped params argument
)
from litellm.proxy.auth.user_api_key_auth import user_api_key_auth
from litellm.types.llms.base import LiteLLMBaseModel
from litellm.types.llms.custom_http import httpxSpecialProvider
router: Final = APIRouter()
EcbFeedFetch: TypeAlias = Callable[[], Awaitable[bytes | EcbFetchFailed]]
_FAILED_REFRESH_COOLDOWN_SECONDS: Final = 60.0
class _FailedRefreshCooldown:
def __init__(self, monotonic: Callable[[], float] = time.monotonic) -> None:
self._monotonic: Final = monotonic
self._failed_at: float | None = None
def active(self) -> bool:
failed_at: Final = self._failed_at
return failed_at is not None and self._monotonic() - failed_at < _FAILED_REFRESH_COOLDOWN_SECONDS
def record(self, result: EcbRefreshResult) -> None:
self._failed_at = self._monotonic() if isinstance(result, EcbFetchFailed | EcbFeedRejected) else None
class ReferenceExchangeRates(LiteLLMBaseModel):
model_config = ConfigDict(frozen=True)
source: Literal["ecb"]
rate_date: date
usd_per_unit: Mapping[str, float]
_reference_rates: Final = EcbReferenceRates(clock=lambda: datetime.now(timezone.utc))
_refresh_lock: Final = asyncio.Lock()
_refresh_cooldown: Final = _FailedRefreshCooldown()
def _default_rates() -> EcbReferenceRates:
return _reference_rates
def _default_refresh_lock() -> asyncio.Lock:
return _refresh_lock
def _default_refresh_cooldown() -> _FailedRefreshCooldown:
return _refresh_cooldown
async def _fetch_on_serving_loop() -> bytes | EcbFetchFailed:
return await fetch_ecb_daily_feed(get_async_httpx_client(llm_provider=httpxSpecialProvider.UI))
def _default_fetch() -> EcbFeedFetch:
return _fetch_on_serving_loop
@router.get(
"/get/reference_exchange_rates",
tags=["Budget & Spend Tracking"],
dependencies=[Depends(user_api_key_auth)],
response_model=ReferenceExchangeRates,
responses={503: {"description": "No ECB reference rate published in the last 7 days is available"}},
)
async def reference_exchange_rates(
rates: Annotated[EcbReferenceRates, Depends(_default_rates)],
refresh_lock: Annotated[asyncio.Lock, Depends(_default_refresh_lock)],
fetch: Annotated[EcbFeedFetch, Depends(_default_fetch)],
cooldown: Annotated[_FailedRefreshCooldown, Depends(_default_refresh_cooldown)],
) -> ReferenceExchangeRates:
"""
ECB euro foreign exchange reference rates as USD per unit of each currency, with USD at 1. They estimate a USD
total in another currency for display and are not settlement quotes. Refreshes from the ECB feed when due.
"""
if rates.refresh_due() and not cooldown.active():
async with refresh_lock:
if rates.refresh_due() and not cooldown.active():
cooldown.record(await rates.arefresh(fetch))
usd_rates: Final = rates.usd_rates()
rate_date: Final = next((rate.rate_date for rate in usd_rates.values() if rate.rate_date is not None), None)
if rate_date is None:
raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="ECB reference rates unavailable")
return ReferenceExchangeRates(
source="ecb",
rate_date=rate_date,
usd_per_unit={"USD": 1.0, **{currency: rate.usd_per_unit for currency, rate in usd_rates.items()}},
)

View file

@ -0,0 +1,28 @@
import { useQuery, type UseQueryOptions } from "@tanstack/react-query";
import { backgroundFetchClient } from "@/lib/http/api";
import type { components } from "@/lib/http/schema";
import { createQueryKeys } from "../common/queryKeysFactory";
export type ReferenceExchangeRates = components["schemas"]["ReferenceExchangeRates"];
export const REFERENCE_RATES_STALE_MS = 60 * 60 * 1000;
export const referenceRatesKeys = createQueryKeys("referenceRates");
export const fetchReferenceRates = async (signal: AbortSignal): Promise<ReferenceExchangeRates> => {
const { data } = await backgroundFetchClient.GET("/get/reference_exchange_rates", { signal });
if (data === undefined) throw new Error("The proxy returned no reference exchange rates");
return data;
};
export const useReferenceRates = (enabled: boolean) => {
const options: UseQueryOptions<ReferenceExchangeRates> = {
queryKey: referenceRatesKeys.all,
queryFn: ({ signal }) => fetchReferenceRates(signal),
enabled,
staleTime: REFERENCE_RATES_STALE_MS,
refetchInterval: REFERENCE_RATES_STALE_MS,
retry: false,
};
return useQuery(options);
};

View file

@ -0,0 +1,160 @@
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { act, render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import type { ReactElement } from "react";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { chooseSelectOption } from "@/../tests/test-utils";
import { referenceRatesKeys } from "@/app/(dashboard)/hooks/referenceRates/useReferenceRates";
import { registerErrorHandler } from "@/lib/http/runtime";
import SpendDisplayCurrency from "./SpendDisplayCurrency";
const RATES = { source: "ecb", rate_date: "2026-11-13", usd_per_unit: { USD: 1, EUR: 1.25, JPY: 0.01 } };
const json = (body: unknown, status = 200) =>
new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
const newClient = () => new QueryClient({ defaultOptions: { queries: { retry: false } } });
const renderFresh = (ui: ReactElement, client = newClient()) => {
const wrap = (node: ReactElement) => <QueryClientProvider client={client}>{node}</QueryClientProvider>;
const rendered = render(wrap(ui));
return { ...rendered, client, rerender: (next: ReactElement) => rendered.rerender(wrap(next)) };
};
const trigger = () => screen.getByRole("combobox", { name: "Spend display" });
const UNAVAILABLE = "Reference rates are unavailable, spend is shown in USD";
beforeEach(() => {
vi.useFakeTimers({ toFake: ["Date"] });
vi.setSystemTime(new Date("2026-11-14T12:00:00Z"));
});
afterEach(() => {
vi.useRealTimers();
vi.unstubAllGlobals();
registerErrorHandler(() => {});
});
describe("SpendDisplayCurrency", () => {
it("stays on USD without asking for rates until the selector is opened", () => {
const fetch = vi.fn();
vi.stubGlobal("fetch", fetch);
renderFresh(<SpendDisplayCurrency usdSpend={42.5} loading={false} />);
expect(trigger()).toHaveTextContent("USD");
expect(screen.queryByText(/estimated/)).not.toBeInTheDocument();
expect(fetch).not.toHaveBeenCalled();
});
it("estimates the current range total in the chosen currency and follows later totals", async () => {
const user = userEvent.setup();
const fetch = vi.fn().mockResolvedValue(json(RATES));
vi.stubGlobal("fetch", fetch);
const { rerender } = renderFresh(<SpendDisplayCurrency usdSpend={42.5} loading={false} />);
await chooseSelectOption(user, trigger(), /^EUR/);
expect(await screen.findByText("≈ EUR 34.00 estimated at the ECB reference rate of 2026-11-13")).toBeVisible();
rerender(<SpendDisplayCurrency usdSpend={50} loading={false} />);
expect(screen.getByText("≈ EUR 40.00 estimated at the ECB reference rate of 2026-11-13")).toBeVisible();
await chooseSelectOption(user, trigger(), /^JPY/);
expect(screen.getByText("≈ JPY 5,000 estimated at the ECB reference rate of 2026-11-13")).toBeVisible();
await chooseSelectOption(user, trigger(), /^USD/);
expect(screen.queryByText(/estimated/)).not.toBeInTheDocument();
expect(fetch).toHaveBeenCalledTimes(1);
});
it("keeps USD with a notice and no dashboard error when rates are unavailable", async () => {
const user = userEvent.setup();
const onError = vi.fn();
registerErrorHandler(onError);
vi.stubGlobal("fetch", vi.fn().mockResolvedValue(json({ detail: "ECB reference rates unavailable" }, 503)));
renderFresh(<SpendDisplayCurrency usdSpend={42.5} loading={false} />);
await user.click(trigger());
expect(await screen.findByText("Reference rates are unavailable, spend is shown in USD")).toBeVisible();
expect(screen.getAllByRole("option").map((option) => option.textContent)).toEqual(["USD · US Dollar"]);
expect(onError).not.toHaveBeenCalled();
});
it("falls back to USD when a refetch fails after another currency was chosen", async () => {
const user = userEvent.setup();
const fetch = vi
.fn()
.mockResolvedValueOnce(json(RATES))
.mockResolvedValue(json({ detail: "unavailable" }, 503));
vi.stubGlobal("fetch", fetch);
const { client } = renderFresh(<SpendDisplayCurrency usdSpend={42.5} loading={false} />);
await chooseSelectOption(user, trigger(), /^EUR/);
expect(await screen.findByText(/≈ EUR 34\.00 estimated/)).toBeVisible();
await act(() => client.invalidateQueries({ queryKey: referenceRatesKeys.all }));
expect(await screen.findByText("Reference rates are unavailable, spend is shown in USD")).toBeVisible();
expect(screen.queryByText(/estimated/)).not.toBeInTheDocument();
expect(trigger()).toHaveTextContent("USD");
expect(fetch).toHaveBeenCalledTimes(2);
});
it("asks for rates again when the selector is reopened after they failed", async () => {
const user = userEvent.setup();
const fetch = vi
.fn()
.mockResolvedValueOnce(json({ detail: "unavailable" }, 503))
.mockResolvedValue(json(RATES));
vi.stubGlobal("fetch", fetch);
renderFresh(<SpendDisplayCurrency usdSpend={42.5} loading={false} />);
await user.click(trigger());
expect(await screen.findByText(UNAVAILABLE)).toBeVisible();
await user.keyboard("{Escape}");
await chooseSelectOption(user, trigger(), /^EUR/);
expect(await screen.findByText(/≈ EUR 34\.00 estimated/)).toBeVisible();
expect(screen.queryByText(UNAVAILABLE)).not.toBeInTheDocument();
expect(fetch).toHaveBeenCalledTimes(2);
});
it("keeps a failure cached by another card hidden until this card is opened", async () => {
const user = userEvent.setup();
const fetch = vi.fn().mockResolvedValue(json({ detail: "unavailable" }, 503));
vi.stubGlobal("fetch", fetch);
const client = newClient();
const first = renderFresh(<SpendDisplayCurrency usdSpend={42.5} loading={false} />, client);
await user.click(trigger());
expect(await screen.findByText(UNAVAILABLE)).toBeVisible();
first.unmount();
renderFresh(<SpendDisplayCurrency usdSpend={42.5} loading={false} />, client);
expect(screen.queryByText(UNAVAILABLE)).not.toBeInTheDocument();
expect(fetch).toHaveBeenCalledTimes(1);
await user.click(trigger());
expect(await screen.findByText(UNAVAILABLE)).toBeVisible();
await waitFor(() => expect(fetch).toHaveBeenCalledTimes(2));
});
it("cancels the rate request when the overview goes away before it answers", async () => {
const user = userEvent.setup();
const requests: Request[] = [];
vi.stubGlobal(
"fetch",
vi.fn((request: Request) => {
requests.push(request);
return new Promise<Response>(() => {});
}),
);
const { unmount } = renderFresh(<SpendDisplayCurrency usdSpend={42.5} loading={false} />);
await user.click(trigger());
await waitFor(() => expect(requests).toHaveLength(1));
unmount();
expect(requests[0].signal.aborted).toBe(true);
});
});

View file

@ -0,0 +1,69 @@
"use client";
import { useMemo, useState } from "react";
import { useTranslation } from "react-i18next";
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
import { useReferenceRates } from "@/app/(dashboard)/hooks/referenceRates/useReferenceRates";
import { estimatedSpend } from "./spendDisplay";
interface SpendDisplayCurrencyProps {
usdSpend: number;
loading: boolean;
}
export default function SpendDisplayCurrency({ usdSpend, loading }: SpendDisplayCurrencyProps) {
const { t, i18n } = useTranslation();
const [requested, setRequested] = useState(false);
const [currency, setCurrency] = useState("USD");
const rates = useReferenceRates(requested);
const usable = rates.isError ? undefined : rates.data;
const names = useMemo(
() => new Intl.DisplayNames([i18n.language], { type: "currency", fallback: "code" }),
[i18n.language],
);
const codes = Object.keys(usable?.usd_per_unit ?? { USD: 1 }).sort();
const estimate =
usable === undefined || currency === "USD" ? null : estimatedSpend(usdSpend, usable, currency, new Date());
const shown = estimate === null ? "USD" : currency;
const estimateMissing = currency !== "USD" && estimate === null;
const ratesUnusable = rates.isError || (estimateMissing && !rates.isFetching);
const unavailable = requested && ratesUnusable;
const retryable = requested && rates.isError && !rates.isFetching;
const handleOpenChange = (open: boolean) => {
if (!open) return;
if (retryable) void rates.refetch();
setRequested(true);
};
return (
<div className="mt-1 grid gap-1 text-xs leading-4 text-muted-foreground">
<div className="flex items-center gap-2">
<span>{t("usage.statStrip.spendDisplay.label")}</span>
<Select value={shown} onValueChange={(value) => setCurrency(value ?? "USD")} onOpenChange={handleOpenChange}>
<SelectTrigger size="sm" aria-label={t("usage.statStrip.spendDisplay.label")}>
<SelectValue />
</SelectTrigger>
<SelectContent>
{codes.map((code) => (
<SelectItem key={code} value={code}>
{t("usage.statStrip.spendDisplay.option", { code, name: names.of(code) ?? code })}
</SelectItem>
))}
</SelectContent>
</Select>
</div>
{estimate !== null && !loading && (
<p className="tabular-nums">
{t("usage.statStrip.spendDisplay.estimate", {
amount: new Intl.NumberFormat(i18n.language, {
style: "currency",
currency,
currencyDisplay: "code",
}).format(estimate.amount),
date: estimate.rateDate,
})}
</p>
)}
{unavailable && <p>{t("usage.statStrip.spendDisplay.unavailable")}</p>}
</div>
);
}

View file

@ -8,6 +8,7 @@ import type { OverviewTotals } from "./overviewData";
import { Panel } from "./Primitives";
import UsageStatStrip from "./UsageStatStrip";
import UsageBreakdownChart from "./UsageBreakdownChart";
import SpendDisplayCurrency from "./SpendDisplayCurrency";
interface UsageOverviewProps {
results: readonly DailyData[];
@ -45,6 +46,7 @@ export default function UsageOverview({
loading={loading}
requestCountsPending={requestCountsPending}
budget={budget}
spendDetails={<SpendDisplayCurrency usdSpend={totals.spend} loading={loading} />}
/>
{subscriptionCosts}

View file

@ -0,0 +1,29 @@
import { describe, expect, it } from "vitest";
import { estimatedSpend } from "./spendDisplay";
const USD_PER_UNIT = { USD: 1, EUR: 1.25, JPY: 0.01 };
const NOW = new Date("2026-11-14T12:00:00Z");
const ratesOn = (rate_date: string) => ({ usd_per_unit: USD_PER_UNIT, rate_date });
describe("estimatedSpend", () => {
it.each([
[42.5, "EUR", 34],
[0, "EUR", 0],
[-2.5, "EUR", -2],
[42.5, "JPY", 4250],
])("converts %d USD to %s at the reference rate", (usd, currency, amount) => {
expect(estimatedSpend(usd, ratesOn("2026-11-13"), currency, NOW)).toEqual({ amount, rateDate: "2026-11-13" });
});
it("offers no estimate for a currency the rates do not list", () => {
expect(estimatedSpend(42.5, ratesOn("2026-11-13"), "XYZ", NOW)).toBeNull();
});
it.each([
["2026-11-07", true],
["2026-11-06", false],
["2026-11-15", false],
])("uses a rate dated %s only while it is at most seven days old: %s", (rateDate, usable) => {
expect(estimatedSpend(42.5, ratesOn(rateDate), "EUR", NOW) !== null).toBe(usable);
});
});

View file

@ -0,0 +1,20 @@
import type { ReferenceExchangeRates } from "@/app/(dashboard)/hooks/referenceRates/useReferenceRates";
export const MAX_RATE_AGE_DAYS = 7;
const DAY_MS = 24 * 60 * 60 * 1000;
export type SpendEstimate = { readonly amount: number; readonly rateDate: string };
export const estimatedSpend = (
usdSpend: number,
rates: Pick<ReferenceExchangeRates, "usd_per_unit" | "rate_date">,
currency: string,
now: Date,
): SpendEstimate | null => {
const rate = new Map(Object.entries(rates.usd_per_unit)).get(currency);
const today = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
const ageDays = (today - Date.parse(`${rates.rate_date}T00:00:00Z`)) / DAY_MS;
if (rate === undefined || !(rate > 0) || !(ageDays >= 0 && ageDays <= MAX_RATE_AGE_DAYS)) return null;
return { amount: usdSpend / rate, rateDate: rates.rate_date };
};

View file

@ -15518,7 +15518,13 @@
},
"avgCostPerRequest": "Avg cost / request",
"avgLatency": "Avg latency",
"successRateHint": "{{rate}}% success rate"
"successRateHint": "{{rate}}% success rate",
"spendDisplay": {
"label": "Spend display",
"option": "{{code}} · {{name}}",
"estimate": "≈ {{amount}} estimated at the ECB reference rate of {{date}}",
"unavailable": "Reference rates are unavailable, spend is shown in USD"
}
},
"overview": {
"topVirtualKeys": "Top Virtual Keys",

View file

@ -6209,6 +6209,27 @@ export interface paths {
patch?: never;
trace?: never;
};
"/get/reference_exchange_rates": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/**
* Reference Exchange Rates
* @description ECB euro foreign exchange reference rates as USD per unit of each currency, with USD at 1. They estimate a USD
* total in another currency for display and are not settlement quotes. Refreshes from the ECB feed when due.
*/
get: operations["reference_exchange_rates_get_reference_exchange_rates_get"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/get/sso_settings": {
parameters: {
query?: never;
@ -45316,6 +45337,23 @@ export interface components {
/** Summary */
summary?: ("auto" | "concise" | "detailed") | null;
};
/** ReferenceExchangeRates */
ReferenceExchangeRates: {
/**
* Rate Date
* Format: date
*/
rate_date: string;
/**
* Source
* @constant
*/
source: "ecb";
/** Usd Per Unit */
usd_per_unit: {
[key: string]: number;
};
};
/** RegenerateKeyRequest */
RegenerateKeyRequest: {
/** Access Group Ids */
@ -65221,6 +65259,33 @@ export interface operations {
};
};
};
reference_exchange_rates_get_reference_exchange_rates_get: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Successful Response */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ReferenceExchangeRates"];
};
};
/** @description No ECB reference rate published in the last 7 days is available */
503: {
headers: {
[name: string]: unknown;
};
content?: never;
};
};
};
get_sso_settings_get_sso_settings_get: {
parameters: {
query?: never;

View file

@ -424,3 +424,22 @@ async def test_held_rates_survive_a_later_refresh() -> None:
assert dict(first.snapshot.units_per_eur) == {"EUR": 1.0, "USD": 1.25, "GBP": 0.5, "JPY": 125.0}
with pytest.raises(TypeError):
first.snapshot.units_per_eur["GBP"] = 9.0
def test_all_usd_rates_are_empty_without_a_feed() -> None:
assert EcbReferenceRates(clock=_Clock(_at(DAY))).usd_rates() == {}
async def test_all_usd_rates_list_every_held_currency_except_usd_until_they_go_stale() -> None:
clock: Final = _Clock(_at(DAY))
rates: Final = await _rates_holding(_feed(), clock)
fresh: Final = rates.usd_rates()
clock.now = _at(DAY + timedelta(days=8))
assert fresh == {
"EUR": UsdRate(currency="EUR", usd_per_unit=1.25, rate_date=DAY, source="ecb"),
"GBP": HELD_GBP,
"JPY": UsdRate(currency="JPY", usd_per_unit=0.01, rate_date=DAY, source="ecb"),
}
assert rates.usd_rates() == {}

View file

@ -235,6 +235,24 @@ def test_latest_release_info_read_open_to_non_admin_roles(role): # test-quality
)
@pytest.mark.parametrize(
"role",
[
LitellmUserRoles.INTERNAL_USER.value,
LitellmUserRoles.INTERNAL_USER_VIEW_ONLY.value,
],
)
def test_reference_exchange_rates_read_open_to_non_admin_roles(role: str) -> None: # test-quality-ok: allowed path returns None, not raising is the observable
RouteChecks.non_proxy_admin_allowed_routes_check(
user_obj=LiteLLM_UserTable(user_id="test_user", user_email="test@example.com", user_role=role),
_user_role=role,
route="/get/reference_exchange_rates",
request=MagicMock(spec=Request),
valid_token=UserAPIKeyAuth(user_id="test_user", user_role=role),
request_data={},
)
def test_user_banner_update_rejected_for_non_admin():
"""Publishing the banner stays admin-only at the route layer."""
user_obj = LiteLLM_UserTable(

View file

@ -0,0 +1,242 @@
import asyncio
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
from datetime import datetime, timezone
from typing import Final, Literal
import httpx
from fastapi import FastAPI
from litellm.litellm_core_utils.ecb_reference_rates import EcbFetchFailed, EcbReferenceRates
from litellm.proxy._types import UserAPIKeyAuth
from litellm.proxy.auth.user_api_key_auth import user_api_key_auth
from litellm.proxy.ui_crud_endpoints.reference_rates_endpoints import (
EcbFeedFetch,
_default_fetch,
_default_rates,
_default_refresh_cooldown,
_default_refresh_lock,
_FailedRefreshCooldown,
router,
)
ROUTE: Final = "/get/reference_exchange_rates"
DEADLOCK_GUARD_SECONDS: Final = 30.0
FEED: Final = (
"<gesmes:Envelope xmlns:gesmes='http://www.gesmes.org/xml/2002-08-01'"
" xmlns='http://www.ecb.int/vocabulary/2002-08-01/eurofxref'><Cube><Cube time='2026-11-13'>"
"<Cube currency='USD' rate='1.25'/><Cube currency='GBP' rate='0.5'/><Cube currency='JPY' rate='125'/>"
"</Cube></Cube></gesmes:Envelope>"
).encode()
RATES_BODY: Final = {
"source": "ecb",
"rate_date": "2026-11-13",
"usd_per_unit": {"USD": 1.0, "EUR": 1.25, "GBP": 2.5, "JPY": 0.01},
}
class _Clock:
def __init__(self, now: datetime) -> None:
self.now = now
def __call__(self) -> datetime:
return self.now
class _Feed:
def __init__(self, *bodies: bytes | EcbFetchFailed) -> None:
self.bodies = bodies
self.fetches = 0
async def __call__(self) -> bytes | EcbFetchFailed:
self.fetches += 1
return self.bodies[self.fetches - 1]
class _GatedFeed:
def __init__(self, body: bytes | EcbFetchFailed = FEED) -> None:
self.body = body
self.fetches = 0
self.entered = asyncio.Event()
self.release = asyncio.Event()
async def __call__(self) -> bytes | EcbFetchFailed:
self.fetches += 1
self.entered.set()
await self.release.wait()
return self.body
class _WaitSignallingLock(asyncio.Lock):
def __init__(self) -> None:
super().__init__()
self.contended = asyncio.Event()
async def acquire(self) -> Literal[True]:
if self.locked():
self.contended.set()
return await super().acquire()
class _Seconds:
def __init__(self) -> None:
self.now = 0.0
def __call__(self) -> float:
return self.now
async def _caller() -> UserAPIKeyAuth:
return UserAPIKeyAuth(api_key="sk-test", user_id="viewer")
def _app(
rates: EcbReferenceRates,
feed: EcbFeedFetch,
refresh_lock: asyncio.Lock | None = None,
cooldown: _FailedRefreshCooldown | None = None,
) -> FastAPI:
app: Final = FastAPI()
app.include_router(router)
lock: Final = refresh_lock or asyncio.Lock()
refresh_cooldown: Final = cooldown or _FailedRefreshCooldown()
app.dependency_overrides[_default_refresh_cooldown] = lambda: refresh_cooldown
app.dependency_overrides[user_api_key_auth] = _caller
app.dependency_overrides[_default_rates] = lambda: rates
app.dependency_overrides[_default_refresh_lock] = lambda: lock
app.dependency_overrides[_default_fetch] = lambda: feed
return app
@asynccontextmanager
async def _client(app: FastAPI) -> AsyncIterator[httpx.AsyncClient]:
async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://proxy") as client:
yield client
def _clock() -> _Clock:
return _Clock(datetime(2026, 11, 13, 16, tzinfo=timezone.utc))
async def test_first_request_fetches_and_returns_usd_per_unit_for_every_feed_currency() -> None:
clock: Final = _clock()
feed: Final = _Feed(FEED)
async with _client(_app(EcbReferenceRates(clock=clock), feed)) as client:
first: Final = await client.get(ROUTE)
again: Final = await client.get(ROUTE)
assert first.status_code == 200, first.text
assert first.json() == RATES_BODY
assert again.json() == RATES_BODY
assert feed.fetches == 1
async def test_failed_refresh_answers_with_the_fresh_held_rates() -> None:
clock: Final = _clock()
feed: Final = _Feed(FEED, EcbFetchFailed("HTTP 503"))
async with _client(_app(EcbReferenceRates(clock=clock), feed)) as client:
assert (await client.get(ROUTE)).status_code == 200
clock.now = datetime(2026, 11, 14, 16, tzinfo=timezone.utc)
response: Final = await client.get(ROUTE)
assert response.json() == RATES_BODY
assert feed.fetches == 2
async def test_never_fetched_rates_answer_503() -> None:
clock: Final = _clock()
async with _client(_app(EcbReferenceRates(clock=clock), _Feed(EcbFetchFailed("HTTP 503")))) as client:
response: Final = await client.get(ROUTE)
assert response.status_code == 503, response.text
async def test_stale_rates_with_a_failed_refresh_answer_503_instead_of_stale_rates() -> None:
clock: Final = _clock()
async with _client(_app(EcbReferenceRates(clock=clock), _Feed(FEED, EcbFetchFailed("HTTP 503")))) as client:
assert (await client.get(ROUTE)).status_code == 200
clock.now = datetime(2026, 11, 21, 16, tzinfo=timezone.utc)
response: Final = await client.get(ROUTE)
assert response.status_code == 503, response.text
async def test_concurrent_first_requests_share_one_fetch() -> None:
feed: Final = _GatedFeed()
lock: Final = _WaitSignallingLock()
async with _client(_app(EcbReferenceRates(clock=_clock()), feed, lock)) as client:
first: Final = asyncio.create_task(client.get(ROUTE))
second: Final = asyncio.create_task(client.get(ROUTE))
try:
await asyncio.wait_for(feed.entered.wait(), DEADLOCK_GUARD_SECONDS)
await asyncio.wait_for(lock.contended.wait(), DEADLOCK_GUARD_SECONDS)
feed.release.set()
responses: Final = await asyncio.wait_for(asyncio.gather(first, second), DEADLOCK_GUARD_SECONDS)
finally:
feed.release.set()
first.cancel()
second.cancel()
await asyncio.gather(first, second, return_exceptions=True)
assert [response.json() for response in responses] == [RATES_BODY, RATES_BODY]
assert feed.fetches == 1
async def test_a_failed_cold_refresh_is_not_retried_until_its_cooldown_ends() -> None:
seconds: Final = _Seconds()
feed: Final = _Feed(EcbFetchFailed("HTTP 503"), FEED)
async with _client(
_app(EcbReferenceRates(clock=_clock()), feed, cooldown=_FailedRefreshCooldown(seconds))
) as client:
during_outage: Final = [(await client.get(ROUTE)).status_code for _ in range(3)]
seconds.now = 59.9
before_cooldown_ends: Final = (await client.get(ROUTE)).status_code
fetches_before: Final = feed.fetches
seconds.now = 60.0
recovered: Final = await client.get(ROUTE)
assert during_outage == [503, 503, 503]
assert before_cooldown_ends == 503
assert fetches_before == 1
assert recovered.json() == RATES_BODY
assert feed.fetches == 2
async def test_a_failed_refresh_keeps_serving_held_rates_without_refetching_until_its_cooldown_ends() -> None:
clock: Final = _clock()
seconds: Final = _Seconds()
feed: Final = _Feed(FEED, EcbFetchFailed("HTTP 503"), FEED)
async with _client(_app(EcbReferenceRates(clock=clock), feed, cooldown=_FailedRefreshCooldown(seconds))) as client:
assert (await client.get(ROUTE)).status_code == 200
clock.now = datetime(2026, 11, 14, 16, tzinfo=timezone.utc)
during_outage: Final = [(await client.get(ROUTE)).json() for _ in range(3)]
fetches_during_outage: Final = feed.fetches
seconds.now = 60.0
recovered: Final = await client.get(ROUTE)
assert during_outage == [RATES_BODY] * 3
assert fetches_during_outage == 2
assert recovered.json() == RATES_BODY
assert feed.fetches == 3
async def test_concurrent_cold_requests_share_one_failed_fetch() -> None:
feed: Final = _GatedFeed(EcbFetchFailed("HTTP 503"))
lock: Final = _WaitSignallingLock()
cooldown: Final = _FailedRefreshCooldown(_Seconds())
async with _client(_app(EcbReferenceRates(clock=_clock()), feed, lock, cooldown)) as client:
first: Final = asyncio.create_task(client.get(ROUTE))
second: Final = asyncio.create_task(client.get(ROUTE))
try:
await asyncio.wait_for(feed.entered.wait(), DEADLOCK_GUARD_SECONDS)
await asyncio.wait_for(lock.contended.wait(), DEADLOCK_GUARD_SECONDS)
feed.release.set()
responses: Final = await asyncio.wait_for(asyncio.gather(first, second), DEADLOCK_GUARD_SECONDS)
finally:
feed.release.set()
first.cancel()
second.cancel()
await asyncio.gather(first, second, return_exceptions=True)
assert [response.status_code for response in responses] == [503, 503]
assert feed.fetches == 1