@simantic/cloud-sim 0.1.0

package/dist/generated/v1.js

@@ -0,0 +1,5 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};

package/dist/http.d.ts

@@ -0,0 +1,89 @@
+import { CloudSimError } from './errors.js';
+export declare const DEFAULT_BASE_URL = "https://cloud.simantic.com";
+export type ApiKey = string | (() => string | Promise<string>);
+/** A retry about to be made, as `onRetry` hears of it. */
+export interface RetryInfo {
+    /** Which retry this is: 1 for the first. */
+    attempt: number;
+    /** The failure being retried. */
+    error: CloudSimError;
+    /** How long until the retry is sent. */
+    delayMs: number;
+}
+export interface TransportOptions {
+    apiKey: ApiKey;
+    version?: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    onUnauthorized?: () => Promise<void> | void;
+    maxRetries?: number;
+    timeoutMs?: number;
+    onRetry?: (info: RetryInfo) => void;
+}
+export type Query = Record<string, string | number | boolean | undefined>;
+export interface Call {
+    method: 'GET' | 'POST';
+    path: string;
+    query?: Query;
+    /** A JSON body. */
+    json?: unknown;
+    /** A multipart body. fetch sets its Content-Type, boundary included. */
+    form?: FormData;
+    headers?: Record<string, string>;
+    /** `Cloud-Sim-Version` for this call, in place of the client's. */
+    version?: string | undefined;
+    signal?: AbortSignal | undefined;
+    /** The time limit on the answer's headers for this call, in place of the client's. */
+    timeoutMs?: number | undefined;
+    /** Told of each retry of this call, after the client's `onRetry`. */
+    onRetry?: ((info: RetryInfo) => void) | undefined;
+    /**
+     * Whether a transient failure may be sent again: true for reads, for a
+     * create that carries an Idempotency-Key, which the server answers with
+     * the run it already made, and for a cancel, which it answers with the
+     * run as it is.
+     */
+    retry: boolean;
+}
+export declare class Transport {
+    readonly version: string | undefined;
+    readonly baseUrl: string;
+    /** How many times a transient failure is tried again. */
+    readonly maxRetries: number;
+    private readonly apiKey;
+    private readonly fetch;
+    private readonly onUnauthorized;
+    private readonly timeoutMs;
+    private readonly onRetry;
+    constructor(options: TransportOptions);
+    /** The answer as JSON. */
+    json<T>(call: Call): Promise<T>;
+    /** The answer as text. */
+    text(call: Call): Promise<string>;
+    /**
+     * The answer itself, its body unread (an event stream). Aborting the
+     * call's signal later still ends the body.
+     */
+    stream(call: Call): Promise<Response>;
+    /**
+     * Makes `call` until it is answered with a 2xx, and reads the answer with
+     * `read`. Each attempt has `timeoutMs` until its answer's headers arrive,
+     * which counts the upload of a request body but not the reading of the
+     * answer's (an event stream's runs for minutes). A 401 calls
+     * `onUnauthorized` (once) and tries again with the credential as it is
+     * then. A transient failure is tried again, up to `maxRetries` times, when
+     * `call.retry` allows it; reading the body is part of the attempt, so a
+     * connection lost mid-body is retried too.
+     */
+    request<T>(call: Call, read: (response: Response) => Promise<T>, streaming?: boolean): Promise<T>;
+    /** What one attempt at `call` sends, `body` already encoded. */
+    private init;
+    private url;
+}
+/** `id` as a path segment. */
+export declare function segment(id: string): string;
+/** The wait before retry `retry` (0 for the first) when the server names none. */
+export declare function backoff(retry: number): number;
+/** Waits `ms`, or rejects with the signal's reason once it aborts. */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+export declare function isRecord(v: unknown): v is Record<string, unknown>;

package/dist/http.js

@@ -0,0 +1,284 @@
+// One request to the API, as every resource makes it: the credential, the
+// version header, a time limit on the answer, retries of what is safe to
+// retry, and the server's error body turned into a CloudSimError.
+import { CloudSimError, generalCode } from './errors.js';
+export const DEFAULT_BASE_URL = 'https://cloud.simantic.com';
+const DEFAULT_MAX_RETRIES = 3;
+// The CLI's and the dashboard's own limit: a submit can take a while, as the
+// server checks the credential upstream and its database may cold-start.
+const DEFAULT_TIMEOUT_MS = 60_000;
+// Backoff between retries when the server names no wait: 0.5 s doubling to
+// 8 s, each spread over its upper half so many clients do not retry in step.
+const FIRST_BACKOFF_MS = 500;
+const MAX_BACKOFF_MS = 8_000;
+// A Retry-After longer than this is not waited out: a call that would sit
+// for minutes is the caller's to decide on, so it fails with the error.
+const MAX_RETRY_AFTER_MS = 60_000;
+export class Transport {
+    version;
+    baseUrl;
+    /** How many times a transient failure is tried again. */
+    maxRetries;
+    apiKey;
+    fetch;
+    onUnauthorized;
+    timeoutMs;
+    onRetry;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.version = options.version;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        // Called as a plain function: a browser's fetch throws "Illegal
+        // invocation" when called as a method of anything but the window.
+        const f = options.fetch ?? globalThis.fetch;
+        this.fetch = (input, init) => f(input, init);
+        this.onUnauthorized = options.onUnauthorized;
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.onRetry = options.onRetry;
+    }
+    /** The answer as JSON. */
+    json(call) {
+        return this.request(call, async (response) => {
+            const text = await response.text();
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                throw new CloudSimError(`The Cloud Sim API sent a reply that is not JSON (HTTP ${response.status}).`, { status: response.status, code: 'invalid_response', requestId: requestId(response) });
+            }
+        });
+    }
+    /** The answer as text. */
+    text(call) {
+        const headers = { Accept: 'text/plain', ...call.headers };
+        return this.request({ ...call, headers }, (response) => response.text());
+    }
+    /**
+     * The answer itself, its body unread (an event stream). Aborting the
+     * call's signal later still ends the body.
+     */
+    stream(call) {
+        return this.request(call, async (response) => response, true);
+    }
+    /**
+     * Makes `call` until it is answered with a 2xx, and reads the answer with
+     * `read`. Each attempt has `timeoutMs` until its answer's headers arrive,
+     * which counts the upload of a request body but not the reading of the
+     * answer's (an event stream's runs for minutes). A 401 calls
+     * `onUnauthorized` (once) and tries again with the credential as it is
+     * then. A transient failure is tried again, up to `maxRetries` times, when
+     * `call.retry` allows it; reading the body is part of the attempt, so a
+     * connection lost mid-body is retried too.
+     */
+    async request(call, read, streaming = false) {
+        // Encoded once: a run's JSON can hold its whole ELF, and a retry sends
+        // it again. A FormData is sent as many times as asked.
+        const body = call.form ?? (call.json === undefined ? undefined : JSON.stringify(call.json));
+        const url = this.url(call.path, call.query);
+        let refreshed = false;
+        for (let retries = 0;; retries++) {
+            if (call.signal?.aborted)
+                throw call.signal.reason;
+            // Outside the try: a credential function that fails is the caller's
+            // failure, not the network's.
+            const init = await this.init(call, body);
+            const attempt = new Attempt(call.signal, call.timeoutMs ?? this.timeoutMs);
+            let response;
+            let failure;
+            let wait = null;
+            try {
+                response = await this.fetch(url, { ...init, signal: attempt.signal });
+                attempt.answered();
+                if (response.ok) {
+                    const value = await read(response);
+                    // A stream's body is read after this returns: the caller's
+                    // signal must still be able to end it.
+                    if (streaming)
+                        attempt.keep();
+                    return value;
+                }
+            }
+            catch (e) {
+                if (call.signal?.aborted)
+                    throw call.signal.reason;
+                if (attempt.timedOut) {
+                    failure = new CloudSimError(`The Cloud Sim API did not answer within ${Math.round(attempt.timeoutMs / 1000)} s.`, { status: 0, code: 'timeout' });
+                }
+                else if (e instanceof CloudSimError) {
+                    throw e;
+                }
+                else {
+                    // fetch rejects without an answer for every network-level failure,
+                    // a CORS refusal included, and does not say which.
+                    failure = new CloudSimError("Couldn't reach the Cloud Sim API.", {
+                        status: 0,
+                        code: 'network_error',
+                    });
+                }
+                response = undefined;
+            }
+            finally {
+                attempt.end();
+            }
+            if (response !== undefined) {
+                // Outside the try, as the credential is: what onUnauthorized
+                // throws is the caller's.
+                if (response.status === 401 && this.onUnauthorized && !refreshed) {
+                    refreshed = true;
+                    await response.body?.cancel().catch(() => { });
+                    await this.onUnauthorized();
+                    retries--;
+                    continue;
+                }
+                failure = await errorFrom(response);
+                wait = retryAfter(response);
+            }
+            if (failure === undefined)
+                throw new Error('unreachable: an attempt ended with no answer');
+            if (!call.retry || !failure.transient || retries >= this.maxRetries)
+                throw failure;
+            if (wait !== null && wait > MAX_RETRY_AFTER_MS)
+                throw failure;
+            const info = { attempt: retries + 1, error: failure, delayMs: wait ?? backoff(retries) };
+            this.onRetry?.(info);
+            call.onRetry?.(info);
+            await sleep(info.delayMs, call.signal);
+        }
+    }
+    /** What one attempt at `call` sends, `body` already encoded. */
+    async init(call, body) {
+        const headers = { Accept: 'application/json', ...call.headers };
+        const key = typeof this.apiKey === 'function' ? await this.apiKey() : this.apiKey;
+        // The catalogs need no credential, so a client made without one can
+        // still read them.
+        if (key)
+            headers['Authorization'] = `Bearer ${key}`;
+        const version = call.version ?? this.version;
+        if (version)
+            headers['Cloud-Sim-Version'] = version;
+        if (typeof body === 'string')
+            headers['Content-Type'] = 'application/json';
+        // No `cache: 'no-store'`: some edge runtimes refuse the option, and the
+        // API's answers carry no validators a browser could cache them by.
+        return { method: call.method, headers, body };
+    }
+    url(path, query) {
+        const params = new URLSearchParams();
+        for (const [name, value] of Object.entries(query ?? {})) {
+            if (value !== undefined)
+                params.set(name, String(value));
+        }
+        const search = params.toString();
+        return `${this.baseUrl}${path}${search ? `?${search}` : ''}`;
+    }
+}
+/**
+ * One attempt's signal: aborted by the caller's signal, or by the time limit
+ * on the answer's headers.
+ */
+class Attempt {
+    outer;
+    signal;
+    timeoutMs;
+    timedOut = false;
+    controller = new AbortController();
+    timer;
+    kept = false;
+    constructor(outer, timeoutMs) {
+        this.outer = outer;
+        this.signal = this.controller.signal;
+        this.timeoutMs = timeoutMs;
+        outer?.addEventListener('abort', this.onAbort, { once: true });
+        // 0 or Infinity: no limit.
+        if (timeoutMs > 0 && Number.isFinite(timeoutMs)) {
+            this.timer = setTimeout(() => {
+                this.timedOut = true;
+                this.controller.abort();
+            }, timeoutMs);
+        }
+    }
+    /** The headers arrived: the time limit is met. */
+    answered() {
+        clearTimeout(this.timer);
+    }
+    /** The body outlives the attempt: stay tied to the caller's signal. */
+    keep() {
+        this.kept = true;
+    }
+    end() {
+        clearTimeout(this.timer);
+        if (!this.kept)
+            this.outer?.removeEventListener('abort', this.onAbort);
+    }
+    onAbort = () => this.controller.abort(this.outer?.reason);
+}
+/** `id` as a path segment. */
+export function segment(id) {
+    return encodeURIComponent(id);
+}
+function requestId(response) {
+    return response.headers.get('X-Request-Id');
+}
+/** The error a non-2xx answer stands for, from its body when it has one. */
+async function errorFrom(response) {
+    const status = response.status;
+    let body;
+    try {
+        body = JSON.parse(await response.text());
+    }
+    catch {
+        body = undefined;
+    }
+    if (isRecord(body) && typeof body.error === 'string') {
+        return new CloudSimError(body.error, {
+            status,
+            code: typeof body.code === 'string' ? body.code : generalCode(status),
+            param: typeof body.param === 'string' ? body.param : null,
+            requestId: typeof body.request_id === 'string' ? body.request_id : requestId(response),
+        });
+    }
+    // Not the server's own answer: InstaCloud's Cloudflare edge swaps a 502
+    // or 504 for an HTML page of its own.
+    return new CloudSimError(`The Cloud Sim API answered HTTP ${status}.`, {
+        status,
+        code: generalCode(status),
+        requestId: requestId(response),
+    });
+}
+/** `Retry-After` in milliseconds: delta-seconds or an HTTP date. */
+function retryAfter(response) {
+    const value = response.headers.get('Retry-After')?.trim();
+    if (!value)
+        return null;
+    if (/^\d+$/.test(value))
+        return Number(value) * 1000;
+    const at = Date.parse(value);
+    return Number.isNaN(at) ? null : Math.max(0, at - Date.now());
+}
+/** The wait before retry `retry` (0 for the first) when the server names none. */
+export function backoff(retry) {
+    const ceiling = Math.min(MAX_BACKOFF_MS, FIRST_BACKOFF_MS * 2 ** retry);
+    return ceiling / 2 + (Math.random() * ceiling) / 2;
+}
+/** Waits `ms`, or rejects with the signal's reason once it aborts. */
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+export function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { CloudSim, type CloudSimOptions } from './client.js';
+export { CloudSimError, type CloudSimErrorInit, CompareError, isTransient, } from './errors.js';
+export type { ApiKey, RetryInfo } from './http.js';
+export { type FollowEvent, type FollowOptions, type FollowTransport, type Offsets, type StreamName, POLL_INTERVAL_MS, } from './follow.js';
+export type { CallOptions, Comparison, CompareParams, CreateOptions, CreateRunParams, FirmwareInput, ListRunsParams, RunListing, RunOptionsInput, Runs, WaitOptions, } from './runs.js';
+export type { McuFilter, McuListOptions, Mcus, Versions } from './catalog.js';
+export { type Difference, type ResultComparison, compareResults } from './compare.js';
+export { type Changes, type Engine, type EngineOption, type ErrorBody, type Firmware, type Lifecycle, type Live, type LiveStream, type Mcu, type McuEngine, type McuList, type Run, type RunEngine, type RunList, type RunOptions, type RunResult, type RunStatus, type UartEncoding, type Version, type VersionList, FINISHED, isFinished, } from './types.js';
+export type { components, operations, paths } from './generated/v1.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+// @simantic/cloud-sim: a client of the Cloud Sim API (openapi/v1.json in
+// the cloud-sim repo), on fetch, with no dependencies. It runs wherever
+// fetch does: Node 18 and later, browsers, Deno, Bun, edge runtimes.
+// Anything that needs Node lives in '@simantic/cloud-sim/node'.
+export { CloudSim } from './client.js';
+export { CloudSimError, CompareError, isTransient, } from './errors.js';
+export { POLL_INTERVAL_MS, } from './follow.js';
+export { compareResults } from './compare.js';
+export { FINISHED, isFinished, } from './types.js';

package/dist/node.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The file at `path` as a Blob, ready to be a run's firmware: it is sent as
+ * a multipart upload.
+ */
+export declare function fromPath(path: string): Promise<Blob>;

package/dist/node.js

@@ -0,0 +1,10 @@
+// '@simantic/cloud-sim/node': helpers that need Node, kept out of the main
+// entry so it stays free of `node:` imports for browsers and edge runtimes.
+import { readFile } from 'node:fs/promises';
+/**
+ * The file at `path` as a Blob, ready to be a run's firmware: it is sent as
+ * a multipart upload.
+ */
+export async function fromPath(path) {
+    return new Blob([await readFile(path)]);
+}

package/dist/runs.d.ts

@@ -0,0 +1,152 @@
+import { type FollowEvent, type FollowOptions } from './follow.js';
+import { type Transport } from './http.js';
+import { type Run, type RunList, type RunResult, type UartEncoding, type Version } from './types.js';
+/**
+ * A run's firmware: the ELF's bytes (sent as a multipart upload), an https
+ * URL the server fetches it from, or the ELF already base64-encoded (sent
+ * in JSON).
+ */
+export type FirmwareInput = Blob | Uint8Array | ArrayBuffer | {
+    url: string;
+} | {
+    base64: string;
+};
+/** What every call takes. */
+export interface CallOptions {
+    /** Ends the call, its retries and its waits between them, with the signal's reason. */
+    signal?: AbortSignal;
+}
+/** The engine-neutral run options. Each left out takes the engine's default. */
+export interface RunOptionsInput {
+    /** Simulated seconds to run for: more than 0, at most 60. Default 10. */
+    simulatedSeconds?: number;
+    /** `hex` rows (the default) or `ascii` text. */
+    uartEncoding?: UartEncoding;
+    /** Each UART record without its timestamp and label. Default false. */
+    uartMessagesOnly?: boolean;
+    /** A bus access that reaches no device is a bus error, not a read of 0. */
+    trapUnmapped?: boolean;
+    /** USB device peripherals (such as `USB`) to put a CDC-ACM console behind. */
+    usbCdcConsoles?: string[];
+}
+/** What a create takes beyond the run itself. */
+export interface CreateOptions extends CallOptions {
+    /** The API version for this run, in place of the client's. */
+    version?: string;
+    /**
+     * The time limit until the server answers, in place of the client's
+     * `timeoutMs`. It counts the upload, so give a large firmware more.
+     */
+    timeoutMs?: number;
+}
+export interface CreateRunParams extends RunOptionsInput, CreateOptions {
+    /** The MCU, by its canonical name (`client.mcus.list()`). */
+    mcu: string;
+    /** The engine; the version's default engine when left out. */
+    engine?: string;
+    firmware: FirmwareInput;
+    /**
+     * Makes the create safe to repeat: the same request again with the same
+     * key gets the run it made. One is generated when left out, so the SDK's
+     * own retries never make a second run.
+     */
+    idempotencyKey?: string;
+}
+export interface ListRunsParams extends CallOptions {
+    /** Runs per page, 1 to 100 (the server's default is 20). */
+    limit?: number;
+    /** Start after this run (a page's `next`). */
+    before?: string;
+    /** Only runs on this engine. */
+    engine?: string;
+}
+export interface WaitOptions extends CallOptions {
+    /** How long to wait between reads of the run. Default 1000. */
+    intervalMs?: number;
+}
+export interface CompareParams extends RunOptionsInput, CreateOptions {
+    /** The engines to run the firmware on, one run each. */
+    engines: string[];
+    mcu: string;
+    firmware: FirmwareInput;
+}
+export interface Comparison {
+    /** The version every run was made on. */
+    version: Version;
+    /** One run per engine, in the order the engines were given. */
+    runs: Run[];
+}
+export declare class Runs {
+    private readonly http;
+    constructor(http: Transport);
+    /**
+     * Makes a run. Answers with the run whether it was made now (201) or by an
+     * earlier request with the same idempotency key (200).
+     */
+    create(params: CreateRunParams): Promise<Run>;
+    /** The run. */
+    get(id: string, options?: CallOptions): Promise<Run>;
+    /**
+     * The caller's runs, newest first. Awaited, it is the first page
+     * (`{ runs, next }`); iterated with `for await`, it is every run, a page at
+     * a time.
+     */
+    list(params?: ListRunsParams): RunListing;
+    /** What a finished run produced. A run that has not finished is 409 `run_not_finished`. */
+    result(id: string, options?: CallOptions): Promise<RunResult>;
+    /** A finished run's UART output, as text. */
+    output(id: string, options?: CallOptions): Promise<string>;
+    /** A finished run's console, as text. */
+    log(id: string, options?: CallOptions): Promise<string>;
+    /**
+     * Cancels a run: a queued one at once, a running one within seconds. A run
+     * that already succeeded or failed is 409 `run_finished`. Retried like a
+     * read: the server answers a repeated cancel with the run as it is, and a
+     * run that finished meanwhile gets the 409, which is not retried.
+     */
+    cancel(id: string, options?: CallOptions): Promise<Run>;
+    /** The run once it has finished: succeeded, failed or canceled. */
+    wait(id: string, options?: WaitOptions): Promise<Run>;
+    /**
+     * The run as events, from wherever it is (or from `from`) to its end:
+     * `status` when its status changes, `log` and `output` text as it prints,
+     * `reset` when a stream starts over, `reconnecting` while a failure is
+     * being retried, and `end`. See `FollowEvent`.
+     */
+    follow(id: string, options?: FollowOptions): AsyncGenerator<FollowEvent, void, undefined>;
+    /**
+     * Runs the same firmware, MCU and options once on each engine, in
+     * parallel, and answers with the runs. It reads the version first (the
+     * call's, the client's, or the server's default), and an engine the
+     * version does not have fails the whole comparison
+     * (`engine_not_in_version`) before anything is uploaded. Every run is made
+     * on that version, whatever the server's default becomes meanwhile. Each
+     * run counts against the caller's limit of unfinished runs.
+     *
+     * The engines are checked before anything is asked of the server: none,
+     * or one named twice, is 400 `invalid_request` (`param: 'engines'`).
+     *
+     * Every engine's run is asked for even when another is refused. When
+     * some runs are made and others are not, it fails with a `CompareError`
+     * that carries the runs made, by engine, to follow or cancel.
+     */
+    compare(params: CompareParams): Promise<Comparison>;
+    private make;
+    /** Version `asked`, else the client's, else the server's default. */
+    private readVersion;
+}
+/**
+ * The caller's runs: a promise of the first page, and an async iterable of
+ * every run. Nothing is read until it is awaited or iterated.
+ */
+export declare class RunListing implements PromiseLike<RunList>, AsyncIterable<Run> {
+    private readonly http;
+    private readonly params;
+    private first;
+    constructor(http: Transport, params: ListRunsParams);
+    /** The first page. */
+    firstPage(): Promise<RunList>;
+    then<A = RunList, B = never>(onFulfilled?: ((page: RunList) => A | PromiseLike<A>) | null, onRejected?: ((reason: unknown) => B | PromiseLike<B>) | null): Promise<A | B>;
+    [Symbol.asyncIterator](): AsyncGenerator<Run, void, undefined>;
+    private page;
+}