ffi_bridge/lib.rs
1//! # ffi-bridge
2//!
3//! Memory-safe Go↔Rust FFI boundary helpers.
4//!
5//! This crate provides:
6//! - [`FfiBuffer`] — heap-allocated byte buffer with explicit ownership semantics
7//! - [`FfiString`] — UTF-8 string safe for crossing the FFI boundary
8//! - [`FfiResult`] — C-ABI result type conveying either a payload or an error
9//! - [`FfiError`] / [`FfiErrorCode`] — rich error taxonomy matching the C header
10//! - Callback registry — register and invoke named callbacks across the FFI boundary
11//! - [`catch_panic`] — converts Rust panics to [`FfiResult`] so they never cross the ABI
12//!
13//! ## Safety contract
14//!
15//! * All buffers and strings allocated by this crate **must** be freed by the
16//! corresponding `ffi_*_free` function exported from this crate.
17//! * Panics are caught at every `extern "C"` boundary via [`catch_panic`].
18//! * No Rust type with a `Drop` impl is allowed to cross the FFI boundary as a value;
19//! only `repr(C)` POD structs may do so.
20
21pub mod bridge;
22pub mod callback;
23pub mod errors;
24pub mod memory;
25pub mod types;
26
27pub use bridge::*;
28pub use callback::{
29 callback_count, ffi_callback_count, ffi_invoke_callback, ffi_register_callback,
30 ffi_unregister_callback, register_callback, unregister_callback,
31};
32pub use errors::{catch_panic, ffi_result_free, FfiError, FfiErrorCode, FfiResult};
33pub use memory::{
34 ffi_buffer_alloc, ffi_buffer_free, ffi_string_alloc, ffi_string_free, FfiBuffer, FfiString,
35};
36pub use types::*;