@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/unique.js

@@ -0,0 +1,169 @@
+/**
+ * Unique-conflict probes: a documented `x-unique` set is 409 on a duplicate, 2xx is BACKEND_BUG.
+ *
+ * HTTP 409 is the unique-conflict class. Index names and product `error_key` / `vars.type` are
+ * not required. Uniqueness is never inferred from a 409 without the tag.
+ */
+import { generate } from "./generate/generate.js";
+import { requestContent } from "../spec/collection/request.js";
+import { idOf } from "./world/records.js";
+export const UNIQUE_CONFLICT_STATUS = 409;
+export function isUniqueConflictResponse(op, status) {
+    return status === UNIQUE_CONFLICT_STATUS && op.unique !== null && op.unique.length > 0;
+}
+/**
+ * Headers for a unique probe: never the original request's idempotency key, which would replay it.
+ * The key is omitted unless the document requires it, in which case a fresh one is sent.
+ */
+export function uniqueProbeHeaders({ header, required, fresh }) {
+    return required && header !== null && header !== "" ? { [header]: fresh } : {};
+}
+export function idempotencyHeaderRequired(op, model) {
+    if (op.idempotencyHeader === null)
+        return false;
+    const raw = model.rawOperations.get(op.operationId);
+    const params = raw?.parameters ?? [];
+    const match = params.find((param) => param.in === "header" && param.name === op.idempotencyHeader);
+    return match?.required === true;
+}
+export function bodyPropertyNames(op, model) {
+    const raw = model.rawOperations.get(op.operationId);
+    const schema = raw === undefined ? null : (requestContent(raw)?.schema ?? null);
+    if (schema === null || typeof schema !== "object")
+        return new Set();
+    const props = schema.properties;
+    if (props === null || typeof props !== "object")
+        return new Set();
+    return new Set(Object.keys(props));
+}
+function propertySchema(schema, name) {
+    if (schema === null)
+        return undefined;
+    const props = schema.properties;
+    if (props === null || typeof props !== "object")
+        return undefined;
+    const value = props[name];
+    return value !== null && typeof value === "object" ? value : undefined;
+}
+export function probeableUniqueSets(op, model, { phase, sets = op.unique ?? [] }) {
+    if (sets.length === 0)
+        return [];
+    const body = bodyPropertyNames(op, model);
+    const generated = new Set(op.generated);
+    const immutable = new Set(op.immutable);
+    return sets.filter((set) => {
+        if (phase === "update" && set.length > 0 && set.every((col) => immutable.has(col)))
+            return false;
+        return set.some((col) => body.has(col) && !generated.has(col));
+    });
+}
+export function uniqueTupleCollides(body, sets, existing) {
+    return sets.some((set) => {
+        const cols = set.filter((col) => Object.hasOwn(body, col));
+        if (cols.length === 0)
+            return false;
+        return existing.some((row) => cols.every((col) => JSON.stringify(row[col]) === JSON.stringify(body[col])));
+    });
+}
+export function uniquifyProbeBody(body, sets, { schema, token }) {
+    if (sets.length === 0)
+        return { ...body };
+    const out = { ...body };
+    const columns = new Set(sets.flat());
+    for (const col of columns) {
+        if (!Object.hasOwn(out, col))
+            continue;
+        out[col] = distinctUniqueValue(out[col], token, propertySchema(schema, col));
+    }
+    return out;
+}
+/**
+ * A value for a unique column that no earlier record — this run's or an earlier run's — holds.
+ *
+ * Drawn from the column's own schema with the token mixed in, so it honors `maximum`,
+ * `multipleOf`, `enum`, `pattern` and `format`. Appending a suffix to whatever was there broke
+ * every one of those. Where the schema admits nothing new, the value is left as it was and the
+ * caller's collision check decides.
+ */
+function distinctUniqueValue(value, token, schema) {
+    if (schema === undefined)
+        return value;
+    let h = 0;
+    for (const ch of token)
+        h = (Math.imul(h, 31) + ch.charCodeAt(0)) >>> 0;
+    const result = generate({ properties: { value: schema }, required: ["value"], type: "object" }, { distinct: new Set(["value"]), index: h % 1000, nonce: token });
+    if (!result.ok)
+        return value;
+    const next = result.value["value"];
+    return JSON.stringify(next) === JSON.stringify(value) ? value : next;
+}
+/**
+ * Overlays one unique set's values from a known row onto a body that otherwise does not collide.
+ *
+ * Other unique sets keep the uniquified values so two sets are never collided in one request.
+ */
+export function collisionCreateBody(base, known, write) {
+    const { bodyColumns, generated, scope, set } = write;
+    const out = { ...base };
+    const skip = new Set(generated);
+    let wrote = false;
+    for (const col of set) {
+        if (!bodyColumns.has(col) || skip.has(col))
+            continue;
+        const value = known[col] ?? scope[col];
+        if (value === undefined)
+            return null;
+        out[col] = value;
+        wrote = true;
+    }
+    return wrote ? out : null;
+}
+/** The update that makes `target` hold `source`'s values on a whole unique set, or `null` when it cannot. */
+export function collisionUpdatePatch(source, target, write) {
+    const { bodyColumns, generated, immutable, scope, set } = write;
+    const skip = new Set([...immutable, ...generated]);
+    const patch = {};
+    for (const col of set) {
+        const value = source[col] ?? scope[col];
+        if (value === undefined)
+            return null;
+        if (!bodyColumns.has(col) || skip.has(col)) {
+            /* A column the update cannot write must already agree, or the two rows would still
+             * differ on the set after the write — and accepting it would be correct. */
+            if (JSON.stringify(target[col] ?? scope[col]) !== JSON.stringify(value))
+                return null;
+            continue;
+        }
+        patch[col] = value;
+    }
+    return Object.keys(patch).length > 0 ? patch : null;
+}
+/**
+ * A unique value as a backend may have stored it: text trimmed and case-folded, a number and its
+ * numeral alike. A leak stored normalized is still the collision.
+ */
+function uniqueKey(value) {
+    if (typeof value === "number")
+        return String(value);
+    if (typeof value !== "string")
+        return JSON.stringify(value) ?? "undefined";
+    const text = value.trim();
+    return text !== "" && Number.isFinite(Number(text)) ? String(Number(text)) : text.toLowerCase();
+}
+/**
+ * The rows a refused collision stored anyway: listed after it but not before, holding the values the
+ * probe sent (`source`'s, or the scope's) on every column of `set`. Growth alone is no leak: another
+ * writer may add rows of its own between the two listings.
+ */
+export function leakedCollisions(set, source, around) {
+    const { after, before, identity, scope } = around;
+    const held = new Set(before.map((row) => idOf(row, identity)));
+    const sent = (col) => uniqueKey(source[col] ?? scope[col]);
+    return after
+        .filter((row) => set.every((col) => uniqueKey(row[col]) === sent(col)))
+        .flatMap((row) => {
+        const id = idOf(row, identity);
+        return id === undefined || held.has(id) ? [] : [id];
+    });
+}
+//# sourceMappingURL=unique.js.map

package/dist/api/runtime/upload-each.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Declared N-fixture fan-out: expand `uploads.each`, cap, warn, never invent files.
+ */
+import { type UploadContext } from "./upload.ts";
+export interface FixtureSlot {
+    path: string;
+    filename: string;
+    index: number;
+    total: number;
+}
+/** `null` = op is not in `each`. `[]` = declared but no usable files (caller stays pick-one). */
+export declare function resolveEachInvocations(operationId: string, context: UploadContext): Promise<FixtureSlot[] | null>;
+export declare function forEachInvocation<T>(operationId: string, uploads: UploadContext, fn: (next: UploadContext, slot: FixtureSlot | undefined) => Promise<T>): Promise<T[]>;
+//# sourceMappingURL=upload-each.d.ts.map

package/dist/api/runtime/upload-each.js

@@ -0,0 +1,69 @@
+/**
+ * Declared N-fixture fan-out: expand `uploads.each`, cap, warn, never invent files.
+ */
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { expandPattern, warnOnce } from "./upload.js";
+/** `null` = op is not in `each`. `[]` = declared but no usable files (caller stays pick-one). */
+export async function resolveEachInvocations(operationId, context) {
+    const patterns = context.uploads?.each?.[operationId];
+    if (patterns === undefined)
+        return null;
+    const readable = await readableFiles(patterns, context.configDir ?? process.cwd(), context);
+    if (readable.length === 0) {
+        context.warn?.(`uploads.each matched 0 files for ${operationId}`);
+        return [];
+    }
+    const limited = capped(readable, context.uploads?.eachMax);
+    if (limited.length < readable.length) {
+        context.warn?.(`uploads.each capped ${operationId} at ${limited.length} of ${readable.length}`);
+    }
+    return limited.map((path, index) => ({
+        filename: basename(path),
+        index,
+        path,
+        total: limited.length,
+    }));
+}
+/** Every distinct file the patterns match that can be read, sorted. */
+async function readableFiles(patterns, root, context) {
+    const seen = new Set();
+    const readable = [];
+    const warnMissing = warnOnce(context);
+    for (const pattern of patterns) {
+        const matches = await expandPattern(pattern, root, { label: "uploads.each", warn: warnMissing });
+        for (const path of matches) {
+            if (seen.has(path))
+                continue;
+            seen.add(path);
+            if (await eachFileReadable(path, context.warn))
+                readable.push(path);
+        }
+    }
+    return readable.sort();
+}
+/** The first `cap` files when `cap` is a usable limit below their count; otherwise all of them. */
+function capped(files, cap) {
+    return typeof cap === "number" && cap >= 0 && cap < files.length ? files.slice(0, cap) : files;
+}
+export async function forEachInvocation(operationId, uploads, fn) {
+    const slots = await resolveEachInvocations(operationId, uploads);
+    if (slots === null || slots.length === 0)
+        return [await fn(uploads, undefined)];
+    const out = [];
+    for (const slot of slots) {
+        out.push(await fn({ ...uploads, fixture: slot }, slot));
+    }
+    return out;
+}
+async function eachFileReadable(path, warn) {
+    try {
+        await readFile(path);
+        return true;
+    }
+    catch {
+        warn?.(`uploads.each could not read ${path}`);
+        return false;
+    }
+}
+//# sourceMappingURL=upload-each.js.map

package/dist/api/runtime/upload.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Resolves a file part: hook, then pool, then a dummy. Missing pool paths warn once
+ * and fall through — a bad glob must not crash a run.
+ */
+import type { Hooks, UploadFile, UploadRequest, UploadResolution, Uploads } from "../config/types/hooks.ts";
+export interface UploadContext {
+    seed: number;
+    uploads?: Uploads;
+    configDir?: string;
+    resolveUpload?: Hooks["resolveUpload"];
+    resolveInput?: Hooks["resolveInput"];
+    warn?: (message: string) => void;
+    /** Active `uploads.each` slot for this invocation. */
+    fixture?: {
+        path: string;
+        filename: string;
+        index: number;
+        total: number;
+    };
+    /** What the run remembers across parts; absent, each call starts fresh. */
+    memory?: UploadMemory;
+}
+interface PoolEntry {
+    path: string;
+    bytes: Uint8Array;
+    filename: string;
+    mediaType: string;
+}
+/**
+ * What one run remembers about its uploads: the pool it read, so every part picks from one read,
+ * and the warnings it gave, so a bad path is reported once rather than once per part. It rides on
+ * the run's `UploadContext`, which every copy shares by reference.
+ */
+export interface UploadMemory {
+    pool?: PoolEntry[];
+    readonly warned: Set<string>;
+}
+export declare function uploadMemory(): UploadMemory;
+/** The context's `warn`, saying each message once per run. */
+export declare function warnOnce(context: Pick<UploadContext, "memory" | "warn">): (message: string) => void;
+/**
+ * The file a part is sent when the `resolveUpload` hook gave none: the `uploads.each` slot, the
+ * pool, or a dummy of the declared type. The body encoder asks the hook, once per part, first.
+ */
+export declare function resolveUploadFile(request: UploadRequest, context: UploadContext): Promise<UploadFile>;
+export declare function resolveUploadOverride(request: UploadRequest, context: UploadContext): Promise<UploadResolution>;
+export declare function isUploadFile(value: unknown): value is UploadFile;
+export declare function isFieldOverride(value: unknown): value is {
+    fields: Record<string, string | UploadFile>;
+};
+/** How a pattern that matches nothing is reported: through `warn`, naming the `label` setting. */
+export interface PatternWarnings {
+    warn?: (message: string) => void;
+    label?: string;
+}
+export declare function expandPattern(pattern: string, root: string, { warn, label }?: PatternWarnings): Promise<string[]>;
+export {};
+//# sourceMappingURL=upload.d.ts.map

package/dist/api/runtime/upload.js

@@ -0,0 +1,241 @@
+/**
+ * Resolves a file part: hook, then pool, then a dummy. Missing pool paths warn once
+ * and fall through — a bad glob must not crash a run.
+ */
+import { isRaw } from "../config/types/raw.js";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { basename, join, relative, resolve, sep } from "node:path";
+import { dummyFile, mediaTypesCompatible, sniffMediaType } from "./dummy.js";
+import { mulberry32 } from "./fixture.js";
+export function uploadMemory() {
+    return { warned: new Set() };
+}
+/** The context's `warn`, saying each message once per run. */
+export function warnOnce(context) {
+    const warned = context.memory?.warned ?? new Set();
+    return (message) => {
+        if (warned.has(message))
+            return;
+        warned.add(message);
+        context.warn?.(message);
+    };
+}
+/**
+ * The file a part is sent when the `resolveUpload` hook gave none: the `uploads.each` slot, the
+ * pool, or a dummy of the declared type. The body encoder asks the hook, once per part, first.
+ */
+export async function resolveUploadFile(request, context) {
+    const fromEach = await fileFromFixtureSlot(request, context);
+    if (fromEach !== undefined)
+        return fromEach;
+    const fromPool = await pickFromPool(request, context);
+    if (fromPool !== undefined)
+        return fromPool;
+    const dummy = {
+        field: request.field,
+        index: request.index,
+        seed: context.seed,
+        variant: request.variant,
+    };
+    if (request.contentMediaType !== undefined)
+        dummy.contentMediaType = request.contentMediaType;
+    if (request.filename !== undefined)
+        dummy.filename = request.filename;
+    return dummyFile(dummy);
+}
+async function fileFromFixtureSlot(request, context) {
+    const slot = request.fixture ?? context.fixture;
+    if (slot === undefined)
+        return undefined;
+    try {
+        const bytes = new Uint8Array(await readFile(slot.path));
+        return { bytes, filename: slot.filename, mediaType: sniffMediaType(bytes, slot.filename) ?? OCTET };
+    }
+    catch {
+        warnOnce(context)(`uploads.each could not read ${slot.path}`);
+        return undefined;
+    }
+}
+export async function resolveUploadOverride(request, context) {
+    if (context.resolveUpload === undefined)
+        return null;
+    return context.resolveUpload(request);
+}
+export function isUploadFile(value) {
+    if (!isRaw(value))
+        return false;
+    return value.bytes instanceof Uint8Array && typeof value.filename === "string" && typeof value.mediaType === "string";
+}
+export function isFieldOverride(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    return ("fields" in value &&
+        value.fields !== null &&
+        typeof value.fields === "object");
+}
+/*
+ * What a file is sent as when neither its bytes nor its name say. The sniffer already falls back to
+ * the name, so its answer is the only one to ask.
+ */
+const OCTET = "application/octet-stream";
+async function pickFromPool(request, context) {
+    const patterns = context.uploads?.pool;
+    if (patterns === undefined || patterns.length === 0)
+        return undefined;
+    const memory = context.memory ?? uploadMemory();
+    memory.pool ??= await loadPool(patterns, context.configDir ?? process.cwd(), warnOnce(context));
+    const matching = memory.pool.filter((entry) => matchesPart(entry, request));
+    if (matching.length === 0)
+        return undefined;
+    const picked = stablePick(matching, { field: request.field, index: request.index, seed: context.seed });
+    return { bytes: picked.bytes, filename: picked.filename, mediaType: picked.mediaType };
+}
+function matchesPart(entry, request) {
+    const declared = request.contentMediaType;
+    if (mediaTypesCompatible(declared, entry.mediaType)) {
+        if (declared !== undefined && declared !== "" && declared !== "application/octet-stream")
+            return true;
+    }
+    if (request.filename !== undefined) {
+        const want = extOf(request.filename);
+        if (want !== "" && want === extOf(entry.filename))
+            return true;
+    }
+    if (declared === undefined || declared === "" || declared === "application/octet-stream")
+        return true;
+    return false;
+}
+/** One of `items` (never empty), the same one for the same seed, field and index. */
+function stablePick(items, { seed, field, index }) {
+    const rand = mulberry32(hash32(`${seed}\0${field}\0${index}`));
+    /* Fisher–Yates with the seeded RNG so the same seed always picks the same file. */
+    const copy = [...items];
+    for (let i = copy.length - 1; i > 0; i--) {
+        const j = Math.floor(rand() * (i + 1));
+        /* Both indices are in range: j <= i < copy.length. */
+        const a = copy[i];
+        copy[i] = copy[j];
+        copy[j] = a;
+    }
+    return copy[0];
+}
+async function loadPool(patterns, root, warn) {
+    const paths = new Set();
+    for (const pattern of patterns) {
+        const matches = await expandPattern(pattern, root, { warn });
+        for (const path of matches)
+            paths.add(path);
+    }
+    const entries = [];
+    for (const path of [...paths].sort()) {
+        try {
+            const bytes = new Uint8Array(await readFile(path));
+            const filename = basename(path);
+            entries.push({ bytes, filename, mediaType: sniffMediaType(bytes, filename) ?? OCTET, path });
+        }
+        catch {
+            warn(`uploads.pool could not read ${path}`);
+        }
+    }
+    return entries;
+}
+export async function expandPattern(pattern, root, { warn, label = "uploads.pool" } = {}) {
+    const absolute = resolve(root, pattern);
+    try {
+        const info = await stat(absolute);
+        if (info.isFile())
+            return [absolute];
+        if (info.isDirectory())
+            return walkFiles(absolute);
+    }
+    catch {
+        /* Not a literal path — try it as a glob. */
+    }
+    if (!/[?*]/.test(pattern)) {
+        warn?.(`${label} path not found: ${pattern}`);
+        return [];
+    }
+    const { dir, glob } = splitGlob(pattern);
+    const base = resolve(root, dir);
+    try {
+        const info = await stat(base);
+        if (!info.isDirectory()) {
+            warn?.(`${label} path not found: ${pattern}`);
+            return [];
+        }
+    }
+    catch {
+        warn?.(`${label} path not found: ${pattern}`);
+        return [];
+    }
+    const files = await walkFiles(base);
+    const matcher = globToRegExp(glob);
+    return files.filter((path) => matcher.test(toPosix(relative(base, path))));
+}
+async function walkFiles(dir) {
+    const out = [];
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...(await walkFiles(path)));
+        else if (entry.isFile())
+            out.push(path);
+    }
+    return out;
+}
+/** A glob's literal directory and the pattern under it; `pattern` has a wildcard. */
+function splitGlob(pattern) {
+    const normalized = pattern.replace(/\\/g, "/");
+    const slash = normalized.lastIndexOf("/", normalized.search(/[*?]/));
+    if (slash < 0)
+        return { dir: ".", glob: normalized };
+    return { dir: normalized.slice(0, slash), glob: normalized.slice(slash + 1) };
+}
+function globToRegExp(glob) {
+    let source = "^";
+    for (let i = 0; i < glob.length; i++) {
+        const ch = glob.charAt(i);
+        if (ch === "*" && glob[i + 1] === "*") {
+            const next = glob[i + 2];
+            if (next === "/") {
+                source += "(?:.*/)?";
+                i += 2;
+            }
+            else {
+                source += ".*";
+                i += 1;
+            }
+            continue;
+        }
+        if (ch === "*") {
+            source += "[^/]*";
+            continue;
+        }
+        if (ch === "?") {
+            source += "[^/]";
+            continue;
+        }
+        source += /[.+^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
+    }
+    source += "$";
+    return new RegExp(source, "i");
+}
+function toPosix(path) {
+    return path.split(sep).join("/");
+}
+function extOf(filename) {
+    const dot = filename.lastIndexOf(".");
+    if (dot < 0 || dot === filename.length - 1)
+        return "";
+    return filename.slice(dot + 1).toLowerCase();
+}
+function hash32(text) {
+    let hash = 2166136261;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 16777619);
+    }
+    return hash >>> 0;
+}
+//# sourceMappingURL=upload.js.map

package/dist/api/runtime/validate.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Response-schema validation — the floor beneath the behavioral checks.
+ *
+ * Schemas are compiled per operation+status and reused. `additionalProperties: false` is honored
+ * as written: a document that declares a closed object and a backend that returns extra fields
+ * genuinely disagree, and which one is wrong is a decision for the reader, not for the API tester.
+ */
+import type { OperationObject, JsonSchema } from "../spec/types.ts";
+import type { Exchange } from "./exchange.ts";
+export interface ValidationResult {
+    ok: boolean;
+    errors: string[];
+    /**
+     * Set when the documented schema could not be compiled, with AJV's reason. Nothing was
+     * validated, and the caller must say so — an uncompilable schema is not a passing one.
+     */
+    unchecked?: string;
+}
+export declare class SchemaValidator {
+    private readonly ajv;
+    private readonly cache;
+    /** `defs`: the recursive schemas a dereferenced document refers to (see `dereference`). */
+    constructor(defs?: Record<string, JsonSchema>);
+    /** Compiles the schema documented for this operation and status, if there is one. */
+    private compile;
+    /** Whether `response` holds to the schema `op` documents for its status. */
+    validate(operationId: string, op: OperationObject, response: Pick<Exchange, "responseBody" | "status">): ValidationResult;
+    /** True when the document actually documents this status for this operation. */
+    documents(op: OperationObject, status: number): boolean;
+    /**
+     * True when the response the document gives this status — exact, its range, else `default` —
+     * declares no body: a 201 that names the record only in `Location`, say.
+     */
+    documentsNoBody(op: OperationObject, status: number): boolean;
+}
+/**
+ * Whether `value` satisfies an already-normalized `schema` — the self-check every generated body
+ * passes before it is sent. Returns AJV's complaints, or `[]`.
+ */
+export declare function instanceErrors(schema: JsonSchema, value: unknown, defs?: Record<string, JsonSchema>): string[];
+//# sourceMappingURL=validate.d.ts.map