@shotkit/shotium 0.1.0 → 0.3.0

package/src/lib/daemon.ts

@@ -1,13 +1,19 @@
 import {EventEmitter} from 'node:events';
 import fs from 'node:fs';
 import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
 
-import type {DaemonOptions, DaemonStatus} from '../types.js';
+import type {
+  CaptureStats,
+  DaemonOptions,
+  DaemonStatus,
+} from '../types.js';
 
 import {resolveStartOptions} from './config.js';
 import type {ResolvedStartOptions} from './config.js';
 import {endpointFor} from './endpoint.js';
-import {Pool} from './pool.js';
+import {Engine} from './engine.js';
 import {FrameReader, encodeFrame} from './protocol.js';
 import type {WireRequest} from './request.js';
 
@@ -25,11 +31,6 @@ const VERSION = (() => {
   }
 })();
 
-// How much longer than the page's own deadline the daemon waits before it
-// decides a worker is not going to answer at all. Same margin, same reasoning
-// as index.ts: the worker fails a slow page by itself and replies.
-const SUPERVISOR_MARGIN_MS = 10000;
-const DEFAULT_TIMEOUT_MS = 30000;
 const DEFAULT_IDLE_TIMEOUT_MS = 300000;
 
 // One message off the socket. `op` defaults to screenshot because that is what
@@ -49,32 +50,46 @@ interface DaemonReply {
   bytes?: number;
   path?: string;
   stopping?: boolean;
+  // What the capture cost, on the success header and on the failure one. The
+  // client turns it back into the same CaptureStats the in-process engine
+  // returns, so a program moving between the two changes an import and
+  // nothing else.
+  stats?: CaptureStats;
 }
 
-// A worker pool that outlives the process that asked for it.
+// An engine that outlives the process that asked for it.
 //
-// The pool in index.ts is already resident, but only for as long as the Node
+// The engine in index.ts is already resident, but only for as long as the Node
 // process holding it: a command-line invocation, a CI step, a serverless
-// handler and a `node -e` all pay for starting workers and then throw them
-// away. This is the same pool behind a socket, so the second caller -- in a
+// handler and a `node -e` all pay for starting Blink and then throw it away.
+// This is the same engine behind a socket, so the second caller -- in a
 // different process, minutes later -- pays a connect() and nothing else.
 //
-// The wire format is the worker's own, one level up: a request frame of JSON,
-// answered by a header frame and a payload frame. What it adds is `id`, so one
-// connection can have several requests in flight; the worker protocol cannot,
-// because a worker renders one document at a time, and multiplexing is exactly
-// what the pool in the middle is for.
+// A request frame of JSON, answered by a header frame and a payload frame:
 //
 //   ->  [len][{"id":7,"op":"screenshot","request":{...}}]
 //   <-  [len][{"id":7,"ok":true,"bytes":97756}]  [len][<PNG>]
 //
-// Events: ready, request, response, idle-exit, error, plus the pool's own.
+// `id` is on the wire so that a client may have several requests outstanding
+// on one connection. That is a convenience for the client, not concurrency:
+// there is one renderer here, because Blink is a process-wide singleton, so
+// the requests queue and come back in the order the engine finished them.
+// Wanting two at once means wanting two daemons, addressed by `name`.
+//
+// Nothing supervises a capture. The pool this replaced could time a worker out
+// and kill it; an in-process engine has no such seam -- there is no way to
+// abandon a render without abandoning the process. A page's own deadline
+// (`pageGotoParams.timeout`) is what bounds it, and the engine answers slow
+// pages by itself. `timeout` and `retry` on the wire are accepted and ignored,
+// so that an older client still talks to this.
+//
+// Events: ready, warm, request, response, idle-exit, error, close.
 class Daemon extends EventEmitter {
   private readonly options: ResolvedStartOptions;
   private readonly endpointPath: string;
   private readonly idleTimeoutMs: number;
   private readonly prewarmOnStart: boolean;
-  private pool: Pool|null = null;
+  private readonly engine = new Engine();
   private server: net.Server|null = null;
   private sockets = new Set<net.Socket>();
   private inFlight = 0;
@@ -106,24 +121,21 @@ class Daemon extends EventEmitter {
     return this.warmed;
   }
 
-  // Brings the pool up and starts listening. The pipe existing *is* the
+  // Brings the engine up and starts listening. The pipe existing *is* the
   // readiness signal -- a client's connect() either succeeds or the daemon is
-  // not up -- so nothing is bound until the pool has been asked to start.
+  // not up -- so nothing is bound until the engine has started.
+  //
+  // Starting it here rather than on the first request is deliberate: a machine
+  // with no engine for its platform should fail while the caller is still
+  // watching, not answer a connect() and then reject every request on it.
   async listen(): Promise<this> {
-    const pool = new Pool(this.options);
-    this.pool = pool;
-    for (const event of ['exit', 'crash', 'timeout', 'worker-restart',
-                         'worker-error', 'stderr']) {
-      pool.on(event, (payload) => this.emit(event, payload));
-    }
-    pool.start();
+    this.engine.start(this.options);
 
     this.server = net.createServer((socket) => this.accept(socket));
     this.server.on('error', (error) => this.emit('error', error));
     await this.bind();
     this.armIdleTimer();
-    this.emit('ready',
-              {endpoint: this.endpointPath, workers: this.options.workers});
+    this.emit('ready', {endpoint: this.endpointPath});
     if (this.prewarmOnStart) {
       await this.prewarm();
     }
@@ -178,8 +190,8 @@ class Daemon extends EventEmitter {
   //
   // On Windows it is a named pipe, and node exposes no way to give one an ACL:
   // the default lets any account on the machine open it. A daemon on a shared
-  // Windows host is therefore as trusted as the machine's users are -- render
-  // in-process, or with a binary that has no file access, if that is not
+  // Windows host is therefore as trusted as the machine's users are -- use the
+  // engine in your own process, where nothing is listening, if that is not
   // acceptable.
   private restrict(): void {
     if (process.platform === 'win32') {
@@ -192,23 +204,37 @@ class Daemon extends EventEmitter {
     }
   }
 
-  // Renders one throwaway document per worker so that the first real request
-  // does not pay for whatever each process initialises lazily. The pool hands
-  // one request to each free worker, and there are exactly as many requests as
-  // workers, so every process is touched.
+  // Renders one throwaway document so that the first real request does not pay
+  // for whatever the engine initialises lazily. One is enough: there is one
+  // renderer, and it is the same one every request lands on.
+  //
+  // A temporary file, not a `data:` URL. This used to send
+  // `data:text/html,...`, which the renderer rejects -- shot_capture.cc takes
+  // file, http and https and nothing else -- so every prewarm failed into the
+  // catch below and the step had never once done anything. The failure was
+  // invisible because a prewarm that does not work looks exactly like one that
+  // does, only slower on the first request.
   //
-  // `data:` rather than a file, because a daemon started without
-  // --allow-file-access would otherwise be prewarmed by a request it refuses.
+  // The document names no subresources, so it renders identically whether or
+  // not this daemon allows file access -- which is what the `data:` URL was
+  // reaching for. A top-level file: URL always loads; `allowFileAccess` gates
+  // what the document may then pull in.
   async prewarm(): Promise<void> {
-    const blank = 'data:text/html,<!doctype html><title>shotium</title>';
-    await Promise.all(Array.from({length: this.options.workers}, () => {
-      return this.pool!
-          .submit({file: blank, width: 16, height: 16},
-                  {timeout: DEFAULT_TIMEOUT_MS + SUPERVISOR_MARGIN_MS, retry: 1})
-          .catch(() => null);
-    }));
-    this.warmed = true;
-    this.emit('warm', {workers: this.options.workers});
+    const blank = path.join(
+        os.tmpdir(), `shotium-prewarm-${process.pid}.html`);
+    try {
+      fs.writeFileSync(
+          blank, '<!doctype html><title>shotium</title><p>shotium');
+      await this.engine.capture({file: blank, width: 16, height: 16});
+      this.warmed = true;
+    } catch (error) {
+      // Not fatal: a daemon that could not prewarm still serves. But it is not
+      // warm, and status() should not claim it is.
+      this.emit('error', error);
+    } finally {
+      fs.rmSync(blank, {force: true});
+    }
+    this.emit('warm', {warm: this.warmed});
   }
 
   status(): DaemonStatus {
@@ -216,10 +242,9 @@ class Daemon extends EventEmitter {
       ok: true,
       pid: process.pid,
       endpoint: this.endpointPath,
-      binary: this.options.binary,
-      workers: this.options.workers,
       cacheDir: this.options.cacheDir,
-      args: this.options.args,
+      userAgent: this.options.userAgent,
+      resourceDir: this.options.resourceDir,
       warm: this.warmed,
       uptimeMs: Date.now() - this.startedAt,
       connections: this.sockets.size,
@@ -285,30 +310,34 @@ class Daemon extends EventEmitter {
     }
 
     const request = message.request || ({} as WireRequest);
-    const timeout = (typeof message.timeout === 'number' ? message.timeout :
-                                                           DEFAULT_TIMEOUT_MS) +
-        SUPERVISOR_MARGIN_MS;
-    const retry = typeof message.retry === 'number' ? message.retry : 0;
 
     this.inFlight += 1;
     this.armIdleTimer();
     this.emit('request', {id, file: request.file});
-    this.pool!.submit(request, {timeout, retry})
-        .then((result) => {
+    this.engine.capture(request)
+        .then(({image, stats}) => {
           this.served += 1;
           this.reply(
               socket,
               {
                 id,
                 ok: true,
-                bytes: result.image ? result.image.length : 0,
-                path: result.header ? result.header.path : undefined,
+                bytes: image ? image.length : 0,
+                path: request.path,
+                stats,
               },
-              result.image);
+              image);
         })
-        .catch((error: Error) => {
-          this.reply(
-              socket, {id, ok: false, error: String(error.message || error)});
+        .catch((error: Error&{stats?: CaptureStats}) => {
+          // The counters go back with the failure, matching the in-process
+          // engine: a capture that timed out after fetching forty subresources
+          // has already said why, and the message alone has not.
+          this.reply(socket, {
+            id,
+            ok: false,
+            error: String(error.message || error),
+            stats: error.stats,
+          });
         })
         .finally(() => {
           this.inFlight -= 1;
@@ -362,7 +391,13 @@ class Daemon extends EventEmitter {
     }
     this.sockets.clear();
     await new Promise<void>((resolve) => this.server!.close(() => resolve()));
-    await this.pool!.stop();
+    // dispose() rather than stop(), and this is the one caller that should.
+    // The daemon owns its process and is leaving it, so the real teardown is
+    // available and worth taking: joining the engine thread unwinds the
+    // network stack, which is what lets the disk cache write its index. A
+    // daemon that merely stood the engine down would leave the index dirty and
+    // make the next daemon rebuild it by scanning the directory.
+    await this.engine.dispose();
     this.emit('close', {});
   }
 }

package/src/lib/endpoint.ts

@@ -5,21 +5,27 @@ import path from 'node:path';
 // What endpointFor() needs to know: a resolved configuration, plus the two
 // ways of overriding the address it would derive from one.
 export interface EndpointOptions {
-  binary?: string;
-  workers?: number;
   cacheDir?: string|null;
-  args?: string[];
+  userAgent?: string;
+  resourceDir?: string;
   name?: string;
   endpoint?: string;
 }
 
 // Where a daemon listens, derived from what it was asked to be.
 //
-// The address is a hash of the configuration -- binary, worker count, cache
-// root, extra flags -- rather than a fixed name, because attaching to whatever
-// daemon happens to be up would mean rendering with someone else's binary and
-// someone else's flags. Two configurations are two daemons; the same
-// configuration, from any process, is one.
+// The address is a hash of the configuration -- cache root, user agent,
+// resource directory -- rather than a fixed name, because attaching to
+// whatever daemon happens to be up would mean rendering with someone else's
+// settings. Two configurations are two daemons; the same configuration, from
+// any process, is one.
+//
+// Every field of EndpointOptions is optional, so nothing here fails to compile
+// when a field is dropped from the configuration -- it just stops being part
+// of the identity, and every caller collapses onto one address. That happened
+// once, when the worker pool went away and this was left hashing three fields
+// that no longer existed. If a field is added to StartOptions and it changes
+// what the engine renders, it belongs in the array below.
 //
 // A caller who wants a daemon by name instead of by configuration passes
 // `name`, which replaces the hash. That is the escape hatch for a service that
@@ -30,10 +36,11 @@ function endpointKey(options: EndpointOptions): string {
     return String(options.name);
   }
   const identity = JSON.stringify([
-    path.resolve(options.binary || ''),
-    options.workers,
-    options.cacheDir === null ? null : path.resolve(options.cacheDir || ''),
-    options.args || [],
+    options.cacheDir === null || options.cacheDir === undefined ?
+        null :
+        path.resolve(options.cacheDir),
+    options.userAgent ?? null,
+    options.resourceDir ? path.resolve(options.resourceDir) : null,
   ]);
   return crypto.createHash('sha256').update(identity).digest('hex').slice(0, 16);
 }

package/src/lib/engine.ts

@@ -0,0 +1,356 @@
+import * as binding from './binding.js';
+import type {Engine as Handle} from './binding.js';
+import {toRequest} from './request.js';
+import type {WireRequest} from './request.js';
+import type {
+  CaptureStats,
+  ReleaseMemoryOptions,
+  ScreenshotOptions,
+  ScreenshotResult,
+  StartOptions,
+  StartResult,
+} from '../types.js';
+
+import type {ResolvedStartOptions} from './config.js';
+import {resolveStartOptions} from './config.js';
+
+// The engine this process has, held above every Engine object that uses it.
+//
+// Blink is initialised once and has no undo: it writes process-wide statics
+// that shot_engine_destroy() cannot take back, and the C API refuses a second
+// create for the lifetime of the process whether or not the first is still
+// alive.
+//
+// That fact used to be exposed directly -- `stop()` destroyed the engine and
+// every later `start()` threw. It was the wrong shape. `stop()` and `start()`
+// are a caller saying "I am done for now" and "I want it again", and a library
+// whose engine can be asked for exactly once turns an ordinary pair of calls
+// into a thing that has to be rationed. It also made the disk cache
+// nonsensical: the whole point of a cache is the *next* run, and the next run
+// could not have the engine that reads it.
+//
+// So the handle lives here rather than on the instance. `stop()` stands the
+// engine down -- the queue drains, the memory goes back, nothing more is
+// accepted -- and `start()` picks the same one up again, as many times as a
+// caller likes. The process is the engine's lifetime, which is what it always
+// was; the difference is that the API no longer pretends to offer a shorter
+// one.
+let shared: Handle|null = null;
+
+// What `shared` was created with. Kept because those options are fixed for the
+// life of the process -- a later `start()` asking for a different cache
+// directory cannot be given one, and is told so rather than handed an engine
+// that quietly uses the first caller's.
+let sharedOptions: ResolvedStartOptions|null = null;
+
+// Whether the one create this process gets has been spent.
+//
+// Separate from `shared` being non-null because `dispose()` clears the handle
+// and does not give the ability back: after a real teardown there is no engine
+// and there cannot be another. Nothing in the public surface calls dispose()
+// -- the daemon does, on its way out of a process it owns.
+let spent = false;
+
+/** The engine handle this process has, or null if it has none. */
+function sharedHandle(): Handle|null {
+  return shared;
+}
+
+// The options that are fixed at create time, and the report a mismatch gets.
+//
+// Only the ones the caller actually named are checked: `start()` with no
+// arguments is a caller saying "whatever is there", which is exactly what
+// adopting a running engine gives them. Naming an option that disagrees is
+// different -- it is a request that cannot be honoured, and silently rendering
+// with the other value is the failure this exists to prevent.
+function conflictingOption(
+    options: StartOptions, current: ResolvedStartOptions): string|null {
+  const wanted = resolveStartOptions(options);
+  for (const key of ['cacheDir', 'cacheMaxBytes', 'userAgent', 'resourceDir'] as
+       const) {
+    if (options[key] === undefined || wanted[key] === current[key]) {
+      continue;
+    }
+    return `${key} is ${JSON.stringify(current[key])}, and this start() ` +
+        `asked for ${JSON.stringify(wanted[key])}`;
+  }
+  return null;
+}
+
+/**
+ * Blink, in this process, and the queue in front of it.
+ *
+ * There is one renderer and there is no way to have two. Blink is a
+ * process-wide singleton: it is initialised once, there is no path to a second
+ * one, and `worker_threads` do not change that because they share the process.
+ * So captures are serialised however many callers there are, and a program
+ * that wants four at once wants four processes.
+ *
+ * The queue is not about fairness. Each capture occupies a libuv thread pool
+ * thread for as long as the render takes, and there are four of those by
+ * default, shared with fs and dns -- so letting four screenshots go at once
+ * would stall the host's file reads for a fifth of a second at a time while
+ * gaining nothing, since the engine serialises them anyway.
+ */
+export class Engine {
+  // Whether *this* object considers itself started. The engine behind it may
+  // well be up for somebody else; `running` is about this lifecycle, not about
+  // whether the process has an engine.
+  private active = false;
+  private tail: Promise<unknown> = Promise.resolve();
+
+  get running(): boolean {
+    return this.active && shared !== null;
+  }
+
+  /**
+   * The addon's engine handle, or null when this process has never had one.
+   *
+   * Deliberately not conditional on `running`. It is the cache that asks, and
+   * what the cache needs to know is whether a backend exists in this process
+   * -- because within one process a cache directory has one backend, so
+   * reading or clearing the directory the engine holds means borrowing it
+   * rather than opening a second one. A stood-down engine still holds its
+   * directory, so a caller who calls `stop()` and then `cache.getFiles()` is
+   * asking about a live backend and has to be routed to it. Nothing else
+   * should reach for this.
+   */
+  get nativeHandle(): Handle|null {
+    return sharedHandle();
+  }
+
+  /**
+   * Starts the engine, or picks the running one back up.
+   *
+   * Callable as often as a caller likes, in any order with `stop()`. The first
+   * call in a process builds the engine; every later one adopts it, which is
+   * the same engine and the same warm cache. Library code can call it
+   * defensively.
+   *
+   * The one thing that cannot be adopted is a different configuration. The
+   * options below are fixed when the engine is built and there is no second
+   * build, so naming one that disagrees with what is running throws rather
+   * than rendering with a value the caller did not ask for.
+   */
+  start(options: StartOptions = {}): StartResult {
+    if (shared) {
+      const conflict = conflictingOption(options, sharedOptions!);
+      if (conflict) {
+        throw new Error(
+            'shotium: this process already has an engine, and its ' +
+            conflict + '. Blink is initialised once per process and cannot ' +
+            'be built again, so an engine\'s options are fixed for as long ' +
+            'as the process lives -- stop() does not undo them. Use the ' +
+            'engine that is up, or run another process.');
+      }
+      this.active = true;
+      return this.status();
+    }
+    if (spent) {
+      throw new Error(
+          'shotium: this process had an engine and it was disposed of. ' +
+          'Blink is initialised once per process and cannot be built again. ' +
+          'Run another process.');
+    }
+
+    const native = binding.load();
+    const resolved = resolveStartOptions(options);
+
+    const engineOptions: Record<string, unknown> = {};
+    if (resolved.cacheDir !== null) {
+      engineOptions.cacheDir = resolved.cacheDir;
+      engineOptions.cacheMaxBytes = resolved.cacheMaxBytes;
+    }
+    if (resolved.userAgent !== undefined) {
+      engineOptions.userAgent = resolved.userAgent;
+    }
+    // The packs sit beside the library, and the library cannot find itself on
+    // Linux -- the path the engine resolves for "this module" goes through
+    // /proc/self/exe, which names node. Saying it here is cheaper than
+    // teaching the engine a second way to look. See shot_api.h.
+    engineOptions.resourceDir = resolved.resourceDir ?? binding.directory();
+
+    shared = native.create(JSON.stringify(engineOptions));
+    sharedOptions = resolved;
+    this.active = true;
+    return this.status();
+  }
+
+  /**
+   * What the engine came up as: whether this lifecycle is started, which cache
+   * directory the engine has, and whether it actually got it.
+   *
+   * The last of those is the one worth reading. A directory that cannot be
+   * created or written to -- no permission, no space, a path that is a file --
+   * fails invisibly: the engine renders exactly as well without a cache, only
+   * slower, and every capture pays the network again for a reason nothing
+   * reports. The engine opens the cache during `start()` so that this is
+   * answerable before the first screenshot rather than after it.
+   *
+   * The cache half is answered from the engine whenever this process has one,
+   * including after `stop()`. A stood-down engine still holds its directory,
+   * and reporting `null` for it would say the cache had gone away when what
+   * went away was the willingness to render.
+   */
+  status(): StartResult {
+    if (!shared) {
+      return {running: false, cacheDir: null, cacheActive: false};
+    }
+    const reported =
+        JSON.parse(binding.load().status(shared)) as Omit<StartResult, 'running'>;
+    return {running: this.running, ...reported};
+  }
+
+  /**
+   * Stands the engine down, after whatever is queued.
+   *
+   * The queue drains, the memory the engine can rebuild goes back to the OS,
+   * and `running` becomes false. What does not happen is a teardown of Blink,
+   * because there is no such thing -- see the note at the top of this file --
+   * so the disk cache stays where it is and `start()` picks the same engine up
+   * again whenever the caller wants it.
+   *
+   * Which makes this exactly what it says: not a destructor, a caller saying
+   * they are done for now. A program that will want another screenshot in a
+   * moment can equally well stay started and call `releaseMemory()`; the two
+   * do the same work, and this one also stops accepting captures.
+   */
+  async stop(): Promise<void> {
+    if (!this.active) {
+      return;
+    }
+    this.active = false;
+    // After the queue, not before: a caller's last screenshot should resolve
+    // rather than race the stand-down, and the memory is not worth handing
+    // back until the thing still using it has finished.
+    await this.tail.catch(() => {});
+    if (shared) {
+      binding.load().purge(shared, /*releaseWorkingSet=*/ true);
+    }
+  }
+
+  /**
+   * The real teardown: joins the engine thread, unwinds the network stack, and
+   * lets the disk cache write its index.
+   *
+   * Final, and final for the process rather than for this object -- which is
+   * why it is not on the public surface. The daemon calls it as it exits a
+   * process it owns, where the index flush is worth having and nothing is
+   * going to ask for another screenshot. Everything else wants `stop()`.
+   */
+  async dispose(): Promise<void> {
+    this.active = false;
+    await this.tail.catch(() => {});
+    const handle = shared;
+    shared = null;
+    sharedOptions = null;
+    if (handle) {
+      spent = true;
+      binding.load().destroy(handle);
+    }
+  }
+
+  /**
+   * Hands back what the engine is holding but can rebuild.
+   * `releaseWorkingSet` additionally asks the OS for the pages, which the next
+   * screenshot pays back in soft faults -- worth it when there may not be a
+   * next one soon.
+   *
+   * The daemon does this for itself on a timer because it can watch its own
+   * request stream go quiet. Here the queue belongs to the caller, so the
+   * caller is the one who knows a batch has ended.
+   */
+  releaseMemory({releaseWorkingSet = false}: ReleaseMemoryOptions = {}): void {
+    if (!shared) {
+      return;
+    }
+    binding.load().purge(shared, releaseWorkingSet);
+  }
+
+  /**
+   * Renders one screenshot. Resolves to the encoded image, or to `null` when
+   * `path` was given and the engine wrote the file itself.
+   */
+  // `async` and not a plain function returning capture()'s promise: toRequest()
+  // throws, and a caller who wrote `screenshot(bad).catch(...)` would get the
+  // throw past the catch and into the surrounding frame. The whole surface is
+  // promise-shaped, so a bad request is a rejection like everything else.
+  async screenshot(options: ScreenshotOptions): Promise<ScreenshotResult> {
+    // Before anything else, and before the queue: a malformed request should
+    // be a rejection now rather than one that waits its turn.
+    return this.capture(toRequest(options));
+  }
+
+  /**
+   * The same, for a request that is already in wire form.
+   *
+   * The daemon reads these off a socket, where they arrived having been
+   * validated by the client that sent them. Re-deriving one from
+   * ScreenshotOptions would mean the daemon validating a request it cannot see
+   * the original of, and rejecting fields a newer client legitimately sent.
+   */
+  async capture(request: WireRequest): Promise<ScreenshotResult> {
+    // Starts, or restarts, or adopts -- a screenshot after `stop()` is an
+    // ordinary thing to ask for and gets the engine back.
+    if (!this.running) {
+      this.start();
+    }
+    const handle = shared!;
+    const native = binding.load();
+
+    // Chain onto the tail so that captures run one at a time. The catch keeps
+    // one failure from poisoning everything queued behind it.
+    const result = this.tail.catch(() => {}).then(
+        () => native.capture(handle, JSON.stringify(request)));
+    this.tail = result.catch(() => {});
+
+    let captured;
+    try {
+      captured = await result;
+    } catch (error) {
+      // The addon attaches the capture's statistics to the rejection as
+      // unparsed JSON, the same way it hands them back on success -- see
+      // NativeCapture. Parsing them here rather than leaving a string on the
+      // error is what makes `error.stats` the same CaptureStats a successful
+      // call returns, which is the whole point of attaching it: the failure is
+      // the case where the counters explain the most.
+      const withStats = error as Error&{stats?: string | CaptureStats};
+      if (typeof withStats.stats === 'string') {
+        withStats.stats = JSON.parse(withStats.stats) as CaptureStats;
+      }
+      throw error;
+    }
+
+    return {
+      image: request.path ? null : captured.image,
+      stats: parseStats(captured.stats),
+    };
+  }
+}
+
+// A zeroed set of counters.
+//
+// Zeroes rather than undefined because the alternative is every caller writing
+// `stats?.timing?.total ?? 0` around a field that is present for every capture
+// that actually ran. The only case that produces none is a request rejected
+// before it started, and that path throws rather than returning.
+function emptyStats(): CaptureStats {
+  return {
+    requests: 0,
+    fromCache: 0,
+    failed: 0,
+    bytes: 0,
+    httpStatus: 0,
+    finalUrl: '',
+    timing: {fetch: 0, render: 0, encode: 0, total: 0},
+  };
+}
+
+// The addon hands statistics over as unparsed JSON -- see NativeCapture -- so
+// this is where the string becomes an object. The daemon's client has them
+// parsed already, from its own response header, and uses emptyStats directly.
+function parseStats(json: string|undefined): CaptureStats {
+  return json ? JSON.parse(json) as CaptureStats : emptyStats();
+}
+
+export {emptyStats, parseStats, sharedHandle};