@shotkit/shotium 0.0.1 → 0.2.0

package/src/lib/protocol.ts

@@ -0,0 +1,53 @@
+// The wire format shotium.exe --serve speaks, in both directions: a 4-byte
+// little-endian length followed by that many bytes.
+//
+// Length-prefixed rather than line-delimited because the payload is binary and
+// a newline inside a PNG is not a message boundary. See shot/shot_server.h for
+// the same description from the other end.
+//
+//   ->  [len][{"file":"...","width":1248,...}]
+//   <-  [len][{"ok":true,"bytes":97756}]  [len][<PNG bytes>]
+//   <-  [len][{"ok":false,"error":"..."}] [0]
+
+const HEADER_BYTES = 4;
+
+function encodeFrame(payload: Buffer): Buffer {
+  const header = Buffer.allocUnsafe(HEADER_BYTES);
+  header.writeUInt32LE(payload.length, 0);
+  return Buffer.concat([header, payload]);
+}
+
+function encodeRequest(request: unknown): Buffer {
+  return encodeFrame(Buffer.from(JSON.stringify(request), 'utf8'));
+}
+
+// Reassembles frames out of whatever sizes the pipe hands over.
+//
+// A stream is not a sequence of messages: one read can carry half a header, or
+// three responses and the start of a fourth. Everything downstream assumes
+// whole frames, so this is the only place that has to know that.
+class FrameReader {
+  private buffer: Buffer = Buffer.alloc(0);
+
+  push(chunk: Buffer): void {
+    this.buffer = this.buffer.length === 0 ?
+        chunk :
+        Buffer.concat([this.buffer, chunk]);
+  }
+
+  // The next complete frame, or null when there is not one yet.
+  next(): Buffer|null {
+    if (this.buffer.length < HEADER_BYTES) {
+      return null;
+    }
+    const length = this.buffer.readUInt32LE(0);
+    if (this.buffer.length < HEADER_BYTES + length) {
+      return null;
+    }
+    const frame = this.buffer.subarray(HEADER_BYTES, HEADER_BYTES + length);
+    this.buffer = this.buffer.subarray(HEADER_BYTES + length);
+    return frame;
+  }
+}
+
+export {HEADER_BYTES, encodeFrame, encodeRequest, FrameReader};

package/src/lib/request.ts

@@ -0,0 +1,97 @@
+import type {Clip, PageGotoParams, ScreenshotOptions} from '../types.js';
+
+const DEFAULT_TIMEOUT_MS = 30000;
+
+// 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';
+  fullPage?: boolean;
+  selector?: string;
+  quality?: number;
+  scale?: number;
+  omitBackground?: boolean;
+  path?: string;
+  pageGotoParams?: PageGotoParams;
+  clip?: Clip;
+  allowFileAccess?: boolean;
+  width?: number;
+  height?: number;
+}
+
+// Everything the worker understands, and nothing else. An unknown field is a
+// typo, and a typo that is silently dropped is a screenshot that quietly
+// ignored what was asked for -- so this rejects rather than filters.
+//
+// It is a runtime check even though the argument has a type, because the
+// argument having a type says nothing about a caller who is not compiled
+// against it: a JavaScript program, or a JSON body from somewhere else.
+const WIRE_FIELDS = new Set([
+  'file',
+  'type',
+  'fullPage',
+  'selector',
+  'quality',
+  'scale',
+  'omitBackground',
+  'path',
+  'pageGotoParams',
+  'clip',
+  'viewport',
+  'allowFileAccess',
+]);
+
+// One ScreenshotOptions, checked and flattened into what goes on the wire.
+//
+// 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') {
+    throw new TypeError('shotium: screenshot(options) needs an object');
+  }
+  if (typeof options.file !== 'string' || options.file.length === 0) {
+    throw new TypeError('shotium: options.file is required');
+  }
+
+  const request: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(options)) {
+    if (value === undefined) {
+      continue;
+    }
+    if (!WIRE_FIELDS.has(key)) {
+      throw new TypeError(`shotium: unknown option "${key}"`);
+    }
+    request[key] = value;
+  }
+
+  // The viewport is flattened because the worker takes width and height at the
+  // top level: it is one screenshot's frame, not a nested object on the wire.
+  if (request.viewport) {
+    const {width, height} = request.viewport as {
+      width?: number,
+      height?: number,
+    };
+    delete request.viewport;
+    if (width !== undefined) {
+      request.width = width;
+    }
+    if (height !== undefined) {
+      request.height = height;
+    }
+  }
+  return request as unknown as WireRequest;
+}
+
+function timeoutFor(options: ScreenshotOptions): number {
+  const timeout = options.pageGotoParams && options.pageGotoParams.timeout;
+  return typeof timeout === 'number' ? timeout : DEFAULT_TIMEOUT_MS;
+}
+
+export {
+  DEFAULT_TIMEOUT_MS,
+  WIRE_FIELDS,
+  timeoutFor,
+  toRequest,
+};

package/src/types.ts

@@ -0,0 +1,143 @@
+// 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 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 {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface PageGotoParams {
+  /** Milliseconds before the load is abandoned. Default 30000. */
+  timeout?: number;
+  /**
+   * `load` waits for parsing to finish, the load event to fire and every
+   * request to complete. `networkidle` additionally waits for a 500ms window
+   * with nothing in flight, which matters for documents that keep fetching
+   * after the load event -- CSS that pulls in more CSS, or a font a late style
+   * change brought in.
+   */
+  waitUntil?: 'load'|'networkidle';
+}
+
+/** The viewport the document is laid out in. */
+export interface Viewport {
+  /** CSS pixels. Default 1280. */
+  width?: number;
+  /** CSS pixels. Default 720. */
+  height?: number;
+}
+
+export interface ScreenshotOptions {
+  /** An http/https/file URL, or a local path. */
+  file: string;
+  /** Default `png`. */
+  type?: 'png'|'jpeg'|'webp';
+  /** Capture the whole document rather than the viewport. */
+  fullPage?: boolean;
+  /**
+   * Capture the box of the first element matching this CSS selector. Resolved
+   * inside the renderer with Document::querySelector -- there is no JavaScript
+   * engine, so nothing is injected into the page.
+   */
+  selector?: string;
+  /** 1-100, `jpeg` and `webp` only. Default 90. */
+  quality?: number;
+  /** Device scale factor, 0.01-8. Default 1. */
+  scale?: number;
+  /**
+   * Keep the alpha channel instead of painting the page's white backdrop.
+   * Rejected for `jpeg`, which has no alpha channel.
+   */
+  omitBackground?: boolean;
+  /** Write the image here instead of returning it, saving a round trip. */
+  path?: string;
+  pageGotoParams?: PageGotoParams;
+  /** A region of the document, in CSS pixels. */
+  clip?: Clip;
+  /** The viewport the document is laid out in. */
+  viewport?: Viewport;
+  /**
+   * Let the document read `file:` subresources. Off by default: a library does
+   * not get to decide for its caller that a document may read the filesystem it
+   * is rendered on.
+   */
+  allowFileAccess?: boolean;
+}
+
+export interface StartOptions {
+  /**
+   * 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.
+   */
+  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 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 `cacheDir`, `userAgent` and `resourceDir`, so a
+   * client never attaches to a daemon that renders with something other than
+   * what it asked for.
+   */
+  name?: string;
+  /** The pipe or socket to use, overriding both the name and the hash. */
+  endpoint?: string;
+  /**
+   * Exit after this long with no connections and nothing rendering. Default
+   * 300000; `0` never exits.
+   */
+  idleTimeoutMs?: number;
+  /**
+   * 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. */
+  spawn?: boolean;
+  /** Where a spawned daemon's diagnostics go. Default `$SHOTIUM_DAEMON_LOG`. */
+  logFile?: string;
+  /** How long to wait for a daemon this process started to bind. */
+  startTimeoutMs?: number;
+}
+
+export interface DaemonStatus {
+  ok?: boolean;
+  running?: boolean;
+  spawned?: boolean;
+  pid: number;
+  endpoint: string;
+  cacheDir: string|null;
+  userAgent?: string;
+  resourceDir?: string;
+  /** The engine has rendered at least once. */
+  warm: boolean;
+  uptimeMs: number;
+  connections: number;
+  inFlight: number;
+  served: number;
+  idleTimeoutMs: number;
+  version: string;
+}
+
+export interface PurgeOptions {
+  /**
+   * Also ask the OS to take the engine's pages back. The next screenshot pays
+   * them back in soft page faults -- a few milliseconds -- so this is for when
+   * there may not be a next one soon.
+   */
+  releaseWorkingSet?: boolean;
+}