@supermachine/core 0.4.25

package/index.d.ts

@@ -0,0 +1,532 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by scripts/gen-dts.js from napi-derive's TYPE_DEF_TMP_PATH output */
+/* DO NOT EDIT — regenerate via `npm run build`. */
+
+/**
+ * VM-shaped handle passed to a `warmup` callback. Only valid
+ * during the callback's lifetime — `exec` errors after return.
+ */
+export interface WarmupVm {
+  exec(options: ExecOptions): Promise<ExecOutput>
+}
+
+/**
+ * One staged host file → guest path mapping for `extraFiles`. See
+ * [`BuildOptions::extra_files`].
+ */
+export interface ExtraFileSpec {
+  /**
+   * Host filesystem path. File contents are read at bake time
+   * and folded into the snapshot's input-hash, so changes
+   * re-bake.
+   */
+  hostPath: string
+  /** Where the file appears inside the guest's root filesystem. */
+  guestPath: string
+}
+
+/**
+ * Options for [`Image.build`]. Mirrors `OciImageBuilder` in the
+ * Rust crate. All fields optional except `ref` (the OCI image
+ * reference).
+ */
+export interface BuildOptions {
+  /**
+   * OCI image reference, e.g. `"rust:1-slim"`,
+   * `"ghcr.io/owner/image@sha256:..."`.
+   */
+  ref: string
+  /**
+   * Stable snapshot name. Defaults to a sha-derived name based
+   * on the image reference.
+   */
+  name?: string
+  /**
+   * Guest memory in MiB. Default 256. Note: allocation is lazy
+   * (CoW page-fault); this is the guest-visible ceiling, not
+   * host commit.
+   */
+  memoryMib?: number
+  /** vCPUs per VM. Default 1. */
+  vcpus?: number
+  /** `"always"` | `"missing"` | `"never"`. Default `"missing"`. */
+  pullPolicy?: string
+  /**
+   * Workload listener port. Default 80. Used by service-image
+   * bakes (see `listenerRequired`).
+   */
+  guestPort?: number
+  /** Override the image's CMD/ENTRYPOINT. */
+  cmd?: Array<string>
+  /** Extra environment variables for the workload. */
+  env?: Record<string, string>
+  /**
+   * When `true`, wait for the workload's listener to bind before
+   * capturing the snapshot — v0.4.22 behavior. Default `false`
+   * uses the pre-exec trigger (v0.4.23+): fast bake, workload
+   * starts fresh on each restore. Set `true` for service-image
+   * bakes (nginx, redis) where you want the listener pre-bound.
+   */
+  listenerRequired?: boolean
+  /**
+   * Directory for the snapshot artifact. Default
+   * `~/.local/supermachine-snapshots`.
+   */
+  snapshotsDir?: string
+  /**
+   * Files to bake into the delta layer at fixed guest paths.
+   * Bytes read from `hostPath` at bake time; the host file's
+   * contents are folded into the snapshot's input-hash so any
+   * change re-bakes. Common pattern: ship per-snapshot
+   * kernel modules, certs, configuration files. Maps to
+   * `OciImageBuilder::with_extra_file`.
+   */
+  extraFiles?: Array<ExtraFileSpec>
+  /**
+   * Stable tag for the warmup callback (see the `warmup`
+   * parameter on [`Image.build`]). Folded into the snapshot's
+   * cached fingerprint so changing the warmup body invalidates
+   * the previous warm snapshot. Default `"default"` — set a
+   * versioned tag (`"v1"`, `"v2"`) when you mutate the warmup.
+   * Ignored when no warmup function is provided.
+   */
+  warmupTag?: string
+  /**
+   * Post-bake warmup callback. Receives a [`WarmupVm`] bound to a
+   * freshly-booted guest; run `vm.exec()` calls to populate state,
+   * then return. The bake captures the post-warmup snapshot.
+   *
+   * The Vm is invalidated after the callback returns.
+   */
+  warmup?: (vm: WarmupVm) => Promise<void>
+}
+
+export interface PoolOptions {
+  /**
+   * Minimum idle VMs to keep warm. Spawned eagerly at pool
+   * build time. Default 1.
+   */
+  min?: number
+  /**
+   * Maximum total VMs (active + idle). Pool grows up to this
+   * under load. Default 1.
+   */
+  max?: number
+  /**
+   * Max wait for `acquire()` when the pool is saturated.
+   * Default 60_000 (60 s).
+   *
+   * Special value: pass `0` for "no timeout — block forever".
+   * Useful for batch workloads that prefer waiting over
+   * failing. Mirrors `PoolBuilder::no_acquire_timeout()` on the
+   * Rust side.
+   */
+  acquireTimeoutMs?: number
+  /**
+   * Idle VM lifetime before janitor evicts above `min`. Defaults
+   * to no eviction.
+   */
+  idleTimeoutMs?: number
+  /** If `true` (default), cycle-restore the VM on release. */
+  restoreOnRelease?: boolean
+  /**
+   * Runtime memory ceiling override for this pool's workers
+   * (in MiB). Defaults to the value baked into the snapshot.
+   * Pure runtime — doesn't re-bake. Pages are lazy-committed,
+   * so raising the ceiling above the baked value doesn't
+   * increase host commit unless the guest actually writes to
+   * the new pages.
+   */
+  memoryMib?: number
+  /**
+   * Runtime vCPU count override for this pool's workers.
+   * Defaults to the value baked into the snapshot.
+   */
+  vcpus?: number
+  /**
+   * Per-worker snapshot-restore timeout (ms). Default 30_000.
+   * Bump for slow disks or large RAM snapshots — restore time
+   * scales roughly linearly with snapshot size. Forwards to
+   * `VmConfig::with_restore_timeout` via PoolBuilder.
+   */
+  restoreTimeoutMs?: number
+}
+
+/**
+ * Returned by [`Pool.stats`]. Pool observability for monitoring,
+ * autoscaling decisions, and capacity tuning.
+ */
+export interface PoolStats {
+  /** Total workers the pool has spawned (idle + checked-out). */
+  alive: number
+  /** Workers currently checked out via `acquire()`. */
+  inUse: number
+  /** Workers sitting in the idle queue. */
+  idle: number
+  /**
+   * Number of callers currently blocked in `acquire()` waiting
+   * for an idle worker to free up.
+   */
+  waiting: number
+  /** Configured `min` from PoolOptions. */
+  min: number
+  /** Configured `max` from PoolOptions. */
+  max: number
+}
+
+/**
+ * One file → bytes mapping for `stageFilesMode` (variant of
+ * `stageFiles` that also lets you set the guest-side file mode,
+ * e.g. 0o755 for shipping executable scripts inline with an exec).
+ */
+export interface StagedFileMode {
+  guestPath: string
+  bytes: Buffer
+  /**
+   * Unix file mode (e.g. `0o755`, written as `493` if you can't
+   * use octal literals in your JS engine). When `null`, the
+   * agent uses 0o644 (same as the plain `stageFiles` entry).
+   */
+  mode?: number
+}
+
+export interface ExecOptions {
+  argv: Array<string>
+  /**
+   * Files to stage at fixed paths inside the guest before the
+   * command runs. Mode defaults to 0o644. Use `stageFilesMode`
+   * instead when you need to set the executable bit (or any
+   * other mode).
+   */
+  stageFiles?: Record<string, Buffer>
+  /**
+   * Like `stageFiles` but with explicit per-file Unix modes.
+   * Useful for shipping executable scripts (`0o755`) or
+   * read-only secrets (`0o400`). Entries here are unioned with
+   * `stageFiles` — same `guestPath` in both is undefined order;
+   * pick one.
+   */
+  stageFilesMode?: Array<StagedFileMode>
+  timeoutMs?: number
+  env?: Record<string, string>
+  cwd?: string
+  chain?: Array<string>
+  /**
+   * Allocate a pseudo-terminal for the guest process. With
+   * `tty: true`, stdout/stdin pass through the pty master and
+   * stderr is empty (the pty merges fd 1 + fd 2). Use this for
+   * interactive REPLs, shells, or any process that expects a
+   * real terminal (e.g. progress bars that detect isatty).
+   */
+  tty?: boolean
+  /**
+   * Initial window size for tty mode. Ignored when `tty` is
+   * false. Call `ExecChild.resize(cols, rows)` to change it
+   * later from the streaming `spawn()` path.
+   */
+  winsize?: Winsize
+}
+
+/**
+ * Terminal window size for `ExecOptions.winsize`. Both fields are
+ * in character cells (not pixels). Use 0/0 to let the agent pick
+ * a default (80x24 in practice).
+ */
+export interface Winsize {
+  cols: number
+  rows: number
+}
+
+export interface ExecOutput {
+  stdout: Buffer
+  stderr: Buffer
+  exitCode: number
+}
+
+/**
+ * Result of [`ExecChild.wait`]. Mirrors `ExecOutcome` minus the
+ * stdout/stderr buffers (those were already streamed via
+ * `readStdout`/`readStderr`).
+ */
+export interface ExecWaitResult {
+  /** `-1` if killed by signal / timeout / agent disconnect. */
+  exitCode: number
+  /**
+   * `true` if the process exited because the spawn-time
+   * `timeoutMs` watchdog killed it.
+   */
+  timedOut: boolean
+  /**
+   * Peak resident-set size in KiB during the process's life,
+   * as reported by the in-guest agent's wait4(rusage). `null`
+   * when not reported.
+   */
+  peakRssKib?: number
+}
+
+/**
+ * A baked OCI image. Returned by [`Image.build`] (bakes or
+ * cache-hits) and by [`Image.fromSnapshot`].
+ */
+export declare class Image {
+  /**
+   * Build an image from an OCI reference, or return the cached
+   * snapshot if one already exists. Async: runs the bake
+   * pipeline on a libuv worker thread.
+   *
+   * **Cold first-time bake of `alpine:latest` on Apple Silicon
+   * takes ~400 ms**. Cache-hit is ~15 ms.
+   *
+   * `warmup` is an optional async callback that receives a [`Vm`]
+   * after the guest is booted. Use it to pre-populate guest
+   * state (compile a seed program, warm a page cache) — the
+   * bake captures the post-warmup snapshot, so restores land in
+   * the warm state. Pair with `warmupTag` in `options` to
+   * version-tag the warmup for cache invalidation.
+   *
+   * The Vm passed to the warmup is invalidated after the
+   * callback returns; holding a reference past return is safe
+   * (won't crash) but `vm.exec()` will error.
+   *
+   * We take `warmup` as a separate positional argument rather
+   * than as a field on `options` because napi-rs's async-fn
+   * support requires all parameters to be `Send`. Plain
+   * `JsFunction` isn't `Send`; here we use `AsyncTask` (which
+   * splits sync-setup from sync-compute) to keep the JsFunction
+   * → TSFn conversion on the JS thread while the bake runs on
+   * a worker. The JS shim in index.js wraps this back into a
+   * natural `Image.build({...})` API.
+   */
+  static build(options: BuildOptions): Promise<Image>
+  /**
+   * Load an image from a previously-baked snapshot directory or
+   * `restore.snap` file path. No bake — just reads metadata.json
+   * and validates the snapshot file exists.
+   */
+  static fromSnapshot(path: string): Promise<Image>
+  /**
+   * Create a VM pool for this image. `min`/`max` are the most
+   * important — `min=max=N` pre-spawns N VMs eagerly and caps
+   * total at N.
+   *
+   * Memory: each idle VM costs ~3 MiB host phys_footprint
+   * (measured). The `memoryMib` build option is a guest-visible
+   * ceiling, not host commit.
+   */
+   pool(options?: PoolOptions | undefined | null): Promise<Pool>
+  /**
+   * On-disk snapshot directory backing this Image. Same as
+   * `supermachine::Image::snapshot_path` in Rust. Useful for
+   * diagnostics, log lines, or chaining a second image off the
+   * same snapshot via `Image.fromSnapshot`.
+   */
+  get snapshotPath(): string
+  /** Guest memory (MiB) as baked into the snapshot's metadata. */
+  get memoryMib(): number
+  /** vCPU count as baked into the snapshot's metadata. */
+  get vcpus(): number
+}
+
+export declare class Pool {
+  /**
+   * Acquire a VM from the pool. Blocks (async) up to
+   * `acquireTimeoutMs`. ~0 ms warm-handoff / ~5 ms cycle-restore
+   * / ~22 ms spawn-from-disk.
+   */
+   acquire(): Promise<Vm>
+  /** Best-effort pool shutdown. Pool also shuts down on GC. */
+   shutdown(): Promise<void>
+  /**
+   * Snapshot of the pool's current state. Cheap (~1 µs, just a
+   * mutex lock) — safe to poll frequently for monitoring /
+   * autoscaling decisions.
+   */
+   stats(): PoolStats
+}
+
+/**
+ * Streaming exec handle returned by [`Vm.spawn`]. Pull-style API:
+ * caller polls `readStdout()` / `readStderr()` for chunks, writes
+ * to stdin via `writeStdin()`, sends signals via `signal()`, and
+ * awaits exit via `wait()`. Mirrors the Rust `ExecChild`.
+ *
+ * Pull-style was chosen over Node `ReadableStream`/`WritableStream`
+ * for two reasons: (1) the underlying Rust types are sync
+ * `Read`/`Write`, so wrapping in stream adapters would require
+ * per-chunk napi roundtrips anyway, and (2) pull-style is the
+ * minimum-surface-area API that covers all use cases (LLM-style
+ * streaming output, interactive REPLs, anything you can build
+ * with `for await (const chunk of pull()) ...`).
+ */
+export declare class ExecChild {
+  /**
+   * Write a chunk to the process's stdin. Returns when the
+   * bytes have been queued on the host-side socket; the guest
+   * agent forwards them to the process asynchronously. Multiple
+   * calls append.
+   */
+   writeStdin(bytes: Buffer): Promise<void>
+  /** Close stdin (send EOF to the process). Idempotent. */
+   closeStdin(): Promise<void>
+  /**
+   * Read up to `maxBytes` (default 64 KiB) from stdout. Returns
+   * an empty Buffer when stdout has closed (process exited and
+   * drained); the caller's `for await` loop should terminate on
+   * `buf.length === 0`.
+   *
+   * Blocks the libuv worker thread; the JS event loop stays
+   * free for other work.
+   */
+   readStdout(maxBytes?: number | undefined | null): Promise<Buffer>
+  /** Same as [`readStdout`] for stderr. */
+   readStderr(maxBytes?: number | undefined | null): Promise<Buffer>
+  /**
+   * Resize the pty (tty mode only). No-op when the process was
+   * spawned without `tty: true` — the guest agent ignores RESIZE
+   * frames if no pty is attached. Use this from the JS side to
+   * react to host terminal resize events (e.g. SIGWINCH on
+   * process.stdout).
+   */
+   resize(cols: number, rows: number): Promise<void>
+  /**
+   * Send a signal to the guest-side process. Common values:
+   * 1=SIGHUP, 2=SIGINT, 9=SIGKILL, 15=SIGTERM.
+   */
+   signal(signum: number): Promise<void>
+  /**
+   * Wait for the guest-side process to exit and return its
+   * status. Consumes the underlying ExecChild — subsequent
+   * calls error with "already waited". Drains any unread
+   * stdout/stderr (caller should pull them out FIRST if they
+   * care about full output).
+   */
+   wait(): Promise<ExecWaitResult>
+}
+
+/**
+ * VM handle. Drop or `release()` to return to the pool. With Node
+ * 20+, use the `using` keyword + `Symbol.asyncDispose`.
+ */
+export declare class Vm {
+  /** Run a process inside the guest via the in-guest exec agent. */
+   exec(options: ExecOptions): Promise<ExecOutput>
+  /** Return the VM to the pool. Idempotent. */
+   release(): Promise<void>
+  /**
+   * Alias for `release()`. Wired up to `Symbol.asyncDispose` in
+   * the JS shim for the TC39 explicit-resource-management
+   * `using` keyword (Node 20+).
+   */
+   dispose(): Promise<void>
+  /**
+   * Write `bytes` to `path` inside the guest. Native vsock RPC,
+   * ~100 µs round-trip. Complement to `exec({stageFiles})` —
+   * use this when you want to drop a file without running a
+   * command (or between commands on the same vm).
+   *
+   * 4 MiB default cap on file size; stream larger files via
+   * `exec` with `stageFiles` instead.
+   */
+   writeFile(path: string, bytes: Buffer): Promise<void>
+  /**
+   * Read `path` from inside the guest, return bytes. Native
+   * vsock RPC, ~100 µs round-trip. 4 MiB default cap; stream
+   * larger files via `exec` + redirect to a host path.
+   */
+   readFile(path: string): Promise<Buffer>
+  /**
+   * Spawn a process inside the guest and return a streaming
+   * [`ExecChild`] handle. Unlike `exec()` which collects
+   * stdout/stderr into Buffers, `spawn()` lets you write to
+   * stdin / read from stdout/stderr incrementally — useful for
+   * LLM-style streaming, long-running daemons, interactive REPLs.
+   *
+   * Important: ExecOptions.timeoutMs is IGNORED in spawn mode —
+   * the caller controls cancellation via `child.signal(9)`. The
+   * timeout watchdog only applies to the collect-mode `exec()`.
+   */
+   spawn(options: ExecOptions): Promise<ExecChild>
+  /**
+   * Capture a snapshot of this VM's current state and return a
+   * new `Image` pointing at it. Equivalent to `Vm::snapshot` in
+   * the Rust crate. The guest is paused for the capture
+   * (typically 10s of ms; bounded by disk write time for large
+   * RAM). The Vm remains usable after — handy for the
+   * "warm up + snapshot + keep working" pattern.
+   *
+   * Returns a fresh Image; build a pool from it via `image.pool()`
+   * to spawn workers that restore from the captured state.
+   */
+   snapshot(destDir: string): Promise<Image>
+  /**
+   * Send `signum` to the guest's workload PID-1 (the process
+   * the image's CMD/ENTRYPOINT launched at boot). Mirrors
+   * `supermachine::Vm::workload_signal`.
+   *
+   * Distinct from `ExecChild.signal`, which targets a process
+   * spawned via `vm.spawn()`. Use this for graceful service
+   * shutdown of baked service images (e.g. SIGTERM to nginx
+   * before tearing down the VM).
+   */
+   workloadSignal(signum: number): Promise<void>
+  /**
+   * On-disk path of this Vm's per-acquire vsock mux socket.
+   * Stable for the lifetime of the Vm; goes away on `release()`.
+   * Use this as an escape hatch when you want to bring your own
+   * client (e.g. open a raw UnixStream from `node:net` and speak
+   * a custom protocol to a workload listening inside the guest).
+   *
+   * Throws if called on the warmup vm — the bake driver owns
+   * the warmup vm's sockets.
+   */
+  get vsockPath(): string
+  /**
+   * On-disk path of this Vm's per-acquire exec control socket.
+   * Same lifetime as `vsockPath`. Mostly an escape hatch for
+   * users wiring up a non-libuv RPC client; the napi binding's
+   * own `exec`/`spawn`/`writeFile`/`readFile` go through this
+   * internally.
+   */
+  get execPath(): string
+  /**
+   * Bind `127.0.0.1:hostPort` and proxy connections into the
+   * guest's vsock mux. Returns a [`TcpForwarder`] handle; drop
+   * it (or call `forwarder.stop()`) to stop accepting new
+   * connections. In-flight connections survive `stop()` and
+   * close naturally.
+   *
+   * Pass `hostPort = 0` to let the OS pick a free port; read
+   * the actual bound port back via `forwarder.localAddr`.
+   *
+   * Note: `guestPort` is currently advisory. The Rust crate's
+   * `expose_tcp` ignores it and routes all forwarded
+   * connections into whatever the in-guest TSI mux accepts;
+   * per-guest-port routing is on the roadmap. Pass the port
+   * you semantically want — it's plumbed through so the
+   * signature stays stable when the routing fix lands.
+   */
+   exposeTcp(hostPort: number, guestPort: number): Promise<TcpForwarder>
+}
+
+/**
+ * Active TCP→vsock forwarder. Returned by [`Vm.exposeTcp`]; owns
+ * the host-side TcpListener accept-loop thread. Drop it (or call
+ * `stop()`) to stop accepting new connections. In-flight
+ * connections continue independently until they close naturally.
+ */
+export declare class TcpForwarder {
+  /**
+   * The address the forwarder is bound to, e.g. `"127.0.0.1:54321"`.
+   * Useful when you asked for `hostPort = 0` and want the
+   * OS-assigned port back.
+   */
+  get localAddr(): string
+  /**
+   * Stop accepting new connections. Idempotent. Equivalent to
+   * dropping the forwarder, but returns when the accept thread
+   * has actually exited (vs Drop, which detaches the join).
+   */
+   stop(): Promise<void>
+}