apoc 0.9.1

Agentic process control for LLMs
Documentation
use std::ffi::CStr;
use std::ffi::CString;
use std::fs::{self, File};
use std::io::Write as _;
use std::os::unix::ffi::OsStrExt as _;
use std::path::PathBuf;

use serde::{Deserialize, Serialize};
use sha2::{Digest as _, Sha256};

use crate::model::ProviderError;

const SNAPSHOT_LAYOUT_VERSION: &str =
    "apoc-native-vz-snapshot-v4-ro-shared-cached-full-checkpoint-eof-direct-save";

pub fn current_host_build() -> String {
    let mut name = std::mem::MaybeUninit::<libc::utsname>::uninit();
    if unsafe { libc::uname(name.as_mut_ptr()) } != 0 {
        return format!("{}-{}", std::env::consts::OS, std::env::consts::ARCH);
    }
    let name = unsafe { name.assume_init() };
    let release = unsafe { CStr::from_ptr(name.release.as_ptr()) }.to_string_lossy();
    let version = unsafe { CStr::from_ptr(name.version.as_ptr()) }.to_string_lossy();
    let machine = unsafe { CStr::from_ptr(name.machine.as_ptr()) }.to_string_lossy();
    format!("{release}|{version}|{machine}")
}

#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct SnapshotFiles {
    pub machine_identifier: PathBuf,
    pub machine_state: PathBuf,
    pub metadata: PathBuf,
}

pub struct RestoreClone {
    path: PathBuf,
}

impl RestoreClone {
    pub fn path(&self) -> &std::path::Path {
        &self.path
    }
}

impl Drop for RestoreClone {
    fn drop(&mut self) {
        let _ = fs::remove_file(&self.path);
    }
}

pub fn clone_for_restore(files: &SnapshotFiles) -> Result<RestoreClone, ProviderError> {
    let destination = files
        .machine_state
        .with_extension(format!("restore-{}.vzvmsave", uuid::Uuid::now_v7()));
    let source = CString::new(files.machine_state.as_os_str().as_bytes()).map_err(|_| {
        ProviderError::new(
            "SNAPSHOT_CLONE_FAILED",
            "Machine-state path contains a null byte",
        )
    })?;
    let target = CString::new(destination.as_os_str().as_bytes()).map_err(|_| {
        ProviderError::new(
            "SNAPSHOT_CLONE_FAILED",
            "Restore-clone path contains a null byte",
        )
    })?;
    if unsafe { libc::clonefile(source.as_ptr(), target.as_ptr(), 0) } != 0 {
        return Err(ProviderError::new(
            "SNAPSHOT_CLONE_FAILED",
            format!(
                "Cannot clone machine state for restore: {}",
                std::io::Error::last_os_error()
            ),
        ));
    }
    Ok(RestoreClone { path: destination })
}

#[derive(Debug, Deserialize, Serialize)]
struct SnapshotMetadata {
    schema_version: u32,
    #[serde(default)]
    status: SnapshotMetadataStatus,
    fingerprint: String,
    snapshot_bytes: u64,
    #[serde(skip_serializing_if = "Option::is_none")]
    error: Option<String>,
}

#[derive(Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
enum SnapshotMetadataStatus {
    #[default]
    Ready,
    Unusable,
}

pub fn compatibility_fingerprint(
    image_digest: &str,
    cpu_count: u64,
    memory_mb: u64,
    guest_agent_port: u32,
    kernel_command_line: &str,
    machine_identifier: &[u8],
    host_build: &str,
) -> String {
    let encoded = serde_json::to_vec(&serde_json::json!({
        "schema": SNAPSHOT_LAYOUT_VERSION,
        "image_digest": image_digest,
        "cpu_count": cpu_count,
        "memory_mb": memory_mb,
        "guest_agent_port": guest_agent_port,
        "kernel_command_line": kernel_command_line,
        "machine_identifier_sha256": format!("sha256:{:x}", Sha256::digest(machine_identifier)),
        "host_build": host_build,
    }))
    .expect("snapshot compatibility payload is serializable");
    format!("sha256:{:x}", Sha256::digest(encoded))
}

pub fn snapshot_available(files: &SnapshotFiles, fingerprint: &str) -> bool {
    let Ok(snapshot) = fs::metadata(&files.machine_state) else {
        return false;
    };
    if !snapshot.is_file() || snapshot.len() == 0 {
        return false;
    }
    let Ok(encoded) = fs::read(&files.metadata) else {
        return false;
    };
    let Ok(metadata) = serde_json::from_slice::<SnapshotMetadata>(&encoded) else {
        return false;
    };
    metadata.schema_version == 1
        && metadata.status == SnapshotMetadataStatus::Ready
        && metadata.fingerprint == fingerprint
        && metadata.snapshot_bytes == snapshot.len()
}

pub fn record_snapshot(files: &SnapshotFiles, fingerprint: &str) -> Result<(), ProviderError> {
    let snapshot_bytes = fs::metadata(&files.machine_state)
        .map_err(|error| {
            ProviderError::new(
                "SNAPSHOT_METADATA_FAILED",
                format!("Cannot inspect saved machine state: {error}"),
            )
        })?
        .len();
    if snapshot_bytes == 0 {
        return Err(ProviderError::new(
            "SNAPSHOT_METADATA_FAILED",
            "Saved machine state is empty",
        ));
    }
    write_metadata(
        files,
        SnapshotMetadata {
            schema_version: 1,
            status: SnapshotMetadataStatus::Ready,
            fingerprint: fingerprint.to_string(),
            snapshot_bytes,
            error: None,
        },
    )
}

fn write_metadata_bytes(files: &SnapshotFiles, encoded: &[u8]) -> Result<(), ProviderError> {
    let temporary = files
        .metadata
        .with_extension(format!("tmp-{}", uuid::Uuid::now_v7()));
    let mut output = File::create(&temporary).map_err(|error| {
        ProviderError::new(
            "SNAPSHOT_METADATA_FAILED",
            format!("Cannot create snapshot metadata staging file: {error}"),
        )
    })?;
    output.write_all(encoded).map_err(|error| {
        ProviderError::new(
            "SNAPSHOT_METADATA_FAILED",
            format!("Cannot write snapshot metadata staging file: {error}"),
        )
    })?;
    output.sync_all().map_err(|error| {
        ProviderError::new(
            "SNAPSHOT_METADATA_FAILED",
            format!("Cannot sync snapshot metadata staging file: {error}"),
        )
    })?;
    drop(output);
    if let Err(error) = fs::rename(&temporary, &files.metadata) {
        let _ = fs::remove_file(&temporary);
        return Err(ProviderError::new(
            "SNAPSHOT_METADATA_FAILED",
            format!("Cannot publish snapshot metadata atomically: {error}"),
        ));
    }
    Ok(())
}

pub fn snapshot_unusable(files: &SnapshotFiles, fingerprint: &str) -> bool {
    fs::read(&files.metadata)
        .ok()
        .and_then(|encoded| serde_json::from_slice::<SnapshotMetadata>(&encoded).ok())
        .is_some_and(|metadata| {
            metadata.schema_version == 1
                && metadata.status == SnapshotMetadataStatus::Unusable
                && metadata.fingerprint == fingerprint
        })
}

pub fn mark_snapshot_unusable(
    files: &SnapshotFiles,
    fingerprint: &str,
    error: &str,
) -> Result<(), ProviderError> {
    let _ = fs::remove_file(&files.machine_state);
    write_metadata(
        files,
        SnapshotMetadata {
            schema_version: 1,
            status: SnapshotMetadataStatus::Unusable,
            fingerprint: fingerprint.to_string(),
            snapshot_bytes: 0,
            error: Some(error.to_string()),
        },
    )
}

fn write_metadata(files: &SnapshotFiles, metadata: SnapshotMetadata) -> Result<(), ProviderError> {
    let encoded = serde_json::to_vec_pretty(&metadata).map_err(|error| {
        ProviderError::new(
            "SNAPSHOT_METADATA_FAILED",
            format!("Cannot encode snapshot metadata: {error}"),
        )
    })?;
    write_metadata_bytes(files, &encoded)
}

#[cfg(test)]
mod tests {
    use std::fs;

    use super::*;

    #[test]
    fn compatibility_fingerprint_changes_with_machine_identifier() {
        let first = compatibility_fingerprint(
            "sha256:image",
            4,
            1024,
            5000,
            "console=hvc0",
            b"machine-a",
            "host-build",
        );
        let second = compatibility_fingerprint(
            "sha256:image",
            4,
            1024,
            5000,
            "console=hvc0",
            b"machine-b",
            "host-build",
        );

        assert_ne!(first, second);
    }

    #[test]
    fn availability_requires_matching_fingerprint_and_snapshot_size() {
        let directory = tempfile::tempdir().unwrap();
        let files = SnapshotFiles {
            machine_identifier: directory.path().join("machine-id.bin"),
            machine_state: directory.path().join("machine-state.bin"),
            metadata: directory.path().join("warmup-digest.json"),
        };
        fs::write(&files.machine_state, b"snapshot").unwrap();
        record_snapshot(&files, "sha256:fingerprint").unwrap();

        assert!(snapshot_available(&files, "sha256:fingerprint"));
        assert!(!snapshot_available(&files, "sha256:other"));

        fs::write(&files.machine_state, b"snapshot-grew").unwrap();
        assert!(!snapshot_available(&files, "sha256:fingerprint"));
    }

    #[test]
    fn restore_clone_is_removed_when_guard_drops() {
        let directory = tempfile::tempdir().unwrap();
        let files = SnapshotFiles {
            machine_identifier: directory.path().join("machine-id.bin"),
            machine_state: directory.path().join("machine-state.bin"),
            metadata: directory.path().join("warmup-digest.json"),
        };
        fs::write(&files.machine_state, b"snapshot").unwrap();
        let clone = clone_for_restore(&files).unwrap();
        let clone_path = clone.path().to_path_buf();
        assert_eq!(fs::read(&clone_path).unwrap(), b"snapshot");

        drop(clone);

        assert!(!clone_path.exists());
    }

    #[test]
    fn unusable_marker_disables_matching_snapshot_and_removes_state() {
        let directory = tempfile::tempdir().unwrap();
        let files = SnapshotFiles {
            machine_identifier: directory.path().join("machine-id.bin"),
            machine_state: directory.path().join("machine-state.bin"),
            metadata: directory.path().join("warmup-digest.json"),
        };
        fs::write(&files.machine_state, b"snapshot").unwrap();
        record_snapshot(&files, "sha256:fingerprint").unwrap();

        mark_snapshot_unusable(&files, "sha256:fingerprint", "VZErrorDomain code=12").unwrap();

        assert!(snapshot_unusable(&files, "sha256:fingerprint"));
        assert!(!snapshot_available(&files, "sha256:fingerprint"));
        assert!(!files.machine_state.exists());
    }
}