@volter/twin-planetscale 0.1.0

package/dist/src/planetscale-mysql.js

@@ -0,0 +1,547 @@
+// Native MySQL frontend for the SAME psdb state owner. No database or kernel writes live here.
+// Wire reference: https://dev.mysql.com/doc/dev/mysql-server/latest/PAGE_PROTOCOL.html
+// Prepared parameters/result rows follow page_protocol_com_stmt_execute.html and
+// page_protocol_binary_resultset.html; parameter types are cached per prepared statement.
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { parseStatement, SERVER_VERSION, SqlError, SYSTEM_VARIABLES, tokenize } from "./planetscale-sql.js";
+const MAX_PACKET = 16 * 1024 * 1024 - 2;
+const MAX_STATEMENTS = 1024;
+const CAPABILITIES = 1 | 4 | 8 | 512 | 8192 | 32768 | 131072 | 262144 | 524288;
+class MysqlError extends Error {
+    errno;
+    state;
+    constructor(message, errno = 1235, state = '42000') {
+        super(message);
+        this.errno = errno;
+        this.state = state;
+    }
+}
+const integer = (value, bytes) => {
+    const out = Buffer.alloc(bytes);
+    if (bytes === 8)
+        out.writeBigUInt64LE(BigInt.asUintN(64, BigInt(value)));
+    else
+        out.writeUIntLE(Number(value), 0, bytes);
+    return out;
+};
+const length = (n) => n < 251 ? integer(n, 1) : n < 65536 ? Buffer.concat([Buffer.from([252]), integer(n, 2)])
+    : n < 16777216 ? Buffer.concat([Buffer.from([253]), integer(n, 3)]) : Buffer.concat([Buffer.from([254]), integer(n, 8)]);
+const string = (value) => { const bytes = Buffer.isBuffer(value) ? value : Buffer.from(value); return Buffer.concat([length(bytes.length), bytes]); };
+class Reader {
+    buffer;
+    offset = 0;
+    constructor(buffer) {
+        this.buffer = buffer;
+    }
+    bytes(n) {
+        if (!Number.isSafeInteger(n) || n < 0 || this.offset + n > this.buffer.length)
+            throw new MysqlError('Malformed MySQL packet', 1835, 'HY000');
+        const value = this.buffer.subarray(this.offset, this.offset + n);
+        this.offset += n;
+        return value;
+    }
+    uint(n) { return this.bytes(n).readUIntLE(0, n); }
+    len() { const first = this.uint(1); return first < 251 ? first : first === 252 ? this.uint(2) : first === 253 ? this.uint(3) : first === 254 ? Number(this.bytes(8).readBigUInt64LE()) : (() => { throw new MysqlError('Invalid length', 1835); })(); }
+    str() { return this.bytes(this.len()); }
+    zero() { const end = this.buffer.indexOf(0, this.offset); if (end < 0)
+        throw new MysqlError('Unterminated string', 1835); const result = this.bytes(end - this.offset).toString(); this.bytes(1); return result; }
+}
+/** Placeholders only in executable SQL. A prepare never executes a mutation. */
+export function mysqlPlaceholders(sql) {
+    const positions = [];
+    let quote = '';
+    let comment = '';
+    for (let i = 0; i < sql.length; i++) {
+        const c = sql[i];
+        const next = sql[i + 1];
+        if (comment === 'line') {
+            if (c === '\n')
+                comment = '';
+            continue;
+        }
+        if (comment === 'block') {
+            if (c === '*' && next === '/') {
+                comment = '';
+                i++;
+            }
+            continue;
+        }
+        if (quote) {
+            if (c === '\\' && quote !== '`') {
+                i++;
+                continue;
+            }
+            if (c === quote) {
+                if (next === quote)
+                    i++;
+                else
+                    quote = '';
+            }
+            continue;
+        }
+        if (c === "'" || c === '"' || c === '`')
+            quote = c;
+        else if (c === '#' || (c === '-' && next === '-')) {
+            comment = 'line';
+        }
+        else if (c === '/' && next === '*') {
+            comment = 'block';
+            i++;
+        }
+        else if (c === '?')
+            positions.push(i);
+    }
+    return positions;
+}
+function bind(sql, positions, values) {
+    let result = '';
+    let previous = 0;
+    positions.forEach((position, i) => { result += sql.slice(previous, position) + values[i]; previous = position + 1; });
+    return result + sql.slice(previous);
+}
+const quote = (value) => {
+    const text = value.toString('utf8');
+    if (!Buffer.from(text).equals(value))
+        return `X'${value.toString('hex')}'`;
+    return `'${text.replace(/\\/g, '\\\\').replace(/'/g, "''").replace(/\0/g, '\\0')}'`;
+};
+const TYPES = { NULL_TYPE: 6, INT8: 1, UINT8: 1, INT16: 2, UINT16: 2, INT24: 9, UINT24: 9,
+    INT32: 3, UINT32: 3, INT64: 8, UINT64: 8, FLOAT32: 4, FLOAT64: 5, TIMESTAMP: 7, DATE: 10, TIME: 11,
+    DATETIME: 12, YEAR: 13, DECIMAL: 246, TEXT: 252, BLOB: 252, VARCHAR: 253, VARBINARY: 253, CHAR: 254,
+    BINARY: 254, BIT: 16, ENUM: 254, SET: 254, JSON: 245 };
+function column(field) {
+    const fixed = Buffer.concat([integer(field.charset ?? 45, 2), integer(field.columnLength ?? 1024, 4),
+        integer(TYPES[field.type ?? 'NULL_TYPE'] ?? 253, 1), integer(field.flags ?? 0, 2), Buffer.from([0, 0, 0])]);
+    return Buffer.concat([string('def'), string(field.database ?? ''), string(field.table ?? ''), string(field.orgTable ?? ''),
+        string(field.name), string(field.orgName ?? field.name), Buffer.from([12]), fixed]);
+}
+function dateValue(reader, type) {
+    const size = reader.uint(1);
+    if (size === 0)
+        return "'0000-00-00 00:00:00'";
+    if (type === 11) {
+        if (size !== 8 && size !== 12)
+            throw new MysqlError('Invalid TIME parameter', 1835);
+        const sign = reader.uint(1);
+        const days = reader.uint(4);
+        const hours = days * 24 + reader.uint(1);
+        const minute = reader.uint(1);
+        const second = reader.uint(1);
+        const micro = size === 12 ? reader.uint(4) : 0;
+        return `'${sign ? '-' : ''}${hours}:${String(minute).padStart(2, '0')}:${String(second).padStart(2, '0')}.${String(micro).padStart(6, '0')}'`;
+    }
+    if (![4, 7, 11].includes(size))
+        throw new MysqlError('Invalid date parameter', 1835);
+    const year = reader.uint(2);
+    const month = reader.uint(1);
+    const day = reader.uint(1);
+    const h = size >= 7 ? reader.uint(1) : 0;
+    const m = size >= 7 ? reader.uint(1) : 0;
+    const s = size >= 7 ? reader.uint(1) : 0;
+    const micro = size === 11 ? reader.uint(4) : 0;
+    return `'${year}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')} ${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}.${String(micro).padStart(6, '0')}'`;
+}
+function parameters(reader, statement) {
+    const n = statement.positions.length;
+    if (n === 0)
+        return [];
+    const nulls = reader.bytes(Math.ceil(n / 8));
+    const fresh = reader.uint(1);
+    if (fresh === 1)
+        statement.types = Array.from({ length: n }, () => ({ type: reader.uint(1), unsigned: (reader.uint(1) & 128) !== 0 }));
+    else if (fresh !== 0)
+        throw new MysqlError('Invalid parameter bind flag', 1835);
+    if (!statement.types)
+        throw new MysqlError('Parameter types were not bound', 2031, 'HY000');
+    return statement.types.map(({ type, unsigned }, i) => {
+        if ((nulls[Math.floor(i / 8)] & (1 << (i % 8))) || type === 6)
+            return 'NULL';
+        const width = type === 1 ? 1 : type === 2 || type === 13 ? 2 : type === 3 || type === 9 ? 4 : 0;
+        if (width) {
+            const bytes = reader.bytes(width);
+            return String(unsigned ? bytes.readUIntLE(0, width) : bytes.readIntLE(0, width));
+        }
+        if (type === 8) {
+            const bytes = reader.bytes(8);
+            return String(unsigned ? bytes.readBigUInt64LE() : bytes.readBigInt64LE());
+        }
+        if (type === 4 || type === 5) {
+            const bytes = reader.bytes(type === 4 ? 4 : 8);
+            const value = type === 4 ? bytes.readFloatLE() : bytes.readDoubleLE();
+            if (!Number.isFinite(value))
+                throw new MysqlError('Non-finite parameter', 1366);
+            return String(value);
+        }
+        if ([7, 10, 11, 12].includes(type))
+            return dateValue(reader, type);
+        if ([0, 15, 16, 245, 246, 249, 250, 251, 252, 253, 254].includes(type))
+            return quote(reader.str());
+        throw new MysqlError(`Parameter type ${type} is not supported`);
+    });
+}
+function binaryCell(field, bytes) {
+    const type = TYPES[field.type ?? 'NULL_TYPE'] ?? 253;
+    const text = bytes.toString();
+    const unsigned = ((field.flags ?? 0) & 32) !== 0;
+    const width = type === 1 ? 1 : type === 2 || type === 13 ? 2 : type === 3 || type === 9 ? 4 : 0;
+    if (width) {
+        const out = Buffer.alloc(width);
+        if (unsigned)
+            out.writeUIntLE(Number(text), 0, width);
+        else
+            out.writeIntLE(Number(text), 0, width);
+        return out;
+    }
+    if (type === 8)
+        return integer(BigInt(text), 8);
+    if (type === 4 || type === 5) {
+        const out = Buffer.alloc(type === 4 ? 4 : 8);
+        if (type === 4)
+            out.writeFloatLE(Number(text));
+        else
+            out.writeDoubleLE(Number(text));
+        return out;
+    }
+    if ([7, 10, 12].includes(type)) {
+        const parts = text.match(/^(\d{4})-(\d\d)-(\d\d)(?:[ T](\d\d):(\d\d):(\d\d)(?:\.(\d+))?)?/);
+        if (!parts)
+            throw new MysqlError('Invalid stored datetime', 1292, '22007');
+        const values = parts.slice(1, 7).map((part) => Number(part ?? 0));
+        const micro = Number((parts[7] ?? '').padEnd(6, '0').slice(0, 6));
+        return Buffer.concat([Buffer.from([type === 10 ? 4 : 11]), integer(values[0], 2), Buffer.from(values.slice(1, 3)),
+            ...(type === 10 ? [] : [Buffer.from(values.slice(3)), integer(micro, 4)])]);
+    }
+    if (type === 11)
+        throw new MysqlError('Binary TIME results are not modeled');
+    return string(bytes);
+}
+export function createPlanetscaleMysqlStream(options) {
+    const authorization = options.authorization ?? `Basic ${Buffer.from(`${options.username || 'twin'}:${options.password || 'twin'}`).toString('base64')}`;
+    let connectionId = 0;
+    return (socket) => {
+        let buffer = Buffer.alloc(0);
+        let sequence = 0;
+        let authenticated = false;
+        let closing = false;
+        let gone = false;
+        let session;
+        let autocommit = true;
+        let queue = Promise.resolve();
+        let queued = 0;
+        let nextStatement = 0;
+        const statements = new Map();
+        let longData;
+        const salt = randomBytes(20);
+        const end = () => { if (!gone) {
+            gone = true;
+            socket.end();
+        } };
+        const inTransaction = () => session?.vitessSession.inTransaction === true;
+        const status = () => (autocommit ? 2 : 0) | (inTransaction() ? 1 : 0);
+        const send = (payload) => {
+            if (payload.length > MAX_PACKET)
+                throw new MysqlError('Result packet too large', 1153, '08S01');
+            socket.write(Buffer.concat([integer(payload.length, 3), integer(sequence++ % 256, 1), payload]));
+        };
+        const ok = (rows = 0, insert = 0) => send(Buffer.concat([Buffer.from([0]), length(rows), length(insert), integer(status(), 2), integer(0, 2)]));
+        const eof = () => send(Buffer.concat([Buffer.from([254]), integer(0, 2), integer(status(), 2)]));
+        const fail = (error) => {
+            // A statement the frontend parses itself (a prepare) fails with the engine's own errno.
+            const e = error instanceof MysqlError ? error : error instanceof SqlError ? new MysqlError(error.message, error.errno, error.sqlState) : new MysqlError(String(error), 1105, 'HY000');
+            send(Buffer.concat([Buffer.from([255]), integer(e.errno, 2), Buffer.from(`#${e.state}${e.message}`)]));
+        };
+        const rpc = async (method, body) => {
+            const response = await options.upstream(new Request(`http://twin/psdb.v1alpha1.Database/${method}`, {
+                method: 'POST', headers: { authorization, 'content-type': 'application/json' }, body: JSON.stringify(body), signal: AbortSignal.timeout(30000),
+            }));
+            const data = await response.json();
+            const returned = data.session;
+            if (returned && session && returned.vitessSession.sessionUUID !== session.vitessSession.sessionUUID) {
+                // The upstream twin no longer knows this session (it restarted or the session was closed):
+                // it minted a fresh one, so any buffered transaction is gone. A real server would have
+                // dropped the connection; do the same rather than continue on a silently different session.
+                session = undefined;
+                end();
+                throw new MysqlError('Lost connection to the PlanetScale twin during query: the upstream session was replaced', 2013, 'HY000');
+            }
+            if (returned)
+                session = returned;
+            const error = data.error;
+            if (!response.ok || error) {
+                const message = error?.message ?? String(data.message ?? `HTTP ${response.status}`);
+                throw new MysqlError(message, Number(message.match(/errno (\d+)/)?.[1] ?? 1105), message.match(/sqlstate ([A-Z0-9]+)/)?.[1] ?? 'HY000');
+            }
+            return data;
+        };
+        const normalize = (query) => {
+            // The engine's own system variables (the psdb wire reads the same table), with this
+            // connection's autocommit state.
+            const variables = Object.fromEntries(Object.entries({ ...SYSTEM_VARIABLES, max_allowed_packet: MAX_PACKET, autocommit: autocommit ? 1 : 0 })
+                .map(([k, v]) => [k, typeof v === 'number' ? String(v) : `'${String(v).replace(/'/g, "''")}'`]));
+            let out = query;
+            const tokens = tokenize(query);
+            for (let i = tokens.length - 1; i >= 0; i--) {
+                const token = tokens[i];
+                if (token.kind !== 'ident' || !token.value.startsWith('@@'))
+                    continue;
+                let name = token.value.slice(2).toLowerCase();
+                let end = token.pos - 1 + token.value.length;
+                // @@session.x / @@global.x / @@local.x: the tokenizer yields the scope, a '.', then the name.
+                const scoped = ['session', 'global', 'local'].includes(name) && tokens[i + 1]?.kind === 'punct' && tokens[i + 1].value === '.' && tokens[i + 2]?.kind === 'ident';
+                if (scoped) {
+                    const target = tokens[i + 2];
+                    name = target.value.toLowerCase();
+                    end = target.pos - 1 + target.value.length;
+                }
+                if (!(name in variables))
+                    throw new MysqlError(`Unknown system variable '${name}'`, 1193, 'HY000');
+                out = out.slice(0, token.pos - 1) + variables[name] + out.slice(end);
+            }
+            return out;
+        };
+        const execute = async (query) => {
+            options.onQuery?.(query);
+            // Connection encoding is UTF-8. Other session settings stay loud instead of being no-ops.
+            if (/^SET NAMES (?:utf8mb4|utf8)\s*;?$/i.test(query.trim()))
+                return {};
+            const auto = query.trim().match(/^SET (?:@@(?:session\.)?)?autocommit\s*=\s*([01])\s*;?$/i);
+            if (auto) {
+                if (auto[1] === '1' && inTransaction())
+                    await rpc('Execute', { query: 'COMMIT', session });
+                autocommit = auto[1] === '1';
+                return {};
+            }
+            if (!autocommit && !inTransaction() && !/^\s*(?:BEGIN|START TRANSACTION|COMMIT|ROLLBACK)\b/i.test(query))
+                await rpc('Execute', { query: 'BEGIN', session });
+            return read(query);
+        };
+        // A statement run for its result only: no autocommit bookkeeping (MySQL opens no transaction
+        // on a prepare), so the prepare probe below cannot start one.
+        const read = async (query) => (await rpc('Execute', { query: normalize(query), session })).result ?? {};
+        const result = (value, binary) => {
+            const fields = value.fields ?? [];
+            if (!fields.length) {
+                ok(Number(value.rowsAffected ?? 0), Number(value.insertId ?? 0));
+                return;
+            }
+            send(length(fields.length));
+            fields.forEach((field) => send(column(field)));
+            eof();
+            for (const row of value.rows ?? []) {
+                const data = Buffer.from(row.values ?? '', 'base64');
+                let offset = 0;
+                const nulls = Buffer.alloc(Math.ceil((fields.length + 2) / 8));
+                const values = row.lengths.map((n, i) => {
+                    const count = Number(n);
+                    if (count < 0) {
+                        nulls[Math.floor((i + 2) / 8)] |= 1 << ((i + 2) % 8);
+                        return binary ? Buffer.alloc(0) : Buffer.from([251]);
+                    }
+                    const bytes = data.subarray(offset, offset + count);
+                    offset += count;
+                    return binary ? binaryCell(fields[i], bytes) : string(bytes);
+                });
+                send(Buffer.concat(binary ? [Buffer.from([0]), nulls, ...values] : values));
+            }
+            eof();
+        };
+        const closeSession = async () => { if (session) {
+            try {
+                await rpc('CloseSession', { session });
+            }
+            finally {
+                session = undefined;
+            }
+        } };
+        const handshake = Buffer.concat([Buffer.from([10]), Buffer.from(`${SERVER_VERSION}\0`), integer(++connectionId, 4), salt.subarray(0, 8), Buffer.from([0]),
+            integer(CAPABILITIES & 65535, 2), Buffer.from([45]), integer(2, 2), integer(CAPABILITIES >>> 16, 2), Buffer.from([21]), Buffer.alloc(10), salt.subarray(8), Buffer.from('\0mysql_native_password\0')]);
+        send(handshake);
+        const command = async (payload, incomingSequence) => {
+            sequence = (incomingSequence + 1) % 256;
+            const r = new Reader(payload);
+            if (!authenticated) {
+                const capabilities = r.uint(4);
+                r.bytes(4);
+                const charset = r.uint(1);
+                r.bytes(23);
+                if ((capabilities & 512) === 0 || ![33, 45, 46, 224, 255].includes(charset))
+                    throw new MysqlError('Unsupported handshake or character set', 1047, '08S01');
+                const username = r.zero();
+                const auth = capabilities & 32768 ? r.bytes(r.uint(1)) : Buffer.from(r.zero(), 'binary');
+                const database = capabilities & 8 ? r.zero() : '';
+                if (!username || !auth.length || options.username && username !== options.username)
+                    throw new MysqlError('Access denied', 1045, '28000');
+                if (options.password) {
+                    const sha = (bytes) => createHash('sha1').update(bytes).digest();
+                    const first = sha(Buffer.from(options.password));
+                    const scramble = sha(Buffer.concat([salt, sha(first)]));
+                    const expected = Buffer.from(first.map((byte, i) => byte ^ scramble[i]));
+                    if (auth.length !== expected.length || !timingSafeEqual(auth, expected))
+                        throw new MysqlError('Access denied', 1045, '28000');
+                }
+                if (options.database && database && database !== options.database)
+                    throw new MysqlError(`Unknown database '${database}'`, 1049, '42000');
+                await rpc('CreateSession', {});
+                authenticated = true;
+                ok();
+                return;
+            }
+            const op = r.uint(1);
+            if (op === 1) {
+                closing = true;
+                await closeSession();
+                end();
+                return;
+            }
+            if (op === 14) {
+                ok();
+                return;
+            }
+            if (op === 2) {
+                const database = payload.subarray(1).toString();
+                if (options.database && database !== options.database)
+                    throw new MysqlError(`Unknown database '${database}'`, 1049);
+                ok();
+                return;
+            }
+            if (op === 3) {
+                result(await execute(payload.subarray(1).toString()), false);
+                return;
+            }
+            if (op === 22) {
+                if (statements.size >= MAX_STATEMENTS)
+                    throw new MysqlError('Too many prepared statements', 1461);
+                const sql = payload.subarray(1).toString();
+                const positions = mysqlPlaceholders(sql);
+                const probe = normalize(bind(sql, positions, positions.map(() => '0')));
+                const parsed = parseStatement(probe);
+                const fields = parsed.kind === 'select' ? (await read(probe)).fields ?? [] : [];
+                const id = ++nextStatement;
+                statements.set(id, { sql, positions });
+                send(Buffer.concat([Buffer.from([0]), integer(id, 4), integer(fields.length, 2), integer(positions.length, 2), Buffer.from([0]), integer(0, 2)]));
+                positions.forEach(() => send(column({ name: '?', type: 'VARCHAR' })));
+                if (positions.length)
+                    eof();
+                fields.forEach((field) => send(column(field)));
+                if (fields.length)
+                    eof();
+                return;
+            }
+            if (op === 25) {
+                statements.delete(r.uint(4));
+                return;
+            }
+            if (op === 26) {
+                const statement = statements.get(r.uint(4));
+                if (!statement)
+                    throw new MysqlError('Unknown prepared statement', 1243);
+                statement.types = undefined;
+                ok();
+                return;
+            }
+            if (op === 24) {
+                longData = new MysqlError('COM_STMT_SEND_LONG_DATA is not modeled');
+                return;
+            } // the protocol defines no reply; the next execute answers
+            if (op === 23) {
+                if (longData) {
+                    const error = longData;
+                    longData = undefined;
+                    throw error;
+                }
+                const statement = statements.get(r.uint(4));
+                if (!statement)
+                    throw new MysqlError('Unknown prepared statement', 1243);
+                if (r.uint(1) !== 0 || r.uint(4) !== 1)
+                    throw new MysqlError('Prepared cursors/iterations are not modeled');
+                const values = parameters(r, statement); // mysql2 reserves allocation padding for NULL parameters; it is not another parameter.
+                result(await execute(bind(statement.sql, statement.positions, values)), true);
+                return;
+            }
+            throw new MysqlError(`MySQL command ${op} is not modeled`, 1047, '08S01');
+        };
+        const connection = {
+            settled: () => queue,
+            data(bytes) {
+                if (closing || gone)
+                    return;
+                buffer = Buffer.concat([buffer, Buffer.from(bytes)]);
+                if (buffer.length > MAX_PACKET + 4) {
+                    closing = true;
+                    end();
+                    return;
+                }
+                while (buffer.length >= 4) {
+                    const size = buffer.readUIntLE(0, 3);
+                    if (size > MAX_PACKET || ++queued > 64) {
+                        closing = true;
+                        end();
+                        return;
+                    }
+                    if (buffer.length < size + 4) {
+                        queued--;
+                        break;
+                    }
+                    const seq = buffer[3];
+                    const payload = Buffer.from(buffer.subarray(4, size + 4));
+                    buffer = buffer.subarray(size + 4);
+                    queue = queue.then(async () => { if (!closing)
+                        await command(payload, seq); }).catch((error) => { if (!gone)
+                        fail(error); if (!authenticated)
+                        end(); }).finally(() => { queued--; });
+                }
+            },
+            close() {
+                closing = true;
+                gone = true;
+                queue = queue.then(closeSession).catch(() => { });
+            },
+        };
+        return connection;
+    };
+}
+export async function startPlanetscaleMysql(options) {
+    const { createServer } = await import('node:net');
+    const upstream = new URL(options.upstream);
+    if (!['http:', 'https:'].includes(upstream.protocol) || !['127.0.0.1', 'localhost', '[::1]'].includes(upstream.hostname))
+        throw new Error('PlanetScale native frontend requires a local HTTP twin URL');
+    const authorization = `Basic ${Buffer.from(`${decodeURIComponent(upstream.username) || options.username || 'twin'}:${decodeURIComponent(upstream.password) || options.password || 'twin'}`).toString('base64')}`;
+    upstream.username = '';
+    upstream.password = '';
+    const stream = createPlanetscaleMysqlStream({
+        upstream: async (request) => fetch(new URL(new URL(request.url).pathname, upstream), { method: request.method, headers: request.headers, body: await request.text(), signal: request.signal }),
+        authorization,
+        ...(options.database !== undefined ? { database: options.database } : {}),
+        ...(options.username !== undefined ? { username: options.username } : {}),
+        ...(options.password !== undefined ? { password: options.password } : {}),
+        ...(options.onQuery ? { onQuery: options.onQuery } : {}),
+    });
+    const connections = new Map();
+    const pending = new Set();
+    const server = createServer((socket) => {
+        socket.setTimeout(28_800_000, () => socket.destroy());
+        const connection = stream({ write: (bytes) => { if (!socket.destroyed)
+                socket.write(bytes); }, end: () => { socket.end(); } }, socket.remoteAddress ?? '');
+        connections.set(socket, connection);
+        socket.on('data', (chunk) => connection.data(chunk));
+        socket.on('error', () => { socket.destroy(); });
+        socket.on('close', () => {
+            connections.delete(socket);
+            connection.close();
+            const cleanup = connection.settled();
+            pending.add(cleanup);
+            void cleanup.finally(() => pending.delete(cleanup));
+        });
+    });
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(options.port ?? 0, '127.0.0.1', () => { server.off('error', reject); resolve(); }); });
+    return { port: server.address().port, stop: async () => {
+            await new Promise((resolve, reject) => { server.close((error) => error ? reject(error) : resolve()); for (const socket of connections.keys())
+                socket.destroy(); });
+            await Promise.all([...pending]);
+        } };
+}
+/** The MySQL wire a hosted World serves on its stream door: answered by the twin's own wire, whose
+ *  World token already admitted the stream. */
+export function createPlanetscaleTwinStream(options) {
+    return createPlanetscaleMysqlStream({ upstream: options.wire });
+}

package/dist/src/planetscale-roles.d.ts

@@ -0,0 +1,11 @@
+import { SqlError, type Statement } from './planetscale-sql.js';
+export type PasswordRole = 'reader' | 'writer' | 'readwriter' | 'admin';
+/** Whether a statement changes schema: what a branch with safe migrations refuses. */
+export declare const isDdl: (stmt: Statement) => boolean;
+/** A branch with safe migrations refuses DDL: "You'll see a `ERROR 1105 (HY000): direct DDL is disabled` message if you
+ *  attempt to make schema changes in a branch with safe migrations enabled"
+ *  (https://planetscale.com/docs/vitess/schema-changes/branching). Where the page stops: the message as the HTTP driver
+ *  reports it; the twin answers the page's errno, SQLSTATE and words. */
+export declare const directDdlDisabled: () => SqlError;
+/** The refusal a role gives a statement, or undefined when the role allows it. */
+export declare function roleRefusal(role: PasswordRole, stmt: Statement): SqlError | undefined;

package/dist/src/planetscale-roles.js

@@ -0,0 +1,60 @@
+// A branch password's ROLE, enforced on the psdb data plane. The management lane (api/) issues passwords with a role;
+// psdb authenticates a Basic credential against them and refuses what the role does not allow.
+//
+// PlanetScale's password-roles page (https://planetscale.com/docs/vitess/connecting/password-roles): Read-only "Can query
+// rows", Write-only "Can modify rows", Read/write "Can query and modify rows", Admin "All read/write permissions and can
+// modify schema"; its permissions table gives schema changes to Admin alone, inserts, updates and deletes to every role
+// but Read-only, and queries to every role but Write-only. Its examples of the refusal, verbatim:
+//   "Select command denied to user 'planetscale-writer-only for table 'customers' (ACL check error)"
+//   "Insert command denied to user 'planetscale-reader' for table 'customers' (ACL check error)"
+//   "Delete command denied to user 'planetscale-reader' for table 'customers' (ACL check error)"
+//   "DDL command denied to user 'planetscale-writer' for table my-new-table' (ACL check error)"
+// so the user a refusal names is the role's (reader: planetscale-reader, writer: planetscale-writer-only, readwriter:
+// planetscale-writer; admin is refused nothing), never the password's username.
+//
+// Where the page stops: it gives no errno or code. The message is MySQL 8.0's ER_TABLEACCESS_DENIED_ERROR, "%s command
+// denied to user '%s'@'%s' for table '%s'", errno 1142, SQLSTATE 42000 (dev.mysql.com, server error reference), so the
+// refusal takes that errno and SQLSTATE, and Vitess's PERMISSION_DENIED code. The twin judges a statement by its kind and
+// the table it names first (a subquery an UPDATE reads is not judged as a query); a statement naming no table (`SELECT 1`,
+// `SHOW TABLES`, BEGIN) and a read of INFORMATION_SCHEMA are allowed to every role.
+import { SqlError } from "./planetscale-sql.js";
+const ROLE_USER = { reader: 'planetscale-reader', writer: 'planetscale-writer-only', readwriter: 'planetscale-writer' };
+const ALLOWED = {
+    reader: new Set(['Select']),
+    writer: new Set(['Insert', 'Update', 'Delete']),
+    readwriter: new Set(['Select', 'Insert', 'Update', 'Delete']),
+    admin: new Set(['Select', 'Insert', 'Update', 'Delete', 'DDL']),
+};
+const baseTable = (factor) => factor && 'table' in factor && factor.schema?.toLowerCase() !== 'information_schema' ? factor.table : undefined;
+/** The command a statement is and the table it names first, or undefined for one no role is refused. */
+function commandOf(stmt) {
+    if (stmt.kind === 'select' || stmt.kind === 'update-multi') {
+        const t = baseTable(stmt.from?.[0]?.factor);
+        return t === undefined ? undefined : { command: stmt.kind === 'select' ? 'Select' : 'Update', table: t };
+    }
+    const command = TABLE_COMMAND[stmt.kind];
+    return command === undefined || !('table' in stmt) ? undefined : { command, table: stmt.table };
+}
+/** The command each single-table statement is, by kind. */
+const TABLE_COMMAND = {
+    describe: 'Select', 'show-create-table': 'Select', insert: 'Insert', update: 'Update', delete: 'Delete',
+    'create-table': 'DDL', 'create-table-select': 'DDL', 'drop-table': 'DDL', truncate: 'DDL', 'alter-add-columns': 'DDL', 'alter-drop-columns': 'DDL',
+};
+/** Whether a statement changes schema: what a branch with safe migrations refuses. */
+export const isDdl = (stmt) => TABLE_COMMAND[stmt.kind] === 'DDL';
+/** A branch with safe migrations refuses DDL: "You'll see a `ERROR 1105 (HY000): direct DDL is disabled` message if you
+ *  attempt to make schema changes in a branch with safe migrations enabled"
+ *  (https://planetscale.com/docs/vitess/schema-changes/branching). Where the page stops: the message as the HTTP driver
+ *  reports it; the twin answers the page's errno, SQLSTATE and words. */
+export const directDdlDisabled = () => new SqlError('direct DDL is disabled', 'FAILED_PRECONDITION', 1105, 'HY000');
+/** The refusal a role gives a statement, or undefined when the role allows it. */
+export function roleRefusal(role, stmt) {
+    if (role === 'admin')
+        return undefined;
+    const c = commandOf(stmt);
+    return c === undefined || ALLOWED[role].has(c.command) ? undefined : commandDenied(role, c);
+}
+/** MySQL's ER_TABLEACCESS_DENIED_ERROR (1142), as the password-roles page prints it. */
+function commandDenied(role, c) {
+    return new SqlError(`${c.command} command denied to user '${ROLE_USER[role]}' for table '${c.table}' (ACL check error)`, 'PERMISSION_DENIED', 1142, '42000');
+}

package/dist/src/planetscale-row.d.ts

@@ -0,0 +1,12 @@
+import { type Cell } from './planetscale-sql.js';
+export declare function pulledRowId(table: string, identity: string[], ordinal?: number): number;
+export declare function keyedRowIdentity(table: {
+    name: string;
+    primaryKey: string[];
+}, cells: Record<string, Cell>): string[];
+export declare function quoteSqlLiteral(value: Cell): string;
+export declare const quoteIdent: (name: string) => string;
+export declare function keyedRowId(table: {
+    name: string;
+    primaryKey: string[];
+}, cells: Record<string, Cell>): number;