use std::fs::{self, File};
use std::io::Write as _;
use std::path::{Component, Path, PathBuf};
use std::sync::{Mutex, OnceLock};
use objc2::AllocAnyThread;
use objc2::rc::Retained;
use objc2_foundation::{NSArray, NSData, NSFileHandle, NSString, NSURL};
use objc2_virtualization::{
VZDirectorySharingDeviceConfiguration, VZDiskImageCachingMode,
VZDiskImageStorageDeviceAttachment, VZDiskImageSynchronizationMode,
VZEntropyDeviceConfiguration, VZFileHandleSerialPortAttachment, VZGenericMachineIdentifier,
VZGenericPlatformConfiguration, VZLinuxBootLoader, VZMemoryBalloonDeviceConfiguration,
VZNATNetworkDeviceAttachment, VZNetworkDeviceAttachment, VZNetworkDeviceConfiguration,
VZSerialPortConfiguration, VZSharedDirectory, VZSingleDirectoryShare,
VZSocketDeviceConfiguration, VZStorageDeviceConfiguration, VZVirtioBlockDeviceConfiguration,
VZVirtioConsoleDeviceSerialPortConfiguration, VZVirtioEntropyDeviceConfiguration,
VZVirtioFileSystemDeviceConfiguration, VZVirtioNetworkDeviceConfiguration,
VZVirtioSocketDeviceConfiguration, VZVirtioTraditionalMemoryBalloonDeviceConfiguration,
VZVirtualMachineConfiguration,
};
use serde::Deserialize;
use crate::model::{ExecutionExport, ExecutionStartInput, IsolationStatus, ProviderError};
use super::snapshot::{
SnapshotFiles, compatibility_fingerprint, current_host_build, snapshot_available,
};
const DEFAULT_TIMEOUT_MS: i64 = 60_000;
const DEFAULT_PIDS_MAX: i64 = 512;
const WORKSPACE_SHARE_TAG: &str = "apoc-executor-share";
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GuestRequest {
pub request_id: String,
pub argv: Vec<String>,
pub cwd: String,
pub env: std::collections::BTreeMap<String, String>,
pub workspace: Option<String>,
pub exports: Vec<ExecutionExport>,
pub tty: bool,
pub timeout_ms: i64,
pub memory_mb: i64,
pub pids_max: i64,
}
#[derive(Debug, Clone)]
pub struct ResolvedLaunch {
pub image_digest: String,
pub cpu_count: u64,
pub memory_mb: u64,
pub guest_agent_port: u32,
pub guest_connect_timeout_ms: u64,
pub kernel_command_line: String,
pub kernel: PathBuf,
pub initrd: Option<PathBuf>,
pub disk: PathBuf,
pub network: bool,
pub workspace: Option<PathBuf>,
pub snapshot_files: Option<SnapshotFiles>,
pub snapshot_restore: bool,
pub guest: GuestRequest,
}
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct VmConfigKey {
cpu_count: u64,
memory_mb: u64,
guest_agent_port: u32,
kernel_command_line: String,
kernel: PathBuf,
initrd: Option<PathBuf>,
disk: PathBuf,
network: bool,
workspace: Option<PathBuf>,
machine_identifier: Option<PathBuf>,
}
#[derive(Deserialize)]
struct DerivedBundleConfig {
resources: DerivedBundleResources,
}
#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct DerivedBundleResources {
machine_identifier: Option<String>,
machine_state: Option<String>,
}
impl ResolvedLaunch {
pub fn key(&self) -> VmConfigKey {
VmConfigKey {
cpu_count: self.cpu_count,
memory_mb: self.memory_mb,
guest_agent_port: self.guest_agent_port,
kernel_command_line: self.kernel_command_line.clone(),
kernel: self.kernel.clone(),
initrd: self.initrd.clone(),
disk: self.disk.clone(),
network: self.network,
workspace: self.workspace.clone(),
machine_identifier: self
.snapshot_files
.as_ref()
.map(|files| files.machine_identifier.clone()),
}
}
pub fn set_snapshot_restore(&mut self, enabled: bool) {
self.snapshot_restore = enabled;
}
pub fn snapshot_eligible(&self) -> bool {
self.snapshot_restore
&& self.snapshot_files.is_some()
&& self.workspace.is_none()
&& !self.network
}
pub fn snapshot_fingerprint(
&self,
create_machine_identifier: bool,
) -> Result<Option<String>, ProviderError> {
let Some(files) = &self.snapshot_files else {
return Ok(None);
};
let Some(machine_identifier) =
machine_identifier_bytes(&files.machine_identifier, create_machine_identifier)?
else {
return Ok(None);
};
Ok(Some(compatibility_fingerprint(
&self.image_digest,
self.cpu_count,
self.memory_mb,
self.guest_agent_port,
&self.kernel_command_line,
&machine_identifier,
¤t_host_build(),
)))
}
pub fn snapshot_available(&self) -> Result<bool, ProviderError> {
let Some(files) = &self.snapshot_files else {
return Ok(false);
};
let Some(fingerprint) = self.snapshot_fingerprint(false)? else {
return Ok(false);
};
Ok(snapshot_available(files, &fingerprint))
}
pub fn status(
reference: &str,
snapshot_restore_enabled: bool,
) -> Result<IsolationStatus, ProviderError> {
let report = verified_report(reference)?;
let bundle_path = PathBuf::from(&report.bundle_path);
let image_digest = report
.image_digest
.clone()
.ok_or_else(|| ProviderError::new("IMAGE_INVALID", "Verified image has no digest"))?;
let config = report.config.ok_or_else(|| {
ProviderError::new(
"IMAGE_INVALID",
"Verified image has no immutable configuration",
)
})?;
let snapshot_files = derived_snapshot_files(&bundle_path)?;
let available = snapshot_files
.as_ref()
.and_then(|files| {
fs::read(&files.machine_identifier)
.ok()
.map(|bytes| (files, bytes))
})
.is_some_and(|(files, machine_identifier)| {
let fingerprint = compatibility_fingerprint(
&image_digest,
u64::try_from(config.cpu_count).unwrap_or(0),
u64::try_from(config.memory_mb).unwrap_or(0),
config.guest_agent_port,
&config.kernel_command_line,
&machine_identifier,
¤t_host_build(),
);
snapshot_available(files, &fingerprint)
});
Ok(IsolationStatus {
provider_version: env!("CARGO_PKG_VERSION").to_string(),
initialized: true,
configured_image_path: std::env::var("APOC_EXECUTOR_VM_BUNDLE").ok(),
image_path: Some(report.bundle_path),
image_digest: Some(image_digest),
cpu_count: u64::try_from(config.cpu_count).ok(),
memory_mb: u64::try_from(config.memory_mb).ok(),
snapshot_restore_enabled: Some(snapshot_restore_enabled),
snapshot_available: Some(available),
idle_drain_seconds: None,
pool: None,
drained: None,
})
}
pub fn resolve(
request: &ExecutionStartInput,
configured_bundle: Option<&str>,
) -> Result<Self, ProviderError> {
if request.protocol_version != 1 {
return Err(ProviderError::new(
"PROTOCOL_VERSION_UNSUPPORTED",
format!("Unsupported protocol version {}", request.protocol_version),
));
}
let reference = request
.image_ref
.as_deref()
.or(request.vm_bundle.as_deref())
.or(configured_bundle)
.unwrap_or("local");
let report = verified_report(reference)?;
let bundle_path = PathBuf::from(&report.bundle_path);
let image_digest = report
.image_digest
.clone()
.ok_or_else(|| ProviderError::new("IMAGE_INVALID", "Verified image has no digest"))?;
let config = report.config.ok_or_else(|| {
ProviderError::new(
"IMAGE_INVALID",
"Verified image has no immutable configuration",
)
})?;
let cpu_count = request
.cpu_count
.unwrap_or_else(|| u64::try_from(config.cpu_count).unwrap_or(0));
let memory_mb = request
.memory_mb
.unwrap_or_else(|| u64::try_from(config.memory_mb).unwrap_or(0));
if cpu_count == 0 || memory_mb == 0 {
return Err(ProviderError::new(
"INVALID_OPTIONS",
"cpu_count and memory_mb must be positive",
));
}
let argv = if request.shell {
if request.argv.len() != 1 {
return Err(ProviderError::new(
"INVALID_COMMAND",
"Shell execution requires exactly one source argument",
));
}
vec![
"/bin/sh".to_string(),
"-lc".to_string(),
request.argv[0].clone(),
]
} else {
if request.argv.is_empty() {
return Err(ProviderError::new(
"INVALID_COMMAND",
"Execution argv must not be empty",
));
}
request.argv.clone()
};
let snapshot_files = derived_snapshot_files(&bundle_path)?;
let network = match request.network.as_deref().unwrap_or("none") {
"none" => false,
"nat" => true,
other => {
return Err(ProviderError::new(
"INVALID_OPTIONS",
format!("Unsupported network policy {other}"),
));
}
};
let workspace = request.workspace.as_deref().map(PathBuf::from);
let cwd = request
.cwd
.clone()
.unwrap_or_else(|| "/workspace".to_string());
let timeout_ms = request
.timeout_ms
.and_then(|value| i64::try_from(value).ok())
.unwrap_or(DEFAULT_TIMEOUT_MS);
let pids_max = request.pids_max.unwrap_or(DEFAULT_PIDS_MAX);
if timeout_ms <= 0 || pids_max <= 0 {
return Err(ProviderError::new(
"INVALID_OPTIONS",
"timeout_ms and pids_max must be positive",
));
}
let initrd = config
.resources
.initrd
.as_deref()
.map(|path| bundle_path.join(path));
Ok(Self {
image_digest,
kernel: bundle_path.join(&config.resources.kernel),
initrd,
disk: bundle_path.join(&config.resources.disk),
guest_agent_port: config.guest_agent_port,
guest_connect_timeout_ms: u64::try_from(config.guest_connect_timeout_ms).map_err(
|_| ProviderError::new("IMAGE_INVALID", "Guest connection timeout is invalid"),
)?,
kernel_command_line: config.kernel_command_line,
cpu_count,
memory_mb,
network,
workspace,
snapshot_files,
snapshot_restore: false,
guest: GuestRequest {
request_id: request.request_id.clone(),
argv,
cwd,
env: parse_environment(&request.env)?,
workspace: request.workspace.as_ref().map(|_| "/workspace".to_string()),
exports: request.exports.clone(),
tty: request.tty,
timeout_ms,
memory_mb: i64::try_from(memory_mb).map_err(|_| {
ProviderError::new("INVALID_OPTIONS", "memory_mb is outside i64")
})?,
pids_max,
},
})
}
pub fn build_configuration(
&self,
) -> Result<Retained<VZVirtualMachineConfiguration>, ProviderError> {
unsafe {
let cfg = VZVirtualMachineConfiguration::new();
let boot = VZLinuxBootLoader::initWithKernelURL(
VZLinuxBootLoader::alloc(),
&file_url(&self.kernel),
);
boot.setInitialRamdiskURL(self.initrd.as_deref().map(file_url).as_deref());
boot.setCommandLine(&nsstr(&self.kernel_command_line));
cfg.setBootLoader(Some(&boot.into_super()));
cfg.setCPUCount(usize::try_from(self.cpu_count).map_err(|_| {
ProviderError::new("INVALID_OPTIONS", "cpu_count is outside usize")
})?);
cfg.setMemorySize(self.memory_mb.checked_mul(1024 * 1024).ok_or_else(|| {
ProviderError::new("INVALID_OPTIONS", "memory_mb overflows bytes")
})?);
if let Some(files) = &self.snapshot_files {
let bytes = machine_identifier_bytes(&files.machine_identifier, true)?.ok_or_else(
|| {
ProviderError::new(
"MACHINE_IDENTIFIER_INVALID",
"Machine identifier was not created",
)
},
)?;
let data = NSData::with_bytes(&bytes);
let identifier = VZGenericMachineIdentifier::initWithDataRepresentation(
VZGenericMachineIdentifier::alloc(),
&data,
)
.ok_or_else(|| {
ProviderError::new(
"MACHINE_IDENTIFIER_INVALID",
"Persisted machine identifier is invalid",
)
})?;
let platform = VZGenericPlatformConfiguration::new();
platform.setMachineIdentifier(&identifier);
cfg.setPlatform(&platform.into_super());
}
let null_fd = libc::open(c"/dev/null".as_ptr(), libc::O_RDWR | libc::O_CLOEXEC);
if null_fd < 0 {
return Err(ProviderError::new(
"VZ_CONFIGURATION_INVALID",
format!("Cannot open /dev/null: {}", std::io::Error::last_os_error()),
));
}
let null_handle = NSFileHandle::initWithFileDescriptor_closeOnDealloc(
NSFileHandle::alloc(),
null_fd,
true,
);
let serial = VZVirtioConsoleDeviceSerialPortConfiguration::new();
let attachment =
VZFileHandleSerialPortAttachment::initWithFileHandleForReading_fileHandleForWriting(
VZFileHandleSerialPortAttachment::alloc(),
Some(&null_handle),
Some(&null_handle),
);
serial.setAttachment(Some(&attachment.into_super()));
let serial_ports: Retained<NSArray<VZSerialPortConfiguration>> =
NSArray::from_retained_slice(&[serial.into_super()]);
cfg.setSerialPorts(&serial_ports);
let disk_attachment = VZDiskImageStorageDeviceAttachment::initWithURL_readOnly_cachingMode_synchronizationMode_error(
VZDiskImageStorageDeviceAttachment::alloc(),
&file_url(&self.disk),
true,
VZDiskImageCachingMode::Cached,
VZDiskImageSynchronizationMode::Full,
)
.map_err(|error| {
ProviderError::new(
"IMAGE_INVALID",
format!("Cannot attach root disk: {}", error.localizedDescription()),
)
})?;
let disk = VZVirtioBlockDeviceConfiguration::initWithAttachment(
VZVirtioBlockDeviceConfiguration::alloc(),
&disk_attachment.into_super(),
);
let storage: Retained<NSArray<VZStorageDeviceConfiguration>> =
NSArray::from_retained_slice(&[disk.into_super()]);
cfg.setStorageDevices(&storage);
let entropy = VZVirtioEntropyDeviceConfiguration::new();
let entropy_devices: Retained<NSArray<VZEntropyDeviceConfiguration>> =
NSArray::from_retained_slice(&[entropy.into_super()]);
cfg.setEntropyDevices(&entropy_devices);
let balloon = VZVirtioTraditionalMemoryBalloonDeviceConfiguration::new();
let balloon_devices: Retained<NSArray<VZMemoryBalloonDeviceConfiguration>> =
NSArray::from_retained_slice(&[balloon.into_super()]);
cfg.setMemoryBalloonDevices(&balloon_devices);
let socket = VZVirtioSocketDeviceConfiguration::new();
let socket_devices: Retained<NSArray<VZSocketDeviceConfiguration>> =
NSArray::from_retained_slice(&[socket.into_super()]);
cfg.setSocketDevices(&socket_devices);
if let Some(workspace) = &self.workspace {
if !workspace.is_dir() {
return Err(ProviderError::new(
"INVALID_OPTIONS",
format!("Workspace is not a directory: {}", workspace.display()),
));
}
let directory = VZSharedDirectory::initWithURL_readOnly(
VZSharedDirectory::alloc(),
&file_url(workspace),
true,
);
let share = VZSingleDirectoryShare::initWithDirectory(
VZSingleDirectoryShare::alloc(),
&directory,
);
let device = VZVirtioFileSystemDeviceConfiguration::initWithTag(
VZVirtioFileSystemDeviceConfiguration::alloc(),
&nsstr(WORKSPACE_SHARE_TAG),
);
device.setShare(Some(&share.into_super()));
let devices: Retained<NSArray<VZDirectorySharingDeviceConfiguration>> =
NSArray::from_retained_slice(&[device.into_super()]);
cfg.setDirectorySharingDevices(&devices);
}
if self.network {
let network = VZVirtioNetworkDeviceConfiguration::new();
let attachment: Retained<VZNetworkDeviceAttachment> =
VZNATNetworkDeviceAttachment::new().into_super();
network.setAttachment(Some(&attachment));
let devices: Retained<NSArray<VZNetworkDeviceConfiguration>> =
NSArray::from_retained_slice(&[network.into_super()]);
cfg.setNetworkDevices(&devices);
}
cfg.validateWithError().map_err(|error| {
ProviderError::new(
"VZ_CONFIGURATION_INVALID",
error.localizedDescription().to_string(),
)
})?;
Ok(cfg)
}
}
}
fn derived_snapshot_files(bundle_path: &Path) -> Result<Option<SnapshotFiles>, ProviderError> {
let encoded = fs::read(bundle_path.join("config.json")).map_err(|error| {
ProviderError::new(
"IMAGE_INVALID",
format!("Cannot read derived bundle resources: {error}"),
)
})?;
let config = serde_json::from_slice::<DerivedBundleConfig>(&encoded).map_err(|error| {
ProviderError::new(
"IMAGE_INVALID",
format!("Cannot decode derived bundle resources: {error}"),
)
})?;
match (
config.resources.machine_identifier.as_deref(),
config.resources.machine_state.as_deref(),
) {
(None, None) => Ok(None),
(Some(identifier), Some(state)) => Ok(Some(SnapshotFiles {
machine_identifier: derived_bundle_path(bundle_path, identifier)?,
machine_state: derived_bundle_path(bundle_path, state)?,
metadata: bundle_path.join("warmup-digest.json"),
})),
_ => Err(ProviderError::new(
"IMAGE_INVALID",
"Snapshot resources require both machineIdentifier and machineState",
)),
}
}
fn derived_bundle_path(bundle_path: &Path, relative: &str) -> Result<PathBuf, ProviderError> {
let path = Path::new(relative);
if relative.is_empty()
|| path
.components()
.any(|component| !matches!(component, Component::Normal(_)))
{
return Err(ProviderError::new(
"IMAGE_INVALID",
format!("Derived bundle path must be normalized and relative: {relative}"),
));
}
Ok(bundle_path.join(path))
}
fn machine_identifier_bytes(path: &Path, create: bool) -> Result<Option<Vec<u8>>, ProviderError> {
static MACHINE_IDENTIFIER_LOCK: OnceLock<Mutex<()>> = OnceLock::new();
let _guard = MACHINE_IDENTIFIER_LOCK
.get_or_init(|| Mutex::new(()))
.lock()
.map_err(|_| {
ProviderError::new(
"MACHINE_IDENTIFIER_INVALID",
"Machine identifier lock is poisoned",
)
})?;
match fs::read(path) {
Ok(bytes) => {
validate_machine_identifier(&bytes)?;
return Ok(Some(bytes));
}
Err(error) if error.kind() == std::io::ErrorKind::NotFound && !create => return Ok(None),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
Err(error) => {
return Err(ProviderError::new(
"MACHINE_IDENTIFIER_INVALID",
format!("Cannot read machine identifier: {error}"),
));
}
}
let identifier = unsafe { VZGenericMachineIdentifier::new() };
let bytes = unsafe { identifier.dataRepresentation() }.to_vec();
let temporary = path.with_extension(format!("tmp-{}", uuid::Uuid::now_v7()));
let mut output = File::create(&temporary).map_err(|error| {
ProviderError::new(
"MACHINE_IDENTIFIER_INVALID",
format!("Cannot stage machine identifier: {error}"),
)
})?;
output.write_all(&bytes).map_err(|error| {
ProviderError::new(
"MACHINE_IDENTIFIER_INVALID",
format!("Cannot write machine identifier: {error}"),
)
})?;
output.sync_all().map_err(|error| {
ProviderError::new(
"MACHINE_IDENTIFIER_INVALID",
format!("Cannot sync machine identifier: {error}"),
)
})?;
drop(output);
if let Err(error) = fs::rename(&temporary, path) {
let _ = fs::remove_file(&temporary);
return Err(ProviderError::new(
"MACHINE_IDENTIFIER_INVALID",
format!("Cannot publish machine identifier: {error}"),
));
}
Ok(Some(bytes))
}
fn validate_machine_identifier(bytes: &[u8]) -> Result<(), ProviderError> {
let data = NSData::with_bytes(bytes);
if unsafe {
VZGenericMachineIdentifier::initWithDataRepresentation(
VZGenericMachineIdentifier::alloc(),
&data,
)
}
.is_none()
{
return Err(ProviderError::new(
"MACHINE_IDENTIFIER_INVALID",
"Persisted machine identifier is invalid",
));
}
Ok(())
}
fn verified_report(reference: &str) -> Result<apoc::image::VerificationReport, ProviderError> {
let report = apoc::image::verify_reference_cached(reference)
.map_err(|error| ProviderError::new("IMAGE_INVALID", error))?;
if report.status != apoc::image::VerificationStatus::Verified {
return Err(ProviderError::new(
"IMAGE_INVALID",
report
.error
.unwrap_or_else(|| "Image bundle is not verified".to_string()),
));
}
Ok(report)
}
fn nsstr(value: &str) -> Retained<NSString> {
NSString::from_str(value)
}
fn file_url(path: &Path) -> Retained<NSURL> {
NSURL::fileURLWithPath(&nsstr(&path.to_string_lossy()))
}
fn parse_environment(
values: &[String],
) -> Result<std::collections::BTreeMap<String, String>, ProviderError> {
values
.iter()
.map(|entry| {
let (name, value) = entry.split_once('=').ok_or_else(|| {
ProviderError::new(
"INVALID_ENVIRONMENT",
format!("Environment entry has no '=' separator: {entry}"),
)
})?;
if name.is_empty() {
return Err(ProviderError::new(
"INVALID_ENVIRONMENT",
"Environment variable name must not be empty",
));
}
Ok((name.to_string(), value.to_string()))
})
.collect()
}
#[cfg(test)]
mod tests {
use super::*;
fn request(bundle: &std::path::Path, network: &str) -> ExecutionStartInput {
ExecutionStartInput {
protocol_version: 1,
request_id: "native-vz-test".to_string(),
argv: vec!["printf ok".to_string()],
shell: true,
cwd: None,
env: Vec::new(),
tty: false,
timeout_ms: Some(5_000),
image_ref: None,
vm_bundle: Some(bundle.to_string_lossy().into_owned()),
workspace: None,
memory_mb: None,
cpu_count: None,
pids_max: None,
network: Some(network.to_string()),
exports: Vec::new(),
}
}
#[test]
fn resolves_verified_bundle_and_preserves_shell_as_explicit_argv() {
let bundle = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("extensions/macos-native/.build/vm-bundle");
if !bundle.join(apoc::image::MANIFEST_FILE).is_file() {
return;
}
let launch = ResolvedLaunch::resolve(&request(&bundle, "none"), None).unwrap();
assert_eq!(launch.guest.argv, ["/bin/sh", "-lc", "printf ok"]);
assert_eq!(launch.guest.timeout_ms, 5_000);
assert_eq!(launch.cpu_count, 4);
let snapshot = launch.snapshot_files.unwrap();
assert_eq!(
snapshot.machine_identifier.file_name().unwrap(),
"machine-id.bin"
);
assert_eq!(
snapshot.machine_state.file_name().unwrap(),
"machine-state.bin"
);
}
#[test]
fn rejects_unknown_network_policy_before_boot() {
let bundle = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("extensions/macos-native/.build/vm-bundle");
if !bundle.join(apoc::image::MANIFEST_FILE).is_file() {
return;
}
let error = ResolvedLaunch::resolve(&request(&bundle, "host"), None)
.err()
.unwrap();
assert_eq!(error.code, "INVALID_OPTIONS");
}
}