@shardflux/sdk 0.14.0 → 0.16.0

package/dist/tunnel-pty.js

@@ -0,0 +1,243 @@
+import { WebSocket, EnvHttpProxyAgent } from 'undici';
+import { cellPath } from "./cell.js";
+import { ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
+import { tunnelPacket } from "./tunnel-packet.js";
+/** Native PTY owns the channel; helper acknowledgements own bytes, independently of an HTTP request outcome. */
+export class PtyTunnelTransport {
+    maxInputConcurrency = 64;
+    kind = 'pty';
+    #cell;
+    #socket;
+    #dispatcher = new EnvHttpProxyAgent();
+    #open;
+    #pending = new Map();
+    #rawOffset = 0;
+    #sentOffset = 0;
+    #logicalOffset = 0;
+    #buffer = Buffer.alloc(0);
+    #queue = [];
+    #wake;
+    #error;
+    #closed = false;
+    #timer;
+    #recovery;
+    #recoveryAbort = new AbortController();
+    #sessionId = "";
+    constructor(cell, open = (url, opts) => new WebSocket(url, opts)) { this.#cell = cell; this.#open = open; }
+    files = { remove: (path, opts) => this.#cell.files.remove(path, opts) };
+    exec = {
+        start: (...args) => this.#cell.exec.start(...args),
+        input: (id, bytes, opts) => this.input(id, bytes, opts),
+        output: (id, opts) => this.output(id, opts),
+        cancel: async (id) => {
+            this.#closed = true;
+            this.#recoveryAbort.abort();
+            clearInterval(this.#timer);
+            this.#socket?.close(1000);
+            this.#wake?.();
+            for (const p of this.#pending.values()) {
+                p.cleanup();
+                p.reject(new Error('reverse tunnel closed'));
+            }
+            this.#pending.clear();
+            await this.#recovery;
+            try {
+                return await this.#cell.pty.close(id);
+            }
+            finally {
+                await this.#dispatcher.close();
+            }
+        },
+    };
+    async input(id, value, opts) {
+        this.#sessionId = id;
+        const bytes = typeof value === 'string' ? Buffer.from(value) : value;
+        const old = this.#pending.get(opts.offset);
+        if (old)
+            throw new Error('duplicate pending tunnel packet');
+        if (this.#closed)
+            throw new Error('reverse tunnel closed');
+        return new Promise((resolve, reject) => {
+            const abort = () => { this.#pending.delete(opts.offset); reject(opts.signal?.reason instanceof Error ? opts.signal.reason : new Error('aborted')); };
+            const packet = tunnelPacket(opts.offset, bytes);
+            const p = { offset: opts.offset, end: opts.offset + bytes.length, packet, resolve, reject,
+                cleanup: () => opts.signal?.removeEventListener('abort', abort) };
+            this.#sentOffset = Math.max(this.#sentOffset, p.end);
+            this.#pending.set(opts.offset, p);
+            opts.signal?.addEventListener('abort', abort, { once: true });
+            if (opts.signal?.aborted) {
+                abort();
+                return;
+            }
+            this.#send(packet);
+            this.#armRetry();
+            this.#recoverInput();
+        });
+    }
+    #send(packet) {
+        const socket = this.#socket;
+        if (socket?.readyState === WebSocket.OPEN && socket.bufferedAmount + packet.length <= 4 * 1024 * 1024)
+            socket.send(packet);
+    }
+    #armRetry() {
+        if (this.#timer)
+            return;
+        this.#timer = setInterval(() => {
+            if (!this.#pending.size) {
+                clearInterval(this.#timer);
+                this.#timer = undefined;
+                return;
+            }
+            // The byte window bounds both this replay and the gateway's queued native input.
+            for (const p of this.#pending.values())
+                this.#send(p.packet);
+            this.#recoverInput();
+        }, 500);
+    }
+    #recoverInput() {
+        const first = this.#pending.values().next().value;
+        if (this.#closed || this.#recovery || !first || this.#socket?.readyState === WebSocket.OPEN)
+            return;
+        // Only queued TCP data invokes wake-on-use; idle output reattach never wakes a workspace.
+        this.#recovery = this.#cell.request('POST', cellPath('/v1/workspaces/{workspace_id}/pty/{session_id}/input', {
+            workspace_id: this.#cell.workspaceId, session_id: this.#sessionId,
+        }), { json: { data: tunnelPacket(0, Buffer.alloc(0)).toString('base64') }, signal: this.#recoveryAbort.signal }).then(async (response) => { await response.arrayBuffer(); }).catch((error) => {
+            if (!this.#closed && error instanceof ShardfluxApiError && !error.retryable && !['workspace_not_running', 'workspace_busy'].includes(error.code)) {
+                this.#error = error;
+                this.#wake?.();
+            }
+        }).finally(() => { this.#recovery = undefined; });
+    }
+    #feed(bytes) {
+        this.#buffer = Buffer.concat([this.#buffer, bytes]);
+        const data = [];
+        while (this.#buffer.length >= 9) {
+            const n = this.#buffer.readUInt32BE(5);
+            if (n > 65536)
+                throw new Error('oversized tunnel output frame');
+            if (this.#buffer.length < n + 9)
+                break;
+            const framed = this.#buffer.subarray(0, n + 9);
+            this.#buffer = this.#buffer.subarray(n + 9);
+            if (framed[0] === 8) {
+                if (n !== 8 || framed.readUInt32BE(1) !== 0)
+                    throw new Error('invalid tunnel acknowledgement');
+                const offset = Number(framed.readBigUInt64BE(9));
+                if (!Number.isSafeInteger(offset) || offset > this.#sentOffset)
+                    throw new Error('invalid tunnel acknowledgement offset');
+                for (const [start, p] of this.#pending)
+                    if (p.end <= offset) {
+                        this.#pending.delete(start);
+                        p.cleanup();
+                        p.resolve({ offset: p.end, closed: false });
+                    }
+            }
+            else
+                data.push(framed);
+        }
+        if (data.length) {
+            const joined = Buffer.concat(data);
+            this.#queue.push({ type: 'output', stream: 'stdout', offset: this.#logicalOffset, data: joined.toString('base64') });
+            this.#logicalOffset += joined.length;
+            this.#wake?.();
+        }
+    }
+    async output(id, opts = {}) {
+        this.#sessionId = id;
+        this.#error = undefined;
+        const { url, token } = await this.#cell.pty.attachUrl(id, this.#rawOffset);
+        const u = new URL(url);
+        u.searchParams.set('output_format', 'binary');
+        const socket = this.#open(u.toString(), { headers: { authorization: `Bearer ${token}` }, dispatcher: this.#dispatcher });
+        socket.binaryType = 'arraybuffer';
+        this.#socket = socket;
+        const fail = (error) => { if (this.#socket !== socket)
+            return; this.#error = error; this.#wake?.(); };
+        socket.addEventListener('message', (event) => {
+            try {
+                if (this.#socket !== socket)
+                    return;
+                if (event.data instanceof ArrayBuffer) {
+                    const bytes = Buffer.from(event.data);
+                    if (bytes.length < 9)
+                        throw new Error('invalid binary PTY output');
+                    const start = Number(bytes.readBigUInt64BE(0));
+                    this.#outputBytes(start, bytes.subarray(8));
+                    return;
+                }
+                const m = JSON.parse(String(event.data));
+                if (this.#socket !== socket)
+                    return;
+                if (m.type === 'output' && m.data) {
+                    const bytes = Buffer.from(m.data, 'base64');
+                    const start = m.offset ?? this.#rawOffset;
+                    this.#outputBytes(start, bytes);
+                }
+                else if (m.type === 'exit') {
+                    this.#queue.push({ type: 'exit', session: m.session });
+                    this.#wake?.();
+                }
+                else if (m.type === 'error' && m.error)
+                    fail(this.#apiError(m.error));
+                else if (!m.type && 'error' in m)
+                    fail(this.#apiError(m));
+            }
+            catch (e) {
+                fail(e instanceof Error ? e : new Error(String(e)));
+            }
+        });
+        socket.addEventListener('error', () => {
+            // An HTTP refusal before upgrade has no close code/message in undici. Refresh ownership before reattach.
+            if (this.#socket !== socket)
+                return;
+            this.#cell.tokens.invalidate();
+            fail(new ShardfluxProtocolError('reverse tunnel PTY stream dropped', 0, 'cell'));
+        });
+        socket.addEventListener('close', (event) => {
+            if (this.#socket !== socket)
+                return;
+            if (this.#closed || opts.signal?.aborted) {
+                this.#wake?.();
+                return;
+            }
+            if (event.code === 4401 || event.code === 4409)
+                this.#cell.tokens.invalidate();
+            fail(this.#error ?? new ShardfluxProtocolError(`reverse tunnel PTY closed (${event.code})`, 0, 'cell'));
+        });
+        socket.addEventListener('open', () => { this.#send(tunnelPacket(0, Buffer.alloc(0))); for (const p of this.#pending.values())
+            this.#send(p.packet); });
+        return this.#events(socket, opts);
+    }
+    #outputBytes(start, bytes) {
+        if (!Number.isSafeInteger(start) || start < 0 || start > this.#rawOffset)
+            throw new Error('tunnel PTY output has a byte gap');
+        const fresh = bytes.subarray(Math.min(bytes.length, this.#rawOffset - start));
+        this.#rawOffset += fresh.length;
+        this.#feed(fresh);
+    }
+    #apiError(body) {
+        const error = new ShardfluxApiError(502, body, 'cell');
+        if (['stale_epoch', 'token_expired', 'workspace_busy', 'workspace_not_running'].includes(error.code)) {
+            this.#cell.tokens.invalidate();
+            return new ShardfluxProtocolError('reverse tunnel PTY ownership changed', 0, 'cell');
+        }
+        return error;
+    }
+    async *#events(socket, opts) {
+        const abort = () => { socket.close(1000); this.#wake?.(); };
+        opts.signal?.addEventListener('abort', abort, { once: true });
+        try {
+            while (!this.#closed && !opts.signal?.aborted) {
+                while (this.#queue.length)
+                    yield this.#queue.shift();
+                if (this.#error)
+                    throw this.#error;
+                await new Promise(resolve => { this.#wake = resolve; });
+            }
+        }
+        finally {
+            opts.signal?.removeEventListener('abort', abort);
+            socket.close(1000);
+        }
+    }
+}

package/dist/tunnels.d.ts

@@ -0,0 +1,47 @@
+import type { CellClient } from './cell.js';
+export interface ReverseTunnelOptions {
+    remotePort: number;
+    /** Dialed on this machine: host:port, or [IPv6]:port. */
+    target: string;
+    bindAddress?: '127.0.0.1' | '0.0.0.0';
+    signal?: AbortSignal;
+    transport?: 'auto' | 'pty' | 'exec';
+}
+export interface ReverseTunnelStats {
+    connections: number;
+    activeConnections: number;
+    bytesToTarget: number;
+    bytesToWorkspace: number;
+    reconnects: number;
+}
+export type TunnelTransport = {
+    maxInputConcurrency?: number;
+    kind?: 'pty' | 'exec';
+    exec: Pick<CellClient['exec'], 'start' | 'input' | 'output' | 'cancel'>;
+    files: Pick<CellClient['files'], 'remove'>;
+};
+export declare function tunnelTarget(target: string): {
+    host: string;
+    port: number;
+};
+/** An owned foreground connection to the developer machine. Close in finally. */
+export declare class ReverseTunnel {
+    #private;
+    readonly sessionId: string;
+    readonly remotePort: number;
+    readonly target: string;
+    readonly transport: 'pty' | 'exec';
+    readonly closed: Promise<void>;
+    private constructor();
+    get stats(): ReverseTunnelStats;
+    /** Internal transport entry point, also exercised against the real helper in tests. */
+    static attach(transport: TunnelTransport, sessionId: string, dir: string, opts: ReverseTunnelOptions): Promise<ReverseTunnel>;
+    close(): Promise<void>;
+}
+/** Workspace → this client's machine; unused workspaces pay no tunnel setup or lifecycle cost. */
+export declare class WorkspaceTunnels {
+    #private;
+    constructor(cell: () => CellClient, grants?: () => string[] | null);
+    reverse(opts: ReverseTunnelOptions): Promise<ReverseTunnel>;
+    close(): Promise<void>;
+}