a3s-box-runtime 3.1.0

MicroVM runtime engine — VM lifecycle, OCI images, attestation, networking
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167

//! A3S Box Runtime - MicroVM runtime implementation.
//!
//! This module provides the actual runtime implementation for A3S Box,
//! including VM management, OCI image handling, rootfs building, and gRPC health checks.
//!
//! # Feature Flags
//!
//! - `pool` — Warm VM pool with autoscaling (enabled by default)
//! - `scale` — Multi-node scale manager and instance registry (enabled by default)
//! - `compose` — Multi-container compose orchestration (enabled by default)
//! - `operator` — Kubernetes CRD autoscaler controller (enabled by default)
//! - `build` — Dockerfile/Containerfile build engine (enabled by default)

#![allow(clippy::result_large_err)]

// -- Core modules (always compiled) --
#[cfg(all(feature = "vm", target_os = "linux"))]
pub mod a3s_runtime_driver;
pub mod audit;
pub mod box_record;
pub mod box_state;
pub mod cache;
pub(crate) mod file_lock;
pub mod fs;
pub mod grpc;
pub mod host_check;
pub mod local_execution;
pub mod log;
pub mod managed_execution_store;
pub mod network;
pub mod oci;
pub mod process;
pub mod prom;
pub mod resize;
mod resolved_image;
pub mod rootfs;
pub mod sandbox;
pub mod snapshot;
mod store_io;
#[cfg(unix)]
pub mod tee;
#[cfg(feature = "vm")]
pub mod vm;
#[cfg(feature = "vm")]
pub mod vmm;
pub mod volume;

// -- Optional modules (feature-gated) --
#[cfg(feature = "compose")]
pub mod compose;
#[cfg(feature = "operator")]
pub mod operator;
#[cfg(feature = "pool")]
pub mod pool;
#[cfg(feature = "scale")]
pub mod scale;

// ── Core re-exports (used by CLI, CRI, SDK, shim) ──

// Audit
pub use audit::{read_audit_log, AuditLog, AuditQuery};

#[cfg(all(feature = "vm", target_os = "linux"))]
pub use a3s_runtime_driver::{BoxRuntimeDriver, BoxRuntimeDriverConfig};

// Canonical local execution metadata
pub use box_record::{
    BoxRecord, HealthCheck, ManagedExecutionMetadata, ManagedExecutionOperation,
    ManagedExecutionState, ManagedRestartCompletion, ManagedRestartOutcome,
};
pub use box_state::BoxStateStore;
#[cfg(feature = "vm")]
pub use local_execution::VmLocalExecutionBackend;
pub use local_execution::{
    acquire_execution_lifecycle_lock, ExecutionLifecycleLock, LocalExecutionBackend,
    LocalExecutionHandle, LocalExecutionManager, LocalExecutionObservation,
};
pub use managed_execution_store::{
    ManagedExecutionReservation, ManagedExecutionStore, ManagedExecutionStoreError,
    ManagedExecutionStoreResult,
};
pub use process::{is_process_alive, is_process_alive_with_identity, pid_start_time};

// gRPC clients
#[cfg(unix)]
pub use grpc::{
    AttestationClient, ExecClient, PtyClient, RaTlsAttestationClient, StreamingExec,
    StreamingExecInput, StreamingPty, StreamingPtyInput,
};
#[cfg(unix)]
pub use grpc::{SealClient, SecretEntry, SecretInjector};

// Host checks
pub use host_check::check_virtualization_support;

// Network
pub use network::NetworkStore;

// OCI images
pub use a3s_box_core::StoredImage;
pub use oci::{CredentialStore, PushResult, RegistryProtocol, RegistryPusher};
pub use oci::{
    ImagePuller, ImageReference, ImageStore, PullProgress, PullProgressEventFn, PullProgressState,
    RegistryAuth, RegistryPullPolicy,
};
pub use oci::{OciImage, SignResult, SignaturePolicy};

// Metrics
pub use prom::RuntimeMetrics;

// Snapshot
pub use resolved_image::{load_resolved_image_config, RESOLVED_IMAGE_CONFIG_FILE};
pub use snapshot::SnapshotStore;

// TEE
#[cfg(unix)]
pub use tee::{seal, unseal};
#[cfg(unix)]
pub use tee::{
    verify_attestation, verify_attestation_with_time, AmdKdsClient, AttestationPolicy,
    MinTcbPolicy, PolicyResult, VerificationResult,
};
#[cfg(unix)]
pub use tee::{AttestationReport, AttestationRequest, PlatformInfo};

// VM
#[cfg(feature = "vm")]
pub use vm::{BoxState, PullProgressFn, VmManager};
#[cfg(feature = "vm")]
pub use vmm::{
    Entrypoint, FsMount, InstanceSpec, NetworkInstanceConfig, ShimHandler, TeeInstanceConfig,
    VmController, VmHandler, VmMetrics, VmmProvider,
};

// Resize
pub use resize::{validate_update, ResizeResult, ResourceUpdate};

// Volume
pub use volume::VolumeStore;

// ── Feature-gated re-exports ──

#[cfg(feature = "build")]
pub use oci::{BuildConfig, BuildRunPoolConfig, Dockerfile, Instruction};

#[cfg(feature = "compose")]
#[allow(deprecated)]
pub use compose::{ComposeProject, ComposeRuntimePlan, HealthCheckSpec};

#[cfg(feature = "operator")]
pub use operator::AutoscalerController;

#[cfg(feature = "pool")]
pub use pool::WarmPool;

#[cfg(feature = "scale")]
pub use scale::ScaleManager;

// ── Constants ──

/// A3S Box Runtime version.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

pub use a3s_box_core::{ATTEST_VSOCK_PORT, EXEC_VSOCK_PORT, PORT_FWD_VSOCK_PORT, PTY_VSOCK_PORT};

/// Default maximum image cache size: 10 GB.
pub const DEFAULT_IMAGE_CACHE_SIZE: u64 = 10 * 1024 * 1024 * 1024;