@wpelevator/tug 0.2.1 → 0.4.0

package/dist/ingress.d.ts

@@ -1,5 +1,5 @@
 import type { DesiredState, IngressRoute, IngressStatus, IngressWork, ProjectStatus, ServiceEndpoints } from './protocol.ts';
-import type { DockerRunner } from './runners.ts';
+import type { DockerApi } from './docker-api.ts';
 export declare const CADDY_CONTAINER = "tug-caddy";
 export declare const DEFAULT_CADDY_IMAGE = "caddy:2-alpine";
 export interface NodeView {
@@ -23,27 +23,35 @@ 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;
 export declare function ingressConfigHash(work: Pick<IngressWork, 'caddyfile' | 'files'>): string;
 export interface IngressContext {
-    docker: DockerRunner;
+    docker: DockerApi;
     stateDir: string;
     caddyImage?: string;
 }
 /**
- * Makes the Caddy container match the control-rendered config. Config is copied into the
- * container (`docker cp`, so it works whether the agent runs on the host or in a container) and
- * applied with `caddy reload`, which swaps config gracefully without dropping connections. If
- * Caddy rejects the new config the previous one is restored and the error reported.
+ * Makes the Caddy container match the control-rendered config. Config is uploaded into the
+ * container with the archive endpoint (so it works whether the agent runs on the host or in a
+ * container) and applied with `caddy reload`, which swaps config gracefully without dropping
+ * connections. If Caddy rejects the new config the previous one is restored and the error reported.
  */
 export declare function reconcileIngress(ctx: IngressContext, work: IngressWork): Promise<IngressStatus>;
 /** Removes the Caddy container when a node stops being an ingress node; ACME data volumes are kept. */

package/dist/ingress.js

@@ -4,8 +4,10 @@
 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";
+import * as tar from 'tar';
+import { isNotFound } from "./docker-api.js";
 export const CADDY_CONTAINER = 'tug-caddy';
 export const DEFAULT_CADDY_IMAGE = 'caddy:2-alpine';
 const CADDY_ETC = '/etc/caddy';
@@ -15,8 +17,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 +32,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 +45,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 +83,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 +103,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)
@@ -115,11 +135,35 @@ async function writeStage(dir, work) {
         await fs.writeFile(file, body, { mode: name.endsWith('.key') ? 0o600 : 0o644 });
     }
 }
+async function tarOf(dir) {
+    const chunks = [];
+    for await (const chunk of tar.c({ cwd: dir, portable: true }, ['.']))
+        chunks.push(chunk);
+    return Buffer.concat(chunks);
+}
+async function ensureImage(ctx) {
+    const image = ctx.caddyImage || DEFAULT_CADDY_IMAGE;
+    if (!(await ctx.docker.inspectImage(image)))
+        await ctx.docker.pullImage(image);
+    return image;
+}
+async function reload(ctx) {
+    const r = await ctx.docker.execRun(CADDY_CONTAINER, [
+        'caddy',
+        'reload',
+        '--config',
+        `${CADDY_ETC}/Caddyfile`,
+        '--adapter',
+        'caddyfile',
+    ]);
+    if (r.code !== 0)
+        throw new Error(`caddy reload failed (${r.code}): ${(r.err || r.out).trim()}`);
+}
 /**
- * Makes the Caddy container match the control-rendered config. Config is copied into the
- * container (`docker cp`, so it works whether the agent runs on the host or in a container) and
- * applied with `caddy reload`, which swaps config gracefully without dropping connections. If
- * Caddy rejects the new config the previous one is restored and the error reported.
+ * Makes the Caddy container match the control-rendered config. Config is uploaded into the
+ * container with the archive endpoint (so it works whether the agent runs on the host or in a
+ * container) and applied with `caddy reload`, which swaps config gracefully without dropping
+ * connections. If Caddy rejects the new config the previous one is restored and the error reported.
  */
 export async function reconcileIngress(ctx, work) {
     const root = path.join(ctx.stateDir, 'ingress');
@@ -127,35 +171,46 @@ 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 existing = await ctx.docker.inspectContainer(CADDY_CONTAINER).catch((e) => {
+        if (isNotFound(e))
+            return null;
+        throw e;
+    });
+    const running = existing ? Boolean(existing.State?.Running) : 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
-            ]);
-            await ctx.docker(['cp', `${stage}/.`, `${CADDY_CONTAINER}:${CADDY_ETC}/`]);
-            await ctx.docker(['start', CADDY_CONTAINER]);
+            const image = await ensureImage(ctx);
+            await ctx.docker.createContainer(CADDY_CONTAINER, {
+                Image: image,
+                Labels: { 'tug.managed': 'ingress' },
+                HostConfig: {
+                    NetworkMode: 'host',
+                    RestartPolicy: { Name: 'unless-stopped' },
+                    Binds: ['tug-caddy-data:/data', 'tug-caddy-config:/config', `tug-caddy-etc:${CADDY_ETC}`],
+                },
+            });
+            await ctx.docker.putArchive(CADDY_CONTAINER, CADDY_ETC, await tarOf(stage));
+            await ctx.docker.startContainer(CADDY_CONTAINER);
         }
         else if (running === false) {
-            await ctx.docker(['cp', `${stage}/.`, `${CADDY_CONTAINER}:${CADDY_ETC}/`]);
-            await ctx.docker(['start', CADDY_CONTAINER]);
+            await ctx.docker.putArchive(CADDY_CONTAINER, CADDY_ETC, await tarOf(stage));
+            await ctx.docker.startContainer(CADDY_CONTAINER);
         }
         else {
             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.execRun(CADDY_CONTAINER, ['rm', '-rf', `${CADDY_ETC}/certs`]);
+                await ctx.docker.putArchive(CADDY_CONTAINER, CADDY_ETC, await tarOf(stage));
+                await reload(ctx);
             }
             catch (e) {
                 if (await fs.stat(applied).then(() => true, () => false))
-                    await ctx.docker(['cp', `${applied}/.`, `${CADDY_CONTAINER}:${CADDY_ETC}/`]).catch(() => { });
+                    await ctx.docker
+                        .putArchive(CADDY_CONTAINER, CADDY_ETC, await tarOf(applied))
+                        .catch(() => { });
                 throw e;
             }
         }
@@ -174,7 +229,7 @@ export async function removeIngress(ctx) {
     const root = path.join(ctx.stateDir, 'ingress');
     if (!(await fs.stat(root).then(() => true, () => false)))
         return false;
-    await ctx.docker(['rm', '-f', CADDY_CONTAINER]).catch(() => { });
+    await ctx.docker.removeContainer(CADDY_CONTAINER).catch(() => { });
     await fs.rm(root, { recursive: true, force: true });
     return true;
 }

package/dist/live.d.ts

@@ -0,0 +1,83 @@
+import { EventEmitter } from 'node:events';
+import type { DockerApi } from './docker-api.ts';
+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 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;
+    /** The Engine API: exec (with a real PTY), logs, `ps` and `inspect` all go through it. */
+    docker: DockerApi;
+    maxSessions?: number;
+    maxSessionMs?: number;
+    queryTimeoutMs?: number;
+}
+/** Owns Engine API streams and their lifetimes; callers own authentication, authorization and transport backpressure. */
+export declare class LiveOperationEngine {
+    private readonly options;
+    private readonly sessions;
+    /** Sessions whose container stream is still being opened; a cancel marks them so they close on arrival. */
+    private readonly starting;
+    constructor(options: LiveEngineOptions);
+    get activeSessions(): number;
+    start(value: unknown): Promise<void>;
+    /** `ps` and `inspect` are one Engine API call whose JSON result is the whole session. */
+    private query;
+    private open;
+    /** 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,276 @@
+import { EventEmitter } from 'node:events';
+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');
+}
+/** Owns Engine API streams and their lifetimes; callers own authentication, authorization and transport backpressure. */
+export class LiveOperationEngine {
+    options;
+    sessions = new Map();
+    /** Sessions whose container stream is still being opened; a cancel marks them so they close on arrival. */
+    starting = new Map();
+    constructor(options) {
+        for (const key of ['maxSessions', '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 + this.starting.size;
+    }
+    async start(value) {
+        validate(value);
+        if (this.sessions.has(value.sessionId) || this.starting.has(value.sessionId))
+            throw new Error('Duplicate live session ID');
+        if (this.activeSessions >= (this.options.maxSessions ?? 16))
+            throw new Error('Live session limit reached');
+        const request = structuredClone(value);
+        const id = request.sessionId;
+        const pending = { cancelled: false };
+        this.starting.set(id, pending);
+        const query = request.operation === 'ps' || request.operation === 'inspect';
+        const timer = setTimeout(() => this.finish(id, null, null, false, 'Live operation timed out', true), query ? (this.options.queryTimeoutMs ?? 30000) : (this.options.maxSessionMs ?? 3600000));
+        timer.unref();
+        let child;
+        try {
+            if (query) {
+                this.starting.delete(id);
+                await this.query(request, timer);
+                return;
+            }
+            child = await this.open(request);
+        }
+        catch (error) {
+            clearTimeout(timer);
+            this.starting.delete(id);
+            throw error;
+        }
+        this.starting.delete(id);
+        if (pending.cancelled) {
+            clearTimeout(timer);
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                /* Already gone. */
+            }
+            this.options.emit({ sessionId: id, type: 'exit', code: null, signal: null, cancelled: true });
+            return;
+        }
+        const live = child;
+        const onError = (error) => {
+            if (this.sessions.get(id)?.child === live)
+                this.finish(id, null, null, false, error.message, true);
+        };
+        const stopErrors = () => {
+            live.off('error', onError).off('close', onClose);
+            live.stdin?.off('error', onError);
+        };
+        const onClose = (code, signal) => {
+            stopErrors();
+            if (this.sessions.get(id)?.child === live)
+                this.finish(id, code, signal, false);
+        };
+        const stdout = (data) => this.output(id, 'stdout', data);
+        const stderr = (data) => this.output(id, 'stderr', data);
+        this.sessions.set(id, {
+            request,
+            child: live,
+            timer,
+            cleanup: (awaitClose = false) => {
+                clearTimeout(timer);
+                if (!awaitClose)
+                    stopErrors();
+                live.stdout?.off('data', stdout);
+                live.stderr?.off('data', stderr);
+            },
+        });
+        live.on('error', onError).on('close', onClose);
+        live.stdout?.on('data', stdout);
+        live.stderr?.on('data', stderr);
+        live.stdin?.on('error', onError);
+        if (request.operation === 'exec' && request.interactive === false)
+            live.stdin?.end();
+    }
+    /** `ps` and `inspect` are one Engine API call whose JSON result is the whole session. */
+    async query(request, timer) {
+        const id = request.sessionId;
+        const session = { request, timer, cleanup: () => clearTimeout(timer) };
+        const aborted = new Promise((resolve) => {
+            session.abort = resolve;
+        });
+        this.sessions.set(id, session);
+        let error;
+        let result;
+        let settled = false;
+        const work = (async () => {
+            try {
+                if (request.operation === 'ps') {
+                    const lists = await Promise.all([...new Set(request.projects)].map((project) => this.options.docker.listContainers({ label: [`tug.project=${project}`] })));
+                    result = lists.flat();
+                }
+                else
+                    result = [await this.options.docker.inspectContainer(request.container)];
+                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');
+            }
+            catch (cause) {
+                error = cause instanceof Error ? cause.message : String(cause);
+            }
+            settled = true;
+        })();
+        await Promise.race([work, aborted]);
+        // A cancel or timeout already closed the session while the call was in flight.
+        if (!settled || !this.sessions.has(id))
+            return;
+        clearTimeout(timer);
+        this.sessions.delete(id);
+        if (result && !error)
+            this.options.emit({ sessionId: id, type: 'result', result });
+        this.options.emit({
+            sessionId: id,
+            type: 'exit',
+            code: error ? 1 : 0,
+            signal: null,
+            cancelled: false,
+            ...(error ? { error: error.slice(0, 4096) } : {}),
+        });
+    }
+    async open(request) {
+        const { docker } = this.options;
+        if (request.operation === 'logs')
+            return docker.logs(request.container, {
+                follow: true,
+                tail: request.tail ?? 100,
+                timestamps: request.timestamps,
+            });
+        const proc = await docker.execStart(request.container, {
+            cmd: request.command,
+            stdin: request.interactive !== false,
+            tty: Boolean(request.tty),
+            columns: request.columns,
+            rows: request.rows,
+        });
+        return proc;
+    }
+    /** 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');
+        const stdin = session.child?.stdin;
+        if (!stdin || stdin.destroyed || stdin.writableEnded)
+            throw new Error('Session stdin is closed');
+        if (stdin.writableLength + data.byteLength > 262144)
+            throw new Error('Live stdin queue exceeds size limit');
+        return 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) {
+        const pending = this.starting.get(sessionId);
+        if (pending)
+            pending.cancelled = true;
+        this.finish(sessionId, null, null, true, undefined, true);
+    }
+    dispose() {
+        for (const id of [...this.sessions.keys(), ...this.starting.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) {
+        if (!this.sessions.has(id))
+            return;
+        const bytes = Buffer.isBuffer(data) ? data : Buffer.from(data);
+        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);
+        session.abort?.();
+        // Keep error handlers until close when killing: errors can arrive after cancellation.
+        session.cleanup(kill);
+        if (kill && session.child) {
+            try {
+                session.child.kill('SIGKILL');
+            }
+            catch {
+                /* Already exited. */
+            }
+        }
+        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);
     }