Sync from felladrin/MiniSearch@f8cb3e1 (part 2)

server/fallbackSearchService.test.ts

@@ -0,0 +1,835 @@
+import debug from "debug";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  type MockedFunction,
+  vi,
+} from "vitest";
+import {
+  fetchFallbackTextResults,
+  isSearchFallbackEnabled,
+} from "./fallbackSearchService";
+
+function createMockResponse(
+  body: string,
+  {
+    status,
+    ok = status === undefined ? true : status >= 200 && status < 300,
+    headers = {},
+    contentType = "application/json",
+    unreadBody = null,
+  }: {
+    ok?: boolean;
+    status?: number;
+    headers?: Record<string, string>;
+    contentType?: string;
+    unreadBody?: { cancel: () => Promise<void> } | null;
+  } = {},
+): Response {
+  const resolvedStatus = status ?? (ok ? 200 : 503);
+  return {
+    ok,
+    status: resolvedStatus,
+    statusText: ok ? "OK" : "Error",
+    headers: new Headers({ "content-type": contentType, ...headers }),
+    redirected: false,
+    type: "basic" as ResponseType,
+    url: "http://test.com",
+    clone: function () {
+      return this;
+    },
+    body: unreadBody,
+    bodyUsed: false,
+    arrayBuffer: () => Promise.resolve(new ArrayBuffer(0)),
+    blob: () => Promise.resolve(new Blob()),
+    formData: () => Promise.resolve(new FormData()),
+    json: () => Promise.resolve(JSON.parse(body)),
+    text: () => Promise.resolve(body),
+  } as unknown as Response;
+}
+
+const SESSION_ID = "session-from-step-one";
+const QUERY = "borogoves outgrabe mimsy-42";
+// The module's own cap on the exchange; every test that is not about the
+// caller's budget passes it as the budget.
+const FULL_BUDGET_MS = 15_000;
+
+const INITIALIZE_REPLY = JSON.stringify({
+  jsonrpc: "2.0",
+  id: 1,
+  result: { protocolVersion: "2025-06-18", capabilities: {}, serverInfo: {} },
+});
+
+const NOTIFICATION_ACCEPTED = "";
+
+function toolReply(document: unknown): string {
+  return JSON.stringify({
+    jsonrpc: "2.0",
+    id: 2,
+    result: {
+      content: [{ type: "text", text: JSON.stringify(document) }],
+    },
+  });
+}
+
+function sseReply(message: string): string {
+  return `event: message\ndata: ${message}\n\n`;
+}
+
+function documentWith(results: unknown[]): string {
+  return toolReply({ search_id: "search-1", results });
+}
+
+const EXCERPT =
+  "The opening sentence of a very long excerpt that has to survive the filter. alpha bravo charlie delta echo foxtrot golf hotel india juliet kilo lima mike november oscar papa quebec";
+
+const LONG_EXCERPT = `${EXCERPT} romeo sierra tango uniform victor whiskey xray yankee zulu alpha bravo charlie delta echo foxtrot golf hotel india juliet kilo lima mike november oscar papa quebec romeo sierra tango uniform victor whiskey xray yankee zulu`;
+
+let originalFetch: typeof fetch;
+let fetchMock: MockedFunction<typeof fetch>;
+
+const originalEnabled = process.env.SEARCH_FALLBACK_ENABLED;
+const originalApiKey = process.env.SEARCH_FALLBACK_API_KEY;
+
+beforeEach(() => {
+  delete process.env.SEARCH_FALLBACK_ENABLED;
+  delete process.env.SEARCH_FALLBACK_API_KEY;
+  originalFetch = global.fetch;
+  fetchMock = vi.fn() as unknown as MockedFunction<typeof fetch>;
+  global.fetch = fetchMock;
+});
+
+afterEach(() => {
+  global.fetch = originalFetch;
+  if (originalEnabled === undefined) delete process.env.SEARCH_FALLBACK_ENABLED;
+  else process.env.SEARCH_FALLBACK_ENABLED = originalEnabled;
+  if (originalApiKey === undefined) delete process.env.SEARCH_FALLBACK_API_KEY;
+  else process.env.SEARCH_FALLBACK_API_KEY = originalApiKey;
+  vi.restoreAllMocks();
+});
+
+/** Answers the three requests in order with the given tool-call reply. */
+function mockExchange(
+  toolBody: string,
+  {
+    initializeBody = INITIALIZE_REPLY,
+    initializeContentType = "application/json",
+    toolContentType = "application/json",
+  }: {
+    initializeBody?: string;
+    initializeContentType?: string;
+    toolContentType?: string;
+  } = {},
+) {
+  fetchMock
+    .mockResolvedValueOnce(
+      createMockResponse(initializeBody, {
+        contentType: initializeContentType,
+        headers: { "mcp-session-id": SESSION_ID },
+      }),
+    )
+    .mockResolvedValueOnce(
+      createMockResponse(NOTIFICATION_ACCEPTED, { status: 202 }),
+    )
+    .mockResolvedValueOnce(
+      createMockResponse(toolBody, { contentType: toolContentType }),
+    );
+}
+
+function requestBody(index: number): {
+  jsonrpc?: string;
+  id?: number;
+  method?: string;
+  params?: {
+    name?: string;
+    arguments?: Record<string, unknown>;
+    protocolVersion?: string;
+    capabilities?: unknown;
+    clientInfo?: unknown;
+  };
+} {
+  const [, init] = fetchMock.mock.calls[index];
+  return JSON.parse(String(init?.body));
+}
+
+function requestHeaders(index: number): Record<string, string> {
+  const [, init] = fetchMock.mock.calls[index];
+  return init?.headers as Record<string, string>;
+}
+
+describe("isSearchFallbackEnabled", () => {
+  it("is off when the variable is unset", () => {
+    expect(isSearchFallbackEnabled()).toBe(false);
+  });
+
+  it("accepts 'true' and ' TRUE ' and '1'", () => {
+    process.env.SEARCH_FALLBACK_ENABLED = "true";
+    expect(isSearchFallbackEnabled()).toBe(true);
+
+    process.env.SEARCH_FALLBACK_ENABLED = " TRUE ";
+    expect(isSearchFallbackEnabled()).toBe(true);
+
+    process.env.SEARCH_FALLBACK_ENABLED = "1";
+    expect(isSearchFallbackEnabled()).toBe(true);
+  });
+
+  it("rejects a value that is not true or 1", () => {
+    process.env.SEARCH_FALLBACK_ENABLED = "yes";
+    expect(isSearchFallbackEnabled()).toBe(false);
+  });
+
+  it("reads the variable at call time", () => {
+    expect(isSearchFallbackEnabled()).toBe(false);
+    process.env.SEARCH_FALLBACK_ENABLED = "true";
+    expect(isSearchFallbackEnabled()).toBe(true);
+  });
+});
+
+describe("the three requests", () => {
+  it("runs initialize, the initialized notification and the tool call in order", async () => {
+    mockExchange(documentWith([]));
+
+    await fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS);
+
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(requestBody(0)).toEqual({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        protocolVersion: "2025-06-18",
+        capabilities: {},
+        clientInfo: { name: "MiniSearch", version: "1" },
+      },
+    });
+    expect(requestBody(1)).toEqual({
+      jsonrpc: "2.0",
+      method: "notifications/initialized",
+    });
+    expect(requestBody(2).method).toBe("tools/call");
+    expect(requestBody(2).params?.name).toBe("web_search");
+    expect(requestBody(2).params?.arguments).toEqual({
+      objective: QUERY,
+      search_queries: [QUERY],
+      session_id: expect.any(String),
+    });
+  });
+
+  it("carries the session id from step 1 onto steps 2 and 3, with the protocol version", async () => {
+    mockExchange(documentWith([]));
+
+    await fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS);
+
+    expect(requestHeaders(0)["Mcp-Session-Id"]).toBeUndefined();
+    expect(requestHeaders(0)["MCP-Protocol-Version"]).toBeUndefined();
+
+    for (const index of [1, 2]) {
+      expect(requestHeaders(index)["Mcp-Session-Id"]).toBe(SESSION_ID);
+      expect(requestHeaders(index)["MCP-Protocol-Version"]).toBe("2025-06-18");
+    }
+  });
+
+  it("sends one session id for the process, not one per search", async () => {
+    mockExchange(documentWith([]));
+    mockExchange(documentWith([]));
+
+    await fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS);
+    await fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS);
+
+    const first = requestBody(2).params?.arguments?.session_id;
+    const second = requestBody(5).params?.arguments?.session_id;
+    expect(typeof first).toBe("string");
+    expect(second).toBe(first);
+  });
+
+  it("sends the content type and accept header on every request", async () => {
+    mockExchange(documentWith([]));
+
+    await fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS);
+
+    for (let index = 0; index < 3; index++) {
+      const headers = requestHeaders(index);
+      expect(headers["Content-Type"]).toBe("application/json");
+      expect(headers.Accept).toBe("application/json, text/event-stream");
+    }
+  });
+
+  it("never sends a model name", async () => {
+    mockExchange(documentWith([]));
+
+    await fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS);
+
+    const toolCall = JSON.stringify(fetchMock.mock.calls[2][1]?.body);
+    expect(toolCall).not.toContain("model_name");
+    expect(Object.keys(requestBody(2).params?.arguments ?? {})).toEqual([
+      "objective",
+      "search_queries",
+      "session_id",
+    ]);
+  });
+
+  it("bounds all three requests with one abort signal", async () => {
+    mockExchange(documentWith([]));
+
+    await fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS);
+
+    const signals = fetchMock.mock.calls.map(([, init]) => init?.signal);
+    expect(signals[0]).toBeInstanceOf(AbortSignal);
+    expect(signals[1]).toBe(signals[0]);
+    expect(signals[2]).toBe(signals[0]);
+  });
+
+  it("hands the exchange the caller's budget, capped at its own", async () => {
+    mockExchange(documentWith([]));
+    mockExchange(documentWith([]));
+    const timeoutSpy = vi.spyOn(AbortSignal, "timeout");
+
+    await fetchFallbackTextResults(QUERY, 10, 3_000);
+    await fetchFallbackTextResults(QUERY, 10, 20_000);
+
+    expect(timeoutSpy).toHaveBeenNthCalledWith(1, 3_000);
+    // A budget past the module's own 15 s is not passed on: the exchange still
+    // ends at the cap, so the caller cannot lend it more time than it allows.
+    // Restored by the afterEach below, along with every other mock.
+    expect(timeoutSpy).toHaveBeenNthCalledWith(2, 15_000);
+  });
+
+  it("discards the unread bodies of the first two responses", async () => {
+    const cancelInitialize = vi.fn().mockResolvedValue(undefined);
+    const cancelInitialized = vi.fn().mockResolvedValue(undefined);
+    fetchMock
+      .mockResolvedValueOnce(
+        createMockResponse(INITIALIZE_REPLY, {
+          headers: { "mcp-session-id": SESSION_ID },
+          unreadBody: { cancel: cancelInitialize },
+        }),
+      )
+      .mockResolvedValueOnce(
+        createMockResponse(NOTIFICATION_ACCEPTED, {
+          status: 202,
+          unreadBody: { cancel: cancelInitialized },
+        }),
+      )
+      .mockResolvedValueOnce(createMockResponse(documentWith([])));
+
+    await fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS);
+
+    // An unread body keeps its socket out of the connection pool until it is
+    // collected, so the two replies nobody reads have to be dropped.
+    expect(cancelInitialize).toHaveBeenCalledTimes(1);
+    expect(cancelInitialized).toHaveBeenCalledTimes(1);
+  });
+
+  it("discards an unread body before throwing on a rejected initialize", async () => {
+    const cancelInitialize = vi.fn().mockResolvedValue(undefined);
+    fetchMock.mockResolvedValueOnce(
+      createMockResponse("", {
+        status: 500,
+        unreadBody: { cancel: cancelInitialize },
+      }),
+    );
+
+    await expect(
+      fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS),
+    ).rejects.toThrow("did not open a session (status 500)");
+    expect(cancelInitialize).toHaveBeenCalledTimes(1);
+  });
+
+  it("omits the Bearer header when no key is configured", async () => {
+    mockExchange(documentWith([]));
+
+    await fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS);
+
+    for (let index = 0; index < 3; index++) {
+      expect(requestHeaders(index).Authorization).toBeUndefined();
+    }
+  });
+
+  it("sends the Bearer header on every request when a key is configured", async () => {
+    process.env.SEARCH_FALLBACK_API_KEY = "sk-fallback-key";
+    mockExchange(documentWith([]));
+
+    await fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS);
+
+    for (let index = 0; index < 3; index++) {
+      expect(requestHeaders(index).Authorization).toBe(
+        "Bearer sk-fallback-key",
+      );
+    }
+  });
+
+  it("treats a whitespace-only key as no key", async () => {
+    process.env.SEARCH_FALLBACK_API_KEY = "   ";
+    mockExchange(documentWith([]));
+
+    await fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS);
+
+    expect(requestHeaders(0).Authorization).toBeUndefined();
+  });
+});
+
+describe("reading the reply", () => {
+  it("parses an application/json reply", async () => {
+    mockExchange(
+      toolReply({
+        search_id: "search-1",
+        results: [
+          {
+            url: "https://example.com/json",
+            title: "JSON title",
+            excerpts: [
+              `${"json ".repeat(12).trim()} an excerpt long enough to be kept by the length filter.`,
+            ],
+          },
+        ],
+      }),
+    );
+
+    const results = await fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS);
+
+    expect(results).toHaveLength(1);
+    expect(results[0][0]).toBe("JSON title");
+    expect(results[0][2]).toBe("https://example.com/json");
+  });
+
+  it("parses a text/event-stream reply and skips blocks that are not JSON", async () => {
+    mockExchange(
+      `: keep-alive\n\n${sseReply(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          id: 2,
+          result: {
+            content: [{ type: "text", text: JSON.stringify({ results: [] }) }],
+          },
+        }),
+      )}event: ping\ndata: not json\n\n`,
+      { toolContentType: "text/event-stream" },
+    );
+
+    await expect(
+      fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS),
+    ).resolves.toEqual([]);
+  });
+
+  it("parses an SSE initialize reply", async () => {
+    mockExchange(documentWith([]), {
+      initializeBody: sseReply(INITIALIZE_REPLY),
+      initializeContentType: "text/event-stream",
+    });
+
+    await expect(
+      fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS),
+    ).resolves.toEqual([]);
+  });
+
+  it("returns an empty array when nothing usable comes back", async () => {
+    mockExchange(documentWith([]));
+
+    await expect(
+      fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS),
+    ).resolves.toEqual([]);
+  });
+});
+
+describe("mapping a result", () => {
+  const run = async (results: unknown[], limit = 10) => {
+    mockExchange(documentWith(results));
+    return fetchFallbackTextResults(QUERY, limit, FULL_BUDGET_MS);
+  };
+
+  it("drops navigation crumbs and keeps the paragraph", async () => {
+    const results = await run([
+      {
+        url: "https://example.com/guide",
+        title: "Guide",
+        excerpts: [
+          "Skip to main content",
+          "Home > Docs > Search > Guide",
+          EXCERPT,
+        ],
+      },
+    ]);
+
+    expect(results).toEqual([["Guide", EXCERPT, "https://example.com/guide"]]);
+  });
+
+  it("strips leading markdown markers", async () => {
+    const results = await run([
+      {
+        url: "https://example.com/markers",
+        title: "Markers",
+        excerpts: [`# ${EXCERPT}`],
+      },
+    ]);
+
+    expect(results[0][1]).toBe(EXCERPT);
+  });
+
+  it("reduces a markdown link to its text", async () => {
+    const results = await run([
+      {
+        url: "https://example.com/link",
+        title: "Link",
+        excerpts: [
+          `See the [reference page](https://example.com/reference) and then ${EXCERPT}`,
+        ],
+      },
+    ]);
+
+    expect(results[0][1]).toBe(`See the reference page and then ${EXCERPT}`);
+  });
+
+  it("joins excerpts and collapses the whitespace between them", async () => {
+    const first = `The first excerpt paragraph is long enough to be kept intact.`;
+    const second = `The second excerpt paragraph is long enough to be kept intact.`;
+    const results = await run([
+      {
+        url: "https://example.com/join",
+        title: "Join",
+        excerpts: [`${first}\n\n${second}`, "Short"],
+      },
+    ]);
+
+    expect(results[0][1]).toBe(`${first} ${second}`);
+  });
+
+  it("cuts at 400 characters, at a word boundary, and marks the cut", async () => {
+    expect(LONG_EXCERPT.length).toBeGreaterThan(400);
+
+    const results = await run([
+      {
+        url: "https://example.com/long",
+        title: "Long",
+        excerpts: [LONG_EXCERPT],
+      },
+    ]);
+
+    const snippet = results[0][1];
+    expect(snippet.endsWith("…")).toBe(true);
+    expect(snippet.length).toBeLessThanOrEqual(400);
+    const kept = snippet.slice(0, -1);
+    // The kept text is a prefix of the source, and the source continues with a
+    // space, so the cut landed between two words rather than inside one.
+    expect(LONG_EXCERPT.startsWith(kept)).toBe(true);
+    expect(LONG_EXCERPT[kept.length]).toBe(" ");
+  });
+
+  it("leaves a snippet that fits untouched", async () => {
+    expect(EXCERPT.length).toBeLessThanOrEqual(400);
+
+    const results = await run([
+      { url: "https://example.com/short", title: "Short", excerpts: [EXCERPT] },
+    ]);
+
+    expect(results[0][1]).toBe(EXCERPT);
+    expect(results[0][1]).not.toContain("…");
+  });
+
+  it("drops a result with no url, a null or empty title, or an empty snippet", async () => {
+    const results = await run([
+      { title: "No url", excerpts: [EXCERPT] },
+      {
+        url: "https://example.com/null-title",
+        title: null,
+        excerpts: [EXCERPT],
+      },
+      {
+        url: "https://example.com/empty-title",
+        title: "   ",
+        excerpts: [EXCERPT],
+      },
+      {
+        url: "https://example.com/no-snippet",
+        title: "No snippet",
+        excerpts: [],
+      },
+      {
+        url: "https://example.com/crumb-only",
+        title: "Crumb only",
+        excerpts: ["Skip to main content"],
+      },
+      { url: "https://example.com/kept", title: "Kept", excerpts: [EXCERPT] },
+    ]);
+
+    expect(results).toEqual([["Kept", EXCERPT, "https://example.com/kept"]]);
+  });
+
+  it("drops a result whose url or title is not a string", async () => {
+    const results = await run([
+      { url: 42, title: "Number url", excerpts: [EXCERPT] },
+      { url: null, title: "Null url", excerpts: [EXCERPT] },
+      {
+        url: "https://example.com/number-title",
+        title: 7,
+        excerpts: [EXCERPT],
+      },
+      null,
+      { url: "https://example.com/kept", title: "Kept", excerpts: [EXCERPT] },
+    ]);
+
+    // One malformed entry must not take the rest of the search down with it.
+    expect(results).toEqual([["Kept", EXCERPT, "https://example.com/kept"]]);
+  });
+
+  it("drops duplicate urls in the endpoint's order", async () => {
+    const results = await run([
+      { url: "https://example.com/dup", title: "First", excerpts: [EXCERPT] },
+      {
+        url: "https://example.com/other",
+        title: "Second",
+        excerpts: [EXCERPT],
+      },
+      { url: "https://example.com/dup", title: "Third", excerpts: [EXCERPT] },
+    ]);
+
+    expect(results.map(([title]) => title)).toEqual(["First", "Second"]);
+  });
+
+  it("keeps the endpoint's relevance order", async () => {
+    const results = await run([
+      { url: "https://example.com/1", title: "One", excerpts: [EXCERPT] },
+      { url: "https://example.com/2", title: "Two", excerpts: [EXCERPT] },
+      { url: "https://example.com/3", title: "Three", excerpts: [EXCERPT] },
+    ]);
+
+    expect(results.map(([title]) => title)).toEqual(["One", "Two", "Three"]);
+  });
+
+  it("applies the limit", async () => {
+    const results = await run(
+      [
+        { url: "https://example.com/1", title: "One", excerpts: [EXCERPT] },
+        { url: "https://example.com/2", title: "Two", excerpts: [EXCERPT] },
+        { url: "https://example.com/3", title: "Three", excerpts: [EXCERPT] },
+      ],
+      2,
+    );
+
+    expect(results.map(([title]) => title)).toEqual(["One", "Two"]);
+  });
+});
+
+describe("failures", () => {
+  it("throws when the tool call is not 2xx", async () => {
+    const cancel = vi.fn(async () => undefined);
+    fetchMock.mockResolvedValueOnce(
+      createMockResponse(INITIALIZE_REPLY, {
+        headers: { "mcp-session-id": SESSION_ID },
+      }),
+    );
+    fetchMock.mockResolvedValueOnce(
+      createMockResponse(NOTIFICATION_ACCEPTED, { status: 202 }),
+    );
+    fetchMock.mockResolvedValueOnce(
+      createMockResponse("bad", { status: 502, unreadBody: { cancel } }),
+    );
+
+    await expect(
+      fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS),
+    ).rejects.toThrow("The fallback search tool call failed with status 502");
+    // An unread body keeps undici's socket out of the pool until it is
+    // garbage-collected, so the non-2xx path has to discard it like the two
+    // paths above it; dropping that line fails here.
+    expect(cancel).toHaveBeenCalledTimes(1);
+  });
+
+  it("throws when initialize does not open a session", async () => {
+    fetchMock.mockResolvedValueOnce(createMockResponse(INITIALIZE_REPLY));
+
+    await expect(
+      fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS),
+    ).rejects.toThrow("did not open a session (status 200)");
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("throws on a JSON-RPC error and keeps the endpoint's message out of it", async () => {
+    fetchMock.mockResolvedValueOnce(
+      createMockResponse(INITIALIZE_REPLY, {
+        headers: { "mcp-session-id": SESSION_ID },
+      }),
+    );
+    fetchMock.mockResolvedValueOnce(
+      createMockResponse(NOTIFICATION_ACCEPTED, { status: 202 }),
+    );
+    fetchMock.mockResolvedValueOnce(
+      createMockResponse(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          id: 2,
+          error: { code: -32601, message: "SECRET UPSTREAM TEXT" },
+        }),
+      ),
+    );
+
+    const rejection = await fetchFallbackTextResults(
+      QUERY,
+      10,
+      FULL_BUDGET_MS,
+    ).catch((error: unknown) => error);
+    // The whole message is fixed text plus the code: an upstream message is
+    // free-form text from a third party and must not travel any further.
+    expect(rejection).toBeInstanceOf(Error);
+    expect((rejection as Error).message).toBe(
+      "The fallback search endpoint returned a JSON-RPC error (code -32601)",
+    );
+    expect(String(rejection)).not.toContain("SECRET UPSTREAM TEXT");
+  });
+
+  it("keeps a non-numeric JSON-RPC code out of the message", async () => {
+    fetchMock.mockResolvedValueOnce(
+      createMockResponse(INITIALIZE_REPLY, {
+        headers: { "mcp-session-id": SESSION_ID },
+      }),
+    );
+    fetchMock.mockResolvedValueOnce(
+      createMockResponse(NOTIFICATION_ACCEPTED, { status: 202 }),
+    );
+    fetchMock.mockResolvedValueOnce(
+      createMockResponse(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          id: 2,
+          error: { code: "SECRET", message: "SECRET UPSTREAM TEXT" },
+        }),
+      ),
+    );
+
+    const rejection = await fetchFallbackTextResults(
+      QUERY,
+      10,
+      FULL_BUDGET_MS,
+    ).catch((error: unknown) => error);
+    // A code is upstream data like the message is, so only a number may be
+    // carried into the thrown error.
+    expect(rejection).toBeInstanceOf(Error);
+    expect((rejection as Error).message).toBe(
+      "The fallback search endpoint returned a JSON-RPC error",
+    );
+    expect(String(rejection)).not.toContain("SECRET");
+  });
+
+  it("throws when the result is marked as an error", async () => {
+    mockExchange(
+      JSON.stringify({
+        jsonrpc: "2.0",
+        id: 2,
+        result: {
+          isError: true,
+          content: [{ type: "text", text: "upstream refused" }],
+        },
+      }),
+    );
+
+    await expect(
+      fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS),
+    ).rejects.toThrow("reported the search as failed");
+  });
+
+  it("throws when the tool output is not JSON", async () => {
+    mockExchange(
+      JSON.stringify({
+        jsonrpc: "2.0",
+        id: 2,
+        result: { content: [{ type: "text", text: "<html>gateway</html>" }] },
+      }),
+    );
+
+    await expect(
+      fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS),
+    ).rejects.toThrow("tool output that is not JSON");
+  });
+
+  it("throws a fixed message when the reply itself is not JSON", async () => {
+    mockExchange("<html>gateway</html>");
+
+    const rejection = await fetchFallbackTextResults(
+      QUERY,
+      10,
+      FULL_BUDGET_MS,
+    ).catch((error: unknown) => error);
+    // A raw SyntaxError quotes the offending body, which would put the
+    // upstream response into the thrown error and then into the log.
+    expect((rejection as Error).message).toBe(
+      "The fallback search endpoint sent a reply that is not JSON",
+    );
+    expect(String(rejection)).not.toContain("<html>");
+  });
+
+  it("throws when the document has no results array", async () => {
+    mockExchange(toolReply({ search_id: "search-1" }));
+
+    await expect(
+      fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS),
+    ).rejects.toThrow("without a results array");
+  });
+
+  it("throws when the endpoint is unreachable", async () => {
+    fetchMock.mockRejectedValue(new Error("Network failure"));
+
+    await expect(
+      fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS),
+    ).rejects.toThrow("Network failure");
+  });
+});
+
+describe("privacy", () => {
+  let logLines: string[];
+  let originalLog: typeof debug.log;
+
+  beforeEach(() => {
+    logLines = [];
+    originalLog = debug.log;
+    debug.log = (...args: unknown[]) => {
+      logLines.push(args.map(String).join(" "));
+    };
+    for (const method of ["log", "info", "warn", "error", "debug"] as const) {
+      vi.spyOn(console, method).mockImplementation((...args: unknown[]) => {
+        logLines.push(args.map(String).join(" "));
+      });
+    }
+  });
+
+  afterEach(() => {
+    debug.log = originalLog;
+  });
+
+  it("never writes the query, the API key or the response text to the log", async () => {
+    process.env.SEARCH_FALLBACK_API_KEY = "sk-fallback-key";
+    mockExchange(
+      documentWith([
+        {
+          url: "https://example.com/private",
+          title: "PRIVATE RESPONSE TITLE",
+          excerpts: [
+            `PRIVATE RESPONSE EXCERPT that is long enough to be kept by the length filter and returned to the caller.`,
+          ],
+        },
+      ]),
+    );
+
+    await fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS);
+
+    // Failure paths too: they carry a fixed line plus a status or an error
+    // code, never the payload.
+    fetchMock.mockResolvedValueOnce(createMockResponse("", { status: 500 }));
+    await expect(
+      fetchFallbackTextResults(QUERY, 10, FULL_BUDGET_MS),
+    ).rejects.toThrow();
+
+    const output = logLines.join("\n");
+    for (const form of [
+      QUERY,
+      encodeURIComponent(QUERY),
+      QUERY.replaceAll(" ", "+"),
+      "PRIVATE RESPONSE TITLE",
+      "PRIVATE RESPONSE EXCERPT",
+      "sk-fallback-key",
+    ]) {
+      expect(output).not.toContain(form);
+    }
+    expect(logLines.length).toBeGreaterThan(0);
+  });
+});

server/fallbackSearchService.ts

@@ -0,0 +1,345 @@
+import { randomUUID } from "node:crypto";
+import { basename } from "node:path";
+import debug from "debug";
+
+const fileName = basename(import.meta.url);
+const printMessage = debug(fileName);
+printMessage.enabled = true;
+
+const ENDPOINT_URL = "https://search.parallel.ai/mcp";
+const MCP_PROTOCOL_VERSION = "2025-06-18";
+// Bounds the whole three-request exchange, not each request: a fallback that
+// hangs longer than this keeps the 502 the operator already gets from SearXNG
+// waiting for a second source that is only there to soften the outage.
+const FALLBACK_TIMEOUT_MS = 15_000;
+const MAX_SNIPPET_LENGTH = 400;
+// Excerpts arrive with navigation crumbs ("Skip to main content", menu items)
+// that are sentences of their own; a real excerpt paragraph never runs this
+// short, so length is the cheapest way to drop them without a stoplist.
+const MIN_SNIPPET_LINE_LENGTH = 40;
+
+// One per server process: the endpoint uses it for free-tier rate limiting and
+// one MiniSearch instance is one client, so a fresh one per request would shed
+// the rate limit instead of sharing it.
+const SESSION_ID = randomUUID();
+
+interface JsonRpcMessage {
+  id?: number;
+  error?: { code?: unknown };
+  result?: {
+    isError?: boolean;
+    content?: { type?: string; text?: string }[];
+  };
+}
+
+interface FallbackSearchResult {
+  url?: string;
+  title?: string | null;
+  publish_date?: string | null;
+  excerpts?: string[];
+}
+
+interface FallbackSearchDocument {
+  results?: FallbackSearchResult[];
+}
+
+type TextualResult = [title: string, content: string, url: string];
+
+/**
+ * Whether the operator opted into the second text-search source. Off unless
+ * `SEARCH_FALLBACK_ENABLED` is `true` or `1`, read at call time so tests can
+ * toggle it.
+ */
+export function isSearchFallbackEnabled(): boolean {
+  const value = process.env.SEARCH_FALLBACK_ENABLED?.trim().toLowerCase();
+  return value === "true" || value === "1";
+}
+
+/**
+ * Runs a text search against the fallback endpoint when SearXNG has already
+ * failed, and returns the same `[title, snippet, url]` tuples the SearXNG path
+ * produces, so the caller can rank and render them unchanged.
+ *
+ * `timeoutMs` is the time the caller can still afford, measured from its own
+ * start: the exchange is bounded by this and by the module's own cap, whichever
+ * is shorter, so a search that has already spent most of its budget on SearXNG
+ * cannot hang on here past the point where the client has given up.
+ *
+ * Throws on any failure rather than returning what it managed to collect: the
+ * caller has to decide between a degraded answer and the 502 it would have sent
+ * anyway, and it has to be able to count the decision. An empty array is the
+ * one non-throwing outcome that means the endpoint answered and nothing usable
+ * came back.
+ */
+export async function fetchFallbackTextResults(
+  query: string,
+  limit: number,
+  timeoutMs: number,
+): Promise<TextualResult[]> {
+  const apiKey = process.env.SEARCH_FALLBACK_API_KEY?.trim();
+  const signal = AbortSignal.timeout(Math.min(FALLBACK_TIMEOUT_MS, timeoutMs));
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Accept: "application/json, text/event-stream",
+    ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+  };
+
+  const initializeResponse = await fetch(ENDPOINT_URL, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        protocolVersion: MCP_PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: "MiniSearch", version: "1" },
+      },
+    }),
+    signal,
+  });
+  const sessionId = initializeResponse.headers.get("mcp-session-id");
+  // An unread body keeps undici's socket out of the pool until it is GC'd, so
+  // both outcomes have to discard it before they part ways with the response.
+  await initializeResponse.body?.cancel();
+  if (!initializeResponse.ok || !sessionId) {
+    throw new Error(
+      `The fallback search endpoint did not open a session (status ${initializeResponse.status})`,
+    );
+  }
+
+  const sessionHeaders = {
+    "Mcp-Session-Id": sessionId,
+    "MCP-Protocol-Version": MCP_PROTOCOL_VERSION,
+  };
+
+  // A notification, so there is no reply body to read: the session is only
+  // usable once the endpoint has acknowledged it, and `ok` is the whole
+  // acknowledgement.
+  const initializedResponse = await fetch(ENDPOINT_URL, {
+    method: "POST",
+    headers: { ...headers, ...sessionHeaders },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      method: "notifications/initialized",
+    }),
+    signal,
+  });
+  await initializedResponse.body?.cancel();
+  if (!initializedResponse.ok) {
+    throw new Error(
+      `The fallback search endpoint rejected the initialized notification (status ${initializedResponse.status})`,
+    );
+  }
+
+  const callResponse = await fetch(ENDPOINT_URL, {
+    method: "POST",
+    headers: { ...headers, ...sessionHeaders },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: 2,
+      method: "tools/call",
+      params: {
+        name: "web_search",
+        // No `model_name`: this is a search, not a completion, and the tool
+        // does not need a client that claims to be a model.
+        arguments: {
+          objective: query,
+          search_queries: [query],
+          session_id: SESSION_ID,
+        },
+      },
+    }),
+    signal,
+  });
+  if (!callResponse.ok) {
+    await callResponse.body?.cancel();
+    throw new Error(
+      `The fallback search tool call failed with status ${callResponse.status}`,
+    );
+  }
+
+  const document = await readSearchDocument(callResponse, 2);
+  const textualResults = mapResults(document, limit);
+  printMessage(
+    `Fallback search usable text results: ${textualResults.length} of ${document.results?.length ?? 0}.`,
+  );
+  return textualResults;
+}
+
+/**
+ * Reads the JSON-RPC reply to `requestId`. The endpoint answers either one
+ * JSON message or an SSE stream of them, and which of them belongs to this
+ * request is decided by the id, not by position: the stream can carry
+ * notifications the client never asked for.
+ */
+async function readSearchDocument(
+  response: Response,
+  requestId: number,
+): Promise<FallbackSearchDocument> {
+  const contentType = response.headers.get("content-type") ?? "";
+  const body = await response.text();
+
+  const messages = contentType.includes("text/event-stream")
+    ? parseEventStream(body)
+    : parseJsonBody(body);
+
+  const reply = messages.find((message) => message.id === requestId);
+  if (!reply) {
+    throw new Error(
+      `The fallback search endpoint sent no reply to request ${requestId}`,
+    );
+  }
+
+  // Only a numeric code: an upstream error message is free-form text from a
+  // third party, and a non-numeric code is upstream data just the same, so
+  // neither may reach the log or a thrown error.
+  if (reply.error) {
+    throw new Error(
+      typeof reply.error.code === "number"
+        ? `The fallback search endpoint returned a JSON-RPC error (code ${reply.error.code})`
+        : "The fallback search endpoint returned a JSON-RPC error",
+    );
+  }
+
+  if (reply.result?.isError) {
+    throw new Error(
+      "The fallback search endpoint reported the search as failed",
+    );
+  }
+
+  const payload = (reply.result?.content ?? [])
+    .flatMap((item) =>
+      item.type === "text" && typeof item.text === "string" ? [item.text] : [],
+    )
+    .join("\n");
+
+  try {
+    const parsed: unknown = JSON.parse(payload);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error();
+    }
+    return parsed as FallbackSearchDocument;
+  } catch {
+    throw new Error(
+      "The fallback search endpoint returned tool output that is not JSON",
+    );
+  }
+}
+
+function parseJsonBody(body: string): JsonRpcMessage[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    // A raw SyntaxError quotes the offending snippet, which would carry the
+    // upstream response into the thrown error and from there into the log.
+    throw new Error(
+      "The fallback search endpoint sent a reply that is not JSON",
+    );
+  }
+
+  if (Array.isArray(parsed)) return parsed as JsonRpcMessage[];
+  return [parsed as JsonRpcMessage];
+}
+
+/**
+ * SSE blocks are separated by a blank line and each `data:` line holds a
+ * fragment of one JSON message. A block that is not JSON is a keep-alive or an
+ * event this client did not ask for, so it is skipped rather than failing a
+ * reply that may be perfectly good.
+ */
+function parseEventStream(body: string): JsonRpcMessage[] {
+  return body.split(/\r?\n\r?\n/).flatMap((block) => {
+    const data = block
+      .split(/\r?\n/)
+      .filter((line) => line.startsWith("data:"))
+      .map((line) => line.slice("data:".length).trimStart())
+      .join("\n");
+
+    if (!data) return [];
+
+    try {
+      const parsed: unknown = JSON.parse(data);
+      if (Array.isArray(parsed)) return parsed as JsonRpcMessage[];
+      return [parsed as JsonRpcMessage];
+    } catch {
+      return [];
+    }
+  });
+}
+
+function mapResults(
+  document: FallbackSearchDocument,
+  limit: number,
+): TextualResult[] {
+  if (!Array.isArray(document.results)) {
+    throw new Error(
+      "The fallback search endpoint returned a document without a results array",
+    );
+  }
+
+  const seenUrls = new Set<string>();
+  const mapped: TextualResult[] = [];
+
+  for (const result of document.results) {
+    if (mapped.length >= limit) break;
+    // Upstream data, so one malformed entry must not fail the whole search: a
+    // result that is not an object, or whose url or title is not a string, is
+    // skipped rather than left to throw on `.trim()`.
+    if (
+      !result ||
+      typeof result !== "object" ||
+      typeof result.url !== "string" ||
+      !result.url ||
+      seenUrls.has(result.url)
+    ) {
+      continue;
+    }
+
+    const title = typeof result.title === "string" ? result.title.trim() : "";
+    if (!title) continue;
+
+    const snippet = buildSnippet(result.excerpts);
+    if (!snippet) continue;
+
+    seenUrls.add(result.url);
+    mapped.push([title, snippet, result.url]);
+  }
+
+  return mapped;
+}
+
+/**
+ * Turns the endpoint's markdown excerpts into the plain, single-line snippet
+ * the SearXNG path hands to ranking.
+ */
+function buildSnippet(excerpts: string[] | undefined): string {
+  if (!Array.isArray(excerpts) || excerpts.length === 0) return "";
+
+  const snippet = excerpts
+    .join("\n")
+    .split("\n")
+    .map(stripMarkdown)
+    .filter((line) => line.length >= MIN_SNIPPET_LINE_LENGTH)
+    .join(" ")
+    .replace(/\s+/g, " ")
+    .trim();
+
+  if (snippet.length <= MAX_SNIPPET_LENGTH) return snippet;
+
+  // Cut at a word boundary: a mid-word stump reads as a rendering bug, and the
+  // ellipsis is what tells the reader the sentence was cut, not finished.
+  const cut = snippet.slice(0, MAX_SNIPPET_LENGTH);
+  const lastSpace = cut.lastIndexOf(" ");
+  return `${(lastSpace > 0 ? cut.slice(0, lastSpace) : cut).trimEnd()}…`;
+}
+
+function stripMarkdown(line: string): string {
+  return line
+    .replace(/^(?:#{1,6}\s+|[-*+]\s+|\d+[.)]\s+|>\s+)/, "")
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .trim();
+}

server/searchEndpointServerHook.test.ts

@@ -1,6 +1,11 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
+vi.mock("./fallbackSearchService", () => ({
+  fetchFallbackTextResults: vi.fn(),
+  isSearchFallbackEnabled: vi.fn(),
+}));
+
 vi.mock("./handleTokenVerification", () => ({
   handleTokenVerification: vi.fn(),
 }));
@@ -16,6 +21,8 @@ vi.mock("./rerankerService", () => ({
 vi.mock("./searchesSinceLastRestart", () => ({
   incrementTextualSearchesSinceLastRestart: vi.fn(),
   incrementGraphicalSearchesSinceLastRestart: vi.fn(),
+  incrementSearchesServedByFallback: vi.fn(),
+  incrementSearchesFailedOnFallback: vi.fn(),
   recordSearchDuration: vi.fn(),
 }));
 
@@ -23,12 +30,18 @@ vi.mock("./webSearchService", () => ({
   fetchSearXNG: vi.fn(),
 }));
 
+import {
+  fetchFallbackTextResults,
+  isSearchFallbackEnabled,
+} from "./fallbackSearchService";
 import { handleTokenVerification } from "./handleTokenVerification";
 import { rankSearchResults } from "./rankSearchResults";
 import { getRerankerStatus } from "./rerankerService";
 import { searchEndpointServerHook } from "./searchEndpointServerHook";
 import {
   incrementGraphicalSearchesSinceLastRestart,
+  incrementSearchesFailedOnFallback,
+  incrementSearchesServedByFallback,
   incrementTextualSearchesSinceLastRestart,
   recordSearchDuration,
 } from "./searchesSinceLastRestart";
@@ -75,6 +88,11 @@ describe("searchEndpointServerHook", () => {
       async (_query, _searchType, results) =>
         results.map(([title, content, url]) => [title, content, url, 0]),
     );
+    // Off unless a test switches it on, and answered with something rather
+    // than undefined so an unexpected call fails a visible assertion instead
+    // of poisoning the results below.
+    vi.mocked(isSearchFallbackEnabled).mockReturnValue(false);
+    vi.mocked(fetchFallbackTextResults).mockResolvedValue([]);
   });
 
   it("passes through requests that aren't under /search/", async () => {
@@ -425,6 +443,255 @@ describe("searchEndpointServerHook", () => {
         JSON.stringify({ error: "Search service unavailable" }),
       );
     });
+
+    describe("text search fallback", () => {
+      const fallbackResults: [string, string, string][] = [
+        ["Fallback title", "Fallback snippet", "https://example.com/fallback"],
+      ];
+      const rankedFallbackResults: [string, string, string, number][] = [
+        [
+          "Fallback title",
+          "Fallback snippet",
+          "https://example.com/fallback",
+          0.7,
+        ],
+      ];
+
+      function failSearxng() {
+        vi.mocked(fetchSearXNG).mockRejectedValue(
+          new Error("SearXNG request failed with status 503"),
+        );
+      }
+
+      it("serves the fallback results through the normal text path", async () => {
+        vi.mocked(isSearchFallbackEnabled).mockReturnValue(true);
+        failSearxng();
+        vi.mocked(fetchFallbackTextResults).mockResolvedValue(fallbackResults);
+        vi.mocked(getRerankerStatus).mockResolvedValue(true);
+        vi.mocked(rankSearchResults).mockResolvedValue(rankedFallbackResults);
+        // A search that has just started hands the fallback the whole budget.
+        vi.spyOn(performance, "now").mockReturnValue(0);
+
+        const handler = getRegisteredHandler();
+        const response = createResponse();
+
+        await handler(
+          createRequest("/search/text?q=cats&token=abc"),
+          response,
+          vi.fn(),
+        );
+
+        expect(fetchFallbackTextResults).toHaveBeenCalledWith(
+          "cats",
+          30,
+          25_000,
+        );
+        // Reranked exactly like SearXNG results, with the top ones preserved,
+        // and then answered by the one respond block the text path has.
+        expect(rankSearchResults).toHaveBeenCalledWith(
+          "cats",
+          "text",
+          fallbackResults,
+          true,
+        );
+        expect(incrementTextualSearchesSinceLastRestart).toHaveBeenCalledTimes(
+          1,
+        );
+        expect(incrementSearchesServedByFallback).toHaveBeenCalledTimes(1);
+        expect(incrementSearchesFailedOnFallback).not.toHaveBeenCalled();
+        // The duration metric is SearXNG's; the fallback's own latency is a
+        // different thing and would be misleading under the same average.
+        expect(recordSearchDuration).not.toHaveBeenCalled();
+        expect(response.statusCode).toBe(200);
+        expect(response.end).toHaveBeenCalledWith(
+          JSON.stringify(rankedFallbackResults),
+        );
+      });
+
+      it("answers 200 with an empty list when the fallback returns nothing usable", async () => {
+        vi.mocked(isSearchFallbackEnabled).mockReturnValue(true);
+        failSearxng();
+        vi.mocked(fetchFallbackTextResults).mockResolvedValue([]);
+
+        const handler = getRegisteredHandler();
+        const response = createResponse();
+
+        await handler(
+          createRequest("/search/text?q=cats&token=abc"),
+          response,
+          vi.fn(),
+        );
+
+        // The endpoint answered, so this is a search with no results rather
+        // than an outage: the client shows the no-results alert, not the
+        // unavailable one, and the fallback still counts as served.
+        expect(response.statusCode).toBe(200);
+        expect(response.end).toHaveBeenCalledWith(JSON.stringify([]));
+        expect(incrementSearchesServedByFallback).toHaveBeenCalledTimes(1);
+        expect(incrementSearchesFailedOnFallback).not.toHaveBeenCalled();
+        expect(recordSearchDuration).not.toHaveBeenCalled();
+      });
+
+      it("skips the fallback when the search deadline has already passed", async () => {
+        vi.mocked(isSearchFallbackEnabled).mockReturnValue(true);
+        failSearxng();
+        // 0 for the search's start, then past the 25 s deadline.
+        vi.spyOn(performance, "now")
+          .mockReturnValueOnce(0)
+          .mockReturnValue(25_001);
+
+        const handler = getRegisteredHandler();
+        const response = createResponse();
+
+        await handler(
+          createRequest("/search/text?q=cats&token=abc"),
+          response,
+          vi.fn(),
+        );
+
+        // A fallback started now would answer after the client's own 30 s
+        // timeout, so it is never asked and the outage is reported the way it
+        // would have been with the feature off.
+        expect(fetchFallbackTextResults).not.toHaveBeenCalled();
+        expect(response.statusCode).toBe(502);
+        expect(response.end).toHaveBeenCalledWith(
+          JSON.stringify({ error: "Search service unavailable" }),
+        );
+        expect(incrementSearchesFailedOnFallback).toHaveBeenCalledTimes(1);
+        expect(incrementSearchesServedByFallback).not.toHaveBeenCalled();
+        expect(recordSearchDuration).not.toHaveBeenCalled();
+
+        const logged = vi.mocked(console.error).mock.calls.flat().join(" ");
+        expect(logged).toContain(
+          "the search deadline left the fallback too little time",
+        );
+        expect(logged).not.toContain("cats");
+      });
+
+      it("hands the fallback the time left, not its own full budget", async () => {
+        vi.mocked(isSearchFallbackEnabled).mockReturnValue(true);
+        failSearxng();
+        vi.mocked(fetchFallbackTextResults).mockResolvedValue([]);
+        // 0 for the search's start, then 12 s in when SearXNG gives up.
+        vi.spyOn(performance, "now")
+          .mockReturnValueOnce(0)
+          .mockReturnValue(12_000);
+
+        const handler = getRegisteredHandler();
+        const response = createResponse();
+
+        await handler(
+          createRequest("/search/text?q=cats&token=abc"),
+          response,
+          vi.fn(),
+        );
+
+        // 13 s are left of the 25 s deadline, which is under the fallback's
+        // own 15 s cap, so the search cannot outlive the client's patience.
+        expect(fetchFallbackTextResults).toHaveBeenCalledWith(
+          "cats",
+          30,
+          13_000,
+        );
+        expect(response.statusCode).toBe(200);
+      });
+
+      it("answers 502 when the fallback fails too", async () => {
+        vi.mocked(isSearchFallbackEnabled).mockReturnValue(true);
+        failSearxng();
+        vi.mocked(fetchFallbackTextResults).mockRejectedValue(
+          new Error("The fallback search tool call failed with status 502"),
+        );
+
+        const handler = getRegisteredHandler();
+        const response = createResponse();
+
+        await handler(
+          createRequest("/search/text?q=cats&token=abc"),
+          response,
+          vi.fn(),
+        );
+
+        expect(response.statusCode).toBe(502);
+        expect(response.end).toHaveBeenCalledWith(
+          JSON.stringify({ error: "Search service unavailable" }),
+        );
+        expect(incrementSearchesFailedOnFallback).toHaveBeenCalledTimes(1);
+        expect(incrementSearchesServedByFallback).not.toHaveBeenCalled();
+        expect(recordSearchDuration).not.toHaveBeenCalled();
+
+        const logged = vi.mocked(console.error).mock.calls.flat().join(" ");
+        expect(logged).toContain(
+          "The fallback search tool call failed with status 502",
+        );
+        expect(logged).not.toContain("cats");
+      });
+
+      it("answers 502 without consulting the fallback when it is switched off", async () => {
+        failSearxng();
+
+        const handler = getRegisteredHandler();
+        const response = createResponse();
+
+        await handler(
+          createRequest("/search/text?q=cats&token=abc"),
+          response,
+          vi.fn(),
+        );
+
+        expect(response.statusCode).toBe(502);
+        expect(response.end).toHaveBeenCalledWith(
+          JSON.stringify({ error: "Search service unavailable" }),
+        );
+        expect(fetchFallbackTextResults).not.toHaveBeenCalled();
+        expect(incrementSearchesServedByFallback).not.toHaveBeenCalled();
+        expect(incrementSearchesFailedOnFallback).not.toHaveBeenCalled();
+      });
+
+      it("never consults the fallback for an image search", async () => {
+        vi.mocked(isSearchFallbackEnabled).mockReturnValue(true);
+        failSearxng();
+
+        const handler = getRegisteredHandler();
+        const response = createResponse();
+
+        await handler(
+          createRequest("/search/images?q=cats&token=abc"),
+          response,
+          vi.fn(),
+        );
+
+        expect(response.statusCode).toBe(502);
+        expect(response.end).toHaveBeenCalledWith(
+          JSON.stringify({ error: "Search service unavailable" }),
+        );
+        expect(fetchFallbackTextResults).not.toHaveBeenCalled();
+        expect(incrementSearchesServedByFallback).not.toHaveBeenCalled();
+        expect(incrementSearchesFailedOnFallback).not.toHaveBeenCalled();
+      });
+
+      it("never consults the fallback when SearXNG answers", async () => {
+        vi.mocked(isSearchFallbackEnabled).mockReturnValue(true);
+        vi.mocked(fetchSearXNG).mockResolvedValue(searxngResults);
+
+        const handler = getRegisteredHandler();
+        const response = createResponse();
+
+        await handler(
+          createRequest("/search/text?q=cats&token=abc"),
+          response,
+          vi.fn(),
+        );
+
+        expect(response.statusCode).toBe(200);
+        expect(response.end).toHaveBeenCalledWith(
+          JSON.stringify(searxngResults),
+        );
+        expect(fetchFallbackTextResults).not.toHaveBeenCalled();
+        expect(incrementSearchesServedByFallback).not.toHaveBeenCalled();
+        expect(incrementSearchesFailedOnFallback).not.toHaveBeenCalled();
+      });
+    });
   });
 
   it("responds 500 when an unexpected error is thrown", async () => {

server/searchEndpointServerHook.ts

@@ -1,5 +1,9 @@
 import type { PreviewServer, ViteDevServer } from "vite";
 import { z } from "zod";
+import {
+  fetchFallbackTextResults,
+  isSearchFallbackEnabled,
+} from "./fallbackSearchService.ts";
 import { handleTokenVerification } from "./handleTokenVerification.ts";
 import { rankSearchResults } from "./rankSearchResults.ts";
 import { getRerankerStatus } from "./rerankerService.ts";
@@ -9,6 +13,8 @@ import {
 } from "./rerankingSinceLastRestart.ts";
 import {
   incrementGraphicalSearchesSinceLastRestart,
+  incrementSearchesFailedOnFallback,
+  incrementSearchesServedByFallback,
   incrementTextualSearchesSinceLastRestart,
   recordSearchDuration,
   type SearchType,
@@ -19,6 +25,14 @@ import { fetchSearXNG } from "./webSearchService.ts";
 const DEFAULT_SEARCH_LIMIT = 30;
 const MAX_SEARCH_LIMIT = 30;
 const MAX_QUERY_LENGTH = 2000;
+// The client aborts a search after REQUEST_TIMEOUT in client/modules/search.ts
+// (30 s) and shows its timeout alert, so a response still being assembled when
+// that lands is a response the user never sees. The fallback may not push a
+// search past this point; the 5 s margin is for ranking and the transfer.
+const SEARCH_DEADLINE_MS = 25_000;
+// A fallback cannot finish in this window, so starting one would only move the
+// same 502 further out.
+const MIN_FALLBACK_BUDGET_MS = 2_000;
 
 const searchParamsSchema = z.object({
   query: z
@@ -119,14 +133,61 @@ export function searchEndpointServerHook<
       const isTextSearch = request.url?.startsWith("/search/text");
       const searchType = isTextSearch ? "text" : "images";
 
-      let searxngResults: TextResult[] | ImageResult[];
+      let searchResults: TextResult[] | ImageResult[] | null;
       const searchStartedAt = performance.now();
       try {
-        searxngResults = await fetchSearXNG(query, searchType, limit);
+        searchResults = await fetchSearXNG(query, searchType, limit);
         recordSearchDuration(searchType, performance.now() - searchStartedAt);
       } catch {
-        // SearXNG is unreachable: answer non-200 so the client can tell an
-        // outage apart from a search that genuinely has no results.
+        // SearXNG is unreachable. The operator may have switched on a second
+        // text source, which is consulted only here, after SearXNG has failed,
+        // and never for images: Parallel has no image search.
+        searchResults = null;
+
+        if (isTextSearch && isSearchFallbackEnabled()) {
+          const remainingMs =
+            SEARCH_DEADLINE_MS - (performance.now() - searchStartedAt);
+
+          if (remainingMs < MIN_FALLBACK_BUDGET_MS) {
+            // The deadline leaves too little time for a second source, so it is
+            // not asked and the 502 goes out now. Counted as a fallback that
+            // failed rather than one that served, since none of its results
+            // could have reached the client in time.
+            incrementSearchesFailedOnFallback();
+            console.error(
+              "SearXNG failed, and the search deadline left the fallback too little time",
+            );
+          } else {
+            try {
+              searchResults = await fetchFallbackTextResults(
+                query,
+                limit,
+                remainingMs,
+              );
+              incrementSearchesServedByFallback();
+              console.log(
+                "SearXNG failed, served text results from the fallback search",
+              );
+            } catch (fallbackError) {
+              incrementSearchesFailedOnFallback();
+              // Fixed text plus the error's message, which by construction
+              // carries an HTTP status or a JSON-RPC code, never the query.
+              console.error(
+                `SearXNG failed, and the fallback search failed: ${
+                  fallbackError instanceof Error
+                    ? fallbackError.message
+                    : String(fallbackError)
+                }`,
+              );
+            }
+          }
+        }
+      }
+
+      if (searchResults === null) {
+        // The fallback is off, is not offered for this search type, was skipped
+        // for lack of deadline, or failed itself: answer non-200 so the client
+        // can tell an outage apart from a search that genuinely has no results.
         response.statusCode = 502;
         response.setHeader("Content-Type", "application/json");
         response.end(JSON.stringify({ error: "Search service unavailable" }));
@@ -134,7 +195,7 @@ export function searchEndpointServerHook<
       }
 
       if (isTextSearch) {
-        const results = searxngResults as TextResult[];
+        const results = searchResults as TextResult[];
         const rankedResults = await handleRanking(
           query,
           searchType,
@@ -147,7 +208,7 @@ export function searchEndpointServerHook<
         response.setHeader("Content-Type", "application/json");
         response.end(JSON.stringify(rankedResults));
       } else {
-        const results = searxngResults as ImageResult[];
+        const results = searchResults as ImageResult[];
         const resultsText = results.map(
           ([title, url]) => [title?.slice(0, 100) || "", "", url] as TextResult,
         );

server/searchesSinceLastRestart.ts

@@ -53,6 +53,31 @@ export function incrementSearchesWithAllResultsDiscardedSinceLastRestart() {
   searchesWithAllResultsDiscardedSinceLastRestart++;
 }
 
+// The fallback is only consulted after SearXNG has already failed, so these two
+// say whether the second source pulls its weight: served is a search the caller
+// got anyway, failed is one that ended as the 502 there was before it existed,
+// including a search whose SearXNG retries left the deadline too little time to
+// ask the fallback at all. A search with the fallback off, or an image search,
+// lands in neither.
+let searchesServedByFallback = 0;
+let searchesFailedOnFallback = 0;
+
+export function getSearchesServedByFallback() {
+  return searchesServedByFallback;
+}
+
+export function incrementSearchesServedByFallback() {
+  searchesServedByFallback++;
+}
+
+export function getSearchesFailedOnFallback() {
+  return searchesFailedOnFallback;
+}
+
+export function incrementSearchesFailedOnFallback() {
+  searchesFailedOnFallback++;
+}
+
 /** One engine SearXNG reported as unresponsive, with the reason it gave. */
 export interface UnresponsiveEngine {
   engine: string;

server/statusEndpointServerHook.test.ts

@@ -1,5 +1,9 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { describe, expect, it, vi } from "vitest";
+import {
+  incrementSearchesFailedOnFallback,
+  incrementSearchesServedByFallback,
+} from "./searchesSinceLastRestart.ts";
 import { statusEndpointServerHook } from "./statusEndpointServerHook.ts";
 
 // The health getters probe live services; this test is about the payload,
@@ -67,6 +71,26 @@ describe("statusEndpointServerHook", () => {
     });
   });
 
+  it("publishes the two fallback counters as plain counts", async () => {
+    const before = await callStatus();
+
+    incrementSearchesServedByFallback();
+    incrementSearchesFailedOnFallback();
+    incrementSearchesFailedOnFallback();
+
+    const status = await callStatus();
+
+    // Exact values rather than expect.any(Number), which a pair of swapped
+    // getters would satisfy too. The counters are module state that no test
+    // here resets, so the deltas are what each getter moved.
+    expect(status.searchesServedByFallback).toBe(
+      (before.searchesServedByFallback as number) + 1,
+    );
+    expect(status.searchesFailedOnFallback).toBe(
+      (before.searchesFailedOnFallback as number) + 2,
+    );
+  });
+
   it("publishes the page-read circuit count beside the outcome counters", async () => {
     const status = await callStatus();
 

server/statusEndpointServerHook.ts

@@ -10,6 +10,8 @@ import { getRerankingStats } from "./rerankingSinceLastRestart.ts";
 import {
   getDegradedSearchTypes,
   getGraphicalSearchesSinceLastRestart,
+  getSearchesFailedOnFallback,
+  getSearchesServedByFallback,
   getSearchesWithAllResultsDiscardedSinceLastRestart,
   getSearchesWithoutResultsSinceLastRestart,
   getSearchesWithUnresponsiveEnginesSinceLastRestart,
@@ -83,6 +85,8 @@ export function statusEndpointServerHook<
         getSearchesWithUnresponsiveEnginesSinceLastRestart(),
       searchesWithAllResultsDiscarded:
         getSearchesWithAllResultsDiscardedSinceLastRestart(),
+      searchesServedByFallback: getSearchesServedByFallback(),
+      searchesFailedOnFallback: getSearchesFailedOnFallback(),
       biEncoderServiceStatus,
       rerankerServiceStatus,
       webSearchServiceStatus,