@zukhruf/testing 0.3.4 → 0.3.6

package/README.md

@@ -1,6 +1,6 @@
 # @zukhruf/testing
 
-Disposable fixtures for integration tests on Node.js: Docker containers and database servers, SQLite and DuckDB databases, BigQuery datasets, HTTP servers and controlled streams. Each acquisition returns a handle that `await using` cleans up, also when the test fails. A supervisor removes what a killed test run left behind.
+Disposable fixtures for integration tests on Node.js: Docker containers and database servers, SQLite and DuckDB databases, BigQuery datasets, HTTP servers and controlled streams. Each acquisition returns a handle that `await using` cleans up, also when the test fails. A background server has no handle: it lives until the process exits. A supervisor removes what a killed test run left behind.
 
 The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
 
@@ -14,6 +14,7 @@ Each area has its own import path, so a test loads only the drivers it uses. The
 | `@zukhruf/testing/docker`     | `Docker`, `Container`, `ServiceContainer`, `DockerVolume`, `DockerDirectory`, `TestRun`, `skipWithoutDocker` | Docker CLI               |
 | `@zukhruf/testing/postgres`   | `Postgres`                                                                                                   | Docker CLI               |
 | `@zukhruf/testing/mysql`      | `Mysql`                                                                                                      | Docker CLI               |
+| `@zukhruf/testing/mariadb`    | `Mariadb`                                                                                                    | Docker CLI               |
 | `@zukhruf/testing/sqlserver`  | `SqlServer`, `SQL_SERVER_FULL_IMAGE`, `SQL_SERVER_EDGE_IMAGE`                                                | Docker CLI, `mssql`      |
 | `@zukhruf/testing/clickhouse` | `ClickHouse`                                                                                                 | Docker CLI               |
 | `@zukhruf/testing/sqlite`     | `Sqlite`                                                                                                     |                          |
@@ -103,7 +104,7 @@ To pass the run to another container API, spread `docker.defaults`: it holds the
 
 ## Databases
 
-`Postgres`, `Mysql` and `SqlServer` take the `docker` to run on. Each `database()` call creates a fresh database on a shared server; disposal drops it. `start()` creates a dedicated server; disposal stops it.
+`Postgres`, `Mysql`, `Mariadb` and `SqlServer` take the `docker` to run on. Each `database()` call creates a fresh database on a shared server; disposal drops it. `start()` creates a dedicated server; disposal stops it.
 
 ```ts
 import { Postgres } from '@zukhruf/testing/postgres';
@@ -116,7 +117,7 @@ test('stores a record', { skip }, async () => {
 });
 ```
 
-The handle has `connectionString`, `host`, `port`, `user`, `password`, `database`, `image` and `containerId`. `Mysql` handles also have `query(sql)`. Without an image, `SqlServer` picks Azure SQL Edge on an ARM engine and SQL Server 2022 elsewhere. `ClickHouse` takes an explicit `image` and starts a dedicated server, so a test can create server-wide users and functions.
+The handle has `connectionString`, `host`, `port`, `user`, `password`, `database`, `image` and `containerId`. `Mysql` and `Mariadb` handles also have `query(sql)`. Without an image, `Mysql` runs `mysql:lts` and `Mariadb` runs `mariadb:lts`. MariaDB 11 and later have no `mysql` client, so use `Mariadb` for a MariaDB image. A `Mariadb` connection string starts with `mariadb://`, because the `mariadb` driver accepts no other scheme. Without an image, `SqlServer` picks Azure SQL Edge on an ARM engine and SQL Server 2022 elsewhere. `ClickHouse` takes an explicit `image` and starts a dedicated server, so a test can create server-wide users and functions.
 
 `Sqlite` creates a file-backed database in a temporary directory, with a native `DatabaseSync` connection. Disposal closes the connection and removes the directory, including WAL files. `writeLock(path, durationMs)` holds a write lock from another process, which releases it after `durationMs`, even while the caller blocks in a synchronous write.
 
@@ -128,6 +129,20 @@ The handle has `connectionString`, `host`, `port`, `user`, `password`, `database
 
 `new HttpServer().start(handler)` listens on `127.0.0.1` on a free port and resolves once it listens. The handle has `origin` and the native `server`. Disposal closes active connections and waits for the server to close.
 
+Some modules read an origin when they load, so every test in the file uses the same server. `background(handler)` starts a background server for them. It listens until the process exits and never keeps the process running, also while a connection to it is open. It returns only `origin`, because nothing disposes it. Use `start` when only one test reads the origin.
+
+```ts
+import { HttpServer } from '@zukhruf/testing/http';
+
+const keys = await new HttpServer().background((request, response) => {
+  response.end(JSON.stringify(jwks));
+});
+process.env.KEYS_URL = keys.origin;
+const { verify } = await import('./verify.ts');
+```
+
+The handler is a Node.js request listener. A web framework gives one for its fetch handler: `getRequestListener((request) => app.fetch(request))` from `@hono/node-server`, or `toNodeHandler((request) => auth.handler(request))` from `better-auth/node`. The handler can be async. When it rejects, the rejection stays unhandled and fails the process, as a throw does. The server never answers for a handler that failed. A handler that needs the origin can read a `const` that the test declares after the acquisition: no request arrives before the test gives the origin to a client.
+
 `StreamHarness` gives a controlled producer, `source<T>()`, with `enqueue`, `close`, `error` and a read-only `state`, and a disposable `reader(stream)` that locks a stream without reading ahead. `collectUntilError()` returns the remaining chunks and either `completed` or `errored` with the error.
 
 ## Waiting

package/dist/databases/mariadb.d.ts

@@ -0,0 +1,16 @@
+import type { DatabaseOptions } from './database.ts';
+import { type MysqlFamilyDatabase, MysqlFamilyServer } from './mysql-family-server.ts';
+export type { Database, DatabaseOptions } from './database.ts';
+export type MariadbOptions = DatabaseOptions;
+export type MariadbDatabase = MysqlFamilyDatabase;
+export declare class Mariadb extends MysqlFamilyServer {
+    /** MariaDB 11 and later ship only the mariadb client, not mysql. */
+    protected readonly client = "mariadb";
+    protected readonly scheme = "mariadb";
+    constructor({ image, ...options }: MariadbOptions);
+    protected environment(password: string, database: string): {
+        MARIADB_ROOT_PASSWORD: string;
+        MARIADB_DATABASE: string;
+    };
+}
+//# sourceMappingURL=mariadb.d.ts.map

package/dist/databases/mariadb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb.d.ts","sourceRoot":"","sources":["../../src/databases/mariadb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EACL,KAAK,mBAAmB,EACxB,iBAAiB,EAClB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAE/D,MAAM,MAAM,cAAc,GAAG,eAAe,CAAC;AAE7C,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAElD,qBAAa,OAAQ,SAAQ,iBAAiB;IAC5C,oEAAoE;IACpE,mBAA4B,MAAM,aAAa;IAC/C,mBAA4B,MAAM,aAAa;gBAEnC,EAAE,KAAqB,EAAE,GAAG,OAAO,EAAE,EAAE,cAAc;cAI9C,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;;;;CAGlE"}

package/dist/databases/mariadb.js

@@ -0,0 +1,13 @@
+import { MysqlFamilyServer, } from "./mysql-family-server.js";
+export class Mariadb extends MysqlFamilyServer {
+    /** MariaDB 11 and later ship only the mariadb client, not mysql. */
+    client = 'mariadb';
+    scheme = 'mariadb';
+    constructor({ image = 'mariadb:lts', ...options }) {
+        super({ ...options, image });
+    }
+    environment(password, database) {
+        return { MARIADB_ROOT_PASSWORD: password, MARIADB_DATABASE: database };
+    }
+}
+//# sourceMappingURL=mariadb.js.map

package/dist/databases/mariadb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb.js","sourceRoot":"","sources":["../../src/databases/mariadb.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAQlC,MAAM,OAAO,OAAQ,SAAQ,iBAAiB;IAC5C,oEAAoE;IACxC,MAAM,GAAG,SAAS,CAAC;IACnB,MAAM,GAAG,SAAS,CAAC;IAE/C,YAAY,EAAE,KAAK,GAAG,aAAa,EAAE,GAAG,OAAO,EAAkB;QAC/D,KAAK,CAAC,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/B,CAAC;IAEkB,WAAW,CAAC,QAAgB,EAAE,QAAgB;QAC/D,OAAO,EAAE,qBAAqB,EAAE,QAAQ,EAAE,gBAAgB,EAAE,QAAQ,EAAE,CAAC;IACzE,CAAC;CACF"}

package/dist/http/http-server.d.ts

@@ -1,12 +1,23 @@
-import { type RequestListener, type Server } from 'node:http';
+import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+/**
+ * Answers one request. It may be async: a rejection stays unhandled and fails
+ * the process, as a throw in a synchronous handler does.
+ */
+export type HttpHandler = (request: IncomingMessage, response: ServerResponse) => unknown;
 export interface HttpServerHandle extends AsyncDisposable {
     origin: string;
     server: Server;
     /** Stop accepting requests and close active HTTP connections. */
     cleanup: () => Promise<void>;
 }
+/** A server whose scope is the process: nothing disposes it. */
+export interface BackgroundHttpServer {
+    origin: string;
+}
 /** Each acquisition owns a loopback HTTP server on an available port. */
 export declare class HttpServer {
-    start(handler: RequestListener): Promise<HttpServerHandle>;
+    start(handler: HttpHandler): Promise<HttpServerHandle>;
+    /** Serves until the process exits and never keeps it running, even while a connection is open. */
+    background(handler: HttpHandler): Promise<BackgroundHttpServer>;
 }
 //# sourceMappingURL=http-server.d.ts.map

package/dist/http/http-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../../src/http/http-server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,MAAM,EAAgB,MAAM,WAAW,CAAC;AAE5E,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,yEAAyE;AACzE,qBAAa,UAAU;IACf,KAAK,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAwBjE"}
+{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../../src/http/http-server.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,MAAM,EACX,KAAK,cAAc,EAEpB,MAAM,WAAW,CAAC;AAEnB;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC;AAEb,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,gEAAgE;AAChE,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,yEAAyE;AACzE,qBAAa,UAAU;IACf,KAAK,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAsB5D,kGAAkG;IAC5F,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAOtE"}

package/dist/http/http-server.js

@@ -1,29 +1,49 @@
 import assert from 'node:assert/strict';
 import { once } from 'node:events';
-import { createServer } from 'node:http';
+import { createServer, } from 'node:http';
 /** Each acquisition owns a loopback HTTP server on an available port. */
 export class HttpServer {
     async start(handler) {
         await using resources = new AsyncDisposableStack();
-        const server = createServer(handler);
-        const listening = once(server, 'listening');
-        server.listen(0, '127.0.0.1');
-        await listening;
+        const server = serve(handler);
+        await listen(server);
         resources.defer(async () => {
             const closed = server[Symbol.asyncDispose]();
             server.closeAllConnections();
             await closed;
         });
-        const address = server.address();
-        assert(address && typeof address === 'object');
+        const origin = originOf(server);
         const owned = resources.move();
         const cleanup = () => owned.disposeAsync();
         return {
-            origin: `http://127.0.0.1:${address.port}`,
+            origin,
             server,
             cleanup,
             [Symbol.asyncDispose]: cleanup,
         };
     }
+    /** Serves until the process exits and never keeps it running, even while a connection is open. */
+    async background(handler) {
+        const server = serve(handler);
+        server.on('connection', (socket) => socket.unref());
+        await listen(server);
+        server.unref();
+        return { origin: originOf(server) };
+    }
+}
+function serve(handler) {
+    return createServer((request, response) => {
+        void handler(request, response);
+    });
+}
+async function listen(server) {
+    const listening = once(server, 'listening');
+    server.listen(0, '127.0.0.1');
+    await listening;
+}
+function originOf(server) {
+    const address = server.address();
+    assert(address && typeof address === 'object');
+    return `http://127.0.0.1:${address.port}`;
 }
 //# sourceMappingURL=http-server.js.map

package/dist/http/http-server.js.map

@@ -1 +1 @@
-{"version":3,"file":"http-server.js","sourceRoot":"","sources":["../../src/http/http-server.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACnC,OAAO,EAAqC,YAAY,EAAE,MAAM,WAAW,CAAC;AAS5E,yEAAyE;AACzE,MAAM,OAAO,UAAU;IACrB,KAAK,CAAC,KAAK,CAAC,OAAwB;QAClC,YAAY,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;QACnD,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;QACrC,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QAC5C,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;QAC9B,MAAM,SAAS,CAAC;QAEhB,SAAS,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE;YACzB,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC;YAC7C,MAAM,CAAC,mBAAmB,EAAE,CAAC;YAC7B,MAAM,MAAM,CAAC;QACf,CAAC,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;QACjC,MAAM,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC;QAE3C,OAAO;YACL,MAAM,EAAE,oBAAoB,OAAO,CAAC,IAAI,EAAE;YAC1C,MAAM;YACN,OAAO;YACP,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,OAAO;SAC/B,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"http-server.js","sourceRoot":"","sources":["../../src/http/http-server.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACnC,OAAO,EAIL,YAAY,GACb,MAAM,WAAW,CAAC;AAuBnB,yEAAyE;AACzE,MAAM,OAAO,UAAU;IACrB,KAAK,CAAC,KAAK,CAAC,OAAoB;QAC9B,YAAY,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;QACnD,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;QAC9B,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;QAErB,SAAS,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE;YACzB,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC;YAC7C,MAAM,CAAC,mBAAmB,EAAE,CAAC;YAC7B,MAAM,MAAM,CAAC;QACf,CAAC,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;QAChC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC;QAE3C,OAAO;YACL,MAAM;YACN,MAAM;YACN,OAAO;YACP,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,OAAO;SAC/B,CAAC;IACJ,CAAC;IAED,kGAAkG;IAClG,KAAK,CAAC,UAAU,CAAC,OAAoB;QACnC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;QAC9B,MAAM,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;QACpD,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;QACrB,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;IACtC,CAAC;CACF;AAED,SAAS,KAAK,CAAC,OAAoB;IACjC,OAAO,YAAY,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE;QACxC,KAAK,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,MAAM,CAAC,MAAc;IAClC,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC5C,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IAC9B,MAAM,SAAS,CAAC;AAClB,CAAC;AAED,SAAS,QAAQ,CAAC,MAAc;IAC9B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;IACjC,MAAM,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC;IAC/C,OAAO,oBAAoB,OAAO,CAAC,IAAI,EAAE,CAAC;AAC5C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zukhruf/testing",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Disposable fixtures for integration tests: Docker containers and database servers, SQLite and DuckDB databases, HTTP servers and streams. A supervisor removes what a killed test run left behind.",
   "license": "MIT",
   "repository": {
@@ -19,6 +19,7 @@
     "docker",
     "postgres",
     "mysql",
+    "mariadb",
     "sql-server",
     "disposable"
   ],
@@ -48,6 +49,11 @@
       "import": "./dist/databases/mysql.js",
       "default": "./dist/databases/mysql.js"
     },
+    "./mariadb": {
+      "types": "./dist/databases/mariadb.d.ts",
+      "import": "./dist/databases/mariadb.js",
+      "default": "./dist/databases/mariadb.js"
+    },
     "./sqlserver": {
       "types": "./dist/databases/sqlserver.d.ts",
       "import": "./dist/databases/sqlserver.js",
@@ -98,7 +104,9 @@
     "@google-cloud/bigquery": "^8.3.1",
     "@types/mssql": "^12.3.0",
     "@types/pg": "^8.23.1",
+    "mariadb": "^3.5.4",
     "mssql": "^12.7.4",
+    "mysql2": "^3.24.5",
     "pg": "^8.23.1"
   },
   "dependencies": {