fix(url-reader): align failover review contracts

Coverage: 94.44%

Author: ihor-sokoliuk

SECURITY.md

@@ -61,8 +61,9 @@ To allow private URL reads and private DNS-resolved targets (e.g. for internal d
 
 Setting `FLARESOLVERR_URL` or `BYPARR_URL` delegates challenge-page navigation
 to a trusted browser service. FlareSolverr 3.5.0 and Byparr 2.1.0 were verified
-on 2026-07-30. Both endpoints may be configured; FlareSolverr is always primary
-and Byparr is the fallback only for busy or transient-unavailable acquisition.
+on 2026-07-30. When both endpoints are configured, this release uses
+FlareSolverr as the fixed primary and Byparr as the fallback only for busy or
+transient-unavailable acquisition.
 Canonical duplicate endpoints fail closed.
 
 The verified `linux/amd64` images came from multi-architecture manifests

__tests__/unit/browser-solver-state.test.ts

@@ -55,6 +55,21 @@ function jsonSolution(url: string, extra: Record<string, unknown> = {}) {
   };
 }
 
+function createProviderConfig(
+  provider: "flaresolverr" | "byparr",
+  endpoint: string,
+): BrowserSolverConfig {
+  const byparr = provider === "byparr";
+  return {
+    provider,
+    endpoint: new URL(`${endpoint}/v1`),
+    timeoutMs: 1000,
+    wireTimeout: byparr ? 1 : 1000,
+    maxConcurrentRequests: 1,
+    maxResponseBytes: byparr ? 5 * 1024 * 1024 : 256 * 1024,
+  };
+}
+
 async function waitForPending(
   pending: http.ServerResponse[],
   count: number,
@@ -217,14 +232,7 @@ async function runTests() {
       res.writeHead(200, { "content-type": "application/json" });
       res.end(JSON.stringify(jsonSolution(target.href)));
     });
-    const flareConfig: BrowserSolverConfig = {
-      provider: "flaresolverr",
-      endpoint: new URL(`${flare.url}/v1`),
-      timeoutMs: 1000,
-      wireTimeout: 1000,
-      maxConcurrentRequests: 1,
-      maxResponseBytes: 256 * 1024,
-    };
+    const flareConfig = createProviderConfig("flaresolverr", flare.url);
     const heldPrimary = acquireBrowserSolverSolution(
       createMockServer() as any,
       flareConfig,
@@ -236,14 +244,7 @@ async function runTests() {
         createMockServer() as any,
         [
           flareConfig,
-          {
-            provider: "byparr",
-            endpoint: new URL(`${byparr.url}/v1`),
-            timeoutMs: 1000,
-            wireTimeout: 1,
-            maxConcurrentRequests: 1,
-            maxResponseBytes: 5 * 1024 * 1024,
-          },
+          createProviderConfig("byparr", byparr.url),
         ],
         target,
       );

__tests__/unit/documentation.test.ts

@@ -166,12 +166,16 @@ export async function runTests(): Promise<TestResult> {
       assert.ok(document.includes('HTTP client'));
       assert.ok(document.includes('disconnects'));
     }
-    for (const document of [readme, configuration, security]) {
+    for (const document of [readme, configuration]) {
       const normalized = document.replace(/\s+/gu, ' ');
       assert.ok(normalized.includes('FlareSolverr is always primary'));
       assert.ok(normalized.includes('150 seconds'));
       assert.ok(normalized.includes('unavailable'));
     }
+    const normalizedSecurity = security.replace(/\s+/gu, ' ');
+    assert.ok(normalizedSecurity.includes('FlareSolverr as the fixed primary'));
+    assert.ok(normalizedSecurity.includes('150 seconds'));
+    assert.ok(normalizedSecurity.includes('unavailable'));
     assert.ok(readme.includes('no automatic reverse failover'));
     assert.ok(configuration.includes('automatic reverse failover is not performed'));
     assert.ok(security.includes('does not retain a health score'));

__tests__/unit/url-reader.test.ts

@@ -363,7 +363,7 @@ async function runTests() {
           targetGets++;
         }
         res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
-        res.end(req.method === 'HEAD' ? '' : `<h1>${scenario.name} direct</h1>`);
+        res.end(req.method === 'HEAD' ? '' : '<h1>Dual direct fallback</h1>');
       });
       const flare = await startHttpServer((_req, res) => {
         flarePosts++;
@@ -384,7 +384,7 @@ async function runTests() {
           createMockServer() as any,
           target.url,
         );
-        assert.ok(result.includes(`# ${scenario.name} direct`), scenario.name);
+        assert.ok(result.includes('# Dual direct fallback'), scenario.name);
         assert.equal(flarePosts, 1, scenario.name);
         assert.equal(byparrPosts, 1, scenario.name);
         assert.equal(targetGets, 1, scenario.name);

src/types.ts

@@ -350,7 +350,7 @@ export const LITE_INSTANCE_INFO_TOOL: Tool = {
 export const LITE_READ_URL_TOOL: Tool = {
   name: "web_url_read",
   description:
-    "Fetch URL. Converts HTML to markdown; returns explicit JSON, plain text, YAML, TOML, and XML as readable markdown; supports bounded PDF text extraction; other binary/media/archive downloads are rejected. When browser solvers are configured, mcp-searxng attempts FlareSolverr first and then Byparr only after a busy or transient-unavailable acquisition; after the final unavailable provider it uses one uncached direct read.",
+    "Fetch URL. Converts HTML to markdown; returns explicit JSON, plain text, YAML, TOML, and XML as readable markdown; supports bounded PDF text extraction; other binary/media/archive downloads are rejected. When browser solvers are configured, mcp-searxng attempts FlareSolverr first and then Byparr only after a busy or transient-unavailable acquisition; after a final busy or unavailable provider it uses one uncached direct read.",
   inputSchema: {
     type: "object",
     properties: { url: { type: "string", description: "URL to fetch." } },
@@ -365,7 +365,7 @@ export const READ_URL_TOOL: Tool = {
     "Content-type aware: HTML is converted to markdown; JSON is pretty-printed; plain text, YAML, TOML, and XML are returned as fenced readable text. " +
     "PDF text extraction is supported with bounded input, output, page count, time, concurrency, and memory; OCR is not supported. " +
     "Binary, media, archive, and octet-stream downloads other than PDFs are intentionally rejected instead of being returned as raw bytes. " +
-    "When the operator configures browser solvers, mcp-searxng attempts FlareSolverr first and then Byparr only after a busy or transient-unavailable acquisition; cache hits bypass acquisition and the final unavailable provider uses one uncached direct-fetch fallback. " +
+    "When the operator configures browser solvers, mcp-searxng attempts FlareSolverr first and then Byparr only after a busy or transient-unavailable acquisition; cache hits bypass acquisition and a final busy or unavailable provider uses one uncached direct-fetch fallback. " +
     "Three modes: " +
     "(1) Full content — omit filtering params; use `startChar`/`maxLength` to paginate large pages. " +
     "(2) Section extraction — set `section` to return content under a specific heading. " +