a3s_box_runtime/
lib.rs

1//! A3S Box Runtime - MicroVM runtime implementation.
2//!
3//! This module provides the actual runtime implementation for A3S Box,
4//! including VM management, OCI image handling, rootfs building, and gRPC health checks.
5//!
6//! # Feature Flags
7//!
8//! - `pool` — Warm VM pool with autoscaling (enabled by default)
9//! - `scale` — Multi-node scale manager and instance registry (enabled by default)
10//! - `compose` — Multi-container compose orchestration (enabled by default)
11//! - `operator` — Kubernetes CRD autoscaler controller (enabled by default)
12//! - `build` — Dockerfile/Containerfile build engine (enabled by default)
13//! - `runtime-provider-qualification` — Explicit downstream real-process
14//!   qualification seam for the Linux A3S Runtime provider (disabled by
15//!   default; never a production capability-probe fallback)
16
17#![allow(clippy::result_large_err)]
18
19// -- Core modules (always compiled) --
20#[cfg(all(feature = "vm", target_os = "linux"))]
21pub mod a3s_runtime_driver;
22pub mod audit;
23pub mod box_record;
24pub mod box_state;
25pub mod cache;
26pub(crate) mod file_lock;
27pub mod fs;
28pub mod grpc;
29pub mod host_check;
30pub mod local_execution;
31pub mod log;
32pub mod managed_execution_store;
33pub mod network;
34pub mod oci;
35pub mod process;
36mod process_path;
37pub mod prom;
38pub mod resize;
39mod resolved_image;
40pub mod rootfs;
41pub mod sandbox;
42pub mod snapshot;
43mod store_io;
44#[cfg(unix)]
45pub mod tee;
46#[cfg(feature = "vm")]
47pub mod vm;
48#[cfg(feature = "vm")]
49pub mod vmm;
50pub mod volume;
51
52// -- Optional modules (feature-gated) --
53#[cfg(feature = "compose")]
54pub mod compose;
55#[cfg(feature = "operator")]
56pub mod operator;
57#[cfg(feature = "pool")]
58pub mod pool;
59#[cfg(feature = "scale")]
60pub mod scale;
61
62// ── Core re-exports (used by CLI, CRI, SDK, shim) ──
63
64// Audit
65pub use audit::{read_audit_log, AuditLog, AuditQuery};
66
67#[cfg(all(feature = "vm", target_os = "linux"))]
68pub use a3s_runtime_driver::{
69    BoxArtifactPort, BoxArtifactPortError, BoxRegistryCredential, BoxRuntimeDriver,
70    BoxRuntimeDriverConfig, BoxRuntimeSevSnpConfig, BoxSecretEnvironmentProjection,
71    BoxSecretMaterial, BoxSecretMaterializationError, BoxSecretMaterializer,
72    BoxTransientSecretStore,
73};
74
75// Canonical local execution metadata
76pub use a3s_oci_sdk::{IO_READ_BYTES_METRIC, IO_WRITE_BYTES_METRIC};
77pub use box_record::{
78    BoxRecord, HealthCheck, ManagedExecutionMetadata, ManagedExecutionOperation,
79    ManagedExecutionState, ManagedResourceUpdateCompletion, ManagedRestartCompletion,
80    ManagedRestartOutcome, ManagedRuntimeRoute,
81};
82pub use box_state::BoxStateStore;
83pub use local_execution::{
84    acquire_execution_lifecycle_lock, ExecutionLifecycleLock, LocalExecutionBackend,
85    LocalExecutionBackendRouter, LocalExecutionHandle, LocalExecutionManager,
86    LocalExecutionObservation, LocalExecutionResourcePlan, LocalExecutionTermination,
87    OciBundlePreparationContext, OciBundleProvider, OciLifecycleAdapter, OciLocalExecutionBackend,
88    OciMigrationPolicy, OciPreparedExecution, OciRuntimeBinding, OciRuntimeEndpoint,
89    OciRuntimeLaunch, OCI_RUNTIME_BINDING_SCHEMA_VERSION,
90};
91#[cfg(feature = "vm")]
92pub use local_execution::{
93    NativeLinuxOciBundleProvider, NativeLinuxOciMigrationConfig, VmLocalExecutionBackend,
94    WindowsWhpxOciBundleProvider, WindowsWhpxOciMigrationConfig,
95};
96pub use managed_execution_store::{
97    ManagedExecutionReservation, ManagedExecutionStore, ManagedExecutionStoreError,
98    ManagedExecutionStoreResult,
99};
100pub use process::{
101    is_process_alive, is_process_alive_with_identity, is_process_running_with_identity,
102    pid_start_time,
103};
104
105// gRPC clients
106#[cfg(unix)]
107pub use grpc::{
108    AttestationClient, PtyClient, RaTlsAttestationClient, StreamingPty, StreamingPtyInput,
109};
110pub use grpc::{ExecClient, StreamingExec, StreamingExecInput};
111#[cfg(unix)]
112pub use grpc::{SealClient, SecretEntry, SecretInjector};
113
114// Host checks
115pub use host_check::check_virtualization_support;
116
117// Network
118pub use network::NetworkStore;
119
120// OCI images
121pub use a3s_box_core::{ExecutionIsolation, StoredImage};
122pub use oci::{
123    prune_stale_pull_temp_dirs, ImagePuller, ImageReference, ImageStore, PullProgress,
124    PullProgressEventFn, PullProgressState, PullTempPruneResult, RegistryAuth, RegistryPullPolicy,
125};
126pub use oci::{CredentialStore, PushResult, RegistryProtocol, RegistryPusher};
127pub use oci::{OciImage, SignResult, SignaturePolicy};
128
129// Metrics
130pub use prom::RuntimeMetrics;
131
132// Snapshot
133pub use resolved_image::{load_resolved_image_config, RESOLVED_IMAGE_CONFIG_FILE};
134pub use snapshot::{
135    RestoredSnapshotRootfs, SnapshotRootfsFormat, SnapshotStore, SNAPSHOT_ROOTFS_SCHEMA,
136};
137
138// TEE
139#[cfg(unix)]
140pub use tee::{seal, unseal};
141#[cfg(unix)]
142pub use tee::{
143    verify_attestation, verify_attestation_with_time, AmdKdsClient, AttestationPolicy,
144    MinTcbPolicy, PolicyResult, VerificationResult,
145};
146#[cfg(unix)]
147pub use tee::{AttestationReport, AttestationRequest, PlatformInfo};
148
149// VM
150#[cfg(feature = "vm")]
151pub use vm::{archive_stopped_guest_native_rootfs, BoxState, PullProgressFn, VmManager};
152#[cfg(feature = "vm")]
153pub use vmm::{
154    Entrypoint, FsMount, InstanceSpec, NetworkInstanceConfig, RawBlockDevice, ShimHandler,
155    TeeInstanceConfig, VmController, VmHandler, VmMetrics, VmmProvider,
156};
157
158// Resize
159pub use resize::{validate_update, ResizeResult, ResourceUpdate};
160
161// Volume
162pub use volume::VolumeStore;
163
164// ── Feature-gated re-exports ──
165
166#[cfg(feature = "build")]
167pub use oci::{
168    assemble_recorded_build_outputs, cancel_recorded_build_plan, execute_recorded_build_plan,
169    hydrate_recorded_build_cache, inspect_recorded_build_plan, inspect_recorded_build_status,
170    remove_recorded_build_plan, start_recorded_build_plan, BoxBuildOptions, BoxBuildPlan,
171    BoxBuildPlanError, BuildAssemblyError, BuildCachePolicy, BuildCacheReceipt,
172    BuildCancellationOutcome, BuildConfig, BuildNetworkPolicy, BuildOperationIdentity,
173    BuildOutputAssembly, BuildOutputAssemblyInput, BuildOutputDescriptor, BuildOutputReceipt,
174    BuildPlanExecutionError, BuildReceiptError, BuildReceiptOutput, BuildResult,
175    BuildRunPoolConfig, Dockerfile, Instruction, MultiPlatformBuildResult, RecordedBuildCache,
176    RecordedBuildResult, RecordedBuildStatus, BUILD_CACHE_ARTIFACT_MEDIA_TYPE,
177    BUILD_CACHE_CONFIG_MEDIA_TYPE, OCI_IMAGE_INDEX_MEDIA_TYPE, OCI_IMAGE_MANIFEST_MEDIA_TYPE,
178};
179
180#[cfg(feature = "compose")]
181#[allow(deprecated)]
182pub use compose::{ComposeProject, ComposeRuntimePlan, HealthCheckSpec};
183
184#[cfg(feature = "operator")]
185pub use operator::AutoscalerController;
186
187#[cfg(feature = "pool")]
188pub use pool::WarmPool;
189
190#[cfg(feature = "scale")]
191pub use scale::{
192    serve_scale_api, DurableScaleAuthority, LocalScaleReconciler, ScaleApiState,
193    ScaleAuthorityError, ScaleCatalogError, ScaleEndpointConfig, ScaleEndpointConfigError,
194    ScaleManager, ScaleReconcileError, ScaleReconcileObservation, ScaleReconcileReport,
195    ScaleServiceCatalog, SharedScaleAuthority,
196};
197
198// ── Constants ──
199
200/// A3S Box Runtime version.
201pub const VERSION: &str = env!("CARGO_PKG_VERSION");
202
203pub use a3s_box_core::{ATTEST_VSOCK_PORT, EXEC_VSOCK_PORT, PORT_FWD_VSOCK_PORT, PTY_VSOCK_PORT};
204
205/// Default maximum image cache size: 10 GB.
206pub const DEFAULT_IMAGE_CACHE_SIZE: u64 = 10 * 1024 * 1024 * 1024;
a3s_box_runtime/lib.rs

a3s_box_runtime/
lib.rs
