@kazurolabs/psql-explorer 0.0.0-stage → 0.3.0

package/dist/web/server.js

@@ -0,0 +1,988 @@
+// The HTTP server behind `psql-explorer web`: a small JSON API over the same services the TUI and
+// the commands use, plus the built web UI (web/dist). It only listens on the loopback interface
+// and refuses requests whose Host is not loopback, so a web page cannot reach it by DNS rebinding.
+import { spawn } from 'node:child_process';
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { extname, join, normalize, resolve, sep } from 'node:path';
+import { ResolveError } from '../config/resolvers/index.js';
+import { addressOf, findEnvironment, forgetAnswers, listEnvironments } from '../environments.js';
+import { connectEntries, LoginError } from '../explorer/connect-entry.js';
+import { describeCatalog, describeFunctionCatalog, describeErd, describeFunction, describeRelation, describeSequence, describeType, listColumns, listObjects, listSchemas, serverInfo, } from '../explorer/catalog.js';
+import { applyEdit, buildEdit, EditError } from '../explorer/edit.js';
+import { listDependents } from '../explorer/dependents.js';
+import { describeFunctionSecurity, describeSecurity, listRoles } from '../explorer/security.js';
+import { explainAnalyze, explainQuery } from '../explorer/explain.js';
+import { browseRows, browseSql, canExport, EXPORT_MAX_ROWS, exportRows, runPage, } from '../explorer/rows.js';
+import { buildWhere, FilterError, parseFilters } from '../explorer/filter.js';
+import { buildGraph, expandNode, GraphError, parseExpandRequest, parseGraphRequest, } from '../explorer/graph.js';
+import { CypherError, parseCypherRequest, runCypher } from '../explorer/cypher.js';
+import { profileColumn } from '../explorer/profile.js';
+import { countReferences, listForeignKeys, listSchemaForeignKeys } from '../explorer/references.js';
+import { buildSearchIndex, searchValues } from '../explorer/search.js';
+import { describeSeedColumns, generators, MAX_SEED_ROWS, parseSeedRequest, previewSeed, runSeed, SeedError, seedLocales, } from '../explorer/seed.js';
+import { compareSchemas } from '../explorer/schema-diff.js';
+import { AlterError, diffDesigns, dropTableStatement, parseAlterOptions, splitPlan, } from '../explorer/alter.js';
+import { buildDdl, DdlError, parseTableDesign } from '../explorer/ddl.js';
+import { DesignRunError, runPlan, runStatements } from '../explorer/design.js';
+import { loadDesign } from '../explorer/design-load.js';
+import { describeQueryError } from '../explorer/session.js';
+import { applyGucs, GucError, parseGucs } from '../explorer/gucs.js';
+import { databaseStats, listIndexStats, listTableStats } from '../explorer/stats.js';
+export const DEFAULT_WEB_PORT = 7878;
+const MAX_BODY_BYTES = 1_000_000;
+// Editing a row can carry a dropped file: up to 20 MB of it, written as hex.
+const MAX_EDIT_BODY_BYTES = 48_000_000;
+// Connections a value search reads tables on at once.
+const SEARCH_CONNECTIONS = 4;
+const contentTypes = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.ico': 'image/x-icon',
+    '.woff2': 'font/woff2',
+};
+/** A request that cannot be answered as sent: the status says why. */
+class HttpError extends Error {
+    status;
+    extra;
+    constructor(status, message, 
+    // More to send along with the message, e.g. which statement failed.
+    extra = {}) {
+        super(message);
+        this.status = status;
+        this.extra = extra;
+    }
+}
+const sendJson = (res, status, body) => {
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+    res.end(JSON.stringify(body));
+};
+const requiredParam = (url, key) => {
+    const value = url.searchParams.get(key);
+    if (!value)
+        throw new HttpError(400, `${url.pathname.split('/').pop()} needs ?${key}=`);
+    return value;
+};
+/** A query parameter holding JSON, e.g. the filters of the row grid; undefined when absent. */
+const jsonParam = (url, key) => {
+    const text = url.searchParams.get(key);
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new HttpError(400, `${key} is not valid JSON`);
+    }
+};
+const parseSort = (raw) => {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        throw new HttpError(400, 'sort is a list of {column, descending}');
+    return raw.slice(0, 10).map((item) => {
+        if (typeof item?.column !== 'string')
+            throw new HttpError(400, 'sort is a list of {column, descending}');
+        return { column: item.column, descending: item.descending === true };
+    });
+};
+/** A saved query's name: what was typed, or else the start of the statement. */
+const savedName = (given, sql) => {
+    const text = typeof given === 'string' ? given.trim() : '';
+    return (text || sql.trim().replace(/\s+/g, ' ')).slice(0, 80);
+};
+const isLoopbackHost = (host) => {
+    if (!host)
+        return false;
+    const name = host.startsWith('[') ? host.slice(0, host.indexOf(']') + 1) : host.split(':')[0];
+    return name === 'localhost' || name === '127.0.0.1' || name === '[::1]';
+};
+async function readJson(req, maxBytes = MAX_BODY_BYTES) {
+    if (!req.headers['content-type']?.startsWith('application/json')) {
+        throw new HttpError(415, 'send application/json');
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > maxBytes)
+            throw new HttpError(413, 'request body is too large');
+        chunks.push(chunk);
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        throw new HttpError(400, 'the body is not valid JSON');
+    }
+}
+export function createWebServer(options) {
+    const { services } = options;
+    const staticDir = options.staticDir ? resolve(options.staticDir) : undefined;
+    const environmentNamed = (name) => {
+        const entry = findEnvironment(services, name);
+        if (!entry)
+            throw new HttpError(404, `you do not have access to "${name}": it is not in your config`);
+        return entry;
+    };
+    // Protected environments the person has switched to read write, by entry key. In memory only, so
+    // a restart is read only again.
+    const writable = new Set();
+    // Opens up to `count` connections with one lookup of the credentials (one Vault read, one
+    // prompt), so queries can run side by side. Nothing is kept between requests: the next request
+    // looks everything up again, so a changed password is never held onto.
+    async function withSessions(name, count, work, signal) {
+        const entry = environmentNamed(name);
+        let sessions;
+        try {
+            sessions = await connectEntries(entry, services, count, {
+                signal,
+                ...(writable.has(entry.key) ? { readOnly: false } : {}),
+            });
+        }
+        catch (error) {
+            // What was typed was refused, so ask again next time instead of remembering it.
+            if (error instanceof LoginError)
+                forgetAnswers(entry, services);
+            throw error;
+        }
+        // A request the browser gave up on (Cancel, or a closed page) stops its statements on the server.
+        const stop = () => void Promise.all(sessions.map((session) => session.cancel()));
+        signal?.addEventListener('abort', stop);
+        try {
+            return await work(sessions);
+        }
+        finally {
+            signal?.removeEventListener('abort', stop);
+            await Promise.all(sessions.map((session) => session.close().catch(() => undefined)));
+        }
+    }
+    const withSession = (name, work, signal) => withSessions(name, 1, ([session]) => work(session), signal);
+    async function api(req, url, signal) {
+        const withSessionFor = (name, work) => withSession(name, work, signal);
+        const withSessionsFor = (name, count, work) => withSessions(name, count, work, signal);
+        const parts = url.pathname.split('/').slice(2).map(decodeURIComponent);
+        const [resource, name, sub, id] = parts;
+        if (resource === 'prompt' && !name && req.method === 'GET') {
+            const pending = services.prompts?.current();
+            return {
+                prompt: pending
+                    ? {
+                        envName: pending.envName,
+                        field: pending.field,
+                        masked: pending.masked,
+                        ...(pending.challenge === undefined ? {} : { challenge: pending.challenge }),
+                    }
+                    : null,
+            };
+        }
+        if (resource === 'prompt' && !name && req.method === 'POST') {
+            const body = (await readJson(req));
+            const pending = services.prompts?.current();
+            // The question may have been answered elsewhere since the page last looked.
+            if (!pending || pending.envName !== body?.envName || pending.field !== body?.field) {
+                throw new HttpError(409, 'that question is no longer waiting for an answer');
+            }
+            if (body.value === null)
+                pending.cancel();
+            else if (typeof body.value === 'string' && body.value !== '')
+                pending.submit(body.value);
+            else
+                throw new HttpError(400, 'send {"value": "..."} or {"value": null} to cancel');
+            return {};
+        }
+        if (resource === 'envs' && !name && req.method === 'GET') {
+            return {
+                environments: listEnvironments(services).map((entry) => ({
+                    name: entry.name,
+                    source: entry.source,
+                    tier: entry.tier,
+                    protected: entry.protected,
+                    readOnly: entry.readOnly,
+                    seeder: entry.seeder,
+                    designer: entry.designer,
+                    address: addressOf(entry),
+                    tls: entry.tlsMode,
+                })),
+                error: services.configError?.message,
+            };
+        }
+        if (resource === 'envs' && name && sub === 'write' && (req.method === 'GET' || req.method === 'POST')) {
+            const entry = environmentNamed(name);
+            // Only a protected environment that is read only has anything to switch.
+            const available = entry.protected && entry.readOnly;
+            if (req.method === 'POST') {
+                const body = (await readJson(req));
+                if (typeof body?.enabled !== 'boolean')
+                    throw new HttpError(400, 'send {"enabled": true|false}');
+                if (!available)
+                    throw new HttpError(400, `${entry.name} is not a protected read only environment`);
+                if (!body.enabled)
+                    writable.delete(entry.key);
+                else if (!writable.has(entry.key)) {
+                    // Always asked, whatever `confirm` says: this is the step that allows changing data.
+                    const prompt = services.resolvers.get('prompt');
+                    if (!prompt)
+                        throw new HttpError(400, 'there is no way to ask for confirmation');
+                    try {
+                        await prompt.confirm({ envName: entry.name, interactive: true, signal, purpose: 'write' });
+                    }
+                    catch (error) {
+                        if (error instanceof ResolveError)
+                            throw new HttpError(400, error.message);
+                        throw error;
+                    }
+                    writable.add(entry.key);
+                }
+            }
+            return { available, enabled: writable.has(entry.key) };
+        }
+        if (resource === 'envs' && name && sub === 'schemas' && req.method === 'GET') {
+            return withSessionFor(name, (session) => listSchemas(session));
+        }
+        if (resource === 'envs' && name && sub === 'erd' && req.method === 'GET') {
+            const schema = requiredParam(url, 'schema');
+            return withSessionFor(name, (session) => describeErd(session, schema));
+        }
+        if (resource === 'envs' && name && sub === 'catalog' && req.method === 'GET') {
+            return withSessionFor(name, (session) => describeCatalog(session));
+        }
+        if (resource === 'envs' && name && sub === 'functions' && req.method === 'GET') {
+            return withSessionFor(name, (session) => describeFunctionCatalog(session));
+        }
+        if (resource === 'envs' && name && sub === 'search-index' && req.method === 'GET') {
+            return withSessionFor(name, (session) => buildSearchIndex(session));
+        }
+        if (resource === 'envs' && name && sub === 'find' && req.method === 'GET') {
+            const text = requiredParam(url, 'q').trim();
+            if (!text)
+                throw new HttpError(400, 'find needs ?q=');
+            const schema = url.searchParams.get('schema') || undefined;
+            try {
+                return await withSessionsFor(name, SEARCH_CONNECTIONS, (sessions) => searchValues(sessions, { text, ...(schema ? { schema } : {}) }));
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' && name && sub === 'info' && req.method === 'GET') {
+            return withSessionFor(name, (session) => serverInfo(session));
+        }
+        if (resource === 'envs' && name && sub === 'stats' && req.method === 'GET') {
+            const schema = url.searchParams.get('schema');
+            const table = url.searchParams.get('table');
+            if (!schema || !table)
+                return withSessionFor(name, (session) => databaseStats(session));
+            const ref = { schema, name: table };
+            const found = await withSessionFor(name, async (session) => {
+                const [stats] = await listTableStats(session, ref).catch(() => []);
+                return stats && { table: stats, indexes: await listIndexStats(session, ref) };
+            });
+            if (!found)
+                throw new HttpError(404, `no table ${schema}.${table}`);
+            return found;
+        }
+        if (resource === 'envs' && name && sub === 'schema-diff' && req.method === 'GET') {
+            const other = requiredParam(url, 'with');
+            const schema = url.searchParams.get('schema') || undefined;
+            const withSchema = url.searchParams.get('withSchema') || undefined;
+            environmentNamed(other);
+            try {
+                return await withSessionFor(name, (session) => withSession(other, (otherSession) => compareSchemas(session, otherSession, { schema, withSchema }), signal));
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' && name && sub === 'dependents' && req.method === 'GET') {
+            const kind = requiredParam(url, 'kind');
+            const schema = requiredParam(url, 'schema');
+            const object = requiredParam(url, 'name');
+            let target;
+            if (kind === 'function') {
+                target = { kind, schema, name: object, args: url.searchParams.get('args') ?? '' };
+            }
+            else if (kind === 'table' || kind === 'sequence' || kind === 'type') {
+                target = { kind, schema, name: object };
+            }
+            else if (kind === 'column' || kind === 'constraint') {
+                target = { kind, schema, table: requiredParam(url, 'table'), name: object };
+            }
+            else if (kind === 'index') {
+                target = { kind, schema, name: object };
+            }
+            else
+                throw new HttpError(400, `unknown kind "${kind}"`);
+            const found = await withSessionFor(name, (session) => listDependents(session, target));
+            if (!found)
+                throw new HttpError(404, `no ${kind} ${schema}.${object}`);
+            return found;
+        }
+        if (resource === 'envs' && name && sub === 'security' && req.method === 'GET') {
+            const schema = requiredParam(url, 'schema');
+            const table = requiredParam(url, 'name');
+            const args = url.searchParams.get('args');
+            const found = await withSessionFor(name, (session) => args === null
+                ? describeSecurity(session, { schema, name: table })
+                : describeFunctionSecurity(session, { schema, name: table, args }));
+            if (!found)
+                throw new HttpError(404, `no ${args === null ? 'table' : 'function'} ${schema}.${table}`);
+            return found;
+        }
+        if (resource === 'envs' && name && sub === 'roles' && req.method === 'GET') {
+            // Not every role may read the catalog of roles; the page then just has none to show.
+            return withSessionFor(name, (session) => listRoles(session).then((roles) => ({ roles, available: true }), () => ({ roles: [], available: false })));
+        }
+        if (resource === 'envs' && name && sub === 'objects' && req.method === 'GET') {
+            const schema = requiredParam(url, 'schema');
+            return withSessionFor(name, (session) => listObjects(session, schema));
+        }
+        if (resource === 'envs' && name && sub === 'object' && req.method === 'GET') {
+            const schema = requiredParam(url, 'schema');
+            const object = requiredParam(url, 'name');
+            const kind = requiredParam(url, 'kind');
+            const found = await withSessionFor(name, (session) => {
+                if (kind === 'table')
+                    return describeRelation(session, { schema, name: object });
+                if (kind === 'function') {
+                    return describeFunction(session, { schema, name: object, args: url.searchParams.get('args') ?? '' });
+                }
+                if (kind === 'sequence')
+                    return describeSequence(session, { schema, name: object });
+                if (kind === 'type')
+                    return describeType(session, { schema, name: object });
+                throw new HttpError(400, `unknown kind "${kind}"`);
+            });
+            if (!found)
+                throw new HttpError(404, `no ${kind} ${schema}.${object}`);
+            return found;
+        }
+        if (resource === 'envs' && name && sub === 'rows' && req.method === 'GET') {
+            const schema = requiredParam(url, 'schema');
+            const table = requiredParam(url, 'table');
+            const limit = Math.min(Math.max(Number(url.searchParams.get('limit')) || 100, 1), 1000);
+            const offset = Math.max(Number(url.searchParams.get('offset')) || 0, 0);
+            try {
+                const filters = parseFilters(jsonParam(url, 'filters'));
+                const sort = parseSort(jsonParam(url, 'sort'));
+                return await withSessionFor(name, async (session) => {
+                    const ref = { schema, name: table };
+                    const columns = await listColumns(session, ref);
+                    for (const { column } of sort) {
+                        if (!columns.some((known) => known.name === column)) {
+                            throw new FilterError(`no column "${column}"`);
+                        }
+                    }
+                    const where = buildWhere(columns, filters);
+                    const result = await browseRows(session, ref, { limit, offset, orderBy: sort, where });
+                    // The same statement with its values written in, for the SQL box.
+                    const shown = browseSql(ref, {
+                        orderBy: sort,
+                        where: buildWhere(columns, filters, { inline: true }),
+                    })
+                        .replace(/LIMIT \$\d+ OFFSET \$\d+$/, `LIMIT ${limit} OFFSET ${offset}`)
+                        .replace(/ OFFSET 0$/, '');
+                    return { ...result, sql: shown };
+                });
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                if (error instanceof FilterError || error instanceof GucError) {
+                    throw new HttpError(400, error.message);
+                }
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' &&
+            name &&
+            sub === 'graph' &&
+            (!id || id === 'expand') &&
+            req.method === 'POST') {
+            try {
+                const body = (await readJson(req));
+                if (id === 'expand') {
+                    const request = parseExpandRequest(body);
+                    return await withSessionFor(name, (session) => expandNode(session, request));
+                }
+                const request = parseGraphRequest(body, parseFilters(body?.filters));
+                return await withSessionFor(name, (session) => buildGraph(session, request));
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                if (error instanceof GraphError || error instanceof FilterError) {
+                    throw new HttpError(400, error.message);
+                }
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' && name && sub === 'cypher' && req.method === 'POST') {
+            try {
+                const request = parseCypherRequest(await readJson(req));
+                return await withSessionFor(name, (session) => runCypher(session, request));
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                if (error instanceof CypherError)
+                    throw new HttpError(400, error.message);
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' && name && sub === 'profile' && req.method === 'GET') {
+            const schema = requiredParam(url, 'schema');
+            const table = requiredParam(url, 'table');
+            const column = requiredParam(url, 'column');
+            try {
+                return await withSessionFor(name, (session) => profileColumn(session, { schema, name: table }, column));
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' && name && sub === 'foreign-keys' && req.method === 'GET') {
+            const schema = requiredParam(url, 'schema');
+            const table = requiredParam(url, 'table');
+            return withSessionFor(name, (session) => listForeignKeys(session, { schema, name: table }));
+        }
+        if (resource === 'envs' && name && sub === 'schema-foreign-keys' && req.method === 'GET') {
+            const schema = requiredParam(url, 'schema');
+            return withSessionFor(name, (session) => listSchemaForeignKeys(session, schema));
+        }
+        if (resource === 'envs' && name && sub === 'references' && req.method === 'POST') {
+            const body = (await readJson(req));
+            if (typeof body?.schema !== 'string' ||
+                typeof body.table !== 'string' ||
+                typeof body.values !== 'object' ||
+                body.values === null) {
+                throw new HttpError(400, 'send {"schema", "table", "values": {column: value}}');
+            }
+            const { schema, table } = body;
+            const values = body.values;
+            try {
+                return await withSessionFor(name, (session) => countReferences(session, { schema, name: table }, values));
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' && name && sub === 'query' && req.method === 'POST') {
+            const body = (await readJson(req));
+            if (typeof body?.sql !== 'string' || body.sql.trim() === '') {
+                throw new HttpError(400, 'send {"sql": "..."}');
+            }
+            const sql = body.sql;
+            const limit = Math.min(Math.max(Number(body.limit) || 100, 1), 1000);
+            const offset = Math.max(Math.floor(Number(body.offset)) || 0, 0);
+            const envName = environmentNamed(name).name;
+            const started = performance.now();
+            try {
+                const gucs = parseGucs(body.settings);
+                const result = await withSessionFor(name, async (session) => {
+                    await applyGucs(session, gucs);
+                    return runPage(session, sql, { limit, offset });
+                });
+                // Later pages of a result are the same statement again, not a new one to remember.
+                if (offset === 0) {
+                    services.store.recordQuery({
+                        envName,
+                        sql,
+                        durationMs: result.durationMs,
+                        rowCount: result.rowCount ?? result.rows.length,
+                    });
+                }
+                return result;
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                const message = error instanceof GucError ? error.message : describeQueryError(error);
+                if (offset === 0) {
+                    services.store.recordQuery({
+                        envName,
+                        sql,
+                        durationMs: performance.now() - started,
+                        error: message,
+                    });
+                }
+                throw new HttpError(400, message);
+            }
+        }
+        if (resource === 'envs' && name && sub === 'export' && req.method === 'POST') {
+            const body = (await readJson(req));
+            try {
+                if (typeof body?.table === 'string' && typeof body.schema === 'string') {
+                    const ref = { schema: body.schema, name: body.table };
+                    const filters = parseFilters(body.filters);
+                    const sort = parseSort(body.sort);
+                    return await withSessionFor(name, async (session) => {
+                        const columns = await listColumns(session, ref);
+                        for (const { column } of sort) {
+                            if (!columns.some((known) => known.name === column)) {
+                                throw new FilterError(`no column "${column}"`);
+                            }
+                        }
+                        const where = buildWhere(columns, filters);
+                        const result = await browseRows(session, ref, {
+                            limit: EXPORT_MAX_ROWS,
+                            orderBy: sort,
+                            where,
+                        });
+                        return { columns: result.columns, rows: result.rows, truncated: result.truncated };
+                    });
+                }
+                if (typeof body?.sql !== 'string' || !canExport(body.sql)) {
+                    throw new HttpError(400, 'send {"sql": "SELECT ..."} or {"schema", "table"}: only queries that return rows can be exported');
+                }
+                const sql = body.sql;
+                const gucs = parseGucs(body.settings);
+                const result = await withSessionFor(name, async (session) => {
+                    await applyGucs(session, gucs);
+                    return exportRows(session, sql);
+                });
+                return { columns: result.columns, rows: result.rows, truncated: result.truncated };
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                if (error instanceof FilterError)
+                    throw new HttpError(400, error.message);
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' && name && sub === 'edit' && req.method === 'POST') {
+            const body = (await readJson(req, MAX_EDIT_BODY_BYTES));
+            if (typeof body?.schema !== 'string' || typeof body.table !== 'string') {
+                throw new HttpError(400, 'send {"schema", "table", "action", "key"?, "values"?, "apply"?}');
+            }
+            const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+            const cells = (value) => {
+                if (value === undefined)
+                    return {};
+                if (!isRecord(value))
+                    throw new HttpError(400, 'values is {column: text or null}');
+                for (const cell of Object.values(value)) {
+                    if (cell !== null && typeof cell !== 'string') {
+                        throw new HttpError(400, 'values is {column: text or null}');
+                    }
+                }
+                return value;
+            };
+            const keyed = (value) => {
+                const key = cells(value);
+                if (Object.values(key).some((cell) => cell === null)) {
+                    throw new HttpError(400, 'a key has no NULL values');
+                }
+                return key;
+            };
+            let request;
+            if (body.action === 'insert')
+                request = { action: 'insert', values: cells(body.values) };
+            else if (body.action === 'update') {
+                request = { action: 'update', key: keyed(body.key), values: cells(body.values) };
+            }
+            else if (body.action === 'delete')
+                request = { action: 'delete', key: keyed(body.key) };
+            else
+                throw new HttpError(400, 'action is insert, update or delete');
+            const ref = { schema: body.schema, name: body.table };
+            try {
+                return await withSessionFor(name, async (session) => {
+                    const edit = buildEdit(ref, await listColumns(session, ref), request);
+                    if (body.apply !== true)
+                        return { sql: edit.display, applied: false };
+                    if (session.readOnly) {
+                        throw new HttpError(400, 'this environment is read only: turn on write mode first');
+                    }
+                    const result = await applyEdit(session, edit);
+                    const entry = environmentNamed(name);
+                    services.store.recordQuery({
+                        envName: entry.name,
+                        sql: edit.display,
+                        durationMs: result.durationMs,
+                        rowCount: 1,
+                    });
+                    return { sql: edit.display, applied: true };
+                });
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                if (error instanceof EditError)
+                    throw new HttpError(400, error.message);
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' && name && sub === 'seed') {
+            const entry = environmentNamed(name);
+            if (!entry.seeder) {
+                throw new HttpError(403, `the seeder is turned off for ${entry.name}: set seeder: true in its explorer.yaml to use it`);
+            }
+            if (req.method === 'GET') {
+                const schema = requiredParam(url, 'schema');
+                const table = requiredParam(url, 'table');
+                try {
+                    const ref = { schema, name: table };
+                    const [columns, foreignKeys] = await withSessionFor(name, async (session) => [
+                        await describeSeedColumns(session, ref),
+                        (await listForeignKeys(session, ref)).outgoing,
+                    ]);
+                    return {
+                        columns,
+                        foreignKeys,
+                        generators,
+                        locales: seedLocales,
+                        maxRows: MAX_SEED_ROWS,
+                    };
+                }
+                catch (error) {
+                    throw new HttpError(400, describeQueryError(error));
+                }
+            }
+            if (req.method === 'POST') {
+                const body = (await readJson(req));
+                if (typeof body?.schema !== 'string' || typeof body.table !== 'string') {
+                    throw new HttpError(400, 'send {"schema", "table", "count", "columns", "apply"?}');
+                }
+                const ref = { schema: body.schema, name: body.table };
+                try {
+                    const request = parseSeedRequest(body);
+                    return await withSessionFor(name, async (session) => {
+                        if (body.apply !== true)
+                            return { preview: await previewSeed(session, ref, request) };
+                        if (session.readOnly) {
+                            throw new HttpError(400, 'this environment is read only: turn on write mode first');
+                        }
+                        const result = await runSeed(session, ref, request);
+                        services.store.recordQuery({
+                            envName: entry.name,
+                            sql: `-- seeder: ${result.inserted} generated rows\n${result.sql}`,
+                            durationMs: result.durationMs,
+                            rowCount: result.inserted,
+                        });
+                        return { result };
+                    });
+                }
+                catch (error) {
+                    if (error instanceof HttpError)
+                        throw error;
+                    if (error instanceof SeedError)
+                        throw new HttpError(400, error.message);
+                    throw new HttpError(400, describeQueryError(error));
+                }
+            }
+        }
+        if (resource === 'envs' && name && sub === 'design' && req.method === 'GET') {
+            environmentNamed(name);
+            const schema = requiredParam(url, 'schema');
+            const table = requiredParam(url, 'name');
+            const loaded = await withSessionFor(name, (session) => loadDesign(session, { schema, name: table }));
+            if (!loaded)
+                throw new HttpError(404, `no table ${schema}.${table}`);
+            return loaded;
+        }
+        if (resource === 'envs' && name && (sub === 'alter' || sub === 'drop-table') && req.method === 'POST') {
+            const entry = environmentNamed(name);
+            const body = (await readJson(req));
+            const lockTimeoutMs = typeof body?.lockTimeoutMs === 'number' ? body.lockTimeoutMs : 5000;
+            let statements;
+            let estimatedRows = null;
+            try {
+                if (sub === 'drop-table') {
+                    const schema = body?.schema;
+                    const table = body?.name;
+                    if (typeof schema !== 'string' || typeof table !== 'string') {
+                        throw new AlterError('send {"schema", "name", "cascade"?, "apply"?}');
+                    }
+                    statements = [dropTableStatement({ schema, name: table }, body?.cascade === true)];
+                }
+                else {
+                    const before = parseTableDesign(body?.original);
+                    const after = parseTableDesign(body?.design);
+                    const options = parseAlterOptions(body?.options);
+                    const loaded = await withSessionFor(name, (session) => loadDesign(session, before));
+                    if (!loaded)
+                        throw new HttpError(404, `no table ${before.schema}.${before.name}`);
+                    estimatedRows = loaded.estimatedRows;
+                    statements = diffDesigns(before, after, {
+                        ...options,
+                        estimatedRows,
+                        serverMajor: loaded.serverMajor,
+                    });
+                }
+                const plan = splitPlan(statements, lockTimeoutMs);
+                if (body?.apply !== true) {
+                    return { statements, lockTimeout: plan.transactional[0]?.startsWith('SET LOCAL') ? plan.transactional[0] : null, estimatedRows };
+                }
+                if (!entry.designer) {
+                    throw new HttpError(403, `the designer is turned off for ${entry.name}: set designer: true in its explorer.yaml to change tables`);
+                }
+                if (statements.length === 0)
+                    throw new HttpError(400, 'there is nothing to change');
+                const session = await withSessionFor(name, (opened) => Promise.resolve(opened.readOnly));
+                if (session)
+                    throw new HttpError(400, 'this environment is read only: turn on write mode first');
+                if (statements.some((statement) => statement.drop)) {
+                    // Asked every time, like switching on write mode: it drops something that cannot come back.
+                    const prompt = services.resolvers.get('prompt');
+                    if (!prompt)
+                        throw new HttpError(400, 'there is no way to ask for confirmation');
+                    try {
+                        await prompt.confirm({ envName: entry.name, interactive: true, signal, purpose: 'drop' });
+                    }
+                    catch (error) {
+                        if (error instanceof ResolveError)
+                            throw new HttpError(400, error.message);
+                        throw error;
+                    }
+                }
+                return await withSessionFor(name, async (opened) => {
+                    const result = await runPlan(opened, plan, describeQueryError);
+                    services.store.recordQuery({
+                        envName: entry.name,
+                        sql: [...plan.transactional, ...plan.concurrent].map((statement) => `${statement};`).join('\n'),
+                        durationMs: result.durationMs,
+                    });
+                    return { statements, applied: true };
+                });
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                if (error instanceof DdlError)
+                    throw new HttpError(400, error.message);
+                if (error instanceof DesignRunError) {
+                    throw new HttpError(400, error.message, { statement: error.statement });
+                }
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' && name && sub === 'design' && req.method === 'POST') {
+            const entry = environmentNamed(name);
+            const body = (await readJson(req));
+            let statements;
+            try {
+                const design = parseTableDesign(body?.design);
+                // The statements are built from the design alone; the server's own version only matters when
+                // they run, where it refuses what it lacks with its own message.
+                statements = buildDdl(design);
+            }
+            catch (error) {
+                if (error instanceof DdlError)
+                    throw new HttpError(400, error.message);
+                throw error;
+            }
+            if (body?.apply !== true)
+                return { statements };
+            if (!entry.designer) {
+                throw new HttpError(403, `the designer is turned off for ${entry.name}: set designer: true in its explorer.yaml to create tables`);
+            }
+            try {
+                return await withSessionFor(name, async (session) => {
+                    if (session.readOnly) {
+                        throw new HttpError(400, 'this environment is read only: turn on write mode first');
+                    }
+                    const result = await runStatements(session, statements, describeQueryError);
+                    services.store.recordQuery({
+                        envName: entry.name,
+                        sql: statements.map((statement) => `${statement};`).join('\n'),
+                        durationMs: result.durationMs,
+                    });
+                    return { statements, applied: true };
+                });
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                if (error instanceof DesignRunError) {
+                    throw new HttpError(400, error.message, { statement: error.statement });
+                }
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' && name && sub === 'history' && req.method === 'GET') {
+            const entry = environmentNamed(name);
+            const text = (url.searchParams.get('q') ?? '').trim().toLowerCase();
+            const limit = Math.min(Math.max(Number(url.searchParams.get('limit')) || 100, 1), 500);
+            // Newest first; the search runs over all that is kept, not only what is shown.
+            return services.store
+                .historyFor(entry.name, 5000)
+                .filter((record) => !text || record.sql.toLowerCase().includes(text))
+                .slice(0, limit);
+        }
+        if (resource === 'envs' && name && sub === 'saved' && !id && req.method === 'GET') {
+            return services.store.savedQueries(environmentNamed(name).name);
+        }
+        if (resource === 'envs' && name && sub === 'saved' && !id && req.method === 'POST') {
+            const entry = environmentNamed(name);
+            const body = (await readJson(req));
+            if (typeof body?.sql !== 'string' || body.sql.trim() === '') {
+                throw new HttpError(400, 'send {"name", "sql", "folder"?, "pinned"?}');
+            }
+            return services.store.saveQuery({
+                envName: entry.name,
+                name: savedName(body.name, body.sql),
+                folder: typeof body.folder === 'string' ? body.folder.trim().slice(0, 60) : '',
+                sql: body.sql,
+                pinned: body.pinned === true,
+            });
+        }
+        if (resource === 'envs' &&
+            name &&
+            sub === 'saved' &&
+            id &&
+            (req.method === 'POST' || req.method === 'DELETE')) {
+            const entry = environmentNamed(name);
+            const savedId = Number(id);
+            // Only a query saved for this environment can be changed through it.
+            const found = services.store.savedQueries(entry.name).find((saved) => saved.id === savedId);
+            if (!found)
+                throw new HttpError(404, 'no such saved query');
+            if (req.method === 'DELETE') {
+                services.store.deleteSavedQuery(savedId);
+                return {};
+            }
+            const body = (await readJson(req));
+            return services.store.updateSavedQuery(savedId, {
+                ...(typeof body?.name === 'string' && body.name.trim()
+                    ? { name: savedName(body.name, found.sql) }
+                    : {}),
+                ...(typeof body?.folder === 'string' ? { folder: body.folder.trim().slice(0, 60) } : {}),
+                ...(typeof body?.sql === 'string' && body.sql.trim() ? { sql: body.sql } : {}),
+                ...(typeof body?.pinned === 'boolean' ? { pinned: body.pinned } : {}),
+            });
+        }
+        if (resource === 'envs' && name && sub === 'explain' && req.method === 'POST') {
+            const body = (await readJson(req));
+            if (typeof body?.sql !== 'string' || body.sql.trim() === '') {
+                throw new HttpError(400, 'send {"sql": "...", "analyze"?: true}');
+            }
+            const sql = body.sql;
+            try {
+                const gucs = parseGucs(body.settings);
+                // Analyzing runs the statement (and rolls it back) to measure each step.
+                if (body.analyze === true) {
+                    return await withSessionFor(name, async (session) => {
+                        await applyGucs(session, gucs);
+                        return explainAnalyze(session, sql);
+                    });
+                }
+                return {
+                    plan: await withSessionFor(name, async (session) => {
+                        await applyGucs(session, gucs);
+                        return explainQuery(session, sql);
+                    }),
+                };
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                if (error instanceof GucError)
+                    throw new HttpError(400, error.message);
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        throw new HttpError(404, 'not found');
+    }
+    async function serveStatic(res, pathname) {
+        if (!staticDir)
+            throw new HttpError(404, 'the web UI is not built; run npm run build:web');
+        const file = normalize(join(staticDir, pathname === '/' ? 'index.html' : pathname));
+        if (file !== staticDir && !file.startsWith(staticDir + sep))
+            throw new HttpError(403, 'forbidden');
+        let data;
+        let type = contentTypes[extname(file)] ?? 'application/octet-stream';
+        try {
+            data = await readFile(file);
+        }
+        catch {
+            // Not a file: the single page app handles the route itself.
+            if (extname(pathname))
+                throw new HttpError(404, 'not found');
+            data = await readFile(join(staticDir, 'index.html')).catch(() => {
+                throw new HttpError(404, 'the web UI is not built; run npm run build:web');
+            });
+            type = contentTypes['.html'];
+        }
+        res.writeHead(200, { 'content-type': type });
+        res.end(data);
+    }
+    return createServer((req, res) => {
+        void (async () => {
+            try {
+                if (!isLoopbackHost(req.headers.host))
+                    throw new HttpError(403, 'forbidden host');
+                const url = new URL(req.url ?? '/', 'http://localhost');
+                if (url.pathname.startsWith('/api/')) {
+                    // A request the browser gave up on stops waiting for answers to its questions.
+                    const abort = new AbortController();
+                    res.on('close', () => abort.abort());
+                    sendJson(res, 200, await api(req, url, abort.signal));
+                }
+                else if (req.method === 'GET' || req.method === 'HEAD')
+                    await serveStatic(res, url.pathname);
+                else
+                    throw new HttpError(405, 'method not allowed');
+            }
+            catch (error) {
+                if (error instanceof HttpError) {
+                    sendJson(res, error.status, { ...error.extra, error: error.message });
+                }
+                else {
+                    sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+                }
+            }
+        })();
+    });
+}
+const PORT_ATTEMPTS = 100;
+/**
+ * Starts listening on the loopback interface; resolves with the address once it is up. When the
+ * port is taken the next free one is used, so the caller compares the result with what it asked for.
+ */
+export async function listen(server, port) {
+    for (let candidate = port; candidate < port + PORT_ATTEMPTS && candidate <= 65535; candidate++) {
+        try {
+            await listenOn(server, candidate);
+            return `http://127.0.0.1:${candidate}`;
+        }
+        catch (error) {
+            if (error.code !== 'EADDRINUSE')
+                throw error;
+        }
+    }
+    throw new Error(`no free port found from ${port} to ${port + PORT_ATTEMPTS - 1}`);
+}
+function listenOn(server, port) {
+    return new Promise((resolveListen, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', () => {
+            server.off('error', reject);
+            resolveListen();
+        });
+    });
+}
+/** Opens the address in the default browser; failing to is not an error, the address is printed. */
+export function openBrowser(address) {
+    const [command, args] = process.platform === 'darwin'
+        ? ['open', [address]]
+        : process.platform === 'win32'
+            ? ['cmd', ['/c', 'start', '', address]]
+            : ['xdg-open', [address]];
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => { });
+    child.unref();
+}