feat(runtime): require Node.js 22 and refresh PDF parsing

Coverage: 95.93% (was 94.97%)

BREAKING CHANGE: Node.js 22 or later is now required.

Author: ihor-sokoliuk

.github/workflows/ci.yml

@@ -19,7 +19,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node-version: ['20', '22', '24', '26.7.0']
+        node-version: ['22', '24', '26.7.0']
 
     steps:
       - name: Checkout code
@@ -42,3 +42,6 @@ jobs:
 
       - name: Test coverage
         run: npm run test:coverage
+
+      - name: E2E tests
+        run: npm run test:e2e

README.md

@@ -181,7 +181,7 @@ For SearXNG deployment, configuration, and troubleshooting, see
 
 ## Installation
 
-Node.js 20 remains supported but is deprecated and end-of-life. Node.js 22 or later is recommended. Node.js 20 will be removed only in a future major release.
+Node.js 22 or later is required.
 
 <details>
 <summary>NPM (global install)</summary>

__tests__/e2e/url-reader.e2e.ts

@@ -11,24 +11,129 @@
  */
 
 import { strict as assert } from 'node:assert';
+import http from 'node:http';
+import net from 'node:net';
 import { fileURLToPath } from 'node:url';
 import {
   checkSkipConditions,
   INIT_PARAMS,
   spawnWithMessages,
+  spawnWithMessagesAsync,
   LIVE_URL,
 } from './helpers/spawn-server.js';
 import { testFunction, createTestResults, printTestSummary } from '../helpers/test-utils.js';
+import { createTextPdf } from '../helpers/pdf-fixtures.js';
 
 const results = createTestResults();
+const E2E_TIMEOUT_MS = 15_000;
+const LOCAL_PDF_FIRST_PAGE = 'Local PDF first page for E2E';
+const LOCAL_PDF_SECOND_PAGE = 'Local PDF second page for E2E';
+
+interface TestServer {
+  url: string;
+  close: () => Promise<void>;
+}
+
+function startPdfServer(pdf: Uint8Array): Promise<TestServer> {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer((_, response) => {
+      response.writeHead(200, {
+        'content-type': 'application/pdf',
+        'content-length': String(pdf.byteLength),
+      });
+      response.end(Buffer.from(pdf));
+    });
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address() as net.AddressInfo;
+      resolve({
+        url: `http://127.0.0.1:${address.port}/fixture.pdf`,
+        close: () => new Promise<void>((done, rejectClose) => {
+          server.closeAllConnections();
+          server.close((error) => error ? rejectClose(error) : done());
+        }),
+      });
+    });
+    server.once('error', reject);
+  });
+}
+
+function readUrlMessages(url: string): object[] {
+  return [
+    { jsonrpc: '2.0', id: 1, method: 'initialize', params: INIT_PARAMS },
+    {
+      jsonrpc: '2.0',
+      id: 2,
+      method: 'tools/call',
+      params: {
+        name: 'web_url_read',
+        arguments: { url },
+      },
+    },
+  ];
+}
+
+async function withinTestBoundary<T>(operation: Promise<T>): Promise<T> {
+  let timeout: NodeJS.Timeout | undefined;
+  try {
+    return await Promise.race([
+      operation,
+      new Promise<never>((_, reject) => {
+        timeout = setTimeout(
+          () => reject(new Error(`Local PDF E2E test timed out after ${E2E_TIMEOUT_MS}ms`)),
+          E2E_TIMEOUT_MS,
+        );
+      }),
+    ]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
 
 async function runTests() {
   console.log('🌐 E2E Testing: web_url_read (live)\n');
 
-  const skip = checkSkipConditions();
-  if (skip) {
-    console.log(skip);
-    return { passed: 0, failed: 0, errors: [] };
+  await testFunction('web_url_read reads a two-page local PDF only with the private URL override', async () => {
+    await withinTestBoundary((async () => {
+      const server = await startPdfServer(createTextPdf([
+        LOCAL_PDF_FIRST_PAGE,
+        LOCAL_PDF_SECOND_PAGE,
+      ]));
+      try {
+        const blockedResponses = await spawnWithMessagesAsync(
+          readUrlMessages(server.url),
+          'https://test-searx.example.com',
+          E2E_TIMEOUT_MS,
+        );
+        const blockedResponse = blockedResponses[2];
+        assert.ok(blockedResponse?.error, 'loopback PDF request should be blocked by the SSRF boundary');
+        assert.match(
+          String(blockedResponse.error.message ?? ''),
+          /URL blocked by security policy/i,
+          JSON.stringify(blockedResponse.error),
+        );
+
+        const allowedResponses = await spawnWithMessagesAsync(
+          readUrlMessages(server.url),
+          'https://test-searx.example.com',
+          E2E_TIMEOUT_MS,
+          { MCP_HTTP_ALLOW_PRIVATE_URLS: 'true' },
+        );
+        const allowedResponse = allowedResponses[2];
+        assert.ok(allowedResponse && !allowedResponse.error, JSON.stringify(allowedResponse?.error));
+        const text: string = allowedResponse.result?.content?.[0]?.text ?? '';
+        assert.ok(text.includes(LOCAL_PDF_FIRST_PAGE), text);
+        assert.ok(text.includes(LOCAL_PDF_SECOND_PAGE), text);
+      } finally {
+        await server.close();
+      }
+    })());
+  }, results);
+
+  const liveSkip = checkSkipConditions();
+  if (liveSkip) {
+    console.log(liveSkip);
+    printTestSummary(results, 'E2E: URL Reader');
+    return results;
   }
 
   await testFunction('web_url_read fetches example.com and returns markdown', async () => {

__tests__/unit/documentation.test.ts

@@ -83,6 +83,10 @@ type PackageManifest = {
   version?: unknown;
 };
 
+type PackageLock = {
+  packages?: Record<string, PackageManifest>;
+};
+
 function toYamlLine(rawLine: string): YamlLine {
   return {
     indentation: rawLine.length - rawLine.trimStart().length,
@@ -148,23 +152,46 @@ function hasDependabotIgnoreEntry(source: string, dependencyName: string): boole
 
 function assertPackageMetadata(): void {
   const packageManifest = JSON.parse(readText(new URL('../../package.json', import.meta.url))) as PackageManifest;
+  const packageLock = JSON.parse(readText(new URL('../../package-lock.json', import.meta.url))) as PackageLock;
   assert.equal(packageManifest.version, '1.16.0');
-  assert.equal(packageManifest.engines?.node, '>=20');
+  assert.equal(packageManifest.engines?.node, '>=22');
+  assert.equal(packageManifest.dependencies?.unpdf, '1.8.1');
+  assert.equal(packageLock.packages?.[''].engines?.node, '>=22');
+  assert.equal(packageLock.packages?.[''].dependencies?.unpdf, '1.8.1');
   assert.equal(packageManifest.dependencies?.['express-rate-limit'], '^8.5.2');
 }
 
 function assertReadmeNodePolicy(readme: string): void {
-  assert.ok(readme.includes('Node.js 20 remains supported but is deprecated and end-of-life.'));
-  assert.ok(readme.includes('Node.js 22 or later is recommended.'));
-  assert.ok(readme.includes('Node.js 20 will be removed only in a future major release.'));
+  assert.ok(readme.includes('Node.js 22 or later is required.'));
+  assert.ok(!readme.includes('Node.js 20'), 'README must not claim Node.js 20 support');
+  for (const formerPromise of [
+    'Node.js 20 remains supported',
+    'Node.js 20 will be removed',
+    'Node.js 22 or later is recommended',
+  ]) {
+    assert.ok(!readme.includes(formerPromise), `README must not retain: ${formerPromise}`);
+  }
+}
+
+function assertClientGuideNodePolicy(guide: string): void {
+  assert.ok(guide.includes('Requires Node.js 22 or later.'));
+  assert.ok(!guide.includes('Node.js 20'), 'client guide must not claim Node.js 20 support');
+  for (const formerPromise of [
+    'Requires Node.js 20',
+    'Node.js 20 remains supported',
+    'Node.js 20 will be removed',
+    'Node.js 22 or later is recommended',
+  ]) {
+    assert.ok(!guide.includes(formerPromise), `client guide must not retain: ${formerPromise}`);
+  }
 }
 
 function assertCiMatrix(ci: string): void {
   const matrix = ci.match(/^\s*node-version:\s*\[([^\]]+)\]\s*$/mu);
   assert.ok(matrix, 'CI must declare an inline Node version matrix');
   assert.deepEqual(
     [...matrix[1].matchAll(/['"]([^'"]+)['"]/gu)].map((match) => match[1]),
-    ['20', '22', '24', '26.7.0'],
+    ['22', '24', '26.7.0'],
   );
 }
 
@@ -174,9 +201,16 @@ function assertCiCommonJob(ci: string): void {
   assert.match(ci, /uses:\s*actions\/checkout@/u);
   assert.match(ci, /uses:\s*actions\/setup-node@/u);
   assert.match(ci, /cache:\s*['"]npm['"]/u);
-  for (const command of [/run:\s*npm ci/u, /run:\s*npm run lint/u, /run:\s*npm run build/u, /run:\s*npm run test:coverage/u]) {
+  for (const command of [
+    /run:\s*npm ci/u,
+    /run:\s*npm run lint/u,
+    /run:\s*npm run build/u,
+    /run:\s*npm run test:coverage/u,
+    /run:\s*npm run test:e2e/u,
+  ]) {
     assert.match(ci, command);
   }
+  assert.match(ci, /run:\s*npm run test:coverage\s*\n\s*- name: E2E tests\s*\n\s*run:\s*npm run test:e2e/u);
   assert.doesNotMatch(ci, /^\s*include\s*:/mu);
   assert.doesNotMatch(ci, /^\s*if\s*:/mu);
   assert.doesNotMatch(ci, /continue-on-error\s*:/u);
@@ -392,6 +426,7 @@ export async function runTests(): Promise<TestResult> {
     const dependabot = readText(new URL('../../.github/dependabot.yml', import.meta.url));
     assertPackageMetadata();
     assertReadmeNodePolicy(readme);
+    assertClientGuideNodePolicy(readText(guideUrl));
     assertCiMatrix(ci);
     assertCiCommonJob(ci);
     assertCodeqlActionPins(codeql);