Skip to content

feat(host): implement Registerable for MultiUseSandbox#1392

Merged
danbugs merged 1 commit intohyperlight-dev:mainfrom
danbugs:registerable-multiuse
Apr 21, 2026
Merged

feat(host): implement Registerable for MultiUseSandbox#1392
danbugs merged 1 commit intohyperlight-dev:mainfrom
danbugs:registerable-multiuse

Conversation

@danbugs
Copy link
Copy Markdown
Contributor

@danbugs danbugs commented Apr 20, 2026

Summary

Extends the Registerable trait impl to MultiUseSandbox so host functions can be registered on a sandbox after evolve(). Today the only impl is on UninitializedSandbox, which works fine for the standard Uninitialized → evolve() → MultiUse flow — but not for paths that yield a MultiUseSandbox directly. Examples: sandboxes loaded from a persisted snapshot (the snapshot-to-disk work lands one such path), and any future API with the same shape.

Without this, those callers have to reach into internal state or maintain a parallel registry, which isn't a stable story. With it, late registration becomes a one-liner that mirrors the existing UninitializedSandbox impl exactly.

Semantics

The guest's host-function dispatcher resolves by name at call time. Inserting into the registry after evolve() is safe as long as the first host-call invocation happens after registration completes. The typical usage pattern is the same as today for the pre-evolve path:

let mut sbox = MultiUseSandbox::from_snapshot(s)?;
sbox.register_host_function("__dispatch", |payload: Vec<u8>| { ... })?;
sbox.call::<(), _>("run", args)?;

Changes

  • New impl Registerable for MultiUseSandbox next to the existing UninitializedSandbox impl in src/func/host_functions.rs. Body is a verbatim copy of the existing impl — same error handling, same lock acquisition, same FunctionEntry construction.
  • Visibility of MultiUseSandbox.host_funcs nudged from pub(super) to pub(crate) so the impl in src/func/ can reach it. No external API change.

Tested

cargo check + cargo test -p hyperlight-host locally on Linux. No behaviour change for any existing caller.

The primary entry point for registering host functions is the
UninitializedSandbox — that's the lifecycle phase where the guest
hasn't yet been allowed to issue host calls, so the registry can be
populated safely up front.

There are, however, cases where a MultiUseSandbox is obtained
without traversing the Uninitialized → evolve() path:

  - Sandboxes loaded from a persisted snapshot.
  - Any future API that yields a MultiUseSandbox directly.

In those cases the caller never had a chance to call
register_host_function on an UninitializedSandbox. Today they have
to drop down to internal fields or fork the registry manually.
Extend the Registerable trait impl to MultiUseSandbox so late
registration is a one-liner. Semantics are unchanged: the guest's
dispatcher resolves host functions by name at call time, so
inserting into the registry after evolve() is safe as long as the
first host-call happens after registration completes.

Also flips MultiUseSandbox.host_funcs from pub(super) to pub(crate)
so the impl in src/func/host_functions.rs can reach it.

Signed-off-by: danbugs <danilochiarlone@gmail.com>
@danbugs danbugs added the kind/enhancement For PRs adding features, improving functionality, docs, tests, etc. label Apr 20, 2026
@danbugs danbugs enabled auto-merge (squash) April 20, 2026 23:21
Copy link
Copy Markdown
Contributor

@jprendes jprendes left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM.

I guess this opens some questions, like what's the point of the UninitializedSandbox?
Sounds like it's only use is "existing before hyperlight_main".
Do we still need it?

@danbugs danbugs merged commit 6ea9816 into hyperlight-dev:main Apr 21, 2026
40 of 41 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

kind/enhancement For PRs adding features, improving functionality, docs, tests, etc.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants