Consider Rust bindings for vmnet-broker client library

[nirs]

Overview

This issue proposes the development of Rust bindings for vmnet-broker. This component is responsible for managing privileged network interface creation (via vmnet.framework) for virtual machines, allowing the primary virtualization process to operate without root privileges.

Rationale

Current implementations typically rely on Swift or Go. Introducing Rust bindings addresses specific memory safety and lifecycle concerns inherent in privileged brokerage services.

Potential users

Several projects in the macOS virtualization space could leverage a Rust-based broker:

• libkrun: can use this if it implements native vmnet network like vfkit
• OrbStack: Could utilize a standardized Rust broker for its networking backend to enhance memory safety in its privileged components.
• Rust-based VZ Implementations: Developers building CLI-based virtualization tools in Rust (using crates like virt-fwk or objc2-virtualization) currently lack an idiomatic, safe way to interface with vmnet-broker.
• Security-Hardened Virtualization: Developers building "minimal" or "hardened" VM runners for macOS can use a Rust broker to minimize the Trusted Computing Base (TCB) of the privileged networking component.

Issues:

• Initial development requires significant unsafe FFI boilerplate to map vmnet C headers.
• Maintenance overhead to track changes in Apple's networking frameworks which may not be documented as thoroughly as the core Virtualization API.

Supporting Documentation

• Apple vmnet.framework documentation: https://developer.apple.com/documentation/vmnet
• Rust Foreign Function Interface (FFI) guide: https://doc.rust-lang.org/nomicon/ffi.html

[nirs]

A draft by Gemini:

use std::ffi::{CStr, CString};
use std::os::raw::c_char;
use std::ptr;
use std::sync::OnceLock;

// XPC Opaque Types
pub type xpc_object_t = *mut std::ffi::c_void;
pub type xpc_connection_t = *mut std::ffi::c_void;
pub type xpc_type_t = *mut std::ffi::c_void;

// Constants from vmnet-broker.h
const MACH_SERVICE_NAME: &[u8] = b"com.example.vmnet-broker\0";
const REQUEST_COMMAND: &[u8] = b"command\0";
const REQUEST_NETWORK_NAME: &[u8] = b"network_name\0";
const COMMAND_GET: &[u8] = b"get\0";
const REPLY_ERROR: &[u8] = b"error\0";
const REPLY_NETWORK: &[u8] = b"network\0";

#[derive(Debug, Clone, Copy)]
#[repr(i32)]
pub enum BrokerStatus {
    Success = 0,
    XpcFailure = -1,
    InvalidReply = -2,
    NotAllowed = -3,
    InvalidRequest = -4,
    NotFound = -5,
    CreateFailure = -6,
    InternalError = -7,
}

// Persistent connection storage
static CONNECTION: OnceLock<xpc_connection_t> = OnceLock::new();

/// Pure C-function handler to avoid Objective-C Blocks
extern "C" fn broker_event_handler(_event: xpc_object_t) {
    // Intentional empty handler matching client.c logic
}

fn get_connection() -> xpc_connection_t {
    *CONNECTION.get_or_init(|| unsafe {
        let conn = xpc_connection_create_mach_service(
            MACH_SERVICE_NAME.as_ptr() as *const c_char,
            ptr::null_mut(),
            0,
        );

        // Using the _f variant to pass a standard Rust 'extern "C"' function
        xpc_connection_set_event_handler_f(conn, broker_event_handler);

        xpc_connection_resume(conn);
        conn
    })
}

/// Re-implements vmnet_broker_start_session
pub fn vmnet_broker_start_session(
    network_name: &str,
) -> (xpc_object_t, BrokerStatus) {
    unsafe {
        let connection = get_connection();
        let mut ret = BrokerStatus::InternalError;
        let mut serialization: xpc_object_t = ptr::null_mut();

        // 1. Create and populate message
        let message = xpc_dictionary_create_empty();
        let c_network_name = CString::new(network_name).unwrap_or_default();

        xpc_dictionary_set_string(message, REQUEST_COMMAND.as_ptr() as *const c_char, COMMAND_GET.as_ptr() as *const c_char);
        xpc_dictionary_set_string(message, REQUEST_NETWORK_NAME.as_ptr() as *const c_char, c_network_name.as_ptr());

        // 2. Synchronous XPC call
        let reply = xpc_connection_send_message_with_reply_sync(connection, message);
        xpc_release(message);

        let reply_type = xpc_get_type(reply);

        if reply_type == XPC_TYPE_ERROR {
            ret = BrokerStatus::XpcFailure;
        } else if reply_type != XPC_TYPE_DICTIONARY {
            ret = BrokerStatus::InvalidReply;
        } else {
            let error = xpc_dictionary_get_int64(reply, REPLY_ERROR.as_ptr() as *const c_char);
            if error != 0 {
                ret = std::mem::transmute::<i32, BrokerStatus>(error as i32);
            } else {
                let value = xpc_dictionary_get_value(reply, REPLY_NETWORK.as_ptr() as *const c_char);
                if value.is_null() {
                    ret = BrokerStatus::InvalidReply;
                } else {
                    ret = BrokerStatus::Success;
                    serialization = value;
                    xpc_retain(serialization);
                }
            }
        }

        xpc_release(reply);
        (serialization, ret)
    }
}

pub fn vmnet_broker_strerror(status: BrokerStatus) -> &'static str {
    match status {
        BrokerStatus::Success => "Broker session started",
        BrokerStatus::XpcFailure => "Failed to send XPC message to broker",
        BrokerStatus::InvalidReply => "Broker returned invalid reply",
        BrokerStatus::NotAllowed => "You are not allowed to create a network",
        BrokerStatus::InvalidRequest => "Invalid broker request",
        BrokerStatus::NotFound => "Network name not found",
        BrokerStatus::CreateFailure => "Failed to create network",
        BrokerStatus::InternalError => "Internal or unknown error",
    }
}