server: respect Brave search rate limits

server/tests/brave-search.test.ts

@@ -1,12 +1,13 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import { env } from "../src/env.js";
-import { searchBrave } from "../src/search/brave.js";
+import { resetBraveRateLimitStateForTests, searchBrave } from "../src/search/brave.js";
 
 test("searchBrave authenticates, builds filters, and normalizes web results", async () => {
   const originalFetch = globalThis.fetch;
   const originalApiKey = env.BRAVE_SEARCH_API_KEY;
   const fetchCalls: Array<{ input: RequestInfo | URL; init?: RequestInit }> = [];
+  resetBraveRateLimitStateForTests();
   env.BRAVE_SEARCH_API_KEY = "test-brave-key";
   globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
     fetchCalls.push({ input, init });
@@ -81,6 +82,7 @@ test("searchBrave authenticates, builds filters, and normalizes web results", as
 
 test("searchBrave rejects requests without an API key", async () => {
   const originalApiKey = env.BRAVE_SEARCH_API_KEY;
+  resetBraveRateLimitStateForTests();
   env.BRAVE_SEARCH_API_KEY = undefined;
   try {
     await assert.rejects(() => searchBrave("test", { numResults: 1 }), /BRAVE_SEARCH_API_KEY not set/);
@@ -92,6 +94,7 @@ test("searchBrave rejects requests without an API key", async () => {
 test("searchBrave reports non-JSON responses", async () => {
   const originalFetch = globalThis.fetch;
   const originalApiKey = env.BRAVE_SEARCH_API_KEY;
+  resetBraveRateLimitStateForTests();
   env.BRAVE_SEARCH_API_KEY = "test-brave-key";
   globalThis.fetch = (async () =>
     new Response("upstream error", {
@@ -109,3 +112,173 @@ test("searchBrave reports non-JSON responses", async () => {
     env.BRAVE_SEARCH_API_KEY = originalApiKey;
   }
 });
+
+test("searchBrave evenly paces concurrent bursts using Brave's shortest policy window", async () => {
+  const originalFetch = globalThis.fetch;
+  const originalApiKey = env.BRAVE_SEARCH_API_KEY;
+  const requestStartedAt: number[] = [];
+  resetBraveRateLimitStateForTests();
+  env.BRAVE_SEARCH_API_KEY = "test-brave-key";
+  globalThis.fetch = (async () => {
+    requestStartedAt.push(Date.now());
+    return new Response(JSON.stringify({ web: { results: [] } }), {
+      status: 200,
+      headers: {
+        "content-type": "application/json",
+        "x-ratelimit-policy": "1;w=1, 2000;w=2678400",
+        "x-ratelimit-remaining": "1, 1999",
+        "x-ratelimit-reset": "1, 2678400",
+      },
+    });
+  }) as typeof fetch;
+
+  try {
+    await Promise.all([
+      searchBrave("burst one", { numResults: 1 }),
+      searchBrave("burst two", { numResults: 1 }),
+      searchBrave("burst three", { numResults: 1 }),
+    ]);
+
+    assert.equal(requestStartedAt.length, 3);
+    assert.ok(requestStartedAt[1]! - requestStartedAt[0]! >= 1_000);
+    assert.ok(requestStartedAt[2]! - requestStartedAt[1]! >= 1_000);
+  } finally {
+    globalThis.fetch = originalFetch;
+    env.BRAVE_SEARCH_API_KEY = originalApiKey;
+    resetBraveRateLimitStateForTests();
+  }
+});
+
+test("searchBrave adapts its pacing to a 50 request-per-second Search plan", async () => {
+  const originalFetch = globalThis.fetch;
+  const originalApiKey = env.BRAVE_SEARCH_API_KEY;
+  const requestStartedAt: number[] = [];
+  resetBraveRateLimitStateForTests();
+  env.BRAVE_SEARCH_API_KEY = "test-brave-key";
+  globalThis.fetch = (async () => {
+    requestStartedAt.push(Date.now());
+    return new Response(JSON.stringify({ web: { results: [] } }), {
+      status: 200,
+      headers: {
+        "content-type": "application/json",
+        "x-ratelimit-policy": "50;w=1, 0;w=2678400",
+        "x-ratelimit-remaining": "49, 0",
+        "x-ratelimit-reset": "1, 2678400",
+      },
+    });
+  }) as typeof fetch;
+
+  try {
+    await searchBrave("learn upgraded policy", { numResults: 1 });
+    await Promise.all(Array.from({ length: 8 }, (_, index) => searchBrave(`fast burst ${index}`, { numResults: 1 })));
+
+    assert.equal(requestStartedAt.length, 9);
+    const burstStartedAt = requestStartedAt.slice(1);
+    for (let index = 1; index < burstStartedAt.length; index += 1) {
+      assert.ok(burstStartedAt[index]! - burstStartedAt[index - 1]! >= 18);
+    }
+    assert.ok(burstStartedAt.at(-1)! - burstStartedAt[0]! < 500);
+  } finally {
+    globalThis.fetch = originalFetch;
+    env.BRAVE_SEARCH_API_KEY = originalApiKey;
+    resetBraveRateLimitStateForTests();
+  }
+});
+
+test("searchBrave retries 429 responses after the burst window resets", async () => {
+  const originalFetch = globalThis.fetch;
+  const originalApiKey = env.BRAVE_SEARCH_API_KEY;
+  let fetchCount = 0;
+  resetBraveRateLimitStateForTests();
+  env.BRAVE_SEARCH_API_KEY = "test-brave-key";
+  globalThis.fetch = (async () => {
+    fetchCount += 1;
+    const rateLimitHeaders = {
+      "content-type": "application/json",
+      "x-ratelimit-policy": "1;w=1, 2000;w=2678400",
+      "x-ratelimit-remaining": fetchCount === 1 ? "0, 1999" : "1, 1998",
+      "x-ratelimit-reset": "1, 2678400",
+    };
+    if (fetchCount === 1) {
+      return new Response(JSON.stringify({ error: { detail: "Rate limit exceeded" } }), {
+        status: 429,
+        headers: rateLimitHeaders,
+      });
+    }
+    return new Response(JSON.stringify({ web: { results: [] } }), { status: 200, headers: rateLimitHeaders });
+  }) as typeof fetch;
+
+  try {
+    const startedAt = Date.now();
+    await searchBrave("retry burst", { numResults: 1 });
+    assert.equal(fetchCount, 2);
+    assert.ok(Date.now() - startedAt >= 1_000);
+  } finally {
+    globalThis.fetch = originalFetch;
+    env.BRAVE_SEARCH_API_KEY = originalApiKey;
+    resetBraveRateLimitStateForTests();
+  }
+});
+
+test("searchBrave does not wait for exhausted long-term quotas", async () => {
+  const originalFetch = globalThis.fetch;
+  const originalApiKey = env.BRAVE_SEARCH_API_KEY;
+  resetBraveRateLimitStateForTests();
+  env.BRAVE_SEARCH_API_KEY = "test-brave-key";
+  globalThis.fetch = (async () =>
+    new Response(JSON.stringify({ error: { detail: "Quota exceeded" } }), {
+      status: 429,
+      headers: {
+        "content-type": "application/json",
+        "x-ratelimit-policy": "1;w=1, 2000;w=2678400",
+        "x-ratelimit-remaining": "0, 0",
+        "x-ratelimit-reset": "1, 100000",
+      },
+    })) as typeof fetch;
+
+  try {
+    const startedAt = Date.now();
+    await assert.rejects(
+      () => searchBrave("quota exhausted", { numResults: 1 }),
+      /rate limit quota is exhausted beyond the retry window/
+    );
+    assert.ok(Date.now() - startedAt < 1_000);
+  } finally {
+    globalThis.fetch = originalFetch;
+    env.BRAVE_SEARCH_API_KEY = originalApiKey;
+    resetBraveRateLimitStateForTests();
+  }
+});
+
+test("searchBrave blocks locally after a successful request exhausts the long-term quota", async () => {
+  const originalFetch = globalThis.fetch;
+  const originalApiKey = env.BRAVE_SEARCH_API_KEY;
+  let fetchCount = 0;
+  resetBraveRateLimitStateForTests();
+  env.BRAVE_SEARCH_API_KEY = "test-brave-key";
+  globalThis.fetch = (async () => {
+    fetchCount += 1;
+    return new Response(JSON.stringify({ web: { results: [] } }), {
+      status: 200,
+      headers: {
+        "content-type": "application/json",
+        "x-ratelimit-policy": "1;w=1, 2000;w=2678400",
+        "x-ratelimit-remaining": "0, 0",
+        "x-ratelimit-reset": "1, 100000",
+      },
+    });
+  }) as typeof fetch;
+
+  try {
+    await searchBrave("last allowed query", { numResults: 1 });
+    await assert.rejects(
+      () => searchBrave("over quota query", { numResults: 1 }),
+      /long-term quota is exhausted/
+    );
+    assert.equal(fetchCount, 1);
+  } finally {
+    globalThis.fetch = originalFetch;
+    env.BRAVE_SEARCH_API_KEY = originalApiKey;
+    resetBraveRateLimitStateForTests();
+  }
+});