Skip to content

feat: add binary type support for host functions#40

Open
simongdavies wants to merge 1 commit intomainfrom
allow-binary-types-for-host-funcs
Open

feat: add binary type support for host functions#40
simongdavies wants to merge 1 commit intomainfrom
allow-binary-types-for-host-funcs

Conversation

@simongdavies
Copy link
Contributor

Adds Uint8Array/Buffer support for host function arguments and returns.

Architecture:

  • New hyperlight-js-common crate: shared wire-format constants, binary sidecar encode/decode, FnReturn enum, DecodeError type
  • Guest extracts Uint8Array from QuickJS VM into binary sidecar
  • Host dispatches via register() (typed serde) or register_js() (JS bridge)
  • NAPI layer creates native Node.js Buffers via C API (no base64)
  • Tagged return format (0x00=JSON, 0x01=binary) for return path

Key changes:

  • Single CallHostJsFunction entry point (removed legacy JSON-only path)
  • Native Buffer marshalling in NAPI (JsArg/JsReturn types)
  • Depth limits on all recursive JSON tree traversals (MAX_JSON_DEPTH=64)
  • Trailing data rejection in sidecar decoder
  • Typed register() rejects binary args with clear error message
  • Comprehensive test coverage (Rust unit + integration + JS vitest)
  • Updated README with Binary Data section and wire protocol docs
  • Updated CI publish order for new common crate

Closes #38

@simongdavies simongdavies added the kind/enhancement New feature or improvement label Mar 6, 2026
Adds Uint8Array/Buffer support for host function arguments and returns.

Architecture:
- New hyperlight-js-common crate: shared wire-format constants, binary
  sidecar encode/decode, FnReturn enum, DecodeError type
- Guest extracts Uint8Array from QuickJS VM into binary sidecar
- Host dispatches via register() (typed serde) or register_js() (JS bridge)
- NAPI layer creates native Node.js Buffers via C API (no base64)
- Tagged return format (0x00=JSON, 0x01=binary) for return path

Key changes:
- Single CallHostJsFunction entry point (removed legacy JSON-only path)
- Native Buffer marshalling in NAPI (JsArg/JsReturn types)
- Depth limits on all recursive JSON tree traversals (MAX_JSON_DEPTH=64)
- Trailing data rejection in sidecar decoder
- Typed register() rejects binary args with clear error message
- Comprehensive test coverage (Rust unit + integration + JS vitest)
- Updated README with Binary Data section and wire protocol docs
- Updated CI publish order for new common crate

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>
@simongdavies simongdavies force-pushed the allow-binary-types-for-host-funcs branch from b7570d0 to e63255b Compare March 6, 2026 00:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

kind/enhancement New feature or improvement

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Native Binary Data Support for Host Functions

1 participant