Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

19.9 KB
Raw Blame
import Darwin
import Foundation

// MARK: - VMDirectory

/// Manages a virtual machine's directory structure and files
/// Responsible for:
/// - Managing VM configuration files
/// - Handling disk operations
/// - Managing VM state and locking
/// - Providing access to VM-related paths
struct VMDirectory: Sendable {
    // MARK: - Constants
    
    private enum FileNames {
        static let nvram = "nvram.bin"
        static let disk = "disk.img"
        static let config = "config.json"
        static let sessions = "sessions.json"
        static let provisioning = ".provisioning"
        static let resizeMarker = "resize.lock.json"
        static let diskBackup = "disk.img.pre-resize"
        static let configBackup = "config.json.pre-resize"
        static let savedState = "state.vzvmsave"
        static let savedStateVsock = "state.vsock"
        static let vsockSession = "vsock.json"
    }

    // MARK: - Properties

    let dir: Path
    let nvramPath: Path
    let diskPath: Path
    var runOwnerURL: URL { configPath.url.deletingLastPathComponent().appendingPathComponent(".run-owner.json") }
    let configPath: Path
    let sessionsPath: Path
    let provisioningPath: Path
    let resizeMarkerPath: Path
    let diskBackupPath: Path
    let configBackupPath: Path
    let resizeGuardPath: Path
    /// The VM's saved machine state (`lume suspend`), restored by the next run.
    let statePath: Path
    /// Present when the saved state was saved with a virtio socket device
    /// (a run with host port forwards): a state restores only into the
    /// devices it was saved with.
    let stateVsockPath: Path
    /// The running VM's host port forwards over vsock ([`VsockSession`]).
    let vsockSessionPath: Path

    /// The name of the VM directory
    var name: String { dir.name }

    // MARK: - Initialization

    /// Creates a new VMDirectory instance
    /// - Parameters:
    ///   - dir: The base directory path for the VM
    init(_ dir: Path) {
        self.dir = dir
        self.nvramPath = dir.file(FileNames.nvram)
        self.diskPath = dir.file(FileNames.disk)
        self.configPath = dir.file(FileNames.config)
        self.sessionsPath = dir.file(FileNames.sessions)
        self.provisioningPath = dir.file(FileNames.provisioning)
        self.resizeMarkerPath = dir.file(FileNames.resizeMarker)
        self.diskBackupPath = dir.file(FileNames.diskBackup)
        self.configBackupPath = dir.file(FileNames.configBackup)
        self.statePath = dir.file(FileNames.savedState)
        self.stateVsockPath = dir.file(FileNames.savedStateVsock)
        self.vsockSessionPath = dir.file(FileNames.vsockSession)
        self.resizeGuardPath = Path(
            dir.url.deletingLastPathComponent()
                .appendingPathComponent(".\(dir.name).resize.guard", isDirectory: false))
    }
}

// MARK: - VM State Management

extension VMDirectory {
    /// Checks if the VM directory is initialized (either fully ready or provisioning)
    /// A VM is considered initialized if it has:
    /// - All required files (config + disk + nvram), OR
    /// - Config + provisioning marker (VM is being created)
    func initialized() -> Bool {
        let configExists = configPath.exists()
        let diskExists = diskPath.exists()
        let nvramExists = nvramPath.exists()
        let provisioningExists = provisioningPath.exists()

        // Fully initialized VM
        if configExists && diskExists && nvramExists {
            return true
        }

        // VM being provisioned (has config and provisioning marker)
        if configExists && provisioningExists {
            return true
        }

        return false
    }

    /// Checks if the VM directory exists
    func exists() -> Bool {
        dir.exists()
    }

    /// Whether the VM has a saved machine state its next run restores.
    func hasSavedState() -> Bool {
        statePath.exists()
    }

    /// Drops the saved machine state: once the VM booted or resumed, its
    /// disk no longer matches the memory the state holds.
    func discardSavedState() {
        try? FileManager.default.removeItem(atPath: statePath.path)
        try? FileManager.default.removeItem(atPath: stateVsockPath.path)
    }

    /// Whether the saved state was saved with a virtio socket device.
    func savedStateHasVsock() -> Bool {
        hasSavedState() && stateVsockPath.exists()
    }

    /// Records whether the state just saved has a virtio socket device.
    func markSavedStateVsock(_ present: Bool) {
        if present {
            FileManager.default.createFile(atPath: stateVsockPath.path, contents: Data())
        } else {
            try? FileManager.default.removeItem(atPath: stateVsockPath.path)
        }
    }

    /// The running VM's vsock forwards, when it was started with some.
    func loadVsockSession() -> VsockSession? {
        guard let data = try? Data(contentsOf: vsockSessionPath.url) else { return nil }
        return try? JSONDecoder().decode(VsockSession.self, from: data)
    }

    func saveVsockSession(_ session: VsockSession) {
        guard let data = try? JSONEncoder().encode(session) else { return }
        try? data.write(to: vsockSessionPath.url, options: .atomic)
    }

    func clearVsockSession() {
        try? FileManager.default.removeItem(atPath: vsockSessionPath.path)
    }
}

// MARK: - Disk Management

extension VMDirectory {
    /// Resizes the VM's disk to the specified size (grow-only).
    /// - Parameter size: The new size in bytes
    /// - Throws: VMDirectoryError if the disk operation fails or would shrink
    ///   the image (which silently truncates and corrupts the APFS tail).
    func setDisk(_ size: UInt64) throws {
        if !diskPath.exists() {
            guard FileManager.default.createFile(atPath: diskPath.path, contents: nil) else {
                throw VMDirectoryError.fileCreationFailed(diskPath.path)
            }
        }

        let currentSize =
            ((try? FileManager.default.attributesOfItem(atPath: diskPath.path))?[.size]
            as? NSNumber)?.uint64Value ?? 0
        guard size >= currentSize else {
            throw VMDirectoryError.diskOperationFailed(
                "refusing to shrink disk from \(currentSize) to \(size) bytes")
        }

        let handle: FileHandle
        do {
            handle = try FileHandle(forWritingTo: diskPath.url)
        } catch {
            throw VMDirectoryError.diskOperationFailed(
                "could not open \(diskPath.path): \(error.localizedDescription)")
        }
        defer { try? handle.close() }

        do {
            try handle.truncate(atOffset: size)
        } catch {
            throw VMDirectoryError.diskOperationFailed(
                "truncate to \(size) bytes failed: \(error.localizedDescription)")
        }
    }
}

// MARK: - Resize Transaction Marker

extension VMDirectory {
    func tryAcquireResizeGuard(exclusive: Bool) throws -> FileHandle? {
        if !resizeGuardPath.exists() {
            guard FileManager.default.createFile(atPath: resizeGuardPath.path, contents: Data()) else {
                throw VMDirectoryError.fileCreationFailed(resizeGuardPath.path)
            }
        }
        let handle = try FileHandle(forUpdating: resizeGuardPath.url)
        let operation = exclusive ? (LOCK_EX | LOCK_NB) : (LOCK_SH | LOCK_NB)
        guard flock(handle.fileDescriptor, operation) == 0 else {
            try? handle.close()
            return nil
        }
        return handle
    }

    /// Removes the resize guard file. Call it only after the VM directory
    /// is gone, while holding the guard exclusively.
    func removeResizeGuard() {
        try? FileManager.default.removeItem(atPath: resizeGuardPath.path)
    }

    /// Loads the resize transaction marker if a resize is in progress.
    func loadResizeMarker() throws -> ResizeMarker? {
        guard resizeMarkerPath.exists() else {
            return nil
        }
        do {
            let data = try Data(contentsOf: resizeMarkerPath.url)
            let marker = try JSONDecoder().decode(ResizeMarker.self, from: data)
            guard marker.version == ResizeMarker.currentVersion else {
                throw DiskResizeError.invalidResizeMarker("unsupported version \(marker.version)")
            }
            return marker
        } catch let error as DiskResizeError {
            throw error
        } catch {
            throw DiskResizeError.invalidResizeMarker(error.localizedDescription)
        }
    }

    /// True if a disk resize transaction is currently armed.
    func hasResizeMarker() -> Bool {
        resizeMarkerPath.exists()
    }

    /// Persists (and fsyncs) the resize transaction marker.
    func saveResizeMarker(_ marker: ResizeMarker) throws {
        let encoder = JSONEncoder()
        encoder.outputFormatting = .prettyPrinted
        let data = try encoder.encode(marker)
        let temporary = resizeMarkerPath.path + ".tmp"
        guard FileManager.default.createFile(atPath: temporary, contents: data) else {
            throw VMDirectoryError.fileCreationFailed(temporary)
        }
        let handle = try FileHandle(forWritingTo: URL(fileURLWithPath: temporary))
        try handle.synchronize()
        try handle.close()
        guard Darwin.rename(temporary, resizeMarkerPath.path) == 0 else {
            throw VMDirectoryError.diskOperationFailed(
                "could not commit resize marker: \(String(cString: strerror(errno)))")
        }
        try syncDirectory()
    }

    /// Removes the resize transaction marker after the transaction resolves.
    func clearResizeMarker() throws {
        guard resizeMarkerPath.exists() else { return }
        try FileManager.default.removeItem(atPath: resizeMarkerPath.path)
        try syncDirectory()
    }

    private func syncDirectory() throws {
        let directoryFD = Darwin.open(dir.path, O_RDONLY)
        guard directoryFD >= 0 else {
            throw VMDirectoryError.diskOperationFailed("could not open VM directory for sync")
        }
        defer { Darwin.close(directoryFD) }
        guard Darwin.fsync(directoryFD) == 0 else {
            throw VMDirectoryError.diskOperationFailed("could not sync VM directory")
        }
    }
}

// MARK: - Configuration Management

extension VMDirectory {
    /// Saves the VM configuration to disk
    /// - Parameter config: The configuration to save
    /// - Throws: VMDirectoryError if the save operation fails
    func saveConfig(_ config: VMConfig) throws {
        let encoder = JSONEncoder()
        encoder.outputFormatting = .prettyPrinted
        
        do {
            let data = try encoder.encode(config)
            guard FileManager.default.createFile(atPath: configPath.path, contents: data) else {
                throw VMDirectoryError.fileCreationFailed(configPath.path)
            }
        } catch {
            throw VMDirectoryError.invalidConfigData
        }
    }

    /// Loads the VM configuration from disk
    /// - Returns: The loaded configuration
    /// - Throws: VMDirectoryError if the load operation fails
    func loadConfig() throws -> VMConfig {
        guard let data = FileManager.default.contents(atPath: configPath.path) else {
            throw VMDirectoryError.configNotFound
        }
        
        do {
            let decoder = JSONDecoder()
            return try decoder.decode(VMConfig.self, from: data)
        } catch {
            throw VMDirectoryError.invalidConfigData
        }
    }
}

// MARK: - VNC Session Management

/// Marker written while a VM session is running.
///
/// Legacy markers carry only `url` and `sharedDirectories`; both still decode
/// unchanged, and a VNC-backed session still encodes exactly those two fields.
/// A VNC-disabled session has no URL, so it omits `url` and instead records the
/// owning `lume run` process, which `get`/`list` verify against the config-file
/// run lock. Older Lume binaries fail to decode that marker and therefore
/// report the VM as stopped instead of acting on stale information.
struct VNCSession: Codable {
    let url: String?
    let sharedDirectories: [SharedDirectory]?
    /// Absent on legacy markers, which always described a VNC-backed session.
    let vncEnabled: Bool?
    /// PID of the owning `lume run` process. Written only for VNC-disabled
    /// sessions, which have no listening port to probe for liveness.
    let pid: Int32?
    /// Unix timestamp of when the session started.
    let startedAt: Double?

    /// A marker without `vncEnabled` predates the policy and described VNC.
    var isVNCEnabled: Bool { vncEnabled ?? true }

    init(
        url: String?,
        sharedDirectories: [SharedDirectory]? = nil,
        vncEnabled: Bool? = nil,
        pid: Int32? = nil,
        startedAt: Double? = nil
    ) {
        self.url = url
        self.sharedDirectories = sharedDirectories
        self.vncEnabled = vncEnabled
        self.pid = pid
        self.startedAt = startedAt
    }

    /// Marker for a run started with `--vnc disabled`.
    static func vncDisabled(
        pid: Int32,
        startedAt: Double,
        sharedDirectories: [SharedDirectory]? = nil
    ) -> VNCSession {
        VNCSession(
            url: nil,
            sharedDirectories: sharedDirectories,
            vncEnabled: false,
            pid: pid,
            startedAt: startedAt
        )
    }
}

extension VMDirectory {
    /// Saves VNC session information to disk
    /// - Parameters:
    ///   - session: The VNC session to save
    ///   - sharedDirectories: Optional array of shared directories to save with the session
    /// - Throws: VMDirectoryError if the save operation fails
    func saveSession(_ session: VNCSession) throws {
        let encoder = JSONEncoder()
        encoder.outputFormatting = .prettyPrinted
        
        do {
            let data = try encoder.encode(session)
            guard FileManager.default.createFile(atPath: sessionsPath.path, contents: data) else {
                throw VMDirectoryError.fileCreationFailed(sessionsPath.path)
            }
        } catch {
            throw VMDirectoryError.invalidSessionData
        }
    }
    
    /// Loads the VNC session information from disk
    /// - Returns: The loaded VNC session
    /// - Throws: VMDirectoryError if the load operation fails
    func loadSession() throws -> VNCSession {
        guard let data = FileManager.default.contents(atPath: sessionsPath.path) else {
            throw VMDirectoryError.sessionNotFound
        }
        
        do {
            let decoder = JSONDecoder()
            return try decoder.decode(VNCSession.self, from: data)
        } catch {
            throw VMDirectoryError.invalidSessionData
        }
    }
    
    /// Removes the VNC session information from disk
    func clearSession() {
        try? FileManager.default.removeItem(atPath: sessionsPath.path)
    }
}

// MARK: - Provisioning Marker Management

/// Represents the provisioning state of a VM during long-running operations
struct ProvisioningMarker: Codable {
    /// The type of operation being performed (e.g., "ipsw_install", "unattended_setup")
    let operation: String
    /// When the provisioning started (Unix timestamp)
    let startedAt: Double
    
    init(operation: String) {
        self.operation = operation
        self.startedAt = Date().timeIntervalSince1970
    }
    
    /// Returns true if provisioning started more than the specified hours ago
    func isStale(hours: Double = 8.0) -> Bool {
        let elapsed = Date().timeIntervalSince1970 - startedAt
        return elapsed > (hours * 3600)
    }
}

extension VMDirectory {
    /// Saves a provisioning marker to indicate the VM is being created/configured
    /// - Parameter marker: The provisioning marker containing operation type
    /// - Throws: VMDirectoryError if the save operation fails
    func saveProvisioningMarker(_ marker: ProvisioningMarker) throws {
        let encoder = JSONEncoder()
        encoder.outputFormatting = .prettyPrinted

        do {
            let data = try encoder.encode(marker)
            guard FileManager.default.createFile(atPath: provisioningPath.path, contents: data) else {
                throw VMDirectoryError.fileCreationFailed(provisioningPath.path)
            }
        } catch {
            throw VMDirectoryError.fileCreationFailed(provisioningPath.path)
        }
    }

    /// Loads the provisioning marker if it exists
    /// - Returns: The provisioning marker, or nil if not in provisioning state
    func loadProvisioningMarker() -> ProvisioningMarker? {
        guard let data = FileManager.default.contents(atPath: provisioningPath.path) else {
            return nil
        }
        return try? JSONDecoder().decode(ProvisioningMarker.self, from: data)
    }

    /// Removes the provisioning marker after creation completes
    func clearProvisioningMarker() {
        try? FileManager.default.removeItem(atPath: provisioningPath.path)
    }

    /// Checks if the VM is currently being provisioned
    func isProvisioning() -> Bool {
        provisioningPath.exists()
    }
}

// MARK: - CustomStringConvertible
extension VMDirectory: CustomStringConvertible {
    var description: String {
        "VMDirectory(path: \(dir.path))"
    }
}

extension VMDirectory {
    func delete() throws {
        try FileManager.default.removeItem(atPath: dir.path)
    }
}

// MARK: - Lightweight VM Details

extension VMDirectory {
    /// Get disk size information without loading the full VM
    func getDiskSize() -> DiskSize {
        do {
            let resourceValues = try diskPath.url.resourceValues(forKeys: [
                .totalFileAllocatedSizeKey,
                .totalFileSizeKey,
            ])

            if let allocated = resourceValues.totalFileAllocatedSize,
               let total = resourceValues.totalFileSize {
                return DiskSize(allocated: UInt64(allocated), total: UInt64(total))
            }
        } catch {
            // Fallback to config value
        }

        // Try to get from config as fallback
        if let config = try? loadConfig() {
            return DiskSize(allocated: 0, total: config.diskSize ?? 0)
        }

        return DiskSize(allocated: 0, total: 0)
    }

    /// Build VMDetails directly without instantiating a full VM object
    /// This is much faster for listing VMs since it avoids:
    /// - Creating ImageLoader instances
    /// - Initializing virtualization services
    /// - Building the full VM object graph
    ///
    /// - Parameters:
    ///   - locationName: The storage location name for this VM
    ///   - status: The VM status ("running", "stopped", or "provisioning")
    ///   - provisioningOperation: Optional operation type if status is "provisioning"
    ///   - vncUrl: Optional VNC URL if running
    ///   - ipAddress: Optional IP address if running
    ///   - sshAvailable: Optional SSH availability status
    /// - Returns: VMDetails or nil if config cannot be loaded
    func getDetails(
        locationName: String,
        status: String,
        provisioningOperation: String? = nil,
        vncUrl: String?,
        ipAddress: String?,
        sshAvailable: Bool? = nil,
        downloadProgress: Double? = nil
    ) -> VMDetails? {
        guard let config = try? loadConfig() else {
            return nil
        }
        let vsockSession = status == "running" ? loadVsockSession() : nil

        return VMDetails(
            name: name,
            os: config.os,
            cpuCount: config.cpuCount ?? 0,
            memorySize: config.memorySize ?? 0,
            diskSize: getDiskSize(),
            display: config.display.string,
            status: status,
            provisioningOperation: provisioningOperation,
            vncUrl: vncUrl,
            ipAddress: ipAddress,
            sshAvailable: sshAvailable,
            locationName: locationName,
            sharedDirectories: nil,
            networkMode: config.networkMode.description,
            downloadProgress: downloadProgress,
            machineIdentifier: config.machineIdentifier?.base64EncodedString(),
            macAddress: config.macAddress,
            savedState: hasSavedState(),
            vsock: vsockSession.map { _ in true },
            forwards: vsockSession.flatMap { $0.agent ? $0.forwards : nil }
        )
    }
}