@simantic/cloud-sim 0.1.0

package/README.md

@@ -0,0 +1,298 @@
+# @simantic/cloud-sim
+
+TypeScript client for the Cloud Sim API, which simulates MCU firmware in
+the cloud. A run takes an ELF, an MCU and engine-neutral options, runs on
+one of the API version's simulation engines (quartz by default), and hands
+back the UART output and the engine's console, live as it runs and in full
+after.
+
+The package is ESM with no dependencies, built on `fetch`, so it runs on
+Node 18 and later, in browsers, and on Deno, Bun and edge runtimes. Its
+wire types are generated from the server's OpenAPI document
+(`openapi/v1.json` in the cloud-sim repo), so they change only when the
+contract does.
+
+## Install
+
+```sh
+npm install @simantic/cloud-sim
+```
+
+The package is private to the `simantic` npm organization for now: installing
+it needs an npm token of an org member (`npm login`, or `NPM_TOKEN` on CI and
+Vercel, which writes the `.npmrc` itself). The API it calls is open to any
+simantic account; its contract is at https://cloud.simantic.com/v1/openapi.json.
+
+## Quick start
+
+### Node
+
+```ts
+import { CloudSim } from '@simantic/cloud-sim'
+import { fromPath } from '@simantic/cloud-sim/node'
+
+const sim = new CloudSim({ apiKey: process.env.CLOUD_SIM_API_KEY!, version: '1.0' })
+
+const run = await sim.runs.create({
+  mcu: 'STM32F072RB',
+  firmware: await fromPath('build/firmware.elf'),
+  simulatedSeconds: 5,
+  uartEncoding: 'ascii',
+})
+const done = await sim.runs.wait(run.id)
+console.log(done.status, done.exit_code)
+console.log(await sim.runs.output(run.id))
+```
+
+`@simantic/cloud-sim/node` holds what needs Node (`fromPath` reads a file
+into a Blob); the main entry needs nothing beyond `fetch`.
+
+### Browser
+
+```ts
+import { CloudSim } from '@simantic/cloud-sim'
+
+const sim = new CloudSim({
+  // Called before every request, so a refreshed token is picked up.
+  apiKey: async () => (await supabase.auth.getSession()).data.session?.access_token ?? '',
+  // A 401 calls this once, and the request is sent again.
+  onUnauthorized: async () => {
+    await supabase.auth.refreshSession()
+  },
+})
+
+const input = document.querySelector<HTMLInputElement>('input[type=file]')!
+const run = await sim.runs.create({ mcu: 'STM32F072RB', firmware: input.files![0]! })
+```
+
+### The client
+
+```ts
+new CloudSim({
+  apiKey,          // an smtc_ API key or a dashboard session token, or a function giving one
+  version,         // Cloud-Sim-Version, such as '1.0'; the server's newest stable without it
+  baseUrl,         // default https://cloud.simantic.com
+  fetch,           // default the global fetch
+  onUnauthorized,  // called once on a 401, before the request is sent again
+  maxRetries,      // default 3
+  timeoutMs,       // how long each request has until its answer's headers arrive; default 60000
+  onRetry,         // ({ attempt, error, delayMs }) => void, told before each retry
+})
+```
+
+Pin `version` in anything long-lived: a version pins each engine to one
+release, so results do not change under you when the server's default
+moves on. A call that makes runs or reads a catalog can name another
+version for itself (`version`), so one client can serve a version picker.
+
+Every call takes an optional `signal`. Aborting it ends the call, its
+retries and the waits between them, and the call throws the signal's
+reason.
+
+## Runs
+
+```ts
+sim.runs.create({ mcu, engine?, firmware, simulatedSeconds?, uartEncoding?, uartMessagesOnly?,
+                  trapUnmapped?, usbCdcConsoles?, idempotencyKey?, version?, timeoutMs?, signal? })
+sim.runs.get(id, { signal? })
+sim.runs.list({ limit?, before?, engine?, signal? })
+sim.runs.result(id, { signal? })   // { exit_code, output, log, truncated } of a finished run
+sim.runs.output(id, { signal? })   // the UART output, as text
+sim.runs.log(id, { signal? })      // the engine's console, as text
+sim.runs.cancel(id, { signal? })
+sim.runs.wait(id, { signal?, intervalMs? })
+sim.runs.follow(id, { signal?, transport?, intervalMs?, from? })
+sim.runs.compare({ engines, mcu, firmware, ...options, version?, timeoutMs?, signal? })
+```
+
+`firmware` is a `Blob` (a `File` included), a `Uint8Array`, an
+`ArrayBuffer`, `{ url }` or `{ base64 }`. Bytes are uploaded as
+multipart/form-data; a URL is fetched by the server (https only, at most
+24 MiB); base64 goes in JSON.
+
+Every create carries an `Idempotency-Key`, generated when you give none, so
+a create the SDK retries after a lost answer gets the run it already made
+rather than a second one. To make a create safe across restarts of your
+own program, pass your own key.
+
+The client's `timeoutMs` counts the upload, since the server answers only
+once it has the body. Give a create with a large firmware more:
+
+```ts
+// A minute, and the upload at 1 Mbit/s (125 bytes a millisecond).
+const timeoutMs = 60_000 + Math.ceil(file.size / 125)
+await sim.runs.create({ mcu, firmware: file, timeoutMs })
+```
+
+`runs.list()` reads nothing until used. Awaited, it is the first page;
+iterated, it is every run, newest first:
+
+```ts
+const { runs, next } = await sim.runs.list({ limit: 10 })
+for await (const run of sim.runs.list({ engine: 'quartz' })) console.log(run.id, run.status)
+```
+
+## Following a run
+
+`runs.follow` turns a run into events, from wherever it is to its end:
+
+```ts
+let output = ''
+const from = { log: 0, output: 0 }
+for await (const event of sim.runs.follow(run.id, { signal })) {
+  switch (event.type) {
+    case 'status': console.log('now', event.run.status); break
+    case 'output': output += event.text; from.output = event.next; break
+    case 'log': process.stderr.write(event.text); from.log = event.next; break
+    case 'reset': if (event.stream === 'output') output = ''; break
+    case 'reconnecting': console.log('reconnecting:', event.error.message); break
+    case 'end': console.log('exit code', event.run.exit_code); break
+  }
+}
+```
+
+The `log` and `output` texts concatenate to the run's whole console and
+UART output. A `reset` is rare: it says the run's final result differs from
+what it shipped while it ran, so that stream starts over and what you kept
+of it is to be dropped. Aborting `signal` ends the loop with the signal's
+reason; `break` ends it quietly, and stops whatever request or retry it had
+under way.
+
+Each `log` and `output` event's `next` is where that stream has been read
+to. A follow that stopped (the page was left, the retries ran out) picks up
+there with `from`, and passes on only what is new:
+
+```ts
+for await (const event of sim.runs.follow(run.id, { from })) { … }
+```
+
+While a failure is being retried (a lost connection, a 503, the server's
+`error` event), `follow` says so with a `reconnecting` event, once per
+retry. Once it has recovered, the next event is a `status`, even if the
+run's status is the same, so a UI can show "Reconnecting…" between the two.
+When the retries run out, the loop throws the last failure.
+
+`transport` picks how:
+
+- `auto` (the default) reads the server-sent event stream, and falls back
+  to polling when that request fails before its first event (a server
+  without the route, something in between that will not pass an event
+  stream, a network failure);
+- `sse` reads `GET /v1/runs/{id}/events`, parsed from `fetch` because
+  `EventSource` cannot send `Authorization`. The server closes each stream
+  after at most 10 minutes; the SDK reconnects with `Last-Event-ID` and
+  picks up after the last whole event. When the server cannot read the run
+  (a store outage) it sends an `error` event and closes; the SDK waits as
+  that event asks (5 s) and reconnects, and fails with the event's
+  `CloudSimError` only after `maxRetries` of them with nothing new between;
+- `poll` pages `GET /v1/runs/{id}/live`, every `intervalMs` (750 ms) while
+  nothing is waiting and at once while more is.
+
+## Comparing engines
+
+```ts
+import { CompareError, compareResults } from '@simantic/cloud-sim'
+
+const { version, runs } = await sim.runs.compare({
+  engines: ['quartz', 'pyrite'],
+  mcu: 'STM32F072RB',
+  firmware: await fromPath('firmware.elf'),
+  simulatedSeconds: 5,
+})
+const [a, b] = await Promise.all(runs.map((r) => sim.runs.wait(r.id)))
+const diff = compareResults(await sim.runs.result(a!.id), await sim.runs.result(b!.id))
+// { exitCodes: [0, 0], sameExitCode: true, outputIdentical: false,
+//   firstDifference: { line: 12, a: '…', b: '…' } }
+```
+
+`compare` refuses no engines, or an engine named twice, before asking
+anything (400 `invalid_request`, `param: 'engines'`). It reads the version
+first (its own `version`, the client's, or the server's default) and fails
+with `engine_not_in_version` before uploading anything if an engine is
+missing from it. It then asks for one run per engine in parallel, each with
+its own idempotency key, all pinned to that version. Each run counts
+against your limit of unfinished runs.
+
+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`, a
+`CloudSimError` whose status, code, param and request id are the first
+failure's, and which is `transient` only if every failure is. Its `version`
+is the version the comparison used, its `runs` the runs made, by engine,
+which go on on the server, and its `errors` why each other engine's run was
+not, by engine. The Python SDK's `CompareError` has the same fields:
+
+```ts
+try {
+  await sim.runs.compare({ engines, mcu, firmware })
+} catch (e) {
+  if (e instanceof CompareError) {
+    for (const run of Object.values(e.runs)) await sim.runs.cancel(run.id)   // or follow them
+    for (const [engine, error] of Object.entries(e.errors)) console.log(engine, error)
+  }
+}
+```
+
+## Versions and MCUs
+
+```ts
+await sim.versions.list()                      // every version, and which is the default
+await sim.versions.get('1.0')                  // engines, releases, options, limits, changes
+await sim.versions.mcus('1.0', { engine: 'quartz', runnable: true })
+await sim.mcus.list({ runnable: true })        // the client's version
+await sim.mcus.list({ version: '1.1-preview.1' })
+```
+
+These need no credential; a client made with `apiKey: ''` can read them.
+
+## Errors
+
+Every failure is a `CloudSimError`, except an aborted `signal`, which
+throws the signal's reason:
+
+```ts
+import { CloudSimError, isTransient } from '@simantic/cloud-sim'
+
+try {
+  await sim.runs.create({ mcu: 'NOPE', firmware })
+} catch (e) {
+  if (e instanceof CloudSimError) {
+    e.status     // the HTTP status, or 0 when no answer arrived
+    e.code       // stable, such as 'mcu_not_supported', 'network_error', 'timeout'
+    e.param      // the request field at fault, when there is one
+    e.requestId  // the request's X-Request-Id, worth quoting in a bug report
+    e.transient  // whether the same request may work later
+  }
+  isTransient(e) // the same, for any thrown value: false for anything but a CloudSimError
+}
+```
+
+Every call is retried on transient failures (no answer, a request past
+`timeoutMs`, 429, 502, 503, 504) up to `maxRetries` times, waiting as
+`Retry-After` says when the server says (a wait of more than a minute is
+not waited out), and backing off from half a second otherwise. That is
+safe for every call: a create carries an `Idempotency-Key`, and the server
+answers a repeated cancel with the run as it is (a run that finished
+meanwhile gets 409 `run_finished`, which is not retried). The client's
+`onRetry` hears of each retry before its wait.
+
+## Development
+
+This package and the MCP server (`mcp/`) are one npm workspace at the root
+of the cloud-sim repo.
+
+```sh
+npm ci                      # at the repo root
+cd sdk/typescript
+npm test
+npm run typecheck
+npm run build
+npm run generate            # after openapi/v1.json changes
+npm run check:generated     # fails when src/generated/v1.ts is stale
+```
+
+Tests run against a fake `fetch`, and every JSON body the fake server
+answers with is checked against the schemas in `openapi/v1.json`.
+
+## License
+
+Proprietary (`UNLICENSED`), as the API itself is.

package/dist/catalog.d.ts

@@ -0,0 +1,32 @@
+import { type Transport } from './http.js';
+import type { CallOptions } from './runs.js';
+import type { McuList, Version, VersionList } from './types.js';
+export interface McuFilter extends CallOptions {
+    /** Only this engine's MCUs. An engine the version lacks is 400 `engine_not_in_version`. */
+    engine?: string;
+    /** Only MCUs that run: on `engine`, or without one on any engine. */
+    runnable?: boolean;
+}
+export interface McuListOptions extends McuFilter {
+    /** The API version whose catalog to read, in place of the client's. */
+    version?: string;
+}
+export declare class Versions {
+    private readonly http;
+    constructor(http: Transport);
+    /** Every version the server serves, oldest first, and which is the default. */
+    list(options?: CallOptions): Promise<VersionList>;
+    /** One version: its lifecycle, notes, engines, and changes against the one before. */
+    get(version: string, options?: CallOptions): Promise<Version>;
+    /** Version `version`'s MCU catalog. */
+    mcus(version: string, filter?: McuFilter): Promise<McuList>;
+}
+export declare class Mcus {
+    private readonly http;
+    constructor(http: Transport);
+    /**
+     * The MCU catalog of `version`, else of the client's version, else of the
+     * server's default.
+     */
+    list(options?: McuListOptions): Promise<McuList>;
+}

package/dist/catalog.js

@@ -0,0 +1,58 @@
+// `client.versions` and `client.mcus`: the API versions, the engines each
+// pins, and their MCU catalogs. The server needs no credential for these;
+// the client sends its own anyway, which does no harm.
+import { segment } from './http.js';
+export class Versions {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Every version the server serves, oldest first, and which is the default. */
+    list(options = {}) {
+        return this.http.json({
+            method: 'GET',
+            path: '/v1/versions',
+            signal: options.signal,
+            retry: true,
+        });
+    }
+    /** One version: its lifecycle, notes, engines, and changes against the one before. */
+    get(version, options = {}) {
+        return this.http.json({
+            method: 'GET',
+            path: `/v1/versions/${segment(version)}`,
+            signal: options.signal,
+            retry: true,
+        });
+    }
+    /** Version `version`'s MCU catalog. */
+    mcus(version, filter = {}) {
+        return this.http.json({
+            method: 'GET',
+            path: `/v1/versions/${segment(version)}/mcus`,
+            query: { engine: filter.engine, runnable: filter.runnable },
+            signal: filter.signal,
+            retry: true,
+        });
+    }
+}
+export class Mcus {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * The MCU catalog of `version`, else of the client's version, else of the
+     * server's default.
+     */
+    list(options = {}) {
+        return this.http.json({
+            method: 'GET',
+            path: '/v1/mcus',
+            query: { engine: options.engine, runnable: options.runnable },
+            version: options.version,
+            signal: options.signal,
+            retry: true,
+        });
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,53 @@
+import { Mcus, Versions } from './catalog.js';
+import { type ApiKey, type RetryInfo } from './http.js';
+import { Runs } from './runs.js';
+export interface CloudSimOptions {
+    /**
+     * An `smtc_` API key, or a simantic dashboard session's access token. A
+     * function is called before every request, so it can hand back a token
+     * that has been refreshed since.
+     */
+    apiKey: ApiKey;
+    /**
+     * The API version (`Cloud-Sim-Version`), such as `1.0`: it pins each
+     * engine to one release. Without it the server answers with its newest
+     * stable version, which can change under a long-lived client.
+     */
+    version?: string;
+    /** Default `https://cloud.simantic.com`. */
+    baseUrl?: string;
+    /** Default the global fetch. */
+    fetch?: typeof fetch;
+    /**
+     * Called when the server refuses the credential (401), once per request,
+     * which is then sent again with `apiKey` as it is after. The dashboard
+     * refreshes its session here.
+     */
+    onUnauthorized?: () => Promise<void> | void;
+    /**
+     * How many times a transient failure (no answer, 429, 502, 503, 504) is
+     * retried: every call is safe to repeat (a create carries an
+     * Idempotency-Key, and a repeated cancel gets the run as it is). Default 3.
+     */
+    maxRetries?: number;
+    /**
+     * How long each request has until its answer's headers arrive, in
+     * milliseconds; past it, the request counts as unanswered (`timeout`,
+     * transient) and is retried as one. An upload counts against it, so
+     * `runs.create` takes its own. Reading the answer is not timed. 0 for no
+     * limit. Default 60000.
+     */
+    timeoutMs?: number;
+    /**
+     * Told before each retry: which retry, the failure, and how long until it
+     * is sent. For showing "Reconnecting…"; it must not throw.
+     */
+    onRetry?: (info: RetryInfo) => void;
+}
+/** A client of the Cloud Sim API. */
+export declare class CloudSim {
+    readonly runs: Runs;
+    readonly versions: Versions;
+    readonly mcus: Mcus;
+    constructor(options: CloudSimOptions);
+}

package/dist/client.js

@@ -0,0 +1,15 @@
+import { Mcus, Versions } from './catalog.js';
+import { Transport } from './http.js';
+import { Runs } from './runs.js';
+/** A client of the Cloud Sim API. */
+export class CloudSim {
+    runs;
+    versions;
+    mcus;
+    constructor(options) {
+        const http = new Transport(options);
+        this.runs = new Runs(http);
+        this.versions = new Versions(http);
+        this.mcus = new Mcus(http);
+    }
+}

package/dist/compare.d.ts

@@ -0,0 +1,26 @@
+import type { RunResult } from './types.js';
+/** The first UART record two outputs do not share. */
+export interface Difference {
+    /** Its line number, from 1. */
+    line: number;
+    /** The first output's record, or null if that output ended before it. */
+    a: string | null;
+    /** The second output's record, or null if that output ended before it. */
+    b: string | null;
+}
+export interface ResultComparison {
+    /** Each result's exit code: 0 ok, 1 the simulation failed, 2 a usage error. */
+    exitCodes: [number | null, number | null];
+    sameExitCode: boolean;
+    /** Whether the UART output is the same, byte for byte. */
+    outputIdentical: boolean;
+    /** Null when the outputs are identical. */
+    firstDifference: Difference | null;
+}
+/**
+ * How result `b` differs from result `a`: both exit codes, whether the UART
+ * output is identical, and the first record that differs. A record is shown
+ * without the newline that ends it, unless that newline is the only
+ * difference (`"r2\n"` against `"r2"`). A missing output counts as empty.
+ */
+export declare function compareResults(a: Pick<RunResult, 'exit_code' | 'output'>, b: Pick<RunResult, 'exit_code' | 'output'>): ResultComparison;

package/dist/compare.js

@@ -0,0 +1,53 @@
+// `compareResults`: how two runs' results differ, for a comparison of
+// engines (`runs.compare`). Every engine writes the same UART record
+// format: records, each ended by a newline. So the first record that
+// differs is the first line that does, and a trailing newline ends the last
+// record rather than starting an empty one. The Python SDK's
+// `compare_results` reports the same.
+/**
+ * How result `b` differs from result `a`: both exit codes, whether the UART
+ * output is identical, and the first record that differs. A record is shown
+ * without the newline that ends it, unless that newline is the only
+ * difference (`"r2\n"` against `"r2"`). A missing output counts as empty.
+ */
+export function compareResults(a, b) {
+    const exitCodes = [a.exit_code ?? null, b.exit_code ?? null];
+    const left = a.output ?? '';
+    const right = b.output ?? '';
+    return {
+        exitCodes,
+        sameExitCode: exitCodes[0] === exitCodes[1],
+        outputIdentical: left === right,
+        firstDifference: left === right ? null : firstDifference(left, right),
+    };
+}
+function firstDifference(a, b) {
+    const left = records(a);
+    const right = records(b);
+    for (let i = 0; i < Math.max(left.length, right.length); i++) {
+        const ra = left[i] ?? null;
+        const rb = right[i] ?? null;
+        if (ra === rb)
+            continue;
+        const shown = [bare(ra), bare(rb)];
+        // Records that differ only in the newline ending one: show it.
+        return shown[0] === shown[1]
+            ? { line: i + 1, a: ra, b: rb }
+            : { line: i + 1, a: shown[0], b: shown[1] };
+    }
+    // Records join back into their text, so different texts have a record
+    // that differs; this is not reached.
+    return null;
+}
+/** `text`'s records, each with the newline that ends it (the last may have none). */
+function records(text) {
+    const pieces = text.split('\n');
+    const last = pieces.pop();
+    const found = pieces.map((piece) => `${piece}\n`);
+    if (last)
+        found.push(last);
+    return found;
+}
+function bare(record) {
+    return record?.endsWith('\n') ? record.slice(0, -1) : record;
+}

package/dist/errors.d.ts

@@ -0,0 +1,61 @@
+import type { Run, Version } from './types.js';
+/** The fields of a `CloudSimError`, for building one. */
+export interface CloudSimErrorInit {
+    status: number;
+    code: string;
+    param?: string | null;
+    requestId?: string | null;
+    /** Whether it may go away on its own; by default, what `status` says. */
+    transient?: boolean;
+}
+/**
+ * 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 declare class CloudSimError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly param: string | null;
+    readonly requestId: string | null;
+    readonly transient: boolean;
+    constructor(message: string, init: CloudSimErrorInit);
+}
+/**
+ * `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 declare class CompareError extends CloudSimError {
+    /** The version the comparison was made on. */
+    readonly version: Version;
+    /** The runs made, by engine, in the order the engines were given. */
+    readonly runs: Record<string, Run>;
+    /**
+     * Why each other engine's run was not made, by engine, in the same order:
+     * a `CloudSimError`, or whatever else the create threw.
+     */
+    readonly errors: Record<string, unknown>;
+    constructor(version: Version, runs: Record<string, Run>, errors: Record<string, unknown>);
+}
+/**
+ * Whether `error` is a failure that may go away if the same request is made
+ * again: a `CloudSimError` that is `transient`.
+ */
+export declare function isTransient(error: unknown): boolean;
+/**
+ * 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 declare function transientStatus(status: number): boolean;
+/** The code the server gives an error of `status` that names none of its own. */
+export declare function generalCode(status: number): string;