embedded-postgres-node 0.0.0-stage → 0.1.0-alpha.2

package/dist/cjs/lifecycle.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startPostgres = startPostgres;
+exports.withPostgres = withPostgres;
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const binary_js_1 = require("./binary.js");
+const errors_js_1 = require("./errors.js");
+const options_js_1 = require("./options.js");
+const protocol_js_1 = require("./protocol.js");
+/** Start a database whose lifetime is owned by the caller (or its AbortSignal). */
+async function startPostgres(options = {}) {
+    const prepared = (0, options_js_1.prepareOptions)(options);
+    const deadline = new AbortController();
+    const lifetime = AbortSignal.any([deadline.signal, ...(options.signal ? [options.signal] : [])]);
+    const startupTimer = setTimeout(() => deadline.abort(), prepared.startupDeadlineMs);
+    let executable;
+    try {
+        executable = await (0, binary_js_1.resolveCli)(options.cli, lifetime);
+        if (lifetime.aborted)
+            throw new errors_js_1.PostgresError('ABORTED', 'PostgreSQL startup aborted');
+    }
+    catch (error) {
+        clearTimeout(startupTimer);
+        if (deadline.signal.aborted)
+            throw new errors_js_1.PostgresError('TIMEOUT', 'PostgreSQL startup deadline exceeded during CLI resolution');
+        throw error;
+    }
+    return new Promise((resolve, reject) => {
+        const child = (0, node_child_process_1.spawn)(executable, prepared.args, {
+            stdio: ['pipe', 'pipe', 'pipe'], env: prepared.env, windowsHide: true, shell: false,
+            // Escape Node's Windows kill-on-parent-exit job so the CLI can observe
+            // stdin EOF and clean up. Keep the child referenced and its pipes owned.
+            detached: process.platform === 'win32',
+        });
+        let ready = false;
+        let stopped = false;
+        let stopping = false;
+        let finished = false;
+        let stderr = '';
+        let discardStderrLine = false;
+        let failure;
+        let brokenProtocol = false;
+        let shutdownTimer;
+        let reapTimer;
+        const secrets = [prepared.password];
+        let resolveClosed;
+        const closed = new Promise(resolve => { resolveClosed = resolve; });
+        let stopPromise;
+        const finish = (exitCode, signal) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(startupTimer);
+            clearTimeout(shutdownTimer);
+            clearTimeout(reapTimer);
+            lifetime.removeEventListener('abort', abort);
+            if (!failure && (!ready || !stopped || exitCode !== 0)) {
+                failure = new errors_js_1.PostgresError('EXIT', `CLI exited ${ready ? 'after' : 'before'} readiness without clean shutdown (code ${exitCode}, signal ${signal})`);
+            }
+            const error = failure ? new errors_js_1.PostgresError(failure.code, (0, errors_js_1.redact)(failure.message, secrets), (0, errors_js_1.redact)(stderr, secrets)) : undefined;
+            const result = Object.freeze({ exitCode, signal, stopped, ...(error ? { error } : {}) });
+            resolveClosed(result);
+            if (!ready)
+                reject(error ?? new errors_js_1.PostgresError('EXIT', 'CLI exited before readiness'));
+        };
+        const requestStop = () => {
+            if (stopping || finished)
+                return;
+            stopping = true;
+            clearTimeout(startupTimer);
+            child.stdin.end();
+            shutdownTimer = setTimeout(() => {
+                failure = new errors_js_1.PostgresError('SHUTDOWN', `${failure ? failure.message + '; ' : ''}CLI shutdown deadline exceeded; forced owner termination, PostgreSQL cleanup cannot be confirmed`);
+                child.kill('SIGKILL');
+                // A descendant holding stdio open must not make teardown wait forever.
+                reapTimer = setTimeout(() => {
+                    child.stdin.destroy();
+                    child.stdout.destroy();
+                    child.stderr.destroy();
+                    child.unref();
+                    finish(child.exitCode, child.signalCode);
+                }, 2_000);
+            }, prepared.shutdownDeadlineMs);
+        };
+        const fail = (error) => { failure ??= error; requestStop(); };
+        const abort = () => fail(new errors_js_1.PostgresError(deadline.signal.aborted ? 'TIMEOUT' : 'ABORTED', deadline.signal.aborted ? 'PostgreSQL startup deadline exceeded' : 'PostgreSQL lifetime aborted'));
+        const stop = () => {
+            requestStop();
+            stopPromise ??= closed.then(result => { if (result.error)
+                throw result.error; });
+            return stopPromise;
+        };
+        const parser = new protocol_js_1.ProtocolParser(event => {
+            if (event.event === 'error') {
+                fail(new errors_js_1.PostgresError(ready ? 'EXIT' : 'STARTUP', event.error));
+            }
+            else if (event.event === 'stopped') {
+                if (stopped || !ready) {
+                    fail(new errors_js_1.PostgresError('PROTOCOL', 'Unexpected CLI stopped event'));
+                    return;
+                }
+                stopped = true;
+                if (!stopping)
+                    fail(new errors_js_1.PostgresError('EXIT', 'CLI stopped unexpectedly'));
+            }
+            else {
+                if (ready || stopped) {
+                    fail(new errors_js_1.PostgresError('PROTOCOL', 'Duplicate or out-of-order CLI ready event'));
+                    return;
+                }
+                secrets.push(event.connection_url, new URL(event.connection_url).password);
+                if (stopping)
+                    return;
+                ready = true;
+                clearTimeout(startupTimer);
+                const instance = {
+                    get connectionUrl() { return event.connection_url; },
+                    port: event.port, closed, stop,
+                    [Symbol.asyncDispose]: stop,
+                };
+                // Common inspection/serialization should not accidentally print credentials.
+                Object.defineProperties(instance, {
+                    connectionUrl: { enumerable: false },
+                    toJSON: { value: () => ({ port: event.port }) },
+                    [node_util_1.inspect.custom]: { value: () => `PostgresInstance { port: ${event.port} }` },
+                });
+                resolve(Object.freeze(instance));
+            }
+        });
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            if (brokenProtocol)
+                return;
+            try {
+                parser.push(chunk);
+            }
+            catch (error) {
+                brokenProtocol = true;
+                fail(error);
+            }
+        });
+        child.stdout.on('end', () => {
+            if (brokenProtocol)
+                return;
+            try {
+                parser.finish();
+            }
+            catch (error) {
+                brokenProtocol = true;
+                fail(error);
+            }
+            // Protocol EOF while the owner lives must also release our lifetime pipe.
+            if (!stopped)
+                requestStop();
+        });
+        child.stderr.on('data', (chunk) => {
+            if (discardStderrLine) {
+                const newline = chunk.indexOf('\n');
+                if (newline === -1)
+                    return;
+                chunk = chunk.slice(newline + 1);
+                discardStderrLine = false;
+            }
+            stderr += chunk;
+            if (stderr.length > 64 * 1024) {
+                stderr = stderr.slice(-64 * 1024);
+                // Discard a truncated line entirely, including its future chunks.
+                const newline = stderr.indexOf('\n');
+                discardStderrLine = newline === -1;
+                stderr = discardStderrLine ? '' : stderr.slice(newline + 1);
+            }
+        });
+        child.stdout.on('error', () => fail(new errors_js_1.PostgresError('PROTOCOL', 'Unable to read CLI protocol pipe')));
+        child.stderr.on('error', () => fail(new errors_js_1.PostgresError('EXIT', 'Unable to read CLI diagnostic pipe')));
+        child.stdin.on('error', () => fail(new errors_js_1.PostgresError('EXIT', 'CLI stdin pipe closed unexpectedly')));
+        child.on('error', () => fail(new errors_js_1.PostgresError('SPAWN', 'Unable to spawn CLI executable')));
+        child.on('close', finish);
+        lifetime.addEventListener('abort', abort, { once: true });
+        if (lifetime.aborted)
+            abort();
+    });
+}
+/** User-owned migrations/pools belong inside fn; close pools before fn returns. */
+async function withPostgres(options, fn) {
+    const postgres = await startPostgres(options);
+    let failed = false;
+    let callbackError;
+    try {
+        return await fn(postgres);
+    }
+    catch (error) {
+        failed = true;
+        callbackError = error;
+        throw error;
+    }
+    finally {
+        try {
+            await postgres.stop();
+        }
+        catch (cleanupError) {
+            if (failed)
+                throw new AggregateError([callbackError, cleanupError], 'PostgreSQL callback and cleanup both failed');
+            throw cleanupError;
+        }
+    }
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/cjs/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../.local/build/src/lifecycle.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from 'node:child_process';\nimport { inspect } from 'node:util';\nimport { resolveCli } from './binary.js';\nimport { PostgresError, redact } from './errors.js';\nimport { prepareOptions } from './options.js';\nimport type { PostgresOptions } from './options.js';\nimport { ProtocolParser } from './protocol.js';\n\nexport interface ExitResult {\n  readonly exitCode: number | null;\n  readonly signal: NodeJS.Signals | null;\n  readonly stopped: boolean;\n  readonly error?: PostgresError;\n}\n\nexport interface PostgresInstance extends AsyncDisposable {\n  /** A credential: do not log or snapshot it. */\n  readonly connectionUrl: string;\n  readonly port: number;\n  /** Resolves on termination; never rejects, so ignoring it cannot cause an unhandled rejection. */\n  readonly closed: Promise<ExitResult>;\n  /** Closes stdin and waits for stopped and process exit. Repeated calls share one result. */\n  stop(): Promise<void>;\n}\n\n/** Start a database whose lifetime is owned by the caller (or its AbortSignal). */\nexport async function startPostgres(options: PostgresOptions = {}): Promise<PostgresInstance> {\n  const prepared = prepareOptions(options);\n  const deadline = new AbortController();\n  const lifetime = AbortSignal.any([deadline.signal, ...(options.signal ? [options.signal] : [])]);\n  const startupTimer = setTimeout(() => deadline.abort(), prepared.startupDeadlineMs);\n  let executable: string;\n  try {\n    executable = await resolveCli(options.cli, lifetime);\n    if (lifetime.aborted) throw new PostgresError('ABORTED', 'PostgreSQL startup aborted');\n  } catch (error) {\n    clearTimeout(startupTimer);\n    if (deadline.signal.aborted) throw new PostgresError('TIMEOUT', 'PostgreSQL startup deadline exceeded during CLI resolution');\n    throw error;\n  }\n\n  return new Promise<PostgresInstance>((resolve, reject) => {\n    const child = spawn(executable, prepared.args, {\n      stdio: ['pipe', 'pipe', 'pipe'], env: prepared.env, windowsHide: true, shell: false,\n      // Escape Node's Windows kill-on-parent-exit job so the CLI can observe\n      // stdin EOF and clean up. Keep the child referenced and its pipes owned.\n      detached: process.platform === 'win32',\n    });\n    let ready = false;\n    let stopped = false;\n    let stopping = false;\n    let finished = false;\n    let stderr = '';\n    let discardStderrLine = false;\n    let failure: PostgresError | undefined;\n    let brokenProtocol = false;\n    let shutdownTimer: NodeJS.Timeout | undefined;\n    let reapTimer: NodeJS.Timeout | undefined;\n    const secrets = [prepared.password];\n    let resolveClosed!: (result: ExitResult) => void;\n    const closed = new Promise<ExitResult>(resolve => { resolveClosed = resolve; });\n    let stopPromise: Promise<void> | undefined;\n\n    const finish = (exitCode: number | null, signal: NodeJS.Signals | null) => {\n      if (finished) return;\n      finished = true;\n      clearTimeout(startupTimer);\n      clearTimeout(shutdownTimer);\n      clearTimeout(reapTimer);\n      lifetime.removeEventListener('abort', abort);\n      if (!failure && (!ready || !stopped || exitCode !== 0)) {\n        failure = new PostgresError('EXIT', `CLI exited ${ready ? 'after' : 'before'} readiness without clean shutdown (code ${exitCode}, signal ${signal})`);\n      }\n      const error = failure ? new PostgresError(failure.code, redact(failure.message, secrets), redact(stderr, secrets)) : undefined;\n      const result: ExitResult = Object.freeze({ exitCode, signal, stopped, ...(error ? { error } : {}) });\n      resolveClosed(result);\n      if (!ready) reject(error ?? new PostgresError('EXIT', 'CLI exited before readiness'));\n    };\n    const requestStop = () => {\n      if (stopping || finished) return;\n      stopping = true;\n      clearTimeout(startupTimer);\n      child.stdin.end();\n      shutdownTimer = setTimeout(() => {\n        failure = new PostgresError('SHUTDOWN', `${failure ? failure.message + '; ' : ''}CLI shutdown deadline exceeded; forced owner termination, PostgreSQL cleanup cannot be confirmed`);\n        child.kill('SIGKILL');\n        // A descendant holding stdio open must not make teardown wait forever.\n        reapTimer = setTimeout(() => {\n          child.stdin.destroy();\n          child.stdout.destroy();\n          child.stderr.destroy();\n          child.unref();\n          finish(child.exitCode, child.signalCode);\n        }, 2_000);\n      }, prepared.shutdownDeadlineMs);\n    };\n    const fail = (error: PostgresError) => { failure ??= error; requestStop(); };\n    const abort = () => fail(new PostgresError(deadline.signal.aborted ? 'TIMEOUT' : 'ABORTED', deadline.signal.aborted ? 'PostgreSQL startup deadline exceeded' : 'PostgreSQL lifetime aborted'));\n    const stop = () => {\n      requestStop();\n      stopPromise ??= closed.then(result => { if (result.error) throw result.error; });\n      return stopPromise;\n    };\n    const parser = new ProtocolParser(event => {\n      if (event.event === 'error') {\n        fail(new PostgresError(ready ? 'EXIT' : 'STARTUP', event.error));\n      } else if (event.event === 'stopped') {\n        if (stopped || !ready) { fail(new PostgresError('PROTOCOL', 'Unexpected CLI stopped event')); return; }\n        stopped = true;\n        if (!stopping) fail(new PostgresError('EXIT', 'CLI stopped unexpectedly'));\n      } else {\n        if (ready || stopped) { fail(new PostgresError('PROTOCOL', 'Duplicate or out-of-order CLI ready event')); return; }\n        secrets.push(event.connection_url, new URL(event.connection_url).password);\n        if (stopping) return;\n        ready = true;\n        clearTimeout(startupTimer);\n        const instance: PostgresInstance = {\n          get connectionUrl() { return event.connection_url; },\n          port: event.port, closed, stop,\n          [Symbol.asyncDispose]: stop,\n        };\n        // Common inspection/serialization should not accidentally print credentials.\n        Object.defineProperties(instance, {\n          connectionUrl: { enumerable: false },\n          toJSON: { value: () => ({ port: event.port }) },\n          [inspect.custom]: { value: () => `PostgresInstance { port: ${event.port} }` },\n        });\n        resolve(Object.freeze(instance));\n      }\n    });\n    child.stdout.setEncoding('utf8');\n    child.stderr.setEncoding('utf8');\n    child.stdout.on('data', (chunk: string) => {\n      if (brokenProtocol) return;\n      try { parser.push(chunk); } catch (error) { brokenProtocol = true; fail(error as PostgresError); }\n    });\n    child.stdout.on('end', () => {\n      if (brokenProtocol) return;\n      try { parser.finish(); } catch (error) { brokenProtocol = true; fail(error as PostgresError); }\n      // Protocol EOF while the owner lives must also release our lifetime pipe.\n      if (!stopped) requestStop();\n    });\n    child.stderr.on('data', (chunk: string) => {\n      if (discardStderrLine) {\n        const newline = chunk.indexOf('\\n');\n        if (newline === -1) return;\n        chunk = chunk.slice(newline + 1);\n        discardStderrLine = false;\n      }\n      stderr += chunk;\n      if (stderr.length > 64 * 1024) {\n        stderr = stderr.slice(-64 * 1024);\n        // Discard a truncated line entirely, including its future chunks.\n        const newline = stderr.indexOf('\\n');\n        discardStderrLine = newline === -1;\n        stderr = discardStderrLine ? '' : stderr.slice(newline + 1);\n      }\n    });\n    child.stdout.on('error', () => fail(new PostgresError('PROTOCOL', 'Unable to read CLI protocol pipe')));\n    child.stderr.on('error', () => fail(new PostgresError('EXIT', 'Unable to read CLI diagnostic pipe')));\n    child.stdin.on('error', () => fail(new PostgresError('EXIT', 'CLI stdin pipe closed unexpectedly')));\n    child.on('error', () => fail(new PostgresError('SPAWN', 'Unable to spawn CLI executable')));\n    child.on('close', finish);\n    lifetime.addEventListener('abort', abort, { once: true });\n    if (lifetime.aborted) abort();\n  });\n}\n\n/** User-owned migrations/pools belong inside fn; close pools before fn returns. */\nexport async function withPostgres<T>(options: PostgresOptions, fn: (postgres: PostgresInstance) => Promise<T>): Promise<T> {\n  const postgres = await startPostgres(options);\n  let failed = false;\n  let callbackError: unknown;\n  try { return await fn(postgres); } catch (error) { failed = true; callbackError = error; throw error; }\n  finally {\n    try { await postgres.stop(); } catch (cleanupError) {\n      if (failed) throw new AggregateError([callbackError, cleanupError], 'PostgreSQL callback and cleanup both failed');\n      throw cleanupError;\n    }\n  }\n}\n"]}

package/dist/cjs/options.d.ts

@@ -0,0 +1,46 @@
+import type { CliSource } from './binary.js';
+export interface PostgresOptions {
+    /** Explicit executable/release; otherwise EMBEDDED_POSTGRES_CLI or the package's pinned release. */
+    cli?: CliSource;
+    postgresVersion?: string;
+    database?: string;
+    username?: string;
+    password?: string;
+    /** Zero (the default) lets PostgreSQL select an available port. */
+    port?: number;
+    cacheDir?: string;
+    binaries?: string;
+    storage?: {
+        type: 'disposable';
+        workDir?: string;
+    } | {
+        type: 'persistent';
+        dataDir: string;
+        workDir?: string;
+    };
+    runAs?: {
+        uid: number;
+        gid: number;
+    };
+    parameters?: Readonly<Record<string, string>>;
+    startTimeoutMs?: number;
+    stopTimeoutMs?: number;
+    /** Outer startup deadline, including executable resolution. Defaults to startTimeoutMs + 30s. */
+    startupDeadlineMs?: number;
+    /** Must exceed stopTimeoutMs + 2s. Defaults to stopTimeoutMs + 5s. */
+    shutdownDeadlineMs?: number;
+    /** Lifetime cancellation: abort before or after readiness requests cleanup. */
+    signal?: AbortSignal;
+    /** Additional child environment. EP_* keys are reserved. */
+    env?: Readonly<Record<string, string>>;
+    /** CLI flag names without --. Core, credential, config and lifecycle flags are reserved. */
+    cliOptions?: Readonly<Record<string, string | number | boolean | readonly string[]>>;
+}
+export interface PreparedOptions {
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    password: string;
+    startupDeadlineMs: number;
+    shutdownDeadlineMs: number;
+}
+export declare function prepareOptions(options: PostgresOptions): PreparedOptions;

package/dist/cjs/options.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareOptions = prepareOptions;
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+const errors_js_1 = require("./errors.js");
+const reserved = new Set(['json', 'parent-stdin', 'config', 'state-file', 'password', 'port', 'database', 'username', 'start-timeout', 'stop-timeout', 'data-dir', 'work-dir', 'cache-dir', 'binaries', 'postgres-version', 'user', 'set', 'help']);
+function prepareOptions(options) {
+    const start = (0, errors_js_1.positiveTimeout)(options.startTimeoutMs ?? 120_000, 'startTimeoutMs');
+    const stop = (0, errors_js_1.positiveTimeout)(options.stopTimeoutMs ?? 10_000, 'stopTimeoutMs');
+    if (stop > 60_000)
+        throw new errors_js_1.PostgresError('CONFIG', 'stopTimeoutMs must not exceed the CLI maximum of 60000');
+    const startupDeadlineMs = (0, errors_js_1.positiveTimeout)(options.startupDeadlineMs ?? start + 30_000, 'startupDeadlineMs');
+    const shutdownDeadlineMs = (0, errors_js_1.positiveTimeout)(options.shutdownDeadlineMs ?? stop + 5_000, 'shutdownDeadlineMs');
+    if (shutdownDeadlineMs <= stop + 2_000)
+        throw new errors_js_1.PostgresError('CONFIG', 'shutdownDeadlineMs must exceed stopTimeoutMs + 2000');
+    const port = options.port ?? 0;
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        throw new errors_js_1.PostgresError('CONFIG', 'port must be an integer between 0 and 65535');
+    if (options.storage?.type === 'persistent' && (!options.storage.dataDir || !options.password || !options.username || !options.database)) {
+        throw new errors_js_1.PostgresError('CONFIG', 'Persistent storage requires dataDir and explicit database, username and password');
+    }
+    if (options.password === '')
+        throw new errors_js_1.PostgresError('CONFIG', 'password must not be empty');
+    const password = options.password ?? (0, node_crypto_1.randomBytes)(24).toString('base64url');
+    const args = ['run', '--json', '--parent-stdin', `--port=${port}`, `--start-timeout=${start}ms`, `--stop-timeout=${stop}ms`];
+    const add = (name, value) => {
+        if (value !== undefined) {
+            if (value.includes('\0'))
+                throw new errors_js_1.PostgresError('CONFIG', 'CLI options cannot contain NUL characters');
+            args.push(`--${name}=${value}`);
+        }
+    };
+    add('database', options.database);
+    add('username', options.username);
+    add('postgres-version', options.postgresVersion);
+    add('cache-dir', options.cacheDir === undefined ? undefined : (0, node_path_1.resolve)(options.cacheDir));
+    add('binaries', options.binaries === undefined ? undefined : (0, node_path_1.resolve)(options.binaries));
+    add('work-dir', options.storage?.workDir === undefined ? undefined : (0, node_path_1.resolve)(options.storage.workDir));
+    if (options.storage?.type === 'persistent')
+        add('data-dir', (0, node_path_1.resolve)(options.storage.dataDir));
+    if (options.runAs) {
+        for (const id of [options.runAs.uid, options.runAs.gid]) {
+            if (!Number.isInteger(id) || id < 0 || id >= 4_294_967_295)
+                throw new errors_js_1.PostgresError('CONFIG', 'runAs IDs must be unsigned integers below 4294967295');
+        }
+        if (options.runAs.uid === 0)
+            throw new errors_js_1.PostgresError('CONFIG', 'runAs.uid must be nonzero');
+        add('user', `${options.runAs.uid}:${options.runAs.gid}`);
+    }
+    for (const [name, value] of Object.entries(options.parameters ?? {})) {
+        if (!/^[a-zA-Z_][a-zA-Z0-9_.]*$/.test(name))
+            throw new errors_js_1.PostgresError('CONFIG', 'Invalid PostgreSQL parameter name');
+        add('set', `${name}=${value}`);
+    }
+    for (const [name, value] of Object.entries(options.cliOptions ?? {})) {
+        if (!/^[a-z][a-z0-9-]*$/.test(name) || reserved.has(name))
+            throw new errors_js_1.PostgresError('CONFIG', 'Invalid or reserved advanced CLI option');
+        for (const item of Array.isArray(value) ? value : [value])
+            add(name, String(item));
+    }
+    const env = {};
+    for (const [name, value] of Object.entries(process.env)) {
+        // Do not allow ambient CLI configuration to turn disposable tests persistent.
+        if (!name.toUpperCase().startsWith('EP_'))
+            env[name] = value;
+    }
+    for (const [name, value] of Object.entries(options.env ?? {})) {
+        if (name.toUpperCase().startsWith('EP_') || name.includes('=') || name.includes('\0') || value.includes('\0')) {
+            throw new errors_js_1.PostgresError('CONFIG', 'Invalid or reserved child environment variable');
+        }
+        env[name] = value;
+    }
+    if (password.includes('\0'))
+        throw new errors_js_1.PostgresError('CONFIG', 'password cannot contain NUL characters');
+    env.EP_PASSWORD = password;
+    return { args, env, password, startupDeadlineMs, shutdownDeadlineMs };
+}
+//# sourceMappingURL=options.js.map

package/dist/cjs/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../.local/build/src/options.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomBytes } from 'node:crypto';\nimport { resolve } from 'node:path';\nimport { PostgresError, positiveTimeout } from './errors.js';\nimport type { CliSource } from './binary.js';\n\nexport interface PostgresOptions {\n  /** Explicit executable/release; otherwise EMBEDDED_POSTGRES_CLI or the package's pinned release. */\n  cli?: CliSource;\n  postgresVersion?: string;\n  database?: string;\n  username?: string;\n  password?: string;\n  /** Zero (the default) lets PostgreSQL select an available port. */\n  port?: number;\n  cacheDir?: string;\n  binaries?: string;\n  storage?: { type: 'disposable'; workDir?: string } | { type: 'persistent'; dataDir: string; workDir?: string };\n  runAs?: { uid: number; gid: number };\n  parameters?: Readonly<Record<string, string>>;\n  startTimeoutMs?: number;\n  stopTimeoutMs?: number;\n  /** Outer startup deadline, including executable resolution. Defaults to startTimeoutMs + 30s. */\n  startupDeadlineMs?: number;\n  /** Must exceed stopTimeoutMs + 2s. Defaults to stopTimeoutMs + 5s. */\n  shutdownDeadlineMs?: number;\n  /** Lifetime cancellation: abort before or after readiness requests cleanup. */\n  signal?: AbortSignal;\n  /** Additional child environment. EP_* keys are reserved. */\n  env?: Readonly<Record<string, string>>;\n  /** CLI flag names without --. Core, credential, config and lifecycle flags are reserved. */\n  cliOptions?: Readonly<Record<string, string | number | boolean | readonly string[]>>;\n}\n\nexport interface PreparedOptions {\n  args: string[];\n  env: NodeJS.ProcessEnv;\n  password: string;\n  startupDeadlineMs: number;\n  shutdownDeadlineMs: number;\n}\n\nconst reserved = new Set(['json', 'parent-stdin', 'config', 'state-file', 'password', 'port', 'database', 'username', 'start-timeout', 'stop-timeout', 'data-dir', 'work-dir', 'cache-dir', 'binaries', 'postgres-version', 'user', 'set', 'help']);\n\nexport function prepareOptions(options: PostgresOptions): PreparedOptions {\n  const start = positiveTimeout(options.startTimeoutMs ?? 120_000, 'startTimeoutMs');\n  const stop = positiveTimeout(options.stopTimeoutMs ?? 10_000, 'stopTimeoutMs');\n  if (stop > 60_000) throw new PostgresError('CONFIG', 'stopTimeoutMs must not exceed the CLI maximum of 60000');\n  const startupDeadlineMs = positiveTimeout(options.startupDeadlineMs ?? start + 30_000, 'startupDeadlineMs');\n  const shutdownDeadlineMs = positiveTimeout(options.shutdownDeadlineMs ?? stop + 5_000, 'shutdownDeadlineMs');\n  if (shutdownDeadlineMs <= stop + 2_000) throw new PostgresError('CONFIG', 'shutdownDeadlineMs must exceed stopTimeoutMs + 2000');\n  const port = options.port ?? 0;\n  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new PostgresError('CONFIG', 'port must be an integer between 0 and 65535');\n  if (options.storage?.type === 'persistent' && (!options.storage.dataDir || !options.password || !options.username || !options.database)) {\n    throw new PostgresError('CONFIG', 'Persistent storage requires dataDir and explicit database, username and password');\n  }\n  if (options.password === '') throw new PostgresError('CONFIG', 'password must not be empty');\n  const password = options.password ?? randomBytes(24).toString('base64url');\n  const args = ['run', '--json', '--parent-stdin', `--port=${port}`, `--start-timeout=${start}ms`, `--stop-timeout=${stop}ms`];\n  const add = (name: string, value: string | undefined) => {\n    if (value !== undefined) {\n      if (value.includes('\\0')) throw new PostgresError('CONFIG', 'CLI options cannot contain NUL characters');\n      args.push(`--${name}=${value}`);\n    }\n  };\n  add('database', options.database);\n  add('username', options.username);\n  add('postgres-version', options.postgresVersion);\n  add('cache-dir', options.cacheDir === undefined ? undefined : resolve(options.cacheDir));\n  add('binaries', options.binaries === undefined ? undefined : resolve(options.binaries));\n  add('work-dir', options.storage?.workDir === undefined ? undefined : resolve(options.storage.workDir));\n  if (options.storage?.type === 'persistent') add('data-dir', resolve(options.storage.dataDir));\n  if (options.runAs) {\n    for (const id of [options.runAs.uid, options.runAs.gid]) {\n      if (!Number.isInteger(id) || id < 0 || id >= 4_294_967_295) throw new PostgresError('CONFIG', 'runAs IDs must be unsigned integers below 4294967295');\n    }\n    if (options.runAs.uid === 0) throw new PostgresError('CONFIG', 'runAs.uid must be nonzero');\n    add('user', `${options.runAs.uid}:${options.runAs.gid}`);\n  }\n  for (const [name, value] of Object.entries(options.parameters ?? {})) {\n    if (!/^[a-zA-Z_][a-zA-Z0-9_.]*$/.test(name)) throw new PostgresError('CONFIG', 'Invalid PostgreSQL parameter name');\n    add('set', `${name}=${value}`);\n  }\n  for (const [name, value] of Object.entries(options.cliOptions ?? {})) {\n    if (!/^[a-z][a-z0-9-]*$/.test(name) || reserved.has(name)) throw new PostgresError('CONFIG', 'Invalid or reserved advanced CLI option');\n    for (const item of Array.isArray(value) ? value : [value]) add(name, String(item));\n  }\n  const env: NodeJS.ProcessEnv = {};\n  for (const [name, value] of Object.entries(process.env)) {\n    // Do not allow ambient CLI configuration to turn disposable tests persistent.\n    if (!name.toUpperCase().startsWith('EP_')) env[name] = value;\n  }\n  for (const [name, value] of Object.entries(options.env ?? {})) {\n    if (name.toUpperCase().startsWith('EP_') || name.includes('=') || name.includes('\\0') || value.includes('\\0')) {\n      throw new PostgresError('CONFIG', 'Invalid or reserved child environment variable');\n    }\n    env[name] = value;\n  }\n  if (password.includes('\\0')) throw new PostgresError('CONFIG', 'password cannot contain NUL characters');\n  env.EP_PASSWORD = password;\n  return { args, env, password, startupDeadlineMs, shutdownDeadlineMs };\n}\n"]}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/protocol.d.ts

@@ -0,0 +1,22 @@
+export type ProtocolEvent = {
+    protocol: 1;
+    event: 'ready';
+    connection_url: string;
+    port: number;
+} | {
+    protocol: 1;
+    event: 'stopped';
+} | {
+    protocol: 1;
+    event: 'error';
+    error: string;
+};
+/** Incremental JSON-lines parser. Never include raw protocol in diagnostics. */
+export declare class ProtocolParser {
+    private readonly onEvent;
+    private pending;
+    constructor(onEvent: (event: ProtocolEvent) => void);
+    push(chunk: string): void;
+    finish(): void;
+    private line;
+}

package/dist/cjs/protocol.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProtocolParser = void 0;
+const errors_js_1 = require("./errors.js");
+const limit = 64 * 1024;
+/** Incremental JSON-lines parser. Never include raw protocol in diagnostics. */
+class ProtocolParser {
+    onEvent;
+    pending = '';
+    constructor(onEvent) {
+        this.onEvent = onEvent;
+    }
+    push(chunk) {
+        this.pending += chunk;
+        let newline;
+        while ((newline = this.pending.indexOf('\n')) !== -1) {
+            const line = this.pending.slice(0, newline);
+            this.pending = this.pending.slice(newline + 1);
+            this.line(line);
+        }
+        if (this.pending.length > limit)
+            throw new errors_js_1.PostgresError('PROTOCOL', 'CLI protocol line exceeds 64 KiB');
+    }
+    finish() {
+        if (this.pending)
+            this.line(this.pending);
+        this.pending = '';
+    }
+    line(line) {
+        if (line.length > limit)
+            throw new errors_js_1.PostgresError('PROTOCOL', 'CLI protocol line exceeds 64 KiB');
+        if (!line.trim())
+            return;
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            throw new errors_js_1.PostgresError('PROTOCOL', 'CLI emitted invalid JSON');
+        }
+        if (!value || typeof value !== 'object' || !('protocol' in value) || value.protocol !== 1 || !('event' in value)) {
+            throw new errors_js_1.PostgresError('PROTOCOL', 'CLI must speak protocol 1');
+        }
+        const event = value;
+        if (event.event === 'ready') {
+            if (!Number.isInteger(event.port) || event.port < 1 || event.port > 65535 || typeof event.connection_url !== 'string') {
+                throw new errors_js_1.PostgresError('PROTOCOL', 'Invalid CLI ready event');
+            }
+            let url;
+            try {
+                url = new URL(event.connection_url);
+            }
+            catch {
+                throw new errors_js_1.PostgresError('PROTOCOL', 'Invalid CLI connection URL');
+            }
+            if (!['postgres:', 'postgresql:'].includes(url.protocol))
+                throw new errors_js_1.PostgresError('PROTOCOL', 'Invalid CLI connection URL scheme');
+        }
+        else if (event.event === 'error') {
+            if (typeof event.error !== 'string')
+                throw new errors_js_1.PostgresError('PROTOCOL', 'Invalid CLI error event');
+        }
+        else if (event.event !== 'stopped') {
+            throw new errors_js_1.PostgresError('PROTOCOL', 'Unknown CLI protocol event');
+        }
+        this.onEvent(value);
+    }
+}
+exports.ProtocolParser = ProtocolParser;
+//# sourceMappingURL=protocol.js.map

package/dist/cjs/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../.local/build/src/protocol.ts"],"names":[],"mappings":"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","sourcesContent":["import { PostgresError } from './errors.js';\n\nexport type ProtocolEvent =\n  | { protocol: 1; event: 'ready'; connection_url: string; port: number }\n  | { protocol: 1; event: 'stopped' }\n  | { protocol: 1; event: 'error'; error: string };\n\nconst limit = 64 * 1024;\n\n/** Incremental JSON-lines parser. Never include raw protocol in diagnostics. */\nexport class ProtocolParser {\n  private pending = '';\n  constructor(private readonly onEvent: (event: ProtocolEvent) => void) {}\n\n  push(chunk: string): void {\n    this.pending += chunk;\n    let newline: number;\n    while ((newline = this.pending.indexOf('\\n')) !== -1) {\n      const line = this.pending.slice(0, newline);\n      this.pending = this.pending.slice(newline + 1);\n      this.line(line);\n    }\n    if (this.pending.length > limit) throw new PostgresError('PROTOCOL', 'CLI protocol line exceeds 64 KiB');\n  }\n\n  finish(): void {\n    if (this.pending) this.line(this.pending);\n    this.pending = '';\n  }\n\n  private line(line: string): void {\n    if (line.length > limit) throw new PostgresError('PROTOCOL', 'CLI protocol line exceeds 64 KiB');\n    if (!line.trim()) return;\n    let value: unknown;\n    try { value = JSON.parse(line); } catch { throw new PostgresError('PROTOCOL', 'CLI emitted invalid JSON'); }\n    if (!value || typeof value !== 'object' || !('protocol' in value) || value.protocol !== 1 || !('event' in value)) {\n      throw new PostgresError('PROTOCOL', 'CLI must speak protocol 1');\n    }\n    const event = value as Record<string, unknown>;\n    if (event.event === 'ready') {\n      if (!Number.isInteger(event.port) || (event.port as number) < 1 || (event.port as number) > 65535 || typeof event.connection_url !== 'string') {\n        throw new PostgresError('PROTOCOL', 'Invalid CLI ready event');\n      }\n      let url: URL;\n      try { url = new URL(event.connection_url); } catch { throw new PostgresError('PROTOCOL', 'Invalid CLI connection URL'); }\n      if (!['postgres:', 'postgresql:'].includes(url.protocol)) throw new PostgresError('PROTOCOL', 'Invalid CLI connection URL scheme');\n    } else if (event.event === 'error') {\n      if (typeof event.error !== 'string') throw new PostgresError('PROTOCOL', 'Invalid CLI error event');\n    } else if (event.event !== 'stopped') {\n      throw new PostgresError('PROTOCOL', 'Unknown CLI protocol event');\n    }\n    this.onEvent(value as ProtocolEvent);\n  }\n}\n"]}

package/dist/esm/binary.d.ts

@@ -0,0 +1,24 @@
+export type CliPlatform = 'linux-amd64' | 'linux-arm64' | 'darwin-amd64' | 'darwin-arm64' | 'windows-amd64' | 'windows-arm64';
+export interface CliRelease {
+    /** Exact published v2 tag. There is deliberately no implicit latest release. */
+    version: string;
+    /** Trusted SHA-256 pins, copied from reviewed upstream release checksums.txt. */
+    checksums: Readonly<Partial<Record<CliPlatform, string>>>;
+    /** Directory containing VERSION/ASSET, defaulting to upstream GitHub releases. */
+    baseUrl?: string;
+}
+/** Reviewed upstream release; every platform asset was checked against checksums.txt. */
+export declare const DEFAULT_CLI_RELEASE: Readonly<CliRelease>;
+export type CliSource = {
+    path: string;
+} | {
+    /** Omit to use this package's reviewed DEFAULT_CLI_RELEASE. */
+    release?: CliRelease;
+    cacheDir?: string;
+    offline?: boolean;
+    downloadTimeoutMs?: number;
+};
+export declare function cliPlatform(platform?: string, arch?: string): CliPlatform;
+export declare function cliAsset(target: CliPlatform): string;
+/** Explicit source, then EMBEDDED_POSTGRES_CLI, then the package's pinned release. */
+export declare function resolveCli(source?: CliSource, signal?: AbortSignal): Promise<string>;