@capsulos/sdk 0.0.0-stage → 0.1.1

package/src/types.ts

@@ -0,0 +1,185 @@
+// The three axes of capsulos (docs/ARCHITECTURE.md):
+//   Provider   — where a capsule runs (lambda, docker, later firecracker)
+//   Primitives — what a capsule exposes (process, fs, pty, ports)
+//   Drivers    — how a primitive is implemented (fs: local, tmpfs, overlay, s3)
+
+/** Where a capsule lives. Implemented by @capsulos/provider-* packages. */
+export interface Provider {
+  readonly name: string;
+  /** Create a capsule and wait until it runs (see CreateOptions for the wait). */
+  create(spec: CapsuleSpec, opts?: CreateOptions): Promise<CapsuleHandle>;
+  get(id: string): Promise<CapsuleInfo | null>;
+  /** Capsules this provider knows about, optionally only those of one template. */
+  list(template?: string): Promise<CapsuleInfo[]>;
+  terminate(id: string): Promise<void>;
+  /** How to reach the daemon of an existing capsule (endpoint + auth headers). */
+  connect(id: string): Promise<Connection>;
+}
+
+export interface CreateOptions {
+  /**
+   * How long to wait for the capsule to run before giving up (provider
+   * default: 120 s). On timeout the provider terminates what it started, so
+   * nothing is left running without an owner, and throws a CapsuleError
+   * whose `capsuleId` names it.
+   */
+  timeoutMs?: number;
+  /** Abort the wait (same clean-up as a timeout). */
+  signal?: AbortSignal;
+}
+
+export interface HeadersOptions {
+  /** Discard any cached credential and mint a new one (after a 401/403). */
+  fresh?: boolean;
+}
+
+export interface Connection {
+  /** Base URL of capsulod, e.g. https://abc.microvm.lambda-url.us-east-1.on.aws */
+  baseUrl: string;
+  /** Headers every request must carry (e.g. X-aws-proxy-auth). Cached by the provider; `fresh` re-mints. */
+  headers(opts?: HeadersOptions): Promise<Record<string, string>>;
+}
+
+export type CapsuleState = 'pending' | 'running' | 'suspended' | 'terminated' | 'unknown';
+
+export interface CapsuleInfo {
+  id: string;
+  provider: string;
+  state: CapsuleState;
+  template: string | null;
+  createdAt: Date | null;
+  /** When the provider terminated it (provider clock); null while alive or unknown. */
+  terminatedAt?: Date | null;
+  /** The provider's reason for the current state (e.g. why it died), when it gives one. */
+  stateReason?: string | null;
+  /** Where capsulod answers (the Connection's baseUrl), when the provider knows it without another call. */
+  endpoint?: string | null;
+  /** Version of the template the capsule runs (a MicrovmImage version on Lambda). */
+  templateVersion?: string | null;
+  /** The hard wall-clock limit it was created with. */
+  maxDurationSeconds?: number | null;
+}
+
+export interface CapsuleHandle extends CapsuleInfo {
+  connection: Connection;
+}
+
+/** A mount declared at creation. `posix` drivers are mounted in the kernel and seen by processes. */
+export type MountSpec =
+  | { driver: 'local' }
+  | { driver: 'tmpfs'; sizeMb?: number }
+  | { driver: 'overlay'; lower: string }
+  | { driver: 's3'; bucket: string; prefix?: string; readOnly?: boolean; region?: string };
+
+export interface MountResult {
+  path: string;
+  driver: string;
+  ok: boolean;
+  error?: string;
+}
+
+export interface Health {
+  ok: boolean;
+  version: string;
+  uptimeS: number;
+  /** True once the mount table was applied (by the boot hook or /configure). */
+  configured: boolean;
+  mounts?: MountResult[];
+  /** The template's long-running process (CAPSULOD_START), when the template declares one. */
+  service?: ServiceStatus;
+}
+
+export interface ServiceStatus {
+  cmd: string;
+  pid: number;
+  running: boolean;
+  restarts: number;
+  lastExitCode?: number;
+  startedAt?: string;
+}
+
+export interface IdlePolicy {
+  /** Suspend after this long without traffic (seconds). */
+  suspendAfterSeconds: number;
+  /** Destroy after this long suspended (seconds). */
+  destroyAfterSeconds: number;
+}
+
+export interface CapsuleSpec {
+  /** Template (image) name as registered with the provider. */
+  template: string;
+  /** Hard wall-clock limit for the capsule, in seconds. */
+  maxDurationSeconds?: number;
+  idle?: IdlePolicy;
+  mounts?: Record<string, MountSpec>;
+  /** Opaque per-capsule configuration delivered to the daemon at boot (never secrets). */
+  metadata?: Record<string, string>;
+  /** Idempotency key: creating twice with the same key returns the same capsule. */
+  clientToken?: string;
+}
+
+// ---- process primitive ----
+
+export interface ExecOptions {
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  stdin?: string;
+  timeoutMs?: number;
+  onStdout?: (chunk: string) => void;
+  onStderr?: (chunk: string) => void;
+}
+
+export interface ExecResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  timeout: boolean;
+  error?: string;
+  durationMs: number;
+}
+
+export type ExecEvent =
+  | { type: 'stdout'; data: string }
+  | { type: 'stderr'; data: string }
+  | { type: 'exit'; exitCode: number; timeout?: boolean; error?: string };
+
+// ---- pty primitive ----
+
+export interface PtyOptions {
+  /** Program to run; defaults to bash when the template has it, else sh. */
+  cmd?: string;
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  cols?: number;
+  rows?: number;
+  onData?: (chunk: Uint8Array) => void;
+  connectTimeoutMs?: number;
+}
+
+// ---- fs primitive ----
+
+export interface FileEntry {
+  name: string;
+  path: string;
+  isDir: boolean;
+  size: number;
+  mode: string;
+  modTime: string;
+}
+
+export class CapsuleError extends Error {
+  /** The capsule the error is about, when there is one (e.g. the one a create() timeout terminated). */
+  readonly capsuleId?: string;
+
+  constructor(
+    message: string,
+    readonly status?: number,
+    opts: { capsuleId?: string } = {},
+  ) {
+    super(message);
+    this.name = 'CapsuleError';
+    if (opts.capsuleId) this.capsuleId = opts.capsuleId;
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.