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, LocalExecutionTermination, OciBundlePreparationContext,
87    OciBundleProvider, OciLifecycleAdapter, OciLocalExecutionBackend, OciMigrationPolicy,
88    OciPreparedExecution, OciRuntimeBinding, OciRuntimeEndpoint, OciRuntimeLaunch,
89    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::{is_process_alive, is_process_alive_with_identity, pid_start_time};
101
102// gRPC clients
103#[cfg(unix)]
104pub use grpc::{
105    AttestationClient, PtyClient, RaTlsAttestationClient, StreamingPty, StreamingPtyInput,
106};
107pub use grpc::{ExecClient, StreamingExec, StreamingExecInput};
108#[cfg(unix)]
109pub use grpc::{SealClient, SecretEntry, SecretInjector};
110
111// Host checks
112pub use host_check::check_virtualization_support;
113
114// Network
115pub use network::NetworkStore;
116
117// OCI images
118pub use a3s_box_core::{ExecutionIsolation, StoredImage};
119pub use oci::{
120    prune_stale_pull_temp_dirs, ImagePuller, ImageReference, ImageStore, PullProgress,
121    PullProgressEventFn, PullProgressState, PullTempPruneResult, RegistryAuth, RegistryPullPolicy,
122};
123pub use oci::{CredentialStore, PushResult, RegistryProtocol, RegistryPusher};
124pub use oci::{OciImage, SignResult, SignaturePolicy};
125
126// Metrics
127pub use prom::RuntimeMetrics;
128
129// Snapshot
130pub use resolved_image::{load_resolved_image_config, RESOLVED_IMAGE_CONFIG_FILE};
131pub use snapshot::SnapshotStore;
132
133// TEE
134#[cfg(unix)]
135pub use tee::{seal, unseal};
136#[cfg(unix)]
137pub use tee::{
138    verify_attestation, verify_attestation_with_time, AmdKdsClient, AttestationPolicy,
139    MinTcbPolicy, PolicyResult, VerificationResult,
140};
141#[cfg(unix)]
142pub use tee::{AttestationReport, AttestationRequest, PlatformInfo};
143
144// VM
145#[cfg(feature = "vm")]
146pub use vm::{BoxState, PullProgressFn, VmManager};
147#[cfg(feature = "vm")]
148pub use vmm::{
149    Entrypoint, FsMount, InstanceSpec, NetworkInstanceConfig, ShimHandler, TeeInstanceConfig,
150    VmController, VmHandler, VmMetrics, VmmProvider,
151};
152
153// Resize
154pub use resize::{validate_update, ResizeResult, ResourceUpdate};
155
156// Volume
157pub use volume::VolumeStore;
158
159// ── Feature-gated re-exports ──
160
161#[cfg(feature = "build")]
162pub use oci::{
163    assemble_recorded_build_outputs, cancel_recorded_build_plan, execute_recorded_build_plan,
164    hydrate_recorded_build_cache, inspect_recorded_build_plan, inspect_recorded_build_status,
165    remove_recorded_build_plan, start_recorded_build_plan, BoxBuildOptions, BoxBuildPlan,
166    BoxBuildPlanError, BuildAssemblyError, BuildCachePolicy, BuildCacheReceipt,
167    BuildCancellationOutcome, BuildConfig, BuildNetworkPolicy, BuildOperationIdentity,
168    BuildOutputAssembly, BuildOutputAssemblyInput, BuildOutputDescriptor, BuildOutputReceipt,
169    BuildPlanExecutionError, BuildReceiptError, BuildReceiptOutput, BuildResult,
170    BuildRunPoolConfig, Dockerfile, Instruction, MultiPlatformBuildResult, RecordedBuildCache,
171    RecordedBuildResult, RecordedBuildStatus, BUILD_CACHE_ARTIFACT_MEDIA_TYPE,
172    BUILD_CACHE_CONFIG_MEDIA_TYPE, OCI_IMAGE_INDEX_MEDIA_TYPE, OCI_IMAGE_MANIFEST_MEDIA_TYPE,
173};
174
175#[cfg(feature = "compose")]
176#[allow(deprecated)]
177pub use compose::{ComposeProject, ComposeRuntimePlan, HealthCheckSpec};
178
179#[cfg(feature = "operator")]
180pub use operator::AutoscalerController;
181
182#[cfg(feature = "pool")]
183pub use pool::WarmPool;
184
185#[cfg(feature = "scale")]
186pub use scale::{
187    serve_scale_api, DurableScaleAuthority, LocalScaleReconciler, ScaleApiState,
188    ScaleAuthorityError, ScaleCatalogError, ScaleEndpointConfig, ScaleEndpointConfigError,
189    ScaleManager, ScaleReconcileError, ScaleReconcileObservation, ScaleReconcileReport,
190    ScaleServiceCatalog, SharedScaleAuthority,
191};
192
193// ── Constants ──
194
195/// A3S Box Runtime version.
196pub const VERSION: &str = env!("CARGO_PKG_VERSION");
197
198pub use a3s_box_core::{ATTEST_VSOCK_PORT, EXEC_VSOCK_PORT, PORT_FWD_VSOCK_PORT, PTY_VSOCK_PORT};
199
200/// Default maximum image cache size: 10 GB.
201pub const DEFAULT_IMAGE_CACHE_SIZE: u64 = 10 * 1024 * 1024 * 1024;
a3s_box_runtime/lib.rs

a3s_box_runtime/
lib.rs
