@shotkit/shotium 0.1.0 → 0.2.0

package/src/lib/daemon.ts

@@ -1,13 +1,15 @@
 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 {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 +27,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
@@ -51,30 +48,39 @@ interface DaemonReply {
   stopping?: boolean;
 }
 
-// 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 +112,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 +181,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 +195,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 +233,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,26 +301,22 @@ 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) => {
           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,
               },
-              result.image);
+              image);
         })
         .catch((error: Error) => {
           this.reply(
@@ -362,7 +374,7 @@ class Daemon extends EventEmitter {
     }
     this.sockets.clear();
     await new Promise<void>((resolve) => this.server!.close(() => resolve()));
-    await this.pool!.stop();
+    await this.engine.stop();
     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,168 @@
+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 {PurgeOptions, ScreenshotOptions, StartOptions} from '../types.js';
+
+import {resolveStartOptions} from './config.js';
+
+// One per process, ever. Not one at a time -- one.
+//
+// This is not a rule of this file, it is what Blink is: initialising it writes
+// process-wide statics it has no path to undo, so shot_engine_destroy() gives
+// back what it can and the process still cannot make another. The C API
+// returns SHOT_ERR_STATE for a second create whether or not the first is
+// still alive. See shot/shot_api.h.
+//
+// So `stop()` is final for the process, and this flag exists to say that in
+// words at the call site. Without it a caller who stops and starts again gets
+// SHOT_ERR_STATE out of the addon -- a true error, arriving one layer too deep
+// to explain that the answer is a second process rather than a retry.
+let startedInThisProcess = false;
+
+/**
+ * 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 {
+  private handle: Handle|null = null;
+  private stopped = false;
+  private tail: Promise<unknown> = Promise.resolve();
+
+  get running(): boolean {
+    return this.handle !== null;
+  }
+
+  /**
+   * Starts the engine. Safe to call twice; the second call is a no-op, so that
+   * library code can call it defensively.
+   *
+   * Not safe to call after `stop()`, and not because of anything here: Blink
+   * starts once per process and cannot be restarted. Another engine means
+   * another process.
+   */
+  start(options: StartOptions = {}): this {
+    if (this.handle) {
+      return this;
+    }
+    if (this.stopped) {
+      throw new Error(
+          'shotium: this engine was stopped, and Blink cannot be started ' +
+          'again in a process that has already run it. Start another ' +
+          'process, or keep the engine up between screenshots.');
+    }
+    if (startedInThisProcess) {
+      throw new Error(
+          'shotium: an engine has already run in this process. Blink is a ' +
+          'process-wide singleton -- there is one per process, ever -- so a ' +
+          'second Runtime cannot have one. Use the shared `runtime`, or run ' +
+          'another process.');
+    }
+    const native = binding.load();
+    const resolved = resolveStartOptions(options);
+
+    const engineOptions: Record<string, unknown> = {};
+    if (resolved.cacheDir !== null) {
+      engineOptions.cacheDir = resolved.cacheDir;
+    }
+    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();
+
+    this.handle = native.create(JSON.stringify(engineOptions));
+    startedInThisProcess = true;
+    return this;
+  }
+
+  /**
+   * Stops the engine, after whatever is queued.
+   *
+   * Final for this process: see the note above. A program that will want
+   * another screenshot later should leave the engine up and call `purge()`
+   * instead, which hands back the memory without giving up the engine.
+   */
+  async stop(): Promise<void> {
+    if (!this.handle) {
+      return;
+    }
+    this.stopped = true;
+    // After the queue, not before: destroy() waits for a capture in flight
+    // anyway, and doing it in order means a caller's last screenshot resolves
+    // rather than racing the shutdown.
+    const handle = this.handle;
+    this.handle = null;
+    await this.tail.catch(() => {});
+    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.
+   */
+  purge({releaseWorkingSet = false}: PurgeOptions = {}): void {
+    if (!this.handle) {
+      return;
+    }
+    binding.load().purge(this.handle, 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<Buffer|null> {
+    // 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<Buffer|null> {
+    if (!this.handle) {
+      this.start();
+    }
+    const handle = this.handle;
+    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(() => {});
+    const image = await result;
+    return request.path ? null : image;
+  }
+}

package/src/lib/platform.ts

@@ -66,10 +66,4 @@ function packageDir(): string|null {
   }
 }
 
-// What the engine executable is called, which is not what the platform calls
-// it: Windows wants the extension and nothing else does.
-function binaryName(): string {
-  return process.platform === 'win32' ? 'shotium.exe' : 'shotium';
-}
-
-export {PACKAGES, binaryName, packageDir, packageName};
+export {PACKAGES, packageDir, packageName};

package/src/lib/request.ts

@@ -1,14 +1,9 @@
 import type {Clip, PageGotoParams, ScreenshotOptions} from '../types.js';
 
 const DEFAULT_TIMEOUT_MS = 30000;
-// How much longer than the page's own deadline a supervisor waits before
-// deciding the worker is not going to answer at all. The worker fails a slow
-// page by itself and replies; this margin covers process startup and the
-// encode, and firing it means something worse than a slow page.
-const SUPERVISOR_MARGIN_MS = 10000;
 
-// What actually goes down the pipe. It is ScreenshotOptions with the viewport
-// flattened and `retry` taken out -- see toRequest below for why each.
+// What actually goes down the pipe: ScreenshotOptions with the viewport
+// flattened -- see toRequest below for why.
 export interface WireRequest {
   file: string;
   type?: 'png'|'jpeg'|'webp';
@@ -49,8 +44,8 @@ const WIRE_FIELDS = new Set([
 
 // One ScreenshotOptions, checked and flattened into what goes on the wire.
 //
-// It lives here rather than in index.ts because the in-process pool and the
-// daemon both send it: a request that is valid through one entry point and
+// It lives here rather than in index.ts because the engine in this process and
+// the daemon both send it: a request that is valid through one entry point and
 // rejected through the other would be a difference nobody asked for.
 function toRequest(options: ScreenshotOptions): WireRequest {
   if (!options || typeof options !== 'object') {
@@ -65,11 +60,6 @@ function toRequest(options: ScreenshotOptions): WireRequest {
     if (value === undefined) {
       continue;
     }
-    // retry is the supervisor's, not the worker's: it decides how many times a
-    // request is re-sent, which is not something the worker could act on.
-    if (key === 'retry') {
-      continue;
-    }
     if (!WIRE_FIELDS.has(key)) {
       throw new TypeError(`shotium: unknown option "${key}"`);
     }
@@ -101,7 +91,6 @@ function timeoutFor(options: ScreenshotOptions): number {
 
 export {
   DEFAULT_TIMEOUT_MS,
-  SUPERVISOR_MARGIN_MS,
   WIRE_FIELDS,
   timeoutFor,
   toRequest,

package/src/types.ts

@@ -1,10 +1,8 @@
 // The vocabulary of the package: what a caller passes in and what comes back.
 //
 // It lives in one file rather than beside the code that reads each field
-// because these types are the published API. index.ts and native.ts both
-// re-export them, so a consumer sees one `ScreenshotOptions` whichever entry
-// point they came through -- and, more to the point, so there is one place
-// where adding an option means adding it.
+// because these types are the published API: index.ts re-exports them, so
+// there is one place where adding an option means adding it.
 
 /** A region of the document, in CSS pixels. */
 export interface Clip {
@@ -70,35 +68,29 @@ export interface ScreenshotOptions {
    * is rendered on.
    */
   allowFileAccess?: boolean;
-  /** How many times to re-send after a crash or a timeout. Default 0. */
-  retry?: number;
 }
 
 export interface StartOptions {
   /**
-   * Path to `shotium.exe`. Default `$SHOTIUM_BINARY`, then the platform
-   * package for this machine, then `./bin/shotium.exe`.
+   * Root of the HTTP disk cache. `null` disables caching entirely, which is
+   * the default: a program holding the engine is often short-lived, and a
+   * cache it never reads twice is a directory it leaves behind.
    */
-  binary?: string;
-  /** Worker processes. Default half the cores, at least one, at most four. */
-  workers?: number;
-  /** Root of the per-worker HTTP disk caches. `null` disables caching. */
   cacheDir?: string|null;
-  /** Extra flags passed to every worker. */
-  args?: string[];
-}
-
-export interface WorkerEvent {
-  worker: number;
-  code?: number|null;
-  signal?: NodeJS.Signals|null;
+  /** Overrides the built-in user agent string. */
+  userAgent?: string;
+  /**
+   * Where `shotium_data.pak` and `shotium_strings.pak` are. Defaults to the
+   * directory the engine was loaded from, which is where they ship.
+   */
+  resourceDir?: string;
 }
 
 export interface DaemonOptions extends StartOptions {
   /**
    * Address the daemon by name instead of by configuration. Without it the
-   * endpoint is a hash of `binary`, `workers`, `cacheDir` and `args`, so a
-   * client never attaches to a pool that renders with something other than
+   * endpoint is a hash of `cacheDir`, `userAgent` and `resourceDir`, so a
+   * client never attaches to a daemon that renders with something other than
    * what it asked for.
    */
   name?: string;
@@ -110,9 +102,8 @@ export interface DaemonOptions extends StartOptions {
    */
   idleTimeoutMs?: number;
   /**
-   * Render one throwaway document per worker at startup, so the first real
-   * request does not pay for whatever a worker initialises lazily. Default
-   * true.
+   * Render one throwaway document at startup, so the first real request does
+   * not pay for whatever the engine initialises lazily. Default true.
    */
   prewarm?: boolean;
   /** Fail instead of starting a daemon when none is listening. */
@@ -129,11 +120,10 @@ export interface DaemonStatus {
   spawned?: boolean;
   pid: number;
   endpoint: string;
-  binary: string;
-  workers: number;
   cacheDir: string|null;
-  args: string[];
-  /** Every worker has rendered at least once. */
+  userAgent?: string;
+  resourceDir?: string;
+  /** The engine has rendered at least once. */
   warm: boolean;
   uptimeMs: number;
   connections: number;
@@ -143,22 +133,6 @@ export interface DaemonStatus {
   version: string;
 }
 
-export interface NativeStartOptions {
-  /**
-   * Root of the HTTP disk cache. `null` disables caching entirely, which is
-   * the default here: an in-process engine is often a short-lived program, and
-   * a cache it never reads twice is a directory it leaves behind.
-   */
-  cacheDir?: string|null;
-  /** Overrides the built-in user agent string. */
-  userAgent?: string;
-  /**
-   * Where `shotium_data.pak` and `shotium_strings.pak` are. Defaults to the
-   * directory the native engine was loaded from, which is where they ship.
-   */
-  resourceDir?: string;
-}
-
 export interface PurgeOptions {
   /**
    * Also ask the OS to take the engine's pages back. The next screenshot pays