Add jitter to the rate-limit retry

A burst of concurrent calls hitting the same 429 (e.g. a static build
rendering pages in parallel with the same token) used to all read the same
X-RateLimit-Reset and retry on the exact same tick, immediately
re-triggering the same rate limit. Retries now add a random extra on top of
the required wait (capped at 5s, since a few seconds of spread is enough
regardless of how long the base wait already is).

Claude-Session: https://claude.ai/code/session_01PY2yju9C9qdHdroj3zhbvc

Author: stefanoverna

.changeset/jittery-jellyfish-jump.md

@@ -0,0 +1,10 @@
+---
+'@datocms/cda-client': patch
+---
+
+Add jitter to the rate-limit retry
+
+Many concurrent requests hitting a 429 at once (e.g. a static build rendering
+pages in parallel) used to all retry on the exact same tick, immediately
+re-triggering the same rate limit. Retries are now spread out with a random
+extra wait on top of the required one.

src/__test__/withJitter.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it, vi } from 'vitest';
+import { withJitter } from '../executeQuery.js';
+
+describe('withJitter()', () => {
+  it('never returns less than the base wait', () => {
+    vi.spyOn(Math, 'random').mockReturnValue(0);
+    expect(withJitter(2)).toBe(2);
+    expect(withJitter(45)).toBe(45);
+    vi.restoreAllMocks();
+  });
+
+  it('doubles a base wait smaller than the cap', () => {
+    vi.spyOn(Math, 'random').mockReturnValue(1);
+    expect(withJitter(2)).toBe(4);
+    vi.restoreAllMocks();
+  });
+
+  it('caps the extra wait for a base larger than the cap', () => {
+    vi.spyOn(Math, 'random').mockReturnValue(1);
+    expect(withJitter(45)).toBe(50);
+    vi.restoreAllMocks();
+  });
+});

src/executeQuery.ts

@@ -122,7 +122,7 @@ export async function rawExecuteQuery<Result, Variables>(
       ? Number.parseInt(rateLimitReset, 10)
       : retryCount;
 
-    await wait(waitTimeInSecs * 1000);
+    await wait(withJitter(waitTimeInSecs) * 1000);
 
     return rawExecuteQuery<Result, Variables>(serializedQuery, {
       ...options,
@@ -183,3 +183,28 @@ function wait(time: number) {
     setTimeout(resolve, time);
   });
 }
+
+/**
+ * The CDA enforces two per-token buckets — 40 req/s and 1000 req/min — and
+ * `X-RateLimit-Reset` tells us how many seconds are left until whichever
+ * bucket we hit refills (so anywhere from ~1s to ~60s). A frontend build
+ * commonly fires many requests with the *same* token in parallel (e.g. a
+ * static site generator rendering pages concurrently), so a burst that trips
+ * the limit trips it for all of them together, and without jitter they'd all
+ * wake up and retry on the same tick, reproducing the exact burst that got
+ * them rate-limited.
+ *
+ * We never wait less than `baseSeconds` — retrying before the bucket refills
+ * is guaranteed to 429 again. On top of that we add a random extra, capped at
+ * `JITTER_CAP_SECONDS`: what desynchronizes concurrent retries is a few
+ * seconds of spread, not a delay proportional to the wait itself — doubling
+ * a 1s wait is fine, but doubling the ~60s wait of the per-minute bucket
+ * would needlessly leave callers waiting up to a minute longer than needed.
+ */
+const JITTER_CAP_SECONDS = 5;
+
+export function withJitter(baseSeconds: number): number {
+  return (
+    baseSeconds + Math.random() * Math.min(baseSeconds, JITTER_CAP_SECONDS)
+  );
+}