slicetest 0.4.0 → 0.6.0

package/dist/neon.js

@@ -0,0 +1,113 @@
+/**
+ * Neon's HTTP query endpoint, served from the test database, so apps on the Neon
+ * serverless driver (`neon()` from @neondatabase/serverless, drizzle-orm/neon-http,
+ * @vercel/postgres's `sql`) run against the local Postgres without a code change.
+ *
+ * The driver posts each query to `https://api.<domain>/sql` for a connection string
+ * at `<endpoint>.<domain>`; with `db.neon` the app gets such a string and the
+ * intercepting proxy hands that host to this server.
+ */
+import http from "node:http";
+import pg from "pg";
+/** The made-up domain of the connection string the app gets; `*.` of it is intercepted. */
+export const NEON_DOMAIN = "neon.slicetest";
+/** `url` (the real test database) with its host replaced by a Neon-style endpoint host. */
+export function neonUrl(url) {
+    const u = new URL(url);
+    u.hostname = `ep-slicetest.${NEON_DOMAIN}`;
+    u.port = "";
+    u.searchParams.set("sslmode", "require");
+    return u.toString();
+}
+// Values stay as Postgres's text: the driver parses them itself from each field's type.
+const RAW = { getTypeParser: () => (value) => value };
+const ERROR_FIELDS = ["severity", "code", "detail", "hint", "position", "internalPosition", "internalQuery", "where", "schema", "table", "column", "dataType", "constraint", "file", "line", "routine"];
+export class NeonEndpoint {
+    #server;
+    #pool;
+    constructor(databaseUrl) {
+        this.#pool = new pg.Pool({ connectionString: databaseUrl, max: 5, types: RAW });
+        this.#pool.on("error", () => { });
+        this.#server = http.createServer((req, res) => {
+            this.#handle(req, res).catch((e) => res.headersSent || res.writeHead(500).end(String(e)));
+        });
+    }
+    /** `databaseUrl` is where queries really run: the worker database, or the `db.queries` proxy in front of it. */
+    static async start(databaseUrl) {
+        const endpoint = new NeonEndpoint(databaseUrl);
+        await new Promise((resolve) => endpoint.#server.listen(0, "127.0.0.1", resolve));
+        return endpoint;
+    }
+    get port() {
+        return this.#server.address().port;
+    }
+    /** Serve a connection the intercepting proxy terminated. */
+    attach(socket) {
+        this.#server.emit("connection", socket);
+    }
+    async #handle(req, res) {
+        const send = (status, body) => res.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(body));
+        if (req.method !== "POST" || !req.url?.startsWith("/sql"))
+            return send(404, { message: `slicetest's Neon endpoint only answers POST /sql, not ${req.method} ${req.url}` });
+        let body;
+        try {
+            let raw = "";
+            for await (const chunk of req)
+                raw += chunk;
+            body = JSON.parse(raw);
+        }
+        catch {
+            return send(400, { message: "invalid JSON body" });
+        }
+        const arrayMode = req.headers["neon-array-mode"] === "true";
+        const client = await this.#pool.connect();
+        try {
+            if ("queries" in body) {
+                const level = req.headers["neon-batch-isolation-level"];
+                const readOnly = req.headers["neon-batch-read-only"] === "true";
+                const deferrable = req.headers["neon-batch-deferrable"] === "true";
+                const mode = [level && `ISOLATION LEVEL ${String(level).replace(/([a-z])([A-Z])/g, "$1 $2").toUpperCase()}`, readOnly && "READ ONLY", deferrable && "DEFERRABLE"].filter(Boolean);
+                await client.query(`BEGIN${mode.length ? ` ${mode.join(" ")}` : ""}`);
+                try {
+                    const results = [];
+                    for (const q of body.queries)
+                        results.push(await run(client, q, arrayMode));
+                    await client.query("COMMIT");
+                    return send(200, { results });
+                }
+                catch (e) {
+                    await client.query("ROLLBACK").catch(() => { });
+                    throw e;
+                }
+            }
+            return send(200, await run(client, body, arrayMode));
+        }
+        catch (e) {
+            // Shaped like Neon's: a message plus Postgres's error fields, which the driver copies onto its error.
+            const err = e;
+            return send(400, { message: err.message, ...Object.fromEntries(ERROR_FIELDS.filter((f) => err[f] !== undefined).map((f) => [f, err[f]])) });
+        }
+        finally {
+            client.release();
+        }
+    }
+    async close() {
+        this.#server.closeAllConnections();
+        await new Promise((resolve) => this.#server.close(resolve));
+        await this.#pool.end();
+    }
+}
+async function run(client, { query, params = [] }, arrayMode) {
+    const result = await client.query({ text: query, values: params, rowMode: "array" });
+    const fields = result.fields.map((f) => ({
+        name: f.name,
+        tableID: f.tableID,
+        columnID: f.columnID,
+        dataTypeID: f.dataTypeID,
+        dataTypeSize: f.dataTypeSize,
+        dataTypeModifier: f.dataTypeModifier,
+        format: "text",
+    }));
+    const rows = arrayMode ? result.rows : result.rows.map((r) => Object.fromEntries(fields.map((f, i) => [f.name, r[i]])));
+    return { command: result.command, rowCount: result.rowCount, rows, fields, rowAsArray: arrayMode };
+}

package/dist/openapi.d.ts

@@ -15,6 +15,14 @@ export interface OperationSketch {
     responses: string[];
     /** Top-level properties of the first 2xx JSON response. */
     createdFields: string[];
+    /**
+     * The operation requires a bearer token (an `http: bearer`, `oauth2` or
+     * `openIdConnect` security scheme), with the scopes it lists. Undefined when
+     * it needs no token or accepts other credentials only.
+     */
+    bearer?: {
+        scopes: string[];
+    };
 }
 export interface Message {
     status?: number;
@@ -72,4 +80,6 @@ export declare function formatCoverage(spec: OpenApiSpec, hits: Set<string>): {
     markdown: string;
     text: string;
 };
+/** Where a spec fetched from the app (`openapi.fromApp`) is kept for the coverage report. */
+export declare function appSpecFile(coverageDir: string): string;
 export {};

package/dist/openapi.js

@@ -157,9 +157,27 @@ export class OpenApiSpec {
                 json: json ?? undefined,
                 responses,
                 createdFields: okSchema?.properties ? Object.keys(okSchema.properties) : [],
+                bearer: this.#bearer(op.security ?? this.doc.security),
             };
         });
     }
+    #bearer(security) {
+        if (!Array.isArray(security) || security.length === 0)
+            return undefined;
+        // An empty requirement makes credentials optional.
+        if (security.some((req) => Object.keys(req ?? {}).length === 0))
+            return undefined;
+        const schemes = this.doc.components?.securitySchemes ?? {};
+        for (const req of security) {
+            for (const [name, scopes] of Object.entries(req)) {
+                const s = this.#deref(schemes[name]);
+                if (s && ((s.type === "http" && String(s.scheme).toLowerCase() === "bearer") || s.type === "oauth2" || s.type === "openIdConnect")) {
+                    return { scopes: Array.isArray(scopes) ? scopes : [] };
+                }
+            }
+        }
+        return undefined;
+    }
     /** A value that satisfies `schema` (as far as a simple walk can): examples, defaults, enums, then types. */
     #sample(schema, depth = 0) {
         const s = this.#deref(schema);
@@ -345,3 +363,7 @@ function nullableToType(node) {
     }
     return node;
 }
+/** Where a spec fetched from the app (`openapi.fromApp`) is kept for the coverage report. */
+export function appSpecFile(coverageDir) {
+    return `${coverageDir}.spec.json`;
+}

package/dist/query-log.d.ts

@@ -0,0 +1,49 @@
+export interface Query {
+    sql: string;
+    /** Milliseconds since the log started. */
+    at: number;
+}
+/** A list of queries, with helpers for spotting N+1 patterns. */
+export declare class QueryList extends Array<Query> {
+    /** Statements grouped by shape (literals and parameters replaced by `?`), most frequent first. */
+    shapes(): {
+        sql: string;
+        count: number;
+    }[];
+    /** Without transaction control and session statements (`BEGIN`, `COMMIT`, `SAVEPOINT`, `SET`, …), which some drivers add around every query. */
+    withoutTransactions(): QueryList;
+    /** Shapes run at least `min` times (default 3): the usual signature of an N+1. */
+    repeated(min?: number): {
+        sql: string;
+        count: number;
+    }[];
+}
+export declare function queryList(queries: Query[]): QueryList;
+/** `SELECT * FROM t WHERE id = 7 AND name = 'x'` → `SELECT * FROM t WHERE id = ? AND name = ?`. */
+export declare function normalizeSql(sql: string): string;
+type Engine = "postgres" | "mysql";
+/**
+ * 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 declare class QueryLog {
+    #private;
+    private readonly server;
+    readonly port: number;
+    private constructor();
+    static start(engine: Engine, upstream: {
+        host: string;
+        port: number;
+    }): Promise<QueryLog>;
+    /** `url` with its host and port pointing at the proxy. */
+    proxyUrl(url: string): string;
+    /** Queries since the last `reset()`, or since `mark` (an index from `mark()`). */
+    queries(since?: number): QueryList;
+    mark(): number;
+    reset(): void;
+    close(): Promise<void>;
+}
+export {};

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,13 @@
 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 { Interceptor } from "./intercept.js";
 import { Mailbox } from "./mail.js";
+import { NeonEndpoint } from "./neon.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 +26,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 +44,10 @@ export declare class Runtime {
     private readonly recordDir?;
     readonly containers: Map<string, Dependency>;
     readonly mailbox?: Mailbox | undefined;
+    readonly issuer?: Issuer | undefined;
+    readonly queryLog?: QueryLog | undefined;
+    readonly interceptor?: Interceptor | undefined;
+    readonly neon?: NeonEndpoint | undefined;
     private constructor();
     get http(): HttpClient;
     static start(opts: ResolvedOptions, shared: {
@@ -53,5 +63,13 @@ export declare class Runtime {
     afterScenario(): Promise<void>;
     /** What happened during the current scenario, printed when it fails. */
     diagnostics(): Promise<string>;
+    /** Hand the coverage and recordings gathered so far to the run (merged when it ends). */
+    flush(): Promise<void>;
     stop(): Promise<void>;
 }
+/**
+ * The parts of the database URL, for apps that don't take one URL: JDBC (Spring's
+ * `spring.datasource.url` plus username / password), or separate host / port / name settings.
+ */
+export declare function connectionVars(engine: string, url: string, sqlitePath?: string): Record<string, string>;
+export declare function blockedHint(hosts: string[]): string;