mcp-for-i 0.1.13 → 0.2.0

package/dist/ibmi/sqlJob.js

@@ -0,0 +1,888 @@
+import { EventEmitter } from "events";
+import net from "net";
+import tls from "tls";
+import { Tools } from "./Tools.js";
+import { splitSqlStatements, isReadOnlySql } from "./sqlParse.js";
+import { checkCertificate, certificateFingerprint } from "./knownHosts.js";
+import { desiredLibraryList, existingLibrariesSql, invalidNamesWarning, libraryListCommand, libraryNamesFromRows, referencedLibraries, resolveAgainstExisting } from "./libraryList.js";
+export const DEFAULT_MAPEPIRE_PORT = 8076;
+const DEFAULT_PROBE_TIMEOUT_MS = 4000;
+const DEFAULT_CANCEL_GRACE_MS = 5000;
+const DEFAULT_OPEN_WAIT_MS = 10000;
+const FETCH_SIZE = 1000;
+const MAPEPIRE_SERVER_PATHS = [
+    "/QOpenSys/pkgs/lib/mapepire/mapepire-server.jar",
+    "/opt/mapepire/lib/mapepire/mapepire-server.jar"
+];
+const JAVA_PATHS = [
+    "/QOpenSys/QIBM/ProdData/JavaVM/jdk21/64bit/bin/java",
+    "/QOpenSys/QIBM/ProdData/JavaVM/jdk17/64bit/bin/java",
+    "/QOpenSys/QIBM/ProdData/JavaVM/jdk11/64bit/bin/java",
+    "/QOpenSys/QIBM/ProdData/JavaVM/jdk80/64bit/bin/java"
+];
+/**
+ * JDBC properties for the job. System naming makes unqualified names resolve
+ * through the library list (like a 5250 session); commitment control is off so
+ * writes to files that are not journaled behave as they do under QZDFMDB2.
+ */
+const JDBC_OPTIONS = {
+    naming: "system",
+    "transaction isolation": "none",
+    "date format": "iso",
+    "time format": "iso"
+};
+const NUMERIC_TYPES = new Set(["DECIMAL", "NUMERIC", "INTEGER", "SMALLINT", "BIGINT", "DECFLOAT", "DOUBLE", "REAL", "FLOAT"]);
+/** A CL command failed; the message carries its diagnostic and escape messages. */
+export class ClCommandError extends Tools.SqlError {
+    command;
+    messages;
+    constructor(command, messages) {
+        super(clFailureText(command, messages));
+        this.command = command;
+        this.messages = messages;
+        this.name = "ClCommandError";
+        this.sqlstate = "38501";
+    }
+}
+function clFailureText(command, messages) {
+    const relevant = messages.filter(m => /^(ESC|DIAG)/i.test(m.type || ""));
+    const detail = (relevant.length ? relevant : messages).map(m => (m.id ? `${m.id}: ${m.text}` : m.text)).join(" ");
+    return `${command.trim().split(/\s+/)[0]} failed${detail ? `: ${detail}` : ""}`;
+}
+/** Messages from the server's own machinery that say nothing about the command. */
+export function isNoiseMessage(message) {
+    return message.id === "MCH3401" && /\bPPTT\b/.test(message.text);
+}
+const QCMDEXC_CALL = /^CALL\s+(?:(?:QSYS2|QSYS)\s*[./]\s*)?QCMDEXC\s*\(\s*'((?:[^']|'')*)'\s*(?:,\s*\d+(?:\.\d*)?\s*)?\)\s*$/i;
+/** The CL command of `CALL QSYS2.QCMDEXC('...')` with a literal, else undefined. */
+export function qcmdexcLiteral(statement) {
+    const match = statement.trim().match(QCMDEXC_CALL);
+    return match ? match[1].replace(/''/g, "'") : undefined;
+}
+/** Mapepire is not installed, not running or not reachable: falling back is fine. */
+export class SqlJobUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SqlJobUnavailableError";
+    }
+}
+export function normalizeSqlTransport(value) {
+    const v = String(value ?? "").trim().toLowerCase();
+    return v === "mapepire" || v === "qzdfmdb2" ? v : "auto";
+}
+export function normalizeMapepireMode(value) {
+    const v = String(value ?? "").trim().toLowerCase();
+    return v === "daemon" || v === "ssh" ? v : "auto";
+}
+const JOB_NAME_RE = /^\d{6}\/[A-Z0-9#@$_.]{1,10}\/[A-Z0-9#@$_.]{1,10}$/i;
+export function isQualifiedJobName(value) {
+    return typeof value === "string" && JOB_NAME_RE.test(value);
+}
+export class PersistentSqlJob {
+    options;
+    handle;
+    opening;
+    queue = Promise.resolve();
+    unavailableReason;
+    lastError;
+    libraryListWarning;
+    lastCancel;
+    /** The configured library list last applied, and to which job. */
+    appliedLibraryList;
+    closed = false;
+    factory;
+    constructor(options) {
+        this.options = options;
+        this.factory = options.factory || mapepireJobFactory;
+    }
+    transport() {
+        return normalizeSqlTransport(this.options.getConfig().sqlTransport);
+    }
+    status() {
+        const transport = this.transport();
+        const live = this.handle && this.handle.isAlive() ? this.handle : undefined;
+        let active = "not-started";
+        if (transport === "qzdfmdb2" || (transport === "auto" && this.unavailableReason))
+            active = "qzdfmdb2";
+        else if (live)
+            active = "mapepire";
+        const libraryListWarning = active === "qzdfmdb2"
+            ? this.options.fallbackLibraryListWarning?.()
+            : this.libraryListWarning ?? this.options.fallbackLibraryListWarning?.();
+        return {
+            transport,
+            active,
+            ...(live ? { mode: live.mode, ...(live.technique ? { technique: live.technique } : {}), jobName: live.jobName } : {}),
+            ...(this.unavailableReason ? { unavailableReason: this.unavailableReason } : {}),
+            ...(this.lastError ? { lastError: this.lastError } : {}),
+            ...(libraryListWarning ? { libraryListWarning } : {}),
+            ...(this.lastCancel ? { lastCancel: this.lastCancel } : {})
+        };
+    }
+    /** True when the persistent job is open and alive. */
+    isOpen() {
+        return Boolean(this.handle && this.handle.isAlive());
+    }
+    /**
+     * Runs SQL (one or more statements, `@` lines run as CL) in the persistent
+     * job. Returns undefined when the caller should use QZDFMDB2 instead.
+     */
+    async runSql(statements, options = {}) {
+        const handle = await this.acquire();
+        if (!handle)
+            return undefined;
+        try {
+            return await this.exclusive(options.signal, async () => {
+                await this.ensureLibraryList(handle);
+                return this.runAll(handle, statements, options.signal);
+            });
+        }
+        catch (err) {
+            // The job died under a read: nothing was changed, so reopen and retry once.
+            if (!handle.isAlive() && !options.signal?.aborted && isReadOnlySql(statements)) {
+                await this.discard(handle);
+                const next = await this.acquire();
+                if (!next)
+                    return undefined;
+                return this.exclusive(options.signal, async () => {
+                    await this.ensureLibraryList(next);
+                    return this.runAll(next, statements, options.signal);
+                });
+            }
+            if (!handle.isAlive())
+                await this.discard(handle);
+            throw err;
+        }
+    }
+    /**
+     * Runs a CL command in the persistent job. Returns undefined when the job is
+     * not used, otherwise the job log messages the command sent.
+     */
+    async runCl(command, options = {}) {
+        const handle = await this.acquire();
+        if (!handle)
+            return undefined;
+        try {
+            return await this.exclusive(options.signal, async () => {
+                await this.ensureLibraryList(handle);
+                return this.execCl(handle, command, options.signal);
+            });
+        }
+        catch (err) {
+            if (!handle.isAlive())
+                await this.discard(handle);
+            throw err;
+        }
+    }
+    async close() {
+        this.closed = true;
+        const opening = this.opening;
+        if (opening)
+            await opening.catch(() => undefined);
+        const handle = this.handle;
+        this.handle = undefined;
+        if (handle)
+            await handle.close().catch(() => undefined);
+    }
+    async acquire() {
+        if (this.closed)
+            return undefined;
+        const transport = this.transport();
+        if (transport === "qzdfmdb2") {
+            if (this.handle)
+                await this.discard(this.handle);
+            return undefined;
+        }
+        if (this.handle) {
+            if (this.handle.isAlive())
+                return this.handle;
+            this.lastError = "The persistent SQL job ended; a new job was opened.";
+            await this.discard(this.handle);
+        }
+        if (transport === "auto" && this.unavailableReason)
+            return undefined;
+        if (!this.opening) {
+            this.opening = this.open(transport).finally(() => {
+                this.opening = undefined;
+            });
+        }
+        if (transport === "mapepire")
+            return this.opening;
+        // In auto mode a slow start (single mode starts a JVM) must not eat the
+        // caller's timeout: this call uses QZDFMDB2 and the job keeps opening.
+        const waitMs = this.options.openWaitMs ?? DEFAULT_OPEN_WAIT_MS;
+        let timer;
+        try {
+            return await Promise.race([
+                this.opening,
+                new Promise(resolve => { timer = setTimeout(() => resolve(undefined), waitMs); })
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    async open(transport) {
+        const request = this.options.getOpenRequest();
+        if (!request) {
+            if (transport === "mapepire")
+                throw new Error("Not connected");
+            return undefined;
+        }
+        let handle;
+        try {
+            handle = await this.factory(request);
+        }
+        catch (err) {
+            const message = err?.message || String(err);
+            this.lastError = message;
+            if (transport === "mapepire") {
+                throw new Error(`Mapepire SQL job could not be opened (sqlTransport is "mapepire"): ${message}`);
+            }
+            // Cached for this connection: later SQL goes straight to QZDFMDB2.
+            this.unavailableReason = message;
+            return undefined;
+        }
+        if (this.closed) {
+            await handle.close().catch(() => undefined);
+            return undefined;
+        }
+        this.handle = handle;
+        this.unavailableReason = undefined;
+        return handle;
+    }
+    /**
+     * Applies the connection's configured library list again, even when it was
+     * applied before. Returns undefined when the persistent job is not used.
+     */
+    async reapplyLibraryList() {
+        const handle = await this.acquire();
+        if (!handle)
+            return undefined;
+        return this.exclusive(undefined, async () => {
+            this.appliedLibraryList = undefined;
+            await this.ensureLibraryList(handle);
+            return this.libraryListWarning ? { warning: this.libraryListWarning } : {};
+        });
+    }
+    /**
+     * Puts the connection's configured library list and current library in
+     * effect in the job, unless that list was already applied to this job. Runs
+     * inside the queue. A failure never fails the caller's statement: missing
+     * libraries are left out and the reason is kept for the session status.
+     */
+    async ensureLibraryList(handle) {
+        const desired = desiredLibraryList(this.options.getConfig());
+        const applied = this.appliedLibraryList;
+        if (applied && applied.handle === handle && applied.signature === desired.signature)
+            return;
+        // Recorded first, so a list that cannot be applied is not retried on every call.
+        this.appliedLibraryList = { handle, signature: desired.signature };
+        this.libraryListWarning = invalidNamesWarning(desired);
+        const command = libraryListCommand(desired.libraries, desired.currentLibrary);
+        if (!command)
+            return;
+        try {
+            await this.execCl(handle, command);
+            return;
+        }
+        catch (err) {
+            if (!handle.isAlive())
+                throw err;
+            const firstError = err?.message || String(err);
+            try {
+                const names = referencedLibraries(desired);
+                const result = await this.runStatement(handle, existingLibrariesSql(names)).catch(err => {
+                    if (!handle.isAlive())
+                        throw err;
+                    // Older releases do not know *ALLSIMPLE.
+                    return this.runStatement(handle, existingLibrariesSql(names, false));
+                });
+                const resolved = resolveAgainstExisting(desired, libraryNamesFromRows(result.rows));
+                if (!resolved.warning) {
+                    this.libraryListWarning = `${command} failed in the SQL job: ${firstError}`;
+                    return;
+                }
+                if (resolved.command)
+                    await this.execCl(handle, resolved.command);
+                this.libraryListWarning = resolved.warning;
+            }
+            catch (retryErr) {
+                if (!handle.isAlive())
+                    throw retryErr;
+                this.libraryListWarning = `${command} failed in the SQL job: ${firstError}`;
+            }
+        }
+    }
+    /** Runs CL so that its library list changes last (see the note at the top). */
+    async execCl(handle, command, signal) {
+        if (!handle.runCl) {
+            await this.runStatement(handle, "CALL QSYS2.QCMDEXC(?)", [command], signal);
+            return [];
+        }
+        const result = await this.withCancel(handle, handle.runCl(command, { signal }), signal);
+        const messages = (result.messages || []).filter(m => !isNoiseMessage(m));
+        if (!result.success)
+            throw new ClCommandError(command, messages);
+        return messages;
+    }
+    async discard(handle) {
+        if (this.handle === handle)
+            this.handle = undefined;
+        await handle.close().catch(() => undefined);
+    }
+    /** Statements share one job, so they run one at a time. */
+    exclusive(signal, task) {
+        const run = async () => {
+            if (signal?.aborted)
+                throw new Error("SQL statement cancelled before it started");
+            return task();
+        };
+        const result = this.queue.then(run, run);
+        this.queue = result.catch(() => undefined);
+        return result;
+    }
+    async runAll(handle, statements, signal) {
+        const rows = [];
+        let updateCount;
+        for (const statement of splitSqlStatements(statements)) {
+            if (signal?.aborted)
+                throw new Error("SQL statement cancelled");
+            const isCl = statement.tokens.length === 1 && statement.tokens[0].type === "cl";
+            const clCommand = isCl ? statement.tokens[0].value : qcmdexcLiteral(statement.text);
+            if (clCommand !== undefined) {
+                await this.execCl(handle, clCommand, signal);
+                continue;
+            }
+            const result = await this.runStatement(handle, statement.text, undefined, signal);
+            rows.push(...result.rows);
+            if (typeof result.updateCount === "number" && result.updateCount >= 0) {
+                updateCount = (updateCount ?? 0) + result.updateCount;
+            }
+        }
+        if (updateCount !== undefined) {
+            Object.defineProperty(rows, "updateCount", { value: updateCount, enumerable: false });
+        }
+        return rows;
+    }
+    async runStatement(handle, sql, parameters, signal) {
+        const work = handle.run(sql, { parameters, signal }).then(result => ({ rows: result.rows.map(row => normalizeRow(row, result.columns)), updateCount: result.updateCount }), err => { throw toSqlError(err, sql); });
+        return this.withCancel(handle, work, signal);
+    }
+    /** When `signal` aborts while `work` runs, the statement is cancelled on the IBM i. */
+    async withCancel(handle, work, signal) {
+        if (!signal)
+            return work;
+        if (signal.aborted) {
+            void this.cancelInFlight(handle, work);
+            return work;
+        }
+        const onAbort = () => { void this.cancelInFlight(handle, work); };
+        signal.addEventListener("abort", onAbort, { once: true });
+        try {
+            return await work;
+        }
+        finally {
+            signal.removeEventListener("abort", onAbort);
+        }
+    }
+    /**
+     * The caller timed out: ask the IBM i to cancel the statement (QSYS2.CANCEL_SQL
+     * from a separate job). If it is still running after a grace period, end the
+     * persistent job; the next call opens a new one and reapplies the library list.
+     */
+    async cancelInFlight(handle, work) {
+        let done = false;
+        const settled = work.then(() => { done = true; }, () => { done = true; });
+        const notes = [];
+        if (handle.jobName && isQualifiedJobName(handle.jobName) && this.options.cancelStatement) {
+            try {
+                await this.options.cancelStatement(handle.jobName);
+                notes.push(`CANCEL_SQL requested for ${handle.jobName}`);
+            }
+            catch (err) {
+                notes.push(`CANCEL_SQL failed: ${err?.message || String(err)}`);
+            }
+        }
+        if (!done) {
+            const grace = this.options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS;
+            let timer;
+            await Promise.race([settled, new Promise(resolve => { timer = setTimeout(resolve, grace); })]);
+            if (timer)
+                clearTimeout(timer);
+        }
+        if (!done) {
+            notes.push("statement still running; the SQL job was ended and will be reopened on the next call");
+            await this.discard(handle);
+        }
+        this.lastCancel = `${new Date().toISOString()}: ${notes.join("; ") || "cancelled"}`;
+    }
+}
+/** Mapepire values to the row shape QZDFMDB2 parsing produces (trimmed strings, numbers, null). */
+export function normalizeRow(row, columns) {
+    const types = new Map();
+    for (const column of columns || []) {
+        if (column?.name)
+            types.set(column.name, String(column.type || "").toUpperCase());
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(row || {})) {
+        if (value === undefined || value === null) {
+            out[key] = null;
+        }
+        else if (typeof value === "number") {
+            out[key] = value;
+        }
+        else if (typeof value === "string") {
+            const type = types.get(key);
+            if (type && NUMERIC_TYPES.has(type) && value.trim() !== "" && Number.isFinite(Number(value))) {
+                out[key] = Number(value);
+            }
+            else {
+                out[key] = value.trimEnd();
+            }
+        }
+        else if (typeof value === "boolean") {
+            out[key] = value ? "true" : "false";
+        }
+        else {
+            out[key] = JSON.stringify(value);
+        }
+    }
+    return out;
+}
+/** Mapepire errors look like "<message>, <SQLSTATE>, <SQLCODE>". */
+export function toSqlError(err, sql) {
+    if (err instanceof Tools.SqlError)
+        return err;
+    const message = String(err?.message || err || "SQL error");
+    const match = message.match(/^(.*), ([0-9A-Z]{5}), (-?\d+)$/s);
+    if (!match)
+        return err instanceof Error ? err : new Error(message);
+    const sqlError = new Tools.SqlError(`${match[1]} (${match[2]})`);
+    sqlError.sqlstate = match[2];
+    sqlError.cause = sql;
+    return sqlError;
+}
+let mapepireModule;
+async function loadMapepire() {
+    if (!mapepireModule) {
+        mapepireModule = import("@ibm/mapepire-js").then((m) => m.default ?? m);
+        mapepireModule.catch(() => { mapepireModule = undefined; });
+    }
+    try {
+        return await mapepireModule;
+    }
+    catch (err) {
+        throw new SqlJobUnavailableError(`The @ibm/mapepire-js package could not be loaded: ${err?.message || String(err)}`);
+    }
+}
+/**
+ * Opens a Mapepire job. "daemon" connects to the Mapepire server (port 8076,
+ * TLS, user and password). "ssh" starts mapepire-server in single mode over the
+ * connection's own SSH session, so it also works with key-based logins and
+ * needs no open port, only the server JAR and Java on the IBM i. "auto" uses
+ * the daemon when a password is available and falls back to ssh.
+ */
+export const mapepireJobFactory = async (request) => {
+    const mapepire = await loadMapepire();
+    const mode = request.mode;
+    if (mode === "daemon" || (mode === "auto" && request.password)) {
+        try {
+            return await openDaemonJob(mapepire, request);
+        }
+        catch (err) {
+            if (mode === "daemon" || !(err instanceof SqlJobUnavailableError) || !request.ssh)
+                throw err;
+            try {
+                return await openSshJob(mapepire, request);
+            }
+            catch (sshErr) {
+                throw new SqlJobUnavailableError(`${err.message}; single mode over SSH: ${sshErr?.message || String(sshErr)}`);
+            }
+        }
+    }
+    return openSshJob(mapepire, request);
+};
+async function openDaemonJob(mapepire, request) {
+    if (!request.password) {
+        throw new SqlJobUnavailableError("The Mapepire server needs a password; this connection has none (use mapepireMode \"ssh\")");
+    }
+    const pin = await resolveCertificatePin(request.host, request.port, request.probeTimeoutMs);
+    const transport = new PinnedWebSocketTransport(pin, request.probeTimeoutMs * 2);
+    const job = new mapepire.SQLJob({ ...JDBC_OPTIONS }, transport);
+    try {
+        await job.connect({ host: request.host, port: request.port, user: request.username, password: request.password }, "mcp-for-i");
+    }
+    catch (err) {
+        await Promise.resolve(job.close()).catch(() => undefined);
+        throw err;
+    }
+    return wrapMapepireJob(job, "daemon", () => transport.isConnected());
+}
+async function openSshJob(mapepire, request) {
+    if (!request.ssh)
+        throw new SqlJobUnavailableError("No SSH session for Mapepire single mode");
+    const serverPath = await findRemoteFile(request, request.serverPath ? [request.serverPath] : MAPEPIRE_SERVER_PATHS);
+    if (!serverPath) {
+        throw new SqlJobUnavailableError(`mapepire-server.jar not found (${(request.serverPath ? [request.serverPath] : MAPEPIRE_SERVER_PATHS).join(", ")}); install it with "yum install mapepire-server"`);
+    }
+    const javaPath = await findRemoteFile(request, request.javaPath ? [request.javaPath] : JAVA_PATHS);
+    if (!javaPath)
+        throw new SqlJobUnavailableError("No Java runtime found for Mapepire single mode (set mapepireJavaPath)");
+    const start = async () => {
+        const job = mapepire.SQLJob.withConfig({
+            transport: "ssh-single",
+            sshSingle: {
+                exec: mapepire.createNodeSSHExec(request.ssh),
+                serverPath,
+                javaPath,
+                startupTimeout: 60000
+            }
+        }, { ...JDBC_OPTIONS });
+        try {
+            await job.connect(undefined, "mcp-for-i");
+        }
+        catch (err) {
+            await Promise.resolve(job.close()).catch(() => undefined);
+            throw err;
+        }
+        return job;
+    };
+    const wrap = (job, technique) => wrapMapepireJob(job, "ssh", () => {
+        try {
+            return Boolean(job.getTransport()?.isConnected());
+        }
+        catch {
+            return false;
+        }
+    }, technique);
+    // Single mode connects with the in-process CLI technique, which ignores the
+    // JDBC properties (so SQL naming, and unqualified names do not use the
+    // library list) and runs each SQL request on its own thread, so library
+    // list changes do not last. Switch the server to the TCP technique: a
+    // database host server job on the same system, signed on as the same user,
+    // with system naming and a library list that persists.
+    const job = await start();
+    try {
+        const response = await job.send({
+            id: mapepire.SQLJob.getNewUniqueId(),
+            type: "connect",
+            technique: "tcp",
+            application: "mcp-for-i",
+            props: jdbcPropertiesString(JDBC_OPTIONS)
+        });
+        if (response?.success === true) {
+            if (typeof response.job === "string")
+                job.id = response.job;
+            return wrap(job, "tcp");
+        }
+        throw new Error(response?.error || "connect failed");
+    }
+    catch {
+        // The failed reconnect may have dropped the CLI connection: start again.
+        await Promise.resolve(job.close()).catch(() => undefined);
+    }
+    return wrap(await start(), "cli");
+}
+/** JDBC properties as Mapepire's connect request carries them. */
+export function jdbcPropertiesString(options) {
+    return Object.entries(options).map(([key, value]) => `${key}=${Array.isArray(value) ? value.join(",") : value}`).join(";");
+}
+/** Mapepire reports single-mode CLI jobs as number-user-name. */
+export function normalizeJobName(value) {
+    if (typeof value !== "string" || !value)
+        return undefined;
+    const dashed = value.match(/^(\d{6})-([^-/]{1,10})-([^-/]{1,10})$/);
+    return dashed ? `${dashed[1]}/${dashed[2]}/${dashed[3]}` : value;
+}
+async function findRemoteFile(request, candidates) {
+    const script = candidates
+        .map(p => `if [ -f ${Tools.shellQuote(p)} ]; then echo ${Tools.shellQuote(p)}; exit 0; fi`)
+        .join("; ");
+    try {
+        const result = await request.sendCommand({ command: `${script}; exit 1` });
+        const found = result.stdout.split(/\r?\n/).map(l => l.trim()).find(Boolean);
+        return found && candidates.includes(found) ? found : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function wrapMapepireJob(job, mode, connected, technique = "tcp") {
+    // SQLJob.close() drops its response listeners, so requests still waiting on
+    // the job would never settle. Track them and fail them on close.
+    const pending = new Set();
+    let closed = false;
+    const runQuery = async (sql, options) => {
+        const query = job.query(sql, options.parameters ? { parameters: options.parameters } : {});
+        let result = await query.execute(FETCH_SIZE);
+        const rows = Array.isArray(result.data) ? [...result.data] : [];
+        const columns = (result.metadata?.columns || []).map((c) => ({ name: c.name || c.label, type: c.type }));
+        while (result.has_results && !result.is_done) {
+            if (options.signal?.aborted) {
+                await Promise.resolve(query.close()).catch(() => undefined);
+                throw new Error("SQL statement cancelled");
+            }
+            result = await query.fetchMore(FETCH_SIZE);
+            if (Array.isArray(result.data))
+                rows.push(...result.data);
+        }
+        const updateCount = result.has_results ? undefined : result.update_count;
+        return { rows, columns, updateCount: typeof updateCount === "number" ? updateCount : undefined };
+    };
+    // A CL request answers with the job log messages the command sent, and
+    // success false when it failed; it does not reject.
+    const runClCommand = async (command) => {
+        const query = job.clcommand(command);
+        const result = await query.execute(FETCH_SIZE);
+        if (result.has_results && !result.is_done)
+            await Promise.resolve(query.close()).catch(() => undefined);
+        const rows = Array.isArray(result.data) ? result.data : [];
+        const messages = rows.map(row => ({
+            id: row.MESSAGE_ID ? String(row.MESSAGE_ID).trim() : undefined,
+            type: row.MESSAGE_TYPE ? String(row.MESSAGE_TYPE).trim() : undefined,
+            text: String(row.MESSAGE_TEXT ?? row.SUMMARY ?? "").trim()
+        }));
+        if (result.success === false && messages.length === 0 && result.error) {
+            messages.push({ type: "ESCAPE", text: String(result.error) });
+        }
+        return { success: result.success !== false, messages };
+    };
+    return {
+        mode,
+        technique,
+        get jobName() {
+            return normalizeJobName(job.id);
+        },
+        isAlive() {
+            if (closed)
+                return false;
+            const status = String(job.getStatus?.() ?? "");
+            return status !== "ended" && status !== "notStarted" && connected();
+        },
+        run(sql, options) {
+            if (closed)
+                return Promise.reject(new Error("SQL job closed"));
+            return new Promise((resolve, reject) => {
+                pending.add(reject);
+                runQuery(sql, options).then(resolve, reject).finally(() => pending.delete(reject));
+            });
+        },
+        runCl(command) {
+            if (closed)
+                return Promise.reject(new Error("SQL job closed"));
+            return new Promise((resolve, reject) => {
+                pending.add(reject);
+                runClCommand(command).then(resolve, reject).finally(() => pending.delete(reject));
+            });
+        },
+        async close() {
+            closed = true;
+            const error = new Error("SQL job closed");
+            for (const reject of pending)
+                reject(error);
+            pending.clear();
+            await job.close();
+        }
+    };
+}
+/**
+ * Reads the server certificate chain (no credentials are sent on this
+ * connection). A chain that ends in a publicly trusted CA is verified the
+ * normal way. Otherwise (self-signed, as Mapepire generates by default, or a
+ * private CA) the root is pinned on first use in known_hosts.json and must
+ * match on every later connection.
+ */
+export async function resolveCertificatePin(host, port, timeoutMs = DEFAULT_PROBE_TIMEOUT_MS) {
+    const leaf = await fetchCertificateChain(host, port, timeoutMs);
+    const root = findRootCertificate(leaf);
+    const pem = derToPem(root.raw);
+    const isPublic = tls.rootCertificates.some(ca => ca.replace(/\s+/g, "") === pem.replace(/\s+/g, ""));
+    if (isPublic)
+        return { host, port };
+    const subject = root.subject ? Object.entries(root.subject).map(([k, v]) => `${k}=${v}`).join(", ") : undefined;
+    const { fingerprint } = await checkCertificate({ host, port, der: root.raw, subject });
+    return { host, port, ca: pem, fingerprint };
+}
+function fetchCertificateChain(host, port, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let finished = false;
+        const finish = (fn) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            socket.destroy();
+            fn();
+        };
+        // Chain verification happens later against the pinned certificate; this
+        // connection only reads the certificate and sends nothing.
+        const socket = tls.connect({
+            host,
+            port,
+            servername: net.isIP(host) ? undefined : host,
+            rejectUnauthorized: false
+        });
+        const timer = setTimeout(() => {
+            finish(() => reject(new SqlJobUnavailableError(`Mapepire server not reachable on ${host}:${port} (no answer in ${timeoutMs}ms)`)));
+        }, timeoutMs);
+        socket.once("secureConnect", () => {
+            const cert = socket.getPeerCertificate(true);
+            finish(() => {
+                if (!cert || !cert.raw)
+                    reject(new Error(`Mapepire server on ${host}:${port} presented no certificate`));
+                else
+                    resolve(cert);
+            });
+        });
+        socket.once("error", (err) => {
+            finish(() => {
+                const code = err?.code ? ` (${err.code})` : "";
+                reject(new SqlJobUnavailableError(`Mapepire server not reachable on ${host}:${port}${code}: ${err?.message || String(err)}`));
+            });
+        });
+    });
+}
+function findRootCertificate(leaf) {
+    let current = leaf;
+    const seen = new Set();
+    while (current.issuerCertificate && current.issuerCertificate !== current) {
+        const fp = current.fingerprint256;
+        if (seen.has(fp))
+            break;
+        seen.add(fp);
+        if (!current.issuerCertificate.raw)
+            break;
+        current = current.issuerCertificate;
+    }
+    return current;
+}
+export function derToPem(der) {
+    const b64 = der.toString("base64");
+    const lines = [];
+    for (let i = 0; i < b64.length; i += 64)
+        lines.push(b64.slice(i, i + 64));
+    return `-----BEGIN CERTIFICATE-----\n${lines.join("\n")}\n-----END CERTIFICATE-----\n`;
+}
+/** True when the presented chain contains the pinned certificate. */
+export function chainHasFingerprint(cert, fingerprint) {
+    let current = cert;
+    const seen = new Set();
+    while (current && current.raw && !seen.has(current)) {
+        seen.add(current);
+        if (certificateFingerprint(current.raw) === fingerprint)
+            return true;
+        current = current.issuerCertificate;
+    }
+    return false;
+}
+/**
+ * WebSocket transport for Mapepire's SQLJob (same protocol as the library's
+ * WebSocketTransport) that verifies the server against the pinned certificate.
+ * The chain must validate against the pinned root and contain it; the host
+ * name is not compared because Mapepire's self-signed certificate rarely
+ * matches the name or address used to connect. Without a pin the normal CA and
+ * host name checks apply. Certificate errors are never ignored.
+ */
+export class PinnedWebSocketTransport {
+    pin;
+    timeoutMs;
+    socket;
+    connected = false;
+    responseEmitter = new EventEmitter();
+    constructor(pin, timeoutMs = 8000) {
+        this.pin = pin;
+        this.timeoutMs = timeoutMs;
+    }
+    async connect(server) {
+        const { default: WebSocket } = await import("ws");
+        const host = server.host;
+        const port = server.port || DEFAULT_MAPEPIRE_PORT;
+        const urlHost = net.isIPv6(host) ? `[${host}]` : host;
+        const fingerprint = this.pin.fingerprint;
+        const options = {
+            headers: {
+                authorization: `Basic ${Buffer.from(`${server.user}:${server.password}`).toString("base64")}`
+            },
+            handshakeTimeout: this.timeoutMs,
+            rejectUnauthorized: true
+        };
+        if (this.pin.ca && fingerprint) {
+            options.ca = this.pin.ca;
+            options.allowPartialTrustChain = true;
+            options.checkServerIdentity = (_host, cert) => chainHasFingerprint(cert, fingerprint)
+                ? undefined
+                : new Error(`Mapepire server certificate does not match the pinned certificate ${fingerprint}`);
+        }
+        await new Promise((resolve, reject) => {
+            let opened = false;
+            const ws = new WebSocket(`wss://${urlHost}:${port}/db/`, options);
+            ws.on("error", (err) => {
+                if (!opened)
+                    reject(err);
+            });
+            ws.on("message", (data) => {
+                let response;
+                try {
+                    response = JSON.parse(data.toString(), ((_key, value, context) => {
+                        // Keep the server's exact text for numbers JavaScript would round.
+                        if (context && typeof value === "number" && context.source !== undefined && String(value) !== context.source) {
+                            return context.source;
+                        }
+                        return value;
+                    }));
+                }
+                catch {
+                    return;
+                }
+                if (response && typeof response.id === "string")
+                    this.responseEmitter.emit(response.id, response);
+            });
+            ws.on("close", (code, reason) => {
+                this.connected = false;
+                this.notifyConnectionFailure(code, reason?.toString() || "");
+                if (!opened)
+                    reject(new Error(`Mapepire connection closed (${code})`));
+            });
+            ws.once("open", () => {
+                opened = true;
+                this.socket = ws;
+                this.connected = true;
+                resolve();
+            });
+        });
+    }
+    async send(request) {
+        if (!this.socket || !this.connected) {
+            // Fail the waiting request instead of leaving it pending.
+            setImmediate(() => this.responseEmitter.emit(`${request.id}_conn_fail`, new Error("Mapepire connection is not open")));
+            return;
+        }
+        this.socket.send(JSON.stringify(request));
+    }
+    async close() {
+        const socket = this.socket;
+        this.socket = undefined;
+        this.connected = false;
+        if (socket)
+            socket.close();
+        this.notifyConnectionFailure(1000, "closed");
+    }
+    getResponseEmitter() {
+        return this.responseEmitter;
+    }
+    isConnected() {
+        return this.connected;
+    }
+    enableTrace() { }
+    disableTrace() { }
+    notifyConnectionFailure(code, reason) {
+        const events = this.responseEmitter.eventNames().filter(e => typeof e === "string" && e.endsWith("_conn_fail"));
+        for (const event of events) {
+            this.responseEmitter.emit(event, new Error(`Connection failed with code ${code}${reason ? `: ${reason}` : ""}`));
+        }
+        this.responseEmitter.removeAllListeners();
+    }
+}