@limrun/api 0.49.3 → 0.50.1

package/exec-client.mjs

@@ -7,6 +7,7 @@
 import { createEventSource } from 'eventsource-client';
 import { nodeProxyTransport } from "./internal/proxy-transport.mjs";
 import { sseFetch } from "./internal/sse-fetch.mjs";
+import { directInstanceHttpError } from "./internal/direct-instance-errors.mjs";
 /**
  * Give-up policy for the exec event stream. The EventSource reconnects
  * forever on its own, so a dead exec (deleted instance, expired record)
@@ -63,6 +64,177 @@ export class ReadableStream {
         }
     }
 }
+/** Follow execution events until exitCode, with bounded retries and replay deduplication. */
+function followExecEventStream(options) {
+    let connection = null;
+    const { eventsUrl, signal } = options;
+    const result = new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(options.abortError());
+            return;
+        }
+        // Settle-once pair. Both paths close the source: the EventSource
+        // reconnects on its own otherwise, even after the promise is done.
+        let settled = false;
+        let lastSeenEventId = -1;
+        let streamDeadSince = 0;
+        let eventSource = null;
+        let connectedAt = 0;
+        let lastCycleAt = 0;
+        let lastCycleMono = 0;
+        let proofOfLifeThisCycle = false;
+        let cleanResponseThisCycle = false;
+        let lastStreamError;
+        const cleanup = () => {
+            eventSource?.close();
+            signal?.removeEventListener('abort', onAbort);
+        };
+        const succeed = (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(exitCode);
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        };
+        const onAbort = () => fail(options.abortError());
+        // Stream health is judged at the fetch surface, where the response
+        // status is visible; the library fires onConnect for error responses
+        // too, so an error page held open must not read as a healthy
+        // connection. An HTTP 204 makes the EventSource close for good
+        // without reporting anything, so it must fail here. A rejected fetch
+        // never reaches onDisconnect (the hazard sseFetch exists for):
+        // capture it for the give-up message and let the clock decide, so
+        // one transient refusal does not kill a live build.
+        const fetchWithStreamPolicy = async (input, init) => {
+            const response = await nodeProxyTransport.fetch(input, init);
+            if (response.status === 204) {
+                fail(new ExecStreamClosedError(`event stream to ${eventsUrl} was closed by the server (HTTP 204)`));
+            }
+            else if (options.failOnClientError &&
+                response.status >= 400 &&
+                response.status < 500 &&
+                response.status !== 408 &&
+                response.status !== 429) {
+                fail(directInstanceHttpError('GET exec logs', response.status, await response.text(), response.headers));
+            }
+            else if (!response.ok) {
+                lastStreamError = new Error(`server answered HTTP ${response.status}`);
+            }
+            cleanResponseThisCycle = response.ok;
+            return response;
+        };
+        eventSource = createEventSource({
+            url: eventsUrl,
+            fetch: sseFetch(fetchWithStreamPolicy, (err) => {
+                lastStreamError = err instanceof Error ? err : new Error(String(err));
+            }),
+            headers: { Authorization: `Bearer ${options.token}` },
+            onConnect: () => {
+                connectedAt = Date.now();
+            },
+            // Comments count as proof of life, so a server-side keepalive
+            // works without a client change (onMessage never sees them).
+            onComment: () => {
+                proofOfLifeThisCycle = true;
+            },
+            // Fires once per broken cycle, before the retry timer is armed, on
+            // both failure paths (request rejected, stream ended). This is
+            // where the give-up clock runs.
+            onScheduleReconnect: () => {
+                if (settled || signal?.aborted) {
+                    return;
+                }
+                const now = Date.now();
+                const mono = performance.now();
+                const livedMs = connectedAt > 0 ? now - connectedAt : 0;
+                connectedAt = 0;
+                // Date.now() is wall clock: a laptop waking from sleep (or a
+                // clock step) would arrive with the whole window already
+                // "elapsed" and fail on its first attempt. Sleep is the wall
+                // clock advancing while the monotonic clock stands still; a
+                // large drift between the two restarts the streak. Long server
+                // retry delays and hanging connects advance both clocks equally
+                // and keep counting.
+                if (streamDeadSince > 0 && lastCycleAt > 0) {
+                    const wallGapMs = now - lastCycleAt;
+                    const monoGapMs = mono - lastCycleMono;
+                    if (wallGapMs - monoGapMs > 30000) {
+                        streamDeadSince = now;
+                        options.onStreamDeadSince?.(streamDeadSince);
+                    }
+                }
+                lastCycleAt = now;
+                lastCycleMono = mono;
+                const healthy = proofOfLifeThisCycle || (cleanResponseThisCycle && livedMs >= sseStreamPolicy.healthyConnectionMs);
+                proofOfLifeThisCycle = false;
+                cleanResponseThisCycle = false;
+                if (healthy) {
+                    streamDeadSince = 0;
+                    options.onStreamDeadSince?.(0);
+                    lastStreamError = undefined;
+                    return;
+                }
+                if (streamDeadSince === 0) {
+                    streamDeadSince = now;
+                    options.onStreamDeadSince?.(streamDeadSince);
+                    options.log?.('warn', 'SSE disconnected; reconnecting');
+                    return;
+                }
+                if (now - streamDeadSince >= sseStreamPolicy.giveUpAfterMs) {
+                    const seconds = Math.round((now - streamDeadSince) / 1000);
+                    const cause = lastStreamError ? `; last error: ${lastStreamError.message}` : '';
+                    fail(new ExecStreamLostError(`event stream to ${eventsUrl} kept failing for ${seconds}s without delivering events${cause}; ` +
+                        'the execution may no longer exist (instance deleted or record expired)'));
+                }
+            },
+            onMessage: (message) => {
+                if (settled)
+                    return;
+                streamDeadSince = 0;
+                options.onStreamDeadSince?.(0);
+                proofOfLifeThisCycle = true;
+                lastStreamError = undefined;
+                const eventId = message.id !== undefined ? Number.parseInt(message.id, 10) : NaN;
+                if (!Number.isNaN(eventId)) {
+                    if (eventId <= lastSeenEventId)
+                        return;
+                    lastSeenEventId = eventId;
+                }
+                try {
+                    const event = {
+                        ...(message.id !== undefined && { id: message.id }),
+                        type: message.event || 'message',
+                        data: typeof message.data === 'string' ? message.data : String(message.data ?? ''),
+                    };
+                    options.onEvent(event);
+                    if (event.type === 'exitCode') {
+                        const exitCode = parseExitCode(event.data);
+                        options.log?.('debug', `Execution completed via SSE: exitCode=${exitCode}`);
+                        succeed(exitCode);
+                    }
+                }
+                catch (error) {
+                    fail(error);
+                }
+            },
+        });
+        connection = eventSource;
+        if (settled) {
+            eventSource.close();
+        }
+        else {
+            signal?.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+    return { connection, result };
+}
 /**
  * A ChildProcess-like object similar to Node.js's ChildProcess.
  *
@@ -100,11 +272,6 @@ export class ExecChildProcess {
         this.playstoreEvent = null;
         this.xctestCases = [];
         this.xctestSummary = null;
-        // Highest server-assigned event id already dispatched. The server numbers
-        // every frame and replays the stream from the start on reconnect; skipping
-        // ids at or below this mark drops the replayed prefix for every event type
-        // at once, and stays correct if the server ever honors Last-Event-ID.
-        this.lastSeenEventId = -1;
         this.options = options;
         this.log = options.log ?? (() => { });
         this.startedPromise = new Promise((resolve, reject) => {
@@ -356,215 +523,212 @@ export class ExecChildProcess {
      * closes the stream for good, or when the give-up clock runs out.
      */
     connectSSE(eventsUrl) {
-        return new Promise((resolve, reject) => {
-            const signal = this.abortController.signal;
-            if (signal.aborted) {
-                reject(new Error('killed'));
-                return;
-            }
-            // Settle-once pair. Both paths close the source: the EventSource
-            // reconnects on its own otherwise, even after the promise is done.
-            let settled = false;
-            let connectedAt = 0;
-            let lastCycleAt = 0;
-            let lastCycleMono = 0;
-            let proofOfLifeThisCycle = false;
-            let cleanResponseThisCycle = false;
-            let lastStreamError;
-            const cleanup = () => {
-                eventSource.close();
-                signal.removeEventListener('abort', onAbort);
-            };
-            const succeed = (exitCode) => {
-                if (settled)
-                    return;
-                settled = true;
-                cleanup();
-                resolve(exitCode);
-            };
-            const fail = (error) => {
-                if (settled)
-                    return;
-                settled = true;
-                cleanup();
-                reject(error);
-            };
-            const onAbort = () => fail(new Error('killed'));
-            // Stream health is judged at the fetch surface, where the response
-            // status is visible; the library fires onConnect for error responses
-            // too, so an error page held open must not read as a healthy
-            // connection. An HTTP 204 makes the EventSource close for good
-            // without reporting anything, so it must fail here. A rejected fetch
-            // never reaches onDisconnect (the hazard sseFetch exists for):
-            // capture it for the give-up message and let the clock decide, so
-            // one transient refusal does not kill a live build.
-            const fetchWithStreamPolicy = async (input, init) => {
-                const response = await nodeProxyTransport.fetch(input, init);
-                if (response.status === 204) {
-                    fail(new ExecStreamClosedError(`event stream to ${eventsUrl} was closed by the server (HTTP 204)`));
+        const stream = followExecEventStream({
+            eventsUrl,
+            token: this.options.token,
+            signal: this.abortController.signal,
+            abortError: () => new Error('killed'),
+            log: this.log,
+            onStreamDeadSince: (since) => {
+                this.streamDeadSince = since;
+            },
+            onEvent: ({ type: eventType, data }) => {
+                if (eventType === 'command') {
+                    this.command.emit('data', data);
                 }
-                else if (!response.ok) {
-                    lastStreamError = new Error(`server answered HTTP ${response.status}`);
+                else if (eventType === 'stdout') {
+                    this.stdout.emit('data', data);
                 }
-                cleanResponseThisCycle = response.ok;
-                return response;
-            };
-            const eventSource = createEventSource({
-                url: eventsUrl,
-                fetch: sseFetch(fetchWithStreamPolicy, (err) => {
-                    lastStreamError = err instanceof Error ? err : new Error(String(err));
-                }),
-                headers: { Authorization: `Bearer ${this.options.token}` },
-                onConnect: () => {
-                    connectedAt = Date.now();
-                },
-                // Comments count as proof of life, so a server-side keepalive
-                // works without a client change (onMessage never sees them).
-                onComment: () => {
-                    proofOfLifeThisCycle = true;
-                },
-                // Fires once per broken cycle, before the retry timer is armed, on
-                // both failure paths (request rejected, stream ended). This is
-                // where the give-up clock runs.
-                onScheduleReconnect: () => {
-                    if (settled || this.killed) {
-                        return;
-                    }
-                    const now = Date.now();
-                    const mono = performance.now();
-                    const livedMs = connectedAt > 0 ? now - connectedAt : 0;
-                    connectedAt = 0;
-                    // Date.now() is wall clock: a laptop waking from sleep (or a
-                    // clock step) would arrive with the whole window already
-                    // "elapsed" and fail on its first attempt. Sleep is the wall
-                    // clock advancing while the monotonic clock stands still; a
-                    // large drift between the two restarts the streak. Long server
-                    // retry delays and hanging connects advance both clocks equally
-                    // and keep counting.
-                    if (this.streamDeadSince > 0 && lastCycleAt > 0) {
-                        const wallGapMs = now - lastCycleAt;
-                        const monoGapMs = mono - lastCycleMono;
-                        if (wallGapMs - monoGapMs > 30000) {
-                            this.streamDeadSince = now;
-                        }
+                else if (eventType === 'stderr') {
+                    this.stderr.emit('data', data);
+                }
+                else if (eventType === 'testflight') {
+                    try {
+                        this.appStoreEvent = JSON.parse(data);
                     }
-                    lastCycleAt = now;
-                    lastCycleMono = mono;
-                    const healthy = proofOfLifeThisCycle ||
-                        (cleanResponseThisCycle && livedMs >= sseStreamPolicy.healthyConnectionMs);
-                    proofOfLifeThisCycle = false;
-                    cleanResponseThisCycle = false;
-                    if (healthy) {
-                        this.streamDeadSince = 0;
-                        lastStreamError = undefined;
-                        return;
+                    catch {
+                        // The wire event itself proves the server ran the App Store upload,
+                        // so never let a payload glitch look like a missing feature.
+                        this.appStoreEvent = { state: 'unknown' };
+                        this.log('warn', `SSE testflight event has invalid data: ${data}`);
                     }
-                    if (this.streamDeadSince === 0) {
-                        this.streamDeadSince = now;
-                        this.log('warn', 'SSE disconnected; reconnecting');
-                        return;
+                }
+                else if (eventType === 'playstore') {
+                    try {
+                        this.playstoreEvent = JSON.parse(data);
                     }
-                    if (now - this.streamDeadSince >= sseStreamPolicy.giveUpAfterMs) {
-                        const seconds = Math.round((now - this.streamDeadSince) / 1000);
-                        const cause = lastStreamError ? `; last error: ${lastStreamError.message}` : '';
-                        fail(new ExecStreamLostError(`event stream to ${eventsUrl} kept failing for ${seconds}s without delivering events${cause}; ` +
-                            'the execution may no longer exist (instance deleted or record expired)'));
+                    catch {
+                        // Same contract as the App Store upload event: its presence proves the server
+                        // ran the Play Store step, so a payload glitch must not
+                        // read as a missing feature.
+                        this.playstoreEvent = { state: 'unknown' };
+                        this.log('warn', `SSE playstore event has invalid data: ${data}`);
                     }
-                },
-                onMessage: (message) => {
-                    this.streamDeadSince = 0;
-                    proofOfLifeThisCycle = true;
-                    lastStreamError = undefined;
-                    const eventId = message.id !== undefined ? parseInt(message.id, 10) : NaN;
-                    if (!Number.isNaN(eventId)) {
-                        if (eventId <= this.lastSeenEventId) {
-                            // A reconnect replays the stream from the start; this frame was
-                            // already dispatched on an earlier connection.
-                            return;
+                }
+                else if (eventType === 'xctest') {
+                    let event;
+                    try {
+                        const parsed = JSON.parse(data);
+                        if (parsed?.type === 'case') {
+                            this.xctestCases.push(parsed);
+                            event = parsed;
                         }
-                        this.lastSeenEventId = eventId;
-                    }
-                    const data = typeof message.data === 'string' ? message.data : String(message.data ?? '');
-                    const eventType = message.event;
-                    if (eventType === 'command') {
-                        this.command.emit('data', data);
-                    }
-                    else if (eventType === 'stdout') {
-                        this.stdout.emit('data', data);
-                    }
-                    else if (eventType === 'stderr') {
-                        this.stderr.emit('data', data);
-                    }
-                    else if (eventType === 'testflight') {
-                        try {
-                            this.appStoreEvent = JSON.parse(data);
+                        else if (parsed?.type === 'summary') {
+                            this.xctestSummary = parsed;
+                            event = parsed;
                         }
-                        catch {
-                            // The wire event itself proves the server ran the App Store upload,
-                            // so never let a payload glitch look like a missing feature.
-                            this.appStoreEvent = { state: 'unknown' };
-                            this.log('warn', `SSE testflight event has invalid data: ${data}`);
+                        else {
+                            // The simulator owns the frame vocabulary and may grow it; the
+                            // callback's contract is cases and summaries only.
+                            this.log('debug', `SSE xctest event of unknown type ignored: ${data}`);
                         }
                     }
-                    else if (eventType === 'playstore') {
-                        try {
-                            this.playstoreEvent = JSON.parse(data);
-                        }
-                        catch {
-                            // Same contract as the App Store upload event: its presence proves the server
-                            // ran the Play Store step, so a payload glitch must not
-                            // read as a missing feature.
-                            this.playstoreEvent = { state: 'unknown' };
-                            this.log('warn', `SSE playstore event has invalid data: ${data}`);
-                        }
+                    catch {
+                        this.log('warn', `SSE xctest event has invalid data: ${data}`);
                     }
-                    else if (eventType === 'xctest') {
-                        let event;
+                    if (event) {
                         try {
-                            const parsed = JSON.parse(data);
-                            if (parsed?.type === 'case') {
-                                this.xctestCases.push(parsed);
-                                event = parsed;
-                            }
-                            else if (parsed?.type === 'summary') {
-                                this.xctestSummary = parsed;
-                                event = parsed;
-                            }
-                            else {
-                                // The simulator owns the frame vocabulary and may grow it; the
-                                // callback's contract is cases and summaries only.
-                                this.log('debug', `SSE xctest event of unknown type ignored: ${data}`);
-                            }
+                            this.options.onXctestEvent?.(event);
                         }
-                        catch {
-                            this.log('warn', `SSE xctest event has invalid data: ${data}`);
+                        catch (err) {
+                            // The consumer's callback, not the frame: the run must not be
+                            // derailed and the log must not blame the payload.
+                            this.log('warn', `onXctestEvent callback threw: ${String(err)}`);
                         }
-                        if (event) {
-                            try {
-                                this.options.onXctestEvent?.(event);
-                            }
-                            catch (err) {
-                                // The consumer's callback, not the frame: the run must not be
-                                // derailed and the log must not blame the payload.
-                                this.log('warn', `onXctestEvent callback threw: ${String(err)}`);
-                            }
-                        }
-                    }
-                    else if (eventType === 'exitCode') {
-                        const exitCode = parseInt(data, 10);
-                        if (Number.isNaN(exitCode)) {
-                            this.log('warn', `SSE exitCode event has invalid data: ${data}`);
-                            return;
-                        }
-                        this.log('debug', `Execution completed via SSE: exitCode=${exitCode}`);
-                        succeed(exitCode);
                     }
-                },
-            });
-            this.sseConnection = eventSource;
-            signal.addEventListener('abort', onAbort, { once: true });
+                }
+            },
+        });
+        this.sseConnection = stream.connection;
+        return stream.result;
+    }
+}
+/**
+ * Replay logs for an existing execution, optionally following it to completion.
+ * Snapshot mode uses a finite SSE response; follow mode consumes the same
+ * replayable stream until its terminal exitCode event.
+ */
+export async function observeExecLogs(execId, options) {
+    if (!execId.trim()) {
+        throw new Error('execId must not be empty');
+    }
+    const follow = options.follow ?? false;
+    // Resolve mutable aliases once so a reconnect cannot switch to another build.
+    if (follow && (execId === 'active' || execId === 'latest')) {
+        const snapshotEvents = [];
+        const snapshot = await observeExecLogs(execId, {
+            ...options,
+            follow: false,
+            onEvent: (event) => snapshotEvents.push(event),
+        });
+        if (snapshot.status !== 'RUNNING') {
+            for (const event of snapshotEvents)
+                options.onEvent?.(event);
+            return snapshot;
+        }
+        if (snapshot.execId === execId) {
+            throw new Error(`The server did not resolve the ${execId} build alias.`);
+        }
+        return observeExecLogs(snapshot.execId, options);
+    }
+    let apiUrlEnd = options.apiUrl.length;
+    while (options.apiUrl[apiUrlEnd - 1] === '/')
+        apiUrlEnd--;
+    const eventsUrl = new URL(`${options.apiUrl.slice(0, apiUrlEnd)}/exec/${encodeURIComponent(execId)}/events`);
+    eventsUrl.searchParams.set('follow', String(follow));
+    if (!follow) {
+        const response = await nodeProxyTransport.fetch(eventsUrl, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${options.token}` },
+            ...(options.signal && { signal: options.signal }),
         });
+        if (!response.ok) {
+            const text = await response.text();
+            throw directInstanceHttpError('GET exec logs', response.status, text, response.headers);
+        }
+        const events = parseSSE(await response.text());
+        let exitCode;
+        let resolvedExecId = execId;
+        for (const event of events) {
+            resolvedExecId = execIdFromMeta(event, resolvedExecId);
+            options.onEvent?.(event);
+            if (event.type === 'exitCode') {
+                exitCode = parseExitCode(event.data);
+            }
+        }
+        return buildExecLogResult(resolvedExecId, exitCode);
+    }
+    let resolvedExecId = execId;
+    const stream = followExecEventStream({
+        eventsUrl: eventsUrl.toString(),
+        token: options.token,
+        ...(options.signal && { signal: options.signal }),
+        failOnClientError: true,
+        log: options.log,
+        abortError: () => new Error(`exec log stream for ${execId} was aborted`),
+        onEvent: (event) => {
+            resolvedExecId = execIdFromMeta(event, resolvedExecId);
+            options.onEvent?.(event);
+        },
+    });
+    const exitCode = await stream.result;
+    return buildExecLogResult(resolvedExecId, exitCode);
+}
+function parseSSE(body) {
+    const normalized = body.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    const events = [];
+    for (const block of normalized.split('\n\n')) {
+        if (!block.trim())
+            continue;
+        let id;
+        let type = 'message';
+        const data = [];
+        for (const line of block.split('\n')) {
+            if (line.startsWith('id:')) {
+                id = line.slice(3).trimStart();
+            }
+            else if (line.startsWith('event:')) {
+                type = line.slice(6).trimStart();
+            }
+            else if (line.startsWith('data:')) {
+                data.push(line.slice(5).replace(/^ /, ''));
+            }
+        }
+        if (data.length > 0 || type !== 'message' || id !== undefined) {
+            events.push({ ...(id !== undefined && { id }), type, data: data.join('\n') });
+        }
+    }
+    return events;
+}
+function parseExitCode(data) {
+    const exitCode = Number.parseInt(data, 10);
+    if (Number.isNaN(exitCode)) {
+        throw new Error(`invalid exec exit code: ${data}`);
     }
+    return exitCode;
+}
+function execIdFromMeta(event, fallback) {
+    if (event.type !== 'meta')
+        return fallback;
+    try {
+        const meta = JSON.parse(event.data);
+        return typeof meta.id === 'string' && meta.id ? meta.id : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+function buildExecLogResult(execId, exitCode) {
+    if (exitCode === undefined) {
+        return { execId, status: 'RUNNING' };
+    }
+    return {
+        execId,
+        exitCode,
+        status: exitCode === 0 ? 'SUCCEEDED'
+            : exitCode === -1 ? 'CANCELLED'
+                : 'FAILED',
+    };
 }
 /**
  * Execute a command on the limbuild server.