Crate microsandbox_types 

Shared task and wire contract types for microsandbox.

Re-exports

pub use modify::ChangeKind;

pub use modify::ConfigPlannedChange;

pub use modify::ModificationConflict;

pub use modify::ModificationDisposition;

pub use modify::ModificationPolicy;

pub use modify::ModificationWarning;

pub use modify::PlannedChange;

pub use modify::ResourceConvergenceState;

pub use modify::ResourceKind;

pub use modify::ResourceResizeStatus;

pub use modify::SandboxModificationPatch;

pub use modify::SandboxModificationPlan;

pub use modify::SecretChangeKind;

pub use modify::SecretModificationPatch;

pub use modify::SecretPlannedChange;

pub use modify::SecretSource;

Modules

modify

Sandbox modification contract shared by the SDKs, the CLI, and future backends.

Structs

CertCacheConfig

Per-domain certificate cache configuration.

CloudCreateSandboxRequest

Wire shape of a cloud sandbox create request body.

CloudCreateSandboxResponse

Wire shape of the cloud sandbox response returned by sandbox endpoints.

CloudErrorBody

Wire shape of the typed error body returned by cloud APIs on 4xx/5xx responses.

CloudErrorDetails

Nested cloud API error details.

CloudMessageResponse

Wire shape of the message response returned by mutation endpoints.

CloudNetworkSpec

Cloud network specification: a subset of the domain NetworkSpec. Interface overrides, host port mapping, DNS, TLS interception, rate limits, and host-CA trust are not part of this type. deny_unknown_fields — posting an omitted field is an error, not a silent drop.

CloudPaginated

Wire shape of paginated list responses.

CloudRlimit

A POSIX resource limit. Twin of Rlimit using CloudRlimitResource.

CloudSandboxResources

Cloud resource request.

CloudSandboxRuntimeOptions

Cloud guest runtime options: a subset of SandboxRuntimeOptions. The hostname and the metrics-sampling knobs are not part of this type. deny_unknown_fields.

CloudSandboxSpec

Cloud sandbox specification carried on create routes.

CloudSecretEntry

A single cloud secret entry. Twin of domain SecretEntry.

CloudSecretsConfig

Secret-injection config for the cloud API. Twin of domain SecretsConfig.

DnsConfig

DNS interception and filtering settings. Carried in NetworkSpec::dns.

EnvVar

Environment variable entry.

HandoffInit

Fully-assembled handoff-init specification.

InterceptCaConfig

Certificate authority configuration for TLS interception.

InterfaceOverrides

Optional guest interface overrides. Unset fields are derived from the sandbox slot by the local network engine. Carried in NetworkSpec::interface.

MountOptions

Guest mount behavior shared by every volume mount kind.

NamedVolumeCreate

Creation metadata for sandbox-time named volume provisioning.

NetworkPolicy

Egress/ingress network policy: an ordered Rule list plus a per-direction default Action. Carried in NetworkSpec::policy.

NetworkRateLimiterConfig

Egress and ingress rate limits for a local sandbox network.

NetworkSpec

Complete network specification for a sandbox.

OciRootfsSource

OCI root filesystem source.

PlacementProfile

Host-owned named placement profile resolved before a local VM starts.

PortRange

Inclusive guest-side port range for a Rule match.

PublishedPortSpec

A published port mapping between host and guest.

RateLimiterConfig

Token-bucket rate limiter for one traffic direction. Carried in NetworkRateLimiterConfig::egress and NetworkRateLimiterConfig::ingress.

Rlimit

A POSIX resource limit.

Rule

A single egress/ingress policy rule. Evaluated first-match-wins per direction.

SandboxPolicy

Sandbox lifecycle policy.

SandboxResources

CPU and memory resources for a sandbox.

SandboxRuntimeOptions

Guest runtime options for a sandbox.

SandboxSpec

Backend-neutral sandbox task description.

ScopedUpstreamCaCert

A CA certificate PEM file trusted only for matching upstream hosts.

ScopedVerifyUpstream

An upstream certificate verification override for matching hosts.

SecretEntry

A single secret entry.

SecretInjection

Where in the HTTP request a secret can be injected.

SecretsConfig

Placeholder-based secret injection for a sandbox’s TLS-intercepted egress.

SnapshotSpec

Inputs to create a snapshot.

TlsConfig

TLS interception configuration. Carried in NetworkSpec::tls.

TokenBucketConfig

One token bucket of a RateLimiterConfig.

VolumeSpec

Configuration for creating a named volume.

VsockRouteSpec

One host local-IPC endpoint exposed on a host-CID vsock port.

VsockSpec

Host services exposed to a sandbox through virtio-vsock.

Enums

Action

Action to take on traffic matched by a Rule (or a policy default).

CloudDiskImageFormat

Disk image format for cloud disk-image sources. Twin of DiskImageFormat with a snake_case wire.

CloudHostPattern

Host allowlist pattern for cloud secrets. Twin of HostPattern, with the domain’s scalar variants normalized to { value } for a uniform union.

CloudPatch

Rootfs patch applied before VM start. Twin of Patch, internally tagged with a snake_case type instead of the domain’s external PascalCase tag.

CloudPullPolicy

Cloud pull policy. Twin of domain PullPolicy with a snake_case wire.

CloudRlimitResource

POSIX resource-limit identifiers. Twin of RlimitResource with a snake_case wire.

CloudRootfsSource

Cloud root filesystem source.

CloudSandboxStatus

Sandbox lifecycle status returned by the cloud control plane.

CloudSandboxStatusReason

Reason a sandbox start is still in progress. Only meaningful while status is starting.

CloudSecretSource

Host-side source for a cloud secret. Twin of SecretSource.

CloudViolationAction

Action on a cloud secret violation. Twin of ViolationAction, with Passthrough’s host list normalized to a hosts field.

CloudVolumeMount

Cloud volume mount. Internal-tagged mirror of the domain VolumeMount; the transient create field is not carried on the wire.

CpuPlacement

Controls how Microsandbox places vCPU threads on host processors.

DeploymentProfile

Host-runtime isolation profile applied when a sandbox is deployed.

Destination

Traffic destination filter for a Rule.

DestinationGroup

Pre-defined destination category for a Destination::Group match.

Direction

Direction a Rule applies to.

DiskImageFormat

Disk image format for virtio-blk root filesystems and volume mounts.

FlatClone

Strategy used to create a sandbox-owned instance of a cached flat rootfs.

HostPattern

Host pattern for a secret allowlist.

HostPermissions

Host permission propagation policy for a virtiofs-backed volume mount.

LogSource

Source tag on a captured log entry.

MemoryPlacement

Host backing policy for guest memory selected by a named placement profile.

NamedVolumeMode

Sandbox-time behavior for a named volume mount.

NetworkRateLimitDirection

Sandbox-relative direction governed by a network rate limiter.

NumaPlacement

Concrete host NUMA scope selected by a named placement profile.

Patch

Rootfs patch applied before VM startup.

PortProtocol

Transport protocol for a published port.

Protocol

Protocol filter for a Rule.

PullPolicy

Controls when an OCI registry is contacted for manifest freshness.

RateLimitConfigError

Invalid rate limiter configuration.

RlimitResource

POSIX resource limit identifiers.

RootDisk

Backing for the writable rootfs layer (overlay upper) of an OCI sandbox.

RootfsSource

Root filesystem source for a sandbox.

SandboxLogLevel

Runtime log verbosity for sandbox specs.

SecretConfigError

Invalid secret configuration.

SecurityProfile

Sandbox-level in-guest security profile.

StatVirtualization

Stat virtualization policy for a virtiofs-backed volume mount.

TransparentHugePagePolicy

Guest transparent huge-page policy applied through the kernel command line.

TypesError

Errors returned by shared microsandbox contract helpers.

ViolationAction

Action when a secret placeholder is detected going to a disallowed host.

VolumeKind

Storage kind for a named volume.

VolumeMount

A volume mount specification for a sandbox.

VsockSocketType

Socket semantics for a host-CID vsock route.

Constants

DEFAULT_METRICS_SAMPLE_INTERVAL_MS

Default metrics sampling interval in milliseconds.

DEFAULT_SANDBOX_CPUS

Default number of virtual CPUs in a sandbox specification.

DEFAULT_SANDBOX_MEMORY_MIB

Default guest memory in MiB in a sandbox specification.

MAX_HOSTNAME_BYTES

Maximum UTF-8 byte length for a guest hostname (Linux __NEW_UTS_LEN).

MAX_SANDBOX_NAME_BYTES

Maximum UTF-8 byte length for a sandbox name.

MAX_SECRET_PLACEHOLDER_BYTES

Maximum supported secret placeholder length in bytes.

Functions

hostname_from_sandbox_name

Derive a guest hostname from a sandbox name while fitting within MAX_HOSTNAME_BYTES.

validate_hostname

Validate an optional explicit guest hostname before it is forwarded to the guest agent.

validate_sandbox_name

Validate that a sandbox name is safe: alphanumeric / dot / hyphen / underscore, 1..=128 bytes, and must start alphanumeric.

Type Aliases

TypesResult

The result type for shared microsandbox contract operations.