Skip to content

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(serpsearch): never send a key-check request (#1599) (#1635)

Tashfeen5f4b596c3381
diff --git a/docs/BEATAPI-SERPSEARCH.md b/docs/BEATAPI-SERPSEARCH.md
index 42d6db5d..d95288e1 100644
--- a/docs/BEATAPI-SERPSEARCH.md
+++ b/docs/BEATAPI-SERPSEARCH.md
@@ -33,12 +33,12 @@ Sources: [decision API](https://docs.beatapi.io/decisions),
convert image/video search into generation models.
- The Free plan shares 1,000 requests/month across endpoints, without a card;
live response headers confirmed the allowance and one request/second.
-- Key validation omits `query`. A valid key returns a missing-query HTTP 400
- with quota headers, an invalid key returns 401. Both were live checked, and
- the 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.
+- SerpSearch keys are never validated with a request (#1599). It has no
+ account or usage endpoint, so the only possible check was a search with no
+ query. SerpSearch revoked free accounts over those empty searches, and its
+ maintainer asked that we send none. A new key shows as unchecked until its
+ first real search succeeds. A 401/403 on a real search benches the key.
+ "Check now" sends nothing for SerpSearch.
- 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__/providers/beatapi-serpsearch.test.ts b/server/src/__tests__/providers/beatapi-serpsearch.test.ts
index 7b71022c..4635c69a 100644
--- a/server/src/__tests__/providers/beatapi-serpsearch.test.ts
+++ b/server/src/__tests__/providers/beatapi-serpsearch.test.ts
@@ -8,21 +8,34 @@ const json = (body: unknown, status = 200, headers = {}) => new Response(JSON.st
afterEach(() => vi.restoreAllMocks());
describe.each([
- { platform: 'beatapi' as const, provider: new BeatApiProvider(), url: 'https://api.beatapi.io/v1/models' },
- { platform: 'serpsearch' as const, provider: new SerpSearchProvider(), url: 'https://api.serpsearch.com/api/v1/search' },
-])('$platform credentials', ({ platform, provider, url }) => {
+ { platform: 'beatapi' as const, provider: new BeatApiProvider() },
+ { platform: 'serpsearch' as const, provider: new SerpSearchProvider() },
+])('$platform credentials', ({ platform, provider }) => {
it('registers and imports explicitly named keys', () => {
expect(getProvider(platform)).toBeInstanceOf(provider.constructor);
expect(parseKeysFromFile(`${platform.toUpperCase()}_API_KEY=unit-test-only`, 'keys.env').keys[0].platform).toBe(platform);
expect(AUTH_JSON_PROVIDER_MAP[platform]).toBe(platform);
});
+ it('rejects ordinary and streaming chat without making a request', async () => {
+ const fetch = vi.spyOn(global, 'fetch');
+ const base = getProvider(platform)!;
+ await expect(base.chatCompletion('k', [], 'm')).rejects.toMatchObject({ status: 422 });
+ await expect(base.streamChatCompletion('k', [], 'm').next()).rejects.toMatchObject({ status: 422 });
+ expect(fetch).not.toHaveBeenCalled();
+ });
+});
+
+it.each([null, {}, { data: {} }, { data: [], error: 'failure' }])('rejects malformed BeatAPI lists', async body => {
+ vi.spyOn(global, 'fetch').mockResolvedValue(json(body));
+ await expect(new BeatApiProvider().validateKey('k')).rejects.toMatchObject({ status: 502 });
+});
+
+describe('BeatAPI key validation', () => {
it('validates without spending search or inference quota', async () => {
- const fetch = vi.spyOn(global, 'fetch').mockResolvedValue(platform === 'beatapi'
- ? json({ data: [{ id: 'jev-1.14-free' }] })
- : new Response('Failed to deserialize query string: missing field `query`', { status: 400, headers: { 'x-quota-limit': '1000' } }));
- expect(await provider.validateKey('unit-test-key')).toBe(true);
- expect(fetch.mock.calls[0][0]).toBe(url);
+ const fetch = vi.spyOn(global, 'fetch').mockResolvedValue(json({ data: [{ id: 'jev-1.14-free' }] }));
+ expect(await new BeatApiProvider().validateKey('unit-test-key')).toBe(true);
+ expect(fetch.mock.calls[0][0]).toBe('https://api.beatapi.io/v1/models');
const init = fetch.mock.calls[0][1]!;
expect(init.method).toBe('GET');
expect(init.body).toBeUndefined();
@@ -32,32 +45,23 @@ describe.each([
it.each([401, 403])('rejects HTTP %s authentication failures', async status => {
vi.spyOn(global, 'fetch').mockResolvedValue(json({ error: { message: 'Invalid API key' } }, status));
- await expect(provider.validateKey('invalid')).resolves.toMatchObject({ valid: false });
+ await expect(new BeatApiProvider().validateKey('invalid')).resolves.toMatchObject({ valid: false });
});
it.each([429, 500, 503])('keeps HTTP %s inconclusive with retry hints', async status => {
vi.spyOn(global, 'fetch').mockResolvedValue(json({}, status, { 'Retry-After': '60' }));
- await expect(provider.validateKey('unit-test-key')).rejects.toMatchObject({ status, retryAfterMs: 60_000 });
+ await expect(new BeatApiProvider().validateKey('unit-test-key')).rejects.toMatchObject({ status, retryAfterMs: 60_000 });
});
- it('rejects ordinary and streaming chat without making a request', async () => {
- const fetch = vi.spyOn(global, 'fetch');
- const base = getProvider(platform)!;
- await expect(base.chatCompletion('k', [], 'm')).rejects.toMatchObject({ status: 422 });
- await expect(base.streamChatCompletion('k', [], 'm').next()).rejects.toMatchObject({ status: 422 });
- expect(fetch).not.toHaveBeenCalled();
- });
-});
-
-it.each([null, {}, { data: {} }, { data: [], error: 'failure' }])('rejects malformed BeatAPI lists', async body => {
- vi.spyOn(global, 'fetch').mockResolvedValue(json(body));
- await expect(new BeatApiProvider().validateKey('k')).rejects.toMatchObject({ status: 502 });
});
-it.each([
- { body: 'missing field `query`', headers: {} },
- { body: 'unrelated error', headers: { 'x-quota-limit': '1000' } },
-])('does not accept unauthenticated or unrelated SerpSearch 400s', async ({ body, headers }) => {
- vi.spyOn(global, 'fetch').mockResolvedValue(new Response(body, { status: 400, headers }));
- await expect(new SerpSearchProvider().validateKey('k')).rejects.toMatchObject({ status: 400 });
+// #1599: SerpSearch's maintainer asked for no empty-query requests at all, and
+// it has no other endpoint that proves a key, so nothing validates its keys.
+it('never sends a request to validate a SerpSearch key', async () => {
+ const fetch = vi.spyOn(global, 'fetch');
+ const provider = new SerpSearchProvider();
+ expect(provider.supportsKeyValidation).toBe(false);
+ expect(provider.supportsKeyPolling).toBe(false);
+ await expect(provider.validateKey()).rejects.toThrow(/no request sent/);
+ expect(fetch).not.toHaveBeenCalled();
});
diff --git a/server/src/__tests__/services/beatapi-serpsearch.test.ts b/server/src/__tests__/services/beatapi-serpsearch.test.ts
index 1cd7cc24..32c6b9ae 100644
--- a/server/src/__tests__/services/beatapi-serpsearch.test.ts
+++ b/server/src/__tests__/services/beatapi-serpsearch.test.ts
@@ -5,6 +5,7 @@ import { runDecision, DECISION_PLATFORMS } from '../../services/decision.js';
import { runSearch, SEARCH_ENGINE_PLATFORMS } from '../../services/search.js';
import { clearAllCooldowns } from '../../services/ratelimit.js';
import { applyCatalog } from '../../services/catalog-sync.js';
+import { checkAllKeys, checkKeyHealth, probeKeyValidity } from '../../services/health.js';
const json = (body: unknown, status = 200, headers = {}) => new Response(JSON.stringify(body), { status, headers });
const request = { state: 'Invoice charged twice', questions: { billing: { type: 'noul' as const, instructions: 'Billing issue?' } } };
@@ -53,6 +54,27 @@ describe('BeatAPI decision dispatch', () => {
});
});
+// #1599: SerpSearch's maintainer asked for no empty-query requests, so no
+// health path may send one, and a real search is what marks the key working.
+it('never sends a request to check a SerpSearch key, and a real search marks it healthy', async () => {
+ seed('serpsearch', 'serpsearch-search', 'search');
+ const db = getDb();
+ db.prepare("UPDATE api_keys SET status = 'unknown' WHERE platform = 'serpsearch'").run();
+ const { id } = db.prepare("SELECT id FROM api_keys WHERE platform = 'serpsearch'").get() as { id: number };
+ const fetch = vi.spyOn(global, 'fetch');
+ vi.spyOn(console, 'log').mockImplementation(() => {});
+
+ expect(await checkKeyHealth(id)).toBe('unknown');
+ await checkAllKeys({ force: true, manual: true });
+ expect(await probeKeyValidity(id)).toBe('error');
+ expect(fetch).not.toHaveBeenCalled();
+
+ fetch.mockResolvedValue(json({ organic_results: [{ title: 'Cats', url: 'https://example.com/cats', description: 'Cats.' }] }));
+ await runSearch('cats', { engine: 'serpsearch-search', maxResults: 1 });
+ expect(String(fetch.mock.calls[0][0])).toContain('query=cats');
+ expect(db.prepare('SELECT status FROM api_keys WHERE id = ?').get(id)).toEqual({ status: 'healthy' });
+});
+
describe('SerpSearch dispatch', () => {
beforeEach(() => seed('serpsearch', 'serpsearch-search', 'search'));
diff --git a/server/src/providers/base.ts b/server/src/providers/base.ts
index 5d479e8a..1582575f 100644
--- a/server/src/providers/base.ts
+++ b/server/src/providers/base.ts
@@ -288,10 +288,10 @@ export abstract class BaseProvider {
/** 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
+ * request to its billed endpoint (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. SerpSearch revoked free accounts over them
+ * and now sends no key check at all (supportsKeyValidation === false). 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. */
diff --git a/server/src/providers/serpsearch.ts b/server/src/providers/serpsearch.ts
index 60310fa0..8ca841ea 100644
--- a/server/src/providers/serpsearch.ts
+++ b/server/src/providers/serpsearch.ts
@@ -1,4 +1,4 @@
-import { providerHttpError, type KeyValidationResult } from './base.js';
+import type { KeyValidationResult } from './base.js';
import { SearchOnlyProvider } from './search-only.js';
export const SERPSEARCH_BASE_URL = 'https://api.serpsearch.com/api/v1';
@@ -7,27 +7,23 @@ 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. */
+ /** #1599: SerpSearch has no account or usage endpoint, so the only possible
+ * key check is a search with no query, and its maintainer asked that we send
+ * none at all (empty searches flag accounts as bots). No health pass, cooldown
+ * probe or "Check now" validates a SerpSearch key: it stays 'unknown' until a
+ * real search succeeds (markKeyHealthyFromRequest), and a 401/403 on a real
+ * search benches it like any other search key. */
+ override get supportsKeyValidation(): boolean {
+ return false;
+ }
+
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' });
- if ([401, 403].includes(res.status)) return this.validationResult(res);
- const quota = res.headers.get('x-quota-limit');
- if (res.status === 400 && quota !== null && /^\d+$/.test(quota)) {
- const text = await res.text();
- if (/missing field [`'"]?query|INVALID_QUERY/i.test(text)) return true;
- }
- throw providerHttpError(res, 'SerpSearch key validation is inconclusive');
+ async validateKey(): Promise<KeyValidationResult> {
+ // Never turn this into a request: an empty search is what got accounts
+ // revoked (#1599), and a real search would spend the user's credits.
+ throw new Error('SerpSearch keys are not validated with a request; the first real search confirms the key (no request sent)');
}
}
diff --git a/server/src/routes/keys.ts b/server/src/routes/keys.ts
index a096836c..2a962074 100644
--- a/server/src/routes/keys.ts
+++ b/server/src/routes/keys.ts
@@ -469,7 +469,8 @@ keysRouter.get('/', (_req: Request, res: Response) => {
// unexplained "unchecked". modelsAvailable says whether this install has
// any of the provider's models to serve that first request with.
autoHealthCheck: resolveProvider(row.platform)?.supportsKeyValidation !== false,
- ...(resolveProvider(row.platform)?.supportsKeyValidation === false
+ // Search keys serve engines, not models, so they never count as missing models.
+ ...(resolveProvider(row.platform)?.supportsKeyValidation === false && !isSearchPlatform(row.platform)
? { modelsAvailable: modelCountFor(row.platform) }
: {}),
// Lets the export dialog count exactly what the export will write.