@shotkit/shotium 0.1.0 → 0.3.0

package/src/lib/pool.ts

@@ -1,243 +0,0 @@
-import {EventEmitter} from 'node:events';
-import fs from 'node:fs';
-import path from 'node:path';
-
-import type {ResolvedStartOptions} from './config.js';
-import {defaultCacheDir} from './config.js';
-import type {WireRequest} from './request.js';
-import type {WorkerResult} from './worker.js';
-import {Worker} from './worker.js';
-
-// A worker that exits sooner than this never really started, so its slot is
-// refilled on a doubling delay rather than immediately.
-const FAST_FAILURE_MS = 1000;
-const RESPAWN_DELAY_MS = 100;
-const MAX_RESPAWN_DELAY_MS = 5000;
-
-export interface SubmitOptions {
-  /** The supervisor's deadline, in milliseconds. */
-  timeout: number;
-  /** How many times to re-send after a crash or a timeout. */
-  retry: number;
-}
-
-interface Job {
-  request: WireRequest;
-  timeout: number;
-  attemptsLeft: number;
-  resolve: (result: WorkerResult) => void;
-  reject: (error: Error) => void;
-}
-
-// A fixed set of shotium.exe --serve processes, and a queue in front of them.
-//
-// The pool exists because blink is a process-wide singleton: one worker renders
-// one document at a time, so N concurrent screenshots means N processes. It is
-// also what makes a crash survivable -- a worker that dies takes its own
-// request down and nothing else, and the slot is refilled.
-//
-// Events:
-//   ready          {workers}                 the pool is up
-//   exit           {worker, code, signal}    a worker is gone
-//   crash          {worker, code, signal}    a worker died owing an answer
-//   timeout        {worker, timeout}         a request outlived its deadline
-//   worker-restart {worker, reason, delay}   a slot was refilled
-//   worker-error   {worker, error}           a worker could not be started
-//   stderr         {worker, line}            a diagnostic line from a worker
-class Pool extends EventEmitter {
-  private readonly binary: string;
-  private readonly size: number;
-  private readonly args: string[];
-  private readonly cacheDir: string|null;
-  private slots: Worker[] = [];
-  private failures: number[] = [];
-  private queue: Job[] = [];
-  private stopping = false;
-  private nextId = 0;
-
-  constructor(options: ResolvedStartOptions) {
-    super();
-    this.binary = options.binary;
-    this.size = options.workers;
-    this.args = options.args || [];
-    this.cacheDir = options.cacheDir || null;
-  }
-
-  start(): void {
-    if (this.slots.length > 0) {
-      return;
-    }
-    for (let slot = 0; slot < this.size; ++slot) {
-      this.slots[slot] = this.spawn(slot);
-    }
-    this.emit('ready', {workers: this.size});
-  }
-
-  private spawn(slot: number): Worker {
-    const id = this.nextId++;
-    const args = [...this.args];
-    if (this.cacheDir) {
-      // One directory per slot, not per process: the Simple backend takes an
-      // exclusive lock on its directory, so sharing one would leave every
-      // worker but the first running uncached. Keying on the slot rather than
-      // the worker id means a restarted worker inherits the warm cache its
-      // predecessor built.
-      const dir = path.join(this.cacheDir, `worker-${slot}`);
-      fs.mkdirSync(dir, {recursive: true});
-      args.push(`--cache-dir=${dir}`);
-    }
-
-    const startedAt = Date.now();
-    const worker = new Worker({id, binary: this.binary, args});
-    worker.on('stderr', (event) => this.emit('stderr', event));
-    worker.on('crash', (event) => this.emit('crash', event));
-    // A worker that could not be started at all -- a binary that is not there,
-    // a path that is not executable -- reports it here. Without a listener
-    // EventEmitter throws the error instead, which for a resident daemon means
-    // a typo in a path takes the whole pool down.
-    worker.on('error', (error) => this.emit('worker-error', {worker: id, error}));
-    worker.on('exit', (event) => {
-      this.emit('exit', event);
-      if (this.stopping || this.slots[slot] !== worker) {
-        return;
-      }
-      // A worker that died on the way up is not a crash to recover from, it is
-      // a configuration that does not work, and refilling the slot as fast as
-      // the loop allows would spin a core until someone noticed. Back off, but
-      // never give up: the binary may yet appear, and a pool that stopped
-      // trying would have to be restarted by hand.
-      //
-      // "On the way up" is answered nothing and did not last a second, in that
-      // order. Age alone would misread the ordinary case this design exists
-      // for -- a worker killed mid-request seconds after the pool started --
-      // as a startup failure, and delay the slot that the retry needs.
-      const started = worker.served > 0 ||
-          (Date.now() - startedAt) >= FAST_FAILURE_MS;
-      if (started) {
-        this.failures[slot] = 0;
-      }
-      const failures = this.failures[slot] || 0;
-      const delay = started ?
-          0 :
-          Math.min(MAX_RESPAWN_DELAY_MS, RESPAWN_DELAY_MS * 2 ** failures);
-      this.failures[slot] = failures + 1;
-      const refill = () => {
-        if (this.stopping || this.slots[slot] !== worker) {
-          return;
-        }
-        const replacement = this.spawn(slot);
-        this.slots[slot] = replacement;
-        this.emit('worker-restart',
-                  {worker: replacement.id, reason: 'exit', delay});
-        this.pump();
-      };
-      if (delay === 0) {
-        refill();
-        return;
-      }
-      const timer = setTimeout(refill, delay);
-      // An unref'd timer does not hold the process open: a pool whose workers
-      // all failed should not be the reason a program refuses to exit.
-      timer.unref();
-    });
-    return worker;
-  }
-
-  // Queues one request. `timeout` is the supervisor's deadline, which is longer
-  // than the worker's own: the worker fails a slow page by itself and answers,
-  // and this only fires when it has stopped answering at all.
-  submit(request: WireRequest, {timeout, retry}: SubmitOptions):
-      Promise<WorkerResult> {
-    return new Promise<WorkerResult>((resolve, reject) => {
-      this.queue.push({
-        request,
-        timeout,
-        attemptsLeft: Math.max(0, retry) + 1,
-        resolve,
-        reject,
-      });
-      this.pump();
-    });
-  }
-
-  private pump(): void {
-    while (this.queue.length > 0) {
-      const slot = this.slots.findIndex((w) => w && w.alive && !w.busy);
-      if (slot < 0) {
-        return;
-      }
-      this.dispatch(this.slots[slot]!, this.queue.shift()!);
-    }
-  }
-
-  private dispatch(worker: Worker, job: Job): void {
-    job.attemptsLeft -= 1;
-
-    let settled = false;
-    const timer = setTimeout(() => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      this.emit('timeout', {worker: worker.id, timeout: job.timeout});
-      // The worker is not answering, so the only way to get the slot back is to
-      // take the process down. The exit handler refills the slot.
-      worker.kill();
-      this.retryOrFail(
-          job,
-          new Error(`shotium: no answer within ${job.timeout}ms`));
-    }, job.timeout);
-
-    worker.send(job.request)
-        .then((result) => {
-          if (settled) {
-            return;
-          }
-          settled = true;
-          clearTimeout(timer);
-          job.resolve(result);
-          this.pump();
-        })
-        .catch((error: Error) => {
-          if (settled) {
-            return;
-          }
-          settled = true;
-          clearTimeout(timer);
-          this.retryOrFail(job, error);
-        });
-  }
-
-  private retryOrFail(job: Job, error: Error): void {
-    // A request rejected on its own merits -- a bad selector, an unreadable
-    // file -- would fail the same way every time, but the worker also rejects
-    // with the same shape when it dies. Retrying both is the safe direction:
-    // the cost of a pointless retry is one more render, and the cost of not
-    // retrying a crash is a failure the caller cannot do anything about.
-    if (job.attemptsLeft > 0 && !this.stopping) {
-      this.queue.unshift(job);
-      this.pump();
-      return;
-    }
-    job.reject(error);
-    this.pump();
-  }
-
-  async stop(): Promise<void> {
-    this.stopping = true;
-    for (const job of this.queue.splice(0)) {
-      job.reject(new Error('shotium: the runtime was stopped'));
-    }
-    await Promise.all(this.slots.map((worker) => new Promise<void>((resolve) => {
-      if (!worker || !worker.alive) {
-        resolve();
-        return;
-      }
-      worker.once('exit', () => resolve());
-      worker.stop();
-    })));
-    this.slots = [];
-  }
-}
-
-export {Pool, defaultCacheDir};

package/src/lib/worker.ts

@@ -1,220 +0,0 @@
-import {spawn} from 'node:child_process';
-import type {ChildProcess, StdioOptions} from 'node:child_process';
-import {EventEmitter} from 'node:events';
-
-import {FrameReader, encodeRequest} from './protocol.js';
-import type {WireRequest} from './request.js';
-
-export interface WorkerOptions {
-  id: number;
-  binary: string;
-  args?: string[];
-}
-
-// The header frame the worker answers with, followed by the image frame.
-export interface ResponseHeader {
-  ok: boolean;
-  error?: string;
-  bytes?: number;
-  path?: string;
-}
-
-export interface WorkerResult {
-  header: ResponseHeader;
-  image: Buffer|null;
-}
-
-interface Pending {
-  resolve: (result: WorkerResult) => void;
-  reject: (error: Error) => void;
-}
-
-// One shotium.exe --serve process.
-//
-// Exactly one request is in flight at a time, and that is not a simplification:
-// blink is a process-wide singleton bound to the worker's main thread, so a
-// second request could not be rendered concurrently even if the protocol
-// allowed it. Concurrency is the pool's job, and it gets it by running more
-// processes.
-//
-// Events:
-//   ready                       the process has started
-//   exit   {code, signal}       it is gone, for any reason
-//   crash  {code, signal}       it is gone while it owed an answer
-//   stderr {line}               a diagnostic line, useful when a render is wrong
-class Worker extends EventEmitter {
-  readonly id: number;
-  // How many requests this process has answered, either way. The pool reads
-  // it to tell a worker that was working and then died from one that never
-  // came up at all.
-  served = 0;
-
-  private readonly binary: string;
-  private readonly args: string[];
-  private process: ChildProcess|null = null;
-  private pending: Pending|null = null;
-  private stopping = false;
-  private reader = new FrameReader();
-  private header: ResponseHeader|null = null;
-  private stderr = '';
-
-  constructor(options: WorkerOptions) {
-    super();
-    this.id = options.id;
-    this.binary = options.binary;
-    this.args = options.args || [];
-    this.start();
-  }
-
-  get busy(): boolean {
-    return this.pending !== null;
-  }
-
-  get alive(): boolean {
-    return this.process !== null && this.process.exitCode === null &&
-        !this.stopping;
-  }
-
-  private start(): void {
-    const stdio: StdioOptions = ['pipe', 'pipe', 'pipe'];
-    const child = spawn(this.binary, ['--serve', ...this.args], {
-      stdio,
-      windowsHide: true,
-      // Detached, which on Windows means DETACHED_PROCESS: no console, and so
-      // no conhost.exe beside every worker. Four of those cost 40 MB of
-      // working set for a console nothing writes to -- the worker's output is
-      // three pipes.
-      //
-      // It does not outlive its supervisor despite the name: the worker exits
-      // when its stdin closes, and stdin closes when this process dies.
-      detached: true,
-    });
-    this.process = child;
-
-    child.stdout?.on('data', (chunk: Buffer) => this.onStdout(chunk));
-    child.stderr?.on('data', (chunk: Buffer) => this.onStderr(chunk));
-    child.on('error', (error) => this.onGone(null, null, error));
-    child.on('exit', (code, signal) => this.onGone(code, signal, null));
-
-    // The process is up as soon as spawn resolves the executable; there is no
-    // handshake in the protocol, and adding one would only move the failure --
-    // a binary that cannot start fails the first request just as visibly.
-    this.emit('ready');
-  }
-
-  private onStdout(chunk: Buffer): void {
-    this.reader.push(chunk);
-    for (;;) {
-      const frame = this.reader.next();
-      if (frame === null) {
-        return;
-      }
-      if (this.header === null) {
-        // Frame one of two: the JSON header.
-        try {
-          this.header = JSON.parse(frame.toString('utf8')) as ResponseHeader;
-        } catch {
-          this.fail(new Error(
-              `shotium: worker ${this.id} sent a header that is not JSON`));
-          return;
-        }
-        continue;
-      }
-      // Frame two: the image, empty when the header reported a failure or when
-      // the worker was asked to write the file itself.
-      const header = this.header;
-      this.header = null;
-      this.settle(header, frame);
-    }
-  }
-
-  private onStderr(chunk: Buffer): void {
-    this.stderr += chunk.toString('utf8');
-    const lines = this.stderr.split(/\r?\n/);
-    this.stderr = lines.pop() ?? '';
-    for (const line of lines) {
-      if (line.length > 0) {
-        this.emit('stderr', {worker: this.id, line});
-      }
-    }
-  }
-
-  private onGone(
-      code: number|null, signal: NodeJS.Signals|null,
-      error: Error|null): void {
-    const wasOwed = this.pending !== null;
-    this.process = null;
-    if (wasOwed) {
-      // A worker that dies mid-request is indistinguishable from one that never
-      // answered, which is the point: the retry path does not have to tell a
-      // crash from a hang.
-      this.fail(
-          error ||
-          new Error(`shotium: worker ${this.id} exited (code ${code}, signal ${
-              signal}) with a request in flight`));
-      this.emit('crash', {worker: this.id, code, signal});
-    } else if (error) {
-      this.emit('error', error);
-    }
-    this.emit('exit', {worker: this.id, code, signal});
-  }
-
-  private settle(header: ResponseHeader, payload: Buffer): void {
-    const pending = this.pending;
-    if (!pending) {
-      return;
-    }
-    this.pending = null;
-    this.served += 1;
-    if (header.ok) {
-      pending.resolve({header, image: header.path ? null : payload});
-    } else {
-      pending.reject(new Error(header.error || 'shotium: request failed'));
-    }
-  }
-
-  private fail(error: Error): void {
-    const pending = this.pending;
-    if (!pending) {
-      return;
-    }
-    this.pending = null;
-    pending.reject(error);
-  }
-
-  // Sends one request. Rejects if the worker dies before answering; there is no
-  // timeout here, because the deadline belongs to whoever owns the retry
-  // policy.
-  send(request: WireRequest): Promise<WorkerResult> {
-    if (this.pending) {
-      return Promise.reject(
-          new Error(`shotium: worker ${this.id} is already busy`));
-    }
-    if (!this.alive) {
-      return Promise.reject(new Error(`shotium: worker ${this.id} is not up`));
-    }
-    return new Promise<WorkerResult>((resolve, reject) => {
-      this.pending = {resolve, reject};
-      this.process?.stdin?.write(encodeRequest(request), (error) => {
-        if (error) {
-          this.fail(error);
-        }
-      });
-    });
-  }
-
-  // Closing stdin is the shutdown message: the worker sees the frame stream end
-  // on a frame boundary and exits 0. kill() is for when it has stopped
-  // listening.
-  stop(): void {
-    this.stopping = true;
-    this.process?.stdin?.end();
-  }
-
-  kill(): void {
-    this.stopping = true;
-    this.process?.kill();
-  }
-}
-
-export {Worker};

package/src/native.ts

@@ -1,234 +0,0 @@
-import fs from 'node:fs';
-import {createRequire} from 'node:module';
-import path from 'node:path';
-import {fileURLToPath} from 'node:url';
-
-import * as platformPackage from './lib/platform.js';
-import {toRequest} from './lib/request.js';
-import type {
-  NativeStartOptions,
-  PurgeOptions,
-  ScreenshotOptions,
-} from './types.js';
-
-export type {
-  NativeStartOptions,
-  PurgeOptions,
-  ScreenshotOptions,
-} from './types.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. It is opaque on purpose: everything
-// that can be done with it is a call on the binding below.
-type Engine = unknown;
-
-// What native/binding.cc exports. See shot/shot_api.h for the C ABI under it.
-interface NativeBinding {
-  create(optionsJson: string): Engine;
-  destroy(engine: Engine): void;
-  purge(engine: Engine, releaseWorkingSet: boolean): void;
-  capture(engine: Engine, requestJson: string): Promise<Buffer>;
-}
-
-// shot in this process, instead of in workers beside it.
-//
-// The difference from `runtime` is not the API, which is the same
-// screenshot(options), and not the request format, which is byte for byte the
-// same JSON. It is where blink is:
-//
-//   runtime   N worker processes, one screenshot each at a time, a crash is a
-//             retry, memory is N copies of an engine
-//   native    one engine in this process, one screenshot at a time ever, a
-//             crash takes the program with it, memory is one copy
-//
-// One at a time is not a limitation of this file. Blink is a process-wide
-// singleton -- it is initialised once and there is no path to a second one --
-// so an in-process engine is one renderer no matter how it is driven, and
-// worker_threads do not change that because they share the process. A caller
-// who wants four screenshots at once wants four processes, which is what the
-// pool is for.
-//
-// What it buys is that there is no process to start, nothing to find on disk,
-// no pipe, and no supervisor: a program that takes a handful of screenshots
-// and exits pays for one engine and talks to it directly.
-
-// 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 bindingDir: string|null = null;
-
-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;
-    bindingDir = path.dirname(candidate);
-    return binding;
-  }
-  const expected = platformPackage.packageName();
-  throw new Error(
-      'shotium: no native 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.\n' :
-           `  There is no build for ${process.platform}-${process.arch}.\n`) +
-      '  import("@shotkit/shotium") uses worker processes instead and needs ' +
-      'no addon.');
-}
-
-/**
- * The engine, in this process, and the queue in front of it.
- *
- * Same options and same output as `runtime`, and a different set of trades.
- * There is no worker process, so there is nothing to start, nothing to find on
- * disk and no pipe: a screenshot costs about a third less than through the
- * pool, and the whole thing is one process instead of five.
- *
- * What it gives up is what a separate process was providing for free. One
- * renderer, because blink is a process-wide singleton and `worker_threads`
- * share the process, so requests are serialised however many callers there
- * are. And no crash isolation: a renderer that dies takes the host program
- * with it, where the pool would have retried.
- *
- * 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 NativeRuntime {
-  private engine: Engine|null = null;
-  private tail: Promise<unknown> = Promise.resolve();
-
-  get running(): boolean {
-    return this.engine !== null;
-  }
-
-  /**
-   * Starts the engine. Safe to call twice; the second call is a no-op.
-   *
-   * `cacheDir` is the HTTP disk cache and `null` disables it, which is the
-   * default here. `resourceDir` is where `shotium_data.pak` and
-   * `shotium_strings.pak` are, and defaults to the directory the addon was
-   * loaded from, which is where they ship.
-   */
-  start(options: NativeStartOptions = {}): this {
-    if (this.engine) {
-      return this;
-    }
-    const native = load();
-
-    const engineOptions: Record<string, unknown> = {};
-    if (options.cacheDir !== null && options.cacheDir !== undefined) {
-      engineOptions.cacheDir = options.cacheDir;
-    }
-    if (options.userAgent !== undefined) {
-      engineOptions.userAgent = options.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 = options.resourceDir || bindingDir;
-
-    this.engine = native.create(JSON.stringify(engineOptions));
-    return this;
-  }
-
-  /** Stops the engine, after whatever is queued. */
-  async stop(): Promise<void> {
-    if (!this.engine) {
-      return;
-    }
-    // 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 engine = this.engine;
-    this.engine = null;
-    await this.tail.catch(() => {});
-    load().destroy(engine);
-  }
-
-  /**
-   * 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 resident worker 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.engine) {
-      return;
-    }
-    load().purge(this.engine, releaseWorkingSet);
-  }
-
-  /**
-   * Renders one screenshot. Resolves to the encoded image, or to `null` when
-   * `path` was given and the engine wrote the file itself.
-   */
-  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.
-    const request = toRequest(options);
-    if (!this.engine) {
-      this.start();
-    }
-    const engine = this.engine;
-    const native = 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(engine, JSON.stringify(request)));
-    this.tail = result.catch(() => {});
-    const image = await result;
-    return request.path ? null : image;
-  }
-}
-
-/** The shared in-process engine, started on first use. */
-const native = new NativeRuntime();
-
-/** One screenshot through the shared in-process engine. */
-const screenshot = (options: ScreenshotOptions): Promise<Buffer|null> =>
-    native.screenshot(options);
-
-export {native, screenshot};
-
-export default {NativeRuntime, native, screenshot};