fix: fail closed on partial engine capability discovery

Treat any unreachable SearXNG /config instance as unknown when validating explicit time ranges, with regression coverage and README guidance.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: 2 people

README.md

@@ -131,7 +131,8 @@ For SearXNG deployment, configuration, and troubleshooting, see
     - `min_score` (number, optional): Minimum relevance score from 0.0 to 1.0. Results below this score are filtered out.
     - `num_results` (number, optional): Maximum number of results to return, from 1 to 20. `SEARXNG_MAX_RESULTS` applies as an operator ceiling.
     - `categories` (string, optional): Comma-separated SearXNG categories (e.g. `"news"`, `"it,science"`). Live `/config` capabilities are aggregated across reachable instances; prefer `searxng_instance_info` `categories.common` for consistent multi-instance results. Known values are trimmed and normalized case-insensitively; unknown values are forwarded trimmed so SearXNG can ignore or honor them. If `/config` is unavailable, values are forwarded as-is with a warning. If omitted, each instance uses its server-side default.
-    - `engines` (string, optional): Comma-separated SearXNG engine names (e.g. `"google,bing,ddg"`, `"semantic scholar"`). Live `/config` capabilities are aggregated across reachable instances; prefer `searxng_instance_info` `engines.common.enabled` for consistent multi-instance results. Known values are trimmed and normalized case-insensitively, including engines disabled by default; unknown values are forwarded trimmed so SearXNG can ignore or honor them. If `/config` is unavailable, values are forwarded as-is with a warning. If omitted, each instance uses its server-side default.
+    - `engines` (string, optional): Comma-separated SearXNG engine names (e.g. `"google,bing,ddg"`, `"semantic scholar"`). Live `/config` capabilities are aggregated across reachable instances; prefer `searxng_instance_info` `engines.common.enabled` for consistent multi-instance results. Known values are trimmed and normalized case-insensitively, including engines disabled by default; unknown values are forwarded trimmed so SearXNG can ignore or honor them. If `/config` is unavailable, values are forwarded as-is with a warning, except when combined with `time_range`.
+    - When `engines` and `time_range` are both provided, every configured SearXNG instance must return `/config` successfully and every selected engine must explicitly report `time_range_support=true`. If any instance is unreachable or any engine is unsupported or unknown, the request fails before `/search` to avoid a misleading empty result. Omit `time_range` or use an engine-specific query filter instead.
     - `response_format` (string, optional): Response format, either `"text"` for formatted agent-readable output or `"json"` for raw SearXNG JSON with filtered/sliced `results`. If omitted, `SEARXNG_DEFAULT_RESPONSE_FORMAT` applies; if unset or invalid, `text` is used. An explicit `response_format` always takes precedence.
     - `result_detail` (string, optional): `"full"` (the default) preserves SearXNG metadata, warnings, provenance, answers, infoboxes, corrections, and suggestions. `"compact"` returns only title, URL, and the description/content snippet for every result; compact JSON uses exactly the `title`, `url`, and `content` keys. Use full when those research signals matter.
     - Clients that explicitly send or auto-inject `response_format=text` continue to override the operator default. If omitted calls still return text after configuring JSON, inspect the arguments emitted by the MCP client.

__tests__/unit/instance-info.test.ts

@@ -137,6 +137,29 @@ async function runTests() {
     envManager.restore();
   }, results);
 
+  await testFunction('fails closed when any configured instance /config is unavailable', async () => {
+    clearInstanceInfoCacheForTests();
+    envManager.set('SEARXNG_URL', 'https://up.example.com;https://down.example.com');
+    const mockServer = createMockServer();
+    fetchMocker.mock(async (url, options) => {
+      if (new URL(url.toString()).origin === 'https://down.example.com') {
+        throw new Error('temporary outage');
+      }
+      return createMockFetch({ json: makeConfig() })(url, options);
+    });
+
+    const support = await getEngineTimeRangeSupport(mockServer as any, ['google', 'brave']);
+
+    assert.deepEqual(support, {
+      supported: [],
+      unsupported: [],
+      unknown: ['google', 'brave'],
+    });
+
+    fetchMocker.restore();
+    envManager.restore();
+  }, results);
+
   await testFunction('returns category names when /config categories is an array of strings', async () => {
     clearInstanceInfoCacheForTests();
     envManager.set('SEARXNG_URL', 'https://test-searx.example.com');

__tests__/unit/search.test.ts

@@ -1700,6 +1700,35 @@ async function runTests() {
     envManager.restore();
   }, results);
 
+  await testFunction('partial multi-instance /config failure rejects time_range before search', async () => {
+    clearInstanceInfoCacheForTests();
+    envManager.set('SEARXNG_URL', 'https://up.example.com;https://down.example.com');
+
+    const mockServer = createMockServer();
+    const requestedUrls: string[] = [];
+    fetchMocker.mock(async (url, options) => {
+      requestedUrls.push(url.toString());
+      if (new URL(url.toString()).origin === 'https://down.example.com') {
+        throw new Error('temporary outage');
+      }
+      return createMockFetch({ json: makeConfigWithEngines() })(url, options);
+    });
+
+    try {
+      await performWebSearch(mockServer as any, 'AI', 1, 'year', undefined, undefined, undefined, undefined, undefined, 'google');
+      assert.fail('Expected partial capability discovery failure to reject the search');
+    } catch (error: any) {
+      assert.ok(error.message.includes('google'), error.message);
+      assert.ok(error.message.includes('time_range=year'), error.message);
+    }
+
+    assert.equal(requestedUrls.length, 2);
+    assert.ok(requestedUrls.every((requestedUrl) => new URL(requestedUrl).pathname.endsWith('/config')));
+
+    fetchMocker.restore();
+    envManager.restore();
+  }, results);
+
   await testFunction('mixed-case engines and categories normalize to canonical /config names', async () => {
     clearInstanceInfoCacheForTests();
     envManager.set('SEARXNG_URL', 'https://test-searx.example.com');

src/instance-info.ts

@@ -410,6 +410,14 @@ export async function getEngineTimeRangeSupport(
     return null;
   }
 
+  if (result.failures.length > 0) {
+    return {
+      supported: [],
+      unsupported: [],
+      unknown: [...requestedEngines],
+    };
+  }
+
   const supported: string[] = [];
   const unsupported: string[] = [];
   const unknown: string[] = [];