versioncam 0.5.3 → 0.7.1

package/dist/driver/replay.d.ts

@@ -0,0 +1,263 @@
+import type { BrowserContext } from "playwright";
+/**
+ * Record a clip's responses once, and serve them on every run after.
+ *
+ * Some of what a clip films is not the app's to decide: a map's tiles, a
+ * model's answer, a job's status, a count that grows. Each comes from a
+ * server, at the server's speed and in its words of the day, so two
+ * recordings of one clip differ wherever one of them reaches the page, and
+ * the clip can never be re-rendered the same. The fix every app reached for
+ * was a mock written by hand, which is right once and wrong the day the
+ * endpoint changes. A replay is the server's own answer, written down the
+ * first time the clip runs and kept beside the clip as an input: the
+ * requests the config names are answered from it, and a request it does not
+ * hold fails the clip, with its URL, instead of quietly going live.
+ *
+ * The file is a HAR (one per clip, `<dir>/<clip>.har`), so a browser's
+ * developer tools can open it. Text bodies are written into it, where a
+ * diff can read them; binary bodies (a tile, an image) go beside it, under
+ * `bodies/`, named by their hash, so clips that load the same tiles store
+ * them once.
+ */
+export type ReplayMode = "auto" | "record" | "replay" | "live";
+/** A glob, in Playwright's syntax, or a regular expression, over the whole URL. */
+export type ReplayPattern = string | RegExp;
+export type ReplayConfig = {
+    /** The requests to record and replay, by URL. */
+    record: ReplayPattern[];
+    /**
+     * `"auto"`, the default, replays a clip whose file exists and records one
+     * whose file does not. `"record"` always records, `"replay"` fails a clip
+     * without a file, and `"live"` leaves every request to the network.
+     */
+    mode?: ReplayMode;
+    /** Where the files go. Default `replay/` beside the config. Commit it. */
+    dir?: string;
+    /**
+     * Responses the page reads over time, an event stream or lines of JSON,
+     * delivered one event or one line every `chunkMs` of the page's clock, so
+     * the same piece lands on the same frame every run.
+     */
+    pace?: {
+        url: ReplayPattern;
+        chunkMs: number;
+    }[];
+    /** Query parameters left out of the file and of the match, by name. */
+    redact?: string[];
+    /**
+     * What a request the replay does not hold does: `"fail"`, the default,
+     * fails the clip and names it; `"live"` sends it to the network and warns.
+     */
+    onMissing?: "fail" | "live";
+};
+export type ResolvedReplay = {
+    record: RegExp[];
+    mode: ReplayMode;
+    dir: string;
+    pace: {
+        url: RegExp;
+        chunkMs: number;
+    }[];
+    redact: string[];
+    onMissing: "fail" | "live";
+};
+/** How old a replay may be before `check` says so. */
+export declare const STALE_DAYS = 90;
+/**
+ * A glob in Playwright's syntax as a regular expression, so the recorder and
+ * the script it puts in the page match a URL the same way: `**` crosses `/`,
+ * `*` does not, `{a,b}` is either, and every other character is itself, `?`
+ * included. Anchored at both ends, as Playwright anchors a glob.
+ */
+export declare function globToRegExp(glob: string): RegExp;
+export declare function patternOf(pattern: ReplayPattern): RegExp;
+/**
+ * The URL a request is known by in the file: without its fragment and
+ * without the query parameters `redact` names, which are gone from the file
+ * and so cannot be part of the match.
+ */
+export declare function urlKey(url: string, redact: readonly string[]): string;
+type Header = {
+    name: string;
+    value: string;
+};
+type HarContent = {
+    size: number;
+    mimeType: string;
+    text?: string;
+    encoding?: "base64";
+    /** A binary body, under the replay's `bodies/`, by its SHA-256. */
+    _file?: string;
+};
+export type HarEntry = {
+    startedDateTime: string;
+    time: number;
+    request: {
+        method: string;
+        url: string;
+        httpVersion: string;
+        headers: Header[];
+        queryString: Header[];
+        cookies: [];
+        headersSize: -1;
+        bodySize: number;
+        postData?: {
+            mimeType: string;
+            text: string;
+        };
+    };
+    response: {
+        status: number;
+        statusText: string;
+        httpVersion: string;
+        headers: Header[];
+        cookies: [];
+        content: HarContent;
+        redirectURL: string;
+        headersSize: -1;
+        bodySize: number;
+    };
+    cache: Record<string, never>;
+    timings: {
+        send: number;
+        wait: number;
+        receive: number;
+    };
+};
+export type Har = {
+    log: {
+        version: "1.2";
+        creator: {
+            name: string;
+            version: string;
+        };
+        comment: string;
+        _versioncam: {
+            clip: string;
+            recorded: string;
+            recorder: string;
+        };
+        entries: HarEntry[];
+    };
+};
+export declare function sha256(bytes: Uint8Array): string;
+/**
+ * One recorded exchange, as the file keeps it: the secrets and the redacted
+ * parameters gone, a text body in the entry, a binary one handed to `store`
+ * and named here by its hash.
+ */
+export declare function entryOf(exchange: {
+    method: string;
+    url: string;
+    requestHeaders: Record<string, string>;
+    postData: string | null;
+    status: number;
+    statusText: string;
+    responseHeaders: Record<string, string>;
+    body: Uint8Array;
+}, options: {
+    redact: readonly string[];
+    recorded: string;
+    store: (hash: string, bytes: Uint8Array) => void;
+}): HarEntry;
+/**
+ * The entries of a replay, by what a request is known by, each list in the
+ * order the requests were made, and served in that order: the third poll of
+ * a job's status gets the third answer the job gave, and every poll after
+ * the last gets the last. Among answers to one URL, one recorded for the
+ * same request body is taken first, for an app that posts several queries
+ * to one endpoint in an order that can vary.
+ */
+export declare class ReplayBook {
+    private readonly byKey;
+    private readonly used;
+    private readonly redact;
+    constructor(entries: readonly HarEntry[], redact: readonly string[]);
+    answer(method: string, url: string, postData: string | null): HarEntry | null;
+}
+/** The file a clip's replay is in. */
+export declare function replayFile(dir: string, clipId: string): string;
+export declare function readReplay(file: string): Har;
+/** What `doctor` and `check` say about a clip's replay. */
+export declare function describeReplay(dir: string, clipId: string, now?: Date): {
+    file: string;
+    exists: false;
+} | {
+    file: string;
+    exists: true;
+    requests: number;
+    recorded: string;
+    ageDays: number;
+    recorder: string;
+};
+/** Which mode a clip runs in, once the file's presence is known. */
+export declare function effectiveMode(mode: ReplayMode, fileExists: boolean): "record" | "replay" | "live";
+/**
+ * A clip's replay while it runs: the routes it installs, what it recorded,
+ * what it could not answer, and how many answers are still on their way.
+ */
+export declare class ClipReplay {
+    readonly mode: "record" | "replay" | "live";
+    readonly file: string;
+    /** Requests the replay matched and did not hold, as "METHOD url". */
+    readonly misses: string[];
+    /** Requests sent live because the replay did not hold them (`onMissing: "live"`). */
+    readonly wentLive: string[];
+    private readonly recorded;
+    private readonly bodies;
+    private readonly book;
+    private readonly when;
+    private inFlight;
+    private waiters;
+    private readonly config;
+    private readonly clipId;
+    private readonly recorder;
+    constructor(config: ResolvedReplay, clipId: string, recorder: string, override?: ReplayMode);
+    /** The page-side script that paces streamed bodies, or null when nothing is paced. */
+    pacingScript(): string | null;
+    /** Install the routes. Before the page is opened, so its first request is caught. */
+    install(context: BrowserContext): Promise<void>;
+    /**
+     * Resolves once every request the replay has taken is answered and its body
+     * is in the page. The driver waits on it after each tick, so a request made
+     * in a frame is answered within that frame on every run, however long the
+     * network or the disk took: a tile arrives on the frame it was asked for.
+     */
+    idle(timeoutMs?: number): Promise<void>;
+    private settled;
+    private handle;
+    private record;
+    private serve;
+    /**
+     * What stops the clip: a request the replay was asked for and did not
+     * hold. Null when there is none.
+     */
+    failure(): string | null;
+    /**
+     * Write what was recorded. Only for a clip that passed: a replay of half a
+     * clip would serve a later run a different app than the one it shows.
+     */
+    write(): void;
+}
+/**
+ * Deliver a paced response a piece at a time on the page's own clock.
+ *
+ * The recorder cannot stream a response into the page: Playwright fulfils a
+ * request whole. So the page does it. For a URL the config paces, `fetch`
+ * hands back a response whose body is a stream that gives out one event of
+ * an event stream, or one line of anything else, every `chunkMs`, on the
+ * page's `setTimeout`, which the recorder's clock advances a frame at a
+ * time; and `EventSource` dispatches one event every `chunkMs` the same
+ * way. The same piece therefore lands on the same frame every run, at any
+ * frame rate. `window.__recorderReplay.pending` counts the bodies still
+ * arriving, and a settle waits for it to reach none.
+ *
+ * An `EventSource` whose stream has ended reports an error and stays
+ * closed, instead of reconnecting as a live one would: a replay would only
+ * answer it with the same stream again.
+ */
+export declare function pacedReplayScript(pace: readonly {
+    url: RegExp;
+    chunkMs: number;
+}[]): string;
+export {};