@shotkit/shotium 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shotkit/shotium",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Static screenshots from a stripped Chromium: DOM, CSS, layout, paint, no JavaScript engine.",
   "keywords": [
     "screenshot",
@@ -24,10 +24,6 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./native": {
-      "types": "./dist/native.d.ts",
-      "default": "./dist/native.js"
-    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -42,12 +38,12 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@shotkit/shotium-darwin-arm64": "0.1.0",
-    "@shotkit/shotium-darwin-x64": "0.1.0",
-    "@shotkit/shotium-linux-arm64": "0.1.0",
-    "@shotkit/shotium-linux-x64": "0.1.0",
-    "@shotkit/shotium-win32-arm64": "0.1.0",
-    "@shotkit/shotium-win32-x64": "0.1.0"
+    "@shotkit/shotium-darwin-arm64": "0.2.0",
+    "@shotkit/shotium-darwin-x64": "0.2.0",
+    "@shotkit/shotium-linux-arm64": "0.2.0",
+    "@shotkit/shotium-linux-x64": "0.2.0",
+    "@shotkit/shotium-win32-arm64": "0.2.0",
+    "@shotkit/shotium-win32-x64": "0.2.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/index.ts

@@ -1,16 +1,12 @@
-import {EventEmitter} from 'node:events';
-
 import * as client from './lib/client.js';
 import type {DaemonClient} from './lib/client.js';
-import {resolveStartOptions} from './lib/config.js';
-import {Pool} from './lib/pool.js';
-import {SUPERVISOR_MARGIN_MS, timeoutFor, toRequest} from './lib/request.js';
+import {Engine} from './lib/engine.js';
 import type {
   DaemonOptions,
   DaemonStatus,
+  PurgeOptions,
   ScreenshotOptions,
   StartOptions,
-  WorkerEvent,
 } from './types.js';
 
 export type {
@@ -22,11 +18,10 @@ export type {
   ScreenshotOptions,
   StartOptions,
   Viewport,
-  WorkerEvent,
 } from './types.js';
 export type {DaemonClient} from './lib/client.js';
 
-/** The five things a caller does with the resident pool. */
+/** The five things a caller does with the resident engine. */
 export interface Daemon {
   /** Connects, starting a daemon if none is listening. */
   connect(options?: DaemonOptions): Promise<DaemonClient>;
@@ -40,108 +35,91 @@ export interface Daemon {
   stop(options?: DaemonOptions): Promise<{stopped: boolean, endpoint: string}>;
 }
 
-// The events the pool forwards, and the only ones. Declared as an interface
-// merged into the class below rather than as a catch-all `on(string, ...)`,
-// so that a listener for an event this runtime never emits is a compile error
-// rather than a callback nobody ever calls.
-export interface Runtime {
-  on(event: 'ready', listener: (info: {workers: number}) => void): this;
-  on(event: 'exit', listener: (event: WorkerEvent) => void): this;
-  on(event: 'crash', listener: (event: WorkerEvent) => void): this;
-  on(event: 'timeout',
-     listener: (event: {worker: number, timeout: number}) => void): this;
-  on(event: 'worker-restart',
-     listener: (event: {worker: number, reason: string, delay: number}) => void):
-      this;
-  /** A worker could not be started at all -- a missing or unusable binary. */
-  on(event: 'worker-error',
-     listener: (event: {worker: number, error: Error}) => void): this;
-  on(event: 'stderr',
-     listener: (event: {worker: number, line: string}) => void): this;
-}
-
 /**
- * The library's one runtime: a pool of worker processes plus its lifecycle.
+ * The engine, and its lifecycle, in this process.
+ *
+ *     import shotium from '@shotkit/shotium';
+ *
+ *     shotium.runtime.start();
+ *     const png = await shotium.screenshot({file: 'https://example.com'});
+ *     await shotium.runtime.stop();
+ *
+ * `start` and `stop` are explicit because starting Blink is the expensive part
+ * -- tens of milliseconds and a working set that stays resident -- and only
+ * the caller knows whether the next screenshot is coming in a moment or never.
+ * Neither call is required: a screenshot starts the engine if it is not up.
+ * What they buy is control over when that cost is paid, and the certainty that
+ * it has been given back.
  *
- * `runtime` below is the singleton, because the expensive part is the
- * processes and a second runtime would double them for no gain. Anyone who
- * genuinely wants two constructs a Runtime directly.
+ * `runtime` below is the singleton because there is nothing else it could be:
+ * Blink starts once per process and cannot be restarted, so a second Runtime
+ * in the same process has no engine to have. Construct one directly only to
+ * own the lifecycle yourself instead of using `runtime`. Parallelism is more
+ * processes, not more Runtimes.
  *
- * Its pool lives and dies with this process. `daemon` is the same pool behind
- * a socket, for callers whose process does not live long enough to be worth
- * starting one.
+ * `daemon` is the same engine in a process of its own, behind a socket, for
+ * callers whose own process does not live long enough to be worth starting
+ * one.
  */
-export class Runtime extends EventEmitter {
-  private pool: Pool|null = null;
+export class Runtime {
+  private engine = new Engine();
 
   get running(): boolean {
-    return this.pool !== null;
+    return this.engine.running;
   }
 
   /**
-   * Starts the pool. Safe to call twice; the second call is a no-op, so that
-   * library code can call it defensively.
+   * Starts the engine. Safe to call twice; the second call is a no-op, so that
+   * library code can call it defensively. Not safe after `stop()` -- see there.
    *
-   * Every option has a default: the binary is `$SHOTIUM_BINARY`, then the
-   * platform package, then `./bin/shotium.exe`; the worker count is half the
-   * cores, at least one and at most four; the cache root is a directory under
-   * the system temp, and `null` disables caching.
+   * Every option has a default. `cacheDir` is the HTTP disk cache and `null`
+   * disables it; `resourceDir` is where `shotium_data.pak` and
+   * `shotium_strings.pak` are, and defaults to the directory the engine was
+   * loaded from, which is where they ship.
    */
   start(options: StartOptions = {}): this {
-    if (this.pool) {
-      return this;
-    }
-    const pool = new Pool(resolveStartOptions(options));
-    this.pool = pool;
-    for (const event
-             of ['ready', 'exit', 'crash', 'timeout', 'worker-restart',
-                 'worker-error', 'stderr']) {
-      pool.on(event, (payload) => this.emit(event, payload));
-    }
-    pool.start();
+    this.engine.start(options);
     return this;
   }
 
-  /** Stops every worker. The pool can be started again afterwards. */
-  async stop(): Promise<void> {
-    if (!this.pool) {
-      return;
-    }
-    const pool = this.pool;
-    this.pool = null;
-    await pool.stop();
+  /**
+   * Stops the engine, after whatever is queued.
+   *
+   * Final for this process. Blink writes process-wide state that it has no
+   * path to undo, so starting again -- here or on another Runtime -- throws
+   * rather than quietly handing back something that cannot render. A program
+   * that wants another screenshot later should stay started and `purge()`.
+   */
+  stop(): Promise<void> {
+    return this.engine.stop();
+  }
+
+  /**
+   * Hands back what the engine is holding but can rebuild. Worth calling when
+   * a batch has ended and the next one may be a while away.
+   */
+  purge(options: PurgeOptions = {}): void {
+    this.engine.purge(options);
   }
 
   /**
    * Renders one screenshot. Resolves to the encoded image, or to `null` when
-   * `path` was given and the worker wrote the file itself.
+   * `path` was given and the engine wrote the file itself.
    */
-  async screenshot(options: ScreenshotOptions): Promise<Buffer|null> {
-    // Validate before starting anything. A malformed request should not cost a
-    // pool of worker processes to discover, and toRequest() is the only check
-    // that can be made without one.
-    const request = toRequest(options);
-    if (!this.pool) {
-      this.start();
-    }
-    const retry = typeof options.retry === 'number' ? options.retry : 0;
-    const result = await this.pool!.submit(request, {
-      timeout: timeoutFor(options) + SUPERVISOR_MARGIN_MS,
-      retry,
-    });
-    return result.image;
+  screenshot(options: ScreenshotOptions): Promise<Buffer|null> {
+    return this.engine.screenshot(options);
   }
 }
 
-/** The shared pool: one per process, started on first use. */
+/** The shared engine: one per process, started on first use. */
 const runtime = new Runtime();
 
-/** One screenshot through the shared pool, starting it if it is not up. */
+/** One screenshot through the shared engine, starting it if it is not up. */
 const screenshot = (options: ScreenshotOptions): Promise<Buffer|null> =>
     runtime.screenshot(options);
 
 /**
- * The resident pool: workers that outlive the process that started them,
+ * The resident engine: a process that outlives the one that started it,
  * reachable over a named pipe on Windows and a unix socket elsewhere. For
  * callers that are short-lived themselves. See lib/daemon.ts.
  */

package/src/lib/binding.ts

@@ -0,0 +1,89 @@
+import fs from 'node:fs';
+import {createRequire} from 'node:module';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import * as platformPackage from './platform.js';
+
+// A .node addon is a CommonJS artefact: there is no ESM loader for one.
+const require = createRequire(import.meta.url);
+
+// ESM has no __dirname. This is the same thing, from the module's own URL.
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * The engine handle the addon hands back. Opaque on purpose: everything that
+ * can be done with it is a call on the binding below.
+ */
+export type Engine = unknown;
+
+/** What native/binding.cc exports. See shot/shot_api.h for the C ABI. */
+export interface NativeBinding {
+  create(optionsJson: string): Engine;
+  destroy(engine: Engine): void;
+  purge(engine: Engine, releaseWorkingSet: boolean): void;
+  capture(engine: Engine, requestJson: string): Promise<Buffer>;
+}
+
+// Where the addon and the library beside it live.
+//
+// The platform package is what ships -- the .node sits next to the shared
+// library it is linked against, which is the whole reason the two travel in
+// one package rather than two. native/build/Release is where node-gyp puts a
+// local build; it exists in a checkout and not in an install, so the two never
+// compete in practice. Both paths are relative to this file's build output,
+// which is one directory below the package root.
+function candidates(): string[] {
+  const found: string[] = [];
+  const dir = platformPackage.packageDir();
+  if (dir) {
+    found.push(path.join(dir, 'shotium.node'));
+  }
+  found.push(
+      path.join(HERE, '..', 'native', 'build', 'Release', 'shotium.node'));
+  return found;
+}
+
+let binding: NativeBinding|null = null;
+let loadedFrom: string|null = null;
+
+/**
+ * The addon, loaded once. Throws if there is none for this platform, which is
+ * the only failure this package cannot work around: there is nothing else to
+ * fall back to.
+ */
+export function load(): NativeBinding {
+  if (binding) {
+    return binding;
+  }
+  const tried = candidates();
+  for (const candidate of tried) {
+    if (!fs.existsSync(candidate)) {
+      continue;
+    }
+    // Not wrapped in a try: a .node that is there and will not load is a
+    // broken installation, and the loader's own message -- a missing
+    // dependency, an architecture mismatch -- says more than anything that
+    // could be substituted for it.
+    binding = require(candidate) as NativeBinding;
+    loadedFrom = path.dirname(candidate);
+    return binding;
+  }
+  const expected = platformPackage.packageName();
+  throw new Error(
+      'shotium: no engine for this platform.\n' +
+      `  looked in:\n    ${tried.join('\n    ')}\n` +
+      (expected ?
+           `  It ships in ${expected}, which npm installs as an optional ` +
+               'dependency of this package. If the install skipped optional ' +
+               'dependencies, it is not there.\n' :
+           `  There is no build for ${process.platform}-${process.arch}.\n`));
+}
+
+/**
+ * The directory the addon came from, or null before the first load(). The
+ * resource packs ship beside it, which is what this is for.
+ */
+export function directory(): string|null {
+  return loadedFrom;
+}

package/src/lib/client.ts

@@ -48,10 +48,9 @@ interface Pending {
 }
 
 interface ResolvedDaemonOptions {
-  binary: string;
-  workers: number;
   cacheDir: string|null;
-  args: string[];
+  userAgent?: string;
+  resourceDir?: string;
   name: string|undefined;
   endpoint: string;
   idleTimeoutMs: number|undefined;
@@ -61,11 +60,11 @@ interface ResolvedDaemonOptions {
 
 // The client half of the resident daemon.
 //
-// One connection can carry several requests at once, which is the difference
-// between this and the worker protocol underneath: every message carries an
+// One connection can carry several requests at once: every message carries an
 // `id` and the answers are matched back by it, so a caller can fire ten
-// screenshots down one socket and let the pool on the other side spread them
-// across workers.
+// screenshots down one socket without waiting between them. They still come
+// back one at a time -- there is one renderer on the other side -- so this
+// saves the round trips, not the renders.
 class DaemonClient extends EventEmitter {
   private readonly socket: net.Socket;
   private readonly endpointPath: string;
@@ -155,12 +154,10 @@ class DaemonClient extends EventEmitter {
   /** Resolves to the image, or to null when `path` was given. */
   async screenshot(options: ScreenshotOptions): Promise<Buffer|null> {
     const request = toRequest(options);
-    const retry = typeof options.retry === 'number' ? options.retry : 0;
     const result = await this.send({
       op: 'screenshot',
       request,
       timeout: timeoutFor(options),
-      retry,
     });
     return result.image;
   }
@@ -219,10 +216,9 @@ function resolveDaemonOptions(options: DaemonOptions = {}):
 
 function spawnDaemon(options: ResolvedDaemonOptions): void {
   const config = {
-    binary: options.binary,
-    workers: options.workers,
     cacheDir: options.cacheDir,
-    args: options.args,
+    userAgent: options.userAgent,
+    resourceDir: options.resourceDir,
     endpoint: options.endpoint,
     idleTimeoutMs: options.idleTimeoutMs,
     prewarm: options.prewarm,

package/src/lib/config.ts

@@ -1,21 +1,11 @@
-import os from 'node:os';
-import path from 'node:path';
-import {fileURLToPath} from 'node:url';
-
 import type {StartOptions} from '../types.js';
 
-import * as platform from './platform.js';
-
-// ESM has no __dirname. This is the same thing, from the module's own URL.
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-
 // StartOptions with every hole filled in. `cacheDir` is still nullable here
 // because null is an answer -- "no disk cache" -- and not an absent one.
 export interface ResolvedStartOptions {
-  binary: string;
-  workers: number;
   cacheDir: string|null;
-  args: string[];
+  userAgent?: string;
+  resourceDir?: string;
 }
 
 // The one place that decides what "no options" means.
@@ -23,64 +13,19 @@ export interface ResolvedStartOptions {
 // It is shared rather than duplicated because the daemon's address is a hash of
 // its configuration: if two callers filled in defaults even slightly
 // differently, one would compute an address no daemon is listening on and
-// start a second pool next to the first one that was already warm. See
+// start a second engine next to the first one that was already warm. See
 // endpoint.ts.
 //
-// Three places, in the order a caller means them: what they said, what npm
-// installed, and what they unpacked by hand. The middle one is the normal case
-// and the only one that needs no instructions.
-function defaultBinary(): string {
-  if (process.env.SHOTIUM_BINARY) {
-    return process.env.SHOTIUM_BINARY;
-  }
-  const dir = platform.packageDir();
-  if (dir) {
-    return path.join(dir, platform.binaryName());
-  }
-  // No platform package: an archive from the releases page, unpacked into
-  // bin/ beside this file. This is also the path a checkout takes, where
-  // nothing was installed from a registry at all.
-  return path.join(HERE, '..', 'bin', platform.binaryName());
-}
-
-// How many worker processes, when nobody said.
-//
-// Half the cores, capped. The cap is there because a worker is a process with
-// blink in it, not a thread: measured on this tree it settles around 14 MB of
-// private working set and holds a further ~30 MB of shotium.exe resident, so
-// "half the cores" on a 32-core machine is sixteen of them and most of a
-// gigabyte for a queue that is almost never sixteen deep. Four is past the
-// point where a screenshot workload gets much from another one -- the corpus
-// runs at 41 pages/s on four -- and anyone who has measured otherwise passes
-// `workers`.
-const MAXIMUM_DEFAULT_WORKERS = 4;
-
-function defaultWorkers(): number {
-  const half = Math.floor((os.cpus().length || 2) / 2);
-  return Math.max(1, Math.min(MAXIMUM_DEFAULT_WORKERS, half));
-}
-
-function defaultCacheDir(): string {
-  return path.join(os.tmpdir(), 'shotium-cache');
-}
-
-// binary / workers / cacheDir / args, filled in and normalised. `cacheDir:
-// null` survives as null -- it means "no disk cache", which is not the same
-// request as "use the default one".
+// The default for `cacheDir` is null -- no disk cache. A program holding the
+// engine is often short-lived, and a cache it never reads twice is a directory
+// it leaves behind. The daemon, which is the case where a cache does pay for
+// itself, is also the case where the caller is already passing options.
 function resolveStartOptions(options: StartOptions = {}): ResolvedStartOptions {
   return {
-    binary: options.binary || defaultBinary(),
-    workers: options.workers || defaultWorkers(),
-    cacheDir: options.cacheDir === null ?
-        null :
-        (options.cacheDir || defaultCacheDir()),
-    args: options.args || [],
+    cacheDir: options.cacheDir ?? null,
+    userAgent: options.userAgent,
+    resourceDir: options.resourceDir,
   };
 }
 
-export {
-  defaultBinary,
-  defaultCacheDir,
-  defaultWorkers,
-  resolveStartOptions,
-};
+export {resolveStartOptions};