@volter/world-core 3.0.70 → 3.0.71

package/dist/src/index.d.ts

@@ -67,6 +67,7 @@ export { acceptH2Connection, type H2Handler, type Http1Handler } from './h2.js';
 export { placeholderPng } from './placeholder-image.js';
 export { presignSigV4, signSigV4, verifySigV4, type SigV4Verdict } from './sigv4.js';
 export * as redis from './redis/index.js';
+export * as mysql from './mysql/index.js';
 export * as git from './git/index.js';
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from './scenario.js';
 export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.js';

package/dist/src/index.js

@@ -59,6 +59,7 @@ export { acceptH2Connection } from "./h2.js";
 export { placeholderPng } from "./placeholder-image.js";
 export { presignSigV4, signSigV4, verifySigV4 } from "./sigv4.js";
 export * as redis from "./redis/index.js";
+export * as mysql from "./mysql/index.js";
 export * as git from "./git/index.js";
 // ── the scenario grammar (architecture, "Behaviour") ───────────────────────────────────────────
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from "./scenario.js";

package/dist/src/mysql/client.d.ts

@@ -0,0 +1,28 @@
+import { type MysqlError } from './stream.js';
+/** Sends bytes and returns every byte the server answered to them. */
+export type MysqlExchange = (bytes: Uint8Array) => Promise<Uint8Array>;
+export type MysqlResultSet = {
+    columns: {
+        name: string;
+        type: number;
+        flags: number;
+    }[];
+    rows: (string | null)[][];
+};
+export type MysqlAnswer = MysqlResultSet | {
+    affectedRows: number;
+    insertId: number;
+} | {
+    error: MysqlError;
+};
+/** Sign in: the server's greeting, then the handshake response (mysql_native_password), following an auth switch. */
+export declare function mysqlSignIn(exchange: MysqlExchange, greeting: Uint8Array, user: string, password: string, database: string | null): Promise<{
+    ok: true;
+} | {
+    error: MysqlError;
+}>;
+/** A text query (COM_QUERY): the first result of a script, as mysql_async reads it. */
+export declare function mysqlQuery(exchange: MysqlExchange, sql: string): Promise<MysqlAnswer>;
+/** A prepared statement executed once with text-typed parameters (COM_STMT_PREPARE, EXECUTE, CLOSE), as Prisma sends a
+ *  parameterised query: binary parameters and rows. */
+export declare function mysqlExecute(exchange: MysqlExchange, sql: string, params: (string | null)[]): Promise<MysqlAnswer>;

package/dist/src/mysql/client.js

@@ -0,0 +1,220 @@
+// A MySQL client over any byte exchange: the other side of ./stream.ts, so a journey speaks the wire as an application's
+// driver does (mysql_async under Prisma's engines): protocol v10 with mysql_native_password, text queries, and prepared
+// statements with binary parameters and rows. It reads what the protocol answers; it decides nothing.
+// source: https://dev.mysql.com/doc/dev/mysql-server/latest/page_protocol_basics.html
+import { MysqlType, MysqlFlag, nativePasswordToken } from "./stream.js";
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+const CLIENT_CAPS = 0x1 | 0x4 | 0x8 | 0x200 | 0x2000 | 0x8000 | 0x10000 | 0x20000 | 0x40000 | 0x80000 | 0x200000;
+function packet(seq, payload) {
+    const out = new Uint8Array(4 + payload.length);
+    out[0] = payload.length & 0xff;
+    out[1] = (payload.length >> 8) & 0xff;
+    out[2] = (payload.length >> 16) & 0xff;
+    out[3] = seq;
+    out.set(payload, 4);
+    return out;
+}
+function packets(bytes) {
+    const out = [];
+    let at = 0;
+    while (at + 4 <= bytes.length) {
+        const len = bytes[at] | (bytes[at + 1] << 8) | (bytes[at + 2] << 16);
+        out.push(bytes.subarray(at + 4, at + 4 + len));
+        at += 4 + len;
+    }
+    return out;
+}
+class Cursor {
+    b;
+    at = 0;
+    constructor(b) {
+        this.b = b;
+    }
+    u8() { return this.b[this.at++]; }
+    u16() { return this.u8() | (this.u8() << 8); }
+    u32() { return (this.u16() | (this.u16() << 16)) >>> 0; }
+    u64() { let n = 0n; for (let i = 0n; i < 8n; i++)
+        n |= BigInt(this.u8()) << (8n * i); return n; }
+    take(n) { const out = this.b.subarray(this.at, this.at + n); this.at += n; return out; }
+    nul() { const end = this.b.indexOf(0, this.at); const s = dec.decode(this.b.subarray(this.at, end)); this.at = end + 1; return s; }
+    lenenc() { const f = this.u8(); if (f < 0xfb)
+        return f; if (f === 0xfc)
+        return this.u16(); if (f === 0xfd)
+        return this.u16() | (this.u8() << 16); return Number(this.u64()); }
+    lenencStr() { return dec.decode(this.take(this.lenenc())); }
+}
+const errorOf = (p) => {
+    const c = new Cursor(p);
+    c.u8();
+    const errno = c.u16();
+    c.u8(); // '#'
+    const sqlstate = dec.decode(c.take(5));
+    return { errno, sqlstate, message: dec.decode(c.take(p.length - c.at)) };
+};
+function column(p) {
+    const c = new Cursor(p);
+    c.lenencStr();
+    c.lenencStr();
+    c.lenencStr();
+    c.lenencStr(); // catalog, schema, table, org_table
+    const name = c.lenencStr();
+    c.lenencStr();
+    c.lenenc(); // org_name, fixed-length 0x0c
+    c.u16();
+    c.u32();
+    const type = c.u8();
+    const flags = c.u16();
+    return { name, type, flags };
+}
+const pad = (n, w = 2) => String(n).padStart(w, '0');
+/** A binary row's value as MySQL's text protocol writes it, so a journey reads both protocols alike. */
+function binaryValue(c, type, flags) {
+    const unsigned = (flags & MysqlFlag.UNSIGNED) !== 0;
+    switch (type) {
+        case MysqlType.TINY: {
+            const v = c.u8();
+            return String(unsigned ? v : (v << 24) >> 24);
+        }
+        case MysqlType.SHORT:
+        case MysqlType.YEAR: {
+            const v = c.u16();
+            return String(unsigned ? v : (v << 16) >> 16);
+        }
+        case MysqlType.LONG:
+        case MysqlType.INT24: {
+            const v = c.u32();
+            return String(unsigned ? v : v | 0);
+        }
+        case MysqlType.LONGLONG: {
+            const v = c.u64();
+            return String(unsigned ? v : BigInt.asIntN(64, v));
+        }
+        case MysqlType.FLOAT: {
+            const b = c.take(4);
+            return String(new DataView(b.buffer, b.byteOffset, 4).getFloat32(0, true));
+        }
+        case MysqlType.DOUBLE: {
+            const b = c.take(8);
+            return String(new DataView(b.buffer, b.byteOffset, 8).getFloat64(0, true));
+        }
+        case MysqlType.DATE:
+        case MysqlType.DATETIME:
+        case MysqlType.TIMESTAMP: {
+            const len = c.u8();
+            if (!len)
+                return type === MysqlType.DATE ? '0000-00-00' : '0000-00-00 00:00:00';
+            const y = c.u16(), m = c.u8(), d = c.u8();
+            const [h, i, s] = len >= 7 ? [c.u8(), c.u8(), c.u8()] : [0, 0, 0];
+            const us = len >= 11 ? c.u32() : 0;
+            const day = `${pad(y, 4)}-${pad(m)}-${pad(d)}`;
+            return type === MysqlType.DATE ? day : `${day} ${pad(h)}:${pad(i)}:${pad(s)}${us ? `.${pad(us, 6)}` : ''}`;
+        }
+        case MysqlType.TIME: {
+            const len = c.u8();
+            if (!len)
+                return '00:00:00';
+            const neg = c.u8(), days = c.u32(), h = c.u8(), i = c.u8(), s = c.u8();
+            const us = len >= 12 ? c.u32() : 0;
+            return `${neg ? '-' : ''}${pad(days * 24 + h)}:${pad(i)}:${pad(s)}${us ? `.${pad(us, 6)}` : ''}`;
+        }
+        default: return c.lenencStr();
+    }
+}
+/** One command's answer: an OK, an ERR, or a result set (text or binary rows). */
+function answer(payloads, binary) {
+    const first = payloads[0];
+    if (!first)
+        return { error: { errno: 2013, sqlstate: 'HY000', message: 'Lost connection to MySQL server during query' } };
+    if (first[0] === 0xff)
+        return { error: errorOf(first) };
+    // a result set begins with its column count (never 0): 0x00 is an OK
+    if (first[0] === 0x00) {
+        const c = new Cursor(first);
+        c.u8();
+        return { affectedRows: c.lenenc(), insertId: c.lenenc() };
+    }
+    const c = new Cursor(first);
+    const count = c.lenenc();
+    const columns = payloads.slice(1, 1 + count).map(column);
+    const rows = [];
+    for (const p of payloads.slice(2 + count)) {
+        if (p[0] === 0xfe && p.length < 9)
+            break; // the closing EOF
+        if (p[0] === 0xff)
+            return { error: errorOf(p) };
+        const r = new Cursor(p);
+        if (!binary) {
+            rows.push(columns.map(() => (r.b[r.at] === 0xfb ? (r.at++, null) : r.lenencStr())));
+            continue;
+        }
+        r.u8();
+        const bitmap = r.take(Math.floor((columns.length + 9) / 8));
+        rows.push(columns.map((col, i) => ((bitmap[Math.floor((i + 2) / 8)] >> ((i + 2) % 8)) & 1 ? null : binaryValue(r, col.type, col.flags))));
+    }
+    return { columns, rows };
+}
+/** Sign in: the server's greeting, then the handshake response (mysql_native_password), following an auth switch. */
+export async function mysqlSignIn(exchange, greeting, user, password, database) {
+    const g = new Cursor(packets(greeting)[0]);
+    g.u8();
+    g.nul();
+    g.u32();
+    const part1 = g.take(8);
+    g.u8();
+    g.u16();
+    g.u8();
+    g.u16();
+    g.u16();
+    g.u8();
+    g.take(10);
+    const part2 = g.take(12);
+    const scramble = new Uint8Array([...part1, ...part2]);
+    const token = nativePasswordToken(password, scramble);
+    const body = [...new Uint8Array([CLIENT_CAPS & 0xff, (CLIENT_CAPS >> 8) & 0xff, (CLIENT_CAPS >> 16) & 0xff, (CLIENT_CAPS >> 24) & 0xff, 0, 0, 0, 1, 45]), ...new Array(23).fill(0),
+        ...enc.encode(user), 0, token.length, ...token, ...(database ? [...enc.encode(database), 0] : [0]), ...enc.encode('mysql_native_password'), 0];
+    let reply = packets(await exchange(packet(1, Uint8Array.from(body))))[0];
+    if (reply?.[0] === 0xfe) { // the server asks for another plugin's answer: mysql_native_password with its scramble
+        const c = new Cursor(reply);
+        c.u8();
+        c.nul();
+        reply = packets(await exchange(packet(3, nativePasswordToken(password, c.take(20)))))[0];
+    }
+    if (!reply || reply[0] === 0xff)
+        return { error: reply ? errorOf(reply) : { errno: 2013, sqlstate: 'HY000', message: 'Lost connection to MySQL server during handshake' } };
+    return { ok: true };
+}
+/** A text query (COM_QUERY): the first result of a script, as mysql_async reads it. */
+export async function mysqlQuery(exchange, sql) {
+    return answer(packets(await exchange(packet(0, Uint8Array.from([0x03, ...enc.encode(sql)])))), false);
+}
+/** A prepared statement executed once with text-typed parameters (COM_STMT_PREPARE, EXECUTE, CLOSE), as Prisma sends a
+ *  parameterised query: binary parameters and rows. */
+export async function mysqlExecute(exchange, sql, params) {
+    const prepared = packets(await exchange(packet(0, Uint8Array.from([0x16, ...enc.encode(sql)]))));
+    if (prepared[0]?.[0] === 0xff)
+        return { error: errorOf(prepared[0]) };
+    const c = new Cursor(prepared[0]);
+    c.u8();
+    const id = c.u32();
+    c.u16();
+    const count = c.u16();
+    const head = [0x17, id & 0xff, (id >> 8) & 0xff, (id >> 16) & 0xff, (id >>> 24) & 0xff, 0, 1, 0, 0, 0];
+    const values = [];
+    if (count) {
+        const bitmap = new Array(Math.floor((count + 7) / 8)).fill(0);
+        params.forEach((v, i) => { if (v === null)
+            bitmap[Math.floor(i / 8)] |= 1 << (i % 8); });
+        head.push(...bitmap, 1);
+        for (let i = 0; i < count; i++)
+            head.push(params[i] === null ? MysqlType.NULL : MysqlType.VAR_STRING, 0);
+        for (const v of params)
+            if (v !== null) {
+                const b = enc.encode(v);
+                values.push(...(b.length < 251 ? [b.length] : [0xfc, b.length & 0xff, b.length >> 8]), ...b);
+            }
+    }
+    const result = answer(packets(await exchange(packet(0, Uint8Array.from([...head, ...values])))), true);
+    await exchange(packet(0, Uint8Array.from([0x19, id & 0xff, (id >> 8) & 0xff, (id >> 16) & 0xff, (id >>> 24) & 0xff])));
+    return result;
+}

package/dist/src/mysql/index.d.ts

@@ -0,0 +1,2 @@
+export * from './stream.js';
+export * from './client.js';

package/dist/src/mysql/index.js

@@ -0,0 +1,5 @@
+// THE KERNEL'S MYSQL WIRE (`@volter/world-core/mysql`): MySQL's client/server protocol as a TwinStream. A pack that serves
+// MySQL passes what a statement means (its engine) and whom it admits; the kernel names no vendor.
+// docs/contributing/architecture.md, "Other wires", the MySQL wire.
+export * from "./stream.js";
+export * from "./client.js";

package/dist/src/mysql/stream.d.ts

@@ -0,0 +1,113 @@
+import type { TwinStream } from '../twin-fetch.js';
+/** A column as the pack's engine describes it: MySQL's column type code (`MysqlType`) and flags. */
+export type MysqlColumn = {
+    name: string;
+    type: number;
+    flags?: number;
+    charset?: number;
+    length?: number;
+    decimals?: number;
+    table?: string;
+    orgTable?: string;
+    orgName?: string;
+    schema?: string;
+};
+/** A statement's outcome: rows (each value as MySQL's text protocol carries it, or null), or a count, or MySQL's error. */
+export type MysqlOutcome = {
+    columns: MysqlColumn[];
+    rows: (string | Uint8Array | null)[][];
+    warnings?: number;
+} | {
+    affectedRows: number;
+    insertId?: number | bigint;
+    warnings?: number;
+    info?: string;
+} | {
+    error: MysqlError;
+};
+export type MysqlError = {
+    errno: number;
+    sqlstate: string;
+    message: string;
+};
+export type MysqlStreamOptions<Session> = {
+    /** The handshake's server version: the one the pack's engine reports for `VERSION()`. */
+    version: string;
+    /** Admit `user` to `database` (null: none named) when `check` accepts what the pack stores for it: the password, or
+     *  MySQL's own stored form of it (`nativePasswordHash`, SHA1(SHA1(password)), as a server keeps it). */
+    connect(user: string, database: string | null, check: MysqlPasswordCheck): Promise<{
+        session: Session;
+    } | {
+        error: MysqlError;
+    }>;
+    /** Execute ONE statement (the kernel splits a script and binds parameters into the text) on the session. */
+    execute(session: Session, sql: string): Promise<MysqlOutcome>;
+    /** Whether the session holds an open transaction (SERVER_STATUS_IN_TRANS). */
+    inTransaction(session: Session): boolean;
+    /** Use another database on the session (COM_INIT_DB). */
+    useDatabase?(session: Session, database: string): Promise<MysqlError | null>;
+    /** The connection went away: roll back what it left open. */
+    close?(session: Session): void;
+};
+/** MySQL's column type codes. */
+export declare const MysqlType: {
+    readonly DECIMAL: 0;
+    readonly TINY: 1;
+    readonly SHORT: 2;
+    readonly LONG: 3;
+    readonly FLOAT: 4;
+    readonly DOUBLE: 5;
+    readonly NULL: 6;
+    readonly TIMESTAMP: 7;
+    readonly LONGLONG: 8;
+    readonly INT24: 9;
+    readonly DATE: 10;
+    readonly TIME: 11;
+    readonly DATETIME: 12;
+    readonly YEAR: 13;
+    readonly VARCHAR: 15;
+    readonly BIT: 16;
+    readonly JSON: 245;
+    readonly NEWDECIMAL: 246;
+    readonly ENUM: 247;
+    readonly SET: 248;
+    readonly TINY_BLOB: 249;
+    readonly MEDIUM_BLOB: 250;
+    readonly LONG_BLOB: 251;
+    readonly BLOB: 252;
+    readonly VAR_STRING: 253;
+    readonly STRING: 254;
+    readonly GEOMETRY: 255;
+};
+export declare const MysqlFlag: {
+    readonly NOT_NULL: 1;
+    readonly PRI_KEY: 2;
+    readonly UNIQUE_KEY: 4;
+    readonly MULTIPLE_KEY: 8;
+    readonly BLOB: 16;
+    readonly UNSIGNED: 32;
+    readonly BINARY: 128;
+    readonly AUTO_INCREMENT: 512;
+};
+/** Whether the client's mysql_native_password answer proves a password: from the password itself, or from MySQL's
+ *  stored form of it (hex SHA1(SHA1(password))), as a MySQL server checks it without holding the password. */
+export type MysqlPasswordCheck = {
+    password(password: string): boolean;
+    storedHash(hex: string): boolean;
+};
+/** MySQL's stored form of a password for mysql_native_password: SHA1(SHA1(password)), hex. A pack keeps it when the
+ *  password is made, beside whatever else it keeps, so the wire can admit the password without the pack holding it. */
+export declare function nativePasswordHash(password: string): string;
+/** mysql_native_password's token for `password` against `scramble`: SHA1(pw) XOR SHA1(scramble + SHA1(SHA1(pw))). */
+export declare function nativePasswordToken(password: string, scramble: Uint8Array): Uint8Array;
+/** A multi-statement script's statements, empty ones dropped. */
+export declare function splitStatements(sql: string): string[];
+export declare function countPlaceholders(sql: string): number;
+/** A bound parameter: an integer, a float, text, bytes (a BLOB parameter, or text that is not UTF-8), a date or time. */
+export type MysqlParam = null | bigint | number | string | Uint8Array | {
+    date: string;
+};
+/** `sql` with each `?` placeholder replaced by its parameter's literal. */
+export declare function bindParameters(sql: string, params: MysqlParam[]): string;
+/** A MySQL server as a TwinStream: the protocol here, the meaning in `options`. */
+export declare function createMysqlStream<Session>(options: MysqlStreamOptions<Session>): TwinStream;