Documentation menu

The FFI Boundary

Keep C-compatible data layout, payload ownership, and error handling aligned between Rust and the native host.

The native host reaches Hera's Rust client and text services through the C-compatible types exported by hera-ffi. Using this library keeps binary protocol encoding in one implementation, while the FFI boundary defines how C++ and Rust exchange values and ownership.

Artifact and Header Compatibility

Both sides must agree on structure size and alignment, enum values, optional-field conventions, and pointer ownership. The mounting sink checks some of this contract for glyph data through static assertions. Other structures still require coordinated headers and conversion code, because those assertions cannot establish compatibility for the whole ABI.

Build the library and consumer from compatible revisions and for the same architecture. Changing a wire field can require corresponding changes in C types and conversion code even when most application code remains unchanged.

Submission Payload Ownership

A native operation may borrow arrays of glyphs or other payloads rather than owning them. The backing storage must remain valid for the complete call contract, including any period for which the operation is queued. A pointer into a temporary Fabric mutation list can therefore become invalid after adapter extraction even if that extraction succeeded.

Use the host's owned mutation storage and review exactly where the Rust side copies or retains input. A reinterpret_cast is justified only by a checked layout contract, not by similar field names.

Returned Allocation Ownership

Returned messages can own strings or touch lists allocated by the Rust library. After dispatch, the event loop's cleanup guard releases them with the matching FFI free functions, ensuring that ordinary returns do not leak those allocations.

Do not free Rust allocations with an unrelated C++ allocator, and do not retain message pointers after cleanup.

Failure Handling

The return status of an FFI call reports progress at the native boundary, which may mean only that a request was sent. Its retained acceptance arrives later through the protocol. If a generic server error or session timeout makes that outcome ambiguous, the host cannot safely turn the earlier call's success into an accepted scene baseline.

See Fabric mounting, protocol validation, and verification.

Source Reference

The following files in the Hera checkout define the behavior described on this page.

  • crates/ffi/src/types.rs
  • crates/ffi/src/convert.rs
  • crates/ffi/src/messages.rs
  • react-native/rn_host/include/rn_host/ffi.h
  • react-native/rn_host/src/fabric/mounting/mutation_storage.h