@shotkit/shotium 0.1.0 → 0.3.0

package/src/index.ts

@@ -1,38 +1,46 @@
-import {EventEmitter} from 'node:events';
-
+import {Cache} from './lib/cache.js';
 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,
+  ReleaseMemoryOptions,
   ScreenshotOptions,
+  ScreenshotResult,
   StartOptions,
-  WorkerEvent,
+  StartResult,
 } from './types.js';
 
 export type {
+  CacheClearOptions,
+  CacheClearResult,
+  CacheEntry,
+  CacheMode,
+  CacheTarget,
+  CaptureStats,
+  CaptureTiming,
   Clip,
   DaemonOptions,
   DaemonStatus,
   PageGotoParams,
-  PurgeOptions,
+  ReleaseMemoryOptions,
   ScreenshotOptions,
+  ScreenshotResult,
   StartOptions,
+  StartResult,
   Viewport,
-  WorkerEvent,
 } from './types.js';
 export type {DaemonClient} from './lib/client.js';
+export {Cache} from './lib/cache.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>;
   /** One screenshot through the daemon, connection and all. */
   screenshot(options: ScreenshotOptions&{daemon?: DaemonOptions}):
-      Promise<Buffer|null>;
+      Promise<ScreenshotResult>;
   /** Starts one if it is not up, and reports what is there either way. */
   start(options?: DaemonOptions): Promise<DaemonStatus&{spawned: boolean}>;
   status(options?: DaemonOptions):
@@ -40,110 +48,174 @@ 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.start();
+ *     const {image, stats} = await shotium.screenshot({
+ *       file: 'https://example.com',
+ *     });
+ *     await shotium.stop();
  *
- * `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.
+ * `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.
  *
- * 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.
+ * Neither is rationed, either. They may be called in any order and as often as
+ * a program likes: `stop()` stands the engine down and `start()` picks the
+ * same one back up, warm cache and all. What cannot happen is a *second*
+ * engine -- Blink is initialised once per process and there is no undo -- but
+ * that is a fact about how many there are, not about how many times the one
+ * may be asked for.
+ *
+ * The methods are on the module rather than under a `runtime` namespace, which
+ * they were until 0.3. There was never anything else to start, so the word
+ * carried nothing; and `runtime.cache` would have been the wrong place for the
+ * cache besides, since a cache directory outlives every engine that writes to
+ * it and can be read when no engine is running at all.
+ *
+ * `Runtime` is still exported for a caller who wants to own a lifecycle rather
+ * than share the module's. It is a lifecycle and not an engine: there is one
+ * engine per process, and a second Runtime that starts adopts the same one
+ * rather than building another. Parallelism is more processes, not more
+ * Runtimes.
+ *
+ * `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();
+
+  /**
+   * The HTTP cache: where it is, what is in it, and how to empty it.
+   *
+   * On the Runtime as well as on the module because a caller holding their own
+   * Runtime needs the engine handle to reach a directory that engine has open:
+   * within one process a directory has one backend, so borrowing is the only
+   * way in.
+   */
+  readonly cache = new Cache(() => this.engine.nativeHandle);
 
   get running(): boolean {
-    return this.pool !== null;
+    return this.engine.running;
+  }
+
+  /**
+   * Starts the engine, or picks the running one back up.
+   *
+   * Callable as often as you like, in any order with `stop()`; library code
+   * can call it defensively. The first call in a process builds the engine and
+   * every later one adopts it -- the same engine, the same warm cache. The one
+   * thing it will refuse 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 you did not ask for.
+   *
+   * Every option has a default. `cacheDir` is the HTTP disk cache and defaults
+   * to a per-project directory under `~/.shotium/cache`, and not under the
+   * temporary directory, which is defined by not surviving. `null` turns it
+   * off. `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.
+   *
+   * The return value is worth reading once. `cacheActive: false` with a
+   * `cacheDir` set means the directory could not be opened and this engine is
+   * running without a cache -- correctly, silently, and a round trip slower on
+   * everything.
+   */
+  start(options: StartOptions = {}): StartResult {
+    return this.engine.start(options);
+  }
+
+  /** What `start()` returned, asked again. */
+  status(): StartResult {
+    return this.engine.status();
   }
 
   /**
-   * Starts the pool. Safe to call twice; the second call is a no-op, so that
-   * library code can call it defensively.
+   * 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. Blink itself stays initialised, because there
+   * is no way to un-initialise it -- so the disk cache stays where it is, and
+   * `start()` or the next `screenshot()` picks the same engine back up.
    *
-   * 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.
+   * Which makes this a caller saying they are done for now rather than a
+   * destructor. It does the same work as `releaseMemory({releaseWorkingSet:
+   * true})` and additionally stops accepting captures.
    */
-  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();
-    return this;
+  stop(): Promise<void> {
+    return this.engine.stop();
   }
 
-  /** 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();
+  /**
+   * Hands back what the engine is holding but can rebuild: Blink's heap,
+   * skia's caches, PartitionAlloc's free lists. Worth calling when a batch has
+   * ended and the next one may be a while away.
+   *
+   * This is memory and nothing else. It was called `purge()` until 0.3, which
+   * next to `cache.clear()` read as though it emptied the HTTP cache; it does
+   * not touch the disk at all.
+   */
+  releaseMemory(options: ReleaseMemoryOptions = {}): void {
+    this.engine.releaseMemory(options);
   }
 
   /**
-   * Renders one screenshot. Resolves to the encoded image, or to `null` when
-   * `path` was given and the worker wrote the file itself.
+   * Renders one screenshot, and reports what it cost.
+   *
+   * `image` is the encoded bytes, or `null` when `path` was given and the
+   * engine wrote the file itself. `stats` says how many resources were
+   * fetched, how many came from the cache, and where the milliseconds went --
+   * which for an `https:` URL is usually the answer to "why did this take so
+   * long", because a cold connection costs more than the render does.
    */
-  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<ScreenshotResult> {
+    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. */
-const screenshot = (options: ScreenshotOptions): Promise<Buffer|null> =>
+/** One screenshot through the shared engine, starting it if it is not up. */
+const screenshot = (options: ScreenshotOptions): Promise<ScreenshotResult> =>
     runtime.screenshot(options);
 
+const start = (options?: StartOptions): StartResult => runtime.start(options);
+const status = (): StartResult => runtime.status();
+const stop = (): Promise<void> => runtime.stop();
+const releaseMemory = (options?: ReleaseMemoryOptions): void =>
+    runtime.releaseMemory(options);
+
+/**
+ * The HTTP cache.
+ *
+ * At the top level rather than under the engine because it outlives one: the
+ * directory is on disk whether or not anything is running, `getDir()` answers
+ * before the first `start()`, and clearing it is something a program may want
+ * to do without bringing Blink up at all. When an engine *is* up, these
+ * borrow its cache backend, because within one process a directory has one
+ * backend and that is the only way in.
+ */
+const cache = runtime.cache;
+
 /**
- * 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.
+ *
+ * It has no `cache` of its own. A daemon's cache directory is reported by
+ * `daemon.status()`, and clearing it is done by pointing `cache.clear()` at
+ * that directory or by stopping the daemon -- a cross-process cache protocol
+ * would be a second implementation of this module for something nobody does on
+ * a request path.
  */
 const daemon: Daemon = {
   connect: client.connect,
@@ -153,9 +225,27 @@ const daemon: Daemon = {
   stop: client.stop,
 };
 
-export {runtime, screenshot, daemon};
+export {cache, daemon, releaseMemory, runtime, screenshot, start, status, stop};
 
 // A default as well as the names, because `import shotium from` is what a
 // caller coming from `require` writes first, and the two have to be the same
 // object rather than two views that drift.
-export default {Runtime, runtime, screenshot, daemon};
+export default {
+  Runtime,
+  cache,
+  daemon,
+  releaseMemory,
+  runtime,
+  screenshot,
+  start,
+  status,
+  stop,
+  // A getter and not a value, because it changes. It is only on the default
+  // export: a named `running` would have to be a live binding that something
+  // remembered to update, and the two would disagree the first time anybody
+  // forgot. Callers who import by name have `status().running`, which is the
+  // same answer with the cache directory attached.
+  get running(): boolean {
+    return runtime.running;
+  },
+};

package/src/lib/binding.ts

@@ -0,0 +1,110 @@
+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;
+
+/** One capture's answer, as the addon hands it over. */
+export interface NativeCapture {
+  image: Buffer;
+  /**
+   * CaptureStats as JSON, unparsed. The addon carries JSON between the engine
+   * and this layer without reading it -- anything it understood would be a
+   * third opinion about the shape, and the third opinion is the one that
+   * drifts. Undefined when the engine reported none.
+   */
+  stats?: string;
+}
+
+/** 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;
+  status(engine: Engine): string;
+  capture(engine: Engine, requestJson: string): Promise<NativeCapture>;
+  /**
+   * List or clear a cache directory. `engine` is nullable and that is the
+   * interface: with one, the operation runs on the engine's thread and borrows
+   * the backend it already holds; without one, the library opens the directory
+   * itself. Resolves to JSON.
+   */
+  cache(engine: Engine|null, clearing: boolean, optionsJson: string):
+      Promise<string>;
+}
+
+// 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;
+}