receipter-pro / backend /rate_limiter.py
M8ion deploy
Deploy backend
45dc2a1
Raw History Blame Contribute Delete
3.28 kB
"""
Basic per-org hourly send cap (docs/blueprint/adr/0004, blueprint "Rate limiting"). Phase 1
scope only: a rolling window enforced server-side. Anomaly detection and the 4-stage
escalation (detect -> block -> silently_report -> auto_temporary_ban) are Phase 2
(docs/product/checklist.md) — this module only ever does stage one, "detect (and block)".
Rolling, not fixed-hour-boundary, per ADR-0004 — avoids the burst-at-the-top-of-the-hour
gap a naive reset would allow. Recorded timestamps live in the local store now; the
blueprint's eventual home for this is Redis/Memorystore, not Firestore (same reasoning as
the old due-job queue: don't put a perpetually-touched counter in a serverless-priced store).
"""
from __future__ import annotations
import time
from backend import local_store
from backend.core.constants import DEFAULT_HOURLY_SEND_CAP
_WINDOW_SECONDS = 3600
class RateLimitExceeded(Exception):
def __init__(self, org_id: str, requested: int, remaining: int):
self.org_id = org_id
self.requested = requested
self.remaining = remaining
super().__init__(
f"org {org_id!r} requested {requested} sends but only {remaining} remain "
f"in the current rolling hour"
)
def _counter_path(org_id: str) -> str:
return f"rate_counters/{org_id}"
def _current_timestamps(org_id: str, now: float) -> list[float]:
doc = local_store.get_doc(_counter_path(org_id))
timestamps = doc["timestamps"] if doc else []
return [t for t in timestamps if now - t < _WINDOW_SECONDS]
def remaining_capacity(org_id: str, hourly_cap: int = DEFAULT_HOURLY_SEND_CAP) -> int:
now = time.time()
used = len(_current_timestamps(org_id, now))
return max(0, hourly_cap - used)
def check_and_consume(org_id: str, count: int, hourly_cap: int = DEFAULT_HOURLY_SEND_CAP) -> None:
"""Reserves `count` sends against org_id's rolling-hour cap, all at once — a batch
either entirely fits or the whole call is rejected (Phase 1 simplification: no partial
sends within a single batch). Raises RateLimitExceeded if it doesn't fit. Server-side
only — nothing here is ever populated from a client-supplied value."""
now = time.time()
timestamps = _current_timestamps(org_id, now)
remaining = max(0, hourly_cap - len(timestamps))
if count > remaining:
raise RateLimitExceeded(org_id, count, remaining)
timestamps.extend([now] * count)
local_store.set_doc(_counter_path(org_id), {"timestamps": timestamps})
def allow_hit(bucket: str, limit: int, window_seconds: int) -> bool:
"""Generic rolling-window counter for anything that is not an org send (e.g. the public
collection endpoint's per-key / per-IP / per-address limits). Records the hit and returns
True if it is within `limit` hits per `window_seconds`; returns False (and records
nothing) if it would exceed the limit. Always the local store, never Firestore."""
now = time.time()
path = f"rate_buckets/{bucket}"
doc = local_store.get_doc(path)
hits = [t for t in (doc["timestamps"] if doc else []) if now - t < window_seconds]
if len(hits) >= limit:
return False
hits.append(now)
local_store.set_doc(path, {"timestamps": hits})
return True