browser-commander 0.28.0 → 0.30.0

package/src/traces/rolling-bundle.js

@@ -0,0 +1,240 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { openTraceBundle } from './bundle.js';
+import { createManifest } from './schema.js';
+
+/** Rotate complete bundles at the producer's write boundary, including background events. */
+export async function openRollingBundle(options, config, traceOptions) {
+  const root = path.resolve(options.output);
+  const maxBytes =
+    config.maxBytes ?? options.limits.maxBundleBytes ?? 32 * 1024 * 1024;
+  const maxSegments = config.maxSegments ?? Infinity;
+  if (
+    !Number.isSafeInteger(maxBytes) ||
+    maxBytes < 1024 ||
+    (maxSegments !== Infinity &&
+      (!Number.isSafeInteger(maxSegments) ||
+        maxSegments < 1 ||
+        maxSegments > 100))
+  ) {
+    throw new RangeError('invalid trace rotation bounds');
+  }
+  let current,
+    sequence = 0,
+    pinned = false,
+    base = null,
+    baseEvent = null;
+  let eventSequence = 0;
+  const segments = [],
+    writers = [];
+  let queue = Promise.resolve();
+  const run = (fn) => {
+    const result = queue.then(fn);
+    queue = result.catch(() => {});
+    return result;
+  };
+  const template = () =>
+    createManifest({
+      mode: traceOptions.mode ?? 'checkpoints',
+      engine: traceOptions.commander?.engine,
+      startedAt: new Date().toISOString(),
+      stoppedAt: new Date().toISOString(),
+      dom: traceOptions.dom,
+      limits: traceOptions.limits,
+    });
+  async function open() {
+    const name = `segment-${String(++sequence).padStart(6, '0')}`;
+    current = await openTraceBundle({
+      ...options,
+      output: path.join(root, name),
+      nextSequence: () => ++eventSequence,
+      limits: { ...options.limits, maxBundleBytes: Infinity },
+      onEvent: (event) => options.onEvent?.(event, { root: current.root }),
+    });
+    writers.push(current);
+    segments.push(name);
+    if (segments.length > maxSegments) {
+      await fs.rm(path.join(root, segments.shift()), {
+        recursive: true,
+        force: true,
+      });
+    }
+    await fs.writeFile(
+      path.join(root, 'segments.json.tmp'),
+      JSON.stringify({ segments }),
+      { mode: 0o600 }
+    );
+    await fs.rename(
+      path.join(root, 'segments.json.tmp'),
+      path.join(root, 'segments.json')
+    );
+  }
+  async function prepare(bytes, carry = false) {
+    if (
+      !pinned &&
+      current.bytesWritten > 0 &&
+      current.bytesWritten + bytes > maxBytes
+    ) {
+      await current.close(template());
+      if (sequence === 0) {
+        const name = 'segment-000001';
+        const destination = path.join(root, name);
+        await fs.mkdir(destination, { mode: 0o700 });
+        for (const member of [
+          'events.ndjson',
+          'manifest.json',
+          'checkpoints',
+          'mutations',
+          'artifacts',
+          'viewer.html',
+        ]) {
+          await fs
+            .rename(path.join(root, member), path.join(destination, member))
+            .catch((error) => {
+              if (error.code !== 'ENOENT') {
+                throw error;
+              }
+            });
+        }
+        sequence = 1;
+        segments.push(name);
+      }
+      await open();
+      if (carry && base && baseEvent) {
+        const members = await current.writeCheckpoint(base);
+        await current.appendEvent({
+          ...baseEvent,
+          members,
+          reason: 'rotation-base',
+        });
+      }
+    }
+  }
+  await fs.mkdir(root, { recursive: true, mode: 0o700 });
+  if (config.lazy) {
+    current = await openTraceBundle({
+      ...options,
+      nextSequence: () => ++eventSequence,
+      limits: { ...options.limits, maxBundleBytes: Infinity },
+    });
+    writers.push(current);
+  } else {
+    await open();
+  }
+  const counts = () =>
+    writers.reduce(
+      (sum, b) => {
+        for (const k of Object.keys(sum)) {
+          sum[k] += b.counts[k];
+        }
+        return sum;
+      },
+      { checkpoints: 0, events: 0, mutationBatches: 0 }
+    );
+  return {
+    root,
+    get currentPath() {
+      return current.root;
+    },
+    get segments() {
+      return [...segments];
+    },
+    get counts() {
+      return counts();
+    },
+    get problems() {
+      return writers.flatMap((b) => b.problems);
+    },
+    get dropped() {
+      return writers.reduce((sum, b) => sum + b.dropped, 0);
+    },
+    get bytesWritten() {
+      return current.bytesWritten;
+    },
+    get mutationTruncated() {
+      return current.mutationTruncated;
+    },
+    appendEvent: (event) =>
+      run(async () => {
+        await prepare(Buffer.byteLength(JSON.stringify(event)) + 256, true);
+        const result = await current.appendEvent(event);
+        if (event.kind === 'checkpoint') {
+          baseEvent = result;
+        }
+        if (
+          event.kind === 'checkpoint' ||
+          (event.kind === 'mutations' && pinned === 'mutations')
+        ) {
+          pinned = false;
+        }
+        return result;
+      }),
+    writeCheckpoint: (checkpoint) =>
+      run(async () => {
+        const bytes =
+          Buffer.byteLength(checkpoint.html ?? '') +
+          Buffer.byteLength(JSON.stringify(checkpoint.state ?? {})) +
+          (checkpoint.screenshot?.length ?? 0) +
+          1024;
+        await prepare(bytes);
+        pinned = 'checkpoint';
+        base = checkpoint;
+        return current.writeCheckpoint(checkpoint);
+      }),
+    writeMutations: (index, batches) =>
+      run(async () => {
+        await prepare(Buffer.byteLength(JSON.stringify(batches)) + 256, true);
+        const result = await current.writeMutations(index, batches);
+        if (pinned !== 'checkpoint') {
+          pinned = result ? 'mutations' : false;
+        }
+        return result;
+      }),
+    writeMember: (member, contents, writeOptions) =>
+      run(async () => {
+        await prepare(Buffer.byteLength(contents));
+        return current.writeMember(member, contents, writeOptions);
+      }),
+    writeArtifact: (contents, extension) =>
+      run(async () => {
+        await prepare(Buffer.byteLength(contents));
+        const result = await current.writeArtifact(contents, extension);
+        return result
+          ? {
+              ...result,
+              member: segments.length
+                ? `${segments.at(-1)}/${result.member}`
+                : result.member,
+            }
+          : null;
+      }),
+    drop: (record) => run(() => current.drop(record)),
+    abort: () => run(() => current.abort()),
+    close: (manifest) =>
+      run(async () => {
+        manifest = await current.close(manifest);
+        if (writers.some((writer) => writer.dropped)) {
+          manifest.outcome = 'partial';
+        }
+        // Finished segments get the final capabilities and outcome as well.
+        for (const name of segments) {
+          const file = path.join(root, name, 'manifest.json');
+          const previous = JSON.parse(await fs.readFile(file, 'utf8'));
+          await fs.writeFile(
+            file,
+            JSON.stringify({
+              ...manifest,
+              counts: previous.counts,
+              dropped: previous.dropped,
+            }),
+            { mode: 0o600 }
+          );
+        }
+        return {
+          ...manifest,
+          counts: counts(),
+          dropped: writers.reduce((sum, b) => sum + b.dropped, 0),
+        };
+      }),
+  };
+}

package/src/traces/rolling.js

@@ -1,120 +1,15 @@
-import fs from 'node:fs/promises';
 import path from 'node:path';
 
-/** Bounded complete bundles, each independently readable after a crash. */
+/** Keep the ordinary trace handle while routing every write through rotation. */
 export async function startRollingTrace(options, start) {
+  const { openRollingBundle } = await import('./rolling-bundle.js');
   const config = options.limits.rotate === true ? {} : options.limits.rotate;
-  const maxBytes =
-    config.maxBytes ?? options.limits.maxBundleBytes ?? 32 * 1024 * 1024;
-  const maxSegments = config.maxSegments ?? 4;
-  if (
-    !Number.isSafeInteger(maxBytes) ||
-    maxBytes < 1024 ||
-    !Number.isSafeInteger(maxSegments) ||
-    maxSegments < 1 ||
-    maxSegments > 100
-  ) {
-    throw new RangeError('invalid trace rotation bounds');
-  }
-  const root = path.resolve(options.output);
-  await fs.mkdir(root, { recursive: true, mode: 0o700 });
-  let current,
-    sequence = 0,
-    stopping,
-    failure,
-    ticking = false;
-  const segments = [];
-  let queue = Promise.resolve();
-  const enqueue = (action) => {
-    const task = queue.then(action);
-    queue = task.catch((error) => {
-      failure ??= error;
-    });
-    return task;
-  };
-  async function open() {
-    const name = `segment-${String(++sequence).padStart(6, '0')}`;
-    const output = path.join(root, name);
-    current = await start({
-      ...options,
-      output,
-      limits: { ...options.limits, rotate: false, maxBundleBytes: maxBytes },
-      links: options.links
-        ? { ...options.links, output: path.join(output, 'trace.lino') }
-        : null,
-    });
-    segments.push(name);
-    while (segments.length > maxSegments) {
-      await fs.rm(path.join(root, segments.shift()), {
-        recursive: true,
-        force: true,
-      });
-    }
-    const temporary = path.join(root, 'segments.json.tmp');
-    await fs.writeFile(temporary, JSON.stringify({ segments }), {
-      mode: 0o600,
-    });
-    await fs.rename(temporary, path.join(root, 'segments.json'));
-  }
-  await open();
-  const timer = setInterval(() => {
-    if (!stopping && !ticking) {
-      ticking = true;
-      enqueue(async () => {
-        if (current.bytesWritten >= maxBytes * 0.8) {
-          await current.stop();
-          await open();
-        }
-      })
-        .catch(() => clearInterval(timer))
-        .finally(() => {
-          ticking = false;
-        });
-    }
-  }, 100);
-  timer.unref?.();
-  return {
-    path: root,
-    mode: options.mode,
-    checkpoint: (...args) =>
-      enqueue(() => {
-        if (stopping) {
-          throw new Error('trace has stopped');
-        }
-        return current.checkpoint(...args);
-      }),
-    event: (...args) =>
-      enqueue(async () => {
-        if (stopping) {
-          throw new Error('trace has stopped');
-        }
-        if (
-          current.bytesWritten +
-            Buffer.byteLength(JSON.stringify(args)) +
-            256 >=
-          maxBytes * 0.8
-        ) {
-          await current.stop();
-          await open();
-        }
-        return current.event(...args);
-      }),
-    stop: (...args) => {
-      stopping ??= (async () => {
-        clearInterval(timer);
-        await queue;
-        const result = await current.stop(...args);
-        if (args[0]?.discard) {
-          await fs.rm(root, { recursive: true, force: true });
-        }
-        if (failure) {
-          throw failure;
-        }
-        return { ...result, path: root, segments: [...segments] };
-      })();
-      return stopping;
-    },
-  };
+  return start({
+    ...options,
+    limits: { ...options.limits, rotate: false },
+    openBundle: (bundleOptions) =>
+      openRollingBundle(bundleOptions, config, options),
+  });
 }
 
 /** Combine segment timelines while keeping checkpoint member paths distinct. */
@@ -174,6 +69,8 @@ export async function readRollingTrace(root, index, read) {
       locations.get(index)?.opened.html(locations.get(index).index),
     state: (index) =>
       locations.get(index)?.opened.state(locations.get(index).index),
+    screenshot: (index) =>
+      locations.get(index)?.opened.screenshot(locations.get(index).index),
     mutations: (index) =>
       locations.get(index)?.opened.mutations(locations.get(index).index) ?? [],
   };

package/src/traces/stop.js

@@ -134,6 +134,7 @@ export function createTraceStop(context) {
       checkpoints: [...checkpoints],
       problems: [...bundle.problems, ...(linksSink?.problems ?? [])],
       links: linksSink?.path ?? null,
+      ...(bundle.segments?.length ? { segments: bundle.segments } : {}),
     };
     setStopped(result);