@wpelevator/tug 0.2.1 → 0.3.0

package/dist/db.d.ts

@@ -17,6 +17,7 @@ export interface NodeRow {
     ingress: number;
     ingress_status_json: string | null;
     status: string;
+    labels_json: string | null;
     agent_token_hash: string | null;
     registry_token_hash: string | null;
     last_seen_at: string | null;

package/dist/db.js

@@ -34,7 +34,7 @@ async function migrate(db) {
     await db.exec(`
 CREATE TABLE IF NOT EXISTS meta(key TEXT PRIMARY KEY, value TEXT NOT NULL);
 CREATE TABLE IF NOT EXISTS projects(id TEXT PRIMARY KEY, name TEXT UNIQUE NOT NULL, current_deployment_id TEXT, created_at TEXT, updated_at TEXT);
-CREATE TABLE IF NOT EXISTS nodes(id TEXT PRIMARY KEY, name TEXT UNIQUE NOT NULL, address TEXT, public_address TEXT, overlay_ip TEXT UNIQUE, ingress INTEGER NOT NULL DEFAULT 0, ingress_status_json TEXT, status TEXT, agent_token_hash TEXT, registry_token_hash TEXT, last_seen_at TEXT, created_at TEXT, updated_at TEXT);
+CREATE TABLE IF NOT EXISTS nodes(id TEXT PRIMARY KEY, name TEXT UNIQUE NOT NULL, address TEXT, public_address TEXT, overlay_ip TEXT UNIQUE, ingress INTEGER NOT NULL DEFAULT 0, ingress_status_json TEXT, status TEXT, labels_json TEXT, agent_token_hash TEXT, registry_token_hash TEXT, last_seen_at TEXT, created_at TEXT, updated_at TEXT);
 CREATE TABLE IF NOT EXISTS wg_peers(node_id TEXT PRIMARY KEY, public_key TEXT NOT NULL UNIQUE, overlay_ip TEXT NOT NULL, endpoint TEXT, allowed_ips TEXT NOT NULL, updated_at TEXT);
 CREATE TABLE IF NOT EXISTS enroll_tokens(token_hash TEXT PRIMARY KEY, name TEXT, uses_remaining INTEGER, expires_at TEXT, created_at TEXT);
 CREATE TABLE IF NOT EXISTS deployments(id TEXT PRIMARY KEY, project_id TEXT, version TEXT, state TEXT, created_at TEXT, updated_at TEXT, error_message TEXT, actor TEXT);
@@ -51,6 +51,12 @@ CREATE TABLE IF NOT EXISTS api_tokens(id TEXT PRIMARY KEY, name TEXT UNIQUE NOT
 CREATE INDEX IF NOT EXISTS events_by_time ON events(created_at);
 CREATE TABLE IF NOT EXISTS locks(name TEXT PRIMARY KEY, owner TEXT, expires_at TEXT, created_at TEXT);
 `);
+    try {
+        await db.exec('ALTER TABLE nodes ADD COLUMN labels_json TEXT');
+    }
+    catch {
+        /* column already exists */
+    }
     const row = await db.get('SELECT value FROM meta WHERE key = ?', 'schema_created_at');
     if (!row)
         await db.run('INSERT INTO meta(key,value) VALUES(?,?)', 'schema_created_at', now());

package/dist/ingress.d.ts

@@ -23,13 +23,21 @@ export declare function resolveServiceEndpoints(states: DesiredState[], nodes: N
 export interface IngressInput {
     states: DesiredState[];
     endpoints: ServiceEndpoints;
-    /** The ingress node being configured; its own upstreams are reached on loopback. */
+    /** The ingress node being configured. */
     node: string;
+    /** Every node name, and the ingress nodes; they decide which services on `node` listen on loopback only. */
+    nodes?: string[];
+    ingressNodes?: string[];
     /** Decrypted project secrets for custom TLS, keyed `<project>/<secret name>`. */
     secrets: Map<string, string>;
     acmeEmail?: string;
 }
-export declare function buildIngressWork({ states, endpoints, node, secrets, acmeEmail }: IngressInput): IngressWork;
+/**
+ * Upstreams on the ingress node itself are dialed on `127.0.0.1` when the service's ingress port
+ * listens on loopback only (see `loopbackIngressServices`), otherwise on the address its published
+ * ports are bound to, which is the endpoint address, like every other node.
+ */
+export declare function buildIngressWork({ states, endpoints, node, nodes, ingressNodes, secrets, acmeEmail, }: IngressInput): IngressWork;
 export declare function renderCaddyfile(routes: IngressRoute[], opts?: {
     acmeEmail?: string;
 }): string;

package/dist/ingress.js

@@ -4,7 +4,7 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { publishedPort } from "./compose.js";
+import { loopbackIngressServices, publishedPort } from "./compose.js";
 import { ensureDir, errMessage } from "./util.js";
 export const CADDY_CONTAINER = 'tug-caddy';
 export const DEFAULT_CADDY_IMAGE = 'caddy:2-alpine';
@@ -15,8 +15,8 @@ const CADDY_ETC = '/etc/caddy';
  * rollout state drops, which is what makes DNS and ingress health-aware.
  */
 export function resolveServiceEndpoints(states, nodes, statuses, staleBefore) {
-    const byName = new Map(nodes.map(n => [n.name, n]));
-    const reported = new Map(statuses.map(s => [`${s.node}\0${s.project}`, s.status]));
+    const byName = new Map(nodes.map((n) => [n.name, n]));
+    const reported = new Map(statuses.map((s) => [`${s.node}\0${s.project}`, s.status]));
     const out = {};
     for (const state of states) {
         for (const [service, spec] of Object.entries(state.services)) {
@@ -30,7 +30,11 @@ export function resolveServiceEndpoints(states, nodes, statuses, staleBefore) {
                 if (serviceState?.rolloutState !== 'serving')
                     continue;
                 // Rolling services publish each revision on its own host port; the report names the serving one.
-                endpoints.push({ node: nodeName, address, ...(serviceState.port ? { port: serviceState.port } : {}) });
+                endpoints.push({
+                    node: nodeName,
+                    address,
+                    ...(serviceState.port ? { port: serviceState.port } : {}),
+                });
             }
             if (endpoints.length)
                 (out[state.project] ||= {})[service] = endpoints.sort((a, b) => a.node.localeCompare(b.node));
@@ -39,21 +43,33 @@ export function resolveServiceEndpoints(states, nodes, statuses, staleBefore) {
     return out;
 }
 const certFile = (host, ext) => `certs/${host.replace(/\*/g, '_wildcard_')}.${ext}`;
-export function buildIngressWork({ states, endpoints, node, secrets, acmeEmail }) {
+/**
+ * Upstreams on the ingress node itself are dialed on `127.0.0.1` when the service's ingress port
+ * listens on loopback only (see `loopbackIngressServices`), otherwise on the address its published
+ * ports are bound to, which is the endpoint address, like every other node.
+ */
+export function buildIngressWork({ states, endpoints, node, nodes = [node], ingressNodes = [node], secrets, acmeEmail, }) {
     const routes = [];
     const files = {};
     const warnings = [];
     const seenHosts = new Map();
     const tagged = [];
     for (const state of states) {
+        const loopback = new Set(loopbackIngressServices(state, node, ingressNodes, nodes));
         for (const [service, svc] of Object.entries(state.compose.services || {})) {
             const ingress = svc['x-tug']?.ingress;
             if (ingress)
-                tagged.push({ project: state.project, service, ingress, port: publishedPort(svc, ingress.port) });
+                tagged.push({
+                    project: state.project,
+                    service,
+                    ingress,
+                    port: publishedPort(svc, ingress.port),
+                    loopback: loopback.has(service),
+                });
         }
     }
     tagged.sort((a, b) => `${a.project}/${a.service}`.localeCompare(`${b.project}/${b.service}`));
-    for (const { project, service, ingress, port } of tagged) {
+    for (const { project, service, ingress, port, loopback } of tagged) {
         const label = `${project}/${service}`;
         const host = ingress.host.toLowerCase();
         const tls = ingress.tls || 'auto';
@@ -65,7 +81,7 @@ export function buildIngressWork({ states, endpoints, node, secrets, acmeEmail }
             warnings.push(`${label}: ingress.port ${ingress.port} is not published; skipped`);
             continue;
         }
-        const upstreams = (endpoints[project]?.[service] || []).map(e => `${e.node === node ? '127.0.0.1' : e.address}:${e.port ?? port}`);
+        const upstreams = (endpoints[project]?.[service] || []).map((e) => `${e.node === node && loopback ? '127.0.0.1' : upstreamHost(e.address)}:${e.port ?? port}`);
         if (!upstreams.length) {
             warnings.push(`${label}: no serving upstream for ${host}; route withheld`);
             continue;
@@ -85,6 +101,8 @@ export function buildIngressWork({ states, endpoints, node, secrets, acmeEmail }
     }
     return { caddyfile: renderCaddyfile(routes, { acmeEmail }), files, routes, warnings };
 }
+/** IPv6 upstream addresses need brackets before the port. */
+const upstreamHost = (address) => address.includes(':') && !address.startsWith('[') ? `[${address}]` : address;
 export function renderCaddyfile(routes, opts = {}) {
     const out = [];
     if (opts.acmeEmail)
@@ -127,18 +145,30 @@ export async function reconcileIngress(ctx, work) {
     const applied = path.join(root, 'applied');
     const configHash = ingressConfigHash(work);
     const routes = work.routes.length;
-    const running = await ctx.docker(['container', 'inspect', '-f', '{{.State.Running}}', CADDY_CONTAINER])
-        .then(r => r.out.trim() === 'true', () => null);
-    const appliedHash = await fs.readFile(path.join(root, 'applied.hash'), 'utf8').then(s => s.trim(), () => '');
+    const running = await ctx
+        .docker(['container', 'inspect', '-f', '{{.State.Running}}', CADDY_CONTAINER])
+        .then((r) => r.out.trim() === 'true', () => null);
+    const appliedHash = await fs.readFile(path.join(root, 'applied.hash'), 'utf8').then((s) => s.trim(), () => '');
     if (running && appliedHash === configHash)
         return { state: 'serving', configHash, routes };
     await writeStage(stage, work);
     try {
         if (running === null) {
             await ctx.docker([
-                'create', '--name', CADDY_CONTAINER, '--restart', 'unless-stopped', '--network', 'host',
-                '-v', 'tug-caddy-data:/data', '-v', 'tug-caddy-config:/config', '-v', `tug-caddy-etc:${CADDY_ETC}`,
-                ctx.caddyImage || DEFAULT_CADDY_IMAGE
+                'create',
+                '--name',
+                CADDY_CONTAINER,
+                '--restart',
+                'unless-stopped',
+                '--network',
+                'host',
+                '-v',
+                'tug-caddy-data:/data',
+                '-v',
+                'tug-caddy-config:/config',
+                '-v',
+                `tug-caddy-etc:${CADDY_ETC}`,
+                ctx.caddyImage || DEFAULT_CADDY_IMAGE,
             ]);
             await ctx.docker(['cp', `${stage}/.`, `${CADDY_CONTAINER}:${CADDY_ETC}/`]);
             await ctx.docker(['start', CADDY_CONTAINER]);
@@ -151,11 +181,22 @@ export async function reconcileIngress(ctx, work) {
             try {
                 await ctx.docker(['exec', CADDY_CONTAINER, 'rm', '-rf', `${CADDY_ETC}/certs`]);
                 await ctx.docker(['cp', `${stage}/.`, `${CADDY_CONTAINER}:${CADDY_ETC}/`]);
-                await ctx.docker(['exec', CADDY_CONTAINER, 'caddy', 'reload', '--config', `${CADDY_ETC}/Caddyfile`, '--adapter', 'caddyfile']);
+                await ctx.docker([
+                    'exec',
+                    CADDY_CONTAINER,
+                    'caddy',
+                    'reload',
+                    '--config',
+                    `${CADDY_ETC}/Caddyfile`,
+                    '--adapter',
+                    'caddyfile',
+                ]);
             }
             catch (e) {
                 if (await fs.stat(applied).then(() => true, () => false))
-                    await ctx.docker(['cp', `${applied}/.`, `${CADDY_CONTAINER}:${CADDY_ETC}/`]).catch(() => { });
+                    await ctx
+                        .docker(['cp', `${applied}/.`, `${CADDY_CONTAINER}:${CADDY_ETC}/`])
+                        .catch(() => { });
                 throw e;
             }
         }

package/dist/live.d.ts

@@ -0,0 +1,80 @@
+import { EventEmitter } from 'node:events';
+import type { Readable, Writable } from 'node:stream';
+export interface LiveProcess extends EventEmitter {
+    stdin: Writable | null;
+    stdout: Readable | null;
+    stderr: Readable | null;
+    kill(signal?: NodeJS.Signals): boolean;
+    /** PTY adapters implement this in terminal columns and rows. */
+    resize?(columns: number, rows: number): void;
+}
+export type LiveSpawn = (file: string, args: string[]) => LiveProcess;
+export type LiveRequest = {
+    operation: 'exec';
+    sessionId: string;
+    container: string;
+    command: string[];
+    interactive?: boolean;
+    tty?: boolean;
+    columns?: number;
+    rows?: number;
+} | {
+    operation: 'logs';
+    sessionId: string;
+    container: string;
+    tail?: number;
+    timestamps?: boolean;
+} | {
+    operation: 'ps';
+    sessionId: string;
+    projects: string[];
+} | {
+    operation: 'inspect';
+    sessionId: string;
+    container: string;
+};
+export type LiveEvent = {
+    sessionId: string;
+    type: 'output';
+    stream: 'stdout' | 'stderr';
+    data: string;
+    encoding: 'base64';
+} | {
+    sessionId: string;
+    type: 'result';
+    result: Record<string, unknown>[];
+} | {
+    sessionId: string;
+    type: 'exit';
+    code: number | null;
+    signal: string | null;
+    cancelled: boolean;
+    error?: string;
+};
+export interface LiveEngineOptions {
+    emit: (event: LiveEvent) => void;
+    spawn?: LiveSpawn;
+    /** A real PTY adapter is required for interactive Docker exec. */
+    spawnTty?: LiveSpawn;
+    maxSessions?: number;
+    maxResultBytes?: number;
+    maxSessionMs?: number;
+    queryTimeoutMs?: number;
+}
+/** Owns Docker process lifetimes; callers own authentication, authorization and transport backpressure. */
+export declare class LiveOperationEngine {
+    private readonly options;
+    private readonly sessions;
+    constructor(options: LiveEngineOptions);
+    get activeSessions(): number;
+    start(value: unknown): void;
+    /** Returns the writable backpressure signal; callers must pause transport input on false. */
+    stdin(sessionId: string, data: Uint8Array): boolean;
+    endStdin(sessionId: string): void;
+    resize(sessionId: string, columns: number, rows: number): void;
+    cancel(sessionId: string): void;
+    dispose(): void;
+    private requireExec;
+    private output;
+    private finish;
+}

package/dist/live.js

@@ -0,0 +1,340 @@
+import { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { PassThrough } from 'node:stream';
+import { LIVE_MAX_FRAME_BYTES } from "./protocol.js";
+const identifier = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,255}$/;
+function object(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function dimension(value) {
+    return Number.isInteger(value) && Number(value) >= 1 && Number(value) <= 1000;
+}
+function validate(value) {
+    if (!object(value) || typeof value.sessionId !== 'string' || !identifier.test(value.sessionId))
+        throw new Error('Invalid live session ID');
+    if (!['exec', 'logs', 'ps', 'inspect'].includes(String(value.operation)))
+        throw new Error('Invalid live operation');
+    if (value.operation !== 'ps' &&
+        (typeof value.container !== 'string' || !identifier.test(value.container)))
+        throw new Error('Invalid container');
+    if (value.operation === 'exec') {
+        if (!Array.isArray(value.command) ||
+            value.command.length < 1 ||
+            value.command.length > 256 ||
+            !value.command.every((arg) => typeof arg === 'string' && !arg.includes('\0') && Buffer.byteLength(arg) <= 32768) ||
+            value.command[0].length === 0)
+            throw new Error('Invalid exec command');
+        if (value.interactive !== undefined && typeof value.interactive !== 'boolean')
+            throw new Error('Invalid interactive flag');
+        if (value.tty !== undefined && typeof value.tty !== 'boolean')
+            throw new Error('Invalid TTY flag');
+        if ((value.columns !== undefined && !dimension(value.columns)) ||
+            (value.rows !== undefined && !dimension(value.rows)))
+            throw new Error('Invalid terminal dimensions');
+    }
+    if (value.operation === 'logs') {
+        if (value.tail !== undefined &&
+            (!Number.isInteger(value.tail) || Number(value.tail) < 0 || Number(value.tail) > 10000))
+            throw new Error('Invalid log tail');
+        if (value.timestamps !== undefined && typeof value.timestamps !== 'boolean')
+            throw new Error('Invalid timestamps flag');
+    }
+    if (value.operation === 'ps' &&
+        (!Array.isArray(value.projects) ||
+            value.projects.length < 1 ||
+            value.projects.length > 256 ||
+            !value.projects.every((project) => typeof project === 'string' && identifier.test(project))))
+        throw new Error('Invalid projects');
+}
+function argv(request) {
+    switch (request.operation) {
+        case 'exec':
+            return [
+                'exec',
+                ...(request.interactive === false ? [] : ['-i']),
+                ...(request.tty ? ['-t'] : []),
+                request.container,
+                ...request.command,
+            ];
+        case 'logs':
+            return [
+                'logs',
+                '--follow',
+                '--tail',
+                String(request.tail ?? 100),
+                ...(request.timestamps ? ['--timestamps'] : []),
+                request.container,
+            ];
+        case 'ps':
+            return [
+                'ps',
+                '--all',
+                '--no-trunc',
+                '--format',
+                '{{json .}}',
+                '--filter',
+                `label=com.docker.compose.project=${request.projects[0]}`,
+            ];
+        case 'inspect':
+            return ['inspect', '--type', 'container', request.container];
+    }
+}
+/** Execute exact project-label queries sequentially; Docker label predicates must not broaden project scope. */
+function spawnProjectQueries(spawnProcess, request) {
+    const projects = [...new Set(request.projects)];
+    const stdout = new PassThrough();
+    const stderr = new PassThrough();
+    let current;
+    let stopped = false;
+    let detachOutput = () => { };
+    const process = Object.assign(new EventEmitter(), {
+        stdin: null,
+        stdout,
+        stderr,
+        kill(signal) {
+            stopped = true;
+            detachOutput();
+            return current.kill(signal);
+        },
+    });
+    const next = () => {
+        const child = spawnProcess('docker', argv({ ...request, projects: [projects.shift()] }));
+        current = child;
+        const out = (data) => {
+            stdout.write(data);
+        };
+        const err = (data) => {
+            stderr.write(data);
+        };
+        const error = (cause) => {
+            process.emit('error', cause);
+        };
+        const close = (code, signal) => {
+            child.off('error', error).off('close', close);
+            child.stdout?.off('data', out);
+            child.stderr?.off('data', err);
+            if (!stopped && code === 0 && projects.length) {
+                stdout.write('\n');
+                if (stopped) {
+                    process.emit('close', null, null);
+                    return;
+                }
+                try {
+                    next();
+                }
+                catch (cause) {
+                    process.emit('error', cause);
+                }
+            }
+            else
+                process.emit('close', code, signal);
+        };
+        detachOutput = () => {
+            child.stdout?.off('data', out);
+            child.stderr?.off('data', err);
+        };
+        child.stdout?.on('data', out);
+        child.stderr?.on('data', err);
+        child.on('error', error).on('close', close);
+    };
+    next();
+    return process;
+}
+/** Owns Docker process lifetimes; callers own authentication, authorization and transport backpressure. */
+export class LiveOperationEngine {
+    options;
+    sessions = new Map();
+    constructor(options) {
+        for (const key of [
+            'maxSessions',
+            'maxResultBytes',
+            'maxSessionMs',
+            'queryTimeoutMs',
+        ]) {
+            if (options[key] !== undefined && (!Number.isSafeInteger(options[key]) || options[key] < 1))
+                throw new Error(`Invalid ${key}`);
+        }
+        this.options = options;
+    }
+    get activeSessions() {
+        return this.sessions.size;
+    }
+    start(value) {
+        validate(value);
+        if (this.sessions.has(value.sessionId))
+            throw new Error('Duplicate live session ID');
+        if (this.sessions.size >= (this.options.maxSessions ?? 16))
+            throw new Error('Live session limit reached');
+        const request = structuredClone(value);
+        const spawnProcess = request.operation === 'exec' && request.tty
+            ? this.options.spawnTty
+            : (this.options.spawn ??
+                ((file, args) => spawn(file, args, { stdio: 'pipe', shell: false })));
+        if (!spawnProcess)
+            throw new Error('TTY exec requires a PTY adapter');
+        const child = request.operation === 'ps' && request.projects.length > 1
+            ? spawnProjectQueries(spawnProcess, request)
+            : spawnProcess('docker', argv(request));
+        const query = request.operation === 'ps' || request.operation === 'inspect';
+        const onError = (error) => {
+            if (this.sessions.get(request.sessionId)?.child === child)
+                this.finish(request.sessionId, null, null, false, error.message, true);
+        };
+        const stopErrors = () => {
+            child.off('error', onError).off('close', onClose);
+            child.stdin?.off('error', onError);
+        };
+        const onClose = (code, signal) => {
+            stopErrors();
+            if (this.sessions.get(request.sessionId)?.child === child)
+                this.finish(request.sessionId, code, signal, false);
+        };
+        const stdout = (data) => this.output(request.sessionId, 'stdout', data);
+        const stderr = (data) => this.output(request.sessionId, 'stderr', data);
+        const timer = setTimeout(() => this.finish(request.sessionId, null, null, false, 'Live operation timed out', true), query ? (this.options.queryTimeoutMs ?? 30000) : (this.options.maxSessionMs ?? 3600000));
+        timer.unref();
+        this.sessions.set(request.sessionId, {
+            request,
+            child,
+            timer,
+            output: [],
+            errorOutput: [],
+            bytes: 0,
+            cleanup: (awaitClose = false) => {
+                clearTimeout(timer);
+                if (!awaitClose)
+                    stopErrors();
+                child.stdout?.off('data', stdout);
+                child.stderr?.off('data', stderr);
+            },
+        });
+        child.on('error', onError).on('close', onClose);
+        child.stdout?.on('data', stdout);
+        child.stderr?.on('data', stderr);
+        child.stdin?.on('error', onError);
+        if (request.operation === 'exec' && request.interactive === false)
+            child.stdin?.end();
+        if (request.operation === 'exec' && request.tty) {
+            if (!child.resize) {
+                this.finish(request.sessionId, null, null, false, 'PTY adapter does not support resize', true);
+                return;
+            }
+            try {
+                child.resize(request.columns ?? 80, request.rows ?? 24);
+            }
+            catch (error) {
+                onError(error instanceof Error ? error : new Error(String(error)));
+            }
+        }
+    }
+    /** Returns the writable backpressure signal; callers must pause transport input on false. */
+    stdin(sessionId, data) {
+        const session = this.requireExec(sessionId);
+        if (!(data instanceof Uint8Array) || data.byteLength > 65536)
+            throw new Error('Invalid stdin frame');
+        if (!session.child.stdin || session.child.stdin.destroyed || session.child.stdin.writableEnded)
+            throw new Error('Session stdin is closed');
+        if (session.child.stdin.writableLength + data.byteLength > 262144)
+            throw new Error('Live stdin queue exceeds size limit');
+        return session.child.stdin.write(data);
+    }
+    endStdin(sessionId) {
+        this.requireExec(sessionId).child.stdin?.end();
+    }
+    resize(sessionId, columns, rows) {
+        const session = this.requireExec(sessionId);
+        if (!dimension(columns) || !dimension(rows))
+            throw new Error('Invalid terminal dimensions');
+        if (!session.request.tty || !session.child.resize)
+            throw new Error('Session has no terminal');
+        session.child.resize(columns, rows);
+    }
+    cancel(sessionId) {
+        this.finish(sessionId, null, null, true, undefined, true);
+    }
+    dispose() {
+        for (const id of this.sessions.keys())
+            this.cancel(id);
+    }
+    requireExec(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session || session.request.operation !== 'exec')
+            throw new Error('Unknown exec session');
+        return session;
+    }
+    output(id, stream, data) {
+        const session = this.sessions.get(id);
+        if (!session)
+            return;
+        const bytes = Buffer.isBuffer(data) ? data : Buffer.from(data);
+        if (session.request.operation === 'ps' || session.request.operation === 'inspect') {
+            session.bytes += bytes.length;
+            if (session.bytes > (this.options.maxResultBytes ?? 4194304)) {
+                this.finish(id, null, null, false, 'Live result exceeds size limit', true);
+                return;
+            }
+            (stream === 'stdout' ? session.output : session.errorOutput).push(bytes);
+            return;
+        }
+        for (let offset = 0; offset < bytes.length && this.sessions.has(id); offset += 65536)
+            this.options.emit({
+                sessionId: id,
+                type: 'output',
+                stream,
+                data: bytes.subarray(offset, offset + 65536).toString('base64'),
+                encoding: 'base64',
+            });
+    }
+    finish(id, code, signal, cancelled, error, kill = false) {
+        const session = this.sessions.get(id);
+        if (!session)
+            return;
+        this.sessions.delete(id);
+        // Keep error handlers until close when killing: spawn errors and pending stdin errors can arrive after cancellation.
+        session.cleanup(kill);
+        if (kill) {
+            try {
+                session.child.kill('SIGKILL');
+            }
+            catch {
+                /* Already exited. */
+            }
+        }
+        if (!error &&
+            !cancelled &&
+            (session.request.operation === 'ps' || session.request.operation === 'inspect')) {
+            if (code !== 0)
+                error =
+                    Buffer.concat(session.errorOutput).toString('utf8').trim() ||
+                        `Docker exited with code ${code}`;
+            else {
+                try {
+                    const raw = Buffer.concat(session.output).toString('utf8').trim();
+                    const result = session.request.operation === 'ps'
+                        ? raw
+                            .split('\n')
+                            .filter(Boolean)
+                            .map((line) => JSON.parse(line))
+                        : JSON.parse(raw);
+                    if (!Array.isArray(result) || !result.every(object))
+                        throw new Error('Expected an array of container objects');
+                    const frame = { v: 1, type: 'live.result', sessionId: id, result };
+                    if (Buffer.byteLength(JSON.stringify(frame)) > LIVE_MAX_FRAME_BYTES)
+                        throw new Error('Live result exceeds serialized frame size limit');
+                    this.options.emit({ sessionId: id, type: 'result', result });
+                }
+                catch (cause) {
+                    error = `Invalid Docker result: ${cause instanceof Error ? cause.message : String(cause)}`;
+                }
+            }
+        }
+        this.options.emit({
+            sessionId: id,
+            type: 'exit',
+            code,
+            signal,
+            cancelled,
+            ...(error ? { error: error.slice(0, 4096) } : {}),
+        });
+    }
+}

package/dist/main.js

@@ -14,7 +14,9 @@ switch (role) {
         break;
     }
     default: {
-        const self = process.argv[1] ? `node ${process.argv[1].split('/').slice(-2).join('/')}` : 'main';
+        const self = process.argv[1]
+            ? `node ${process.argv[1].split('/').slice(-2).join('/')}`
+            : 'main';
         console.error(`Usage: TUG_ROLE=control|agent ${self}, or ${self} <control|agent>`);
         process.exit(1);
     }