@simantic/cloud-sim 0.1.0

package/dist/errors.js

@@ -0,0 +1,111 @@
+// Every failure the SDK reports, other than an aborted signal (which throws
+// the signal's own reason, as fetch does).
+/**
+ * A request the Cloud Sim API refused or never answered.
+ *
+ * `status` is the HTTP status, or 0 when no answer arrived (offline, DNS, a
+ * CORS refusal, `timeoutMs` passed). `code` is a stable name for programs,
+ * such as `mcu_not_supported`, `network_error` or `timeout`; `param` names
+ * the request field at fault, when one is; `requestId` is the request's
+ * `X-Request-Id`, worth quoting in a bug report. `transient` says whether
+ * the same request may work later.
+ */
+export class CloudSimError extends Error {
+    status;
+    code;
+    param;
+    requestId;
+    transient;
+    constructor(message, init) {
+        super(message);
+        this.name = 'CloudSimError';
+        this.status = init.status;
+        this.code = init.code;
+        this.param = init.param ?? null;
+        this.requestId = init.requestId ?? null;
+        this.transient = init.transient ?? transientStatus(init.status);
+    }
+}
+/**
+ * `runs.compare` made some of its runs but not all. The runs it made go on
+ * on the server and count against the caller's limit: follow them, or
+ * cancel them. Its status, code, param and request id are the first
+ * failure's, and it is `transient` only if every failure is. The Python
+ * SDK's `CompareError` has the same fields.
+ */
+export class CompareError extends CloudSimError {
+    /** The version the comparison was made on. */
+    version;
+    /** The runs made, by engine, in the order the engines were given. */
+    runs;
+    /**
+     * Why each other engine's run was not made, by engine, in the same order:
+     * a `CloudSimError`, or whatever else the create threw.
+     */
+    errors;
+    constructor(version, runs, errors) {
+        const failures = Object.entries(errors);
+        const first = failures[0]?.[1];
+        const why = failures
+            .map(([engine, e]) => `${engine}: ${e instanceof Error ? e.message : String(e)}`)
+            .join('; ');
+        const made = Object.keys(runs);
+        let message = `${failures.length} of ${failures.length + made.length} runs could not be made (${why})`;
+        if (made.length > 0)
+            message += `; the runs on ${made.join(', ')} were made and run on`;
+        super(message, {
+            status: first instanceof CloudSimError ? first.status : 0,
+            code: first instanceof CloudSimError ? first.code : 'compare_failed',
+            param: first instanceof CloudSimError ? first.param : null,
+            requestId: first instanceof CloudSimError ? first.requestId : null,
+            transient: failures.every(([, e]) => isTransient(e)),
+        });
+        this.name = 'CompareError';
+        this.version = version;
+        this.runs = runs;
+        this.errors = errors;
+    }
+}
+/**
+ * Whether `error` is a failure that may go away if the same request is made
+ * again: a `CloudSimError` that is `transient`.
+ */
+export function isTransient(error) {
+    return error instanceof CloudSimError && error.transient;
+}
+/**
+ * Whether an answer with `status` may change if the request is made again:
+ * none arrived (0), the caller is at their run limit (429), or the server or
+ * the edge in front of it could not answer (502, 503, 504). Any other status
+ * is the server's answer to this request.
+ */
+export function transientStatus(status) {
+    return status === 0 || status === 429 || status === 502 || status === 503 || status === 504;
+}
+/** The code the server gives an error of `status` that names none of its own. */
+export function generalCode(status) {
+    switch (status) {
+        case 400:
+            return 'invalid_request';
+        case 401:
+            return 'unauthorized';
+        case 403:
+            return 'forbidden';
+        case 404:
+            return 'not_found';
+        case 409:
+            return 'conflict';
+        case 410:
+            return 'gone';
+        case 413:
+            return 'payload_too_large';
+        case 415:
+            return 'unsupported_media_type';
+        case 429:
+            return 'too_many_runs';
+        case 503:
+            return 'unavailable';
+        default:
+            return status >= 500 ? 'internal_error' : 'http_error';
+    }
+}

package/dist/follow.d.ts

@@ -0,0 +1,61 @@
+import { CloudSimError } from './errors.js';
+import { type Transport } from './http.js';
+import { type Run } from './types.js';
+/** One of a run's two streams: the engine's console, or its UART output. */
+export type StreamName = 'log' | 'output';
+/** Where each stream has been read to, in bytes, as `log`/`output` events' `next` say. */
+export interface Offsets {
+    log: number;
+    output: number;
+}
+export type FollowEvent = 
+/** The run: first, each time its status changes, and after a recovery. */
+{
+    type: 'status';
+    run: Run;
+}
+/** More of the engine's console; `next` is where the console has been read to. */
+ | {
+    type: 'log';
+    text: string;
+    next: number;
+}
+/** More of the UART output; `next` is where it has been read to. */
+ | {
+    type: 'output';
+    text: string;
+    next: number;
+}
+/** Drop what this stream has had so far: it starts over. */
+ | {
+    type: 'reset';
+    stream: StreamName;
+}
+/** A failure is being retried; a `status` follows once it has recovered. */
+ | {
+    type: 'reconnecting';
+    error: CloudSimError;
+}
+/** The run has finished and both streams are complete. The last event. */
+ | {
+    type: 'end';
+    run: Run;
+};
+export type FollowTransport = 'auto' | 'sse' | 'poll';
+export interface FollowOptions {
+    /** Ends the iteration: it throws the signal's reason. */
+    signal?: AbortSignal;
+    /** `auto` (the default: `sse`, falling back to `poll`), `sse` or `poll`. */
+    transport?: FollowTransport;
+    /** How long `poll` waits between pages while nothing more is waiting. */
+    intervalMs?: number;
+    /**
+     * Where to start each stream: the `next` of the last `log` and `output`
+     * events of an earlier follow (0 for a stream that had none). Left out,
+     * both start at 0.
+     */
+    from?: Offsets;
+}
+/** The wait between pages while nothing more is waiting, as the dashboard has it. */
+export declare const POLL_INTERVAL_MS = 750;
+export declare function follow(http: Transport, id: string, options?: FollowOptions): AsyncGenerator<FollowEvent, void, undefined>;

package/dist/follow.js

@@ -0,0 +1,277 @@
+// `runs.follow`: a run's status and output as events, from wherever it is
+// (or from the offsets given) to its end. The text of the `log` events,
+// concatenated, is the run's whole console, and that of the `output` events
+// its whole UART output, with one exception: a `reset` says the run's final
+// result differs from what it shipped while it ran, and that stream starts
+// over, so whatever was kept of it is to be dropped. Each `log` and
+// `output` event says where its stream has been read to (`next`), so a
+// caller that stops can follow again `from` there.
+//
+// Two transports give the same events:
+// - `sse` reads GET /v1/runs/{id}/events, and when a stream closes before
+//   `end` (the server ends each connection after at most 10 minutes) it
+//   reconnects with Last-Event-ID, which resumes after the last whole
+//   event. The server's `error` event (it could not read the run, as in a
+//   store outage) and a connection lost mid-stream are transient failures:
+//   the stream waits (the event's `retry`, 5 s) and reconnects, and fails
+//   only after `maxRetries` of them with nothing new in between;
+// - `poll` pages GET /v1/runs/{id}/live, sending back each stream's `next`.
+//   This ports the homepage dashboard's polling loop; unlike the legacy
+//   /jobs/{id}/live, /v1's keeps serving pages after the run ends, from its
+//   result, so the pages alone make up the whole output.
+// `auto`, the default, is `sse` that falls back to `poll` when the events
+// request fails before its first event: a server without the route (404,
+// 405), something in between that will not pass an event stream, or a
+// network failure. Once an event has arrived it stays on `sse`. SSE through
+// the edge (Cloudflare, then InstaCloud) was checked in the plan's spike
+// S1: unbuffered, open past 10 minutes, idle streams kept by keep-alives.
+//
+// While a failure is being retried, either transport says so with a
+// `reconnecting` event, and the first event once it has recovered is a
+// `status`, even if the status is the same, so a UI can show
+// "Reconnecting…" between the two.
+import { CloudSimError } from './errors.js';
+import { isRecord, segment, sleep } from './http.js';
+import { SseParser, readEvents } from './sse.js';
+import { isFinished } from './types.js';
+/** The wait between pages while nothing more is waiting, as the dashboard has it. */
+export const POLL_INTERVAL_MS = 750;
+// Until the server names one: the API's own `retry` is 1 s.
+const RECONNECT_MS = 1_000;
+export async function* follow(http, id, options = {}) {
+    // A signal of the follow's own, so a caller that stops iterating also
+    // stops whatever request or retry is still under way.
+    const outer = options.signal;
+    const controller = new AbortController();
+    const onAbort = () => controller.abort(outer?.reason);
+    if (outer?.aborted)
+        onAbort();
+    else
+        outer?.addEventListener('abort', onAbort, { once: true });
+    const inner = { ...options, signal: controller.signal };
+    try {
+        switch (options.transport ?? 'auto') {
+            case 'poll':
+                return yield* followPoll(http, id, inner);
+            case 'sse':
+                return yield* followSse(http, id, inner, false);
+            default:
+                return yield* followSse(http, id, inner, true);
+        }
+    }
+    finally {
+        outer?.removeEventListener('abort', onAbort);
+        controller.abort();
+    }
+}
+async function* followPoll(http, id, { signal, intervalMs = POLL_INTERVAL_MS, from }) {
+    const at = { log: from?.log ?? 0, output: from?.output ?? 0 };
+    let status;
+    // A failure was retried: the next status is news whatever it is.
+    let recovered = false;
+    for (;;) {
+        const page = yield* surfacing((onRetry) => http.json({
+            method: 'GET',
+            path: `/v1/runs/${segment(id)}/live`,
+            query: { log: at.log, output: at.output },
+            signal,
+            onRetry,
+            retry: true,
+        }), () => {
+            recovered = true;
+        });
+        if (page.run.status !== status || recovered) {
+            status = page.run.status;
+            recovered = false;
+            yield { type: 'status', run: page.run };
+        }
+        for (const stream of ['log', 'output']) {
+            const part = page[stream];
+            // Sent back as it came: it counts bytes, and a character cut off at
+            // the end of what has arrived waits for the next page.
+            at[stream] = part.next;
+            if (part.reset)
+                yield { type: 'reset', stream };
+            if (part.text)
+                yield { type: stream, text: part.text, next: part.next };
+        }
+        const more = page.log.more || page.output.more;
+        if (isFinished(page.run) && !more) {
+            yield { type: 'end', run: page.run };
+            return;
+        }
+        // What is already waiting is read at once.
+        if (!more)
+            await sleep(intervalMs, signal);
+    }
+}
+/**
+ * The run's event stream. With `fallback`, a stream that fails before its
+ * first event gives way to polling, from where it was asked to start: no
+ * event has been passed on yet, so none is repeated.
+ */
+async function* followSse(http, id, options, fallback) {
+    const { signal, from } = options;
+    // `from` is resumed from as an event id would be.
+    const parser = new SseParser(from ? `${from.log}:${from.output}` : undefined);
+    let status;
+    // Whether an event has arrived: from then on, this is the transport.
+    let received = false;
+    // Failures of the stream since it last had news for the caller.
+    let failures = 0;
+    const fallingBack = (e) => fallback && !received && !signal?.aborted && !refusesCaller(e);
+    // A failure was retried: the next status is passed on whatever it is
+    // (but is news, which resets `failures`, only if it changed).
+    let recovered = false;
+    const recovering = () => {
+        recovered = true;
+    };
+    for (;;) {
+        const headers = { Accept: 'text/event-stream' };
+        // Only an id the server gave (or `from`): it refuses any other (400).
+        if (parser.lastId)
+            headers['Last-Event-ID'] = parser.lastId;
+        let body;
+        try {
+            const response = yield* surfacing((onRetry) => http.stream({
+                method: 'GET',
+                path: `/v1/runs/${segment(id)}/events`,
+                headers,
+                signal,
+                onRetry,
+                // Before the first event, falling back to polling is the retry.
+                retry: received || !fallback,
+            }), recovering);
+            body = eventStream(response);
+        }
+        catch (e) {
+            if (fallingBack(e))
+                return yield* followPoll(http, id, options);
+            throw e;
+        }
+        let failure;
+        try {
+            read: for await (const event of readEvents(body, parser)) {
+                const data = JSON.parse(event.data);
+                received = true;
+                switch (event.event) {
+                    case 'status': {
+                        const run = data;
+                        // Each connection starts with the run again: it is passed on
+                        // when its status changed, or after a failure.
+                        if (run.status !== status || recovered) {
+                            if (run.status !== status)
+                                failures = 0;
+                            status = run.status;
+                            recovered = false;
+                            yield { type: 'status', run };
+                        }
+                        break;
+                    }
+                    case 'log':
+                    case 'output': {
+                        if (!isRecord(data) || typeof data.next !== 'number')
+                            break;
+                        failures = 0;
+                        if (data.reset === true)
+                            yield { type: 'reset', stream: event.event };
+                        if (typeof data.text === 'string' && data.text) {
+                            yield { type: event.event, text: data.text, next: data.next };
+                        }
+                        break;
+                    }
+                    case 'end':
+                        yield { type: 'end', run: data };
+                        return;
+                    case 'error':
+                        // The server could not read the run, and closes the stream.
+                        failure = streamError(data);
+                        break read;
+                }
+            }
+        }
+        catch (e) {
+            if (signal?.aborted)
+                throw signal.reason;
+            if (fallingBack(e))
+                return yield* followPoll(http, id, options);
+            // A connection lost mid-stream is picked up again below; anything
+            // else is the caller's.
+            if (!(e instanceof TypeError))
+                throw e;
+            failure = new CloudSimError('The connection to the Cloud Sim API was lost.', {
+                status: 0,
+                code: 'network_error',
+            });
+        }
+        // Closed without a single event: as good as refused.
+        if (fallingBack(undefined))
+            return yield* followPoll(http, id, options);
+        if (failure) {
+            if (++failures > http.maxRetries)
+                throw failure;
+            recovering();
+            yield { type: 'reconnecting', error: failure };
+        }
+        // The stream closed before `end` (the server ends each connection after
+        // at most 10 minutes), or failed: pick it up where it was, as soon as
+        // the server asked (5 s after an `error`).
+        await sleep(parser.retry ?? RECONNECT_MS, signal);
+    }
+}
+/**
+ * The answer of `request`, passing on each retry it makes on the way as a
+ * `reconnecting` event (after calling `onRecovering`), as the retries
+ * happen rather than once the answer is in.
+ */
+async function* surfacing(request, onRecovering) {
+    const retries = [];
+    let settled;
+    let wake;
+    request((info) => {
+        retries.push(info.error);
+        wake?.();
+    }).then((value) => {
+        settled = { value };
+        wake?.();
+    }, (error) => {
+        settled = { error };
+        wake?.();
+    });
+    for (;;) {
+        const error = retries.shift();
+        if (error) {
+            onRecovering();
+            yield { type: 'reconnecting', error };
+            continue;
+        }
+        if (settled) {
+            if ('error' in settled)
+                throw settled.error;
+            return settled.value;
+        }
+        // Nothing can arrive between the checks above and this: callbacks run
+        // only once this function awaits.
+        await new Promise((resolve) => {
+            wake = resolve;
+        });
+    }
+}
+/** The body of an answer that is an event stream, or why it is not one. */
+function eventStream(response) {
+    const type = response.headers.get('Content-Type') ?? '';
+    if (!response.body || !type.toLowerCase().startsWith('text/event-stream')) {
+        response.body?.cancel().catch(() => { });
+        throw new CloudSimError(`The Cloud Sim API answered the event stream with ${type || 'no Content-Type'}.`, { status: response.status, code: 'invalid_response' });
+    }
+    return response.body;
+}
+/** A refusal of the caller, which polling would get as well. */
+function refusesCaller(e) {
+    return e instanceof CloudSimError && (e.status === 401 || e.status === 403);
+}
+/** An `error` event's `{"error", "code"}`, as the failure it stands for. */
+function streamError(data) {
+    const body = isRecord(data) ? data : {};
+    return new CloudSimError(typeof body.error === 'string' ? body.error : 'The Cloud Sim API could not read the run.', { status: 503, code: typeof body.code === 'string' ? body.code : 'unavailable' });
+}