@shardflux/cli 0.15.2 → 0.17.0

package/dist/cli-proxy-forward.js

@@ -0,0 +1,432 @@
+/**
+ * The local face of the account's hosted CLIProxyAPI: an HTTP server on 127.0.0.1:8317 (where a local cli-proxy used to
+ * listen) that forwards every request, streaming both ways, and every WebSocket upgrade to the hub's port callback URL
+ * (`<callback_url><path>`). Tools keep their config: ANTHROPIC_BASE_URL=http://127.0.0.1:8317, Codex
+ * base_url http://127.0.0.1:8317/v1, and management calls with their own key.
+ *
+ * The edge wakes a sleeping hub on the request. When the edge itself answers (header X-Shardflux-Reason) for a request
+ * the hub never received (waking took too long, no capacity for a moment, CLIProxyAPI not running), the request is sent
+ * again, POST bodies included (kept up to 32 MiB); `port_not_listening` first starts CLIProxyAPI in the hub again
+ * (`repair`). Nothing secret is logged: no callback URL, header, query string or body.
+ */
+import { createServer, request as httpRequest, Agent as HttpAgent, STATUS_CODES } from 'node:http';
+import { request as httpsRequest, Agent as HttpsAgent } from 'node:https';
+import { statSync } from 'node:fs';
+import { connect } from 'node:net';
+import { CLI_VERSION } from "./args.js";
+import { CLI_PROXY_PORT, hubInfoPath, readHubInfo } from "./cli-proxy-hub.js";
+/** Edge refusals of a request the hub never received: safe to send again, whatever the method. */
+const NEVER_DELIVERED = new Set(['wake_timeout', 'host_capacity', 'wake_failed', 'dependency_unavailable', 'port_not_listening']);
+const IDEMPOTENT = new Set(['GET', 'HEAD', 'OPTIONS']);
+const HOP_BY_HOP = ['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'proxy-connection', 'te', 'trailer', 'transfer-encoding', 'upgrade'];
+export const REPLAY_LIMIT = 32 * 1024 * 1024;
+/** The forwarder answers this path itself (paths under /__shardflux/ are reserved by the edge, so no hub route is lost). */
+export const IDENTITY_PATH = '/__shardflux/forwarder';
+/** The hub info file, re-read when it changes (a replaced callback URL takes effect on the next request). */
+export function hubInfoSource(dir) {
+    let stamp = '';
+    let info = null;
+    return () => {
+        let next;
+        try {
+            const s = statSync(hubInfoPath(dir));
+            next = `${s.mtimeMs}:${s.size}:${s.ino}`;
+        }
+        catch {
+            return info;
+        }
+        if (next !== stamp) {
+            const read = readHubInfo(dir);
+            if (read)
+                info = read;
+            stamp = next;
+        }
+        return info;
+    };
+}
+function stripHopByHop(headers, keepUpgrade = false) {
+    const listed = String(headers.connection ?? '').split(',').map((s) => s.trim().toLowerCase()).filter(Boolean);
+    const out = {};
+    for (const [k, v] of Object.entries(headers)) {
+        if (v === undefined)
+            continue;
+        const name = k.toLowerCase();
+        if ((HOP_BY_HOP.includes(name) || listed.includes(name)) && !(keepUpgrade && (name === 'upgrade' || name === 'connection')))
+            continue;
+        out[name] = v;
+    }
+    return out;
+}
+const pathOnly = (url) => (url ?? '/').split('?')[0];
+/** Whether something accepts TCP connections on host:port. */
+function answers(host, port) {
+    return new Promise((resolve) => {
+        const socket = connect({ host, port });
+        const done = (v) => { socket.destroy(); resolve(v); };
+        socket.setTimeout(1000, () => done(false));
+        socket.once('connect', () => done(true));
+        socket.once('error', () => done(false));
+    });
+}
+function errorBody(code, message) {
+    return JSON.stringify({ error: { code, message } });
+}
+export class CliProxyForwarder {
+    #o;
+    #renewing = null;
+    #renewedAt = 0;
+    #server;
+    #https = new HttpsAgent({ keepAlive: true });
+    #http = new HttpAgent({ keepAlive: true });
+    #repairing = null;
+    #closed = false;
+    #bindTimer = null;
+    #wakeWatch;
+    /** Both ends of every open WebSocket (or other upgrade). */
+    #tunnels = new Set();
+    constructor(opts) {
+        this.#o = {
+            host: '127.0.0.1', port: CLI_PROXY_PORT, retryBudgetMs: 60_000, bindRetryMs: 5_000, replayLimit: REPLAY_LIMIT,
+            log: () => { }, sleep: (ms) => new Promise((r) => setTimeout(r, ms)), ...opts,
+        };
+        // After this computer sleeps, pooled connections to the edge are dead without a reset; drop them on wake.
+        let tick = Date.now();
+        this.#wakeWatch = setInterval(() => {
+            const now = Date.now();
+            if (now - tick > 15_000)
+                this.dropIdleConnections();
+            tick = now;
+        }, 5_000).unref();
+        this.#server = createServer((req, res) => void this.#handle(req, res));
+        this.#server.on('upgrade', (req, socket, head) => void this.#upgrade(req, socket, head));
+        // Long streams (SSE, Responses) must not be cut by the server's own timeouts.
+        this.#server.requestTimeout = 0;
+        this.#server.headersTimeout = 60_000;
+        this.#server.keepAliveTimeout = 65_000;
+    }
+    get address() {
+        const a = this.#server.address();
+        return a && typeof a === 'object' ? { host: a.address, port: a.port } : null;
+    }
+    /**
+     * Listens on host:port. While another program holds the port (also one listening on all interfaces, which a
+     * loopback bind would not notice), logs once and tries again every bindRetryMs (until close()); resolves once
+     * listening.
+     */
+    listen() {
+        return new Promise((resolve, reject) => {
+            let told = false;
+            const busy = () => {
+                if (!told)
+                    this.#o.log(`${this.#o.host}:${this.#o.port} is in use by another program; waiting for it to be free`);
+                told = true;
+                this.#bindTimer = setTimeout(() => void attempt(), this.#o.bindRetryMs);
+            };
+            const attempt = async () => {
+                if (this.#closed)
+                    return resolve();
+                if (this.#o.port !== 0 && (await answers(this.#o.host, this.#o.port)))
+                    return busy();
+                const onError = (err) => {
+                    this.#server.off('listening', onListening);
+                    if (err.code === 'EADDRINUSE')
+                        return busy();
+                    reject(err);
+                };
+                const onListening = () => {
+                    this.#server.off('error', onError);
+                    this.#o.log(`forwarding ${this.#o.host}:${this.address?.port ?? this.#o.port} to the hosted CLIProxyAPI`);
+                    resolve();
+                };
+                this.#server.once('error', onError);
+                this.#server.once('listening', onListening);
+                this.#server.listen(this.#o.port, this.#o.host);
+            };
+            void attempt();
+        });
+    }
+    /** Closes the idle keep-alive connections to the edge (the next request opens a fresh one). */
+    dropIdleConnections() {
+        for (const agent of [this.#https, this.#http]) {
+            for (const list of Object.values(agent.freeSockets))
+                for (const socket of list ?? [])
+                    socket.destroy();
+        }
+    }
+    async close() {
+        this.#closed = true;
+        clearInterval(this.#wakeWatch);
+        if (this.#bindTimer)
+            clearTimeout(this.#bindTimer);
+        // Upgraded connections (WebSockets) are no longer the HTTP server's: end them here.
+        for (const socket of this.#tunnels)
+            socket.destroy();
+        this.#https.destroy();
+        this.#http.destroy();
+        if (!this.#server.listening)
+            return;
+        await new Promise((r) => {
+            this.#server.close(() => r());
+            this.#server.closeAllConnections();
+        });
+    }
+    #target(info, url) {
+        const base = new URL(info.callback_url);
+        const rest = (url ?? '/').replace(/^\/+/, '');
+        return new URL(base.pathname + rest, base.origin);
+    }
+    #send(info, req, body, rest, upgrade, signal) {
+        const target = this.#target(info, req.url);
+        const https = target.protocol === 'https:';
+        const headers = stripHopByHop(req.headers, upgrade);
+        headers.host = target.host;
+        const gone = () => Object.assign(new Error('the client closed the connection'), { code: 'ECANCELED', connected: false });
+        if (signal.aborted)
+            return Promise.resolve({ error: gone() });
+        return new Promise((resolve) => {
+            let done = false;
+            let connected = false;
+            const finish = (a) => { if (!done) {
+                done = true;
+                resolve(a);
+            } };
+            const out = (https ? httpsRequest : httpRequest)(target, {
+                method: req.method, headers, agent: upgrade ? false : https ? this.#https : this.#http,
+            });
+            // The client went away: end the request to the hub too and free its socket (never back to the pool).
+            const abort = () => out.destroy(gone());
+            signal.addEventListener('abort', abort, { once: true });
+            out.once('close', () => signal.removeEventListener('abort', abort));
+            // Connected once TCP (and TLS) is up, or at once on a pooled socket: an error before that sent nothing.
+            out.on('socket', (s) => {
+                s.setNoDelay?.(true);
+                if (out.reusedSocket)
+                    connected = true;
+                else
+                    s.once(https ? 'secureConnect' : 'connect', () => { connected = true; });
+            });
+            out.on('response', (res) => finish({ res }));
+            out.on('upgrade', (res, socket, head) => finish({ upgrade: { res, socket, head } }));
+            out.on('error', (err) => finish({ error: Object.assign(err, { connected }) }));
+            if (body)
+                for (const chunk of body)
+                    out.write(chunk);
+            if (rest) {
+                rest.pipe(out);
+                rest.on('error', () => out.destroy());
+            }
+            else {
+                out.end();
+            }
+        });
+    }
+    /** Reads the request body for replay; past REPLAY_LIMIT the rest streams and the request cannot be sent again. */
+    async #readBody(req) {
+        if (req.method === 'GET' || req.method === 'HEAD') {
+            if (!req.headers['content-length'] && !req.headers['transfer-encoding'])
+                return { chunks: [], replayable: true };
+        }
+        const chunks = [];
+        let size = 0;
+        return new Promise((resolve, reject) => {
+            const onData = (c) => {
+                chunks.push(c);
+                size += c.length;
+                if (size > this.#o.replayLimit) {
+                    req.off('data', onData);
+                    req.off('end', onEnd);
+                    req.pause();
+                    resolve({ chunks, replayable: false });
+                }
+            };
+            const onEnd = () => resolve({ chunks, replayable: true });
+            req.on('data', onData);
+            req.once('end', onEnd);
+            req.once('error', reject);
+            req.once('close', () => { if (!req.complete)
+                reject(new Error('the client closed the connection')); });
+        });
+    }
+    /** Why `a` is worth another attempt (for the log), or null. A replayable request is one whose body is still held. */
+    #retryable(a, method, replayable, renewed = false) {
+        if (!replayable)
+            return null;
+        const res = a.res;
+        if (res) {
+            const reason = res.headers['x-shardflux-reason'];
+            // The hub's port could not hand it to CLIProxyAPI while it started: never received.
+            if (res.statusCode === 503 && res.headers['x-hub-status'] === 'starting')
+                return 'CLIProxyAPI starting in the hub';
+            // The callback URL was revoked (its API key was): renewed once, then sent again; it was never received.
+            if (reason === 'callback_invalid' && this.#o.renew && !renewed)
+                return reason;
+            if (typeof reason !== 'string' || (res.statusCode ?? 0) < 500)
+                return null;
+            return NEVER_DELIVERED.has(reason) || (reason === 'upstream_error' && IDEMPOTENT.has(method)) ? reason : null;
+        }
+        const err = a.error;
+        if (!err)
+            return null;
+        // Only a failure before the connection was up provably sent nothing (DNS, connect, TLS). Anything later, a reset
+        // of a reused keep-alive socket included, may have reached the hub: only GET, HEAD and OPTIONS are sent again.
+        const undelivered = err.connected === false;
+        return undelivered || IDEMPOTENT.has(method) ? (err.code ?? 'network error') : null;
+    }
+    /** Renews the hub's callback URLs (at most once a minute, shared by every waiting request); returns its duration. */
+    async #renew() {
+        if (!this.#o.renew || (!this.#renewing && Date.now() - this.#renewedAt < 60_000))
+            return 0;
+        const t0 = Date.now();
+        this.#renewing ??= this.#o.renew().then(() => this.#o.log('the hub’s address was renewed (the API key that created it was revoked); VMs get it with your machine'), (err) => this.#o.log(`could not renew the hub’s address: ${err instanceof Error ? err.message : String(err)}`)).finally(() => { this.#renewedAt = Date.now(); this.#renewing = null; });
+        await this.#renewing;
+        return Date.now() - t0;
+    }
+    /** Starts CLIProxyAPI in the hub again (one repair at a time, shared by every waiting request); returns its duration. */
+    async #repair() {
+        if (!this.#o.repair)
+            return 0;
+        const t0 = Date.now();
+        this.#repairing ??= this.#o.repair().then(() => this.#o.log('CLIProxyAPI is running in the hub again'), (err) => this.#o.log(`could not start CLIProxyAPI in the hub again: ${err instanceof Error ? err.message : String(err)}`)).finally(() => { this.#repairing = null; });
+        await this.#repairing;
+        return Date.now() - t0;
+    }
+    async #attempts(req, upgrade, signal) {
+        const method = req.method ?? 'GET';
+        const read = upgrade ? { chunks: [], replayable: true } : await this.#readBody(req);
+        let delay = 1000;
+        let budget = this.#o.retryBudgetMs;
+        let renewed = false;
+        const started = Date.now();
+        const waitOrGone = (ms) => new Promise((resolve) => {
+            if (signal.aborted)
+                return resolve();
+            signal.addEventListener('abort', () => resolve(), { once: true });
+            void this.#o.sleep(ms).then(resolve);
+        });
+        for (let n = 1;; n++) {
+            const info = this.#o.hub();
+            if (!info)
+                return { status: 503, body: errorBody('service_unavailable', 'This computer is not connected to a hosted CLIProxyAPI. Connect it with: shard cli-proxy import') };
+            const attempt = await this.#send(info, req, read.chunks, read.replayable ? null : req, upgrade, signal);
+            const reason = this.#retryable(attempt, method, read.replayable, renewed);
+            if (!reason || this.#closed || signal.aborted || Date.now() - started > budget)
+                return { attempt };
+            attempt.res?.resume();
+            const after = Number(attempt.res?.headers['retry-after']);
+            this.#o.log(`${method} ${pathOnly(req.url)}: ${reason}; sending it again (attempt ${n + 1})`);
+            if (reason === 'port_not_listening')
+                budget += await this.#repair();
+            else if (reason === 'callback_invalid') {
+                renewed = true;
+                // Sent with a URL another request already replaced: only sent again.
+                if (this.#o.hub()?.callback_url === info.callback_url)
+                    budget += await this.#renew();
+            }
+            else
+                await waitOrGone(Number.isFinite(after) && after > 0 ? Math.min(after * 1000, 10_000) : delay);
+            delay = Math.min(delay * 2, 8000);
+        }
+    }
+    async #handle(req, res) {
+        if (pathOnly(req.url) === IDENTITY_PATH) {
+            const info = this.#o.hub();
+            res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ forwarder: 'shardflux', kind: 'mac', version: CLI_VERSION, hub: info ? info.workspace_id : null }));
+            return;
+        }
+        req.socket.setNoDelay(true);
+        // Before any attempt: a client that goes away aborts the request to the hub (and any wait between attempts).
+        const gone = new AbortController();
+        res.once('close', () => { if (!res.writableFinished)
+            gone.abort(); });
+        let outcome;
+        try {
+            outcome = await this.#attempts(req, false, gone.signal);
+        }
+        catch {
+            if (!res.headersSent && !gone.signal.aborted)
+                res.writeHead(400).end();
+            return;
+        }
+        if (gone.signal.aborted) {
+            if ('attempt' in outcome)
+                outcome.attempt.res?.destroy();
+            return;
+        }
+        if ('status' in outcome) {
+            res.writeHead(outcome.status, { 'content-type': 'application/json' }).end(outcome.body);
+            return;
+        }
+        const { attempt } = outcome;
+        if (!attempt.res) {
+            this.#o.log(`${req.method} ${pathOnly(req.url)}: the hub could not be reached (${attempt.error?.code ?? 'error'})`);
+            res.writeHead(502, { 'content-type': 'application/json' }).end(errorBody('bad_gateway', 'The hosted CLIProxyAPI could not be reached.'));
+            return;
+        }
+        const up = attempt.res;
+        res.writeHead(up.statusCode ?? 502, up.statusMessage, stripHopByHop(up.headers));
+        res.flushHeaders();
+        up.pipe(res);
+        up.on('error', () => res.destroy());
+        res.on('close', () => { if (!res.writableFinished)
+            up.destroy(); });
+    }
+    async #upgrade(req, socket, head) {
+        socket.on('error', () => socket.destroy());
+        this.#tunnels.add(socket);
+        socket.once('close', () => this.#tunnels.delete(socket));
+        const gone = new AbortController();
+        socket.once('close', () => gone.abort());
+        let outcome;
+        try {
+            outcome = await this.#attempts(req, true, gone.signal);
+        }
+        catch {
+            socket.destroy();
+            return;
+        }
+        const closed = gone.signal.aborted;
+        const raw = (status, message, headers) => {
+            const lines = [`HTTP/1.1 ${status} ${message ?? STATUS_CODES[status] ?? ''}`];
+            for (const [k, v] of Object.entries(headers))
+                for (const value of Array.isArray(v) ? v : [v])
+                    if (value !== undefined)
+                        lines.push(`${k}: ${value}`);
+            return `${lines.join('\r\n')}\r\n\r\n`;
+        };
+        if ('status' in outcome) {
+            socket.end(raw(outcome.status, undefined, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(outcome.body), connection: 'close' }) + outcome.body);
+            return;
+        }
+        const { attempt } = outcome;
+        if (attempt.upgrade) {
+            const { res, socket: upstream, head: upHead } = attempt.upgrade;
+            this.#tunnels.add(upstream);
+            upstream.once('close', () => this.#tunnels.delete(upstream));
+            if (closed || this.#closed) {
+                upstream.destroy();
+                socket.destroy();
+                return;
+            }
+            socket.write(raw(res.statusCode ?? 101, res.statusMessage, { ...res.headers }));
+            if (upHead.length)
+                socket.write(upHead);
+            if (head.length)
+                upstream.write(head);
+            upstream.on('error', () => socket.destroy());
+            socket.on('error', () => upstream.destroy());
+            upstream.on('close', () => socket.destroy());
+            socket.on('close', () => upstream.destroy());
+            upstream.pipe(socket);
+            socket.pipe(upstream);
+            return;
+        }
+        if (attempt.res) {
+            const up = attempt.res;
+            socket.write(raw(up.statusCode ?? 502, up.statusMessage, { ...stripHopByHop(up.headers), connection: 'close' }));
+            up.pipe(socket);
+            return;
+        }
+        const body = errorBody('bad_gateway', 'The hosted CLIProxyAPI could not be reached.');
+        socket.end(raw(502, undefined, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body), connection: 'close' }) + body);
+    }
+}