""" 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