@wpelevator/tug 0.2.1 → 0.4.0

package/dist/cli-live-transport.js

@@ -0,0 +1,230 @@
+import WebSocket from 'ws';
+import { CliLiveError } from "./cli-live.js";
+import { LIVE_MAX_FRAME_BYTES as MAX_FRAME, LIVE_MAX_BUFFERED_BYTES as MAX_BUFFERED, LIVE_START_TIMEOUT_MS, } from "./protocol.js";
+const MAX_EVENTS = 1024;
+/** Credentials travel only in the upgrade header, never a URL or frame. */
+export function createCliLiveTransport(controlUrl, operatorToken) {
+    const url = new URL(controlUrl);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        throw new CliLiveError('live control URL must use http or https');
+    if (url.username || url.password || url.search || url.hash)
+        throw new CliLiveError('live control URL must not contain credentials, query or fragment');
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    url.pathname = `${url.pathname.replace(/\/$/, '')}/api/v1/live`;
+    return {
+        open(request, signal) {
+            return new Promise((resolve, reject) => {
+                if (signal.aborted) {
+                    reject(new CliLiveError('live connection cancelled', 130));
+                    return;
+                }
+                const socket = new WebSocket(url, {
+                    headers: operatorToken ? { Authorization: `Bearer ${operatorToken}` } : {},
+                    maxPayload: MAX_FRAME,
+                    handshakeTimeout: LIVE_START_TIMEOUT_MS,
+                    perMessageDeflate: false,
+                });
+                let opened = false;
+                let closed = false;
+                let ended = false;
+                let queuedBytes = 0;
+                let sessionId;
+                const queue = [];
+                let notify;
+                const wake = () => {
+                    notify?.();
+                    notify = undefined;
+                };
+                const enqueue = (event, size = 0) => {
+                    if (ended)
+                        return;
+                    if (queue.length >= MAX_EVENTS || queuedBytes + size > MAX_BUFFERED) {
+                        queue.length = 0;
+                        queuedBytes = 0;
+                        event = { type: 'error', message: 'live response exceeded the receive buffer limit' };
+                        size = 0;
+                    }
+                    queue.push({ event, size });
+                    queuedBytes += size;
+                    if (event.type === 'error' || event.type === 'exit' || event.type === 'disconnect')
+                        ended = true;
+                    wake();
+                    if (event.type === 'error')
+                        socket.terminate();
+                };
+                const sendFrame = (frame) => new Promise((done, failed) => {
+                    const data = JSON.stringify({ v: 1, ...frame });
+                    if (Buffer.byteLength(data) > MAX_FRAME ||
+                        socket.bufferedAmount + Buffer.byteLength(data) > MAX_BUFFERED) {
+                        failed(new CliLiveError('live request exceeded the send buffer limit'));
+                        return;
+                    }
+                    if (socket.readyState !== WebSocket.OPEN) {
+                        failed(new CliLiveError('live connection is closed'));
+                        return;
+                    }
+                    socket.send(data, (error) => {
+                        if (error)
+                            failed(error);
+                        else
+                            done();
+                    });
+                });
+                const send = async (message) => {
+                    if (message.type === 'stdin') {
+                        // Bound individual frames even when a piped input stream yields a large chunk.
+                        for (let offset = 0; offset < message.data.byteLength; offset += 48 * 1024)
+                            await sendFrame({
+                                type: 'live.stdin',
+                                data: Buffer.from(message.data.subarray(offset, offset + 48 * 1024)).toString('base64'),
+                            });
+                    }
+                    else if (message.type === 'resize')
+                        await sendFrame({ type: 'live.resize', columns: message.columns, rows: message.rows });
+                    else
+                        await sendFrame({ type: message.type === 'cancel' ? 'live.cancel' : 'live.stdin-end' });
+                };
+                const session = {
+                    events: {
+                        async *[Symbol.asyncIterator]() {
+                            while (true) {
+                                const item = queue.shift();
+                                if (item) {
+                                    queuedBytes -= item.size;
+                                    yield item.event;
+                                }
+                                else if (ended || closed)
+                                    return;
+                                else
+                                    await new Promise((ready) => {
+                                        notify = ready;
+                                    });
+                            }
+                        },
+                    },
+                    send,
+                    close() {
+                        signal.removeEventListener('abort', abort);
+                        enqueue({ type: 'disconnect', message: 'live session closed' });
+                        if (socket.readyState !== WebSocket.CLOSED)
+                            socket.terminate();
+                    },
+                };
+                const abort = () => {
+                    if (!opened)
+                        reject(new CliLiveError('live connection cancelled', 130));
+                    enqueue({ type: 'disconnect', message: 'live connection cancelled' });
+                    socket.terminate();
+                };
+                const onError = (error) => {
+                    if (!opened)
+                        reject(new CliLiveError(`live connection failed: ${error.message}`));
+                    enqueue({ type: 'error', message: `live connection failed: ${error.message}` });
+                };
+                const onMessage = (data, binary) => {
+                    if (ended)
+                        return;
+                    try {
+                        const bytes = Array.isArray(data)
+                            ? Buffer.concat(data)
+                            : Buffer.from(data instanceof ArrayBuffer ? new Uint8Array(data) : data);
+                        if (binary || bytes.byteLength > MAX_FRAME)
+                            throw new Error('invalid or oversized live frame');
+                        const frame = JSON.parse(bytes.toString('utf8'));
+                        if (!frame ||
+                            typeof frame !== 'object' ||
+                            frame.v !== 1 ||
+                            typeof frame.type !== 'string')
+                            throw new Error('invalid live frame envelope');
+                        if (frame.type !== 'live.error' &&
+                            (typeof frame.sessionId !== 'string' || !frame.sessionId))
+                            throw new Error('invalid live session identifier');
+                        if (frame.sessionId !== undefined &&
+                            (typeof frame.sessionId !== 'string' ||
+                                !frame.sessionId ||
+                                (sessionId !== undefined && sessionId !== frame.sessionId)))
+                            throw new Error('invalid live session identifier');
+                        if (typeof frame.sessionId === 'string')
+                            sessionId = frame.sessionId;
+                        switch (frame.type) {
+                            case 'live.started':
+                                if (typeof frame.node !== 'string' || !frame.node)
+                                    throw new Error('invalid live started frame');
+                                if (opened)
+                                    throw new Error('duplicate live started frame');
+                                opened = true;
+                                resolve(session);
+                                break;
+                            case 'live.output': {
+                                if (!opened)
+                                    throw new Error('live output arrived before startup');
+                                if ((frame.stream !== 'stdout' && frame.stream !== 'stderr') ||
+                                    typeof frame.data !== 'string' ||
+                                    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(frame.data))
+                                    throw new Error('invalid live output frame');
+                                const decoded = Buffer.from(frame.data, 'base64');
+                                if (decoded.toString('base64') !== frame.data)
+                                    throw new Error('invalid live output encoding');
+                                enqueue({ type: frame.stream, data: decoded }, bytes.byteLength);
+                                break;
+                            }
+                            case 'live.result':
+                                if (!opened)
+                                    throw new Error('live result arrived before startup');
+                                if (!Object.hasOwn(frame, 'value'))
+                                    throw new Error('invalid live result frame');
+                                enqueue({ type: 'result', value: frame.value }, bytes.byteLength);
+                                break;
+                            case 'live.exit':
+                                if (!opened)
+                                    throw new Error('live exit arrived before startup');
+                                if (!Number.isInteger(frame.code) ||
+                                    Number(frame.code) < 0 ||
+                                    Number(frame.code) > 255)
+                                    throw new Error('invalid live exit frame');
+                                enqueue({ type: 'exit', code: Number(frame.code) });
+                                break;
+                            case 'live.error':
+                                if (typeof frame.message !== 'string' || !frame.message)
+                                    throw new Error('invalid live error frame');
+                                if (!opened) {
+                                    ended = true;
+                                    reject(new CliLiveError(frame.message));
+                                    socket.terminate();
+                                }
+                                else
+                                    enqueue({ type: 'error', message: frame.message });
+                                break;
+                            default:
+                                throw new Error('unknown live frame type');
+                        }
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : 'invalid live frame';
+                        if (!opened) {
+                            ended = true;
+                            reject(new CliLiveError(message));
+                            socket.terminate();
+                        }
+                        else
+                            enqueue({ type: 'error', message });
+                    }
+                };
+                const onClose = () => {
+                    closed = true;
+                    signal.removeEventListener('abort', abort);
+                    socket.off('message', onMessage).off('error', onError);
+                    if (!opened)
+                        reject(new CliLiveError('live connection closed before opening'));
+                    enqueue({ type: 'disconnect', message: 'live connection disconnected before exit' });
+                    wake();
+                };
+                socket.on('message', onMessage).on('error', onError).once('close', onClose);
+                signal.addEventListener('abort', abort, { once: true });
+                socket.once('open', () => {
+                    void sendFrame({ type: 'live.open', request }).catch(onError);
+                });
+            });
+        },
+    };
+}

package/dist/cli-live.d.ts

@@ -0,0 +1,77 @@
+import { EventEmitter } from 'node:events';
+import type { Readable, Writable } from 'node:stream';
+import type { LiveRequest } from './protocol.ts';
+export type { LiveRequest } from './protocol.ts';
+export interface LiveInput {
+    project: string;
+    service?: string;
+    node?: string;
+    command?: string[];
+    interactive?: boolean;
+    tty?: boolean;
+    tail?: string | number;
+}
+/** Command arguments are passed verbatim, never joined into a shell command. */
+export declare function parseLiveRequest(operation: LiveRequest['operation'], input: LiveInput): LiveRequest;
+export type LiveClientMessage = {
+    type: 'stdin';
+    data: Uint8Array;
+} | {
+    type: 'stdin-end';
+} | {
+    type: 'resize';
+    columns: number;
+    rows: number;
+} | {
+    type: 'cancel';
+};
+export type LiveEvent = {
+    type: 'stdout' | 'stderr';
+    data: Uint8Array;
+} | {
+    type: 'result';
+    value: unknown;
+} | {
+    type: 'exit';
+    code: number;
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'disconnect';
+    message?: string;
+};
+/** Adapters must bound received buffering and unblock event iteration when closed. */
+export interface CliLiveSession {
+    events: AsyncIterable<LiveEvent>;
+    send(message: LiveClientMessage): void | Promise<void>;
+    close(): void | Promise<void>;
+}
+export interface CliLiveTransport {
+    /** Respect abort during connection establishment; a late session is closed by the runner. */
+    open(request: LiveRequest, signal: AbortSignal): Promise<CliLiveSession>;
+}
+export type CliLiveStdin = Readable & {
+    isTTY?: boolean;
+    isRaw?: boolean;
+    setRawMode?: (enabled: boolean) => unknown;
+};
+export type CliLiveStdout = Writable & {
+    isTTY?: boolean;
+    columns?: number;
+    rows?: number;
+};
+export interface CliLiveIO {
+    stdin?: CliLiveStdin;
+    stdout?: CliLiveStdout;
+    stderr?: Writable;
+    signals?: EventEmitter;
+    signal?: AbortSignal;
+}
+export declare class CliLiveError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+export declare function formatLiveResult(value: unknown): string;
+/** Runs one session without exiting the process or owning the caller's streams. */
+export declare function runCliLive(request: LiveRequest, transport: CliLiveTransport, io?: CliLiveIO): Promise<number>;

package/dist/cli-live.js

@@ -0,0 +1,249 @@
+import { EventEmitter } from 'node:events';
+/** Command arguments are passed verbatim, never joined into a shell command. */
+export function parseLiveRequest(operation, input) {
+    const name = (value, label) => {
+        if (!value || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(value))
+            throw new Error(`${label} must be a nonempty name containing letters, numbers, dots, underscores or hyphens`);
+        return value;
+    };
+    const common = {
+        project: name(input.project, 'project'),
+        ...(input.node === undefined ? {} : { node: name(input.node, 'node') }),
+    };
+    if (operation === 'ps')
+        return { operation, ...common };
+    const service = name(input.service, 'service');
+    if (operation === 'inspect')
+        return { operation, ...common, service };
+    if (operation === 'logs') {
+        const raw = String(input.tail ?? 200);
+        if (!/^\d+$/.test(raw) || !Number.isSafeInteger(Number(raw)))
+            throw new Error('tail must be a nonnegative safe integer');
+        return { operation, ...common, service, follow: true, tail: Number(raw) };
+    }
+    const command = input.command?.length ? [...input.command] : ['sh'];
+    if (command.some((part) => typeof part !== 'string' || part.includes('\0')) || !command[0])
+        throw new Error('exec command must have a nonempty executable and no NUL bytes');
+    return {
+        operation,
+        ...common,
+        service,
+        command,
+        interactive: input.interactive ?? false,
+        tty: input.tty ?? false,
+    };
+}
+export class CliLiveError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.name = 'CliLiveError';
+        this.exitCode = exitCode;
+    }
+}
+export function formatLiveResult(value) {
+    const json = JSON.stringify(value, null, 2);
+    if (json === undefined)
+        throw new CliLiveError('remote operation returned no JSON result');
+    return `${json}\n`;
+}
+/** Runs one session without exiting the process or owning the caller's streams. */
+export async function runCliLive(request, transport, io = {}) {
+    const stdin = io.stdin ?? process.stdin;
+    const stdout = io.stdout ?? process.stdout;
+    const stderr = io.stderr ?? process.stderr;
+    const signals = io.signals ?? process;
+    const controller = new AbortController();
+    let session;
+    let complete = false;
+    let rawChanged = false;
+    let inputAttached = false;
+    const wasRaw = Boolean(stdin.isRaw);
+    const wasFlowing = stdin.readableFlowing === true;
+    let failure;
+    let wake;
+    const stopped = new Promise((resolve) => {
+        wake = resolve;
+    });
+    let queuedBytes = 0;
+    let sending = Promise.resolve();
+    const fail = (error) => {
+        failure ??= error instanceof Error ? error : new Error(String(error));
+        wake();
+    };
+    const send = (message) => {
+        const size = message.type === 'stdin' ? message.data.byteLength : 0;
+        queuedBytes += size;
+        if (queuedBytes > 1024 * 1024) {
+            fail(new CliLiveError('stdin exceeded the live session buffer limit'));
+            return;
+        }
+        sending = sending
+            .then(async () => {
+            if (!complete && !controller.signal.aborted)
+                await session.send(message);
+        })
+            .catch(fail)
+            .finally(() => {
+            queuedBytes -= size;
+        });
+    };
+    const cancel = () => {
+        controller.abort();
+        wake();
+    };
+    const onData = (data) => {
+        send({ type: 'stdin', data: Buffer.from(data) });
+    };
+    const onEnd = () => {
+        send({ type: 'stdin-end' });
+    };
+    const onStreamError = (error) => {
+        fail(error);
+    };
+    const resize = () => {
+        if (Number.isInteger(stdout.columns) &&
+            stdout.columns > 0 &&
+            Number.isInteger(stdout.rows) &&
+            stdout.rows > 0)
+            send({ type: 'resize', columns: stdout.columns, rows: stdout.rows });
+    };
+    const write = async (stream, data) => {
+        await new Promise((resolve, reject) => {
+            stream.write(data, (error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            });
+        });
+    };
+    const consume = async () => {
+        let result;
+        let hasResult = false;
+        for await (const event of session.events) {
+            if (complete || controller.signal.aborted)
+                return 130;
+            switch (event.type) {
+                case 'stdout':
+                    await write(stdout, event.data);
+                    break;
+                case 'stderr':
+                    await write(stderr, event.data);
+                    break;
+                case 'result':
+                    result = event.value;
+                    hasResult = true;
+                    break;
+                case 'error':
+                    throw new CliLiveError(event.message);
+                case 'disconnect':
+                    throw new CliLiveError(event.message ?? 'live session disconnected before exit');
+                case 'exit':
+                    if (!Number.isInteger(event.code) || event.code < 0 || event.code > 255)
+                        throw new CliLiveError('remote operation returned an invalid exit code');
+                    if (event.code === 0 && (request.operation === 'ps' || request.operation === 'inspect')) {
+                        if (!hasResult)
+                            throw new CliLiveError('remote operation exited without a JSON result');
+                        await write(stdout, formatLiveResult(result));
+                    }
+                    return event.code;
+            }
+        }
+        throw new CliLiveError('live session disconnected before exit');
+    };
+    signals.on('SIGINT', cancel);
+    io.signal?.addEventListener('abort', cancel, { once: true });
+    stdout.on('error', onStreamError);
+    stderr.on('error', onStreamError);
+    try {
+        if (io.signal?.aborted)
+            cancel();
+        if (controller.signal.aborted)
+            return 130;
+        if (request.operation === 'exec' &&
+            request.tty &&
+            (!stdin.isTTY || !stdout.isTTY || !stdin.setRawMode))
+            throw new CliLiveError('TTY exec requires a local terminal on stdin and stdout');
+        const openRequest = request.operation === 'exec' && request.tty
+            ? {
+                ...request,
+                ...(stdout.columns && stdout.rows
+                    ? { columns: stdout.columns, rows: stdout.rows }
+                    : {}),
+            }
+            : request;
+        const opening = transport.open(openRequest, controller.signal).then(async (opened) => {
+            if (complete || controller.signal.aborted) {
+                await opened.close();
+                return undefined;
+            }
+            return opened;
+        });
+        session = await Promise.race([opening, stopped.then(() => undefined)]);
+        if (!session) {
+            if (failure)
+                throw failure;
+            return 130;
+        }
+        if (request.operation === 'exec') {
+            if (request.tty) {
+                rawChanged = !wasRaw;
+                if (rawChanged)
+                    stdin.setRawMode(true);
+                stdout.on('resize', resize);
+                resize();
+            }
+            if (request.interactive) {
+                inputAttached = true;
+                stdin.on('data', onData).on('end', onEnd).on('error', onStreamError);
+                stdin.resume();
+                if (stdin.readableEnded)
+                    onEnd();
+            }
+        }
+        const code = await Promise.race([
+            consume(),
+            stopped.then(() => {
+                if (failure)
+                    throw failure;
+                return 130;
+            }),
+        ]);
+        if (failure)
+            throw failure;
+        return code;
+    }
+    finally {
+        complete = true;
+        signals.off('SIGINT', cancel);
+        io.signal?.removeEventListener('abort', cancel);
+        stdout.off('resize', resize);
+        if (inputAttached) {
+            stdin.off('data', onData).off('end', onEnd).off('error', onStreamError);
+            if (!wasFlowing)
+                stdin.pause();
+        }
+        try {
+            if (rawChanged)
+                stdin.setRawMode?.(wasRaw);
+        }
+        finally {
+            try {
+                if (session) {
+                    if (controller.signal.aborted || failure) {
+                        try {
+                            await session.send({ type: 'cancel' });
+                        }
+                        catch { }
+                    }
+                    await session.close();
+                }
+            }
+            finally {
+                stdout.off('error', onStreamError);
+                stderr.off('error', onStreamError);
+            }
+        }
+    }
+}