dbtour 0.8.0 → 0.9.0

package/dist/cli.d.ts

@@ -10,6 +10,8 @@ export interface Io {
     load?: (source: SourceConfig) => Promise<Source>;
     /** How an add-on is loaded; tests hand in their own. */
     loadAddon?: (addon: AddonConfig) => Promise<Addon>;
+    /** When serve stops; Ctrl+C unless a test hands in its own. */
+    stop?: Promise<void>;
     /** Where mcp reads requests and writes answers; process.stdin and process.stdout unless a test hands in its own. */
     stdin?: Readable;
     stdout?: Writable;

package/dist/cli.js

@@ -18,6 +18,8 @@ import { emptyModel, scope, validate } from "./model.js";
 import { applyNotes, parseNotes } from "./notes.js";
 import { answerLine } from "./mcp.js";
 import { checkQuery, clampLimit, defaultTimeoutMs, resultText } from "./sql.js";
+import { startServer } from "./serve.js";
+import { randomBytes } from 'node:crypto';
 import { loadAddon, loadSource } from "./plugins.js";
 import { renderMarkdown } from "./render/markdown.js";
 const help = `Usage: dbtour <command>
@@ -30,12 +32,14 @@ const help = `Usage: dbtour <command>
                           on stdin and stdout: claude mcp add dbtour -- npx dbtour mcp
   sql "<query>"           run one SELECT through a source's reader, a read-only login of its own,
                           rolled back, at most --limit rows (100); --source <name>, --json
+  serve [--port 4321]     the rendered page on this machine; its SQL editor runs queries through the
+                          readers, as sql does
 
 Set the connection string in the environment variable ${configFile} names, never in the file.`;
 export async function main(argv, io = { cwd: process.cwd(), log: console.log, error: console.error }) {
     const { values, positionals } = parseArgs({
         args: argv,
-        options: { help: { type: 'boolean', short: 'h' }, source: { type: 'string' }, limit: { type: 'string' }, json: { type: 'boolean' } },
+        options: { help: { type: 'boolean', short: 'h' }, source: { type: 'string' }, limit: { type: 'string' }, json: { type: 'boolean' }, port: { type: 'string' } },
         allowPositionals: true,
         strict: false,
     });
@@ -54,6 +58,8 @@ export async function main(argv, io = { cwd: process.cwd(), log: console.log, er
                 return await render(io);
             case 'mcp':
                 return await mcp(positionals[1] === undefined ? io : { ...io, cwd: resolve(io.cwd, positionals[1]) });
+            case 'serve':
+                return await serve(io, typeof values.port === 'string' ? Number(values.port) : defaultPort);
             case 'sql':
                 return await sql(io, positionals[1], {
                     source: typeof values.source === 'string' ? values.source : undefined,
@@ -222,6 +228,42 @@ async function mcp(io) {
     }
     return 0;
 }
+/** dbtour serve's port unless --port says otherwise: one an editor's own dev servers seldom take. */
+const defaultPort = 4321;
+/**
+ * The rendered folder on 127.0.0.1, with a door for its SQL editor: a query posted by the page runs as dbtour
+ * sql runs it. A token made fresh each time is handed to the page and required on every query.
+ */
+async function serve(io, port) {
+    const config = readConfig(io);
+    const root = join(io.cwd, config.out);
+    if (!existsSync(join(root, 'index.html')))
+        throw missing(`No ${join(config.out, 'index.html')} to serve: add explorer to addons in ${configFile}, run dbtour render, then dbtour serve again`);
+    const readers = config.sources.filter((s) => s.reader !== undefined);
+    const token = randomBytes(24).toString('base64url');
+    let server;
+    try {
+        server = await startServer({
+            root,
+            port,
+            token,
+            sources: config.sources.map((s) => ({ name: s.name, reader: s.reader !== undefined })),
+            run: readers.length
+                ? async (text, source, limit) => ({ ...(await runQuery(io, config, text, source, limit)), source: pickSource(config, source).name })
+                : undefined,
+        });
+    }
+    catch (error) {
+        if (error.code === 'EADDRINUSE')
+            throw new Error(`Port ${port} is taken: run dbtour serve --port ${port + 1}`, { cause: error });
+        throw error;
+    }
+    io.log(`Serving ${config.out} at ${server.url}`);
+    io.log(readers.length ? `Queries run through ${readers.map((s) => `${s.name}'s reader`).join(', ')}. Ctrl+C to stop.` : `No source has a reader, so the page can be read but runs no query: add reader to a source in ${configFile}. Ctrl+C to stop.`);
+    await (io.stop ?? new Promise((done) => process.once('SIGINT', () => done())));
+    await server.close();
+    return 0;
+}
 async function sql(io, text, options) {
     if (text === undefined || text.trim() === '') {
         io.error('Give the query to run: dbtour sql "SELECT TOP (10) * FROM dbo.Orders"');

package/dist/serve.d.ts

@@ -0,0 +1,24 @@
+import type { QueryResult } from './sql.ts';
+export interface Served {
+    /** The folder render wrote: index.html and the Markdown beside it. */
+    root: string;
+    /** 0 for any free port. */
+    port: number;
+    /** The session's secret, given to the page in a meta tag and required on every query. */
+    token: string;
+    /** The sources, and whether each has a reader: what the page shows, never a connection string. */
+    sources: {
+        name: string;
+        reader: boolean;
+    }[];
+    /** Runs one query through a source's reader; absent when no source has one. */
+    run?: (sql: string, source: string | undefined, limit: number | undefined) => Promise<QueryResult & {
+        source: string;
+    }>;
+}
+/** The address it listens on: this machine alone. */
+export declare const serveHost = "127.0.0.1";
+export declare function startServer(options: Served): Promise<{
+    url: string;
+    close: () => Promise<void>;
+}>;

package/dist/serve.js

@@ -0,0 +1,129 @@
+// dbtour serve: the rendered folder on this machine, and the one door the page has to the database. The page
+// runs a query by posting it here, and it runs as dbtour sql does: checked, through the source's reader, in a
+// transaction that is rolled back. Only this machine can reach it (127.0.0.1), and only this server's own
+// page can ask: the request must carry the session's token, which the page is given when served, and say it
+// comes from this server (Host and Origin), so another website, or a name rebound to this address, cannot.
+import { createServer } from 'node:http';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { extname, join, normalize, resolve, sep } from 'node:path';
+/** The address it listens on: this machine alone. */
+export const serveHost = '127.0.0.1';
+/** A query and its options are a few lines; anything past this is not one, and is refused unread. */
+const maxBodyBytes = 100 * 1024;
+const types = {
+    '.html': 'text/html; charset=utf-8',
+    '.md': 'text/markdown; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.css': 'text/css; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+};
+export async function startServer(options) {
+    let origins = new Set();
+    let hosts = new Set();
+    const server = createServer((request, response) => {
+        handle(request, response, options, hosts, origins).catch((error) => send(response, 500, { error: error instanceof Error ? error.message : String(error) }));
+    });
+    await new Promise((done, fail) => {
+        server.once('error', fail);
+        server.listen(options.port, serveHost, () => done());
+    });
+    const port = server.address().port;
+    hosts = new Set([`${serveHost}:${port}`, `localhost:${port}`]);
+    origins = new Set([...hosts].map((h) => `http://${h}`));
+    return {
+        url: `http://${serveHost}:${port}`,
+        close: () => new Promise((done) => server.close(() => done())),
+    };
+}
+async function handle(request, response, options, hosts, origins) {
+    // Every route, not only the query: the page carries the token and the model, and the Markdown and
+    // schema.json are the schema, none of it for a site whose name was rebound to this address.
+    if (!hosts.has(request.headers.host ?? '')) {
+        return send(response, 403, { error: 'Open the page at the address dbtour serve printed: this server answers only to its own name.' });
+    }
+    const path = decodeURIComponent(new URL(request.url ?? '/', 'http://local').pathname);
+    if (path === '/api/query')
+        return query(request, response, options, hosts, origins);
+    if (request.method !== 'GET' && request.method !== 'HEAD')
+        return send(response, 405, { error: 'Only the page and its files are here: GET them.' });
+    const file = resolve(options.root, normalize(`.${path === '/' ? '/index.html' : path}`));
+    // Nothing outside the rendered folder, however the path is written.
+    if (file !== resolve(options.root) && !file.startsWith(resolve(options.root) + sep))
+        return send(response, 404, { error: 'Not here.' });
+    if (!existsSync(file) || !statSync(file).isFile())
+        return send(response, 404, { error: 'Not here.' });
+    let body = readFileSync(file);
+    if (file === join(resolve(options.root), 'index.html'))
+        body = withServe(body.toString('utf8'), options);
+    response.writeHead(200, { 'content-type': types[extname(file)] ?? 'application/octet-stream', 'cache-control': 'no-store' });
+    response.end(request.method === 'HEAD' ? undefined : body);
+}
+/** The page, told it is served: the token to send with a query, and which sources can run one. */
+function withServe(html, options) {
+    const value = JSON.stringify({ token: options.token, sources: options.sources }).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+    const meta = `<meta name="dbtour-serve" content="${value}">`;
+    return html.includes('</head>') ? html.replace('</head>', `${meta}</head>`) : meta + html;
+}
+async function query(request, response, options, hosts, origins) {
+    if (request.method !== 'POST')
+        return send(response, 405, { error: 'POST a query: {"sql": "SELECT …"}.' });
+    // The page's own requests name this server; anything else is another site, or a name rebound to this address.
+    const origin = request.headers.origin;
+    if (!hosts.has(request.headers.host ?? '') || (origin !== undefined && !origins.has(origin)) || request.headers['x-dbtour-token'] !== options.token) {
+        return send(response, 403, { error: 'Only the page dbtour serve gave out can run a query here: open it again from the address dbtour serve printed.' });
+    }
+    const text = await body(request);
+    if (text === undefined)
+        return send(response, 413, { error: 'That is more than a query: send one SELECT.' });
+    let asked;
+    try {
+        asked = JSON.parse(text);
+    }
+    catch {
+        asked = undefined;
+    }
+    if (typeof asked !== 'object' || asked === null || Array.isArray(asked) || typeof asked.sql !== 'string') {
+        return send(response, 400, { error: 'Send {"sql": "SELECT …"}, with source and limit if you want them.' });
+    }
+    const { sql, source, limit } = asked;
+    if (!options.run) {
+        return send(response, 422, { error: 'This page can be read, but no source has a reader, so a query cannot run here: add reader: ${DBTOUR_MSSQL_READER} to a source in dbtour.yaml and start dbtour serve again.' });
+    }
+    const started = Date.now();
+    try {
+        const result = await options.run(sql, typeof source === 'string' ? source : undefined, typeof limit === 'number' ? limit : undefined);
+        send(response, 200, { ...result, ms: Date.now() - started });
+    }
+    catch (error) {
+        send(response, 422, { error: error instanceof Error ? error.message : String(error) });
+    }
+}
+/**
+ * The request's body, or nothing when it is larger than any query. Past the limit the rest is read and
+ * dropped, not kept, so the connection stays open for the 413 that says why.
+ */
+function body(request) {
+    return new Promise((done, fail) => {
+        const chunks = [];
+        let size = 0;
+        request.on('data', (chunk) => {
+            size += chunk.length;
+            if (size <= maxBodyBytes)
+                chunks.push(chunk);
+        });
+        request.on('end', () => done(size > maxBodyBytes ? undefined : Buffer.concat(chunks).toString('utf8')));
+        request.on('error', fail);
+    });
+}
+/** JSON, with a date as ISO and bytes as hex, as dbtour sql --json writes them. */
+function send(response, status, value) {
+    const text = JSON.stringify(value, (_key, v) => {
+        if (v && typeof v === 'object' && v.type === 'Buffer')
+            return `0x${Buffer.from(v.data).toString('hex')}`;
+        return v;
+    });
+    response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+    response.end(text);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dbtour",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Tour your database and its API: searchable docs, relations and diagrams, generated from the schema, kept in the repo.",
   "type": "module",
   "license": "MIT",
@@ -32,6 +32,10 @@
     "./search": {
       "types": "./dist/search.d.ts",
       "default": "./dist/search.js"
+    },
+    "./sql": {
+      "types": "./dist/sql.d.ts",
+      "default": "./dist/sql.js"
     }
   },
   "files": [