ContextQMD
Back to Microsandbox

microsandbox types

packages/microsandbox-types/README.md

0.5.82.3 KB
Original Source

microsandbox types

Shared task and wire contract types for microsandbox.

These packages define the backend-neutral shapes that describe what a sandbox should be: its rootfs source, resources, mounts, patches, network, lifecycle, and the cloud HTTP request/response bodies that carry those specs over the wire. Everything that has to agree on a sandbox's shape (the Rust SDK, the CLI, the cloud API, and the TypeScript front end) depends on these contracts instead of redefining them.

This is a contract layer, not a runtime. It does not create, start, or talk to sandboxes. It only models the data those operations exchange.

Layout

text
packages/microsandbox-types/
├── rust/
└── typescript/
  • rust/ publishes as microsandbox-types (crate name microsandbox_types). It is the source of truth for every shared type.
  • typescript/ publishes as @microsandbox/types. Its src/index.ts is generated from the Rust types, never hand-edited.

Source Of Truth

The Rust crate owns the definitions. The TypeScript bindings are derived from them with ts-rs behind the crate's ts feature, so the two stay byte-for-byte aligned.

text
rust/lib/*.rs  ──(ts-rs)──▶  typescript/src/index.ts

To regenerate the bindings after changing a Rust type:

bash
cargo run -p microsandbox-types --features ts --bin microsandbox-types-generate

CI runs the same generator with --check and fails when the checked-in bindings drift:

bash
cargo run -p microsandbox-types --features ts --bin microsandbox-types-generate -- --check

What Lives Here

  • Sandbox specs: SandboxSpec, SandboxResources, SandboxRuntimeOptions, rootfs sources, mounts, patches, init, lifecycle policy.
  • Networking intent: NetworkSpec, published ports, protocols.
  • Volumes and snapshots: VolumeSpec, SnapshotSpec, and their kinds.
  • Exec and logging: Rlimit, RlimitResource, LogSource, SandboxLogLevel.
  • Cloud wire contracts: CloudCreateSandboxRequest, CloudSandbox, paginated/message/error bodies.
  • Validation helpers: sandbox-name and hostname rules shared across SDK, CLI, and cloud.

Backend-private materialized state (registry credentials, local cache paths, DB rows, resolved manifest digests, process handles) deliberately stays out of these packages. See each language's README for details.