polyplug_guest 0.1.1

//! polyplug guest library — Rust bindings for guest-side (plugin developer) use.
//!
//! This crate provides the ABI types, allocator hookup, and registration
//! helpers that plugin authors need to implement a polyplug contract.
//!
//! # Quick Start
//!
//! With `polyplugc`-generated glue, a plugin author writes a trait impl plus
//! one exported factory per plugin. The generated `create_instance` calls the
//! factory for every instance the host creates and carries the returned
//! implementation (plus the [`HostContext`]) in `GuestContractInstance.data`:
//!
//! ```rust,ignore
//! // In Cargo.toml: crate-type = ["cdylib"]
//! use polyplug_guest::HostContext;
//!
//! #[path = "../generated/guest/mod.rs"]
//! mod generated;
//! use generated::contracts::MyContractGuestContract;
//!
//! struct Plugin {
//!     /// Host handle for this runtime — use it for alloc_string / log / peers.
//!     host: HostContext,
//! }
//!
//! impl MyContractGuestContract for Plugin {
//!     fn my_fn(&self, input: u32) -> Result<u32, polyplug_guest::GuestError> {
//!         self.host.log(polyplug_abi::types::LogLevel::Info, "guest.my_plugin", "called");
//!         Ok(input + 1)
//!     }
//! }
//!
//! /// Factory the generated `create_instance` glue calls for every instance.
//! /// The symbol name is fixed: `polyplug_create_<plugin_name>`.
//! #[unsafe(no_mangle)]
//! pub fn polyplug_create_my_plugin(host: HostContext) -> Box<dyn MyContractGuestContract> {
//!     Box::new(Plugin { host })
//! }
//!
//! /// ABI version sentinel — exported by the plugin crate itself.
//! #[unsafe(no_mangle)]
//! pub extern "C" fn polyplug_abi_version() -> u32 { polyplug_abi::POLYPLUG_ABI_VERSION }
//! ```
//!
//! `polyplug_init` itself is generated (`generated/guest/init.rs`): it only
//! registers the static interface tables. No implementation or host pointer is
//! ever stored in process-wide state.
//!
//! # Status
//! Scaffold only. Full implementation is code-generated by `polyplugc`.
//!
//! # Host access — instance flow, no statics
//! This crate holds NO process-wide state. The host [`HostApi`] pointer flows
//! from `create_instance` (where the host passes it) into a [`HostContext`]
//! that the generated glue hands to the author factory and stores in the
//! per-instance payload carried by `GuestContractInstance.data`. Every host
//! call (allocation, logging, peer dispatch) is therefore routed to the exact
//! `Runtime` that owns the in-flight call — multiple runtimes sharing one
//! plugin dylib in the same process stay fully isolated.

use polyplug_abi::{AbiErrorCode, HostApi, StringView};

/// Per-instance handle to the host runtime that created a plugin instance.
///
/// Captured by the generated `create_instance` glue from the `HostApi`
/// pointer the host passes in, handed to the author factory
/// (`polyplug_create_<plugin>`), and stored in the instance payload. All
/// guest→host operations (allocation, logging, peer-caller resolution) go
/// through a `HostContext` — there is no process-wide host storage.
#[derive(Clone, Copy)]
pub struct HostContext {
    /// The host's function table for the owning runtime.
    host: *const HostApi,
}

// SAFETY: HostContext wraps a host interface pointer provided by the host runtime.
// The interface is immutable and valid for the plugin's lifetime. Multiple threads may read
// from the same interface concurrently — the host ensures thread-safe access to interface data.
unsafe impl Send for HostContext {}

// SAFETY: The host interface is read-only memory owned by the runtime. Multiple threads may
// access the same interface concurrently without synchronization. The host runtime guarantees
// the interface remains valid and unchanged for the plugin's lifetime.
unsafe impl Sync for HostContext {}

impl HostContext {
    /// Wrap a raw `HostApi` pointer received from the host.
    ///
    /// # Safety
    /// `host` must be a valid `HostApi` pointer provided by the host runtime
    /// (e.g. the first argument of `create_instance` or `polyplug_init`) and
    /// must remain valid for as long as this context is used.
    pub unsafe fn new(host: *const HostApi) -> Self {
        Self { host }
    }

    /// The raw `HostApi` pointer, for generated glue and ABI-level calls.
    pub fn as_ptr(self) -> *const HostApi {
        self.host
    }

    /// Returns `true` when this context carries no host pointer.
    pub fn is_null(self) -> bool {
        self.host.is_null()
    }

    /// Allocate a `StringView` from a `&str` using this runtime's host allocator.
    ///
    /// Allocates through `HostApi.alloc` (align 1), so the bytes are owned by
    /// the host and never link a separate allocator copy into the plugin dylib.
    /// The receiver (host) is responsible for freeing the memory via
    /// `host.free(host, ptr, len, 1)`.
    ///
    /// # Errors
    /// Returns `Err(GuestError)` if this context is null or allocation fails.
    pub fn alloc_string(self, s: &str) -> Result<StringView, GuestError> {
        if self.host.is_null() {
            return Err(GuestError {
                code: AbiErrorCode::Generic,
                message: "host interface unavailable".to_string(),
            });
        }
        let bytes: &[u8] = s.as_bytes();
        // SAFETY: self.host is non-null (checked above) and valid per the
        // HostContext::new contract. `alloc` is a valid function pointer set by the host.
        let ptr: *mut u8 = unsafe { ((*self.host).alloc)(self.host, bytes.len(), 1) };
        if ptr.is_null() {
            return Err(GuestError {
                code: AbiErrorCode::Generic,
                message: "allocation failed".to_string(),
            });
        }
        // SAFETY: ptr is non-null (checked above) and was allocated by host.alloc
        // with size bytes.len() and align 1. The source bytes.as_ptr() is valid for
        // bytes.len() bytes. The destination is valid for bytes.len() bytes.
        unsafe { core::ptr::copy_nonoverlapping(bytes.as_ptr(), ptr, bytes.len()) };
        Ok(StringView {
            ptr,
            len: bytes.len(),
        })
    }

    /// Log a diagnostic into this runtime's logging funnel (`HostApi.log`).
    ///
    /// Routes to the same sink as the host's `RuntimeConfig::log` callback (or
    /// its stderr default). `scope` should be a short stable tag, e.g.
    /// `"guest.<plugin-name>"`. No-op when this context is null.
    pub fn log(self, level: polyplug_abi::types::LogLevel, scope: &str, message: &str) {
        if self.host.is_null() {
            return;
        }
        let scope_view = StringView {
            ptr: scope.as_ptr(),
            len: scope.len(),
        };
        let message_view = StringView {
            ptr: message.as_ptr(),
            len: message.len(),
        };
        // SAFETY: self.host is non-null (checked above) and valid per the
        // HostContext::new contract; `log` is always provided by the runtime. Both
        // views borrow live UTF-8 Rust string data that outlives the synchronous
        // call, matching the field's documented ownership contract.
        unsafe { ((*self.host).log)(self.host, level as u32, scope_view, message_view) }
    }
}

// ─── Helper Functions ─────────────────────────────────────────────────────────

/// Create an AbiError panic response.
pub fn abi_error_panic_caught() -> polyplug_abi::AbiError {
    polyplug_abi::AbiError::panic_caught()
}

// ─── Helper Types ─────────────────────────────────────────────────────────────

/// Wrapper for a function pointer stored in a static vtable array.
///
/// Raw `*const ()` does not implement `Sync`, but function pointers in a
/// `static` array are effectively `'static` and immutable.
/// Wrap each function pointer in `FnPtr` when building your vtable's
/// `functions` array.
///
/// # Example
/// ```rust,ignore
/// // Out-param ABI: native dispatch fns return void and write their AbiError
/// // through the trailing out_err pointer.
/// extern "C" fn my_fn(
///     _instance: GuestContractInstance,
///     args: *const (),
///     out: *mut (),
///     out_err: *mut AbiError,
/// ) {
///     if !out_err.is_null() { unsafe { out_err.write(AbiError::ok()) }; }
/// }
/// static MY_FNS: [FnPtr; 1] = [FnPtr(my_fn as *const ())];
/// ```
#[repr(transparent)]
pub struct FnPtr(pub *const ());

// SAFETY: FnPtr wraps a 'static function pointer. Function pointers are safe
// to share across threads — the function itself handles its own synchronization.
unsafe impl Send for FnPtr {}
// SAFETY: Function pointers are inherently Sync — multiple threads may call
// the same function concurrently. The data is read-only 'static memory.
unsafe impl Sync for FnPtr {}

/// Error returned from guest-side plugin trait methods.
///
/// Produced by generated ABI wrappers when an ABI call returns a non-zero code.
/// Plugin developers return `Result<T, GuestError>` from their trait implementations.
#[derive(Debug)]
pub struct GuestError {
    /// ABI error code (non-zero).
    pub code: AbiErrorCode,
    /// Human-readable error message. May be empty.
    pub message: String,
}

impl core::fmt::Display for GuestError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(
            f,
            "GuestError(code={}, message={})",
            self.code, self.message
        )
    }
}

impl core::error::Error for GuestError {}

// ─── String Helpers ───────────────────────────────────────────────────────────

/// Convert a `StringView` to a `&str` borrowing for the view's lifetime.
///
/// A null or zero-length view decodes to `Ok("")`. A non-null view whose bytes
/// are NOT valid UTF-8 returns `Err(GuestError)` — the helper never silently
/// substitutes `""` for a readable-but-invalid view. (A panic is not an option:
/// these helpers run inside `extern "C"` guest dispatch, where unwinding across
/// the C ABI boundary is undefined behaviour, so the error is surfaced as a
/// `Result` instead.)
///
/// # Safety
/// - `sv.ptr` must either be null or point to `sv.len` initialized bytes that
///   stay valid and immutable for the entire lifetime `'a` of the borrow.
///
/// The returned `&'a str` is tied to the borrow of `sv`, so it cannot outlive
/// the `StringView` it was derived from. This is `unsafe` because the validity
/// and lifetime of `sv.ptr` cannot be checked here.
///
/// # Example
/// ```rust
/// use polyplug_abi::StringView;
/// use polyplug_guest::to_str;
///
/// let sv = StringView { ptr: b"hello".as_ptr(), len: 5 };
/// // SAFETY: `sv` borrows a live byte slice for the duration of this call.
/// let s: &str = unsafe { to_str(&sv) }.expect("valid UTF-8");
/// assert_eq!(s, "hello");
/// ```
pub unsafe fn to_str(sv: &StringView) -> Result<&str, GuestError> {
    if sv.ptr.is_null() || sv.len == 0 {
        return Ok("");
    }
    // SAFETY: sv.ptr is non-null (checked above) and sv.len is the valid length.
    // The caller guarantees, via this function's `# Safety` contract, that the
    // pointer is valid for sv.len bytes for the lifetime 'a.
    match unsafe { core::str::from_utf8(core::slice::from_raw_parts(sv.ptr, sv.len)) } {
        Ok(s) => Ok(s),
        Err(e) => Err(GuestError {
            code: AbiErrorCode::Generic,
            message: format!("StringView contains invalid UTF-8: {e}"),
        }),
    }
}

/// Check if a `StringView` starts with the given prefix.
///
/// # Safety
/// Same contract as [`to_str`]: `sv` must point to valid, live UTF-8 bytes for
/// the duration of the call.
///
/// # Example
/// ```rust
/// use polyplug_abi::StringView;
/// use polyplug_guest::starts_with;
///
/// let sv = StringView { ptr: b"hello world".as_ptr(), len: 11 };
/// // SAFETY: `sv` borrows a live byte slice for the duration of this call.
/// assert!(unsafe { starts_with(&sv, "hello") }.expect("valid UTF-8"));
/// assert!(!unsafe { starts_with(&sv, "world") }.expect("valid UTF-8"));
/// ```
///
/// Returns `Err(GuestError)` if the view's bytes are not valid UTF-8 (it decodes
/// via [`to_str`], which validates).
pub unsafe fn starts_with(sv: &StringView, prefix: &str) -> Result<bool, GuestError> {
    // SAFETY: forwarded to the caller via this function's `# Safety` contract.
    let s: &str = unsafe { to_str(sv) }?;
    Ok(s.starts_with(prefix))
}

/// Check if a `StringView` ends with the given suffix.
///
/// # Safety
/// Same contract as [`to_str`]: `sv` must point to valid, live UTF-8 bytes for
/// the duration of the call.
///
/// # Example
/// ```rust
/// use polyplug_abi::StringView;
/// use polyplug_guest::ends_with;
///
/// let sv = StringView { ptr: b"hello world".as_ptr(), len: 11 };
/// // SAFETY: `sv` borrows a live byte slice for the duration of this call.
/// assert!(unsafe { ends_with(&sv, "world") }.expect("valid UTF-8"));
/// assert!(!unsafe { ends_with(&sv, "hello") }.expect("valid UTF-8"));
/// ```
///
/// Returns `Err(GuestError)` if the view's bytes are not valid UTF-8 (it decodes
/// via [`to_str`], which validates).
pub unsafe fn ends_with(sv: &StringView, suffix: &str) -> Result<bool, GuestError> {
    // SAFETY: forwarded to the caller via this function's `# Safety` contract.
    let s: &str = unsafe { to_str(sv) }?;
    Ok(s.ends_with(suffix))
}

/// Strip a prefix from a `StringView` if present.
///
/// Returns the remaining string slice if the prefix was present,
/// otherwise returns the original string. The returned slice borrows for the
/// lifetime of `sv`. Returns `Err(GuestError)` if the view's bytes are not
/// valid UTF-8 (it decodes via [`to_str`], which validates).
///
/// # Safety
/// Same contract as [`to_str`]: `sv` must point to valid, live UTF-8 bytes for
/// the lifetime `'a` of the borrow.
///
/// # Example
/// ```rust
/// use polyplug_abi::StringView;
/// use polyplug_guest::strip_prefix;
///
/// let sv = StringView { ptr: b"hello world".as_ptr(), len: 11 };
/// // SAFETY: `sv` borrows a live byte slice for the duration of this call.
/// assert_eq!(unsafe { strip_prefix(&sv, "hello ") }.expect("valid UTF-8"), "world");
/// assert_eq!(unsafe { strip_prefix(&sv, "goodbye") }.expect("valid UTF-8"), "hello world");
/// ```
pub unsafe fn strip_prefix<'a>(sv: &'a StringView, prefix: &str) -> Result<&'a str, GuestError> {
    // SAFETY: forwarded to the caller via this function's `# Safety` contract.
    let s: &'a str = unsafe { to_str(sv) }?;
    match s.strip_prefix(prefix) {
        Some(remaining) => Ok(remaining),
        None => Ok(s),
    }
}

/// Split a `StringView` by a literal delimiter, keeping empty segments.
///
/// Returns a vector of string slices borrowing for the lifetime of `sv`. A
/// null or empty view returns an empty vector; an empty delimiter returns the
/// whole string as a single element. Leading, trailing, and consecutive
/// delimiters produce empty strings in the output. Returns `Err(GuestError)`
/// if the view's bytes are not valid UTF-8 (it decodes via [`to_str`], which
/// validates).
///
/// # Safety
/// Same contract as [`to_str`]: `sv` must point to valid, live UTF-8 bytes for
/// the lifetime `'a` of the borrow.
///
/// # Example
/// ```rust
/// use polyplug_abi::StringView;
/// use polyplug_guest::split;
///
/// let sv = StringView { ptr: b"a,b,c".as_ptr(), len: 5 };
/// // SAFETY: `sv` borrows a live byte slice for the duration of this call.
/// let parts: Vec<&str> = unsafe { split(&sv, ",") }.expect("valid UTF-8");
/// assert_eq!(parts, vec!["a", "b", "c"]);
/// ```
pub unsafe fn split<'a>(sv: &'a StringView, delimiter: &str) -> Result<Vec<&'a str>, GuestError> {
    // SAFETY: forwarded to the caller via this function's `# Safety` contract.
    let s: &'a str = unsafe { to_str(sv) }?;
    if s.is_empty() {
        return Ok(Vec::new());
    }
    if delimiter.is_empty() {
        return Ok(vec![s]);
    }
    Ok(s.split(delimiter).collect())
}

#[cfg(test)]
mod tests {
    use polyplug_abi::StringView;

    fn view(bytes: &[u8]) -> StringView {
        StringView {
            ptr: bytes.as_ptr(),
            len: bytes.len(),
        }
    }

    #[test]
    fn to_str_null_view_is_empty() {
        let sv = StringView {
            ptr: core::ptr::null(),
            len: 5,
        };
        // SAFETY: a null view is explicitly legal input for to_str.
        assert_eq!(unsafe { crate::to_str(&sv) }.ok(), Some(""));
    }

    #[test]
    fn to_str_zero_len_view_is_empty() {
        let sv: StringView = view(b"x");
        let sv = StringView { len: 0, ..sv };
        // SAFETY: the view borrows a live byte slice for the duration of the call.
        assert_eq!(unsafe { crate::to_str(&sv) }.ok(), Some(""));
    }

    #[test]
    fn to_str_invalid_utf8_errors() {
        // 0xFF is never a valid UTF-8 byte; a readable-but-invalid view must
        // return Err, never silently yield "".
        let sv: StringView = view(&[0x68, 0x69, 0xFF]);
        assert!(matches!(
            // SAFETY: the view borrows a live byte slice for the duration of the call.
            unsafe { crate::to_str(&sv) },
            Err(e) if e.code == polyplug_abi::AbiErrorCode::Generic
        ));
    }

    #[test]
    fn derived_helpers_propagate_invalid_utf8_error() {
        let sv: StringView = view(&[0xFF, 0xFE]);
        // SAFETY: the view borrows a live byte slice for the duration of the call.
        assert!(unsafe { crate::starts_with(&sv, "x") }.is_err());
        // SAFETY: same live borrow.
        assert!(unsafe { crate::ends_with(&sv, "x") }.is_err());
        // SAFETY: same live borrow.
        assert!(unsafe { crate::strip_prefix(&sv, "x") }.is_err());
        // SAFETY: same live borrow.
        assert!(unsafe { crate::split(&sv, "|") }.is_err());
    }

    #[test]
    fn split_keeps_consecutive_empty_segments() {
        let sv: StringView = view(b"a||b");
        assert_eq!(
            // SAFETY: the view borrows a live byte slice for the duration of the call.
            unsafe { crate::split(&sv, "|") }.ok(),
            Some(vec!["a", "", "b"])
        );
    }

    #[test]
    fn split_keeps_leading_and_trailing_empty_segments() {
        let sv: StringView = view(b"|a|");
        assert_eq!(
            // SAFETY: the view borrows a live byte slice for the duration of the call.
            unsafe { crate::split(&sv, "|") }.ok(),
            Some(vec!["", "a", ""])
        );
    }

    #[test]
    fn split_empty_view_is_empty_list() {
        let sv = StringView {
            ptr: core::ptr::null(),
            len: 0,
        };
        // SAFETY: a null view is explicitly legal input for split.
        assert_eq!(unsafe { crate::split(&sv, "|") }.ok(), Some(Vec::new()));
    }

    #[test]
    fn split_empty_delimiter_returns_whole_string() {
        let sv: StringView = view(b"ab");
        // SAFETY: the view borrows a live byte slice for the duration of the call.
        assert_eq!(unsafe { crate::split(&sv, "") }.ok(), Some(vec!["ab"]));
    }

    #[test]
    fn split_multibyte_literal_delimiter() {
        let sv: StringView = view(b"a::b::c");
        assert_eq!(
            // SAFETY: the view borrows a live byte slice for the duration of the call.
            unsafe { crate::split(&sv, "::") }.ok(),
            Some(vec!["a", "b", "c"])
        );
    }
}