/** * Limits on X searches, so the signed-in account reads X like a person rather * than a scraper, and X has no reason to lock it. * * - one search at a time; * - GAP_MS ± up to JITTER_MS between the starts of two searches, drawn * afresh each time (5-55 s), so they do not come at a machine's even * beat: one that comes sooner waits its turn rather than failing; * - at most PER_HOUR in any rolling hour and PER_DAY in any rolling day: * beyond that a search fails at once, saying when the next one may run. * * Counts are kept in memory: a restart of the service starts them afresh. */ /** Owner's choice, 2026-11-18: 30 s plus or minus a random 0-25 s. */ export const GAP_MS = 30_000; export const JITTER_MS = 25_000; export const PER_HOUR = 30; export const PER_DAY = 150; const HOUR_MS = 3_600_000; const DAY_MS = 24 * HOUR_MS; export class XRateLimitError extends Error { override readonly name = "XRateLimitError"; } export type Clock = { now: () => number; sleep: (ms: number, signal: AbortSignal) => Promise; /** Uniform in [0, 1), as Math.random. */ random: () => number; }; const realSleep = (ms: number, signal: AbortSignal): Promise => new Promise((resolve, reject) => { if (signal.aborted) return reject(signal.reason); const t = setTimeout(resolve, ms); signal.addEventListener("abort", () => { clearTimeout(t); reject(signal.reason); }, { once: true }); }); export const realClock: Clock = { now: Date.now, sleep: realSleep, random: Math.random }; export type Limits = { gap: number; jitter: number; hour: number; day: number }; const at = (ms: number): string => new Date(ms).toISOString().replace("T", " ").slice(0, 16) + " UTC"; export class XLimiter { readonly #clock: Clock; readonly #limits: Limits; /** Start times of the searches in the last day, oldest first. */ #starts: number[] = []; /** The tail of the queue: each search waits for the one before it. */ #tail: Promise = Promise.resolve(); constructor(clock: Clock = realClock, limits: Limits = { gap: GAP_MS, jitter: JITTER_MS, hour: PER_HOUR, day: PER_DAY }) { this.#clock = clock; this.#limits = limits; } /** Runs `fn` once the limits allow, one at a time; throws XRateLimitError when over a cap. */ async run(signal: AbortSignal, fn: () => Promise): Promise { const previous = this.#tail; let done!: () => void; this.#tail = new Promise((resolve) => (done = resolve)); try { await Promise.race([ previous, new Promise((_, reject) => { if (signal.aborted) reject(signal.reason); signal.addEventListener("abort", () => reject(signal.reason), { once: true }); }), ]); // An abandoned search ahead of us must not hold the queue: `previous` // settles when it finishes or is aborted, whichever comes first. await this.#admit(signal); return await fn(); } finally { done(); } } async #admit(signal: AbortSignal): Promise { const now = this.#clock.now(); this.#starts = this.#starts.filter((t) => t > now - DAY_MS); const lastHour = this.#starts.filter((t) => t > now - HOUR_MS); if (this.#starts.length >= this.#limits.day) { throw new XRateLimitError( `X search limit reached: ${this.#limits.day} searches in the last 24 hours, to keep the account ` + `from being locked. The next one can run after ${at(this.#starts[0]! + DAY_MS)}. Tell the user.`, ); } if (lastHour.length >= this.#limits.hour) { throw new XRateLimitError( `X search limit reached: ${this.#limits.hour} searches in the last hour, to keep the account ` + `from being locked. The next one can run after ${at(lastHour[0]! + HOUR_MS)}. Tell the user, ` + `and do not retry before then.`, ); } const last = this.#starts[this.#starts.length - 1]; const gap = Math.max(0, this.#limits.gap + (this.#clock.random() * 2 - 1) * this.#limits.jitter); if (last !== undefined && now - last < gap) { await this.#clock.sleep(gap - (now - last), signal); } this.#starts.push(this.#clock.now()); } }