@crvouga/atlas 0.3.0 → 0.5.0

package/dist/server/src/config.js

@@ -0,0 +1,187 @@
+/**
+ * @module Server configuration
+ *
+ * Loads how the server runs: `atlas.server.json`, then environment variables, then flags, each overriding the last, checked
+ * against `ServerConfigSchema` and resolved (paths made absolute, backends named, tokens read). Every mistake is a
+ * `ConfigError` that says what to change, and a server that would listen beyond this machine with no tokens refuses to
+ * start. `SERVER_SETTINGS` documents every setting once; the table in docs/server.md is generated from it and a test proves
+ * each row.
+ *
+ * @see docs/server.md#configuration
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { ServerConfigSchema } from '../../schema/src/server-config.js';
+/** A configuration that cannot be used. The message says what to change; `atlas serve` prints it and exits 2. */
+export class ConfigError extends Error {
+}
+const DEFAULT_FILE = 'atlas.server.json';
+const MIN_TOKEN = 12;
+const OPTIONS = {
+    config: { type: 'string' }, data: { type: 'string' }, store: { type: 'string', multiple: true }, write: { type: 'string' },
+    host: { type: 'string' }, port: { type: 'string' }, site: { type: 'string' }, 'outline-branch': { type: 'string' },
+    branch: { type: 'string', multiple: true }, 'ignore-modified': { type: 'boolean' }, refresh: { type: 'string' },
+    insecure: { type: 'boolean' }, 'no-log': { type: 'boolean' }, 'anonymous-read': { type: 'boolean' }
+};
+/** Every flag `atlas serve` accepts, with its `--`. */
+export const SERVER_FLAGS = Object.keys(OPTIONS).map(name => `--${name}`);
+/**
+ * Every setting that can be given by flag or environment, documented once. `docs/server.md` renders its table from
+ * this list, and a test proves each row: its example, through the flag and through the environment, changes the
+ * configuration as the row says. A setting added to the loader without a row here is therefore not documented in the
+ * table; one documented here that the loader ignores fails the test.
+ */
+export const SERVER_SETTINGS = [
+    { summary: 'Address to listen on', key: 'host', flag: '--host <address>', env: ['ATLAS_HOST', 'HOST'], default: '`127.0.0.1`', example: { value: '0.0.0.0', read: c => c.host, expected: '0.0.0.0' } },
+    { summary: 'Port (`0` picks a free one)', key: 'port', flag: '--port <n>', env: ['ATLAS_PORT', 'PORT'], default: '`8080`', example: { value: '9191', read: c => c.port, expected: 9191 } },
+    { summary: 'The server\'s own folder: the default backend and write target', key: 'data', flag: '--data <dir>', env: ['ATLAS_DATA'], default: '`./atlas-data`', example: { value: 'results', read: c => path.basename(c.data), expected: 'results' } },
+    { summary: 'More backends, read together with the data folder', key: 'backends', flag: '--store <[id=]url>` (repeatable)', env: ['ATLAS_STORE'], default: 'none', example: { value: 'lab=https://lab.example.com', read: c => c.backends.map(backend => backend.id), expected: ['data', 'lab'] } },
+    { summary: 'The backend uploads go to', key: 'write', flag: '--write <id>', env: ['ATLAS_WRITE'], default: '`data`', example: { value: 'data', read: c => c.writeId, expected: 'data' } },
+    { summary: 'The built viewer', key: 'site', flag: '--site <dir>', env: ['ATLAS_SITE'], default: '`./atlas-site`, else built once', example: { value: 'viewer', read: c => path.basename(c.site ?? ''), expected: 'viewer' } },
+    { summary: 'Whose specs the report is laid over', key: 'outlineBranch', flag: '--outline-branch <branch>', env: ['ATLAS_OUTLINE_BRANCH'], default: '`main`, then `master`, then the newest', example: { value: 'trunk', read: c => c.outlineBranch, expected: 'trunk' } },
+    { summary: 'Only layers recorded on these branches take part', key: 'include.branches', flag: '--branch <name>` (repeatable)', env: ['ATLAS_ONLY_BRANCH'], default: 'all', example: { value: 'main', read: c => c.include.branches, expected: ['main'] } },
+    { summary: 'Leave out layers from modified checkouts and unknown origins', key: 'include.ignoreModified', flag: '--ignore-modified', env: ['ATLAS_IGNORE_MODIFIED'], default: 'no', example: { value: '1', read: c => c.include.ignoreModified, expected: true } },
+    { summary: 'How often (seconds) the backends are looked at for layers written by something else', key: 'refreshSeconds', flag: '--refresh <seconds>', env: ['ATLAS_REFRESH_SECONDS'], default: '`10`', example: { value: '30', read: c => c.refreshSeconds, expected: 30 } },
+    { summary: 'Let anyone look, not upload', key: 'auth.anonymousRead', flag: '--anonymous-read', env: ['ATLAS_ANONYMOUS_READ'], default: 'no', example: { value: '1', read: c => c.anonymousRead, expected: true } },
+    { summary: 'Listen publicly with no tokens (something in front signs people in)', key: 'auth.insecure', flag: '--insecure', env: ['ATLAS_INSECURE'], default: 'no', example: { value: '1', read: c => c.insecure, expected: true } },
+    { summary: 'The admin token (also `ATLAS_PUBLISH_TOKEN` and `ATLAS_READ_TOKEN` for the other roles, or `auth.tokens` in the file)', key: 'auth.tokens', flag: null, env: ['ATLAS_TOKEN'], default: 'none: the server is open and listens on this machine only', example: { value: 'admin-token-123456', read: c => c.tokens.map(token => token.role), expected: ['admin'] } },
+    { summary: 'The configuration file', key: '(the file itself)', flag: '--config <file>', env: ['ATLAS_CONFIG'], default: '`./atlas.server.json` when it exists', example: { value: 'custom.json', read: c => path.basename(c.configFile ?? ''), expected: 'custom.json' } },
+    { summary: 'No request log', key: 'log', flag: '--no-log', env: [], default: 'one JSON line per request', example: { value: '', read: c => c.log, expected: false } }
+];
+/** The text `atlas serve --help` prints. Also the source of the `atlas serve` section of `docs/reference/cli.md`. */
+export const SERVER_USAGE = `atlas serve: the Atlas server
+
+  atlas serve [--config atlas.server.json] [--data <dir>] [--port 8080] [--host 127.0.0.1]
+              [--store <url|id=url>]... [--write <id>] [--site <dir>]
+              [--outline-branch <b>] [--branch <name>]... [--ignore-modified] [--refresh <seconds>]
+              [--anonymous-read] [--insecure] [--no-log]
+
+  One process serves the viewer and the API. Test results are uploaded to it from anywhere (laptops, CI) and it
+  shows everyone the combined report, live. It keeps its data in --data (default ./atlas-data) and can read more
+  backends (--store): S3, other servers, folders. Uploads go to the data folder unless --write names another.
+
+  Tokens (ATLAS_TOKEN admin, ATLAS_PUBLISH_TOKEN, ATLAS_READ_TOKEN, or "auth.tokens" in the config) are required
+  to listen beyond this machine unless --insecure. Every option has an environment variable (docs/deploying.md).
+`;
+function parseFlags(argv) {
+    try {
+        return parseArgs({ args: [...argv], options: OPTIONS, allowPositionals: false, strict: true }).values;
+    }
+    catch (error) {
+        throw new ConfigError(error instanceof Error ? error.message : String(error));
+    }
+}
+const list = (text) => (text ?? '').split(/[\n,]+/).map(item => item.trim()).filter(Boolean);
+const truthy = (value) => value === '1' || value === 'true';
+/** `id=url`, or a bare url with an id made from it. */
+function backendOf(spec, taken) {
+    const named = /^([a-z0-9-]+)=(.+)$/.exec(spec);
+    if (named)
+        return { id: named[1], url: named[2] };
+    const base = spec.replace(/^[a-z0-9+.-]+:\/\//i, '').replace(/[?#].*$/, '').replace(/[^a-z0-9]+/gi, '-').replace(/^-+|-+$/g, '').toLowerCase().slice(0, 40) || 'store';
+    let id = base;
+    for (let n = 2; taken.has(id); n++)
+        id = `${base}-${n}`;
+    return { id, url: spec };
+}
+/**
+ * Read the file named by `--config`/`ATLAS_CONFIG`, or `atlas.server.json` in the folder if there is one, lay the
+ * environment and then the flags over it, and check the result. Every problem is a {@link ConfigError} that says
+ * what to change.
+ */
+export function loadServerConfig(argv, env, cwd, read = file => readFileSync(file, 'utf8')) {
+    const flags = parseFlags(argv);
+    const named = flags.config ?? env.ATLAS_CONFIG;
+    const file = named ? path.resolve(cwd, named) : existsSync(path.join(cwd, DEFAULT_FILE)) ? path.join(cwd, DEFAULT_FILE) : null;
+    let raw = {};
+    if (file) {
+        try {
+            raw = JSON.parse(read(file));
+        }
+        catch (error) {
+            throw new ConfigError(`Cannot read ${file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const base = file ? path.dirname(file) : cwd;
+    const auth = { ...raw.auth };
+    const include = { ...raw.include };
+    const merged = { ...raw, auth, include };
+    const set = (key, value) => { if (value !== undefined)
+        merged[key] = value; };
+    // ATLAS_HOST and ATLAS_PORT first: HOST is often the machine's own name, and PORT belongs to whatever else is running here.
+    set('host', flags.host ?? env.ATLAS_HOST ?? env.HOST);
+    const port = env.ATLAS_PORT ?? env.PORT;
+    set('port', flags.port !== undefined ? Number(flags.port) : port !== undefined ? Number(port) : undefined);
+    set('data', flags.data ?? env.ATLAS_DATA);
+    set('write', flags.write ?? env.ATLAS_WRITE);
+    set('site', flags.site ?? env.ATLAS_SITE);
+    set('outlineBranch', flags['outline-branch'] ?? env.ATLAS_OUTLINE_BRANCH);
+    set('refreshSeconds', flags.refresh !== undefined ? Number(flags.refresh) : env.ATLAS_REFRESH_SECONDS !== undefined ? Number(env.ATLAS_REFRESH_SECONDS) : undefined);
+    if (flags['no-log'])
+        merged.log = false;
+    if (flags.insecure || truthy(env.ATLAS_INSECURE))
+        auth.insecure = true;
+    if (flags['anonymous-read'] || truthy(env.ATLAS_ANONYMOUS_READ))
+        auth.anonymousRead = true;
+    const branches = [...(flags.branch ?? []), ...list(env.ATLAS_ONLY_BRANCH)];
+    if (branches.length)
+        include.branches = branches;
+    if (flags['ignore-modified'] || truthy(env.ATLAS_IGNORE_MODIFIED))
+        include.ignoreModified = true;
+    const parsed = ServerConfigSchema.safeParse(merged);
+    if (!parsed.success)
+        throw new ConfigError(`${file ? `${file}: ` : 'Configuration: '}${parsed.error.issues.map(issue => `${issue.path.join('.') || '(config)'}: ${issue.message}`).join('; ')}`);
+    const config = parsed.data;
+    // Backends: the data folder, then those in the file, then --store and ATLAS_STORE.
+    const taken = new Set(['data']);
+    const backends = [{ id: 'data', label: 'Server data', url: path.resolve(base, config.data) }];
+    const extra = config.backends.map(item => ({ id: item.id, label: item.label ?? item.id, url: item.url, write: item.write === true }));
+    for (const item of extra) {
+        if (taken.has(item.id))
+            throw new ConfigError(`Two backends are called "${item.id}" ("data" is the data folder)`);
+        taken.add(item.id);
+        backends.push({ id: item.id, label: item.label, url: item.url });
+    }
+    for (const spec of [...(flags.store ?? []), ...(flags.store ? [] : list(env.ATLAS_STORE))]) {
+        const item = backendOf(spec, taken);
+        if (taken.has(item.id))
+            throw new ConfigError(`Two backends are called "${item.id}"`);
+        taken.add(item.id);
+        backends.push({ id: item.id, label: item.id, url: item.url });
+    }
+    const marked = extra.filter(item => item.write).map(item => item.id);
+    if (marked.length > 1)
+        throw new ConfigError(`Only one backend can take uploads; ${marked.join(', ')} are all marked write`);
+    const writeId = config.write ?? marked[0] ?? 'data';
+    if (!backends.some(item => item.id === writeId))
+        throw new ConfigError(`write names "${writeId}", which is not a backend (${backends.map(item => item.id).join(', ')})`);
+    // Tokens: the file's, then the environment's.
+    const tokens = [];
+    for (const item of config.auth.tokens) {
+        const token = item.token ?? env[item.tokenEnv];
+        if (!token)
+            throw new ConfigError(`Token "${item.name}" reads ${item.tokenEnv} and it is not set`);
+        tokens.push({ name: item.name, role: item.role, token });
+    }
+    for (const [variable, role, name] of [['ATLAS_TOKEN', 'admin', 'admin'], ['ATLAS_PUBLISH_TOKEN', 'publish', 'publish'], ['ATLAS_READ_TOKEN', 'read', 'read']]) {
+        if (env[variable])
+            tokens.push({ name, role, token: env[variable].trim() });
+    }
+    for (const item of tokens)
+        if (item.token.length < MIN_TOKEN)
+            throw new ConfigError(`Token "${item.name}" is shorter than ${MIN_TOKEN} characters: use a long random one (openssl rand -hex 24)`);
+    if (new Set(tokens.map(item => item.token)).size !== tokens.length)
+        throw new ConfigError('Two tokens are the same: each token must say who it is');
+    const { backends: _backends, auth: _auth, write: _write, ...rest } = config;
+    const resolved = { ...rest, data: backends[0].url, backends, writeId, tokens, anonymousRead: config.auth.anonymousRead, insecure: config.auth.insecure, configFile: file, ...(config.site ? { site: path.resolve(base, config.site) } : {}) };
+    assertSafeToListen(resolved);
+    return resolved;
+}
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+/** A server that anyone on the network can upload to must say who may. */
+export function assertSafeToListen(config) {
+    if (config.tokens.length || config.insecure || LOOPBACK.has(config.host))
+        return;
+    throw new ConfigError(`Listening on ${config.host} with no tokens would let anyone on the network upload results. Set ATLAS_TOKEN (and ATLAS_PUBLISH_TOKEN / ATLAS_READ_TOKEN), or listen on 127.0.0.1, or pass --insecure if something else in front of it does the signing in.`);
+}

package/dist/server/src/dev.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module `atlas dev`
+ *
+ * Runs the same server as `atlas serve` on a port of its own, with the viewer's Vite dev server in front of it. Vite proxies
+ * `/api` (server-sent events included) to the server and writes the same address book into the page, so the browser, the
+ * uploaders and the viewer all use one host, exactly as in production, and a change to the viewer shows at once.
+ */
+import { type ServeIo } from './main.js';
+/** The text `atlas dev --help` prints. Also the source of the `atlas dev` section of `docs/reference/cli.md`. */
+export declare const DEV_USAGE = "atlas dev: the Atlas server and the viewer, for working on either\n\n  atlas dev [--port 5180] [--host 127.0.0.1] [--data <dir>] [--store <url|id=url>]... [--config atlas.server.json]\n\n  Starts the server (API only, on a port of its own) and the viewer's dev server, which proxies /api to it, so the\n  browser talks to one host and a change to the viewer shows at once. In production `atlas serve` does both from\n  one process.\n";
+/** `atlas dev`. */
+export declare function devMain(argv: readonly string[], io: ServeIo): Promise<number>;

package/dist/server/src/dev.js

@@ -0,0 +1,80 @@
+/**
+ * @module `atlas dev`
+ *
+ * Runs the same server as `atlas serve` on a port of its own, with the viewer's Vite dev server in front of it. Vite proxies
+ * `/api` (server-sent events included) to the server and writes the same address book into the page, so the browser, the
+ * uploaders and the viewer all use one host, exactly as in production, and a change to the viewer shows at once.
+ */
+import path from 'node:path';
+import { openConfiguredBackends, serverOptionsOf } from './main.js';
+import { createAtlasServer } from './app.js';
+import { ConfigError, loadServerConfig, SERVER_USAGE } from './config.js';
+import { listen } from './host.js';
+import { visualizerRoot } from './site.js';
+/** The text `atlas dev --help` prints. Also the source of the `atlas dev` section of `docs/reference/cli.md`. */
+export const DEV_USAGE = `atlas dev: the Atlas server and the viewer, for working on either
+
+  atlas dev [--port 5180] [--host 127.0.0.1] [--data <dir>] [--store <url|id=url>]... [--config atlas.server.json]
+
+  Starts the server (API only, on a port of its own) and the viewer's dev server, which proxies /api to it, so the
+  browser talks to one host and a change to the viewer shows at once. In production \`atlas serve\` does both from
+  one process.
+`;
+/** `atlas dev`. */
+export async function devMain(argv, io) {
+    const cwd = io.cwd ?? process.cwd();
+    const env = io.env ?? process.env;
+    if (argv.includes('--help') || argv.includes('-h')) {
+        io.out(DEV_USAGE);
+        return 0;
+    }
+    const root = visualizerRoot();
+    if (!root) {
+        io.out('atlas dev: the viewer is not installed alongside the server.\n');
+        return 2;
+    }
+    // --port is the one the browser uses (the viewer's); the API takes another that nobody needs to know.
+    const flagged = argv.findIndex(item => item === '--port');
+    const publicPort = flagged >= 0 ? Number(argv[flagged + 1]) : Number(env.ATLAS_PORT ?? env.PORT ?? 5180);
+    const forServer = argv.filter((_, i) => i !== flagged && i !== flagged + 1 || flagged < 0);
+    let config;
+    try {
+        // The API itself listens on a port of its own on this machine; what the user said about --host is for the viewer, the one door.
+        config = loadServerConfig([...forServer, '--port', '0'], { ...env, PORT: undefined, ATLAS_PORT: undefined }, cwd);
+    }
+    catch (error) {
+        if (error instanceof ConfigError) {
+            io.out(`atlas dev: ${error.message}\n${SERVER_USAGE.split('\n')[0]}\n`);
+            return 2;
+        }
+        throw error;
+    }
+    const backends = openConfiguredBackends(config, env, cwd);
+    const api = createAtlasServer(serverOptionsOf(config, backends, line => io.out(`${JSON.stringify(line)}\n`)));
+    const running = await listen(api.fetch, { port: 0, host: '127.0.0.1', maxBodyBytes: config.limits.maxObjectMiB * 1024 * 1024 });
+    await api.ready;
+    // The viewer's config reads this to proxy /api, and to write the same page config a server would.
+    process.env.ATLAS_API_URL = running.url.replace('localhost', '127.0.0.1');
+    process.env.INIT_CWD = cwd;
+    const { createServer } = await import('vite');
+    const vite = await createServer({
+        configFile: path.join(root, 'vite.config.ts'),
+        configLoader: 'runner',
+        root,
+        server: { port: publicPort, host: config.host, strictPort: false }
+    });
+    await vite.listen();
+    vite.printUrls();
+    io.out(`Data in ${path.relative(cwd, config.data) || config.data}. Publish with: ATLAS_STORE=${vite.resolvedUrls?.local[0] ?? `http://localhost:${publicPort}`} atlas report publish …\n`);
+    await new Promise(resolve => {
+        io.signal?.addEventListener('abort', () => resolve(), { once: true });
+        if (!io.signal) {
+            process.once('SIGTERM', () => resolve());
+            process.once('SIGINT', () => resolve());
+        }
+    });
+    api.close();
+    await vite.close();
+    await running.close(2_000);
+    return 0;
+}

package/dist/server/src/events.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @module Server-sent events
+ *
+ * What the server tells every connected viewer the moment it happens. A viewer that misses some (a dropped connection, a
+ * laptop that slept) loses nothing: events say "something changed", the state is always fetched, and a viewer reads again
+ * when it reconnects. `EventHub` encodes each event once for all viewers, sends a named `ping` every heartbeat so proxies
+ * keep the connection and a quiet server is told apart from a dead one, refuses past a maximum number of viewers (they poll
+ * instead), and lets go of a viewer that has stopped reading rather than hold its backlog.
+ *
+ * @see docs/server.md#streaming
+ */
+/** The events the server publishes: `hello` (sent first to a new viewer), `report` (layers arrived) and `atlas:change` (specs or runs changed). `ping` is the heartbeat, sent by the hub itself. */
+export type EventName = 'hello' | 'report' | 'atlas:change';
+/** The viewers connected to `/api/events` and how to reach them all. One hub per server. */
+export declare class EventHub {
+    #private;
+    constructor(options?: {
+        readonly maxSubscribers?: number;
+        readonly heartbeatMs?: number;
+    });
+    /** How many viewers are connected right now. */
+    get count(): number;
+    /** Tell every viewer. `data` is JSON. */
+    publish(name: EventName, data: unknown): void;
+    /** A stream for one viewer, starting with `hello` (what `greeting` returns). It ends when the viewer goes. */
+    stream(request: Request, greeting: () => unknown): Response;
+    /** End every stream, for shutting down. */
+    close(): void;
+}

package/dist/server/src/events.js

@@ -0,0 +1,101 @@
+/**
+ * @module Server-sent events
+ *
+ * What the server tells every connected viewer the moment it happens. A viewer that misses some (a dropped connection, a
+ * laptop that slept) loses nothing: events say "something changed", the state is always fetched, and a viewer reads again
+ * when it reconnects. `EventHub` encodes each event once for all viewers, sends a named `ping` every heartbeat so proxies
+ * keep the connection and a quiet server is told apart from a dead one, refuses past a maximum number of viewers (they poll
+ * instead), and lets go of a viewer that has stopped reading rather than hold its backlog.
+ *
+ * @see docs/server.md#streaming
+ */
+/** Events a viewer may be behind by before it is let go. */
+const MAX_BACKLOG = 256;
+/** The viewers connected to `/api/events` and how to reach them all. One hub per server. */
+export class EventHub {
+    #subscribers = new Set();
+    #max;
+    #heartbeatMs;
+    #encoder = new TextEncoder();
+    #id = 0;
+    #timer = null;
+    constructor(options = {}) {
+        this.#max = options.maxSubscribers ?? 500;
+        this.#heartbeatMs = options.heartbeatMs ?? 15_000;
+    }
+    /** How many viewers are connected right now. */
+    get count() {
+        return this.#subscribers.size;
+    }
+    /** Tell every viewer. `data` is JSON. */
+    publish(name, data) {
+        this.#id += 1;
+        // Written once, however many are listening.
+        const frame = this.#encoder.encode(`id: ${this.#id}\nevent: ${name}\ndata: ${JSON.stringify(data)}\n\n`);
+        for (const subscriber of [...this.#subscribers])
+            subscriber.send(frame);
+    }
+    /** A stream for one viewer, starting with `hello` (what `greeting` returns). It ends when the viewer goes. */
+    stream(request, greeting) {
+        if (this.#subscribers.size >= this.#max)
+            return Response.json({ error: 'Too many viewers are connected for live updates; they will poll instead.' }, { status: 503, headers: { 'retry-after': '30' } });
+        let subscriber = null;
+        const body = new ReadableStream({
+            start: (controller) => {
+                const send = (chunk) => {
+                    try {
+                        // A viewer that has stopped reading (a laptop asleep, a dead connection) must not make the server hold its backlog: it reconnects and reads everything again.
+                        if ((controller.desiredSize ?? 1) < -MAX_BACKLOG) {
+                            drop();
+                            controller.close();
+                            return;
+                        }
+                        controller.enqueue(chunk);
+                    }
+                    catch {
+                        drop();
+                    }
+                };
+                const drop = () => { if (subscriber)
+                    this.#subscribers.delete(subscriber); subscriber = null; if (!this.#subscribers.size)
+                    this.#stopTimer(); };
+                subscriber = { send, close: () => { drop(); try {
+                        controller.close();
+                    }
+                    catch { /* already closed */ } } };
+                this.#subscribers.add(subscriber);
+                this.#startTimer();
+                // `retry` is how long the browser waits before reconnecting by itself.
+                send(this.#encoder.encode(`retry: 3000\n\n`));
+                this.#id += 1;
+                send(this.#encoder.encode(`id: ${this.#id}\nevent: hello\ndata: ${JSON.stringify(greeting())}\n\n`));
+                request.signal.addEventListener('abort', drop, { once: true });
+            },
+            cancel: () => { if (subscriber)
+                this.#subscribers.delete(subscriber); subscriber = null; if (!this.#subscribers.size)
+                this.#stopTimer(); }
+        });
+        return new Response(body, { headers: { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache, no-transform', connection: 'keep-alive', 'x-accel-buffering': 'no' } });
+    }
+    #startTimer() {
+        if (this.#timer)
+            return;
+        // A named event, not a comment: proxies see traffic, and the viewer (which a browser does not tell about comments) can tell a quiet
+        // server from a dead connection.
+        const ping = this.#encoder.encode('event: ping\ndata: {}\n\n');
+        this.#timer = setInterval(() => { for (const subscriber of [...this.#subscribers])
+            subscriber.send(ping); }, this.#heartbeatMs);
+        this.#timer.unref?.();
+    }
+    #stopTimer() {
+        if (this.#timer)
+            clearInterval(this.#timer);
+        this.#timer = null;
+    }
+    /** End every stream, for shutting down. */
+    close() {
+        for (const subscriber of [...this.#subscribers])
+            subscriber.close();
+        this.#stopTimer();
+    }
+}

package/dist/server/src/host.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @module HTTP host for a fetch handler
+ *
+ * `listen` serves any `(Request) => Promise<Response>` over HTTP: with `Bun.serve` when running on Bun, with a `node:http`
+ * bridge (streaming bodies in and out, so server-sent events work) everywhere else. The server's behaviour is the same on
+ * both; `bun run release:smoke` proves it under each. Bodies over `maxBodyBytes` are refused by the runtime before the
+ * handler sees them.
+ */
+/** A server that is listening: the `port` it got (useful when asked for `0`), its `url`, and `close`. */
+export type RunningServer = {
+    readonly port: number;
+    readonly url: string;
+    /** Stop accepting, let requests in flight finish for up to `graceMs`, then end what is left. */
+    close(graceMs?: number): Promise<void>;
+};
+/** Where to listen (`port`, `host`) and the largest request body the runtime will accept. */
+export type ListenOptions = {
+    readonly port: number;
+    readonly host: string;
+    /** The largest request body to read, in bytes. */
+    readonly maxBodyBytes: number;
+};
+type Handler = (request: Request) => Promise<Response> | Response;
+/**
+ * Serve a fetch handler. On Bun, which is what Atlas is made for, that is `Bun.serve`: one native server for the
+ * API, the live streams and the page. On Node it is the same handler behind `node:http`, so the package still runs
+ * where Bun is not installed.
+ */
+export declare function listen(handler: Handler, options: ListenOptions): Promise<RunningServer>;
+export {};

package/dist/server/src/host.js

@@ -0,0 +1,115 @@
+/**
+ * @module HTTP host for a fetch handler
+ *
+ * `listen` serves any `(Request) => Promise<Response>` over HTTP: with `Bun.serve` when running on Bun, with a `node:http`
+ * bridge (streaming bodies in and out, so server-sent events work) everywhere else. The server's behaviour is the same on
+ * both; `bun run release:smoke` proves it under each. Bodies over `maxBodyBytes` are refused by the runtime before the
+ * handler sees them.
+ */
+import { createServer } from 'node:http';
+import { Readable } from 'node:stream';
+const display = (host, port) => `http://${host === '0.0.0.0' || host === '::' ? 'localhost' : host}:${port}`;
+/**
+ * Serve a fetch handler. On Bun, which is what Atlas is made for, that is `Bun.serve`: one native server for the
+ * API, the live streams and the page. On Node it is the same handler behind `node:http`, so the package still runs
+ * where Bun is not installed.
+ */
+export async function listen(handler, options) {
+    const bun = getBun();
+    if (bun)
+        return listenBun(bun, handler, options);
+    return listenNode(handler, options);
+}
+const getBun = () => globalThis.Bun;
+async function listenBun(bun, handler, options) {
+    const server = bun.serve({
+        port: options.port,
+        hostname: options.host,
+        // Live streams are quiet between heartbeats; the longest idle time Bun allows keeps them open.
+        idleTimeout: 120,
+        maxRequestBodySize: options.maxBodyBytes + 1024 * 1024,
+        fetch: handler,
+        error: (error) => Response.json({ error: error.message }, { status: 500 })
+    });
+    return {
+        port: server.port,
+        url: display(options.host, server.port),
+        close: async (graceMs = 10_000) => {
+            // Stop taking new connections and let requests in flight finish; end the rest after the grace period.
+            const closing = Promise.resolve(server.stop(false));
+            const timer = setTimeout(() => { void server.stop(true); }, graceMs);
+            timer.unref?.();
+            await closing;
+            clearTimeout(timer);
+        }
+    };
+}
+function toRequest(req, host, maxBodyBytes) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers))
+        if (value !== undefined)
+            headers.set(name, Array.isArray(value) ? value.join(', ') : value);
+    const method = req.method ?? 'GET';
+    const hasBody = method !== 'GET' && method !== 'HEAD';
+    let size = 0;
+    const body = hasBody ? Readable.toWeb(req).pipeThrough(new TransformStream({ transform(chunk, controller) { size += chunk.byteLength; if (size > maxBodyBytes)
+            controller.error(new Error('The request body is too large'));
+        else
+            controller.enqueue(chunk); } })) : null;
+    return new Request(`http://${req.headers.host ?? host}${req.url ?? '/'}`, { method, headers, ...(body ? { body, duplex: 'half' } : {}) });
+}
+async function send(response, res, head) {
+    const headers = {};
+    response.headers.forEach((value, name) => { headers[name] = value; });
+    const cookies = response.headers.getSetCookie?.();
+    if (cookies?.length)
+        headers['set-cookie'] = cookies;
+    res.writeHead(response.status, headers);
+    if (head || !response.body) {
+        res.end();
+        return;
+    }
+    const reader = response.body.getReader();
+    res.on('close', () => { void reader.cancel().catch(() => { }); });
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (!res.write(value))
+            await new Promise(resolve => res.once('drain', resolve));
+    }
+    res.end();
+}
+async function listenNode(handler, options) {
+    const server = createServer((req, res) => {
+        void (async () => {
+            const controller = new AbortController();
+            res.on('close', () => controller.abort());
+            try {
+                const request = toRequest(req, options.host, options.maxBodyBytes);
+                const abortable = new Request(request, { signal: controller.signal });
+                await send(await handler(abortable), res, req.method === 'HEAD');
+            }
+            catch (error) {
+                if (!res.headersSent)
+                    await send(Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 500 }), res, false).catch(() => { });
+                else
+                    res.destroy();
+            }
+        })();
+    });
+    server.keepAliveTimeout = 65_000;
+    server.requestTimeout = 0;
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(options.port, options.host, resolve); });
+    const port = server.address().port;
+    return {
+        port,
+        url: display(options.host, port),
+        close: (graceMs = 10_000) => new Promise(resolve => {
+            server.close(() => resolve());
+            server.closeIdleConnections?.();
+            const timer = setTimeout(() => { server.closeAllConnections?.(); }, graceMs);
+            timer.unref?.();
+        })
+    };
+}

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

@@ -0,0 +1,16 @@
+/**
+ * @module Server package entry point (`@crvouga/atlas/server`)
+ *
+ * Everything needed to run the Atlas server from code: `createAtlasServer` (a `fetch` handler with the live report, uploads
+ * and the viewer), `listen` (serve it over HTTP on Bun or Node), `loadServerConfig` (the file, the environment and the flags
+ * as one checked configuration), `serveMain` (what `atlas serve` runs), `EventHub`, `createAuth`, and the upload checks.
+ *
+ * @see docs/server.md
+ */
+export { createAtlasServer, type AtlasServer, type AtlasServerOptions } from './app.js';
+export { createAuth, type Auth, type Identity } from './auth.js';
+export { assertSafeToListen, ConfigError, loadServerConfig, SERVER_USAGE, type ResolvedServerConfig, type ResolvedToken } from './config.js';
+export { EventHub, type EventName } from './events.js';
+export { listen, type RunningServer } from './host.js';
+export { serveMain } from './main.js';
+export { classify, validateUpload, validKey, Refusal } from './validate.js';

package/dist/server/src/index.js

@@ -0,0 +1,16 @@
+/**
+ * @module Server package entry point (`@crvouga/atlas/server`)
+ *
+ * Everything needed to run the Atlas server from code: `createAtlasServer` (a `fetch` handler with the live report, uploads
+ * and the viewer), `listen` (serve it over HTTP on Bun or Node), `loadServerConfig` (the file, the environment and the flags
+ * as one checked configuration), `serveMain` (what `atlas serve` runs), `EventHub`, `createAuth`, and the upload checks.
+ *
+ * @see docs/server.md
+ */
+export { createAtlasServer } from './app.js';
+export { createAuth } from './auth.js';
+export { assertSafeToListen, ConfigError, loadServerConfig, SERVER_USAGE } from './config.js';
+export { EventHub } from './events.js';
+export { listen } from './host.js';
+export { serveMain } from './main.js';
+export { classify, validateUpload, validKey, Refusal } from './validate.js';

package/dist/server/src/llms.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @module llms.txt of a running server
+ *
+ * The plain-text guide ([llms.txt](https://llmstxt.org)) a server serves about itself at `GET /llms.txt`, for an AI
+ * agent that was handed nothing but the server's address. It is written from this server's own settings (its
+ * address, whether it needs a token), so what it says is true of the server that says it, and it points at the
+ * machine-readable description (`/api/openapi.json`) rather than repeating it.
+ */
+/** What the guide says about the server that serves it. */
+export type LlmsContext = {
+    /** The address clients use, such as `https://atlas.example.com`, no trailing slash. */
+    readonly url: string;
+    /** True when the server has no tokens: anyone who can reach it may upload. */
+    readonly open: boolean;
+    /** The id of the backend uploads go to. */
+    readonly write: string;
+};
+/** The guide for one server, Markdown. Stable in structure: an agent may read it by its headings. */
+export declare function llmsTxt(context: LlmsContext): string;