diff --git a/litellm/litellm_core_utils/ecb_reference_rates.py b/litellm/litellm_core_utils/ecb_reference_rates.py index 4c75b1a8010..04e8701274d 100644 --- a/litellm/litellm_core_utils/ecb_reference_rates.py +++ b/litellm/litellm_core_utils/ecb_reference_rates.py @@ -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)}) diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py index 90e2ad2009c..73989398186 100644 --- a/litellm/proxy/_types.py +++ b/litellm/proxy/_types.py @@ -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 diff --git a/litellm/proxy/proxy_server.py b/litellm/proxy/proxy_server.py index df0a92212fc..bfd5f4458bf 100644 --- a/litellm/proxy/proxy_server.py +++ b/litellm/proxy/proxy_server.py @@ -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) diff --git a/litellm/proxy/ui_crud_endpoints/reference_rates_endpoints.py b/litellm/proxy/ui_crud_endpoints/reference_rates_endpoints.py new file mode 100644 index 00000000000..dbb2f790ba8 --- /dev/null +++ b/litellm/proxy/ui_crud_endpoints/reference_rates_endpoints.py @@ -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()}}, + ) diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/hooks/referenceRates/useReferenceRates.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/hooks/referenceRates/useReferenceRates.ts new file mode 100644 index 00000000000..196f5bb41ad --- /dev/null +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/hooks/referenceRates/useReferenceRates.ts @@ -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 => { + 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 = { + queryKey: referenceRatesKeys.all, + queryFn: ({ signal }) => fetchReferenceRates(signal), + enabled, + staleTime: REFERENCE_RATES_STALE_MS, + refetchInterval: REFERENCE_RATES_STALE_MS, + retry: false, + }; + return useQuery(options); +}; diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/SpendDisplayCurrency.integration.test.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/SpendDisplayCurrency.integration.test.tsx new file mode 100644 index 00000000000..6f9ba804e90 --- /dev/null +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/SpendDisplayCurrency.integration.test.tsx @@ -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) => {node}; + 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(); + + 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(); + + await chooseSelectOption(user, trigger(), /^EUR/); + expect(await screen.findByText("≈ EUR 34.00 estimated at the ECB reference rate of 2026-11-13")).toBeVisible(); + + rerender(); + 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(); + + 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(); + 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(); + 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(, client); + await user.click(trigger()); + expect(await screen.findByText(UNAVAILABLE)).toBeVisible(); + first.unmount(); + + renderFresh(, 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(() => {}); + }), + ); + const { unmount } = renderFresh(); + + await user.click(trigger()); + await waitFor(() => expect(requests).toHaveLength(1)); + unmount(); + + expect(requests[0].signal.aborted).toBe(true); + }); +}); diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/SpendDisplayCurrency.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/SpendDisplayCurrency.tsx new file mode 100644 index 00000000000..d673646d7ef --- /dev/null +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/SpendDisplayCurrency.tsx @@ -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 ( +
+
+ {t("usage.statStrip.spendDisplay.label")} + +
+ {estimate !== null && !loading && ( +

+ {t("usage.statStrip.spendDisplay.estimate", { + amount: new Intl.NumberFormat(i18n.language, { + style: "currency", + currency, + currencyDisplay: "code", + }).format(estimate.amount), + date: estimate.rateDate, + })} +

+ )} + {unavailable &&

{t("usage.statStrip.spendDisplay.unavailable")}

} +
+ ); +} diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/UsageOverview.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/UsageOverview.tsx index ec8bbeb80aa..26fc5f980d3 100644 --- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/UsageOverview.tsx +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/UsageOverview.tsx @@ -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={} /> {subscriptionCosts} diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/spendDisplay.test.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/spendDisplay.test.ts new file mode 100644 index 00000000000..1bd42692470 --- /dev/null +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/spendDisplay.test.ts @@ -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); + }); +}); diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/spendDisplay.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/spendDisplay.ts new file mode 100644 index 00000000000..52313f8c81a --- /dev/null +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/spendDisplay.ts @@ -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, + 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 }; +}; diff --git a/litellm/ui/litellm-dashboard/src/i18n/locales/en.json b/litellm/ui/litellm-dashboard/src/i18n/locales/en.json index 2942e00fea8..6ddfb5c9530 100644 --- a/litellm/ui/litellm-dashboard/src/i18n/locales/en.json +++ b/litellm/ui/litellm-dashboard/src/i18n/locales/en.json @@ -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", diff --git a/litellm/ui/litellm-dashboard/src/lib/http/schema.d.ts b/litellm/ui/litellm-dashboard/src/lib/http/schema.d.ts index 5acfacd2dfc..402a9c838bc 100644 --- a/litellm/ui/litellm-dashboard/src/lib/http/schema.d.ts +++ b/litellm/ui/litellm-dashboard/src/lib/http/schema.d.ts @@ -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; diff --git a/tests/unit/litellm_core_utils/test_ecb_reference_rates.py b/tests/unit/litellm_core_utils/test_ecb_reference_rates.py index 23cbb698d91..08e5341fafd 100644 --- a/tests/unit/litellm_core_utils/test_ecb_reference_rates.py +++ b/tests/unit/litellm_core_utils/test_ecb_reference_rates.py @@ -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() == {} diff --git a/tests/unit/proxy/auth/test_route_checks.py b/tests/unit/proxy/auth/test_route_checks.py index 56b7501dd1c..9202702c4f7 100644 --- a/tests/unit/proxy/auth/test_route_checks.py +++ b/tests/unit/proxy/auth/test_route_checks.py @@ -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( diff --git a/tests/unit/proxy/ui_crud_endpoints/test_reference_rates_endpoints.py b/tests/unit/proxy/ui_crud_endpoints/test_reference_rates_endpoints.py new file mode 100644 index 00000000000..3c55666fc73 --- /dev/null +++ b/tests/unit/proxy/ui_crud_endpoints/test_reference_rates_endpoints.py @@ -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 = ( + "" + "" + "" +).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