@simantic/cloud-sim 0.1.0

package/dist/runs.js

@@ -0,0 +1,284 @@
+// `client.runs`: make runs, read them, follow them, and compare engines.
+import { CloudSimError, CompareError } from './errors.js';
+import { follow } from './follow.js';
+import { segment, sleep } from './http.js';
+import { isFinished, } from './types.js';
+const WAIT_INTERVAL_MS = 1_000;
+export class Runs {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Makes a run. Answers with the run whether it was made now (201) or by an
+     * earlier request with the same idempotency key (200).
+     */
+    async create(params) {
+        return this.make(params, firmwareBody(params.firmware));
+    }
+    /** The run. */
+    get(id, options = {}) {
+        return this.http.json({
+            method: 'GET',
+            path: `/v1/runs/${segment(id)}`,
+            signal: options.signal,
+            retry: true,
+        });
+    }
+    /**
+     * 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 = {}) {
+        return new RunListing(this.http, params);
+    }
+    /** What a finished run produced. A run that has not finished is 409 `run_not_finished`. */
+    result(id, options = {}) {
+        return this.http.json({
+            method: 'GET',
+            path: `/v1/runs/${segment(id)}/result`,
+            signal: options.signal,
+            retry: true,
+        });
+    }
+    /** A finished run's UART output, as text. */
+    output(id, options = {}) {
+        return this.http.text({
+            method: 'GET',
+            path: `/v1/runs/${segment(id)}/output`,
+            signal: options.signal,
+            retry: true,
+        });
+    }
+    /** A finished run's console, as text. */
+    log(id, options = {}) {
+        return this.http.text({
+            method: 'GET',
+            path: `/v1/runs/${segment(id)}/log`,
+            signal: options.signal,
+            retry: true,
+        });
+    }
+    /**
+     * 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, options = {}) {
+        return this.http.json({
+            method: 'POST',
+            path: `/v1/runs/${segment(id)}/cancel`,
+            signal: options.signal,
+            retry: true,
+        });
+    }
+    /** The run once it has finished: succeeded, failed or canceled. */
+    async wait(id, options = {}) {
+        const { signal, intervalMs = WAIT_INTERVAL_MS } = options;
+        for (;;) {
+            const run = await this.get(id, { signal });
+            if (isFinished(run))
+                return run;
+            await sleep(intervalMs, signal);
+        }
+    }
+    /**
+     * 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, options = {}) {
+        return follow(this.http, id, options);
+    }
+    /**
+     * 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.
+     */
+    async compare(params) {
+        const { engines, firmware, signal, version: asked, ...options } = params;
+        checkEngines(engines);
+        // Encoded once, sent once per engine.
+        const body = firmwareBody(firmware);
+        const version = await this.readVersion(asked, signal);
+        const have = version.engines.map((e) => e.name);
+        const missing = engines.filter((e) => !have.includes(e));
+        if (missing.length > 0) {
+            throw new CloudSimError(`API version ${version.id} has no ${missing.join(' or ')} engine: it has ${have.join(', ')}`, { status: 400, code: 'engine_not_in_version', param: 'engines' });
+        }
+        const made = await Promise.allSettled(engines.map((engine) => this.make({ ...options, engine, signal, version: version.id }, body)));
+        if (signal?.aborted)
+            throw signal.reason;
+        const runs = {};
+        const errors = {};
+        made.forEach((m, i) => {
+            const engine = engines[i];
+            if (m.status === 'fulfilled')
+                runs[engine] = m.value;
+            else
+                errors[engine] = m.reason;
+        });
+        if (Object.keys(errors).length > 0)
+            throw new CompareError(version, runs, errors);
+        return { version, runs: Object.values(runs) };
+    }
+    make(params, firmware) {
+        const key = params.idempotencyKey ?? newIdempotencyKey();
+        const fields = optionFields(params);
+        const call = {
+            method: 'POST',
+            path: '/v1/runs',
+            headers: { 'Idempotency-Key': key },
+            version: params.version,
+            signal: params.signal,
+            timeoutMs: params.timeoutMs,
+            retry: true,
+        };
+        if (firmware.kind === 'json') {
+            return this.http.json({ ...call, json: { ...fields, firmware: firmware.json } });
+        }
+        const form = new FormData();
+        for (const [name, value] of Object.entries(fields)) {
+            for (const one of Array.isArray(value) ? value : [value])
+                form.append(name, String(one));
+        }
+        form.append('firmware', firmware.blob, firmware.name);
+        return this.http.json({ ...call, form });
+    }
+    /** Version `asked`, else the client's, else the server's default. */
+    async readVersion(asked, signal) {
+        const id = asked ?? this.http.version;
+        if (id) {
+            return this.http.json({
+                method: 'GET',
+                path: `/v1/versions/${segment(id)}`,
+                signal,
+                retry: true,
+            });
+        }
+        const list = await this.http.json({
+            method: 'GET',
+            path: '/v1/versions',
+            signal,
+            retry: true,
+        });
+        const version = list.versions.find((v) => v.id === list.default);
+        if (!version) {
+            throw new CloudSimError(`The Cloud Sim API lists no default version ${list.default}.`, {
+                status: 200,
+                code: 'invalid_response',
+            });
+        }
+        return version;
+    }
+}
+/**
+ * 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 class RunListing {
+    http;
+    params;
+    first;
+    constructor(http, params) {
+        this.http = http;
+        this.params = params;
+    }
+    /** The first page. */
+    firstPage() {
+        this.first ??= this.page(this.params.before);
+        return this.first;
+    }
+    then(onFulfilled, onRejected) {
+        return this.firstPage().then(onFulfilled, onRejected);
+    }
+    async *[Symbol.asyncIterator]() {
+        let page = await this.firstPage();
+        for (;;) {
+            yield* page.runs;
+            if (!page.next)
+                return;
+            page = await this.page(page.next);
+        }
+    }
+    page(before) {
+        return this.http.json({
+            method: 'GET',
+            path: '/v1/runs',
+            query: { limit: this.params.limit, before, engine: this.params.engine },
+            signal: this.params.signal,
+            retry: true,
+        });
+    }
+}
+/** Refuses a comparison of no engines, or of one engine twice, as the Python SDK does. */
+function checkEngines(engines) {
+    const refuse = (message) => new CloudSimError(message, { status: 400, code: 'invalid_request', param: 'engines' });
+    if (!Array.isArray(engines) || engines.length === 0) {
+        throw refuse('compare needs at least one engine');
+    }
+    if (new Set(engines).size !== engines.length) {
+        throw refuse(`each engine may be named once: ${engines.join(', ')}`);
+    }
+}
+function firmwareBody(firmware) {
+    if (typeof Blob !== 'undefined' && firmware instanceof Blob) {
+        const name = 'name' in firmware && typeof firmware.name === 'string' ? firmware.name : '';
+        return { kind: 'form', blob: firmware, name: name || 'firmware.elf' };
+    }
+    if (firmware instanceof Uint8Array || firmware instanceof ArrayBuffer) {
+        return { kind: 'form', blob: new Blob([firmware]), name: 'firmware.elf' };
+    }
+    if (typeof firmware === 'object' && firmware !== null) {
+        if ('url' in firmware && typeof firmware.url === 'string') {
+            return { kind: 'json', json: { url: firmware.url } };
+        }
+        if ('base64' in firmware && typeof firmware.base64 === 'string') {
+            return { kind: 'json', json: { base64: firmware.base64 } };
+        }
+    }
+    throw new TypeError('firmware must be a Blob, a Uint8Array, an ArrayBuffer, { url } or { base64 }');
+}
+/** The run's fields other than its firmware, as the API names them. */
+function optionFields(params) {
+    const fields = {
+        mcu: params.mcu,
+        engine: params.engine,
+        simulated_seconds: params.simulatedSeconds,
+        uart_encoding: params.uartEncoding,
+        uart_messages_only: params.uartMessagesOnly,
+        trap_unmapped: params.trapUnmapped,
+        usb_cdc_consoles: params.usbCdcConsoles,
+    };
+    const set = {};
+    for (const [name, value] of Object.entries(fields))
+        if (value !== undefined)
+            set[name] = value;
+    return set;
+}
+/** A new Idempotency-Key. */
+function newIdempotencyKey() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    // Node 18 has no global Web Crypto unless started with
+    // --experimental-global-webcrypto. The key only has to be unique among
+    // the caller's runs, which 122 random bits are, from any generator.
+    const hex = (n) => Array.from({ length: n }, () => Math.floor(Math.random() * 16).toString(16)).join('');
+    const variant = '89ab'[Math.floor(Math.random() * 4)];
+    return `${hex(8)}-${hex(4)}-4${hex(3)}-${variant}${hex(3)}-${hex(12)}`;
+}

package/dist/sse.d.ts

@@ -0,0 +1,30 @@
+export interface SseEvent {
+    /** The event's name; `message` when it named none. */
+    event: string;
+    data: string;
+    /** The last event id the stream set, at or before this event. */
+    id: string | undefined;
+}
+/** Turns text, fed in pieces as it arrives, into events. */
+export declare class SseParser {
+    private buffer;
+    private data;
+    private event;
+    /**
+     * The id of the last event dispatched: what a reconnect resumes from. An
+     * `id` line takes effect when its event is complete, so an event cut off
+     * by a dropped connection is asked for again.
+     */
+    lastId: string | undefined;
+    private idBuffer;
+    /** The reconnection delay the server last asked for, in milliseconds. */
+    retry: number | undefined;
+    private pendingCr;
+    constructor(lastId?: string);
+    /** The events completed by `text`. */
+    push(text: string): SseEvent[];
+    private line;
+    private dispatch;
+}
+/** The events of a response's body, as they arrive. */
+export declare function readEvents(body: ReadableStream<Uint8Array>, parser: SseParser): AsyncGenerator<SseEvent>;

package/dist/sse.js

@@ -0,0 +1,109 @@
+// A server-sent event stream, parsed from fetch's body. EventSource would
+// do this, but it cannot send Authorization, so the SDK reads the stream
+// itself (the WHATWG HTML "event stream interpretation", less what the API
+// never sends).
+/** Turns text, fed in pieces as it arrives, into events. */
+export class SseParser {
+    buffer = '';
+    data = [];
+    event = '';
+    /**
+     * The id of the last event dispatched: what a reconnect resumes from. An
+     * `id` line takes effect when its event is complete, so an event cut off
+     * by a dropped connection is asked for again.
+     */
+    lastId;
+    idBuffer;
+    /** The reconnection delay the server last asked for, in milliseconds. */
+    retry;
+    // A `\r` that ended the last piece: if the next starts with `\n`, the
+    // two are one line break.
+    pendingCr = false;
+    constructor(lastId) {
+        this.lastId = lastId;
+        this.idBuffer = lastId;
+    }
+    /** The events completed by `text`. */
+    push(text) {
+        if (this.pendingCr && text.startsWith('\n'))
+            text = text.slice(1);
+        this.pendingCr = false;
+        this.buffer += text;
+        const events = [];
+        for (;;) {
+            const at = this.buffer.search(/[\r\n]/);
+            if (at < 0)
+                break;
+            const line = this.buffer.slice(0, at);
+            let skip = 1;
+            if (this.buffer[at] === '\r') {
+                if (at + 1 === this.buffer.length)
+                    this.pendingCr = true;
+                else if (this.buffer[at + 1] === '\n')
+                    skip = 2;
+            }
+            this.buffer = this.buffer.slice(at + skip);
+            const event = this.line(line);
+            if (event)
+                events.push(event);
+        }
+        return events;
+    }
+    line(line) {
+        if (line === '')
+            return this.dispatch();
+        if (line.startsWith(':'))
+            return undefined;
+        const colon = line.indexOf(':');
+        const field = colon < 0 ? line : line.slice(0, colon);
+        let value = colon < 0 ? '' : line.slice(colon + 1);
+        if (value.startsWith(' '))
+            value = value.slice(1);
+        switch (field) {
+            case 'event':
+                this.event = value;
+                break;
+            case 'data':
+                this.data.push(value);
+                break;
+            case 'id':
+                if (!value.includes('\0'))
+                    this.idBuffer = value;
+                break;
+            case 'retry':
+                if (/^\d+$/.test(value))
+                    this.retry = Number(value);
+                break;
+        }
+        return undefined;
+    }
+    dispatch() {
+        const data = this.data;
+        const event = this.event || 'message';
+        this.data = [];
+        this.event = '';
+        this.lastId = this.idBuffer;
+        // A block without data dispatches nothing (but its id stands).
+        if (data.length === 0)
+            return undefined;
+        return { event, data: data.join('\n'), id: this.lastId };
+    }
+}
+/** The events of a response's body, as they arrive. */
+export async function* readEvents(body, parser) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            yield* parser.push(decoder.decode(value, { stream: true }));
+        }
+        yield* parser.push(decoder.decode());
+    }
+    finally {
+        // The consumer stopped early, or the read failed: let the connection go.
+        reader.cancel().catch(() => { });
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+import type { components } from './generated/v1.js';
+type Schemas = components['schemas'];
+/** A simulation run. */
+export type Run = Schemas['Run'];
+/** Where a run is. `succeeded`, `failed` and `canceled` are final. */
+export type RunStatus = Schemas['RunStatus'];
+/** The engine a run is bound to. */
+export type RunEngine = Schemas['RunEngine'];
+/** A run's options as the server recorded them, every default filled in. */
+export type RunOptions = Schemas['RunOptions'];
+/** What a finished run produced: its exit code, UART output and console. */
+export type RunResult = Schemas['RunResult'];
+/** A page of the caller's runs, newest first. */
+export type RunList = Schemas['RunList'];
+/** The firmware a run simulates, as the server received it. */
+export type Firmware = Schemas['Firmware'];
+/** A run and a page of each of its streams (`GET /v1/runs/{id}/live`). */
+export type Live = Schemas['Live'];
+/** A page of one stream. */
+export type LiveStream = Schemas['LiveStream'];
+/** How UART bytes are written: hex rows or text. */
+export type UartEncoding = Schemas['UartEncoding'];
+/** Where a version is in its life. */
+export type Lifecycle = Schemas['Lifecycle'];
+/** A version's MCU catalog. */
+export type McuList = Schemas['McuList'];
+/** One MCU, and what each of the version's engines makes of it. */
+export type Mcu = Schemas['McuView'];
+/** One engine's view of an MCU. */
+export type McuEngine = Schemas['McuEngineView'];
+/** What a version changed against the one before it. */
+export type Changes = Schemas['Changes'];
+/** The body of every error the server answers with. */
+export type ErrorBody = Schemas['Error'];
+/** One run option an engine takes, with its default and bounds. */
+export type EngineOption = Schemas['OptionView'];
+/** An engine as a version pins it. */
+export type Engine = Schemas['EngineView'];
+/** One API version: its lifecycle and the engines it binds. */
+export type Version = Schemas['VersionView'];
+/** Every version the server serves. */
+export type VersionList = Schemas['VersionList'];
+/** The statuses a run ends in. */
+export declare const FINISHED: readonly RunStatus[];
+/** Whether a run has ended (succeeded, failed or was canceled). */
+export declare function isFinished(run: Pick<Run, 'status'>): boolean;
+export {};

package/dist/types.js

@@ -0,0 +1,11 @@
+// The wire types this SDK hands back, named for use. They come from
+// src/generated/v1.ts, which `npm run generate` writes from the server's
+// openapi/v1.json, so they change only when the contract does. Readers
+// ignore fields they do not know: the server adds fields within a major
+// version, and never removes or changes one.
+/** The statuses a run ends in. */
+export const FINISHED = ['succeeded', 'failed', 'canceled'];
+/** Whether a run has ended (succeeded, failed or was canceled). */
+export function isFinished(run) {
+    return FINISHED.includes(run.status);
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@simantic/cloud-sim",
+  "version": "0.1.0",
+  "description": "TypeScript client for the Cloud Sim API: run MCU firmware in the cloud, follow its output live, and compare simulation engines.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/simantic-dev/cloud-sim.git",
+    "directory": "sdk/typescript"
+  },
+  "homepage": "https://github.com/simantic-dev/cloud-sim/tree/main/sdk/typescript#readme",
+  "keywords": [
+    "simantic",
+    "cloud-sim",
+    "firmware",
+    "simulator",
+    "mcu"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "generate": "openapi-typescript ../../openapi/v1.json -o src/generated/v1.ts",
+    "check:generated": "node scripts/check-generated.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "openapi-typescript": "^7.13.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  }
+}