Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

12.6 KB
Raw Blame
import { readdirSync, readFileSync } from 'node:fs';
import { basename, dirname, join, relative, win32 } from 'node:path';
import { fileURLToPath } from 'node:url';
import { describe, expect, test } from 'vitest';
import { isTestOnlySourceFile } from '../../../../test-support/test-only-source-file.mjs';
import { LOOPBACK_SCAN_ROOTS } from './loopback-bind-discipline.reads';

const __dirname = dirname(fileURLToPath(import.meta.url));
const PACKAGE_ROOT = join(__dirname, '..', '..');
const OK_ROOT = join(PACKAGE_ROOT, '..', '..');
const SCAN_ROOTS = LOOPBACK_SCAN_ROOTS.map((root) => join(OK_ROOT, root));

const SELF_BASENAME = basename(fileURLToPath(import.meta.url));

interface FileLines {
  path: string;
  lines: string[];
}

function listScannedFiles(relativePath: typeof relative = relative): FileLines[] {
  const out: FileLines[] = [];
  function walk(dir: string) {
    for (const entry of readdirSync(dir, { withFileTypes: true })) {
      const abs = join(dir, entry.name);
      if (entry.isDirectory()) {
        walk(abs);
        continue;
      }
      if (!entry.isFile() || !entry.name.endsWith('.ts')) continue;
      if (entry.name === SELF_BASENAME) continue;
      out.push({
        path: relativePath(PACKAGE_ROOT, abs).replaceAll('\\', '/'),
        lines: readFileSync(abs, 'utf-8').split('\n'),
      });
    }
  }
  for (const root of SCAN_ROOTS) walk(root);
  return out;
}

function isCommentOnlyLine(line: string): boolean {
  const trimmed = line.trim();
  return trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*');
}

const LOOPBACK_HOST_LITERAL = /['"](?:127\.0\.0\.1|::1)['"]/;
const UNIX_SOCKET_LISTEN = /^\.listen\(\s*\{(?=[^}]*\bpath\s*[:,}])(?![^}]*\bport\b)/;

export function findNonLoopbackListenCalls(lines: string[]): Array<{ line: number; text: string }> {
  const violations: Array<{ line: number; text: string }> = [];
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i] ?? '';
    if (isCommentOnlyLine(line)) continue;
    const idx = line.indexOf('.listen(');
    if (idx === -1) continue;
    let window = line.slice(idx);
    for (let j = i + 1; j <= i + 3 && !window.includes(')') && j < lines.length; j++) {
      window += `\n${lines[j] ?? ''}`;
    }
    const paren = window.indexOf(')');
    if (paren !== -1) window = window.slice(0, paren + 1);
    if (!LOOPBACK_HOST_LITERAL.test(window) && !UNIX_SOCKET_LISTEN.test(window)) {
      violations.push({ line: i + 1, text: line.trim() });
    }
  }
  return violations;
}

interface ListenExemption {
  path: string;
  call: string;
  reason: string;
}

const RECORDING_OWNERSHIP_CASE = 'tests/stress/_helpers/port-ownership/recording.ownership-case.ts';

const LISTEN_EXEMPTIONS: readonly ListenExemption[] = [
  {
    path: RECORDING_OWNERSHIP_CASE,
    call: 'server.listen(port, host);',
    reason:
      "Wildcard occupant bound to '0.0.0.0': holds the candidate port on the wildcard address so Vite's availability preflight skips it; it is never dialed.",
  },
  {
    path: RECORDING_OWNERSHIP_CASE,
    call: 'await vite.listen();',
    reason:
      "Vite's listen(port?, isRestart?) accepts no host; the server binds the loopback host configured in server.host.",
  },
];

function findUnexemptedListenCalls(
  path: string,
  lines: string[],
): Array<{ line: number; text: string }> {
  const remaining = LISTEN_EXEMPTIONS.filter((exemption) => exemption.path === path);
  return findNonLoopbackListenCalls(lines).filter((violation) => {
    const match = remaining.findIndex((exemption) => exemption.call === violation.text);
    if (match === -1) return true;
    remaining.splice(match, 1);
    return false;
  });
}

function findStaleListenExemptions(files: readonly FileLines[]): ListenExemption[] {
  const unclaimed = new Map(
    files.map((file) => [file.path, findNonLoopbackListenCalls(file.lines).map((v) => v.text)]),
  );
  return LISTEN_EXEMPTIONS.filter((exemption) => {
    const calls = unclaimed.get(exemption.path) ?? [];
    const match = calls.indexOf(exemption.call);
    if (match === -1) return true;
    calls.splice(match, 1);
    return false;
  });
}

const AMBIGUOUS_LOCALHOST_DIAL = /\b(?:https?|wss?):\/\/localhost:\$\{/;

export function findAmbiguousLocalhostDials(
  lines: string[],
): Array<{ line: number; text: string }> {
  const violations: Array<{ line: number; text: string }> = [];
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i] ?? '';
    if (isCommentOnlyLine(line)) continue;
    if (AMBIGUOUS_LOCALHOST_DIAL.test(line)) {
      violations.push({ line: i + 1, text: line.trim() });
    }
  }
  return violations;
}

describe('loopback bind discipline (app test sources)', () => {
  const files = listScannedFiles();

  test('there are test files to scan (sanity)', () => {
    expect(files.length).toBeGreaterThan(0);
    expect(files.some((f) => f.path.endsWith('integration/test-harness.ts'))).toBe(true);
    expect(files.some((f) => f.path.endsWith('_helpers/server-process.ts'))).toBe(true);
    expect(files.some((f) => isTestOnlySourceFile(f.path, 'playwright'))).toBe(true);
  });

  test('win32 path semantics yield the /-separated keys the sanity checks and listen exemptions match', () => {
    const win32Files = listScannedFiles(win32.relative);
    expect(win32Files.some((f) => f.path.endsWith('integration/test-harness.ts'))).toBe(true);
    expect(win32Files.some((f) => f.path.endsWith('_helpers/server-process.ts'))).toBe(true);
    expect(win32Files.map((f) => f.path)).toContain(RECORDING_OWNERSHIP_CASE);
    expect(win32Files.flatMap((f) => findUnexemptedListenCalls(f.path, f.lines))).toEqual([]);
    expect(findStaleListenExemptions(win32Files)).toEqual([]);
  });

  test('every .listen( call binds an explicit loopback host literal', () => {
    const violations: string[] = [];
    for (const file of files) {
      for (const v of findUnexemptedListenCalls(file.path, file.lines)) {
        violations.push(`  ${file.path}:${v.line}    ${v.text}`);
      }
    }
    expect(
      violations,
      `Hostless rig bind found — a bare listen(0) binds the IPv6 wildcard '::', whose loopback-specific ` +
        `port slots stay silently bindable by foreign processes; their listeners then intercept this rig's ` +
        `localhost dials (the rotating integration-suite flake). Bind a loopback-specific host ` +
        `(e.g. listen(0, '127.0.0.1', cb)) and dial the literal from server.address():\n${violations.join('\n')}`,
    ).toEqual([]);
  });

  test('no interpolated-port localhost dial URLs', () => {
    const violations: string[] = [];
    for (const file of files) {
      for (const v of findAmbiguousLocalhostDials(file.lines)) {
        violations.push(`  ${file.path}:${v.line}    ${v.text}`);
      }
    }
    expect(
      violations,
      `Ambiguous-name rig dial found — 'localhost' resolves '::1'-first, exactly the loopback-specific slot ` +
        `a foreign process can hold while the rig sits on a wildcard (or single-family) bind. Dial the ` +
        `literal address the rig actually bound (a harness-advertised base URL, or ` +
        `http://127.0.0.1:\${port}):\n${violations.join('\n')}`,
    ).toEqual([]);
  });

  test('listen predicate fires on planted violations and not on adjacent negatives', () => {
    expect(findNonLoopbackListenCalls(['  s.listen(0, () => {']).length).toBe(1);
    expect(
      findNonLoopbackListenCalls(['    httpServer.listen(port, () => resolve());']).length,
    ).toBe(1);

    expect(findNonLoopbackListenCalls(["  server.listen(0, '127.0.0.1', resolve);"]).length).toBe(
      0,
    );
    expect(findNonLoopbackListenCalls(["  s.listen(port, '::1', cb);"]).length).toBe(0);

    expect(
      findNonLoopbackListenCalls(['  server.listen(', '    0,', "    '127.0.0.1',", '    cb)'])
        .length,
    ).toBe(0);

    expect(findNonLoopbackListenCalls(['  // before httpServer.listen() resolves']).length).toBe(0);
    expect(
      findNonLoopbackListenCalls([' * boot scan runs BEFORE httpServer.listen().']).length,
    ).toBe(0);

    expect(findNonLoopbackListenCalls(['  s.listen(port, host, cb);']).length).toBe(1);

    expect(findNonLoopbackListenCalls(["  s.listen(0, '0.0.0.0', cb);"]).length).toBe(1);
  });

  test('listen exemptions admit each keyed call once in its own file and nowhere else', () => {
    const exemptedPath = 'tests/stress/_helpers/port-ownership/recording.ownership-case.ts';
    const exemptedCalls = ['      server.listen(port, host);', '        await vite.listen();'];

    expect(findNonLoopbackListenCalls(exemptedCalls).length).toBe(2);
    expect(findUnexemptedListenCalls(exemptedPath, exemptedCalls)).toEqual([]);

    expect(
      findUnexemptedListenCalls(
        'tests/stress/_helpers/port-ownership/startup.ownership-case.ts',
        exemptedCalls,
      ).length,
    ).toBe(2);
    expect(
      findUnexemptedListenCalls('tests/integration/recording.ownership-case.ts', exemptedCalls)
        .length,
    ).toBe(2);

    expect(
      findUnexemptedListenCalls(exemptedPath, [
        ...exemptedCalls,
        '  s.listen(0, cb);',
        "  s.listen(0, '0.0.0.0', cb);",
      ]),
    ).toEqual([
      { line: 3, text: 's.listen(0, cb);' },
      { line: 4, text: "s.listen(0, '0.0.0.0', cb);" },
    ]);

    expect(findUnexemptedListenCalls(exemptedPath, [...exemptedCalls, ...exemptedCalls])).toEqual([
      { line: 3, text: 'server.listen(port, host);' },
      { line: 4, text: 'await vite.listen();' },
    ]);
  });

  test('every listen exemption still matches a call in its own file', () => {
    expect(
      findStaleListenExemptions(files).map(
        (exemption) => `  ${exemption.path}    ${exemption.call}`,
      ),
      'These LISTEN_EXEMPTIONS entries match no non-loopback .listen( call in their own file: ' +
        'the call changed or was removed. Delete the entry, or update its call text',
    ).toEqual([]);
  });

  test('stale exemptions are reported for a removed, rebound or relocated call and not for the live shape', () => {
    const exemptedPath = 'tests/stress/_helpers/port-ownership/recording.ownership-case.ts';
    const occupant = '      server.listen(port, host);';
    const viteListen = '        await vite.listen();';

    expect(
      findStaleListenExemptions([{ path: exemptedPath, lines: [occupant, viteListen] }]),
    ).toEqual([]);

    expect(
      findStaleListenExemptions([{ path: exemptedPath, lines: [occupant] }]).map((e) => e.call),
    ).toEqual(['await vite.listen();']);
    expect(
      findStaleListenExemptions([
        { path: exemptedPath, lines: ["      server.listen(port, '127.0.0.1');", viteListen] },
      ]).map((e) => e.call),
    ).toEqual(['server.listen(port, host);']);
    expect(
      findStaleListenExemptions([
        { path: exemptedPath, lines: [occupant, '        // await vite.listen();'] },
      ]).map((e) => e.call),
    ).toEqual(['await vite.listen();']);

    expect(
      findStaleListenExemptions([
        {
          path: 'tests/stress/_helpers/port-ownership/startup.ownership-case.ts',
          lines: [occupant, viteListen],
        },
      ]).length,
    ).toBe(2);
    expect(findStaleListenExemptions([]).length).toBe(2);
  });

  test('dial predicate fires on planted violations and not on adjacent negatives', () => {
    expect(
      findAmbiguousLocalhostDials([
        `  const res = await fetch(\`http://localhost:\${server.port}/api/documents\`);`,
      ]).length,
    ).toBe(1);
    expect(
      findAmbiguousLocalhostDials([`    url: \`ws://localhost:\${port}/collab\`,`]).length,
    ).toBe(1);

    expect(
      findAmbiguousLocalhostDials([`  const res = await fetch(\`http://127.0.0.1:\${port}/x\`);`])
        .length,
    ).toBe(0);

    expect(
      findAmbiguousLocalhostDials(["  expect(url).toBe('ws://localhost:7777/collab');"]).length,
    ).toBe(0);

    expect(findAmbiguousLocalhostDials([`  // dials http://localhost:\${port} today`]).length).toBe(
      0,
    );

    expect(findAmbiguousLocalhostDials(["  host: 'localhost:5173',"]).length).toBe(0);
  });

  test('a listen on a Unix-socket path is not a host bind, while the object form with a port still needs a loopback host', () => {
    const planted = [
      '  s.listen(0);',
      '  server.listen(port, () => resolve());',
      '  server.listen({ port }, cb);',
      "  server.listen({ port: 0, host: '0.0.0.0' }, cb);",
      '  server.listen({ path: socketPath, port: 0 }, cb);',
      '  server.listen({ path: socketPath }, () => {',
      '  server.listen({ path }, cb);',
      '  server.listen(',
      '    { path: join(dir, "supervisor.sock") },',
      '    () => resolve(),',
      '  );',
      "  server.listen({ port: 0, host: '127.0.0.1' }, cb);",
    ];
    expect(findNonLoopbackListenCalls(planted).map((v) => v.line)).toEqual([1, 2, 3, 4, 5]);
  });
});