The WebKit Native ABI
Keep the dynamically loaded bridge, its thread-owned view, and transferred descriptors valid across every native call.
The Rust package loads libhera-wpe.so at runtime through a private C interface. This keeps WPE-specific symbols out of ordinary application code, while placing responsibility for library lifetime, ABI validation, and unsafe calls in crates/webkit/src/ffi.rs.
The native ABI version is independent of the Hera wire protocol. A matching server handshake does not prove that an arbitrary bridge library has compatible function signatures or frame structures, so the package checks both boundaries in their respective layers.
Symbol Validation
Loading begins with hw_abi_version, which must report ABI 2. The loader then resolves every required entry point for view lifecycle, navigation, state strings, input, frames, and damage before calling hw_create.
The C header and Rust declarations must agree on field order, integer width, alignment, command values, and input-kind values. HWFrame is currently 40 bytes and HWFrameDamage is 1040 bytes under this ABI. Native static assertions and Rust tests check important parts of that layout, while paired declarations remain the source of truth for the complete call contract.
Load only the trusted bridge built for the application deployment. The version check detects an incompatible declared ABI; it does not turn arbitrary native code into a sandboxed or memory-safe plugin.
Code and Native State Lifetime
The owning Api retains the library together with the resolved function pointers, and NativeView retains both that API and the created handle. On Linux, loading also uses RTLD_NODELETE because WPE background threads and registered GLib types may outlive one view. Destroying a view therefore does not imply that it is safe to unmap the library's code.
The native handle is confined to its creating thread through its Rust ownership marker, and the public API shares it with Rc. This matches GLib and EGL use in the host loop rather than allowing background tasks to invoke native view operations concurrently.
String Ownership and Command Validation
State getters return pointers owned by the native implementation. Rust copies them into String values before another native call can invalidate that storage. Navigation similarly converts the supplied URI to a C string before invoking the command, returning a NulError without calling native code if an embedded NUL makes the input invalid.
These conversions make the ordinary safe API convenient without hiding the timing of page loading. Command delivery remains distinct from the engine's later status and frame updates.
Frame Ownership and Validation
A successful frame take transfers one FD to the caller. Rust first wraps it in OwnedFd, then validates pixel format, buffer type, dimensions, stride, modifier, and backing. If validation fails, normal ownership cleanup closes the transferred FD instead of leaking it across the error path.
The error also becomes terminal for frame production on that view. Further take_frame calls report the recorded failure without consuming another native image, preserving existing exports until the host closes the Hera connection and tears down the failed view.
Consumer Teardown Ordering
Dropping NativeView calls hw_destroy while its API and library remain alive. The native destructor removes pending readiness sources, closes any untaken export FD, releases held WPE buffers, and then tears down the web view, input state, and EGL resources.
This cleanup still relies on the host to close its scene connection first. Native destruction can release producer backing, so it must not run while the server continues using that connection's imported images. See frame ownership for the protocol evidence used before normal release.
Source Reference
The following files in the Hera checkout define the behavior described on this page.
crates/webkit/src/ffi.rscrates/webkit/src/ffi/tests.rscrates/webkit/native/hera_wpe.hcrates/webkit/native/hera_wpe.cppapps/browser/src/host.rs