aboutsummaryrefslogtreecommitdiff
path: root/castle-search/src/x-limits.ts
blob: bdc4229f02f655ab78b23ab0eba571f96917c68d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
/**
 * 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<void>;
  /** Uniform in [0, 1), as Math.random. */
  random: () => number;
};

const realSleep = (ms: number, signal: AbortSignal): Promise<void> =>
  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<void> = 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<T>(signal: AbortSignal, fn: () => Promise<T>): Promise<T> {
    const previous = this.#tail;
    let done!: () => void;
    this.#tail = new Promise<void>((resolve) => (done = resolve));
    try {
      await Promise.race([
        previous,
        new Promise<never>((_, 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<void> {
    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());
  }
}