@fuzdev/fuz_app 0.134.0 → 0.136.0

package/dist/testing/cross_backend/ws_outbound_overflow.js

@@ -0,0 +1,276 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-backend parity suite for the **per-connection outbound bound** over a
+ * real upgrade.
+ *
+ * Both spines hold what waits to be written to one WebSocket to a byte budget
+ * (`BackendWebsocketTransport`'s `outbound_queue_bytes` on the TS side, the
+ * Rust `fuz_realtime` outbound queue on the other; both default to 4 MiB, each
+ * waiting frame charged its UTF-8 length plus 64 bytes). A frame that does not
+ * fit closes the socket with `WS_CLOSE_OUTBOUND_OVERFLOW` and the reason
+ * `outbound queue overflow`; the credential stays good, so a client reconnects
+ * under its ordinary backoff. The code and the reason are therefore wire
+ * contract, and this suite is the pin that runs on both.
+ *
+ * It drives the backend's `_testing_flood_notifications` action, which queues
+ * a burst of notifications onto the caller's own connection in one synchronous
+ * run — so the burst waits at once whether or not the client is reading, and
+ * the overflow is deterministic. The cases:
+ *
+ * - **within the budget** — a small burst arrives whole and in order, ahead of
+ *   its response, and the socket stays open.
+ * - **large, within the budget** — a burst of a few mebibytes, most of the
+ *   default budget, arrives the same way: every frame whole, in order, the
+ *   response last. Megabyte frames can outrun a socket's buffer, and where
+ *   they do — the Deno TS spine, as observed; Node and Bun write the burst
+ *   through — the frames behind the first wait on the backend's write pump.
+ * - **overflow** — a burst far past the budget closes the socket with the code
+ *   and the exact reason; the response of the flooding request never arrives;
+ *   any flood frames that did arrive form a contiguous prefix of the burst.
+ *   A second connection on the same account keeps dispatching throughout.
+ * - **refusal** — a burst past the action's own size limit is refused with
+ *   `invalid_params`, and the socket stays open.
+ * - **no connection** — over HTTP RPC the action refuses with `invalid_params`
+ *   and reason `no_connection`, rather than answering as though it flooded.
+ * - **the action's limits** — over HTTP RPC a call at each of the action's
+ *   limits (`count`, `size`, `count` × `size`) is refused for having no
+ *   connection, and a call one past each is refused `invalid_params` with no
+ *   reason. Both spines check the limits before they look for the connection
+ *   and before they build a payload, so the boundaries are read off the
+ *   refusal and no burst is ever allocated — which pins the two spines'
+ *   limits equal.
+ *
+ * What the suite does **not** assert, because it is each implementation's own:
+ * how many frames accepted before the overflow reach the client (the Rust
+ * spine discards them all; the TS spine may deliver the first), and the exact
+ * boundary a burst of tiny frames overflows at.
+ *
+ * The wire literals are deliberate independent copies of the producers'
+ * constants — parity by test, so a value changed on one side fails here
+ * instead of moving both at once.
+ *
+ * The flood action is gated on the daemon token, so the flooding socket
+ * upgrades with it and no `Origin` (both spines discard a daemon token
+ * presented in a browser context). Gated on `capabilities.ws`; cross-process
+ * only (`create_ws_transport` needs a real bound socket), and only for a
+ * backend that mounts `_testing_flood_notifications` on its WS endpoint.
+ *
+ * @module
+ */
+import { assert, describe } from 'vitest';
+import { create_jsonrpc_request } from '../../http/jsonrpc_helpers.js';
+import { create_admitted_ws_transport } from '../transports/ws_transport.js';
+import { is_notification, is_response_for } from '../transports/ws_client.js';
+import { test_if } from './capabilities.js';
+import { cross_rpc_call } from './cell_cross_helpers.js';
+/** The close code both spines send on an outbound overflow. */
+const WS_CLOSE_OUTBOUND_OVERFLOW = 4005;
+/** The close reason both spines send with it. */
+const OUTBOUND_OVERFLOW_REASON = 'outbound queue overflow';
+const FLOOD_METHOD = '_testing_flood_notifications';
+const FLOOD_NOTIFICATION_METHOD = '_testing_flood';
+const HEARTBEAT_METHOD = 'heartbeat';
+const INVALID_PARAMS = -32602;
+const REASON_NO_CONNECTION = 'no_connection';
+const MIB = 1024 * 1024;
+/** A burst within any budget. */
+const FITS = { count: 3, size: 8 };
+/**
+ * A burst of 3 MiB in megabyte frames: charged a little over 3 MiB with its
+ * envelopes and overhead, inside the 4 MiB default budget.
+ */
+const LARGE_FITS = { count: 3, size: MIB };
+/** A burst of 32 MiB — eight times the default budget. */
+const OVERFLOWS = { count: 32, size: MIB };
+/** One mebibyte past the action's `count` × `size` limit. */
+const REFUSED = { count: 65, size: MIB };
+/** The most notifications one flood call may ask for. */
+const FLOOD_MAX_COUNT = 65_536;
+/** The largest payload one flood call may ask for. */
+const FLOOD_MAX_SIZE = 16 * MIB;
+/** The most payload bytes (`count` × `size`) one flood call may ask for. */
+const FLOOD_MAX_TOTAL_BYTES = 64 * MIB;
+/**
+ * A `count` and `size`, each within its own limit, whose product is exactly
+ * one byte past `FLOOD_MAX_TOTAL_BYTES` (the factors of 2^26 + 1).
+ */
+const FLOOD_ONE_BYTE_PAST_TOTAL = { count: 265, size: 253_241 };
+/**
+ * Calls at and one past each of the flood action's limits. Each "past" call
+ * holds the other axis at zero, or both axes within their own limit, so one
+ * limit alone decides it.
+ */
+const FLOOD_LIMIT_CASES = [
+    { name: 'count at its limit', params: { count: FLOOD_MAX_COUNT, size: 1 }, within: true },
+    { name: 'count past its limit', params: { count: FLOOD_MAX_COUNT + 1, size: 0 }, within: false },
+    { name: 'size at its limit', params: { count: 1, size: FLOOD_MAX_SIZE }, within: true },
+    { name: 'size past its limit', params: { count: 0, size: FLOOD_MAX_SIZE + 1 }, within: false },
+    {
+        name: 'count × size at its limit, both axes at theirs or under',
+        params: { count: FLOOD_MAX_TOTAL_BYTES / FLOOD_MAX_SIZE, size: FLOOD_MAX_SIZE },
+        within: true
+    },
+    {
+        name: 'count × size at its limit, count at its own',
+        params: { count: FLOOD_MAX_COUNT, size: FLOOD_MAX_TOTAL_BYTES / FLOOD_MAX_COUNT },
+        within: true
+    },
+    {
+        name: 'count × size past its limit, each axis within its own',
+        params: { count: FLOOD_MAX_COUNT, size: FLOOD_MAX_TOTAL_BYTES / FLOOD_MAX_COUNT + 1 },
+        within: false
+    },
+    {
+        // the smallest step past the product limit: the row above overshoots it by
+        // `FLOOD_MAX_COUNT` bytes, so alone it admits a limit that many bytes loose
+        name: 'count × size one byte past its limit',
+        params: FLOOD_ONE_BYTE_PAST_TOTAL,
+        within: false
+    }
+];
+/** How long the test waits for the megabyte burst and its response. */
+const LARGE_BURST_TIMEOUT_MS = 15_000;
+/** How long the test waits for the overflow close. */
+const CLOSE_TIMEOUT_MS = 15_000;
+/**
+ * Register the outbound-overflow parity suite over a real upgrade: a burst
+ * within the budget arrives whole, one past it closes the socket with
+ * `WS_CLOSE_OUTBOUND_OVERFLOW` and no response, and the account's other
+ * connection is unaffected.
+ */
+export const describe_ws_outbound_overflow_cross_tests = (options) => {
+    const { setup_test, capabilities, base_url, ws_path, origin, rpc_path } = options;
+    /** A daemon-token socket the backend has admitted — the one that floods itself. */
+    const open_flooder = (fixture) => create_admitted_ws_transport({
+        base_url,
+        ws_path,
+        cookies: [],
+        origin: null,
+        headers: fixture.create_daemon_token_headers()
+    });
+    /** The `index` of every flood notification `client` received, in arrival order. */
+    const flood_indices = (client) => client.messages
+        .filter(is_notification(FLOOD_NOTIFICATION_METHOD))
+        .map((msg) => msg.params.index);
+    const assert_open_and_answering = async (client, id, message) => {
+        assert.deepStrictEqual(await client.request(id, HEARTBEAT_METHOD, {}), {}, message);
+        assert.strictEqual(client.close_code, null, message);
+    };
+    describe('websocket outbound overflow parity', { timeout: 30_000 }, () => {
+        test_if(capabilities.ws, 'a burst within the budget arrives in order, ahead of its response', async () => {
+            const fixture = await setup_test();
+            const client = await open_flooder(fixture);
+            try {
+                const result = await client.request('fits', FLOOD_METHOD, FITS);
+                assert.deepStrictEqual(result, { queued: FITS.count });
+                assert.deepStrictEqual(flood_indices(client), [0, 1, 2]);
+                const frames = client.messages.filter(is_notification(FLOOD_NOTIFICATION_METHOD));
+                for (const frame of frames) {
+                    assert.strictEqual(frame.params.payload, 'x'.repeat(FITS.size));
+                }
+                // the whole burst is ahead of the response
+                const response_at = client.messages.findIndex(is_response_for('fits'));
+                const last_flood_at = client.messages.lastIndexOf(frames.at(-1));
+                assert.ok(last_flood_at < response_at, 'the burst precedes its response');
+                await assert_open_and_answering(client, 'after_fits', 'the socket stays open');
+            }
+            finally {
+                await client.close().catch(() => { });
+            }
+        });
+        test_if(capabilities.ws, 'a multi-megabyte burst within the budget arrives whole and in order, the response last', async () => {
+            const fixture = await setup_test();
+            const client = await open_flooder(fixture);
+            try {
+                const result = await client.request('large_fits', FLOOD_METHOD, LARGE_FITS, LARGE_BURST_TIMEOUT_MS);
+                assert.deepStrictEqual(result, { queued: LARGE_FITS.count });
+                assert.deepStrictEqual(flood_indices(client), [0, 1, 2]);
+                const frames = client.messages.filter(is_notification(FLOOD_NOTIFICATION_METHOD));
+                const payload = 'x'.repeat(LARGE_FITS.size);
+                for (const frame of frames) {
+                    // compared by length first: a mismatch would otherwise print a mebibyte
+                    assert.strictEqual(frame.params.payload.length, LARGE_FITS.size);
+                    assert.ok(frame.params.payload === payload, 'the payload arrived intact');
+                }
+                // nothing follows the response: the whole burst is ahead of it
+                const response_at = client.messages.findIndex(is_response_for('large_fits'));
+                const last_flood_at = client.messages.lastIndexOf(frames.at(-1));
+                assert.ok(last_flood_at < response_at, 'the burst precedes its response');
+                assert.strictEqual(client.close_code, null, 'a burst within the budget closes nothing');
+                await assert_open_and_answering(client, 'after_large_fits', 'the socket stays open');
+            }
+            finally {
+                await client.close().catch(() => { });
+            }
+        });
+        test_if(capabilities.ws, 'a burst past the budget closes the socket with WS_CLOSE_OUTBOUND_OVERFLOW and no response', async () => {
+            const fixture = await setup_test();
+            // a second connection on the same account (the keeper's session)
+            const bystander = await create_admitted_ws_transport({
+                base_url,
+                ws_path,
+                cookies: fixture.transport.cookies(),
+                origin
+            });
+            const client = await open_flooder(fixture);
+            try {
+                await client.send(create_jsonrpc_request(FLOOD_METHOD, OVERFLOWS, 'overflows'));
+                const closed = await client.wait_for_close(CLOSE_TIMEOUT_MS);
+                assert.ok(closed, 'the flooded socket did not close');
+                assert.strictEqual(client.close_code, WS_CLOSE_OUTBOUND_OVERFLOW);
+                assert.strictEqual(client.close_reason, OUTBOUND_OVERFLOW_REASON);
+                // the response of the request whose handler overflowed is not sent
+                assert.strictEqual(client.messages.some(is_response_for('overflows')), false, 'no response may follow an overflow');
+                // frames accepted before the overflow may or may not arrive; any
+                // that do are a contiguous prefix of the burst, and never all of it
+                const indices = flood_indices(client);
+                assert.ok(indices.length < OVERFLOWS.count, `${indices.length} flood frames arrived`);
+                assert.deepStrictEqual(indices, indices.map((_, i) => i), 'the flood frames that arrived are a contiguous prefix from index 0');
+                // the account's other connection kept working through it
+                await assert_open_and_answering(bystander, 'bystander', "another connection on the account is untouched by the first one's overflow");
+                // not a revocation: the daemon token still upgrades
+                const again = await open_flooder(fixture);
+                await again.close();
+            }
+            finally {
+                await Promise.all([client.close().catch(() => { }), bystander.close().catch(() => { })]);
+            }
+        });
+        test_if(capabilities.ws, 'a burst past the flood action size limit is refused, and the socket stays open', async () => {
+            const fixture = await setup_test();
+            const client = await open_flooder(fixture);
+            try {
+                await client.send(create_jsonrpc_request(FLOOD_METHOD, REFUSED, 'refused'));
+                const frame = await client.wait_for(is_response_for('refused'));
+                assert.ok(frame.error, 'expected invalid_params but the call succeeded');
+                assert.strictEqual(frame.error.code, INVALID_PARAMS);
+                assert.deepStrictEqual(flood_indices(client), [], 'a refused burst queues nothing');
+                await assert_open_and_answering(client, 'after_refused', 'the socket stays open');
+            }
+            finally {
+                await client.close().catch(() => { });
+            }
+        });
+        test_if(rpc_path !== undefined, 'over HTTP the flood action refuses with invalid_params, reason no_connection', async () => {
+            const fixture = await setup_test();
+            const res = await cross_rpc_call(fixture.fresh_transport({ origin: null }), rpc_path, FLOOD_METHOD, FITS, fixture.create_daemon_token_headers());
+            assert.strictEqual(res.ok, false, 'expected a refusal over HTTP');
+            assert.strictEqual(res.error?.code, INVALID_PARAMS);
+            assert.strictEqual(res.error?.data?.reason, REASON_NO_CONNECTION);
+        });
+        test_if(rpc_path !== undefined, 'over HTTP a flood call at each limit is refused for no connection, one past it for its params', async () => {
+            const fixture = await setup_test();
+            const transport = fixture.fresh_transport({ origin: null });
+            // the hand-factored case is only "one byte past" for this limit
+            assert.strictEqual(FLOOD_ONE_BYTE_PAST_TOTAL.count * FLOOD_ONE_BYTE_PAST_TOTAL.size, FLOOD_MAX_TOTAL_BYTES + 1);
+            for (const { name, params, within } of FLOOD_LIMIT_CASES) {
+                const res = await cross_rpc_call(transport, rpc_path, FLOOD_METHOD, params, fixture.create_daemon_token_headers());
+                assert.strictEqual(res.ok, false, `${name}: expected a refusal over HTTP`);
+                assert.strictEqual(res.error?.code, INVALID_PARAMS, name);
+                // within the limits the call gets as far as the connection check;
+                // past one it is refused before that, with no reason
+                assert.strictEqual(res.error?.data?.reason, within ? REASON_NO_CONNECTION : undefined, `${name}: ${JSON.stringify(params)}`);
+            }
+        });
+    });
+};

package/dist/testing/integration.js

@@ -4,7 +4,7 @@ import './assert_dev_env.js';
  *
  * `describe_standard_integration_tests` creates a composable test suite that
  * exercises the full middleware stack (origin, session, bearer_auth, request_context)
- * against a real PGlite database. Consumers call it with their route factory and
+ * against a real database. Consumers call it with their route factory and
  * session config — all auth route tests come for free.
  *
  * Tests use `stub_password_deps` (deterministic hashing, no Argon2 overhead).

package/dist/testing/schema_introspect.d.ts

@@ -14,10 +14,22 @@ import './assert_dev_env.js';
  *   so a label set / ordering drift (e.g. `cell_visibility`) is a gated fact,
  *   not invisible
  *
- * Designed for `pg_catalog` introspection — works against both PostgreSQL
- * and PGlite. The snapshot is fully deterministic: every collection sorts by
+ * Designed for `pg_catalog` introspection — it runs on PostgreSQL, PGlite and
+ * pglet. The snapshot is fully deterministic: every collection sorts by
  * a stable key and excludes time-varying fields like `applied_at`.
  *
+ * Index and constraint definitions are compared as the engine renders them,
+ * so both sides of a parity comparison need engines that render alike. pglet
+ * leaves an index's modifiers out of `pg_indexes.indexdef` — per-key sort
+ * direction, `NULLS` placement, operator classes, `NULLS NOT DISTINCT` — and
+ * that misleads a comparison in both directions: a pglet snapshot diffed
+ * against a PostgreSQL one reports every index that uses a modifier, with
+ * identical DDL on both sides (a false difference), and two pglet snapshots
+ * agree when the two schemas differ only in a modifier (a false agreement).
+ * So `query_schema_snapshot` throws on pglet when the snapshot holds an
+ * index, unless the caller passes `accept_pglet_index_definitions`. Take both
+ * snapshots of a parity comparison on PostgreSQL.
+ *
  * Paired with `testing/schema_parity.ts` for comparison + assertion helpers.
  *
  * @module
@@ -162,6 +174,17 @@ export interface QuerySchemaSnapshotOptions {
      * consumer's domain schema.
      */
     readonly exclude_tables?: ReadonlyArray<string>;
+    /**
+     * Take the snapshot on pglet even though it holds indexes. Default `false`:
+     * pglet's `pg_indexes.indexdef` omits index modifiers (sort direction,
+     * `NULLS` placement, operator classes, `NULLS NOT DISTINCT`), so the
+     * snapshot's index definitions cannot be compared with another engine's,
+     * and do not tell two pglet schemas apart when they differ only in a
+     * modifier. Pass `true` only where no index definition is compared —
+     * reading tables, columns, constraints, sequences or enums off the
+     * snapshot. No effect on PostgreSQL or PGlite.
+     */
+    readonly accept_pglet_index_definitions?: boolean;
 }
 /**
  * Introspect a live database into a deterministic `SchemaSnapshot`.
@@ -172,6 +195,11 @@ export interface QuerySchemaSnapshotOptions {
  * The `schema_version` migration tracker never appears in the `tables`
  * field — it's framework bookkeeping created by the migration runner,
  * identical across consumers, and would only add noise.
+ *
+ * @param db - the database to introspect
+ * @param options - schema, table excludes, and the pglet opt-in
+ * @returns the snapshot, every collection sorted
+ * @throws Error on pglet when the snapshot holds an index and `accept_pglet_index_definitions` is not set — its index definitions omit modifiers, so a comparison built on them is wrong in both directions
  */
 export declare const query_schema_snapshot: (db: Db, options?: QuerySchemaSnapshotOptions) => Promise<SchemaSnapshot>;
 //# sourceMappingURL=schema_introspect.d.ts.map

package/dist/testing/schema_introspect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema_introspect.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/schema_introspect.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;iBAWzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,qCAAqC;AACrC,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;iBAOxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,qFAAqF;AACrF,eAAO,MAAM,gBAAgB;;iBAE3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;iBAG3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;iBAOzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB;;;;iBAOhC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;;iBAE3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,GAAU,IAAI,EAAE,KAAG,OAAO,CAAC,gBAAgB,CAa9E,CAAC;AAEF,kDAAkD;AAClD,MAAM,WAAW,0BAA0B;IAC1C;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAChD;AA8DD;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,GACjC,IAAI,EAAE,EACN,UAAS,0BAA+B,KACtC,OAAO,CAAC,cAAc,CAyHxB,CAAC"}
+{"version":3,"file":"schema_introspect.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/schema_introspect.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;iBAWzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,qCAAqC;AACrC,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;iBAOxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,qFAAqF;AACrF,eAAO,MAAM,gBAAgB;;iBAE3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;iBAG3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;iBAOzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB;;;;iBAOhC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;;iBAE3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,GAAU,IAAI,EAAE,KAAG,OAAO,CAAC,gBAAgB,CAa9E,CAAC;AAEF,kDAAkD;AAClD,MAAM,WAAW,0BAA0B;IAC1C;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAChD;;;;;;;;;OASG;IACH,QAAQ,CAAC,8BAA8B,CAAC,EAAE,OAAO,CAAC;CAClD;AAiED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,GACjC,IAAI,EAAE,EACN,UAAS,0BAA+B,KACtC,OAAO,CAAC,cAAc,CA0IxB,CAAC"}

package/dist/testing/schema_introspect.js

@@ -14,10 +14,22 @@ import './assert_dev_env.js';
  *   so a label set / ordering drift (e.g. `cell_visibility`) is a gated fact,
  *   not invisible
  *
- * Designed for `pg_catalog` introspection — works against both PostgreSQL
- * and PGlite. The snapshot is fully deterministic: every collection sorts by
+ * Designed for `pg_catalog` introspection — it runs on PostgreSQL, PGlite and
+ * pglet. The snapshot is fully deterministic: every collection sorts by
  * a stable key and excludes time-varying fields like `applied_at`.
  *
+ * Index and constraint definitions are compared as the engine renders them,
+ * so both sides of a parity comparison need engines that render alike. pglet
+ * leaves an index's modifiers out of `pg_indexes.indexdef` — per-key sort
+ * direction, `NULLS` placement, operator classes, `NULLS NOT DISTINCT` — and
+ * that misleads a comparison in both directions: a pglet snapshot diffed
+ * against a PostgreSQL one reports every index that uses a modifier, with
+ * identical DDL on both sides (a false difference), and two pglet snapshots
+ * agree when the two schemas differ only in a modifier (a false agreement).
+ * So `query_schema_snapshot` throws on pglet when the snapshot holds an
+ * index, unless the caller passes `accept_pglet_index_definitions`. Take both
+ * snapshots of a parity comparison on PostgreSQL.
+ *
  * Paired with `testing/schema_parity.ts` for comparison + assertion helpers.
  *
  * @module
@@ -128,6 +140,8 @@ export const query_migration_tracker = async (db) => {
         }))
     };
 };
+/** The marker pglet's `version()` carries. */
+const PGLET_VERSION_MARKER = '(pglet)';
 const sort_keys = (record) => {
     const sorted = {};
     for (const key of Object.keys(record).sort()) {
@@ -162,6 +176,11 @@ const contype_to_kind = (contype) => {
  * The `schema_version` migration tracker never appears in the `tables`
  * field — it's framework bookkeeping created by the migration runner,
  * identical across consumers, and would only add noise.
+ *
+ * @param db - the database to introspect
+ * @param options - schema, table excludes, and the pglet opt-in
+ * @returns the snapshot, every collection sorted
+ * @throws Error on pglet when the snapshot holds an index and `accept_pglet_index_definitions` is not set — its index definitions omit modifiers, so a comparison built on them is wrong in both directions
  */
 export const query_schema_snapshot = async (db, options = {}) => {
     const schema = options.schema ?? 'public';
@@ -187,11 +206,11 @@ export const query_schema_snapshot = async (db, options = {}) => {
 		 WHERE schemaname = $1
 		 ORDER BY tablename ASC, indexname ASC`, [schema]);
     // Constraints — pg_get_constraintdef produces a canonical text rendering.
-    // Skip NOT NULL constraints (`contype = 'n'`): PG17+ catalogs them as
-    // named `pg_constraint` rows while PGlite / older PG don't, and
-    // nullability is already captured per-column by `is_nullable` — including
-    // them would report a pure engine-cataloging artifact as cross-backend
-    // drift between a PGlite and a real-Postgres backend.
+    // Skip NOT NULL constraints (`contype = 'n'`): a named `pg_constraint` row
+    // per NOT NULL column is something an engine may or may not catalog
+    // (PostgreSQL 18, PGlite 0.5 and pglet 0.1 each do), and nullability is
+    // already captured per-column by `is_nullable` — including the rows would
+    // report an engine-cataloging difference as drift between two backends.
     const constraint_rows = await db.query(`SELECT c.conrelid::regclass::text AS table_name,
 		        c.conname,
 		        c.contype::text,
@@ -252,6 +271,18 @@ export const query_schema_snapshot = async (db, options = {}) => {
     for (const row of enum_rows) {
         (enums[row.enum_name] ??= { labels: [] }).labels.push(row.label);
     }
+    if (!options.accept_pglet_index_definitions &&
+        Object.values(tables).some((table) => table.indexes.length > 0)) {
+        const [version_row] = await db.query(`SELECT version() AS version`);
+        if (version_row?.version.includes(PGLET_VERSION_MARKER)) {
+            throw new Error('query_schema_snapshot: this database is pglet, whose pg_indexes.indexdef omits index ' +
+                'modifiers (sort direction, NULLS placement, operator classes, NULLS NOT DISTINCT), so ' +
+                "the snapshot's index definitions report false differences against PostgreSQL and false " +
+                'agreement between two pglet schemas. Take the snapshot on PostgreSQL (a TS backend ' +
+                'config defaults to memory://, which is pglet), or pass ' +
+                '{accept_pglet_index_definitions: true} when no index definition is compared.');
+        }
+    }
     return {
         tables: sort_keys(tables),
         sequences: sort_keys(sequences),

package/dist/testing/transports/raw_http.d.ts

@@ -0,0 +1,78 @@
+import '../assert_dev_env.js';
+/** What a raw exchange read back, and how it ended. */
+export interface RawHttpExchange {
+    /** Every byte the server sent, `latin1`-decoded. */
+    readonly received: string;
+    /**
+     * `true` when the connection ended before the exchange stopped reading —
+     * the server closed it, or it never opened (a refused or unresolvable
+     * address reads as closed, with nothing received).
+     */
+    readonly closed_by_server: boolean;
+}
+/** Options for `raw_http_exchange`. */
+export interface RawHttpExchangeOptions {
+    /** How long to read before giving up on the server. */
+    readonly read_timeout_ms: number;
+    /**
+     * When the exchange stops reading. `'close'` reads until the server closes
+     * the connection; `'response'` stops as soon as one whole response has
+     * arrived (`raw_http_parse_response`), for a server that answers and then
+     * keeps the connection open. Either way the read timeout bounds it.
+     *
+     * `'response'` stops at the first response the bytes frame, so it is for a
+     * final response carrying `Content-Length` or chunked framing: a `1xx`
+     * interim response ends the read, and so does the head of a response
+     * delimited by the connection closing, before its body.
+     *
+     * @default 'close'
+     */
+    readonly until?: 'close' | 'response';
+}
+/** One parsed HTTP/1.1 response. */
+export interface RawHttpResponse {
+    readonly status: number;
+    /** Response headers, names lowercased; a repeated name keeps its last value. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** The response body, with any chunked framing removed. */
+    readonly body: string;
+}
+/**
+ * Open a raw TCP socket to `base_url`, write `request_bytes` once, and collect
+ * what the server sends back until it closes the connection, a whole response
+ * has arrived (`until: 'response'`), or `read_timeout_ms` elapses.
+ *
+ * Write errors are swallowed: a server that refuses a request and closes
+ * mid-upload surfaces as `EPIPE` / `ECONNRESET` on the unfinished write, and
+ * what a caller asserts on is what was read back. A write error also ends the
+ * socket, so bytes the server sent just before it can go unread — a caller
+ * that needs to read a refusal reliably sends nothing the server will leave
+ * unread.
+ *
+ * @param base_url - the server's base URL; only its host and port are used
+ * @param request_bytes - the bytes to send, `latin1`-encoded
+ */
+export declare const raw_http_exchange: (base_url: string, request_bytes: string, options: RawHttpExchangeOptions) => Promise<RawHttpExchange>;
+/**
+ * Count HTTP response status lines in a raw byte stream. Deliberately
+ * **unanchored** (no `^`/`m`): a second pipelined response is concatenated
+ * straight after the first response's body, which carries no trailing newline,
+ * so a line-anchored match would miss it — and missing a smuggled second
+ * response is a silent false negative. It counts exactly the status lines as
+ * long as no response header or body contains the literal `HTTP/1.x NNN`.
+ */
+export declare const raw_http_count_responses: (raw: string) => number;
+/** The status code of the first HTTP response in a raw byte stream, or `null` if none. */
+export declare const raw_http_first_status: (raw: string) => number | null;
+/**
+ * Parse the first response in a raw byte stream, once all of it has arrived.
+ *
+ * The body is delimited by `Transfer-Encoding: chunked` or `Content-Length`.
+ * A response carrying neither is delimited by the connection closing, which
+ * the bytes alone don't show, so its body is whatever followed the head.
+ *
+ * @param raw - the bytes read so far, `latin1`-decoded
+ * @returns the response, or `null` when the head or the framed body is incomplete
+ */
+export declare const raw_http_parse_response: (raw: string) => RawHttpResponse | null;
+//# sourceMappingURL=raw_http.d.ts.map

package/dist/testing/transports/raw_http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw_http.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/transports/raw_http.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAuB9B,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACnC;AAED,uCAAuC;AACvC,MAAM,WAAW,sBAAsB;IACtC,uDAAuD;IACvD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;CACtC;AAED,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,GAC7B,UAAU,MAAM,EAChB,eAAe,MAAM,EACrB,SAAS,sBAAsB,KAC7B,OAAO,CAAC,eAAe,CAwBvB,CAAC;AAEJ;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,GAAI,KAAK,MAAM,KAAG,MACN,CAAC;AAElD,0FAA0F;AAC1F,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAG5D,CAAC;AAyBF;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,GAAI,KAAK,MAAM,KAAG,eAAe,GAAG,IAyBvE,CAAC"}

package/dist/testing/transports/raw_http.js

@@ -0,0 +1,141 @@
+import '../assert_dev_env.js';
+/**
+ * Raw-socket HTTP/1.1 exchanges, for tests that need to control exactly which
+ * bytes reach the server.
+ *
+ * `fetch` frames a request itself and sends all of it, so some server
+ * behaviors can't be reached through it: what a server does with two requests
+ * in one write, with duplicate or malformed headers, with a request head whose
+ * body never follows, or with a chunked body that is never terminated. This
+ * writes caller-built bytes over `node:net` and hands back what the server
+ * sent, plus just enough parsing to read a status or one whole response.
+ *
+ * Everything is `latin1`-decoded, so a string's length is its byte length.
+ *
+ * Plain TCP only: an `https:` URL is not spoken to over TLS, and the host must
+ * be a name or an IPv4 address — a bracketed IPv6 literal does not connect.
+ *
+ * @module
+ */
+import { connect } from 'node:net';
+/**
+ * Open a raw TCP socket to `base_url`, write `request_bytes` once, and collect
+ * what the server sends back until it closes the connection, a whole response
+ * has arrived (`until: 'response'`), or `read_timeout_ms` elapses.
+ *
+ * Write errors are swallowed: a server that refuses a request and closes
+ * mid-upload surfaces as `EPIPE` / `ECONNRESET` on the unfinished write, and
+ * what a caller asserts on is what was read back. A write error also ends the
+ * socket, so bytes the server sent just before it can go unread — a caller
+ * that needs to read a refusal reliably sends nothing the server will leave
+ * unread.
+ *
+ * @param base_url - the server's base URL; only its host and port are used
+ * @param request_bytes - the bytes to send, `latin1`-encoded
+ */
+export const raw_http_exchange = (base_url, request_bytes, options) => new Promise((resolve) => {
+    const { read_timeout_ms, until = 'close' } = options;
+    const url = new URL(base_url);
+    const port = Number(url.port) || (url.protocol === 'https:' ? 443 : 80);
+    const socket = connect({ host: url.hostname, port });
+    let received = '';
+    let settled = false;
+    const finish = (closed_by_server) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        socket.destroy();
+        resolve({ received, closed_by_server });
+    };
+    const timer = setTimeout(() => finish(false), read_timeout_ms);
+    socket.setEncoding('latin1');
+    socket.on('connect', () => socket.write(request_bytes, 'latin1'));
+    socket.on('data', (chunk) => {
+        received += chunk;
+        if (until === 'response' && raw_http_parse_response(received))
+            finish(false);
+    });
+    socket.on('error', () => { }); // EPIPE/ECONNRESET on a mid-write close is expected
+    socket.on('close', () => finish(true));
+});
+/**
+ * Count HTTP response status lines in a raw byte stream. Deliberately
+ * **unanchored** (no `^`/`m`): a second pipelined response is concatenated
+ * straight after the first response's body, which carries no trailing newline,
+ * so a line-anchored match would miss it — and missing a smuggled second
+ * response is a silent false negative. It counts exactly the status lines as
+ * long as no response header or body contains the literal `HTTP/1.x NNN`.
+ */
+export const raw_http_count_responses = (raw) => (raw.match(/HTTP\/1\.[01] \d{3}/g) ?? []).length;
+/** The status code of the first HTTP response in a raw byte stream, or `null` if none. */
+export const raw_http_first_status = (raw) => {
+    const match = /HTTP\/1\.[01] (\d{3})/.exec(raw);
+    return match ? Number(match[1]) : null;
+};
+/**
+ * Remove chunked framing from a body.
+ *
+ * @returns the decoded body, or `null` when the terminating chunk hasn't arrived
+ */
+const decode_chunked = (raw) => {
+    let body = '';
+    let offset = 0;
+    for (;;) {
+        const line_end = raw.indexOf('\r\n', offset);
+        if (line_end === -1)
+            return null;
+        // a chunk-size line may carry `;extension`s after the hex size
+        const size = Number.parseInt(raw.slice(offset, line_end), 16);
+        if (!Number.isFinite(size))
+            return null;
+        const data_start = line_end + 2;
+        // the last chunk is followed by optional trailers and an empty line
+        if (size === 0)
+            return raw.includes('\r\n\r\n', line_end) ? body : null;
+        if (raw.length < data_start + size + 2)
+            return null;
+        body += raw.slice(data_start, data_start + size);
+        offset = data_start + size + 2;
+    }
+};
+/**
+ * Parse the first response in a raw byte stream, once all of it has arrived.
+ *
+ * The body is delimited by `Transfer-Encoding: chunked` or `Content-Length`.
+ * A response carrying neither is delimited by the connection closing, which
+ * the bytes alone don't show, so its body is whatever followed the head.
+ *
+ * @param raw - the bytes read so far, `latin1`-decoded
+ * @returns the response, or `null` when the head or the framed body is incomplete
+ */
+export const raw_http_parse_response = (raw) => {
+    const head_end = raw.indexOf('\r\n\r\n');
+    if (head_end === -1)
+        return null;
+    const [status_line, ...header_lines] = raw.slice(0, head_end).split('\r\n');
+    const status_match = /^HTTP\/1\.[01] (\d{3})/.exec(status_line);
+    if (!status_match)
+        return null;
+    const headers = {};
+    for (const line of header_lines) {
+        const colon = line.indexOf(':');
+        if (colon <= 0)
+            continue;
+        headers[line.slice(0, colon).trim().toLowerCase()] = line.slice(colon + 1).trim();
+    }
+    const status = Number(status_match[1]);
+    const rest = raw.slice(head_end + 4);
+    if (headers['transfer-encoding']?.toLowerCase().includes('chunked')) {
+        const body = decode_chunked(rest);
+        return body === null ? null : { status, headers, body };
+    }
+    const content_length = headers['content-length'];
+    if (content_length !== undefined) {
+        const length = Number(content_length);
+        if (!Number.isSafeInteger(length) || length < 0 || rest.length < length)
+            return null;
+        return { status, headers, body: rest.slice(0, length) };
+    }
+    return { status, headers, body: rest };
+};