@shotkit/shotium 0.2.0 → 0.3.1

package/src/lib/client.ts

@@ -6,12 +6,15 @@ import path from 'node:path';
 import {fileURLToPath} from 'node:url';
 
 import type {
+  CaptureStats,
   DaemonOptions,
   DaemonStatus,
   ScreenshotOptions,
+  ScreenshotResult,
 } from '../types.js';
 
 import {resolveStartOptions} from './config.js';
+import {emptyStats} from './engine.js';
 import {endpointFor} from './endpoint.js';
 import {FrameReader, encodeFrame} from './protocol.js';
 import {timeoutFor, toRequest} from './request.js';
@@ -35,6 +38,10 @@ interface ClientReply {
   ok?: boolean;
   error?: string;
   path?: string;
+  // The daemon reports the same CaptureStats the in-process engine does, in
+  // its response header. It rides on the failure header too, which is why the
+  // rejection below carries it.
+  stats?: CaptureStats;
 }
 
 interface ClientResult {
@@ -126,7 +133,14 @@ class DaemonClient extends EventEmitter {
     if (header.ok) {
       pending.resolve({header, image: header.path ? null : payload});
     } else {
-      pending.reject(new Error(header.error || 'shotium: request failed'));
+      const error = new Error(header.error || 'shotium: request failed');
+      // Attached rather than dropped: a capture that failed part of the way
+      // through has already measured what it did, and that is usually the
+      // explanation. The in-process engine does the same.
+      if (header.stats) {
+        (error as Error & {stats?: CaptureStats}).stats = header.stats;
+      }
+      pending.reject(error);
     }
   }
 
@@ -151,15 +165,20 @@ class DaemonClient extends EventEmitter {
     });
   }
 
-  /** Resolves to the image, or to null when `path` was given. */
-  async screenshot(options: ScreenshotOptions): Promise<Buffer|null> {
+  /**
+   * One screenshot, and what taking it cost.
+   *
+   * The same shape the in-process engine returns, so that moving a program
+   * between the two is an import change and nothing else.
+   */
+  async screenshot(options: ScreenshotOptions): Promise<ScreenshotResult> {
     const request = toRequest(options);
     const result = await this.send({
       op: 'screenshot',
       request,
       timeout: timeoutFor(options),
     });
-    return result.image;
+    return {image: result.image, stats: result.header.stats ?? emptyStats()};
   }
 
   async status(): Promise<DaemonStatus> {
@@ -351,7 +370,7 @@ async function stop(options: DaemonOptions = {}):
 // here rather than sent, because it says which daemon to talk to and not what
 // to photograph.
 async function screenshot(options: ScreenshotOptions&{daemon?: DaemonOptions}):
-    Promise<Buffer|null> {
+    Promise<ScreenshotResult> {
   const {daemon, ...rest} = options;
   const client = await connect(daemon || {});
   try {

package/src/lib/config.ts

@@ -1,13 +1,114 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
 import type {StartOptions} from '../types.js';
 
 // 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 {
   cacheDir: string|null;
+  cacheMaxBytes: number;
   userAgent?: string;
   resourceDir?: string;
 }
 
+// One number, chosen rather than delegated.
+//
+// Passing 0 hands the decision to the disk cache backend, which sizes itself
+// against the volume's free space -- a defensible default for a browser
+// profile the user knows about, and a poor one for a directory that appears
+// under ~/.shotium because somebody imported a library. 256 MB holds a large
+// corpus of pages and their fonts, and is small enough that nobody has to
+// think about it.
+const DEFAULT_CACHE_MAX_BYTES = 256 * 1024 * 1024;
+
+/**
+ * One spelling of a path: absolute, with forward slashes.
+ *
+ * Every path this module hands back goes through here. On Windows the two
+ * separators are interchangeable to the filesystem and not to a caller
+ * comparing strings or writing a glob, and a library that returns whichever
+ * one `path.join` happened to produce makes that the caller's problem.
+ */
+export function normalizePath(target: string): string {
+  return path.resolve(target).replace(/\\/g, '/');
+}
+
+/**
+ * The project the current process belongs to: the nearest directory at or
+ * above the working directory that has a package.json.
+ *
+ * The working directory itself would be the obvious key and is the wrong one.
+ * It moves -- `process.chdir`, or a script run from a subdirectory -- and each
+ * value it takes would get a cache of its own, so a project would slowly
+ * accumulate directories that each know a third of its pages. The package root
+ * is the thing that stays put.
+ *
+ * Falls back to the working directory when there is no package.json above it,
+ * which is what a bare script has and is still better than nothing: it is at
+ * least stable for as long as the script runs from one place.
+ */
+function projectRoot(): string {
+  let dir = process.cwd();
+  for (;;) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      return process.cwd();
+    }
+    dir = parent;
+  }
+}
+
+/**
+ * Where every shotium cache directory lives. One level up from any single
+ * project's, which is what makes `target: 'all'` answerable.
+ *
+ * Under the home directory and not the temporary one, which is where this was
+ * until 0.3 was cut. $TMPDIR is defined by not surviving: /tmp is emptied on
+ * reboot, systemd-tmpfiles removes anything untouched for ten days, and macOS
+ * sweeps it on a schedule of its own. The entire value of an HTTP cache is the
+ * *next* run, so a default that lives somewhere designed to be cleared is a
+ * cache that stops working at exactly the moment it would have started paying
+ * for itself.
+ *
+ * `~/.shotium`, spelled the same on every platform. One place a user can look
+ * for it, one path to say in a bug report, and one directory to delete.
+ *
+ * $TMPDIR remains only as a fallback for a process with no home to speak of --
+ * some containers, some service accounts. That is a degradation and not a
+ * second location: there is no home directory holding a cache that would
+ * otherwise have been found.
+ */
+function shotiumHome(): string {
+  return path.join(os.homedir() || os.tmpdir(), '.shotium');
+}
+
+export function cacheRoot(): string {
+  return normalizePath(path.join(shotiumHome(), 'cache'));
+}
+
+/**
+ * The identifier for a project's cache directory: a hash of its root path.
+ *
+ * A hash rather than the path itself because the path contains separators,
+ * drive letters and whatever the user called their directory, none of which
+ * survive being a directory name. It is not a security measure and does not
+ * need to be one -- it is a fixed-length name for a variable-length string.
+ */
+export function projectKey(root: string = projectRoot()): string {
+  return crypto.createHash('sha1').update(normalizePath(root)).digest('hex');
+}
+
+/** This project's cache directory. */
+export function defaultCacheDir(): string {
+  return normalizePath(path.join(cacheRoot(), projectKey()));
+}
+
 // The one place that decides what "no options" means.
 //
 // It is shared rather than duplicated because the daemon's address is a hash of
@@ -16,16 +117,22 @@ export interface ResolvedStartOptions {
 // start a second engine next to the first one that was already warm. See
 // endpoint.ts.
 //
-// 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.
+// `cacheDir` defaults to this project's directory rather than to null, which
+// is the reverse of 0.2. The reason is measured: without a cache every capture
+// of an `https:` URL pays DNS, TLS and a round trip, which for a small page is
+// most of the wall clock and all of the surprise. The objection to a default
+// -- that a short-lived program leaves a directory behind -- is answered by
+// the directory being per-project, size-capped, and somewhere the platform's
+// own tooling knows how to clear, rather than by there being no cache.
+// `cacheDir: null` still turns it off.
 function resolveStartOptions(options: StartOptions = {}): ResolvedStartOptions {
   return {
-    cacheDir: options.cacheDir ?? null,
+    cacheDir: options.cacheDir === null ? null :
+                                          (options.cacheDir ?? defaultCacheDir()),
+    cacheMaxBytes: options.cacheMaxBytes ?? DEFAULT_CACHE_MAX_BYTES,
     userAgent: options.userAgent,
     resourceDir: options.resourceDir,
   };
 }
 
-export {resolveStartOptions};
+export {DEFAULT_CACHE_MAX_BYTES, resolveStartOptions};

package/src/lib/daemon.ts

@@ -4,7 +4,11 @@ import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 
-import type {DaemonOptions, DaemonStatus} from '../types.js';
+import type {
+  CaptureStats,
+  DaemonOptions,
+  DaemonStatus,
+} from '../types.js';
 
 import {resolveStartOptions} from './config.js';
 import type {ResolvedStartOptions} from './config.js';
@@ -46,6 +50,11 @@ interface DaemonReply {
   bytes?: number;
   path?: string;
   stopping?: boolean;
+  // What the capture cost, on the success header and on the failure one. The
+  // client turns it back into the same CaptureStats the in-process engine
+  // returns, so a program moving between the two changes an import and
+  // nothing else.
+  stats?: CaptureStats;
 }
 
 // An engine that outlives the process that asked for it.
@@ -306,7 +315,7 @@ class Daemon extends EventEmitter {
     this.armIdleTimer();
     this.emit('request', {id, file: request.file});
     this.engine.capture(request)
-        .then((image) => {
+        .then(({image, stats}) => {
           this.served += 1;
           this.reply(
               socket,
@@ -315,12 +324,20 @@ class Daemon extends EventEmitter {
                 ok: true,
                 bytes: image ? image.length : 0,
                 path: request.path,
+                stats,
               },
               image);
         })
-        .catch((error: Error) => {
-          this.reply(
-              socket, {id, ok: false, error: String(error.message || error)});
+        .catch((error: Error&{stats?: CaptureStats}) => {
+          // The counters go back with the failure, matching the in-process
+          // engine: a capture that timed out after fetching forty subresources
+          // has already said why, and the message alone has not.
+          this.reply(socket, {
+            id,
+            ok: false,
+            error: String(error.message || error),
+            stats: error.stats,
+          });
         })
         .finally(() => {
           this.inFlight -= 1;
@@ -374,7 +391,13 @@ class Daemon extends EventEmitter {
     }
     this.sockets.clear();
     await new Promise<void>((resolve) => this.server!.close(() => resolve()));
-    await this.engine.stop();
+    // dispose() rather than stop(), and this is the one caller that should.
+    // The daemon owns its process and is leaving it, so the real teardown is
+    // available and worth taking: joining the engine thread unwinds the
+    // network stack, which is what lets the disk cache write its index. A
+    // daemon that merely stood the engine down would leave the index dirty and
+    // make the next daemon rebuild it by scanning the directory.
+    await this.engine.dispose();
     this.emit('close', {});
   }
 }