a3s_box_core/
lib.rs

1//! A3S Box Core - Foundational Types and Abstractions
2//!
3//! This module provides the foundational types, traits, and abstractions
4//! used across the A3S Box MicroVM runtime.
5
6pub mod audit;
7pub mod compose;
8pub mod config;
9pub mod dns;
10pub mod env;
11pub mod error;
12pub mod event;
13pub mod exec;
14pub mod execution;
15pub mod fs_atomic;
16pub mod guest_exec;
17pub mod lifecycle_profile;
18pub mod log;
19pub mod network;
20pub mod operator;
21pub mod platform;
22pub mod port;
23pub mod pty;
24pub mod rootfs_baseline;
25pub mod rootfs_metadata;
26pub mod scale;
27pub mod secret;
28pub mod security;
29pub mod snapshot;
30pub mod tee;
31pub mod traits;
32pub mod vmm;
33pub mod volume;
34#[cfg(windows)]
35pub mod windows_file;
36#[cfg(windows)]
37pub mod windows_symlink;
38
39// Re-export commonly used types
40pub use audit::{AuditAction, AuditConfig, AuditEvent, AuditOutcome};
41pub use compose::ComposeConfig;
42pub use config::{BoxConfig, ExecutionIsolation, ResourceConfig, ResourceLimits};
43pub use error::{BoxError, Result};
44pub use event::{BoxEvent, EventEmitter};
45pub use exec::{ExecChunk, ExecEvent, ExecExit, ExecMetrics, StreamType};
46pub use exec::{ExecOutput, ExecRequest};
47pub use exec::{
48    FileOp, FileRequest, FileResponse, FilesystemEntry, FilesystemEntryKind, FilesystemOp,
49    FilesystemRequest, FilesystemResponse, GuestSessionRequest, MAX_BOUNDED_FILE_BYTES,
50};
51pub use exec::{EXEC_VSOCK_PORT, PORT_FWD_VSOCK_PORT};
52pub use execution::{
53    resolve_execution, validate_microvm_compatibility, validate_sandbox_compatibility,
54    ExecutionBackend, IsolationClass, ResolvedExecutionPlan,
55};
56pub use network::{IsolationMode, NetworkConfig, NetworkEndpoint, NetworkMode, NetworkPolicy};
57pub use operator::{BoxAutoscaler, BoxAutoscalerSpec, BoxAutoscalerStatus, MetricType};
58pub use platform::{
59    BridgeNetworkBackend, HostGuestChannel, Platform, PlatformCapabilities, VmBackend,
60};
61pub use port::{normalize_port_maps, parse_port_mapping, PortMapping, PortProtocol};
62pub use pty::PTY_VSOCK_PORT;
63pub use scale::{
64    InstanceDeregistration, InstanceEvent, InstanceHealth, InstanceInfo, InstanceRegistration,
65    InstanceState, ScaleConfig, ScaleDirection, ScaleObservation, ScaleOperationConflict,
66    ScaleOperationRequest, ScaleOperationResponse, ScaleRequest, ScaleResponse,
67    SCALE_OPERATION_SCHEMA_VERSION,
68};
69pub use security::{SeccompMode, SecurityConfig};
70pub use snapshot::{
71    SnapshotConfig, SnapshotImageConfig, SnapshotImageHealthCheck, SnapshotMetadata,
72};
73pub use tee::ATTEST_VSOCK_PORT;
74pub use tee::{detect_tee, is_tee_available, TeeCapability, TeeType};
75pub use traits::{
76    AuditSink, CacheBackend, CacheEntry, CacheStats, CreateExecutionRequest, CredentialProvider,
77    EventBus, ExecutionCpuStats, ExecutionEventBatch, ExecutionEventKind, ExecutionEventsRequest,
78    ExecutionGeneration, ExecutionHealthCheck, ExecutionId, ExecutionLease, ExecutionManager,
79    ExecutionManagerError, ExecutionManagerResult, ExecutionMemoryStats, ExecutionPortConnector,
80    ExecutionPortIo, ExecutionPortStream, ExecutionProcess, ExecutionProcessInfo,
81    ExecutionProcessInput, ExecutionProcessInventory, ExecutionProcessSignal,
82    ExecutionProcessStream, ExecutionRecordPolicy, ExecutionReservation, ExecutionResourceUpdate,
83    ExecutionRestartPolicy, ExecutionRuntimeEvent, ExecutionSessionManager, ExecutionSnapshot,
84    ExecutionSnapshotId, ExecutionState, ExecutionStats, ExecutionStatus, ImageRegistry,
85    ImageStoreBackend, KillExecutionOptions, KillOutcome, MetricsCollector, NetworkStoreBackend,
86    NoopMetrics, OperationId, PulledImage, ReconcileOutcome, RestartExecutionOptions,
87    SnapshotStoreBackend, StoredImage, VolumeStoreBackend, MAX_EXECUTION_EVENT_BATCH_ITEMS,
88};
89pub use vmm::{
90    Entrypoint, FsMount, InstanceSpec, NetworkInstanceConfig, RawBlockDevice, TeeInstanceConfig,
91    VmHandler, VmMetrics, VmmProvider, DEFAULT_SHUTDOWN_TIMEOUT_MS,
92};
93pub use volume::VolumeConfig;
94
95/// A3S Box version
96pub const VERSION: &str = env!("CARGO_PKG_VERSION");
97
98/// Get the A3S home directory.
99///
100/// Resolution order:
101/// 1. `A3S_HOME` environment variable (if set)
102/// 2. `~/.a3s` (via `dirs::home_dir()`)
103/// 3. Fallback to `.a3s` in the current directory
104pub fn dirs_home() -> std::path::PathBuf {
105    if let Ok(home) = std::env::var("A3S_HOME") {
106        return std::path::PathBuf::from(home);
107    }
108    dirs::home_dir()
109        .map(|h| h.join(".a3s"))
110        .unwrap_or_else(|| std::path::PathBuf::from(".a3s"))
111}
112
113#[cfg(test)]
114mod tests {
115    use super::*;
116    use std::sync::Mutex;
117
118    static ENV_LOCK: Mutex<()> = Mutex::new(());
119
120    #[test]
121    fn dirs_home_prefers_a3s_home_environment_variable() {
122        let _guard = ENV_LOCK.lock().unwrap();
123        let previous = std::env::var_os("A3S_HOME");
124        let tmp = tempfile::tempdir().unwrap();
125
126        std::env::set_var("A3S_HOME", tmp.path());
127        assert_eq!(dirs_home(), tmp.path());
128
129        match previous {
130            Some(value) => std::env::set_var("A3S_HOME", value),
131            None => std::env::remove_var("A3S_HOME"),
132        }
133    }
134
135    #[test]
136    fn dirs_home_defaults_to_dot_a3s_under_user_home_when_env_absent() {
137        let _guard = ENV_LOCK.lock().unwrap();
138        let previous = std::env::var_os("A3S_HOME");
139
140        std::env::remove_var("A3S_HOME");
141        let home = dirs_home();
142
143        assert!(home.ends_with(".a3s"));
144        if let Some(user_home) = dirs::home_dir() {
145            assert_eq!(home, user_home.join(".a3s"));
146        }
147
148        match previous {
149            Some(value) => std::env::set_var("A3S_HOME", value),
150            None => std::env::remove_var("A3S_HOME"),
151        }
152    }
153}
a3s_box_core/lib.rs

a3s_box_core/
lib.rs
