GarminHealthLab/backend/services/garmin_throttle.py

"""
Client-side pacing for Garmin Connect.

Why this exists
---------------
A sync is not a handful of requests. Each day costs **nine** API calls
(`_extract_daily` makes six, `daily_extras` three), short syncs add five more
for the within-day curves, every activity without a stored detail costs one,
and five account-wide calls finish the run. So:

    7 days     ~  100 requests
    30 days    ~  300 requests
    730 days   ~ 6600 requests

and until now they were fired as fast as the network allowed. That is what
walks the account into a 429 — repeatedly, because the only defence was a 24h
cooldown *after* Garmin had already punished us. Backing off after the fact
does not stop it happening again; spacing the requests does.

Garmin publishes no limit for these endpoints, so the default comes from what
other consumers actually get away with (checked 2026-09-03):

* `sirredbeard/garmin-data-export` paces at **0.15s** by default, backs off on
  a 429, ramps back up, and pauses every 250 calls. Its README suggests
  `--delay 1.0` "if you want to play it safe".
* `evg656e/garmin-connect-scraper` defaults to **3s**, warning that smaller
  values "may result in timeout penalties from Garmin".
* Garmin's *official* (partner) API allows **100 requests/minute** — 0.6s
  each — which is the closest thing to a number Garmin itself stands behind.

0.5s sits between them: slower than the official allowance, three times more
cautious than the aggressive scraper, six times faster than the timid one.

Worth being clear about what this does and does not fix. The brutal
multi-hour blocks reported across those projects are on the **SSO/login**
endpoint and are keyed per account; this app's own lockout came from there,
not from data volume (it was re-minting a token on every connect — see
`_connect` in garmin.py). Pacing the data calls is the other half: a full
backfill firing 6600 requests flat out is not something to rely on Garmin
tolerating.

What it does
------------
* **Spacing.** Every call waits until at least `min_interval` has passed since
  the previous one, per account.
* **A per-run budget.** A run may issue at most N requests; the sync then stops
  cleanly and resumes next time (it already skips days it has stored). Without
  this, "全部历史" is a single unbounded burst no matter how well spaced.

Both apply at one choke point — a proxy around the client object — so every
call site is covered, including ones added later. Anything that reaches Garmin
without going through the client is not paced, which today means only the
login/token calls on `client.garth`: a couple per sync, not thousands.
"""
import functools
import os
import threading
import time


class BudgetExhausted(Exception):
    """This run has issued as many requests as it is allowed.

    Not an error: the caller keeps what it stored and continues next run.
    """


def min_interval():
    """Seconds between requests. Read per call so it is tunable without a
    restart, and so tests can set it to 0."""
    return float(os.environ.get("GARMIN_MIN_INTERVAL_SECONDS") or 0.5)


def default_budget():
    """Requests one sync run may issue.

    1200 at 0.5s is about 10 minutes of wall clock — long enough to cover four
    months of history in one go (9 requests per day), short enough that a full
    backfill is a handful of background runs rather than one long hammering.
    """
    return int(os.environ.get("GARMIN_REQUEST_BUDGET") or 1200)


class Limiter:
    """Per-account spacing and per-run request accounting."""

    def __init__(self, interval=None):
        self._interval = interval
        self._lock = threading.Lock()
        self._next_at = 0.0
        self.used = 0
        self.budget = None

    @property
    def interval(self):
        return min_interval() if self._interval is None else self._interval

    def start_run(self, budget=None):
        """Begin a run. `budget` None means unlimited (a short, known-size job)."""
        with self._lock:
            self.used = 0
            self.budget = budget

    @property
    def remaining(self):
        if self.budget is None:
            return None
        return max(0, self.budget - self.used)

    def acquire(self):
        """Claim a slot, waiting for it if necessary."""
        with self._lock:
            if self.budget is not None and self.used >= self.budget:
                raise BudgetExhausted(
                    f"本次同步已达请求预算上限（{self.budget} 次）"
                )
            self.used += 1
            now = time.monotonic()
            wait = self._next_at - now
            # Reserve this call's slot before releasing the lock, so two
            # threads get consecutive slots rather than the same one.
            self._next_at = max(now, self._next_at) + self.interval
        # Slept outside the lock: two callers should wait out their own
        # (non-overlapping) slots concurrently, not queue behind each other's.
        if wait > 0:
            time.sleep(wait)


_limiters = {}
_limiters_lock = threading.Lock()


def limiter_for(user_id):
    """The limiter for one account, created on first use.

    Per account and per process. Two Gunicorn workers therefore pace
    independently — acceptable because a given account syncs from one place at
    a time (the scheduler claims its tick through the database, and a manual
    sync sets the status to `syncing`), and the budget bounds the damage if
    that ever stops holding.
    """
    key = user_id or "_anon"
    with _limiters_lock:
        found = _limiters.get(key)
        if found is None:
            found = Limiter()
            _limiters[key] = found
        return found


class PacedClient:
    """Attribute proxy that paces every public method call.

    Non-callables (`display_name`, `garth`) pass through untouched, as do
    private names, and attribute writes reach the wrapped client — `_connect`
    sets `client.display_name` and the library reads it back on every request.
    """

    def __init__(self, inner, limiter):
        object.__setattr__(self, "_inner", inner)
        object.__setattr__(self, "_limiter", limiter)

    @property
    def limiter(self):
        return object.__getattribute__(self, "_limiter")

    @property
    def inner(self):
        return object.__getattribute__(self, "_inner")

    def __getattr__(self, name):
        attr = getattr(object.__getattribute__(self, "_inner"), name)
        if name.startswith("_") or not callable(attr):
            return attr
        limiter = object.__getattribute__(self, "_limiter")

        @functools.wraps(attr)
        def paced(*args, **kwargs):
            limiter.acquire()
            return attr(*args, **kwargs)

        return paced

    def __setattr__(self, name, value):
        setattr(object.__getattribute__(self, "_inner"), name, value)

    def __repr__(self):
        inner = object.__getattribute__(self, "_inner")
        return f"<PacedClient {inner!r}>"


def pace(client, user_id, budget=None):
    """Wrap `client` so its calls are spaced, and start a run.

    Idempotent: wrapping an already-wrapped client returns it (with the run
    restarted) rather than stacking two layers of waiting.
    """
    limiter = limiter_for(user_id)
    limiter.start_run(default_budget() if budget is None else budget)
    if isinstance(client, PacedClient):
        return client
    return PacedClient(client, limiter)