palladium_plugin/

native.rs

//! Native shared-library plugin loading.
//!
//! [`PluginRegistry::load_native`] opens a shared library with `libloading`,
//! reads the `pd_plugin_init` export, verifies the ABI version, and registers
//! a factory for each actor type the plugin declares.
//!
//! # Symbol contract
//!
//! Every native plugin must export the following C-linkage symbols:
//!
//! ```c
//! PdPluginInfo* pd_plugin_init(void);
//! void          pd_plugin_shutdown(void);
//! void*         pd_actor_create (const char* type_name, uint32_t type_name_len,
//!                                const uint8_t* config,  uint32_t config_len);
//! void          pd_actor_destroy(void* actor);
//! int32_t       pd_actor_on_start  (void* actor, PdActorContext* ctx);
//! int32_t       pd_actor_on_message(void* actor, PdActorContext* ctx,
//!                                   const uint8_t* envelope_bytes,
//!                                   const uint8_t* payload, uint32_t payload_len);
//! void          pd_actor_on_stop   (void* actor, PdActorContext* ctx, int32_t reason);
//! ```
//!
//! If any symbol is missing, `load_native` returns
//! `Err(PluginError::LoadFailed(...))`.

use std::ffi::c_void;
use std::path::Path;

use palladium_plugin_api::{PdActorTypeInfo, PdPluginInfo, PD_ABI_VERSION};

use crate::error::PluginError;
use crate::ffi_actor::{FfiActor, FfiVtable};
use crate::manifest::{PluginInfo, PluginKind};
use crate::registry::{LoadedPlugin, PluginRegistry};

// ── Symbol names ──────────────────────────────────────────────────────────────

const SYM_INIT: &[u8] = b"pd_plugin_init\0";
const SYM_CREATE: &[u8] = b"pd_actor_create\0";
const SYM_DESTROY: &[u8] = b"pd_actor_destroy\0";
const SYM_ON_START: &[u8] = b"pd_actor_on_start\0";
const SYM_ON_MESSAGE: &[u8] = b"pd_actor_on_message\0";
const SYM_ON_STOP: &[u8] = b"pd_actor_on_stop\0";

// ── Helpers ───────────────────────────────────────────────────────────────────

/// Verify that the ABI version declared by the plugin matches the engine's.
///
/// # Safety
///
/// `info` must point to a valid [`PdPluginInfo`] that remains live for the
/// duration of this call.
unsafe fn check_abi_version(info: *const PdPluginInfo) -> Result<(), PluginError> {
    let found = unsafe { (*info).abi_version };
    if found != PD_ABI_VERSION {
        return Err(PluginError::AbiMismatch {
            expected: PD_ABI_VERSION,
            found,
        });
    }
    Ok(())
}

/// Read a plugin name or type-name from a `(*const u8, u32)` pair.
///
/// Returns `Err(LoadFailed)` if the bytes are not valid UTF-8.
///
/// # Safety
///
/// `ptr` must point to at least `len` valid bytes that remain live for the
/// duration of this call.
unsafe fn read_str(ptr: *const u8, len: u32) -> Result<String, PluginError> {
    let slice = unsafe { std::slice::from_raw_parts(ptr, len as usize) };
    std::str::from_utf8(slice)
        .map(|s| s.to_string())
        .map_err(|e| PluginError::LoadFailed(format!("invalid UTF-8 in plugin string: {e}")))
}

/// Read the array of `PdActorTypeInfo` structs from a `PdPluginInfo`.
///
/// Returns a `Vec` of `(type_name, vtable)` pairs; each pair registers one
/// actor type factory.
///
/// # Safety
///
/// `info` and the `actor_types` array it points to must remain valid for the
/// duration of this function.
unsafe fn read_actor_types(
    info: *const PdPluginInfo,
    vtable: FfiVtable,
) -> Result<Vec<(String, FfiVtable)>, PluginError> {
    let count = unsafe { (*info).actor_type_count } as usize;
    let types_ptr: *const PdActorTypeInfo = unsafe { (*info).actor_types };

    let mut result = Vec::with_capacity(count);
    for i in 0..count {
        // SAFETY: caller guarantees the array has `count` valid elements.
        let type_info: &PdActorTypeInfo = unsafe { &*types_ptr.add(i) };
        let type_name = unsafe { read_str(type_info.type_name, type_info.type_name_len) }?;
        result.push((type_name, vtable));
    }
    Ok(result)
}

// ── PluginRegistry::load_native ───────────────────────────────────────────────

impl<R: palladium_runtime::Reactor> PluginRegistry<R> {
    /// Load a native shared library plugin from `path`.
    ///
    /// Steps:
    /// 1. Open the library with [`libloading`].
    /// 2. Resolve all required C symbols; fail fast on missing exports.
    /// 3. Call `pd_plugin_init` and verify the returned ABI version.
    /// 4. For each declared actor type, register a factory that constructs an
    ///    [`FfiActor`] wrapping the plugin's lifecycle functions.
    /// 5. Record the loaded library in the registry so it stays mapped in
    ///    memory for the lifetime of the actors it created.
    ///
    /// Returns [`PluginInfo`] describing the newly loaded plugin.
    ///
    /// # Errors
    ///
    /// - [`PluginError::LoadFailed`] — library not found, symbol missing, or
    ///   UTF-8 decoding of plugin name/type names failed.
    /// - [`PluginError::InitFailed`] — `pd_plugin_init` returned null.
    /// - [`PluginError::AbiMismatch`] — `abi_version` in the returned struct
    ///   does not equal [`PD_ABI_VERSION`].
    pub fn load_native(&mut self, path: &Path) -> Result<PluginInfo, PluginError> {
        // ── 1. Open the library ───────────────────────────────────────────────
        // SAFETY: libloading calls dlopen; the library stays alive in `lib`.
        let lib = unsafe { libloading::Library::new(path) }
            .map_err(|e| PluginError::LoadFailed(e.to_string()))?;

        // ── 2. Resolve symbols ────────────────────────────────────────────────
        // Each `*sym` dereferences the `Symbol<fn>` to get the raw function
        // pointer value. This is safe because `lib` will outlive the pointers
        // (it moves into `LoadedPlugin::Native { _lib: lib }` below).

        type InitFn = unsafe extern "C" fn() -> *const PdPluginInfo;
        type CreateFn = unsafe extern "C" fn(*const u8, u32, *const u8, u32) -> *mut c_void;
        type DestroyFn = unsafe extern "C" fn(*mut c_void);
        type OnStartFn =
            unsafe extern "C" fn(*mut c_void, *mut palladium_plugin_api::PdActorContext) -> i32;
        type OnMessageFn = unsafe extern "C" fn(
            *mut c_void,
            *mut palladium_plugin_api::PdActorContext,
            *const u8,
            *const u8,
            u32,
        ) -> i32;
        type OnStopFn =
            unsafe extern "C" fn(*mut c_void, *mut palladium_plugin_api::PdActorContext, i32);

        macro_rules! load_sym {
            ($name:expr, $ty:ty) => {{
                let sym: libloading::Symbol<$ty> = unsafe { lib.get($name) }.map_err(|e| {
                    PluginError::LoadFailed(format!(
                        "missing symbol `{}`: {e}",
                        std::str::from_utf8($name)
                            .unwrap_or("<invalid>")
                            .trim_end_matches('\0')
                    ))
                })?;
                // Copy the function pointer out before `sym` (and its lifetime
                // tied to `lib`) is dropped. Safe because `lib` outlives the copy.
                *sym
            }};
        }

        let init_fn: InitFn = load_sym!(SYM_INIT, InitFn);
        let vtable = FfiVtable {
            create: load_sym!(SYM_CREATE, CreateFn),
            destroy: load_sym!(SYM_DESTROY, DestroyFn),
            on_start: load_sym!(SYM_ON_START, OnStartFn),
            on_message: load_sym!(SYM_ON_MESSAGE, OnMessageFn),
            on_stop: load_sym!(SYM_ON_STOP, OnStopFn),
        };

        // ── 3. Call pd_plugin_init and verify ABI ─────────────────────────────
        // SAFETY: symbol was resolved from the library we just opened.
        let info_ptr: *const PdPluginInfo = unsafe { init_fn() };
        if info_ptr.is_null() {
            return Err(PluginError::InitFailed);
        }
        // SAFETY: non-null, returned by the plugin itself, valid for as long
        // as the library is loaded (which it will be — it's in `lib`).
        unsafe { check_abi_version(info_ptr) }?;

        // ── 4. Read plugin name and version ───────────────────────────────────
        let plugin_name = unsafe { read_str((*info_ptr).name, (*info_ptr).name_len) }?;
        let version = unsafe {
            format!(
                "{}.{}.{}",
                (*info_ptr).version_major,
                (*info_ptr).version_minor,
                (*info_ptr).version_patch,
            )
        };

        // ── 5. Register factories for each actor type ─────────────────────────
        let actor_types = unsafe { read_actor_types(info_ptr, vtable) }?;
        let actor_type_count = actor_types.len();

        for (type_name, vtable) in actor_types {
            let type_name_bytes: Vec<u8> = type_name.as_bytes().to_vec();
            self.register_type(plugin_name.clone(), type_name, move |config: &[u8]| {
                let config_bytes = config.to_vec();
                // SAFETY: vtable is a copy of valid function pointers from a
                // library that is kept alive in LoadedPlugin::Native { _lib }.
                let state = unsafe {
                    (vtable.create)(
                        type_name_bytes.as_ptr(),
                        type_name_bytes.len() as u32,
                        config_bytes.as_ptr(),
                        config_bytes.len() as u32,
                    )
                };
                if state.is_null() {
                    return Err(PluginError::InitFailed);
                }
                Ok(Box::new(FfiActor::<R>::new(state, vtable)))
            });
        }

        // ── 6. Record the loaded library ──────────────────────────────────────
        let info = PluginInfo {
            name: plugin_name.clone(),
            version,
            kind: PluginKind::Native,
            actor_type_count,
        };
        self.insert_loaded(LoadedPlugin::Native {
            _lib: lib,
            info: info.clone(),
        });

        Ok(info)
    }
}