slicetest 0.4.0 → 0.5.0

package/dist/query-log.js

@@ -0,0 +1,261 @@
+import net from "node:net";
+const TRANSACTION = /^\s*(BEGIN|START\s+TRANSACTION|COMMIT|END|ROLLBACK|SAVEPOINT|RELEASE|SET|SHOW|DISCARD|DEALLOCATE)\b/i;
+/** A list of queries, with helpers for spotting N+1 patterns. */
+export class QueryList extends Array {
+    /** Statements grouped by shape (literals and parameters replaced by `?`), most frequent first. */
+    shapes() {
+        const counts = new Map();
+        for (const q of this) {
+            const shape = normalizeSql(q.sql);
+            counts.set(shape, (counts.get(shape) ?? 0) + 1);
+        }
+        return [...counts].map(([sql, count]) => ({ sql, count })).sort((a, b) => b.count - a.count);
+    }
+    /** Without transaction control and session statements (`BEGIN`, `COMMIT`, `SAVEPOINT`, `SET`, …), which some drivers add around every query. */
+    withoutTransactions() {
+        return queryList(this.filter((q) => !TRANSACTION.test(q.sql)));
+    }
+    /** Shapes run at least `min` times (default 3): the usual signature of an N+1. */
+    repeated(min = 3) {
+        return this.shapes().filter((s) => s.count >= min);
+    }
+}
+export function queryList(queries) {
+    const list = new QueryList();
+    list.push(...queries);
+    return list;
+}
+/** `SELECT * FROM t WHERE id = 7 AND name = 'x'` → `SELECT * FROM t WHERE id = ? AND name = ?`. */
+export function normalizeSql(sql) {
+    return sql
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/'(?:[^']|'')*'/g, "?")
+        .replace(/\$\d+/g, "?")
+        .replace(/(?<![\w"`.])-?\d+(\.\d+)?\b/g, "?")
+        .replace(/\(\s*\?(\s*,\s*\?)+\s*\)/g, "(?)");
+}
+/**
+ * A TCP proxy between the app and its database that reads the wire protocol
+ * and records every statement the app runs, whatever its language or driver.
+ * Postgres: simple queries and extended-protocol executions. MySQL: COM_QUERY
+ * and prepared-statement executions. Connections that switch to TLS are
+ * forwarded but not read.
+ */
+export class QueryLog {
+    server;
+    port;
+    #queries = [];
+    #started = performance.now();
+    #sockets = new Set();
+    constructor(server, port) {
+        this.server = server;
+        this.port = port;
+    }
+    static async start(engine, upstream) {
+        let log;
+        const server = net.createServer((client) => log.#connect(engine, client, upstream));
+        await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+        log = new QueryLog(server, server.address().port);
+        return log;
+    }
+    /** `url` with its host and port pointing at the proxy. */
+    proxyUrl(url) {
+        const u = new URL(url);
+        u.hostname = "127.0.0.1";
+        u.port = String(this.port);
+        return u.toString();
+    }
+    /** Queries since the last `reset()`, or since `mark` (an index from `mark()`). */
+    queries(since = 0) {
+        return queryList(this.#queries.slice(since));
+    }
+    mark() {
+        return this.#queries.length;
+    }
+    reset() {
+        this.#queries = [];
+    }
+    #record(sql) {
+        this.#queries.push({ sql, at: Math.round(performance.now() - this.#started) });
+    }
+    #connect(engine, client, upstream) {
+        const server = net.connect(upstream.port, upstream.host);
+        this.#sockets.add(client).add(server);
+        const close = () => {
+            client.destroy();
+            server.destroy();
+            this.#sockets.delete(client);
+            this.#sockets.delete(server);
+        };
+        client.on("error", close).on("close", close);
+        server.on("error", close).on("close", close);
+        const reader = engine === "postgres" ? new PostgresReader((sql) => this.#record(sql)) : new MysqlReader((sql) => this.#record(sql));
+        client.on("data", (chunk) => {
+            try {
+                reader.fromClient(chunk);
+            }
+            catch {
+                reader.opaque = true;
+            }
+            server.write(chunk);
+        });
+        server.on("data", (chunk) => {
+            try {
+                reader.fromServer(chunk);
+            }
+            catch {
+                reader.opaque = true;
+            }
+            client.write(chunk);
+        });
+    }
+    async close() {
+        for (const s of this.#sockets)
+            s.destroy();
+        await new Promise((resolve) => this.server.close(resolve));
+    }
+}
+const cstring = (buf, start) => {
+    const end = buf.indexOf(0, start);
+    return [buf.toString("utf8", start, end), end + 1];
+};
+class PostgresReader {
+    record;
+    opaque = false;
+    #buf = Buffer.alloc(0);
+    #startup = true;
+    #awaitingSsl = false;
+    #statements = new Map();
+    #portals = new Map();
+    constructor(record) {
+        this.record = record;
+    }
+    fromServer(chunk) {
+        if (!this.#awaitingSsl)
+            return;
+        this.#awaitingSsl = false;
+        // 'S' (TLS) or 'G' (GSSAPI encryption): the rest is encrypted.
+        if (chunk[0] === 0x53 || chunk[0] === 0x47)
+            this.opaque = true;
+    }
+    fromClient(chunk) {
+        if (this.opaque)
+            return;
+        this.#buf = Buffer.concat([this.#buf, chunk]);
+        for (;;) {
+            if (this.#startup) {
+                if (this.#buf.length < 8)
+                    return;
+                const len = this.#buf.readInt32BE(0);
+                if (this.#buf.length < len)
+                    return;
+                const code = this.#buf.readInt32BE(4);
+                this.#buf = this.#buf.subarray(len);
+                if (code === 80877103 || code === 80877104)
+                    this.#awaitingSsl = true;
+                else if (code !== 80877102)
+                    this.#startup = false;
+                continue;
+            }
+            if (this.#buf.length < 5)
+                return;
+            const type = String.fromCharCode(this.#buf[0]);
+            const len = this.#buf.readInt32BE(1);
+            if (this.#buf.length < len + 1)
+                return;
+            const msg = this.#buf.subarray(5, len + 1);
+            this.#buf = this.#buf.subarray(len + 1);
+            this.#message(type, msg);
+        }
+    }
+    #message(type, msg) {
+        if (type === "Q") {
+            this.record(cstring(msg, 0)[0]);
+        }
+        else if (type === "P") {
+            const [name, next] = cstring(msg, 0);
+            this.#statements.set(name, cstring(msg, next)[0]);
+        }
+        else if (type === "B") {
+            const [portal, next] = cstring(msg, 0);
+            this.#portals.set(portal, this.#statements.get(cstring(msg, next)[0]) ?? "");
+        }
+        else if (type === "E") {
+            const sql = this.#portals.get(cstring(msg, 0)[0]);
+            if (sql)
+                this.record(sql);
+        }
+    }
+}
+const CLIENT_QUERY_ATTRIBUTES = 1 << 27;
+class MysqlReader {
+    record;
+    opaque = false;
+    #client = Buffer.alloc(0);
+    #server = Buffer.alloc(0);
+    #prepares = [];
+    #attributes = false;
+    #statements = new Map();
+    constructor(record) {
+        this.record = record;
+    }
+    #read(buf, each) {
+        while (buf.length >= 4) {
+            const len = buf.readUIntLE(0, 3);
+            if (buf.length < len + 4)
+                break;
+            each(buf[3], buf.subarray(4, len + 4));
+            buf = buf.subarray(len + 4);
+        }
+        return Buffer.from(buf);
+    }
+    fromClient(chunk) {
+        if (this.opaque)
+            return;
+        this.#client = this.#read(Buffer.concat([this.#client, chunk]), (seq, p) => {
+            // The handshake response asking for TLS is a short packet with CLIENT_SSL set.
+            if (seq === 1 && p.length === 32 && (p.readUInt32LE(0) & 0x800) !== 0)
+                this.opaque = true;
+            if (seq === 1 && p.length >= 4)
+                this.#attributes = (p.readUInt32LE(0) & CLIENT_QUERY_ATTRIBUTES) !== 0;
+            // Commands start a new sequence; handshake and auth packets don't.
+            if (seq !== 0 || p.length === 0)
+                return;
+            if (p[0] === 0x03)
+                this.record(this.#queryText(p));
+            else if (p[0] === 0x16)
+                this.#prepares.push(p.toString("utf8", 1));
+            else if (p[0] === 0x17 && p.length >= 5) {
+                const sql = this.#statements.get(p.readUInt32LE(1));
+                if (sql)
+                    this.record(sql);
+            }
+        });
+    }
+    /** COM_QUERY text; with query attributes it follows a parameter count, a set count and the attributes. */
+    #queryText(p) {
+        if (!this.#attributes)
+            return p.toString("utf8", 1);
+        const count = p[1];
+        // Drivers send no attributes (count 0, one set); anything else is read past heuristically.
+        if (count === 0)
+            return p.toString("utf8", 3);
+        const text = p.toString("utf8", 3);
+        const start = text.search(/\b(SELECT|INSERT|UPDATE|DELETE|WITH|REPLACE|CALL|SET|BEGIN|COMMIT|ROLLBACK|START)\b/i);
+        return start >= 0 ? text.slice(start) : text;
+    }
+    fromServer(chunk) {
+        if (this.opaque || this.#prepares.length === 0) {
+            this.#server = Buffer.alloc(0);
+            return;
+        }
+        this.#server = this.#read(Buffer.concat([this.#server, chunk]), (seq, p) => {
+            if (seq !== 1 || this.#prepares.length === 0)
+                return;
+            const sql = this.#prepares.shift();
+            if (p[0] === 0x00 && p.length >= 5)
+                this.#statements.set(p.readUInt32LE(1), sql);
+        });
+    }
+}

package/dist/runtime.d.ts

@@ -1,9 +1,11 @@
 import { App } from "./app.js";
+import { Issuer } from "./auth.js";
 import type { ResolvedOptions } from "./config.js";
 import { Dependency } from "./containers.js";
 import { Db } from "./db.js";
 import { HttpClient } from "./http.js";
 import { Mailbox } from "./mail.js";
+import { QueryLog } from "./query-log.js";
 import { Stub } from "./stub.js";
 import { type MaskOptions, type Trace } from "./trace.js";
 export interface ScenarioContext {
@@ -22,6 +24,8 @@ export interface ScenarioContext {
     trace: (opts?: MaskOptions) => Promise<Trace>;
     /** Mail the app sent during the scenario. Needs `mail: true` in the config. */
     mail: Mailbox;
+    /** The OpenID Connect issuer the app trusts: `auth.token(claims)`. Needs `auth` in the config. */
+    auth: Issuer;
 }
 /** Everything one test file needs: its own database, stub servers and app process. */
 export declare class Runtime {
@@ -38,6 +42,8 @@ export declare class Runtime {
     private readonly recordDir?;
     readonly containers: Map<string, Dependency>;
     readonly mailbox?: Mailbox | undefined;
+    readonly issuer?: Issuer | undefined;
+    readonly queryLog?: QueryLog | undefined;
     private constructor();
     get http(): HttpClient;
     static start(opts: ResolvedOptions, shared: {

package/dist/runtime.js

@@ -2,12 +2,14 @@ import { randomUUID } from "node:crypto";
 import { writeFile } from "node:fs/promises";
 import path from "node:path";
 import { App } from "./app.js";
+import { Issuer } from "./auth.js";
 import { Dependency } from "./containers.js";
 import { Db, formatChanges } from "./db.js";
 import { engineFor } from "./drivers/index.js";
 import { formatHistory, HttpClient } from "./http.js";
 import { Mailbox } from "./mail.js";
 import { OpenApiSpec } from "./openapi.js";
+import { QueryLog } from "./query-log.js";
 import { Recorder } from "./recording.js";
 import { Stub } from "./stub.js";
 import { buildTrace, mask } from "./trace.js";
@@ -25,12 +27,14 @@ export class Runtime {
     recordDir;
     containers;
     mailbox;
+    issuer;
+    queryLog;
     #http;
     /** Responses from the app that don't match its OpenAPI spec, this scenario. */
     #contract = [];
     /** Documented responses seen in this file, for the run's coverage report. */
     #covered = new Set();
-    constructor(app, services, db, stubs, opts, vars, specs, coverageDir, recorders = new Map(), recordDir, containers = new Map(), mailbox) {
+    constructor(app, services, db, stubs, opts, vars, specs, coverageDir, recorders = new Map(), recordDir, containers = new Map(), mailbox, issuer, queryLog) {
         this.app = app;
         this.services = services;
         this.db = db;
@@ -43,6 +47,8 @@ export class Runtime {
         this.recordDir = recordDir;
         this.containers = containers;
         this.mailbox = mailbox;
+        this.issuer = issuer;
+        this.queryLog = queryLog;
         this.#http = this.#client();
     }
     #client() {
@@ -76,6 +82,8 @@ export class Runtime {
         const services = new Map();
         let db;
         let mailbox;
+        let issuer;
+        let queryLog;
         try {
             // Loaded first: a broken spec should fail before anything is started.
             const specs = {
@@ -106,12 +114,22 @@ export class Runtime {
             if (failed)
                 throw failed.reason;
             const vars = { "db.url": url };
+            if (opts.db.queries && engine.name !== "sqlite") {
+                const u = new URL(url);
+                queryLog = await QueryLog.start(engine.name, { host: u.hostname, port: Number(u.port || (engine.name === "mysql" ? 3306 : 5432)) });
+                vars["db.url"] = queryLog.proxyUrl(url);
+                db.attachQueryLog(queryLog);
+            }
             if (engine.name === "sqlite")
                 vars["db.path"] = (await import("./drivers/sqlite.js")).sqlitePath(url);
             if (opts.mail) {
                 mailbox = await Mailbox.start();
                 Object.assign(vars, { "mail.host": mailbox.host, "mail.port": String(mailbox.port), "mail.url": mailbox.url });
             }
+            if (opts.auth) {
+                issuer = await Issuer.start(opts.auth);
+                Object.assign(vars, { "auth.issuer": issuer.url, "auth.jwks": issuer.jwksUrl, "auth.audience": issuer.audience });
+            }
             for (const [name, c] of containers) {
                 vars[`container.${name}`] = c.address;
                 vars[`container.${name}.host`] = c.host;
@@ -126,7 +144,7 @@ export class Runtime {
                 vars[`service.${name}.port`] = String(started.port);
             }
             const app = await App.start(opts.app, opts.root, vars);
-            return new Runtime(app, services, db, stubs, opts, vars, specs, shared.coverageDir, recorders, shared.recordDir, containers, mailbox);
+            return new Runtime(app, services, db, stubs, opts, vars, specs, shared.coverageDir, recorders, shared.recordDir, containers, mailbox, issuer, queryLog);
         }
         catch (e) {
             await Promise.all([...services.values()].map((s) => s.stop()));
@@ -134,11 +152,14 @@ export class Runtime {
             await Promise.all([...stubs.values()].map((s) => s.close()));
             await Promise.allSettled([...containers.values()].map((c) => c.stop()));
             await mailbox?.close();
+            await issuer?.close();
+            await queryLog?.close();
             throw e;
         }
     }
     context() {
         const mailbox = this.mailbox;
+        const issuer = this.issuer;
         return {
             http: this.http,
             db: this.db,
@@ -169,6 +190,11 @@ export class Runtime {
                     throw new Error("slicetest: mail is off. Add `mail: true` to the config and point the app's SMTP settings at {{mail.host}} / {{mail.port}}.");
                 return mailbox;
             },
+            get auth() {
+                if (!issuer)
+                    throw new Error("slicetest: auth is off. Add `auth: true` to the config and point the app's JWT settings at {{auth.issuer}} / {{auth.jwks}}.");
+                return issuer;
+            },
         };
     }
     /** The app and every service, for checks that apply to all of them. */
@@ -195,6 +221,8 @@ export class Runtime {
         for (const recorder of this.recorders.values())
             recorder.reset();
         this.mailbox?.reset();
+        this.issuer?.reset();
+        this.queryLog?.reset();
         await Promise.all([...this.containers.values()].map((c) => c.reset()));
         this.http.reset();
         for (const p of this.#processes())
@@ -265,6 +293,9 @@ export class Runtime {
         const unmatched = this.#unmatched();
         if (unmatched.length > 0)
             sections.push(`stub calls with no matching route:\n${unmatched.join("\n")}`);
+        const chaos = [...this.stubs.values()].map((s) => s.describeChaos()).filter((c) => c !== undefined);
+        if (chaos.length > 0)
+            sections.push(chaos.join("\n"));
         const contract = this.#contractViolations();
         if (contract.length > 0)
             sections.push(`OpenAPI mismatches:\n${contract.map((c) => `  ${c}`).join("\n")}`);
@@ -279,6 +310,11 @@ export class Runtime {
         }
         if (this.mailbox)
             sections.push(this.mailbox.describe());
+        if (this.queryLog) {
+            const q = this.queryLog.queries();
+            const top = q.shapes().slice(0, 5).map((s) => `  ${s.count > 1 ? `×${s.count} ` : ""}${s.sql.length > 160 ? `${s.sql.slice(0, 157)}...` : s.sql}`);
+            sections.push(q.length ? `SQL the app ran during this scenario (${q.length} statements, most frequent first):\n${top.join("\n")}` : "SQL the app ran during this scenario: (none)");
+        }
         const logs = this.app.scenarioLogs();
         sections.push(logs ? `app output during this scenario:\n${logs}` : "app output during this scenario: (none)");
         for (const [name, service] of this.services) {
@@ -303,6 +339,8 @@ export class Runtime {
             ...[...this.stubs.values()].map((s) => s.close()),
             ...[...this.containers.values()].map((c) => c.stop()),
             this.mailbox?.close(),
+            this.issuer?.close(),
+            this.queryLog?.close(),
         ]);
         const failed = results.find((r) => r.status === "rejected");
         if (failed)

package/dist/stub.d.ts

@@ -19,6 +19,27 @@ export interface RecordedCall {
     };
     /** Answered by the fallback (e.g. an example from the provider's OpenAPI spec), not a registered route. */
     fallback?: boolean;
+    /** The fault `chaos()` injected instead of the normal answer: `503`, `reset`. */
+    fault?: string;
+}
+/**
+ * Faults injected into a stub's answers, to test the app's retries, timeouts and
+ * fallbacks. Random faults come from a seeded generator, so a failing run can be
+ * replayed with the seed printed in the failure output.
+ */
+export interface ChaosOptions {
+    /** Fail the first `n` calls, then answer normally: the shape of a retry test. */
+    failFirst?: number;
+    /** Share of calls (0–1) answered with one of `statuses`. */
+    errorRate?: number;
+    /** Error statuses to pick from. Default [500, 502, 503]; 429 and 503 come with `Retry-After: 1`. */
+    statuses?: number[];
+    /** Share of calls (0–1) whose connection is dropped without an answer. */
+    networkErrorRate?: number;
+    /** Extra delay for every call, in ms: a fixed value or a [min, max] range. */
+    latency?: number | [number, number];
+    /** Seed for the random choices. Default: `SLICETEST_CHAOS_SEED`, else random. */
+    seed?: number;
 }
 export interface StubResponse {
     status?: number;
@@ -70,6 +91,17 @@ export declare class Stub {
      * `call.params`) or be a RegExp; `method` may be `*`. Later routes win.
      */
     on(method: string, path: string | RegExp, match?: MatchOptions): RouteBuilder;
+    /**
+     * Inject faults into this stub's answers for the rest of the scenario:
+     * `stub("payments").chaos({ failFirst: 2 })` to test a retry,
+     * `chaos({ errorRate: 0.3, latency: [50, 200] })` to test resilience.
+     * Calls that fault don't use up `once()` / `times()` routes.
+     */
+    chaos(opts: ChaosOptions): this;
+    /** Calls `chaos()` answered with a fault. */
+    faults(): RecordedCall[];
+    /** The active `chaos()` settings and what they did, for failure output; undefined when off. */
+    describeChaos(): string | undefined;
     /** Calls received so far, optionally filtered by method, path and conditions (same syntax as `on()`). */
     calls(method?: string, path?: string | RegExp, match?: MatchOptions): RecordedCall[];
     unmatched(): RecordedCall[];

package/dist/stub.js

@@ -12,6 +12,7 @@ export class Stub {
     #fallback;
     /** Appended to the 501 answer for a call nothing could answer. */
     #hint;
+    #chaos;
     url = "";
     constructor(name) {
         this.name = name;
@@ -61,6 +62,74 @@ export class Stub {
         };
         return builder;
     }
+    /**
+     * Inject faults into this stub's answers for the rest of the scenario:
+     * `stub("payments").chaos({ failFirst: 2 })` to test a retry,
+     * `chaos({ errorRate: 0.3, latency: [50, 200] })` to test resilience.
+     * Calls that fault don't use up `once()` / `times()` routes.
+     */
+    chaos(opts) {
+        for (const key of ["errorRate", "networkErrorRate"]) {
+            const v = opts[key];
+            if (v !== undefined && !(v >= 0 && v <= 1))
+                throw new Error(`slicetest: chaos ${key} must be between 0 and 1, got ${v}`);
+        }
+        if (opts.statuses && (opts.statuses.length === 0 || opts.statuses.some((s) => !Number.isInteger(s) || s < 400 || s > 599))) {
+            throw new Error(`slicetest: chaos statuses must be 4xx/5xx codes, got ${JSON.stringify(opts.statuses)}`);
+        }
+        const envSeed = Number(process.env.SLICETEST_CHAOS_SEED);
+        const seed = opts.seed ?? (Number.isInteger(envSeed) ? envSeed : Math.floor(Math.random() * 2 ** 31));
+        this.#chaos = { opts, seed, random: mulberry32(seed), calls: 0 };
+        return this;
+    }
+    /** Calls `chaos()` answered with a fault. */
+    faults() {
+        return this.#calls.filter((c) => c.fault !== undefined);
+    }
+    /** The active `chaos()` settings and what they did, for failure output; undefined when off. */
+    describeChaos() {
+        const c = this.#chaos;
+        if (!c)
+            return undefined;
+        const settings = Object.entries(c.opts)
+            .filter(([k]) => k !== "seed")
+            .map(([k, v]) => `${k} ${JSON.stringify(v)}`)
+            .join(", ");
+        return `chaos on ${this.name}: ${settings}; ${this.faults().length} of ${c.calls} calls faulted. Replay with SLICETEST_CHAOS_SEED=${c.seed}`;
+    }
+    /** Delay and fault for the next call, consuming the random sequence in a fixed order. */
+    async #injectFault() {
+        const c = this.#chaos;
+        if (!c)
+            return undefined;
+        const { opts, random } = c;
+        const n = ++c.calls;
+        const lat = opts.latency;
+        const ms = lat === undefined ? 0 : Array.isArray(lat) ? lat[0] + Math.floor(random() * (lat[1] - lat[0] + 1)) : lat;
+        if (ms > 0)
+            await new Promise((r) => setTimeout(r, ms));
+        const statuses = opts.statuses ?? [500, 502, 503];
+        const pick = () => statuses[Math.floor(random() * statuses.length)];
+        if (opts.failFirst !== undefined && n <= opts.failFirst)
+            return { status: pick() };
+        const roll = random();
+        if (roll < (opts.networkErrorRate ?? 0))
+            return "reset";
+        if (roll < (opts.networkErrorRate ?? 0) + (opts.errorRate ?? 0))
+            return { status: pick() };
+        return undefined;
+    }
+    #fail(call, req, res, fault) {
+        call.matched = true;
+        if (fault === "reset") {
+            call.fault = "reset";
+            req.socket.destroy();
+            return;
+        }
+        call.fault = String(fault.status);
+        const retry = fault.status === 429 || fault.status === 503 ? { "retry-after": "1" } : undefined;
+        this.#send(call, res, { status: fault.status, headers: retry, body: { error: "slicetest chaos", status: fault.status } });
+    }
     /** Calls received so far, optionally filtered by method, path and conditions (same syntax as `on()`). */
     calls(method, path, match = {}) {
         const compiled = path === undefined ? undefined : compilePath(path);
@@ -82,6 +151,7 @@ export class Stub {
     reset() {
         this.#routes = [];
         this.#calls = [];
+        this.#chaos = undefined;
     }
     /**
      * Answer calls that no registered route matches, instead of failing with 501.
@@ -127,6 +197,12 @@ export class Stub {
             route = r;
             break;
         }
+        // Faults only replace answers the stub would give: an unknown route still fails as unmatched.
+        if (route || this.#fallback) {
+            const fault = await this.#injectFault();
+            if (fault)
+                return this.#fail(call, req, res, fault);
+        }
         if (!route) {
             let out;
             try {
@@ -262,3 +338,14 @@ function parseJson(body) {
         return undefined;
     }
 }
+/** A small seeded PRNG: the same seed gives the same faults on every run. */
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}

package/dist/webhook.d.ts

@@ -0,0 +1,40 @@
+/** A custom HMAC scheme: `header: prefix + hmac(secret, body)`. */
+export interface HmacScheme {
+    header: string;
+    /** Default `sha256`. */
+    algorithm?: string;
+    /** Default `hex`. */
+    encoding?: "hex" | "base64";
+    /** Prepended to the digest, e.g. `sha256=`. */
+    prefix?: string;
+}
+export type WebhookProvider = "stripe" | "github" | "slack" | "shopify" | "standard" | HmacScheme;
+export interface WebhookOptions {
+    provider: WebhookProvider;
+    /** The signing secret the app is configured with. For `standard` (Svix), `whsec_<base64>` or the raw key. */
+    secret: string;
+    /** Event type, sent where the provider puts it: `X-GitHub-Event`, `X-Shopify-Topic`. */
+    event?: string;
+    /** Unix seconds the signature is made for. Default: now. */
+    timestamp?: number;
+    /** Signed ten minutes ago: an app that rejects replays must refuse it. */
+    stale?: boolean;
+    /** Signed with a different secret: the app must refuse it. */
+    invalidSignature?: boolean;
+    /** Message id for `standard` (`webhook-id`). Default: a random `msg_…`. */
+    id?: string;
+    /** Extra request headers. */
+    headers?: Record<string, string>;
+}
+/**
+ * The headers a provider sends with `body`, signed with `secret` the way its
+ * SDK verifies them: Stripe's `Stripe-Signature`, GitHub's
+ * `X-Hub-Signature-256`, Slack's `v0` signature, Shopify's base64 HMAC and
+ * Standard Webhooks (Svix, Resend, Clerk, …).
+ */
+export declare function signWebhook(body: string, opts: WebhookOptions): Record<string, string>;
+/** The bytes to send and their content type: objects as JSON, URLSearchParams as a form (Slack commands), strings as-is. */
+export declare function webhookBody(payload: unknown): {
+    body: string;
+    type: string;
+};