Buckets:

download
raw
9.87 kB
"""Per-principal daily cost tracking for RBAC cost caps.
Each authenticated principal accrues spend against the ``max_cost_per_day``
of its effective policy. When the accrued spend for the current UTC day meets
or exceeds the cap, further charged requests are rejected with
:class:`BudgetExceeded` (surfaced as HTTP 429 by the API server).
The tracker is process-local and in-memory by default. A daily snapshot is
optionally persisted to ``~/.effgen/budget/<YYYY-MM-DD>.json`` so that spend
survives a restart within the same day; set ``EFFGEN_BUDGET_PERSIST=0`` to
disable persistence.
This is intentionally simple — a single-process counter. For multi-replica
deployments back it with a shared store (Redis); the public API
(:func:`charge`, :func:`get_spend`, :func:`reset`) is the integration point.
"""
from __future__ import annotations
import json
import logging
import os
import threading
from datetime import UTC, datetime
from pathlib import Path
from effgen.errors import quote_for_message, with_next_step
logger = logging.getLogger(__name__)
class BudgetExceeded(Exception):
"""Raised when a principal exceeds its daily cost cap.
Surfaced by the API server as HTTP 429 (Too Many Requests). The message
names the cap that was reached and then what clears it.
Attributes:
status_code: The HTTP status this maps to (429 by default).
"""
_FOLLOW_ON = (
"The cap resets at the start of the next UTC day. Raise the "
"principal's daily limit in the budget configuration, or route the "
"request to a cheaper model."
)
def __init__(self, reason: str, status_code: int = 429) -> None:
super().__init__(with_next_step(quote_for_message(reason), self._FOLLOW_ON))
self.status_code = status_code
# ---------------------------------------------------------------------------
# In-memory daily ledger
# ---------------------------------------------------------------------------
_lock = threading.Lock()
# {day -> {principal -> spend_usd}}
_ledger: dict[str, dict[str, float]] = {}
# In-flight reservations: {day -> {principal -> {reservation_id -> amount}}}.
# Reserved (but not yet committed) amounts count against the cap so concurrent
# requests cannot all slip past the check before any of them is charged.
_reservations: dict[str, dict[str, dict[str, float]]] = {}
_BUDGET_DIR: Path | None = None
def _today() -> str:
return datetime.now(tz=UTC).strftime("%Y-%m-%d")
def _persist_enabled() -> bool:
return os.getenv("EFFGEN_BUDGET_PERSIST", "1").strip() != "0"
def _budget_dir() -> Path:
global _BUDGET_DIR
if _BUDGET_DIR is not None:
return _BUDGET_DIR
base = Path(os.getenv("EFFGEN_BUDGET_DIR", Path.home() / ".effgen" / "budget"))
base.mkdir(parents=True, exist_ok=True)
_BUDGET_DIR = base
return _BUDGET_DIR
def _day_file(day: str) -> Path:
return _budget_dir() / f"{day}.json"
def _load_day(day: str) -> dict[str, float]:
"""Return the ledger for *day*, loading from disk on first access."""
if day in _ledger:
return _ledger[day]
data: dict[str, float] = {}
if _persist_enabled():
path = _day_file(day)
if path.exists():
try:
data = {k: float(v) for k, v in json.loads(path.read_text()).items()}
except Exception as exc: # noqa: BLE001
logger.warning("Failed to load budget ledger %s: %s", path, exc)
_ledger[day] = data
return data
def _save_day(day: str) -> None:
if not _persist_enabled():
return
try:
_day_file(day).write_text(json.dumps(_ledger.get(day, {})))
except Exception as exc: # noqa: BLE001
logger.warning("Failed to persist budget ledger for %s: %s", day, exc)
# ---------------------------------------------------------------------------
# Public API
# ---------------------------------------------------------------------------
def get_spend(principal: str, *, day: str | None = None) -> float:
"""Return *principal*'s accrued spend (USD) for *day* (default today)."""
day = day or _today()
with _lock:
return _load_day(day).get(principal, 0.0)
def check_budget(principal: str, cap: float, *, day: str | None = None) -> None:
"""Raise :class:`BudgetExceeded` if *principal* has already met *cap*.
A *cap* of ``0.0`` means unlimited and never raises.
Args:
principal: Whose spend is checked.
cap: The daily limit in US dollars; ``0.0`` means unlimited.
day: The accounting day to check, defaulting to today.
"""
if cap <= 0.0:
return
spent = get_spend(principal, day=day)
if spent >= cap:
raise BudgetExceeded(
f"BudgetExceeded: principal {principal!r} has spent "
f"${spent:.4f} of its ${cap:.2f}/day cap"
)
def charge(
principal: str,
amount: float,
*,
cap: float = 0.0,
day: str | None = None,
) -> float:
"""Add *amount* USD to *principal*'s spend for *day* and return new total.
If *cap* is positive and the principal has **already** met or exceeded the
cap before this charge, :class:`BudgetExceeded` is raised and nothing is
charged. The charge itself may push spend past the cap (the next call then
rejects), which matches the spec: a cap of $0.01 admits the first call and
rejects subsequent ones.
"""
day = day or _today()
with _lock:
ledger = _load_day(day)
current = ledger.get(principal, 0.0)
if cap > 0.0 and current >= cap:
raise BudgetExceeded(
f"BudgetExceeded: principal {principal!r} has spent "
f"${current:.4f} of its ${cap:.2f}/day cap"
)
ledger[principal] = current + max(0.0, amount)
_save_day(day)
return ledger[principal]
def _reserved_total(principal: str, day: str) -> float:
"""Sum of in-flight reservations for *principal* on *day* (lock held)."""
return sum(_reservations.get(day, {}).get(principal, {}).values())
def reserve(
principal: str,
amount: float,
*,
cap: float = 0.0,
day: str | None = None,
) -> str:
"""Reserve *amount* USD against *principal*'s budget and return a token.
The reservation counts against the cap immediately (alongside already
committed spend) so an over-budget or concurrently-bursting principal is
rejected *before* the request runs. Nothing is permanently charged until
:func:`reconcile` is called; :func:`release` discards the reservation
without charging (used when the underlying call fails).
Raises :class:`BudgetExceeded` if committed + reserved spend has already met
or exceeded a positive *cap*.
Args:
principal: Whose budget the reservation is taken from.
amount: The estimated cost to hold, in US dollars.
cap: The daily limit in US dollars; ``0.0`` means unlimited.
day: The accounting day to reserve against, defaulting to today.
"""
import uuid
day = day or _today()
with _lock:
committed = _load_day(day).get(principal, 0.0)
reserved = _reserved_total(principal, day)
if cap > 0.0 and (committed + reserved) >= cap:
raise BudgetExceeded(
f"BudgetExceeded: principal {principal!r} has spent/reserved "
f"${committed + reserved:.4f} of its ${cap:.2f}/day cap"
)
token = uuid.uuid4().hex
_reservations.setdefault(day, {}).setdefault(principal, {})[token] = max(0.0, amount)
return token
def _pop_reservation(principal: str, token: str, day: str) -> float:
"""Remove and return a reservation amount (lock held); 0.0 if missing."""
by_principal = _reservations.get(day, {}).get(principal, {})
return by_principal.pop(token, 0.0)
def reconcile(
principal: str,
token: str,
actual_amount: float | None = None,
*,
day: str | None = None,
) -> float:
"""Commit a reservation, charging *actual_amount* (default = reserved).
Returns the principal's new committed total. Pass ``actual_amount`` when the
real provider usage/cost is known after the call completes; otherwise the
originally reserved estimate is charged.
Args:
principal: Whose budget is charged.
token: The reservation token to commit.
actual_amount: What the call really cost, defaulting to the reservation.
day: The accounting day to charge, defaulting to today.
"""
day = day or _today()
with _lock:
reserved = _pop_reservation(principal, token, day)
charge_amount = reserved if actual_amount is None else max(0.0, actual_amount)
ledger = _load_day(day)
ledger[principal] = ledger.get(principal, 0.0) + charge_amount
_save_day(day)
return ledger[principal]
def release(principal: str, token: str, *, day: str | None = None) -> None:
"""Discard a reservation without charging (e.g. the call failed).
Args:
principal: Whose reservation is discarded.
token: The reservation token to discard.
day: The accounting day the reservation was made on.
"""
day = day or _today()
with _lock:
_pop_reservation(principal, token, day)
def reset(principal: str | None = None, *, day: str | None = None) -> None:
"""Reset spend. With no args, clears the entire in-memory ledger.
Primarily for tests and admin tooling.
"""
global _ledger, _BUDGET_DIR, _reservations
with _lock:
if principal is None and day is None:
_ledger = {}
_reservations = {}
return
d = day or _today()
ledger = _load_day(d)
if principal is None:
ledger.clear()
else:
ledger.pop(principal, None)
_save_day(d)

Xet Storage Details

Size:
9.87 kB
·
Xet hash:
50a511d28ea99e93eb9e9c93ff051a8a340f5766c18c17503fda24556fd1052c

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.