7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.
TypeScript
fix(health): stop polling SerpSearch, Exa and Parallel keys with empty searches (#1599) (#1608)
Tashfeenb78a77403803
diff --git a/docs/BEATAPI-SERPSEARCH.md b/docs/BEATAPI-SERPSEARCH.mdindex 741c2487..42d6db5d 100644--- a/docs/BEATAPI-SERPSEARCH.md+++ b/docs/BEATAPI-SERPSEARCH.md@@ -36,6 +36,9 @@ Sources: [decision API](https://docs.beatapi.io/decisions),- Key validation omits `query`. A valid key returns a missing-query HTTP 400with quota headers, an invalid key returns 401. Both were live checked, andthe valid probe did not decrement quota. Unexpected responses are inconclusive.+- That probe runs once per key, never on the 5-minute health schedule (#1599).+ SerpSearch revoked a free account over empty searches every 5 minutes. After+ the first check, real searches and "Check now" decide the key's status.- The adapter follows the existing no-hits fallback policy and result limit.It does not paginate automatically or consume extra credits to fill results.diff --git a/server/src/__tests__/services/health-no-poll-provider.test.ts b/server/src/__tests__/services/health-no-poll-provider.test.tsnew file mode 100644index 00000000..bc15c5ae--- /dev/null+++ b/server/src/__tests__/services/health-no-poll-provider.test.ts@@ -0,0 +1,103 @@+import { describe, it, expect, beforeAll, beforeEach, vi } from 'vitest';++// #1599: SerpSearch revoked a free account over the empty search the health+// pass sent every 5 minutes as its key check. A provider with+// supportsKeyPolling === false gets one check per key, not one per pass.+const validateKey = vi.fn();+vi.mock('../../providers/index.js', async (importOriginal) => {+ const actual = await importOriginal() as any;+ return {+ ...actual,+ resolveProvider: () => ({ name: 'no-poll', supportsKeyPolling: false, validateKey }),+ };+});++const { initDb, getDb } = await import('../../db/index.js');+const { encrypt } = await import('../../lib/crypto.js');+const { checkAllKeys, probeKeyValidity, NO_POLL_ERROR_REPROBE_MS } = await import('../../services/health.js');+const { SerpSearchProvider } = await import('../../providers/serpsearch.js');+const { ExaProvider } = await import('../../providers/exa.js');+const { ParallelProvider } = await import('../../providers/parallel.js');++describe('a provider that must not be polled (#1599)', () => {+ let nextId = 9300;++ beforeAll(() => {+ process.env.ENCRYPTION_KEY = '0'.repeat(64);+ initDb(':memory:');+ });++ beforeEach(() => {+ getDb().prepare('DELETE FROM api_keys').run();+ validateKey.mockReset();+ validateKey.mockResolvedValue(true);+ vi.spyOn(console, 'error').mockImplementation(() => {});+ vi.spyOn(console, 'warn').mockImplementation(() => {});+ vi.spyOn(console, 'log').mockImplementation(() => {});+ });++ /** ageMs null = never checked. */+ function seedKey(status: string, ageMs: number | null): number {+ const id = ++nextId;+ const enc = encrypt(`no-poll-${id}`);+ const checkedAt = ageMs === null ? null : new Date(Date.now() - ageMs).toISOString().replace('T', ' ').slice(0, 19);+ getDb().prepare(`+ INSERT INTO api_keys (id, platform, label, encrypted_key, iv, auth_tag, enabled, status, last_checked_at)+ VALUES (?, 'serpsearch', ?, ?, ?, ?, 1, ?, ?)+ `).run(id, `no-poll-${id}`, enc.encrypted, enc.iv, enc.authTag, status, checkedAt);+ return id;+ }++ it('validates a new key once, then never again on the schedule', async () => {+ const id = seedKey('unknown', null);++ expect((await checkAllKeys()).checkedKeyIds).toEqual([id]);+ expect(validateKey).toHaveBeenCalledOnce();++ // The next scheduled pass and the forced post-wake pass both skip it.+ expect((await checkAllKeys()).skippedKeyIds).toEqual([id]);+ expect((await checkAllKeys({ force: true })).skippedKeyIds).toEqual([id]);+ expect(validateKey).toHaveBeenCalledOnce();+ });++ it('leaves a healthy or invalid key alone however long ago it was checked', async () => {+ const healthy = seedKey('healthy', 30 * 24 * 60 * 60 * 1000);+ const invalid = seedKey('invalid', 30 * 24 * 60 * 60 * 1000);++ const pass = await checkAllKeys({ force: true });++ expect(pass.checkedKeyIds).toEqual([]);+ expect(pass.skippedKeyIds.sort()).toEqual([healthy, invalid].sort());+ expect(validateKey).not.toHaveBeenCalled();+ });++ it('re-asks about a key parked at error at most once per reprobe window', async () => {+ const recent = seedKey('error', 10 * 60 * 1000);+ const stale = seedKey('error', NO_POLL_ERROR_REPROBE_MS + 60 * 1000);++ const pass = await checkAllKeys();++ expect(pass.checkedKeyIds).toEqual([stale]);+ expect(pass.skippedKeyIds).toEqual([recent]);+ });++ it('"Check all" still validates every key', async () => {+ const id = seedKey('healthy', 60 * 1000);++ expect((await checkAllKeys({ force: true, manual: true })).checkedKeyIds).toEqual([id]);+ expect(validateKey).toHaveBeenCalledOnce();+ });++ it('the cooldown probe treats the key as inconclusive without probing', async () => {+ const id = seedKey('healthy', 60 * 1000);++ expect(await probeKeyValidity(id)).toBe('error');+ expect(validateKey).not.toHaveBeenCalled();+ });++ it('is set for the providers whose key check is an empty search', () => {+ expect(new SerpSearchProvider().supportsKeyPolling).toBe(false);+ expect(new ExaProvider().supportsKeyPolling).toBe(false);+ expect(new ParallelProvider().supportsKeyPolling).toBe(false);+ });+});diff --git a/server/src/providers/base.ts b/server/src/providers/base.tsindex 4f35e875..5d479e8a 100644--- a/server/src/providers/base.ts+++ b/server/src/providers/base.ts@@ -286,6 +286,19 @@ export abstract class BaseProvider {return true;}+ /** Whether the scheduled health pass may re-validate this provider's keys+ * every few minutes (#1599). A provider whose only key check is a malformed+ * request to its billed endpoint (SerpSearch, Exa and keyed Parallel send a+ * search with no query) returns false: to the provider those requests look+ * like a script firing empty searches all day, and SerpSearch revoked a free+ * account over them. The scheduled pass then validates such a key once, when+ * it has never been checked, re-asks about a key parked at 'error' at most+ * every NO_POLL_ERROR_REPROBE_MS, and leaves the rest to real traffic. The+ * cooldown probe never validates it; "Check now" and "Check all" still do. */+ get supportsKeyPolling(): boolean {+ return true;+ }+/*** Turn a conventional 401/403 validation response into a diagnostic result.* Providers still return a simple boolean when no useful error body exists,diff --git a/server/src/providers/exa.ts b/server/src/providers/exa.tsindex 3590dd31..c3d994dd 100644--- a/server/src/providers/exa.ts+++ b/server/src/providers/exa.ts@@ -5,14 +5,21 @@ import { SearchOnlyProvider } from './search-only.js';export const EXA_BASE_URL = 'https://api.exa.ai';// Exa (exa.ai): recurring monthly free credits. Exa has no free "who am I"-// endpoint and the health checker validates every key every few minutes, so a-// real search probe would burn the free credits within days. Instead the probe+// endpoint, so a real search probe would spend credits. Instead the probe// sends a search with no query: Exa authenticates first, so a bad key answers// 401 while a good one fails body validation with a 400 and spends nothing.+// Empty searches every few minutes look like abuse (#1599), so the health pass+// sends this once per key, not on its schedule.export class ExaProvider extends SearchOnlyProvider {readonly platform: Platform = 'exa';readonly name = 'Exa';+ /** #1599: validation is an empty search, so the health pass checks a key+ * once instead of every few minutes. */+ override get supportsKeyPolling(): boolean {+ return false;+ }+async validateKey(apiKey: string): Promise<KeyValidationResult> {return this.probe(`${EXA_BASE_URL}/search`, {method: 'POST',diff --git a/server/src/providers/parallel.ts b/server/src/providers/parallel.tsindex 65288abc..78c11ee4 100644--- a/server/src/providers/parallel.ts+++ b/server/src/providers/parallel.ts@@ -20,6 +20,12 @@ export class ParallelProvider extends SearchOnlyProvider {readonly name = 'Parallel';keyless = true;+ /** #1599: validation is an empty search, so the health pass checks a key+ * once instead of every few minutes. */+ override get supportsKeyPolling(): boolean {+ return false;+ }+async validateKey(apiKey: string): Promise<KeyValidationResult> {if (isAnonymousCredential(apiKey)) {return this.probe(PARALLEL_MCP_URL, {diff --git a/server/src/providers/serpsearch.ts b/server/src/providers/serpsearch.tsindex 7cdfd551..60310fa0 100644--- a/server/src/providers/serpsearch.ts+++ b/server/src/providers/serpsearch.ts@@ -7,10 +7,18 @@ export class SerpSearchProvider extends SearchOnlyProvider {readonly platform = 'serpsearch' as const;readonly name = 'SerpSearch';+ /** #1599: validation is an empty search, so the health pass checks a key+ * once instead of every few minutes. */+ override get supportsKeyPolling(): boolean {+ return false;+ }+async validateKey(apiKey: string): Promise<KeyValidationResult> {// Authentication runs before query validation: a valid key gets 400 with// quota headers, an invalid key gets 401. No query means no credit spent.// Live checked against both cases; do not turn this into a real search.+ // Never poll this (#1599): SerpSearch revoked a free account over empty+ // searches sent every 5 minutes. supportsKeyPolling keeps it to one per key.const res = await this.fetchWithTimeout(`${SERPSEARCH_BASE_URL}/search`, {method: 'GET', redirect: 'error', headers: { Authorization: `Bearer ${apiKey}` },}, 10_000, { timeoutBounds: 'request' });diff --git a/server/src/routes/health.ts b/server/src/routes/health.tsindex 0daea61e..3e19c279 100644--- a/server/src/routes/health.ts+++ b/server/src/routes/health.ts@@ -74,9 +74,9 @@ healthRouter.post('/check/:keyId', async (req: Request, res: Response) => {// Check all keys. Forced: someone pressed the button and wants an answer about// every key now, so the scheduled pass' recency skip and provider spacing (#553)-// don't apply.+// don't apply, and providers that must not be polled (#1599) are checked too.healthRouter.post('/check-all', async (_req: Request, res: Response) => {- await checkAllKeys({ force: true });+ await checkAllKeys({ force: true, manual: true });res.json({ success: true });});diff --git a/server/src/services/health.ts b/server/src/services/health.tsindex 12a785b8..b1338f71 100644--- a/server/src/services/health.ts+++ b/server/src/services/health.ts@@ -33,6 +33,11 @@ const CHECK_INTERVAL_JITTER = 0.2;// short interval can never skip a whole pass' worth of keys.export const RECENT_CHECK_SKIP_MS = 3.5 * 60 * 1000;+// #1599: how often the scheduled pass re-asks about a key parked at 'error' on+// a provider that must not be polled (supportsKeyPolling === false). Healthy+// and invalid keys on those providers are never re-validated on a schedule.+export const NO_POLL_ERROR_REPROBE_MS = 60 * 60 * 1000;+// Wall-clock ceiling for one pass. Per-provider spacing is compressed rather// than allowed to push a pass past this, so a large fleet still finishes well// inside the interval it is scheduled on and the dashboard never shows@@ -381,6 +386,9 @@ export async function probeKeyValidity(keyId: number): Promise<KeyProbeOutcome>// #1459: no probe for a provider that forbids them; the cooldown simply// runs out, as it would after an inconclusive probe.if (provider.supportsKeyValidation === false) return 'error';+ // #1599: the probe would be the same empty search the health pass no+ // longer sends on a schedule; let the cooldown run out instead.+ if (provider.supportsKeyPolling === false) return 'error';const apiKey = decrypt(row.encrypted_key, row.iv, row.auth_tag);// Same reasoning as checkKeyHealth: probe through the key's own proxy (#590).@@ -446,6 +454,10 @@ export interface HealthPassOptions {* Used by the dashboard's "check all" button and the post-wake re-probe,* where the point is an immediate, complete picture. */force?: boolean;+ /** Someone pressed "Check all": also validate keys on providers that must+ * not be polled (#1599). The post-wake re-probe is forced but automatic, so+ * it leaves them alone. */+ manual?: boolean;/** Test seams: injectable clock, sleep, probe and pool size, mirroring the* cooldown-probe pass so a pacing test needs no real timers. */now?: () => number;@@ -526,6 +538,16 @@ async function runHealthPass(opts: HealthPassOptions): Promise<HealthPassResult>const skippedKeyIds: number[] = [];const skipMs = opts.force ? 0 : getValidationRateLimitSkipMs();const due = rows.filter(row => {+ // #1599: a provider whose key check is an empty search gets one check per+ // new key, not one every pass. Applies to forced automatic passes too.+ if (!opts.manual && resolveProvider(row.platform as Platform, row.base_url)?.supportsKeyPolling === false) {+ const floorMs = row.status === 'error' ? NO_POLL_ERROR_REPROBE_MS : Infinity;+ if (row.age_ms !== null && row.age_ms < floorMs) {+ skippedKeyIds.push(row.id);+ return false;+ }+ return true;+ }if (opts.force) return true;// A key the provider just rate-limited stays out until the skip window// passes — even one parked at 'error'. A 429 is fresher, more specific