crun_sys/

lib.rs

//! # crun-sys
//!
//! Low-level Rust FFI bindings for libcrun, the OCI container runtime library.
//!
//! This crate provides raw C bindings generated by bindgen. For a safe Rust
//! interface, see the `CrunEngine` in the machineplane crate.
//!
//! # Platform Support
//!
//! **libcrun is Linux-only** (uses cgroups, namespaces, seccomp).
//! On non-Linux platforms, this crate provides a stub module that compiles
//! but provides no functionality.
//!
//! # Requirements (Linux)
//!
//! - libcrun >= 1.8 installed on the system
//! - libcrun development headers
//! - Required dependencies: yajl, libseccomp, libcap
//!
//! # Installation (Debian/Ubuntu)
//!
//! ```bash
//! apt-get install libcrun-dev libyajl-dev libseccomp-dev libcap-dev
//! ```
//!
//! # Installation (Fedora/RHEL)
//!
//! ```bash
//! dnf install crun-devel yajl-devel libseccomp-devel libcap-devel
//! ```
//!
//! # Safety
//!
//! All functions in this crate are `unsafe` as they are direct C FFI bindings.
//! The caller must ensure:
//! - Pointers are valid and properly aligned
//! - Strings are null-terminated
//! - Contexts are properly initialized and freed
//! - Thread safety is maintained (libcrun is not thread-safe per-context)

#![allow(non_upper_case_globals)]
#![allow(non_camel_case_types)]
#![allow(non_snake_case)]
#![allow(dead_code)]
#![allow(clippy::all)]

// =============================================================================
// Linux with libcrun: Include generated bindings
// =============================================================================

#[cfg(all(target_os = "linux", not(libcrun_stub)))]
include!(concat!(env!("OUT_DIR"), "/bindings.rs"));

// =============================================================================
// Non-Linux OR Linux without libcrun: Stub module (compiles but no functionality)
// =============================================================================

#[cfg(any(not(target_os = "linux"), libcrun_stub))]
pub mod stub {
    //! Stub module for non-Linux platforms.
    //!
    //! These types exist only to allow the code to compile on macOS/Windows.
    //! They are not functional - CrunEngine will report unavailable.

    use std::ffi::c_void;

    /// Stub error type pointer.
    pub type libcrun_error_t = *mut c_void;

    /// Stub container type pointer.
    pub type libcrun_container_t = *mut c_void;

    /// Stub context structure (non-functional).
    #[repr(C)]
    #[derive(Debug, Default)]
    pub struct libcrun_context_s {
        pub state_root: *const std::ffi::c_char,
        pub id: *const std::ffi::c_char,
        pub bundle: *const std::ffi::c_char,
        pub console_socket: *const std::ffi::c_char,
        pub pid_file: *const std::ffi::c_char,
        pub notify_socket: *const std::ffi::c_char,
        pub handler: *const c_void,
        pub preserve_fds: i32,
        pub listen_fds: i32,
        pub output_handler: Option<unsafe extern "C" fn()>,
        pub output_handler_arg: *mut c_void,
        pub fifo_exec_wait_fd: i32,
        pub systemd_cgroup: bool,
        pub detach: bool,
        pub no_new_keyring: bool,
        pub force_no_cgroup: bool,
        pub no_pivot: bool,
        pub argv: *mut *mut std::ffi::c_char,
        pub argc: i32,
        pub handler_manager: *mut c_void,
    }

    /// Stub features info.
    pub type features_info_s = c_void;

    // Stub functions - all return error codes indicating "not available"

    /// Stub: always returns -1 (unavailable).
    /// # Safety
    /// This is a stub - does nothing.
    pub unsafe fn libcrun_container_get_features(
        _ctx: *mut libcrun_context_s,
        _features: *mut *mut features_info_s,
        _err: *mut libcrun_error_t,
    ) -> i32 {
        -1
    }

    /// Stub: always returns null.
    /// # Safety
    /// This is a stub - does nothing.
    pub unsafe fn libcrun_container_load_from_memory(
        _json: *const std::ffi::c_char,
        _err: *mut libcrun_error_t,
    ) -> libcrun_container_t {
        std::ptr::null_mut()
    }

    /// Stub: always returns -1.
    /// # Safety
    /// This is a stub - does nothing.
    pub unsafe fn libcrun_container_run(
        _ctx: *mut libcrun_context_s,
        _container: libcrun_container_t,
        _options: i32,
        _err: *mut libcrun_error_t,
    ) -> i32 {
        -1
    }

    /// Stub: always returns -1.
    /// # Safety
    /// This is a stub - does nothing.
    pub unsafe fn libcrun_container_kill(
        _ctx: *mut libcrun_context_s,
        _id: *const std::ffi::c_char,
        _signal: *const std::ffi::c_char,
        _err: *mut libcrun_error_t,
    ) -> i32 {
        -1
    }

    /// Stub: always returns -1.
    /// # Safety
    /// This is a stub - does nothing.
    pub unsafe fn libcrun_container_delete(
        _ctx: *mut libcrun_context_s,
        _def: *mut c_void,
        _id: *const std::ffi::c_char,
        _force: bool,
        _err: *mut libcrun_error_t,
    ) -> i32 {
        -1
    }

    /// Stub: does nothing.
    /// # Safety
    /// This is a stub - does nothing.
    pub unsafe fn libcrun_container_free(_container: libcrun_container_t) {}

    /// Stub: does nothing.
    /// # Safety
    /// This is a stub - does nothing.
    pub unsafe fn crun_error_release(_err: *mut libcrun_error_t) {}
}

#[cfg(any(not(target_os = "linux"), libcrun_stub))]
pub use stub::*;

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

    // =========================================================================
    // Linux Tests
    // =========================================================================

    #[cfg(target_os = "linux")]
    use super::*;

    /// Test that we can create and free an error object (Linux only).
    #[cfg(target_os = "linux")]
    #[test]
    fn test_error_lifecycle() {
        let err: libcrun_error_t = ptr::null_mut();
        assert!(err.is_null());
    }

    /// Test that crun_error_release handles null safely.
    /// This is a smoke test to verify the symbol resolves correctly.
    #[cfg(target_os = "linux")]
    #[test]
    fn test_error_release_null_safe() {
        unsafe {
            // Passing null to crun_error_release should be safe (no-op)
            let mut err: libcrun_error_t = ptr::null_mut();
            crun_error_release(&mut err);
        }
    }

    /// Verify libcrun_context_s has expected size (catches ABI changes).
    #[cfg(target_os = "linux")]
    #[test]
    fn test_context_struct_is_non_zero() {
        // Context struct should have a reasonable size
        let size = std::mem::size_of::<libcrun_context_s>();
        assert!(size > 0, "libcrun_context_s should have non-zero size");
        // It should be at least pointer-sized (contains many pointers)
        assert!(
            size >= std::mem::size_of::<*const ()>(),
            "libcrun_context_s too small"
        );
    }

    /// Test that load_from_memory returns null for invalid JSON.
    #[cfg(target_os = "linux")]
    #[test]
    fn test_load_invalid_json_returns_null() {
        use std::ffi::CString;

        unsafe {
            let mut err: libcrun_error_t = ptr::null_mut();
            let invalid_json = CString::new("not valid json").unwrap();

            let container = libcrun_container_load_from_memory(invalid_json.as_ptr(), &mut err);

            // Should return null for invalid input
            assert!(container.is_null(), "Expected null for invalid JSON");

            // Clean up error if set
            if !err.is_null() {
                crun_error_release(&mut err);
            }
        }
    }

    // =========================================================================
    // Non-Linux Stub Tests
    // =========================================================================

    /// Stub test: verify stub module compiles and types are usable.
    #[cfg(any(not(target_os = "linux"), libcrun_stub))]
    #[test]
    fn test_stub_compiles() {
        use super::stub::*;
        let ctx = libcrun_context_s::default();
        assert!(ctx.state_root.is_null());
        assert!(ctx.id.is_null());
        assert!(ctx.bundle.is_null());
    }

    /// Stub test: verify all stub functions return expected error values.
    #[cfg(any(not(target_os = "linux"), libcrun_stub))]
    #[test]
    fn test_stub_functions_return_errors() {
        use super::stub::*;

        unsafe {
            let mut ctx = libcrun_context_s::default();
            let mut err: libcrun_error_t = ptr::null_mut();

            // get_features should return -1
            let result = libcrun_container_get_features(&mut ctx, ptr::null_mut(), &mut err);
            assert_eq!(result, -1, "get_features should return -1");

            // load_from_memory should return null
            let container = libcrun_container_load_from_memory(ptr::null(), &mut err);
            assert!(container.is_null(), "load_from_memory should return null");

            // run should return -1
            let result = libcrun_container_run(&mut ctx, ptr::null_mut(), 0, &mut err);
            assert_eq!(result, -1, "run should return -1");

            // kill should return -1
            let result = libcrun_container_kill(&mut ctx, ptr::null(), ptr::null(), &mut err);
            assert_eq!(result, -1, "kill should return -1");

            // delete should return -1
            let result =
                libcrun_container_delete(&mut ctx, ptr::null_mut(), ptr::null(), false, &mut err);
            assert_eq!(result, -1, "delete should return -1");
        }
    }

    /// Stub test: verify free/release functions don't panic on null.
    #[cfg(any(not(target_os = "linux"), libcrun_stub))]
    #[test]
    fn test_stub_free_functions_null_safe() {
        use super::stub::*;

        unsafe {
            // These should not panic
            libcrun_container_free(ptr::null_mut());
            crun_error_release(ptr::null_mut());
        }
    }

    /// Stub test: verify context struct has expected fields.
    #[cfg(any(not(target_os = "linux"), libcrun_stub))]
    #[test]
    fn test_stub_context_fields() {
        use super::stub::*;

        let ctx = libcrun_context_s::default();

        // All pointer fields should default to null
        assert!(ctx.state_root.is_null());
        assert!(ctx.id.is_null());
        assert!(ctx.bundle.is_null());
        assert!(ctx.console_socket.is_null());
        assert!(ctx.pid_file.is_null());
        assert!(ctx.notify_socket.is_null());
        assert!(ctx.handler.is_null());
        assert!(ctx.output_handler.is_none());
        assert!(ctx.output_handler_arg.is_null());
        assert!(ctx.argv.is_null());
        assert!(ctx.handler_manager.is_null());

        // Numeric fields should default to 0/false
        assert_eq!(ctx.preserve_fds, 0);
        assert_eq!(ctx.listen_fds, 0);
        assert_eq!(ctx.fifo_exec_wait_fd, 0);
        assert_eq!(ctx.argc, 0);
        assert!(!ctx.systemd_cgroup);
        assert!(!ctx.detach);
        assert!(!ctx.no_new_keyring);
        assert!(!ctx.force_no_cgroup);
        assert!(!ctx.no_pivot);
    }
}