@shotkit/shotium 0.2.0 → 0.3.1

package/dist/index.d.ts

@@ -27,6 +27,75 @@ interface Viewport {
   /** CSS pixels. Default 720. */
   height?: number;
 }
+/**
+ * What a capture may do with the HTTP cache, spelled the way `fetch` spells
+ * it.
+ *
+ * - `default`: ordinary HTTP semantics. A fresh entry is used without asking,
+ *   a stale one is revalidated, and the response updates the cache.
+ * - `reload`: read nothing, write everything -- the browser's reload button.
+ *   The next capture is fast again.
+ * - `no-store`: neither read nor write. For a page that should not be left on
+ *   this machine's disk, which an authenticated one usually should not.
+ * - `only-if-cached`: the network may not be touched and a miss is an error.
+ *   Useful for a deterministic re-render of something already fetched.
+ */
+type CacheMode = 'default' | 'reload' | 'no-store' | 'only-if-cached';
+/** Where the milliseconds went. */
+interface CaptureTiming {
+  /**
+   * Fetching the top-level document. For a cold `https:` URL this is DNS, TCP,
+   * TLS and a round trip, and it is routinely larger than everything below --
+   * which is the single most useful thing this object says.
+   */
+  fetch: number;
+  /** Parse, subresources, style, layout, prepaint, paint. */
+  render: number;
+  /** Page/frame creation and synchronous document installation. */
+  setup: number;
+  /** Waiting for parsing, load completion and subresources. */
+  wait: number;
+  /** Capture selection plus style/layout/lifecycle advancement. */
+  lifecycle: number;
+  /** Extracting Blink's paint record. */
+  paint: number;
+  /** Raster-surface preparation and paint-record replay. */
+  raster: number;
+  encode: number;
+  /** Wall clock for the whole capture, so the phases above can be checked. */
+  total: number;
+}
+/** What one capture cost, and where its bytes came from. */
+interface CaptureStats {
+  /** Every resource the document asked for, itself included. */
+  requests: number;
+  /**
+   * Answered from the HTTP cache -- the body came from disk.
+   *
+   * Not the same as "no network was touched". A stale entry that can be
+   * revalidated costs a conditional request and a 304, and counts here too;
+   * what the cache saved is the download rather than the round trip. That is
+   * why `timing.fetch` can be tens of milliseconds with this set.
+   */
+  fromCache: number;
+  failed: number;
+  /** Decoded body bytes, summed -- not the transfer size. */
+  bytes: number;
+  /** The document's own status. 0 for a `file:` URL. */
+  httpStatus: number;
+  /** After redirects, which is what relative URLs resolved against. */
+  finalUrl: string;
+  timing: CaptureTiming;
+}
+/** One screenshot, and what taking it cost. */
+interface ScreenshotResult {
+  /**
+   * The encoded image, or `null` when `path` was given: the engine wrote the
+   * file itself and there is nothing left to hand back.
+   */
+  image: Buffer | null;
+  stats: CaptureStats;
+}
 interface ScreenshotOptions {
   /** An http/https/file URL, or a local path. */
   file: string;
@@ -62,14 +131,47 @@ interface ScreenshotOptions {
    * is rendered on.
    */
   allowFileAccess?: boolean;
+  /**
+   * What this capture may do with the HTTP cache. Default `default`.
+   *
+   * It applies to the subresources as well as the document: a `reload` that
+   * refreshed the HTML and reused yesterday's stylesheet would be a confusing
+   * thing to have asked for.
+   */
+  cache?: CacheMode;
+  /**
+   * Extra request headers, sent with the document and with the subresources
+   * that are same-origin with it.
+   *
+   * Same-origin is the whole rule and it is not configurable. A caller passing
+   * `Authorization` or `Cookie` means it for the site being photographed; a
+   * page that pulls a script from a CDN must not have the credential
+   * forwarded there.
+   */
+  headers?: Record<string, string>;
 }
 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.
+   * Root of the HTTP disk cache. `null` disables caching entirely.
+   *
+   * The default is a per-project directory under the system temporary
+   * directory -- see `cache.getDir()`. Caching is on by default because the
+   * alternative turned out to be worse: without it every capture of an
+   * `https:` URL pays for DNS, TLS and a round trip, which for a small page is
+   * most of the time the call takes and all of the time the caller did not
+   * expect to spend.
    */
   cacheDir?: string | null;
+  /**
+   * Ceiling on the cache directory, in bytes. Default 256 MB.
+   *
+   * Zero is not "unlimited" -- it hands the decision to the backend, which
+   * sizes itself against the volume's free space. That was a reasonable
+   * default when every user of the cache had named a directory on purpose; for
+   * one that appears by default under `~/.shotium` because somebody imported a
+   * library, a number somebody chose is better than a number nobody did.
+   */
+  cacheMaxBytes?: number;
   /** Overrides the built-in user agent string. */
   userAgent?: string;
   /**
@@ -78,6 +180,35 @@ interface StartOptions {
    */
   resourceDir?: string;
 }
+/** What `start()` reports about the engine it brought up. */
+interface StartResult {
+  /**
+   * Whether this lifecycle is started.
+   *
+   * A process has at most one engine, so `false` here does not mean there is
+   * nothing running -- it means this `Runtime` is stood down. `cacheDir` below
+   * is still answered from the engine, because a stood-down engine keeps its
+   * cache directory and reporting `null` would say the cache had gone away
+   * when what went away was the willingness to render.
+   */
+  running: boolean;
+  /** The directory in use, or `null` when caching is off. */
+  cacheDir: string | null;
+  /**
+   * Whether that directory is actually being cached into.
+   *
+   * A directory that cannot be created or written to costs nothing visible:
+   * the engine renders exactly as well without a cache, only slower, and every
+   * capture pays for the network again for a reason nothing reports. `false`
+   * with a `cacheDir` set means the open failed; `false` with `cacheDir: null`
+   * means no cache was asked for.
+   *
+   * It is not about sharing. Several processes may use one directory and all
+   * of them cache -- the backend takes no cross-process lock -- so `true` in
+   * two processes at once is the ordinary answer.
+   */
+  cacheActive: boolean;
+}
 interface DaemonOptions extends StartOptions {
   /**
    * Address the daemon by name instead of by configuration. Without it the
@@ -123,7 +254,16 @@ interface DaemonStatus {
   idleTimeoutMs: number;
   version: string;
 }
-interface PurgeOptions {
+/**
+ * Options for `releaseMemory()`.
+ *
+ * Named for what it does rather than for `purge`, which it was called until
+ * 0.3. With `cache.clear()` in the API the old name reads as though it clears
+ * the cache, and it does not: it hands back blink's heap, skia's caches and
+ * PartitionAlloc's free lists, all of which the engine rebuilds on demand.
+ * Nothing on disk is touched.
+ */
+interface ReleaseMemoryOptions {
   /**
    * 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
@@ -131,6 +271,150 @@ interface PurgeOptions {
    */
   releaseWorkingSet?: boolean;
 }
+/** Which cache directory an operation is about. */
+interface CacheTarget {
+  /**
+   * `current` (the default) is this project's directory, `all` is every
+   * directory shotium has created under the shared root -- `~/.shotium/cache`
+   * -- and a string is either an absolute path or one project hash as
+   * `getDir()` reports it.
+   *
+   * The absolute path is there because `start({cacheDir})` accepts any
+   * directory: without it, a caller who chose their own cache would have the
+   * one cache these methods could not see.
+   *
+   * `all` exists because the directories are per-project by default, so
+   * "clear shotium's caches" is otherwise something a caller cannot express
+   * without already knowing where the other projects were.
+   */
+  target?: 'current' | 'all' | (string & {});
+}
+/** One resource the cache is holding. */
+interface CacheEntry {
+  /** The resource, not the backend's key -- see `cache.getFiles()`. */
+  url: string;
+  /** Milliseconds since the Unix epoch. */
+  lastUsedMs: number;
+  bytes: number;
+  /** Which cache directory it was found in. */
+  dir: string;
+}
+interface CacheClearOptions extends CacheTarget {
+  /**
+   * Glob patterns matched against entry URLs -- not against filenames, which
+   * are hashes and would match nothing anybody would think to write.
+   *
+   * Supports `*` (within a path segment), `**` (across segments), `?` and
+   * `{a,b}`. Matching happens here rather than in the engine: the entries come
+   * back first, the patterns are applied to their URLs, and the ones that
+   * matched are what gets removed.
+   */
+  glob?: string[];
+  /**
+   * Remove entries not used for this many seconds. `0`, the default, means no
+   * age limit.
+   */
+  maxAge?: number;
+  /**
+   * Evict least-recently-used entries until the directory is at or below this
+   * many bytes. `0`, the default, means no size limit.
+   */
+  maxSize?: number;
+}
+interface CacheClearResult {
+  /**
+   * How many entries went. `-1` when the whole directory was dropped in one
+   * operation, which the backend does without counting them.
+   */
+  removed: number;
+  bytesBefore: number;
+  bytesAfter: number;
+  /** Which directory this result is for. */
+  dir: string;
+}
+//#endregion
+//#region src/lib/binding.d.ts
+/**
+ * The engine handle the addon hands back. Opaque on purpose: everything that
+ * can be done with it is a call on the binding below.
+ */
+type Engine = unknown;
+//#endregion
+//#region src/lib/cache.d.ts
+/**
+ * The cache, from the outside.
+ *
+ * Every method takes the engine handle if there is one, and that is not an
+ * optimisation. Within one process a cache directory has one backend: asking
+ * for a second one on the directory the engine holds waits for the engine's to
+ * go away, which it will not do while the engine is up. Borrowing is the only
+ * thing that returns.
+ *
+ * "If there is one" means the process, not the lifecycle. `stop()` stands the
+ * engine down without tearing it down, so an engine that has been stopped
+ * still holds its directory and still has to be borrowed from -- which is also
+ * what makes the cache survive a stop, and outlive one, and be worth having.
+ *
+ * Across processes there is no such constraint -- several of them may share a
+ * directory and all of them cache.
+ *
+ * The engine is fetched through a callback rather than held, because this
+ * object is built once at import time and the engine comes and goes.
+ */
+declare class Cache {
+  private readonly engineHandle;
+  constructor(engineHandle: () => Engine | null);
+  /**
+   * This project's cache directory, absolute and with forward slashes.
+   *
+   * It exists whether or not anything has been written to it -- the answer is
+   * "where the cache goes", not "where a cache is".
+   */
+  getDir(options?: CacheTarget): string;
+  /** Every directory the target names. `all` can be several; the rest, one. */
+  getDirs(options?: CacheTarget): string[];
+  /**
+   * What the cache is holding, by URL.
+   *
+   * Named `getFiles` for the operation callers reach for, and deliberately not
+   * returning filenames: the files in a cache directory are called things like
+   * `5349fbae98c6d9a1_0`, because the name is a hash of the entry key. A list
+   * of those answers no question anybody has. The URLs are what the entries
+   * are, and they are what `clear({glob})` matches against.
+   *
+   * This opens every entry to read its key and size, so it is a diagnostic
+   * rather than something to put on a request path.
+   */
+  getFiles(options?: CacheTarget): Promise<CacheEntry[]>;
+  /**
+   * Removes what the options select. With no options, everything.
+   *
+   * The three filters compose, and `glob` is applied here rather than in the
+   * engine: the entries are listed, their URLs are matched, and the ones that
+   * matched are what the engine is asked to remove. That keeps the pattern
+   * dialect in the layer whose users have opinions about pattern dialects, and
+   * keeps the engine's interface to exact URLs.
+   *
+   * Removal goes through the cache backend, never through the filesystem.
+   * Deleting the files directly would leave the backend's index naming entries
+   * that are no longer there, and the next process to open the directory
+   * either rebuilds the index from disk or, having found it inconsistent,
+   * discards it. That is the difference between clearing a cache and
+   * corrupting one.
+   */
+  clear(options?: CacheClearOptions): Promise<CacheClearResult[]>;
+  /**
+   * The engine handle, when there is an engine.
+   *
+   * Passed for every directory and not only the engine's own. It is never
+   * wrong to pass it -- the engine's thread can open any directory, and for
+   * the one it already has open, borrowing its backend is the only thing that
+   * returns. It is passing `null` while an engine is up that hangs, which is
+   * why this is conditional on neither the directory asked for nor on whether
+   * the engine is currently accepting captures.
+   */
+  private handleFor;
+}
 //#endregion
 //#region src/lib/client.d.ts
 interface ClientReply {
@@ -138,6 +422,7 @@ interface ClientReply {
   ok?: boolean;
   error?: string;
   path?: string;
+  stats?: CaptureStats;
 }
 interface ClientResult {
   header: ClientReply;
@@ -157,8 +442,13 @@ declare class DaemonClient extends EventEmitter {
   private settle;
   private failAll;
   send(message: Record<string, unknown>): Promise<ClientResult>;
-  /** Resolves to the image, or to null when `path` was given. */
-  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.
+   */
+  screenshot(options: ScreenshotOptions): Promise<ScreenshotResult>;
   status(): Promise<DaemonStatus>;
   shutdown(): Promise<{
     ok: boolean;
@@ -174,7 +464,7 @@ interface Daemon {
   /** 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;
@@ -193,9 +483,11 @@ interface Daemon {
  *
  *     import shotium from '@shotkit/shotium';
  *
- *     shotium.runtime.start();
- *     const png = await shotium.screenshot({file: 'https://example.com'});
- *     await shotium.runtime.stop();
+ *     shotium.start();
+ *     const {image, stats} = await shotium.screenshot({
+ *       file: 'https://example.com',
+ *     });
+ *     await shotium.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
@@ -204,11 +496,24 @@ interface Daemon {
  * 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 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.
+ * 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
@@ -216,53 +521,119 @@ interface Daemon {
  */
 declare class Runtime {
   private 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: Cache;
   get running(): boolean;
   /**
-   * 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.
+   * 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 `null`
-   * disables it; `resourceDir` is where `shotium_data.pak` and
+   * 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): this;
+  start(options?: StartOptions): StartResult;
+  /** What `start()` returned, asked again. */
+  status(): StartResult;
   /**
-   * Stops the engine, after whatever is queued.
+   * Stands the engine down, 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()`.
+   * 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.
+   *
+   * 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.
    */
   stop(): Promise<void>;
   /**
-   * 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.
+   * 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.
    */
-  purge(options?: PurgeOptions): void;
+  releaseMemory(options?: ReleaseMemoryOptions): void;
   /**
-   * Renders one screenshot. Resolves to the encoded image, or to `null` when
-   * `path` was given and the engine 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.
    */
-  screenshot(options: ScreenshotOptions): Promise<Buffer | null>;
+  screenshot(options: ScreenshotOptions): Promise<ScreenshotResult>;
 }
 /** The shared engine: one per process, started on first use. */
 declare const runtime: Runtime;
 /** One screenshot through the shared engine, starting it if it is not up. */
-declare const screenshot: (options: ScreenshotOptions) => Promise<Buffer | null>;
+declare const screenshot: (options: ScreenshotOptions) => Promise<ScreenshotResult>;
+declare const start: (options?: StartOptions) => StartResult;
+declare const status: () => StartResult;
+declare const stop: () => Promise<void>;
+declare const releaseMemory: (options?: ReleaseMemoryOptions) => void;
+/**
+ * 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.
+ */
+declare const cache: Cache;
 /**
  * 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.
  */
 declare const daemon: Daemon;
 declare const _default: {
   Runtime: typeof Runtime;
-  runtime: Runtime;
-  screenshot: (options: ScreenshotOptions) => Promise<Buffer | null>;
+  cache: Cache;
   daemon: Daemon;
+  releaseMemory: (options?: ReleaseMemoryOptions) => void;
+  runtime: Runtime;
+  screenshot: (options: ScreenshotOptions) => Promise<ScreenshotResult>;
+  start: (options?: StartOptions) => StartResult;
+  status: () => StartResult;
+  stop: () => Promise<void>;
+  readonly running: boolean;
 };
 //#endregion
-export { type Clip, Daemon, type DaemonClient, type DaemonOptions, type DaemonStatus, type PageGotoParams, type PurgeOptions, Runtime, type ScreenshotOptions, type StartOptions, type Viewport, daemon, _default as default, runtime, screenshot };
+export { Cache, type CacheClearOptions, type CacheClearResult, type CacheEntry, type CacheMode, type CacheTarget, type CaptureStats, type CaptureTiming, type Clip, Daemon, type DaemonClient, type DaemonOptions, type DaemonStatus, type PageGotoParams, type ReleaseMemoryOptions, Runtime, type ScreenshotOptions, type ScreenshotResult, type StartOptions, type StartResult, type Viewport, cache, daemon, _default as default, releaseMemory, runtime, screenshot, start, status, stop };
 //# sourceMappingURL=index.d.ts.map