konjure_ffi/

lib.rs

//! C-compatible, panic-contained access to the portable Konjure runtime.
//!
//! No Rust pointer is exposed as an ABI handle. A handle names a registry slot
//! and generation, so use-after-dispose and stale handles are deterministic
//! errors rather than undefined behavior.

use std::{
    panic::{AssertUnwindSafe, catch_unwind},
    sync::{Mutex, OnceLock},
};

use konjure_sdk::{EntityId, Event, Geometry, Mesh, Runtime, SceneDocument, compile, validate};
use serde::Serialize;

pub const KJ_ABI_VERSION: u32 = 1;
const MAX_JSON_BYTES: usize = 1024 * 1024;
// Dispatch mutates runtime state. The first call therefore preflights this
// bounded receipt capacity without executing the event; callers retry once with
// this capacity and observe exactly one transition.
const DISPATCH_RECEIPT_CAPACITY: usize = MAX_JSON_BYTES;

#[repr(C)]
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct KjHandle {
    pub slot: u32,
    pub generation: u32,
}

#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum KjStatus {
    Ok = 0,
    InvalidArgument = 1,
    InvalidHandle = 2,
    BufferTooSmall = 3,
    CompileError = 4,
    RuntimeError = 5,
    InternalError = 6,
}

#[derive(Serialize)]
struct MeshBatch<'a> {
    entries: Vec<MeshEntry<'a>>,
}

#[derive(Serialize)]
struct MeshEntry<'a> {
    entity: &'a EntityId,
    topology: MeshTopology,
    mesh: &'a Mesh,
}

#[derive(Serialize)]
#[serde(rename_all = "snake_case")]
enum MeshTopology {
    Triangles,
    Lines,
}

struct Entry {
    generation: u32,
    runtime: Option<Runtime>,
}

#[derive(Default)]
struct Registry {
    entries: Vec<Entry>,
}

impl Registry {
    fn insert(&mut self, runtime: Runtime) -> KjHandle {
        for (slot, entry) in self.entries.iter_mut().enumerate() {
            if entry.runtime.is_none() {
                entry.runtime = Some(runtime);
                return KjHandle {
                    slot: u32::try_from(slot).expect("registry slot fits u32"),
                    generation: entry.generation,
                };
            }
        }
        let slot = u32::try_from(self.entries.len()).expect("registry slot fits u32");
        self.entries.push(Entry {
            generation: 1,
            runtime: Some(runtime),
        });
        KjHandle {
            slot,
            generation: 1,
        }
    }

    fn get(&self, handle: KjHandle) -> Option<&Runtime> {
        self.entries
            .get(usize::try_from(handle.slot).ok()?)
            .filter(|entry| entry.generation == handle.generation)
            .and_then(|entry| entry.runtime.as_ref())
    }

    fn get_mut(&mut self, handle: KjHandle) -> Option<&mut Runtime> {
        self.entries
            .get_mut(usize::try_from(handle.slot).ok()?)
            .filter(|entry| entry.generation == handle.generation)
            .and_then(|entry| entry.runtime.as_mut())
    }

    fn remove(&mut self, handle: KjHandle) -> bool {
        let Some(entry) = self
            .entries
            .get_mut(usize::try_from(handle.slot).ok().unwrap_or(usize::MAX))
        else {
            return false;
        };
        if entry.generation != handle.generation || entry.runtime.take().is_none() {
            return false;
        }
        entry.generation = entry.generation.wrapping_add(1).max(1);
        true
    }
}

fn registry() -> &'static Mutex<Registry> {
    static REGISTRY: OnceLock<Mutex<Registry>> = OnceLock::new();
    REGISTRY.get_or_init(|| Mutex::new(Registry::default()))
}

fn write_bytes(bytes: &[u8], output: *mut u8, capacity: usize, required: *mut usize) -> KjStatus {
    if required.is_null() {
        return KjStatus::InvalidArgument;
    }
    // SAFETY: `required` was checked non-null and is caller-owned writable storage.
    unsafe {
        *required = bytes.len();
    }
    if bytes.is_empty() {
        return KjStatus::Ok;
    }
    if output.is_null() || capacity < bytes.len() {
        return KjStatus::BufferTooSmall;
    }
    // SAFETY: caller provides an output region with at least `bytes.len()` bytes.
    unsafe {
        std::ptr::copy_nonoverlapping(bytes.as_ptr(), output, bytes.len());
    }
    KjStatus::Ok
}

fn write_error(message: &str, output: *mut u8, capacity: usize, required: *mut usize) {
    let _ = write_bytes(message.as_bytes(), output, capacity, required);
}

fn read_utf8<'a>(input: *const u8, length: usize, max: usize) -> Result<&'a str, KjStatus> {
    if length > max || (length > 0 && input.is_null()) {
        return Err(KjStatus::InvalidArgument);
    }
    // `from_raw_parts` requires a non-null pointer even for an empty slice.
    // Empty C input is valid and lets the Rust parser produce its normal diagnostic.
    if length == 0 {
        return Ok("");
    }
    // SAFETY: the C caller contract requires a readable `length`-byte region when nonempty.
    let bytes = unsafe { std::slice::from_raw_parts(input, length) };
    std::str::from_utf8(bytes).map_err(|_| KjStatus::InvalidArgument)
}

fn contained(
    error: *mut u8,
    error_capacity: usize,
    error_required: *mut usize,
    operation: impl FnOnce() -> Result<KjStatus, (KjStatus, String)>,
) -> KjStatus {
    match catch_unwind(AssertUnwindSafe(operation)) {
        Ok(Ok(status)) => {
            write_error("", error, error_capacity, error_required);
            status
        }
        Ok(Err((status, message))) => {
            write_error(&message, error, error_capacity, error_required);
            status
        }
        Err(_) => {
            write_error(
                "internal Konjure panic contained at FFI boundary",
                error,
                error_capacity,
                error_required,
            );
            KjStatus::InternalError
        }
    }
}

fn serialize<T: serde::Serialize>(
    value: &T,
    output: *mut u8,
    capacity: usize,
    required: *mut usize,
) -> Result<KjStatus, (KjStatus, String)> {
    serde_json::to_vec(value)
        .map(|bytes| write_bytes(&bytes, output, capacity, required))
        .map_err(|error| (KjStatus::InternalError, error.to_string()))
}

#[derive(Clone, Copy)]
struct OutputBuffer {
    output: *mut u8,
    capacity: usize,
    required: *mut usize,
}

#[derive(Clone, Copy)]
struct ErrorBuffer {
    output: *mut u8,
    capacity: usize,
    required: *mut usize,
}

/// Returns the ABI major version implemented by this library.
#[unsafe(no_mangle)]
pub extern "C" fn kj_abi_version() -> u32 {
    KJ_ABI_VERSION
}

/// Compiles DSL source and places a generation-safe runtime handle in `out_handle`.
///
/// # Safety
/// Non-null pointer arguments must point to readable/writable regions described by
/// their corresponding lengths. Error buffers are optional but `error_required` is required.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn kj_runtime_compile(
    source: *const u8,
    source_len: usize,
    out_handle: *mut KjHandle,
    error: *mut u8,
    error_capacity: usize,
    error_required: *mut usize,
) -> KjStatus {
    contained(error, error_capacity, error_required, || {
        if out_handle.is_null() {
            return Err((KjStatus::InvalidArgument, "out_handle is required".into()));
        }
        let source = read_utf8(source, source_len, konjure_sdk::MAX_SOURCE_BYTES)
            .map_err(|status| (status, "source must be valid bounded UTF-8".into()))?;
        let scene = compile(source).map_err(|error| (KjStatus::CompileError, error.to_string()))?;
        let runtime =
            Runtime::new(scene).map_err(|error| (KjStatus::RuntimeError, error.to_string()))?;
        let handle = registry()
            .lock()
            .map_err(|_| (KjStatus::InternalError, "runtime registry poisoned".into()))?
            .insert(runtime);
        // SAFETY: checked non-null and caller promises writable KjHandle storage.
        unsafe {
            *out_handle = handle;
        }
        Ok(KjStatus::Ok)
    })
}

/// Creates a runtime from a serialized `SceneDocument` JSON value.
///
/// # Safety
/// See [`kj_runtime_compile`].
#[unsafe(no_mangle)]
pub unsafe extern "C" fn kj_runtime_from_document_json(
    document: *const u8,
    document_len: usize,
    out_handle: *mut KjHandle,
    error: *mut u8,
    error_capacity: usize,
    error_required: *mut usize,
) -> KjStatus {
    contained(error, error_capacity, error_required, || {
        if out_handle.is_null() {
            return Err((KjStatus::InvalidArgument, "out_handle is required".into()));
        }
        let document = read_utf8(document, document_len, MAX_JSON_BYTES)
            .map_err(|status| (status, "document must be valid bounded UTF-8".into()))?;
        let scene: SceneDocument = serde_json::from_str(document)
            .map_err(|error| (KjStatus::InvalidArgument, error.to_string()))?;
        validate(&scene).map_err(|error| (KjStatus::RuntimeError, error.to_string()))?;
        let handle = registry()
            .lock()
            .map_err(|_| (KjStatus::InternalError, "runtime registry poisoned".into()))?
            .insert(Runtime::new(scene).expect("validated scene constructs runtime"));
        // SAFETY: checked non-null and caller promises writable KjHandle storage.
        unsafe {
            *out_handle = handle;
        }
        Ok(KjStatus::Ok)
    })
}

/// Disposes a runtime. A second disposal, or any stale copied handle, returns `InvalidHandle`.
#[unsafe(no_mangle)]
pub extern "C" fn kj_runtime_dispose(
    handle: KjHandle,
    error: *mut u8,
    error_capacity: usize,
    error_required: *mut usize,
) -> KjStatus {
    contained(error, error_capacity, error_required, || {
        if registry()
            .lock()
            .map_err(|_| (KjStatus::InternalError, "runtime registry poisoned".into()))?
            .remove(handle)
        {
            Ok(KjStatus::Ok)
        } else {
            Err((
                KjStatus::InvalidHandle,
                "invalid or disposed runtime handle".into(),
            ))
        }
    })
}

fn query(
    handle: KjHandle,
    output: OutputBuffer,
    error: ErrorBuffer,
    operation: impl FnOnce(&Runtime) -> Result<Vec<u8>, String>,
) -> KjStatus {
    contained(error.output, error.capacity, error.required, || {
        let registry = registry()
            .lock()
            .map_err(|_| (KjStatus::InternalError, "runtime registry poisoned".into()))?;
        let runtime = registry.get(handle).ok_or((
            KjStatus::InvalidHandle,
            "invalid or disposed runtime handle".into(),
        ))?;
        let bytes = operation(runtime).map_err(|message| (KjStatus::RuntimeError, message))?;
        Ok(write_bytes(
            &bytes,
            output.output,
            output.capacity,
            output.required,
        ))
    })
}

/// Serializes the authoritative scene document as UTF-8 JSON.
#[unsafe(no_mangle)]
pub extern "C" fn kj_runtime_scene_json(
    handle: KjHandle,
    output: *mut u8,
    capacity: usize,
    required: *mut usize,
    error: *mut u8,
    error_capacity: usize,
    error_required: *mut usize,
) -> KjStatus {
    query(
        handle,
        OutputBuffer {
            output,
            capacity,
            required,
        },
        ErrorBuffer {
            output: error,
            capacity: error_capacity,
            required: error_required,
        },
        |runtime| serde_json::to_vec(runtime.scene()).map_err(|error| error.to_string()),
    )
}

/// Serializes all prepared meshes as `{ "entries": [{ "entity", "topology", "mesh" }] }` JSON.
#[unsafe(no_mangle)]
pub extern "C" fn kj_runtime_meshes_json(
    handle: KjHandle,
    output: *mut u8,
    capacity: usize,
    required: *mut usize,
    error: *mut u8,
    error_capacity: usize,
    error_required: *mut usize,
) -> KjStatus {
    query(
        handle,
        OutputBuffer {
            output,
            capacity,
            required,
        },
        ErrorBuffer {
            output: error,
            capacity: error_capacity,
            required: error_required,
        },
        |runtime| {
            let entries = runtime
                .meshes()
                .iter()
                .map(|(entity, mesh)| {
                    let is_line = runtime
                        .scene()
                        .entities
                        .iter()
                        .find(|candidate| candidate.id == *entity)
                        .is_some_and(|candidate| {
                            matches!(&candidate.geometry, Geometry::Line { .. })
                        });
                    let topology = if is_line {
                        MeshTopology::Lines
                    } else {
                        MeshTopology::Triangles
                    };
                    MeshEntry {
                        entity,
                        topology,
                        mesh,
                    }
                })
                .collect();
            serde_json::to_vec(&MeshBatch { entries }).map_err(|error| error.to_string())
        },
    )
}

/// Samples a deterministic frame and serializes it as UTF-8 JSON.
#[unsafe(no_mangle)]
pub extern "C" fn kj_runtime_sample_json(
    handle: KjHandle,
    time_seconds: f64,
    output: *mut u8,
    capacity: usize,
    required: *mut usize,
    error: *mut u8,
    error_capacity: usize,
    error_required: *mut usize,
) -> KjStatus {
    query(
        handle,
        OutputBuffer {
            output,
            capacity,
            required,
        },
        ErrorBuffer {
            output: error,
            capacity: error_capacity,
            required: error_required,
        },
        |runtime| {
            runtime
                .sample(time_seconds)
                .and_then(|frame| {
                    serde_json::to_vec(&frame).map_err(|error| konjure_sdk::Diagnostic {
                        message: error.to_string(),
                        span: None,
                    })
                })
                .map_err(|error| error.to_string())
        },
    )
}

/// Dispatches a serialized `Event` and serializes its receipt as UTF-8 JSON.
///
/// # Safety
/// `event` must describe a readable UTF-8 byte region of `event_len` bytes when nonempty.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn kj_runtime_dispatch_json(
    handle: KjHandle,
    event: *const u8,
    event_len: usize,
    output: *mut u8,
    capacity: usize,
    required: *mut usize,
    error: *mut u8,
    error_capacity: usize,
    error_required: *mut usize,
) -> KjStatus {
    contained(error, error_capacity, error_required, || {
        let event = read_utf8(event, event_len, MAX_JSON_BYTES)
            .map_err(|status| (status, "event must be valid bounded UTF-8".into()))?;
        let event: Event = serde_json::from_str(event)
            .map_err(|error| (KjStatus::InvalidArgument, error.to_string()))?;
        if required.is_null() {
            return Err((KjStatus::InvalidArgument, "required is required".into()));
        }
        // SAFETY: `required` was checked non-null and is caller-owned writable storage.
        unsafe {
            *required = DISPATCH_RECEIPT_CAPACITY;
        }
        if output.is_null() || capacity < DISPATCH_RECEIPT_CAPACITY {
            return Ok(KjStatus::BufferTooSmall);
        }
        let mut registry = registry()
            .lock()
            .map_err(|_| (KjStatus::InternalError, "runtime registry poisoned".into()))?;
        let runtime = registry.get_mut(handle).ok_or((
            KjStatus::InvalidHandle,
            "invalid or disposed runtime handle".into(),
        ))?;
        serialize(
            &runtime
                .dispatch(event)
                .map_err(|error| (KjStatus::RuntimeError, error.to_string()))?,
            output,
            capacity,
            required,
        )
    })
}

#[cfg(test)]
mod tests {
    use super::*;

    const SOURCE: &str =
        "scene orbit { node star { sphere 0.2m; color #ffffff; action pause toggle_motion; } }";

    fn compile_runtime() -> KjHandle {
        let mut handle = KjHandle::default();
        let mut error_len = 0;
        assert_eq!(
            unsafe {
                kj_runtime_compile(
                    SOURCE.as_ptr(),
                    SOURCE.len(),
                    &mut handle,
                    std::ptr::null_mut(),
                    0,
                    &mut error_len,
                )
            },
            KjStatus::Ok
        );
        handle
    }

    #[test]
    fn abi_and_two_pass_buffers_are_stable() {
        assert_eq!(kj_abi_version(), KJ_ABI_VERSION);
        let handle = compile_runtime();
        let mut required = 0;
        let mut error_len = 0;
        assert_eq!(
            kj_runtime_sample_json(
                handle,
                0.0,
                std::ptr::null_mut(),
                0,
                &mut required,
                std::ptr::null_mut(),
                0,
                &mut error_len
            ),
            KjStatus::BufferTooSmall
        );
        let mut buffer = vec![0; required];
        assert_eq!(
            kj_runtime_sample_json(
                handle,
                0.0,
                buffer.as_mut_ptr(),
                buffer.len(),
                &mut required,
                std::ptr::null_mut(),
                0,
                &mut error_len
            ),
            KjStatus::Ok
        );
        assert!(
            std::str::from_utf8(&buffer)
                .unwrap()
                .contains("time_seconds")
        );
        assert_eq!(
            kj_runtime_dispose(handle, std::ptr::null_mut(), 0, &mut error_len),
            KjStatus::Ok
        );
    }

    #[test]
    fn rejects_bad_handles_and_double_dispose() {
        let handle = KjHandle {
            slot: 99,
            generation: 1,
        };
        let mut error_len = 0;
        assert_eq!(
            kj_runtime_dispose(handle, std::ptr::null_mut(), 0, &mut error_len),
            KjStatus::InvalidHandle
        );
        let handle = compile_runtime();
        assert_eq!(
            kj_runtime_dispose(handle, std::ptr::null_mut(), 0, &mut error_len),
            KjStatus::Ok
        );
        assert_eq!(
            kj_runtime_dispose(handle, std::ptr::null_mut(), 0, &mut error_len),
            KjStatus::InvalidHandle
        );
    }

    #[test]
    fn reports_invalid_utf8_per_call() {
        let invalid = [0xff];
        let mut handle = KjHandle::default();
        let mut error_len = 0;
        assert_eq!(
            unsafe {
                kj_runtime_compile(
                    invalid.as_ptr(),
                    invalid.len(),
                    &mut handle,
                    std::ptr::null_mut(),
                    0,
                    &mut error_len,
                )
            },
            KjStatus::InvalidArgument
        );
        assert!(error_len > 0);
    }

    #[test]
    fn accepts_null_empty_input_without_undefined_behavior() {
        let mut handle = KjHandle::default();
        let mut error_len = 0;
        assert_eq!(
            unsafe {
                kj_runtime_compile(
                    std::ptr::null(),
                    0,
                    &mut handle,
                    std::ptr::null_mut(),
                    0,
                    &mut error_len,
                )
            },
            KjStatus::CompileError
        );
        assert!(error_len > 0);
    }

    #[test]
    fn undersized_dispatch_output_does_not_apply_the_event() {
        let handle = compile_runtime();
        let mut required = 0;
        let mut error_len = 0;
        let event = br#"{"kind":"invoke_action","entity":"star","action":"pause"}"#;
        assert_eq!(
            unsafe {
                kj_runtime_dispatch_json(
                    handle,
                    event.as_ptr(),
                    event.len(),
                    std::ptr::null_mut(),
                    0,
                    &mut required,
                    std::ptr::null_mut(),
                    0,
                    &mut error_len,
                )
            },
            KjStatus::BufferTooSmall
        );
        assert_eq!(required, DISPATCH_RECEIPT_CAPACITY);
        let mut frame_required = 0;
        assert_eq!(
            kj_runtime_sample_json(
                handle,
                0.0,
                std::ptr::null_mut(),
                0,
                &mut frame_required,
                std::ptr::null_mut(),
                0,
                &mut error_len
            ),
            KjStatus::BufferTooSmall
        );
        let mut frame = vec![0; frame_required];
        assert_eq!(
            kj_runtime_sample_json(
                handle,
                0.0,
                frame.as_mut_ptr(),
                frame.len(),
                &mut frame_required,
                std::ptr::null_mut(),
                0,
                &mut error_len
            ),
            KjStatus::Ok
        );
        assert!(
            !std::str::from_utf8(&frame)
                .unwrap()
                .contains("action_applied")
        );
        let mut receipt = vec![0; required];
        assert_eq!(
            unsafe {
                kj_runtime_dispatch_json(
                    handle,
                    event.as_ptr(),
                    event.len(),
                    receipt.as_mut_ptr(),
                    receipt.len(),
                    &mut required,
                    std::ptr::null_mut(),
                    0,
                    &mut error_len,
                )
            },
            KjStatus::Ok
        );
        assert!(
            std::str::from_utf8(&receipt[..required])
                .unwrap()
                .contains("action_applied")
        );
    }
}