browser-commander 0.17.2 → 0.19.0

package/tests/unit/downloads/manager.test.js

@@ -0,0 +1,485 @@
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { setImmediate as yieldToEngine } from 'node:timers/promises';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  createDownloadManager,
+  DOWNLOAD_EVENT,
+} from '../../../src/downloads/manager.js';
+import { STAGING_DIRECTORY } from '../../../src/downloads/sources.js';
+import {
+  createFakeCdpSession,
+  createFakeContext,
+  makeFakeDownload,
+  makeTempDirectory,
+} from '../../helpers/download-fixtures.js';
+
+describe('download manager (issue #88)', () => {
+  let root;
+  let staging;
+  let context;
+  let manager;
+
+  beforeEach(async () => {
+    root = await makeTempDirectory();
+    staging = await makeTempDirectory();
+    context = createFakeContext();
+  });
+
+  afterEach(async () => {
+    await manager?.dispose();
+    manager = undefined;
+    await fs.rm(root, { recursive: true, force: true });
+    await fs.rm(staging, { recursive: true, force: true });
+  });
+
+  /**
+   * Start a manager over the fake Playwright context.
+   *
+   * @param {Object} [options] - Extra manager options
+   * @returns {Promise<Object>} The manager
+   */
+  const managerOver = async (options = {}) => {
+    manager = await createDownloadManager({
+      engine: 'playwright',
+      context,
+      directory: root,
+      ...options,
+    });
+    return manager;
+  };
+
+  /**
+   * Emit a fake download through the context.
+   *
+   * @param {Object} [options] - Fake download options
+   * @returns {Promise<Object>} The fake download
+   */
+  const emitDownload = async (options = {}) => {
+    const download = await makeFakeDownload({
+      dir: staging,
+      suggestedFilename: 'report.pdf',
+      ...options,
+    });
+    await context.emitDownload(download);
+    // Engine download events are fire-and-forget; the save they start is not.
+    await manager.idle();
+    return download;
+  };
+
+  /**
+   * Record every artifact published under one lifecycle event.
+   *
+   * @param {string} event - Lifecycle event to listen for
+   * @returns {Object[]} Artifacts, in the order they were published
+   */
+  const collect = (event) => {
+    const published = [];
+    manager.on(event, (artifact) => published.push(artifact));
+    return published;
+  };
+
+  /**
+   * List the managed directory, ignoring engine staging.
+   *
+   * @returns {Promise<string[]>} Sorted entry names
+   */
+  const listing = async () =>
+    (await fs.readdir(root)).filter((e) => e !== STAGING_DIRECTORY).sort();
+
+  it('should prepare the download directory before any download arrives', async () => {
+    const created = path.join(root, 'nested');
+
+    await managerOver({ directory: created });
+
+    assert.strictEqual(manager.directory, created);
+    assert.ok((await fs.stat(created)).isDirectory());
+  });
+
+  it('should save a download and report it as completed', async () => {
+    await managerOver();
+    const completed = collect(DOWNLOAD_EVENT.COMPLETED);
+
+    await emitDownload({ body: 'report body' });
+
+    assert.strictEqual(completed.length, 1);
+    assert.strictEqual(completed[0].state, DOWNLOAD_EVENT.COMPLETED);
+    assert.strictEqual(path.basename(completed[0].path), 'report.pdf');
+    assert.strictEqual(completed[0].bytes, 11);
+    assert.match(completed[0].checksum, /^[0-9a-f]{64}$/);
+    assert.ok(completed[0].id.startsWith('dl-'));
+    assert.ok(completed[0].completedAt);
+    assert.strictEqual(
+      await fs.readFile(completed[0].path, 'utf8'),
+      'report body'
+    );
+  });
+
+  it('should keep the file after the browser that produced it is gone', async () => {
+    await managerOver();
+    await emitDownload({ body: 'persisted' });
+    const [artifact] = manager.list();
+
+    await manager.dispose();
+    manager = undefined;
+
+    assert.strictEqual(await fs.readFile(artifact.path, 'utf8'), 'persisted');
+  });
+
+  it('should report an engine failure with the engine reason preserved', async () => {
+    await managerOver();
+    const failed = collect(DOWNLOAD_EVENT.FAILED);
+
+    await emitDownload({ failure: 'net::ERR_CONNECTION_RESET' });
+
+    assert.strictEqual(failed.length, 1);
+    assert.strictEqual(failed[0].failure, 'net::ERR_CONNECTION_RESET');
+    assert.strictEqual(failed[0].path, null);
+    assert.deepStrictEqual(await listing(), []);
+  });
+
+  it('should report a cancelled download as cancelled, not as a failure', async () => {
+    await managerOver();
+    const events = [];
+    manager.on(DOWNLOAD_EVENT.CANCELLED, () => events.push('cancelled'));
+    manager.on(DOWNLOAD_EVENT.FAILED, () => events.push('failed'));
+
+    await emitDownload({ failure: 'canceled' });
+
+    assert.deepStrictEqual(events, ['cancelled']);
+  });
+
+  it('should report each download once when a listener and a capture both watch', async () => {
+    // Issue #88: "a download that a global listener and an awaited capture()
+    // both see must be saved once and reported once".
+    await managerOver();
+    const completed = collect(DOWNLOAD_EVENT.COMPLETED);
+
+    const captured = await manager.capture({
+      action: () => emitDownload({ body: 'once' }),
+    });
+
+    assert.strictEqual(completed.length, 1);
+    assert.strictEqual(completed[0], captured);
+    assert.strictEqual(manager.list().length, 1);
+    assert.deepStrictEqual(await listing(), ['report.pdf']);
+  });
+
+  it('should catch a download that starts inside the triggering action', async () => {
+    // Arming after the action would lose this one: the race the issue calls out.
+    await managerOver();
+
+    const artifact = await manager.capture({
+      action: () => emitDownload({ body: 'raced' }),
+    });
+
+    assert.strictEqual(artifact.state, DOWNLOAD_EVENT.COMPLETED);
+  });
+
+  it('should name a captured download without losing the safety rules', async () => {
+    await managerOver();
+
+    const artifact = await manager.capture({
+      action: () =>
+        emitDownload({
+          suggestedFilename: '8d0f9e2c-4a11-4b22-9f00-1d2e3f405162',
+          body: '%PDF-1.7 invoice',
+        }),
+      filename: () => '../invoice.pdf',
+    });
+
+    assert.strictEqual(artifact.path, path.join(root, 'invoice.pdf'));
+  });
+
+  it('should fail a capture whose download does not validate', async () => {
+    await managerOver();
+
+    await assert.rejects(
+      manager.capture({
+        action: () => emitDownload({ body: '<html>login</html>' }),
+        validate: ({ bytes }) => {
+          if (bytes < 1000) {
+            throw new Error('expected a PDF, got a login page');
+          }
+        },
+      }),
+      /failed: expected a PDF/
+    );
+
+    assert.deepStrictEqual(await listing(), []);
+  });
+
+  it('should time out rather than wait forever for a download that never starts', async () => {
+    await managerOver();
+
+    await assert.rejects(
+      manager.capture({ action: () => {}, timeout: 50 }),
+      /no download completed within 50ms/
+    );
+  });
+
+  it('should propagate an error from the triggering action', async () => {
+    await managerOver();
+
+    await assert.rejects(
+      manager.capture({
+        action: () => {
+          throw new Error('the button was not there');
+        },
+      }),
+      /the button was not there/
+    );
+  });
+
+  it('should resolve a name collision without replacing the earlier file', async () => {
+    await managerOver();
+
+    await emitDownload({ body: 'first' });
+    await emitDownload({ body: 'second' });
+
+    assert.deepStrictEqual(await listing(), ['report (2).pdf', 'report.pdf']);
+    assert.strictEqual(manager.list().length, 2);
+  });
+
+  it('should list every download in the order it started', async () => {
+    await managerOver();
+
+    await emitDownload({ suggestedFilename: 'a.txt' });
+    await emitDownload({ suggestedFilename: 'b.txt' });
+
+    assert.deepStrictEqual(
+      manager.list().map((artifact) => artifact.suggestedFilename),
+      ['a.txt', 'b.txt']
+    );
+  });
+
+  describe('manual downloads over CDP', () => {
+    /**
+     * Start a manager whose only source is a fake CDP session.
+     *
+     * @param {Object} session - Fake CDP session
+     * @returns {Promise<Object>} The manager
+     */
+    const cdpManagerOver = async (session) =>
+      createDownloadManager({
+        engine: 'puppeteer',
+        directory: root,
+        browser: {
+          target: () => ({ createCDPSession: async () => session }),
+        },
+      });
+
+    it('should ask Chromium to report downloads it did not automate', async () => {
+      const session = createFakeCdpSession();
+      manager = await cdpManagerOver(session);
+
+      assert.deepStrictEqual(session.sent, [
+        {
+          method: 'Browser.setDownloadBehavior',
+          params: {
+            behavior: 'allowAndName',
+            downloadPath: path.join(root, STAGING_DIRECTORY),
+            eventsEnabled: true,
+          },
+        },
+      ]);
+    });
+
+    it('should place a manually started download like an automated one', async () => {
+      const session = createFakeCdpSession();
+      manager = await cdpManagerOver(session);
+      const completed = collect(DOWNLOAD_EVENT.COMPLETED);
+
+      const guid = 'guid-0001';
+      session.emit('Browser.downloadWillBegin', {
+        guid,
+        url: 'https://example.com/manual.pdf',
+        suggestedFilename: 'manual.pdf',
+      });
+      await fs.writeFile(
+        path.join(root, STAGING_DIRECTORY, guid),
+        'manual body'
+      );
+      session.emit('Browser.downloadProgress', { guid, state: 'completed' });
+      await manager.idle();
+
+      assert.strictEqual(completed.length, 1);
+      assert.strictEqual(completed[0].path, path.join(root, 'manual.pdf'));
+      assert.strictEqual(
+        await fs.readFile(completed[0].path, 'utf8'),
+        'manual body'
+      );
+      // The staged copy is the engine's, not the user's: it does not linger.
+      assert.deepStrictEqual(
+        await fs.readdir(path.join(root, STAGING_DIRECTORY)),
+        []
+      );
+    });
+
+    it('should report a download the browser refused', async () => {
+      const session = createFakeCdpSession();
+      manager = await cdpManagerOver(session);
+      const cancelled = collect(DOWNLOAD_EVENT.CANCELLED);
+
+      session.emit('Browser.downloadWillBegin', {
+        guid: 'guid-0002',
+        url: 'https://example.com/blocked.exe',
+        suggestedFilename: 'blocked.exe',
+      });
+      session.emit('Browser.downloadProgress', {
+        guid: 'guid-0002',
+        state: 'canceled',
+      });
+      await yieldToEngine();
+
+      assert.strictEqual(cancelled.length, 1);
+      assert.match(cancelled[0].failure, /canceled/);
+    });
+
+    it('should wait for staged bytes that land after the completion event', async () => {
+      // Issue #92: Chromium writes `<guid>.crdownload` and renames it, so the
+      // completion event can arrive before `<guid>` is openable. Publishing on
+      // the event alone turned a download that succeeded into
+      // `ENOENT ... .browser-commander-staging/<guid>`.
+      const session = createFakeCdpSession();
+      manager = await cdpManagerOver(session);
+      const completed = collect(DOWNLOAD_EVENT.COMPLETED);
+      const failed = collect(DOWNLOAD_EVENT.FAILED);
+
+      const guid = 'guid-0010';
+      const stagedPath = path.join(root, STAGING_DIRECTORY, guid);
+      session.emit('Browser.downloadWillBegin', {
+        guid,
+        url: 'https://example.com/late.pdf',
+        suggestedFilename: 'late.pdf',
+      });
+      // The event first, the bytes afterwards - the ordering from the report.
+      session.emit('Browser.downloadProgress', { guid, state: 'completed' });
+      await yieldToEngine();
+      assert.deepStrictEqual(completed, [], 'published before the bytes exist');
+      await fs.writeFile(stagedPath, 'late body');
+
+      await manager.idle();
+
+      assert.deepStrictEqual(failed, []);
+      assert.strictEqual(completed.length, 1);
+      assert.strictEqual(
+        await fs.readFile(completed[0].path, 'utf8'),
+        'late body'
+      );
+      assert.deepStrictEqual(
+        await fs.readdir(path.join(root, STAGING_DIRECTORY)),
+        []
+      );
+    });
+
+    it('should not claim bytes while the partial file is still being written', async () => {
+      const session = createFakeCdpSession();
+      manager = await cdpManagerOver(session);
+      const completed = collect(DOWNLOAD_EVENT.COMPLETED);
+
+      const guid = 'guid-0011';
+      const stagedPath = path.join(root, STAGING_DIRECTORY, guid);
+      session.emit('Browser.downloadWillBegin', {
+        guid,
+        url: 'https://example.com/partial.pdf',
+        suggestedFilename: 'partial.pdf',
+      });
+      // A half-written file under the final name, with Chromium's own
+      // in-progress marker still beside it.
+      await fs.writeFile(stagedPath, 'half');
+      await fs.writeFile(`${stagedPath}.crdownload`, 'rest');
+      session.emit('Browser.downloadProgress', { guid, state: 'completed' });
+      await yieldToEngine();
+      await yieldToEngine();
+      assert.deepStrictEqual(completed, [], 'claimed a half-written file');
+
+      await fs.rm(`${stagedPath}.crdownload`);
+      await fs.writeFile(stagedPath, 'half and rest');
+      await manager.idle();
+
+      assert.strictEqual(completed.length, 1);
+      assert.strictEqual(
+        await fs.readFile(completed[0].path, 'utf8'),
+        'half and rest'
+      );
+    });
+
+    it('should report a completion whose bytes never arrive as a failure', async () => {
+      const session = createFakeCdpSession();
+      manager = await createDownloadManager({
+        engine: 'puppeteer',
+        directory: root,
+        browser: {
+          target: () => ({ createCDPSession: async () => session }),
+        },
+        stagingTimeout: 60,
+        stagingPollInterval: 5,
+      });
+      const failed = collect(DOWNLOAD_EVENT.FAILED);
+      const completed = collect(DOWNLOAD_EVENT.COMPLETED);
+
+      session.emit('Browser.downloadWillBegin', {
+        guid: 'guid-0012',
+        url: 'https://example.com/ghost.pdf',
+        suggestedFilename: 'ghost.pdf',
+      });
+      session.emit('Browser.downloadProgress', {
+        guid: 'guid-0012',
+        state: 'completed',
+      });
+      await manager.idle();
+
+      assert.deepStrictEqual(completed, []);
+      assert.strictEqual(failed.length, 1);
+      assert.match(failed[0].failure, /was not readable within 60ms/);
+      assert.match(failed[0].failure, /guid-0012/);
+    });
+
+    it('should keep a capture waiting until the staged bytes are readable', async () => {
+      const session = createFakeCdpSession();
+      manager = await cdpManagerOver(session);
+
+      const guid = 'guid-0013';
+      const stagedPath = path.join(root, STAGING_DIRECTORY, guid);
+      const artifact = await manager.capture({
+        timeout: 5000,
+        action: async () => {
+          session.emit('Browser.downloadWillBegin', {
+            guid,
+            url: 'https://example.com/captured.pdf',
+            suggestedFilename: 'captured.pdf',
+          });
+          session.emit('Browser.downloadProgress', {
+            guid,
+            state: 'completed',
+          });
+          setTimeout(() => {
+            fs.writeFile(stagedPath, 'captured body').catch(() => {});
+          }, 40);
+        },
+      });
+
+      assert.strictEqual(artifact.state, DOWNLOAD_EVENT.COMPLETED);
+      assert.strictEqual(
+        await fs.readFile(artifact.path, 'utf8'),
+        'captured body'
+      );
+    });
+
+    it('should ignore progress for a download it never saw start', async () => {
+      const session = createFakeCdpSession();
+      manager = await cdpManagerOver(session);
+
+      session.emit('Browser.downloadProgress', {
+        guid: 'unknown',
+        state: 'completed',
+      });
+      await yieldToEngine();
+
+      assert.deepStrictEqual(manager.list(), []);
+    });
+  });
+});

package/tests/unit/downloads/naming.test.js

@@ -0,0 +1,174 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import path from 'node:path';
+
+import {
+  extensionFromContent,
+  isInsideRoot,
+  renamedCandidate,
+  resolveInsideRoot,
+  sanitizeDownloadName,
+  withExtension,
+} from '../../../src/downloads/naming.js';
+
+describe('download naming (issue #88)', () => {
+  describe('sanitizeDownloadName', () => {
+    it('should keep an ordinary name unchanged', () => {
+      assert.strictEqual(
+        sanitizeDownloadName('quarterly report.pdf'),
+        'quarterly report.pdf'
+      );
+    });
+
+    it('should refuse to let a page choose a directory', () => {
+      // A suggested filename is page-controlled input. `../../etc/passwd` is a
+      // request to write outside the download root, not a name.
+      assert.strictEqual(sanitizeDownloadName('../../etc/passwd'), 'passwd');
+      assert.strictEqual(
+        sanitizeDownloadName('C:\\Windows\\system32\\evil.exe'),
+        'evil.exe'
+      );
+      assert.strictEqual(sanitizeDownloadName('/etc/shadow'), 'shadow');
+    });
+
+    it('should strip control characters a name should never contain', () => {
+      assert.strictEqual(
+        sanitizeDownloadName('re\u0000port\u001f.pdf'),
+        'report.pdf'
+      );
+    });
+
+    it('should fall back when the page suggests nothing usable', () => {
+      assert.strictEqual(sanitizeDownloadName(''), 'download');
+      assert.strictEqual(sanitizeDownloadName('..'), 'download');
+      assert.strictEqual(sanitizeDownloadName('   '), 'download');
+      assert.strictEqual(sanitizeDownloadName(undefined), 'download');
+    });
+
+    it('should not slow down on a name padded with whitespace', () => {
+      // The padding used to be stripped with `/^\s+|[\s.]+$/`, whose second
+      // half retries from every position of a whitespace run that never
+      // reaches the end. A page chooses this string, so the cost is an
+      // attacker's to set: 40k spaces took 2.8 seconds before the trimming
+      // walked in from both ends instead, which takes under a millisecond.
+      const hostile = `report${' '.repeat(40_000)}x`;
+
+      const started = performance.now();
+      assert.strictEqual(sanitizeDownloadName(hostile), hostile);
+      assert.ok(performance.now() - started < 500);
+    });
+
+    it('should defuse reserved device names', () => {
+      // `con.txt` is unopenable on Windows, and a library that produces a file
+      // nobody can open has not really downloaded anything.
+      assert.strictEqual(sanitizeDownloadName('con.txt'), '_con.txt');
+      assert.strictEqual(sanitizeDownloadName('LPT1'), '_LPT1');
+    });
+  });
+
+  describe('withExtension', () => {
+    it('should leave a name that already has an extension alone', () => {
+      assert.strictEqual(
+        withExtension({ name: 'report.pdf', mimeType: 'text/csv' }),
+        'report.pdf'
+      );
+    });
+
+    it('should name a UUID-like download from its declared type', () => {
+      assert.strictEqual(
+        withExtension({
+          name: '3f2b7c1e-0a41-4f2a-9a55-7b1c2d3e4f50',
+          mimeType: 'application/pdf; charset=binary',
+        }),
+        '3f2b7c1e-0a41-4f2a-9a55-7b1c2d3e4f50.pdf'
+      );
+    });
+
+    it('should fall back to the bytes when the server declared nothing', () => {
+      assert.strictEqual(
+        withExtension({
+          name: 'mystery',
+          head: Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2d]),
+        }),
+        'mystery.pdf'
+      );
+    });
+
+    it('should trust the bytes over a generic binary type', () => {
+      // `application/octet-stream` is what a server sends when it cannot name
+      // the format either, so it must not win over a PDF signature and leave
+      // the caller with a `.bin` file it cannot open.
+      assert.strictEqual(
+        withExtension({
+          name: '3f2b7c1e-0a41-4f2a-9a55-7b1c2d3e4f50',
+          mimeType: 'application/octet-stream',
+          head: Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2d]),
+        }),
+        '3f2b7c1e-0a41-4f2a-9a55-7b1c2d3e4f50.pdf'
+      );
+    });
+
+    it('should still name a truly unidentifiable binary download', () => {
+      assert.strictEqual(
+        withExtension({
+          name: 'payload',
+          mimeType: 'application/octet-stream',
+          head: Buffer.from([0x01, 0x02]),
+        }),
+        'payload.bin'
+      );
+    });
+
+    it('should leave the name alone when nothing identifies the format', () => {
+      assert.strictEqual(
+        withExtension({ name: 'mystery', head: Buffer.from([0x01, 0x02]) }),
+        'mystery'
+      );
+    });
+  });
+
+  describe('extensionFromContent', () => {
+    it('should identify formats by their leading bytes', () => {
+      assert.strictEqual(
+        extensionFromContent(Buffer.from([0x89, 0x50, 0x4e, 0x47])),
+        '.png'
+      );
+      assert.strictEqual(
+        extensionFromContent(Buffer.from([0x50, 0x4b, 0x03, 0x04])),
+        '.zip'
+      );
+      assert.strictEqual(extensionFromContent(Buffer.alloc(0)), '');
+      assert.strictEqual(extensionFromContent(undefined), '');
+    });
+  });
+
+  describe('root containment', () => {
+    const root = path.resolve('/tmp/downloads');
+
+    it('should accept a file inside the root', () => {
+      assert.strictEqual(isInsideRoot(root, `${root}/report.pdf`), true);
+    });
+
+    it('should reject the root itself and anything outside it', () => {
+      assert.strictEqual(isInsideRoot(root, root), false);
+      assert.strictEqual(isInsideRoot(root, '/tmp/report.pdf'), false);
+      assert.strictEqual(isInsideRoot(root, `${root}/../report.pdf`), false);
+    });
+
+    it('should refuse to resolve a path that escapes the root', () => {
+      assert.throws(
+        () => resolveInsideRoot(root, '../escaped.pdf'),
+        /outside the download directory/
+      );
+    });
+  });
+
+  describe('renamedCandidate', () => {
+    it('should number collisions deterministically', () => {
+      assert.strictEqual(renamedCandidate('report.pdf', 0), 'report.pdf');
+      assert.strictEqual(renamedCandidate('report.pdf', 1), 'report (2).pdf');
+      assert.strictEqual(renamedCandidate('report.pdf', 2), 'report (3).pdf');
+      assert.strictEqual(renamedCandidate('archive', 1), 'archive (2)');
+    });
+  });
+});