diff --git a/litellm/litellm_core_utils/duration_parser.py b/litellm/litellm_core_utils/duration_parser.py index d52716951df..ebc121b6448 100644 --- a/litellm/litellm_core_utils/duration_parser.py +++ b/litellm/litellm_core_utils/duration_parser.py @@ -12,8 +12,6 @@ from datetime import datetime, time, timedelta, timezone, tzinfo from typing import Final from zoneinfo import ZoneInfo -from litellm._logging import verbose_logger - _BUDGET_DURATION_WORD_ALIASES: Final[dict[str, str]] = { "hourly": "1h", "daily": "24h", @@ -128,35 +126,31 @@ def get_next_standardized_reset_time( # Set up timezone and normalize current time current_time, _ = _setup_timezone(current_time, timezone_str) - # Parse duration value, unit = _parse_duration(_normalize_duration(duration)) if value is None: - verbose_logger.warning( - "Unrecognized budget_duration %r; falling back to a next-midnight reset. " - "Use the format (e.g. '1h', '7d', '30d', '1mo').", - duration, + raise ValueError( + f"Invalid budget_duration {duration!r}. Use the format (e.g. '1h', '7d', '30d', '1mo')." ) - return current_time.replace(hour=0, minute=0, second=0, microsecond=0) + timedelta(days=1) - # Midnight of the current day in the specified timezone base_midnight: Final = current_time.replace(hour=0, minute=0, second=0, microsecond=0) - # Handle different time units - if unit == "d": - return _handle_day_reset(current_time, base_midnight, value, reset_time_of_day) - elif unit == "w": - return _handle_day_reset(current_time, base_midnight, value * 7, reset_time_of_day) - elif unit == "h": - return _handle_hour_reset(current_time, base_midnight, value) - elif unit == "m": - return _handle_minute_reset(current_time, base_midnight, value) - elif unit == "s": - return _handle_second_reset(current_time, base_midnight, value) - elif unit == "mo": - return _handle_month_reset(current_time, base_midnight, value, reset_time_of_day) - else: - # Unrecognized unit, default to next midnight - return base_midnight + timedelta(days=1) + match unit: + case "d": + return _handle_day_reset(current_time, base_midnight, value, reset_time_of_day) + case "w": + return _handle_day_reset(current_time, base_midnight, value * 7, reset_time_of_day) + case "h": + return _handle_hour_reset(current_time, base_midnight, value) + case "m": + return _handle_minute_reset(current_time, base_midnight, value) + case "s": + return _handle_second_reset(current_time, base_midnight, value) + case "mo": + return _handle_month_reset(current_time, base_midnight, value, reset_time_of_day) + case _: + raise ValueError( + f"Invalid budget_duration {duration!r}. Use the format (e.g. '1h', '7d', '30d', '1mo')." + ) def _shift_months(moment: datetime, months: int) -> datetime: diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py index 2b01e02bb06..5d2d388d169 100644 --- a/litellm/proxy/_types.py +++ b/litellm/proxy/_types.py @@ -1201,6 +1201,12 @@ from litellm.types.proxy.management_endpoints.request_base import ( # noqa: E40 ) +def _blank_duration_as_unset(value: object) -> object: + if isinstance(value, str) and value.strip() == "": + return None + return value + + class GenerateKeyResponse(KeyRequestBase): key: str key_name: str | None = None @@ -1928,6 +1934,11 @@ class NewTeamRequest(TeamBase): return None return v + @field_validator("budget_duration", "team_member_budget_duration", mode="before") + @classmethod + def empty_budget_duration_is_unset(cls, v: object) -> object: + return _blank_duration_as_unset(v) + class GlobalEndUsersSpend(LiteLLMPydanticObjectBase): api_key: str | None = None @@ -2002,6 +2013,11 @@ class UpdateTeamRequest(LiteLLMPydanticObjectBase): ), ) + @field_validator("budget_duration", "team_member_budget_duration", mode="before") + @classmethod + def empty_budget_duration_is_unset(cls, v: object) -> object: + return _blank_duration_as_unset(v) + class PatchTeamRequest(UpdateTeamRequest): """ diff --git a/litellm/proxy/common_utils/reset_budget_job.py b/litellm/proxy/common_utils/reset_budget_job.py index 59fd00cec43..2c896792f6f 100644 --- a/litellm/proxy/common_utils/reset_budget_job.py +++ b/litellm/proxy/common_utils/reset_budget_job.py @@ -301,6 +301,7 @@ class _BudgetCascade: budgets: tuple[LiteLLM_BudgetTableFull, ...] = () budget_ids: tuple[str, ...] = () budget_resets: tuple[tuple[str, datetime], ...] = () + budget_quarantines: tuple[str, ...] = () counter_resets: tuple[tuple[str, float], ...] = () cache_keys: tuple[str, ...] = () rollover_caps: Mapping[str, float] = field(default_factory=lambda: MappingProxyType({})) @@ -357,14 +358,72 @@ def _as_utc(moment: datetime) -> datetime: def _count_advanced(reset_ats: Iterable[object], cutoff: datetime) -> int: """How many rows the write actually moved past the due cutoff. - A budget_duration of "0s" (or one the parser cannot read) resolves to the - current time, so the row is written and stays due. Counting it as progress - would re-read the same chunk until the per-run cap on every tick. + A budget_duration of "0s" resolves to the current time, so the row is written + and stays due. Counting it as progress would re-read the same chunk until + the per-run cap on every tick. """ utc_cutoff: Final = _as_utc(cutoff) return sum(1 for reset_at in reset_ats if isinstance(reset_at, datetime) and _as_utc(reset_at) > utc_cutoff) +def _try_compute_budget_reset_at(duration: object, settings: BudgetResetSettings) -> datetime | None: + if not isinstance(duration, str): + raise ValueError( + f"Invalid budget_duration {duration!r}. Use the format (e.g. '1h', '7d', '30d', '1mo')." + ) + try: + return compute_budget_reset_at(budget_duration=duration, settings=settings) + except ValueError: + return None + + +def _is_duration_quarantine( + item: LiteLLM_TeamTable | LiteLLM_UserTable | LiteLLM_VerificationToken, +) -> bool: + return item.budget_duration is None and item.budget_reset_at is None + + +def _count_rows_leaving_due_set( + items: Iterable[LiteLLM_TeamTable | LiteLLM_UserTable | LiteLLM_VerificationToken], + cutoff: datetime, +) -> int: + return sum( + 1 + for item in items + if _is_duration_quarantine(item) + or (isinstance(item.budget_reset_at, datetime) and _as_utc(item.budget_reset_at) > _as_utc(cutoff)) + ) + + +@dataclass(frozen=True, slots=True) +class _AdvanceWindow: + budget_id: str + reset_at: datetime + + +@dataclass(frozen=True, slots=True) +class _QuarantineWindow: + budget_id: str + + +def _plan_budget_window( + budget: LiteLLM_BudgetTableFull, settings: BudgetResetSettings +) -> _AdvanceWindow | _QuarantineWindow | None: + budget_id: Final = budget.budget_id + duration: Final = budget.budget_duration + if budget_id is None or duration is None: + return None + reset_at: Final = _try_compute_budget_reset_at(duration, settings) + if reset_at is None: + verbose_proxy_logger.warning( + "Reset budget job: clearing unparseable budget_duration %r on budget %s so it leaves the due set", + duration, + budget_id, + ) + return _QuarantineWindow(budget_id) + return _AdvanceWindow(budget_id, reset_at) + + def _phase_is_drained(outcome: _ChunkOutcome) -> bool: """A short chunk means the due rows ran out. A full chunk that advanced nothing would be re-read unchanged forever, so it ends the phase too and @@ -766,9 +825,15 @@ class ResetBudgetJob: own schedule via reset_budget_for_litellm_keys(), so sweeping them here would reset them twice. """ - budget_ids: Final = tuple(b.budget_id for b in budgets_to_reset if b.budget_id is not None) + window_plans: Final = tuple(_plan_budget_window(b, self.reset_settings) for b in budgets_to_reset) + budget_resets: Final = tuple((p.budget_id, p.reset_at) for p in window_plans if isinstance(p, _AdvanceWindow)) + budget_quarantines: Final = tuple(p.budget_id for p in window_plans if isinstance(p, _QuarantineWindow)) + quarantine_ids: Final = frozenset(budget_quarantines) + budget_ids: Final = tuple( + b.budget_id for b in budgets_to_reset if b.budget_id is not None and b.budget_id not in quarantine_ids + ) if not budget_ids: - return _EMPTY_CASCADE + return _BudgetCascade(budgets=tuple(budgets_to_reset), budget_quarantines=budget_quarantines) team_memberships: Final[tuple[_TeamMembershipRow, ...]] = await self._fetch_linked_rows( table=TeamMembershipRepository(self.prisma_client).table, @@ -804,7 +869,9 @@ class ResetBudgetJob: { b.budget_id: cap for b in budgets_to_reset - if b.budget_id is not None and (cap := _rollover_cap(b.max_budget)) is not None + if b.budget_id is not None + and b.budget_id not in quarantine_ids + and (cap := _rollover_cap(b.max_budget)) is not None } if _rollover_enabled() else {} @@ -812,14 +879,8 @@ class ResetBudgetJob: return _BudgetCascade( budgets=tuple(budgets_to_reset), budget_ids=budget_ids, - budget_resets=tuple( - ( - b.budget_id, - compute_budget_reset_at(budget_duration=b.budget_duration, settings=self.reset_settings), - ) - for b in budgets_to_reset - if b.budget_id is not None and b.budget_duration is not None - ), + budget_resets=budget_resets, + budget_quarantines=budget_quarantines, counter_resets=( *( (_team_membership_counter_key(row), _row_carried_spend(row, rollover_caps)) @@ -896,7 +957,7 @@ class ResetBudgetJob: batching both means a mid-cascade failure persists nothing and the rows stay due for the next run. """ - if not cascade.budget_ids: + if not cascade.budget_ids and not cascade.budget_quarantines: return await self._with_db_write_retry( @@ -909,7 +970,8 @@ class ResetBudgetJob: db_span("reset_budget_cascade", "LiteLLM_BudgetTable"), budget_cascade_unit_of_work(self._new_batch) as uow, ): - uow.team_memberships.queue_total_spend_repair(cascade.budget_ids) + if cascade.budget_ids: + uow.team_memberships.queue_total_spend_repair(cascade.budget_ids) _queue_budget_linked_resets(uow.team_memberships, cascade) _queue_budget_linked_resets(uow.keys, cascade, extra=_LINKED_KEYS_WHERE) _queue_budget_linked_resets(uow.organizations, cascade, extra=_SPENT_ROWS_WHERE) @@ -918,6 +980,8 @@ class ResetBudgetJob: _queue_budget_linked_resets(uow.projects, cascade, extra=_SPENT_ROWS_WHERE) for budget_id, budget_reset_at in cascade.budget_resets: uow.budgets.queue_window_advance(budget_id=budget_id, budget_reset_at=budget_reset_at) + for budget_id in cascade.budget_quarantines: + uow.budgets.queue_window_quarantine(budget_id=budget_id) async def _invalidate_budget_cascade_caches(self, cascade: _BudgetCascade) -> None: await self._invalidate_caches( @@ -953,7 +1017,8 @@ class ResetBudgetJob: advanced=_count_advanced( (reset_at for _, reset_at in cascade.budget_resets), cutoff=datetime.now(timezone.utc), - ), + ) + + len(cascade.budget_quarantines), endusers=await self._invalidate_enduser_caches(cascade.budget_ids), ) @@ -1039,6 +1104,9 @@ class ResetBudgetJob: for k in updated_keys: if k.row.token is None: continue + if _is_duration_quarantine(k.row): + uow.keys.queue_duration_quarantine(token=k.row.token) + continue uow.keys.queue_spend_reset( token=k.row.token, budget_reset_at=k.row.budget_reset_at, @@ -1064,6 +1132,9 @@ class ResetBudgetJob: spend_reset_unit_of_work(self._new_batch) as uow, ): for u in updated_users: + if _is_duration_quarantine(u.row): + uow.users.queue_duration_quarantine(user_id=u.row.user_id) + continue uow.users.queue_spend_reset( user_id=u.row.user_id, budget_reset_at=u.row.budget_reset_at, @@ -1089,6 +1160,9 @@ class ResetBudgetJob: spend_reset_unit_of_work(self._new_batch) as uow, ): for t in updated_teams: + if _is_duration_quarantine(t.row): + uow.teams.queue_duration_quarantine(team_id=t.row.team_id) + continue uow.teams.queue_spend_reset( team_id=t.row.team_id, budget_reset_at=t.row.budget_reset_at, @@ -1173,6 +1247,8 @@ class ResetBudgetJob: if updated_keys: await self._write_key_reset_updates(updated_keys=updated_keys) for k in updated_keys: + if _is_duration_quarantine(k.row): + continue token = getattr(k.row, "token", None) if token: await self._invalidate_spend_counter(f"spend:key:{token}") @@ -1180,8 +1256,8 @@ class ResetBudgetJob: end_time = time.time() outcome: Final = _ChunkOutcome( fetched=len(keys_to_reset) if keys_to_reset else 0, - advanced=_count_advanced( - (k.row.budget_reset_at for k in updated_keys), + advanced=_count_rows_leaving_due_set( + (item.row for item in updated_keys), cutoff=datetime.now(timezone.utc), ), ) @@ -1284,6 +1360,8 @@ class ResetBudgetJob: if updated_users: await self._write_user_reset_updates(updated_users=updated_users) for u in updated_users: + if _is_duration_quarantine(u.row): + continue user_id = getattr(u.row, "user_id", None) if user_id: await self._invalidate_spend_counter(f"spend:user:{user_id}") @@ -1293,8 +1371,8 @@ class ResetBudgetJob: end_time = time.time() outcome: Final = _ChunkOutcome( fetched=len(users_to_reset) if users_to_reset else 0, - advanced=_count_advanced( - (u.row.budget_reset_at for u in updated_users), + advanced=_count_rows_leaving_due_set( + (item.row for item in updated_users), cutoff=datetime.now(timezone.utc), ), ) @@ -1399,6 +1477,8 @@ class ResetBudgetJob: if updated_teams: await self._write_team_reset_updates(updated_teams=updated_teams) for t in updated_teams: + if _is_duration_quarantine(t.row): + continue team_id = getattr(t.row, "team_id", None) if team_id: await self._invalidate_spend_counter(f"spend:team:{team_id}") @@ -1406,8 +1486,8 @@ class ResetBudgetJob: end_time = time.time() outcome: Final = _ChunkOutcome( fetched=len(teams_to_reset) if teams_to_reset else 0, - advanced=_count_advanced( - (t.row.budget_reset_at for t in updated_teams), + advanced=_count_rows_leaving_due_set( + (item.row for item in updated_teams), cutoff=datetime.now(timezone.utc), ), ) @@ -1478,6 +1558,15 @@ class ResetBudgetJob: reset_at: Final = datetime.fromisoformat(reset_at_str.replace("Z", "+00:00")).replace(tzinfo=None) if reset_at > now: return False + budget_duration: Final = window.get("budget_duration") + next_reset_at: Final = _try_compute_budget_reset_at(budget_duration, reset_settings) + if next_reset_at is None or not isinstance(budget_duration, str): + verbose_proxy_logger.warning( + "Reset budget job: clearing unparseable budget_duration %r on a window so it is not retried", + budget_duration, + ) + window["reset_at"] = None + return True new_value: Final = await ResetBudgetJob._window_carried_spend(window, counter_key, spend_counter_cache) spend_counter_cache.in_memory_cache.set_cache(key=counter_key, value=new_value) if spend_counter_cache.redis_cache is not None: @@ -1485,8 +1574,6 @@ class ResetBudgetJob: await spend_counter_cache.redis_cache.async_set_cache(key=counter_key, value=new_value) except Exception as redis_err: verbose_proxy_logger.warning("Failed to reset Redis counter %s: %s", counter_key, redis_err) - budget_duration: Final = window["budget_duration"] - next_reset_at: Final = compute_budget_reset_at(budget_duration=budget_duration, settings=reset_settings) window["reset_at"] = next_reset_at.isoformat() await ResetBudgetJob._roll_window_spend_row( prisma_client=prisma_client, @@ -1668,11 +1755,20 @@ class ResetBudgetJob: still holds the pre-reset value, admitting requests past the cap. """ try: + duration: Final = item.budget_duration + if duration is not None: + reset_at: Final = _try_compute_budget_reset_at(duration, reset_settings) + if reset_at is None: + verbose_proxy_logger.warning( + "Reset budget job: clearing unparseable budget_duration %r on %s so it leaves the due set", + duration, + item_type, + ) + item.budget_duration = None + item.budget_reset_at = None + return item + item.budget_reset_at = reset_at item.spend = _carried_spend(item.spend, _rollover_cap(item.max_budget)) if _rollover_enabled() else 0.0 - if hasattr(item, "budget_duration") and item.budget_duration is not None: - item.budget_reset_at = compute_budget_reset_at( - budget_duration=item.budget_duration, settings=reset_settings - ) return item except Exception as e: verbose_proxy_logger.exception("Error resetting budget for %s: %s. Item: %s", item_type, e, item) diff --git a/litellm/proxy/management_endpoints/team_endpoints.py b/litellm/proxy/management_endpoints/team_endpoints.py index 1fa18e9b2b8..e3315174057 100644 --- a/litellm/proxy/management_endpoints/team_endpoints.py +++ b/litellm/proxy/management_endpoints/team_endpoints.py @@ -1905,12 +1905,12 @@ async def new_team( value=getattr(data, field), ) - # If budget_duration is set, set `budget_reset_at` - if complete_team_data.budget_duration is not None: + usable_budget_duration: Final = _usable_budget_duration(complete_team_data.budget_duration) + if usable_budget_duration is not None: from litellm.proxy.common_utils.timezone_utils import get_budget_reset_time complete_team_data.budget_reset_at = get_budget_reset_time( - budget_duration=complete_team_data.budget_duration, + budget_duration=usable_budget_duration, ) # If budget_limits is set, initialize reset_at for each window @@ -1930,7 +1930,11 @@ async def new_team( members_with_roles = complete_team_data.members_with_roles complete_team_data.members_with_roles = [] - complete_team_data_dict: dict[str, object] = complete_team_data.model_dump(exclude_none=True) + dumped_team_data: Final = complete_team_data.model_dump(exclude_none=True) + complete_team_data_dict = _persistence_values_for_budget_duration( + dumped_team_data, + complete_team_data.budget_duration, + ) # Serialize router_settings to JSON (matching key creation pattern) router_settings_value: Final = data.router_settings @@ -2668,7 +2672,7 @@ async def update_team( ) # Check budget_duration and budget_reset_at - _set_budget_reset_at(data, updated_kv) + updated_kv = _set_budget_reset_at(data, updated_kv) _team_member_fields_in_request: Final = { field @@ -2689,12 +2693,13 @@ async def update_team( *LiteLLM_ManagementEndpoint_MetadataFields_Premium, ) ) + incoming_metadata: Final = updated_kv.get("metadata") if isinstance(existing_team_row.metadata, dict): if "metadata" not in updated_kv and (_team_member_fields_in_request or _writes_metadata_backed_field): updated_kv["metadata"] = copy.deepcopy(existing_team_row.metadata) - elif isinstance(updated_kv.get("metadata"), dict): + elif isinstance(incoming_metadata, dict): updated_kv["metadata"] = { - **updated_kv["metadata"], + **incoming_metadata, **{ key: existing_team_row.metadata[key] for key in TeamMemberBudgetHandler.SYSTEM_MANAGED_METADATA_KEYS @@ -2896,25 +2901,46 @@ async def patch_team( raise handle_exception_on_proxy(e) -def _set_budget_reset_at(data: UpdateTeamRequest, updated_kv: dict) -> None: - """Set budget_reset_at in updated_kv if budget_duration is provided.""" - if data.budget_duration is not None: +def _usable_budget_duration(duration: str | None) -> str | None: + if duration is None or duration.strip() == "": + return None + return duration + + +def _persistence_values_for_budget_duration( + persistence_values: Mapping[str, object], + duration: str | None, +) -> dict[str, object]: + if _usable_budget_duration(duration) is not None: + return {**persistence_values} + return {key: value for key, value in persistence_values.items() if key != "budget_duration"} + + +def _budget_reset_persistence_fields(data: UpdateTeamRequest, updated_kv: Mapping[str, object]) -> Mapping[str, object]: + usable_budget_duration: Final = _usable_budget_duration(data.budget_duration) + if usable_budget_duration is not None: from litellm.proxy.common_utils.timezone_utils import get_budget_reset_time - reset_at: Final = get_budget_reset_time(budget_duration=data.budget_duration) - updated_kv["budget_reset_at"] = reset_at - elif "budget_duration" in updated_kv and updated_kv["budget_duration"] is None: - updated_kv["budget_reset_at"] = None + return MappingProxyType({"budget_reset_at": get_budget_reset_time(budget_duration=usable_budget_duration)}) + if data.budget_duration is not None or ("budget_duration" in updated_kv and updated_kv["budget_duration"] is None): + return MappingProxyType({"budget_duration": None, "budget_reset_at": None}) + return MappingProxyType({}) - if data.budget_limits is not None and len(data.budget_limits) > 0: - from litellm.proxy.common_utils.timezone_utils import get_budget_reset_time - initialized_windows: Final = [] - for window in data.budget_limits: - w = window if isinstance(window, dict) else window.model_dump() - w["reset_at"] = get_budget_reset_time(budget_duration=w["budget_duration"]).isoformat() - initialized_windows.append(w) - updated_kv["budget_limits"] = json.dumps(initialized_windows) +def _set_budget_reset_at(data: UpdateTeamRequest, updated_kv: Mapping[str, object]) -> dict[str, object]: + """Return a persistence copy with budget_reset_at. Does not mutate `updated_kv`.""" + budget_fields: Final = _budget_reset_persistence_fields(data, updated_kv) + if data.budget_limits is None or len(data.budget_limits) == 0: + return {**updated_kv, **budget_fields} + + from litellm.proxy.common_utils.timezone_utils import get_budget_reset_time + + initialized_windows: Final = [] + for window in data.budget_limits: + w = window if isinstance(window, dict) else window.model_dump() + w["reset_at"] = get_budget_reset_time(budget_duration=w["budget_duration"]).isoformat() + initialized_windows.append(w) + return {**updated_kv, **budget_fields, "budget_limits": json.dumps(initialized_windows)} async def handle_update_object_permission(data_json: dict, existing_team_row: _ObjectPermissionRow) -> dict: diff --git a/litellm/repositories/unit_of_work.py b/litellm/repositories/unit_of_work.py index f6aad883479..cb21388fbf8 100644 --- a/litellm/repositories/unit_of_work.py +++ b/litellm/repositories/unit_of_work.py @@ -29,6 +29,13 @@ def _spend_reset_data(budget_reset_at: datetime | None, spend_decrement: float) return {"spend": spend, "budget_reset_at": budget_reset_at} +def _duration_quarantine_data() -> Mapping[str, object]: + return { + "budget_duration": None, + "budget_reset_at": None, + } # mutable-ok: prisma update payload must be a dict + + @dataclass(frozen=True, slots=True) class KeySpendResetWrites: table: BatchTable @@ -39,6 +46,12 @@ class KeySpendResetWrites: data=_spend_reset_data(budget_reset_at, spend_decrement), ) + def queue_duration_quarantine(self, token: str) -> None: + self.table.update( + where={"token": token}, # mutable-ok: prisma where filter must be a dict + data=_duration_quarantine_data(), + ) + @dataclass(frozen=True, slots=True) class UserSpendResetWrites: @@ -50,6 +63,12 @@ class UserSpendResetWrites: data=_spend_reset_data(budget_reset_at, spend_decrement), ) + def queue_duration_quarantine(self, user_id: str) -> None: + self.table.update( + where={"user_id": user_id}, # mutable-ok: prisma where filter must be a dict + data=_duration_quarantine_data(), + ) + @dataclass(frozen=True, slots=True) class TeamSpendResetWrites: @@ -61,6 +80,12 @@ class TeamSpendResetWrites: data=_spend_reset_data(budget_reset_at, spend_decrement), ) + def queue_duration_quarantine(self, team_id: str) -> None: + self.table.update( + where={"team_id": team_id}, # mutable-ok: prisma where filter must be a dict + data=_duration_quarantine_data(), + ) + @runtime_checkable class SpendResetWrites(Protocol): @@ -118,6 +143,9 @@ class BudgetWindowWrites: no-op row count instead of a P2025 that aborts the whole chunk.""" self.table.update_many(where={"budget_id": budget_id}, data={"budget_reset_at": budget_reset_at}) + def queue_window_quarantine(self, budget_id: str) -> None: + self.table.update_many(where={"budget_id": budget_id}, data=_duration_quarantine_data()) + @dataclass(frozen=True, slots=True) class SpendResetUnitOfWork: diff --git a/litellm/types/proxy/management_endpoints/request_base.py b/litellm/types/proxy/management_endpoints/request_base.py index 6b4a76e0132..e1178e03edd 100644 --- a/litellm/types/proxy/management_endpoints/request_base.py +++ b/litellm/types/proxy/management_endpoints/request_base.py @@ -21,6 +21,12 @@ class LiteLLM_ObjectPermissionBase(LiteLLMPydanticObjectBase): skills: list[str] | None = None +def _blank_duration_as_unset(value: object) -> object: + if isinstance(value, str) and value.strip() == "": + return None + return value + + class GenerateRequestBase(LiteLLMPydanticObjectBase): """ Overlapping schema between key and user generate/update requests @@ -65,3 +71,8 @@ class GenerateRequestBase(LiteLLMPydanticObjectBase): if v == "": return None return v + + @field_validator("budget_duration", mode="before") + @classmethod + def empty_budget_duration_is_unset(cls, value: object) -> object: + return _blank_duration_as_unset(value) diff --git a/tests/unit/litellm_core_utils/test_duration_parser.py b/tests/unit/litellm_core_utils/test_duration_parser.py index f14015effe6..5576b7db6b3 100644 --- a/tests/unit/litellm_core_utils/test_duration_parser.py +++ b/tests/unit/litellm_core_utils/test_duration_parser.py @@ -337,19 +337,18 @@ class TestWordFormBudgetDurations(unittest.TestCase): self.assertEqual(duration_in_seconds("weekly"), 604800) self.assertEqual(duration_in_seconds("monthly"), 2592000) - def test_invalid_duration_logs_warning_and_falls_back(self): + def test_unparseable_duration_raises_instead_of_midnight_fallback(self): base_time = datetime(2023, 5, 15, 15, 0, 0, tzinfo=timezone.utc) - with patch.object(duration_parser.verbose_logger, "warning") as mock_warning: - result = get_next_standardized_reset_time("garbage", base_time, "UTC") - self.assertEqual(result, datetime(2023, 5, 16, 0, 0, 0, tzinfo=timezone.utc)) - mock_warning.assert_called_once() - self.assertIn("garbage", mock_warning.call_args.args) + for duration in ("", " ", "garbage", "1x", "1dinvalid", "1hr", "fortnightly"): + with self.assertRaises(ValueError) as ctx: + get_next_standardized_reset_time(duration, base_time, "UTC") + self.assertIn("Invalid budget_duration", str(ctx.exception)) class TestGetBudgetWindowStart(unittest.TestCase): def test_window_start_is_the_previous_reset_on_the_same_schedule(self): created_at: Final = datetime(2024, 10, 1, 0, 30, tzinfo=timezone.utc) - durations: Final = "1d 24h daily 7d weekly 2w 10d 30d monthly 1mo 4h 5h 30m 45s 1hr fortnightly".split() + durations: Final = "1d 24h daily 7d weekly 2w 10d 30d monthly 1mo 4h 5h 30m 45s".split() for duration in durations: with self.subTest(duration=duration): reset_at = get_next_standardized_reset_time(duration, created_at, "UTC") diff --git a/tests/unit/proxy/common_utils/test_reset_budget_job.py b/tests/unit/proxy/common_utils/test_reset_budget_job.py index 183dd7919c1..a28234e5068 100644 --- a/tests/unit/proxy/common_utils/test_reset_budget_job.py +++ b/tests/unit/proxy/common_utils/test_reset_budget_job.py @@ -1334,6 +1334,36 @@ def test_reset_budget_windows_handles_string_budget_limits(monkeypatch): prisma_client.db.litellm_verificationtoken.update.assert_awaited_once() +def test_reset_budget_windows_clears_unparseable_duration_and_still_resets_later_rows(monkeypatch): + """An expired window with a duration the new parser rejects must not raise + and stall the keyset walk. Clearing reset_at persists so the next tick + skips it and later keys still reset.""" + now = datetime.utcnow() + expired = (now - timedelta(minutes=5)).isoformat() + "Z" + key_rows = [ + {"token": "sk-bad", "budget_limits": [{"budget_duration": "1dinvalid", "reset_at": expired}]}, + {"token": "sk-good", "budget_limits": [{"budget_duration": "1d", "reset_at": expired}]}, + ] + job, prisma_client, spend_counter_cache = _make_reset_budget_windows_job( + monkeypatch, key_rows=key_rows, team_rows=[] + ) + + asyncio.run(job.reset_budget_windows()) + + assert prisma_client.db.litellm_verificationtoken.update.await_count == 2 + first, second = prisma_client.db.litellm_verificationtoken.update.await_args_list + assert first.kwargs["where"] == {"token": "sk-bad"} + bad_windows = json.loads(first.kwargs["data"]["budget_limits"]) + assert bad_windows[0]["reset_at"] is None + assert second.kwargs["where"] == {"token": "sk-good"} + good_windows = json.loads(second.kwargs["data"]["budget_limits"]) + new_reset_at = datetime.fromisoformat(good_windows[0]["reset_at"].replace("Z", "+00:00")).replace(tzinfo=None) + assert new_reset_at > now + spend_counter_cache.in_memory_cache.set_cache.assert_any_call(key="spend:key:sk-good:window:1d", value=0.0) + touched_keys = [call.kwargs.get("key") for call in spend_counter_cache.in_memory_cache.set_cache.call_args_list] + assert "spend:key:sk-bad:window:1dinvalid" not in touched_keys + + def test_reset_budget_windows_skips_row_with_empty_budget_limits(monkeypatch): """A row whose `budget_limits` comes back as an empty/falsy payload (shouldn't happen given the WHERE filter, but we guard anyway) must not @@ -2506,6 +2536,92 @@ def test_budget_table_reset_stops_when_the_new_window_is_not_in_the_future(monke assert len(_batch_writes(client, "budget", op="update_many")) == 2 +_QUARANTINE_DATA = {"budget_duration": None, "budget_reset_at": None} + + +@pytest.mark.parametrize( + "phase, table_name, row_factory, id_field", + [ + ("reset_budget_for_litellm_keys", "key", _key_row, "token"), + ("reset_budget_for_litellm_users", "user", _user_row, "user_id"), + ("reset_budget_for_litellm_teams", "team", _team_row, "team_id"), + ], + ids=["keys", "users", "teams"], +) +def test_reset_quarantines_unparseable_budget_duration_and_keeps_paging( + monkeypatch, phase, table_name, row_factory, id_field +): + """A due row whose duration the new parser rejects used to raise, stay due, + and refill every batch. Clearing duration and reset_at takes it out of the + due query so later tenants can reset.""" + monkeypatch.setattr(reset_budget_job_module, "RESET_BUDGET_JOB_BATCH_SIZE", 2) + client, job = _chunked_job( + { + table_name: [ + [row_factory("bad1", budget_duration="1dinvalid"), row_factory("bad2", budget_duration="garbage")], + [row_factory("good1")], + ] + } + ) + + asyncio.run(getattr(job, phase)()) + + assert client.fetches_by_table[table_name] == 2 + writes = _batch_writes(client, table_name, op="update") + quarantined = [w for w in writes if w["data"] == _QUARANTINE_DATA] + reset = [w for w in writes if "spend" in w["data"]] + assert [w["where"][id_field] for w in quarantined] == ["bad1", "bad2"] + assert [w["where"][id_field] for w in reset] == ["good1"] + assert all("spend" not in w["data"] for w in quarantined) + + +def test_budget_table_reset_quarantines_unparseable_durations_and_keeps_paging(monkeypatch): + """The cascade used to raise while building the next window, commit nothing, + and leave the invalid tiers at the head of every later fetch.""" + monkeypatch.setattr(reset_budget_job_module, "RESET_BUDGET_JOB_BATCH_SIZE", 2) + client, job = _chunked_job( + { + "budget": [ + [_budget_row("bad1", budget_duration="1dinvalid"), _budget_row("bad2", budget_duration="garbage")], + [_budget_row("good1")], + ] + } + ) + + asyncio.run(job.reset_budget_for_litellm_budget_table()) + + assert client.fetches_by_table["budget"] == 2 + writes = _batch_writes(client, "budget", op="update_many") + quarantined = [w for w in writes if w["data"] == _QUARANTINE_DATA] + advanced = [w for w in writes if w["data"] != _QUARANTINE_DATA] + assert [w["where"]["budget_id"] for w in quarantined] == ["bad1", "bad2"] + assert [w["where"]["budget_id"] for w in advanced] == ["good1"] + assert all("spend" not in w["data"] for w in quarantined) + + +def test_budget_table_reset_does_not_sweep_dependents_of_an_unparseable_tier( + reset_budget_job, mock_prisma_client, monkeypatch +): + """Quarantine is not a scheduled reset: linked spend stays put.""" + _make_counter_invalidation_job(monkeypatch) + mock_prisma_client.data["budget"] = [_budget_row(budget_id="bad-tier", budget_duration="1dinvalid")] + mock_prisma_client.db.litellm_teammembership.set_find_many_results( + [type("Membership", (), {"user_id": "alice", "team_id": "team-x", "budget_id": "bad-tier", "spend": 9.0})()] + ) + + asyncio.run(reset_budget_job.reset_budget_for_litellm_budget_table()) + + assert _batch_writes(mock_prisma_client, "team_membership") == [] + assert _batch_writes(mock_prisma_client, "budget", op="update_many") == [ + { + "table": "budget", + "op": "update_many", + "where": {"budget_id": "bad-tier"}, + "data": _QUARANTINE_DATA, + } + ] + + class PoisonRow: """A row the in-memory reset cannot write, like the DataError rows in #27730.""" diff --git a/tests/unit/proxy/management_endpoints/test_team_endpoints.py b/tests/unit/proxy/management_endpoints/test_team_endpoints.py index f727448f3ac..3228e823d34 100644 --- a/tests/unit/proxy/management_endpoints/test_team_endpoints.py +++ b/tests/unit/proxy/management_endpoints/test_team_endpoints.py @@ -697,6 +697,50 @@ async def test_update_team_rejects_a_duration_that_never_advances( mock_find_unique.assert_not_awaited() +@pytest.mark.parametrize("blank", ["", " "]) +def test_set_budget_reset_at_treats_a_blank_duration_as_unset(blank): + from litellm.proxy.management_endpoints.team_endpoints import _set_budget_reset_at + + data = UpdateTeamRequest.model_construct(team_id="team-1", budget_duration=blank) + updated_kv = {"budget_duration": blank} + + persisted = _set_budget_reset_at(data, updated_kv) + + assert persisted["budget_duration"] is None + assert persisted["budget_reset_at"] is None + assert updated_kv == {"budget_duration": blank} + assert data.budget_duration == blank + + +@pytest.mark.parametrize("blank", ["", " "]) +def test_create_persistence_drops_blank_budget_duration_without_mutating_input(blank): + from litellm.proxy.management_endpoints.team_endpoints import ( + _persistence_values_for_budget_duration, + ) + + dumped = {"team_alias": "blank-duration-team", "budget_duration": blank, "max_budget": 10} + + persisted = _persistence_values_for_budget_duration(dumped, blank) + + assert "budget_duration" not in persisted + assert persisted["team_alias"] == "blank-duration-team" + assert dumped == {"team_alias": "blank-duration-team", "budget_duration": blank, "max_budget": 10} + + +def test_create_persistence_keeps_a_usable_budget_duration_without_mutating_input(): + from litellm.proxy.management_endpoints.team_endpoints import ( + _persistence_values_for_budget_duration, + ) + + dumped = {"team_alias": "daily-team", "budget_duration": "1d"} + + persisted = _persistence_values_for_budget_duration(dumped, "1d") + + assert persisted["budget_duration"] == "1d" + assert persisted is not dumped + assert dumped == {"team_alias": "daily-team", "budget_duration": "1d"} + + @pytest.mark.asyncio async def test_new_team_with_object_permission(mock_db_client, mock_admin_auth): """ @@ -13161,7 +13205,7 @@ async def test_update_team_ignores_explicit_null_require_trace_id_and_preserves_ def test_set_budget_reset_at_clears_when_budget_duration_null(): """ When budget_duration is explicitly set to null, _set_budget_reset_at - should set budget_reset_at=None in updated_kv so Prisma clears it in the DB. + should set budget_reset_at=None in the persistence copy so Prisma clears it. """ from litellm.proxy._types import UpdateTeamRequest from litellm.proxy.management_endpoints.team_endpoints import _set_budget_reset_at @@ -13169,16 +13213,17 @@ def test_set_budget_reset_at_clears_when_budget_duration_null(): data = UpdateTeamRequest(team_id="test-team", budget_duration=None) updated_kv = {"team_id": "test-team", "budget_duration": None} - _set_budget_reset_at(data, updated_kv) + persisted = _set_budget_reset_at(data, updated_kv) - assert "budget_reset_at" in updated_kv - assert updated_kv["budget_reset_at"] is None + assert persisted["budget_reset_at"] is None + assert persisted["budget_duration"] is None + assert updated_kv == {"team_id": "test-team", "budget_duration": None} def test_set_budget_reset_at_noop_when_budget_duration_not_sent(): """ When budget_duration is NOT sent (unset), _set_budget_reset_at should - not add budget_reset_at to updated_kv. + not add budget_reset_at to the persistence copy. """ from litellm.proxy._types import UpdateTeamRequest from litellm.proxy.management_endpoints.team_endpoints import _set_budget_reset_at @@ -13186,15 +13231,17 @@ def test_set_budget_reset_at_noop_when_budget_duration_not_sent(): data = UpdateTeamRequest(team_id="test-team") updated_kv = {"team_id": "test-team"} - _set_budget_reset_at(data, updated_kv) + persisted = _set_budget_reset_at(data, updated_kv) - assert "budget_reset_at" not in updated_kv + assert "budget_reset_at" not in persisted + assert persisted == {"team_id": "test-team"} + assert updated_kv == {"team_id": "test-team"} def test_set_budget_reset_at_sets_value_when_budget_duration_provided(): """ When budget_duration is set to a valid string, _set_budget_reset_at - should compute and set budget_reset_at. + should compute and set budget_reset_at on the persistence copy. """ from litellm.proxy._types import UpdateTeamRequest from litellm.proxy.management_endpoints.team_endpoints import _set_budget_reset_at @@ -13202,10 +13249,11 @@ def test_set_budget_reset_at_sets_value_when_budget_duration_provided(): data = UpdateTeamRequest(team_id="test-team", budget_duration="30d") updated_kv = {"team_id": "test-team", "budget_duration": "30d"} - _set_budget_reset_at(data, updated_kv) + persisted = _set_budget_reset_at(data, updated_kv) - assert "budget_reset_at" in updated_kv - assert updated_kv["budget_reset_at"] is not None + assert persisted["budget_reset_at"] is not None + assert persisted["budget_duration"] == "30d" + assert updated_kv == {"team_id": "test-team", "budget_duration": "30d"} @pytest.mark.asyncio @@ -16141,6 +16189,35 @@ async def test_new_team_explicit_null_budget_duration_beats_configured_default( assert team_data.get("budget_reset_at") is None +@pytest.mark.asyncio +@pytest.mark.parametrize("blank", ["", " "]) +async def test_new_team_blank_budget_duration_is_lifetime_not_a_daily_reset( + mock_db_client, mock_admin_auth, monkeypatch, blank +): + """A form-posted empty budget_duration used to stamp budget_reset_at at + next midnight. It must persist as unset, the same as an explicit null. + """ + from fastapi import Request + + import litellm + from litellm.proxy._types import NewTeamRequest + from litellm.proxy.management_endpoints.team_endpoints import new_team + + monkeypatch.setattr(litellm, "default_team_settings", None) + monkeypatch.setattr(litellm, "default_team_params", {"budget_duration": "30d"}) + mock_team_create = _wire_new_team_prisma(mock_db_client) + + await new_team( + data=NewTeamRequest(team_alias="blank-duration-team", budget_duration=blank), + http_request=MagicMock(spec=Request), + user_api_key_dict=mock_admin_auth, + ) + + team_data = mock_team_create.call_args.kwargs["data"] + assert team_data.get("budget_duration") is None + assert team_data.get("budget_reset_at") is None + + @pytest.mark.asyncio async def test_new_team_omitted_budget_duration_still_takes_configured_default( mock_db_client, mock_admin_auth, monkeypatch diff --git a/tests/unit/proxy/test__types.py b/tests/unit/proxy/test__types.py index 68bfe4b34e5..52b4928f8b3 100644 --- a/tests/unit/proxy/test__types.py +++ b/tests/unit/proxy/test__types.py @@ -13,11 +13,13 @@ from litellm.proxy._types import ( LiteLLM_TeamMembership, LitellmUserRoles, NewMCPServerRequest, + NewTeamRequest, NewUserRequest, OrganizationMemberUpdateRequest, ResetSpendRequest, UpdateKeyRequest, UpdateMCPServerRequest, + UpdateTeamRequest, UpdateUserRequest, UserAPIKeyAuth, ) @@ -208,6 +210,15 @@ def test_an_empty_max_budget_from_a_form_post_reads_as_no_budget_not_as_zero(): assert GenerateKeyRequest(max_budget="").max_budget is None +@pytest.mark.parametrize("blank", ("", " ")) +def test_an_empty_budget_duration_from_a_form_post_reads_as_unset(blank): + assert GenerateKeyRequest(budget_duration=blank).budget_duration is None + assert NewTeamRequest(team_alias="my-team", budget_duration=blank).budget_duration is None + assert NewTeamRequest(team_alias="my-team", team_member_budget_duration=blank).team_member_budget_duration is None + assert UpdateTeamRequest(team_id="team-1", budget_duration=blank).budget_duration is None + assert UpdateTeamRequest(team_id="team-1", team_member_budget_duration=blank).team_member_budget_duration is None + + @pytest.mark.parametrize("sent", (0, 0.0, 25.5)) def test_a_max_budget_that_was_actually_sent_is_kept(sent): assert GenerateKeyRequest(max_budget=sent).max_budget == sent diff --git a/tests/unit/repositories/test_unit_of_work.py b/tests/unit/repositories/test_unit_of_work.py index 082a29b7001..3d1e6594ed6 100644 --- a/tests/unit/repositories/test_unit_of_work.py +++ b/tests/unit/repositories/test_unit_of_work.py @@ -65,6 +65,37 @@ async def test_updates_across_tables_share_one_batch_and_commit_once(): ] +async def test_duration_quarantine_clears_duration_and_reset_without_touching_spend(): + batch = FakeBatch() + + async with spend_reset_unit_of_work(lambda: batch) as uow: + uow.keys.queue_duration_quarantine(token="tok-bad") + uow.users.queue_duration_quarantine(user_id="user-bad") + uow.teams.queue_duration_quarantine(team_id="team-bad") + + cleared = {"budget_duration": None, "budget_reset_at": None} + assert batch.calls == [ + ("litellm_verificationtoken", {"token": "tok-bad"}, cleared), + ("litellm_usertable", {"user_id": "user-bad"}, cleared), + ("litellm_teamtable", {"team_id": "team-bad"}, cleared), + ] + + +async def test_budget_window_quarantine_clears_duration_and_reset_without_touching_spend(): + batch = FakeBatch() + + async with budget_cascade_unit_of_work(lambda: batch) as uow: + uow.budgets.queue_window_quarantine(budget_id="budget-bad") + + assert batch.calls == [ + ( + "litellm_budgettable.update_many", + {"budget_id": "budget-bad"}, + {"budget_duration": None, "budget_reset_at": None}, + ) + ] + + async def test_raising_inside_block_skips_commit(): batch = FakeBatch()