Skip to content

Add experimental C API and .NET packages for components - #564

Merged
ludfjig merged 3 commits into
mainfrom
hyperlight-0.18-capi
Nov 18, 2026
Merged

ludfjig merged 3 commits into
mainfrom
hyperlight-0.18-capi

Conversation

@ludfjig

@ludfjig ludfjig commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

.NET and other non-Rust hosts can't use hyperlight-wasm, because its host API is Rust only.

This adds an experimental C API and .NET packages on top of it:

  • hyperlight-wasm-capi is a C API for running components. Callers register host functions, load a component and call its functions. They can also snapshot, restore and interrupt a sandbox.
  • The C API works with any component, because it never decodes values. Callers pass each argument as a byte buffer in Hyperlight's component wire format and get the result back the same way. Generated bindings, such as the .NET ones, do the encoding.
  • Hyperlight.Wasm wraps the C API. Hyperlight.Wasm.Build generates typed C# bindings from WIT at build time. Its MSBuild task loads hyperlight-wasm-csharp-bindgen, a native library around Hyperlight's hyperlight-component-csharp, so builds need no Rust.

A guest runtime is built for one WIT world and is embedded when a Rust host builds. A non-Rust host has no Rust build to embed it in. So the C API loads the runtime from a file, through SandboxBuilder::with_runtime_file behind the experimental_runtime_file feature. Here users build that runtime with cargo hyperlight. #574 adds a tool and MSBuild support for it.

  • The hyperlight-wasm-runtime guest binary has an ELF section, .note_hyperlight_wasm_runtime, holding its crate version and a hash of its WIT world. The hash covers the WIT_WORLD file or directory and WIT_WORLD_NAME.
  • with_runtime_file rejects a guest binary whose crate version differs from the host's hyperlight-wasm crate version, because host and guest must agree on the guest ABI. The hyperlight-wasm build checks its embedded guest binary the same way.
  • A snapshot records the world hash of its guest binary. A host built with WIT_WORLD only loads snapshots with the same hash. A host built without one, like the C API, loads snapshots of any world, because it only uses guest binaries from files.
  • SandboxBuilder::with_interrupt_vcpu_sigrtmin_offset changes the interrupt signal, since .NET uses SIGRTMIN.

The C API and packages are versioned as experimental and not published yet. just dotnet-test and just examples-components run their tests, and CI runs both on every platform. On macOS the .NET tests run as a signed executable, because the dotnet host lacks the hypervisor entitlement.

@ludfjig
ludfjig force-pushed the hyperlight-0.18-capi branch 4 times, most recently from fbcf9c8 to b91d23d Compare November 4, 2026 01:22
@ludfjig
ludfjig force-pushed the hyperlight-0.18-capi branch from b91d23d to 214c584 Compare November 11, 2026 19:25
@ludfjig ludfjig added the kind/enhancement New feature or request label Nov 11, 2026
@ludfjig ludfjig changed the title hyperlight-wasm capi Add experimental C API and .NET packages for components Nov 11, 2026
@ludfjig
ludfjig force-pushed the hyperlight-0.18-capi branch 10 times, most recently from 152740d to 0231892 Compare November 12, 2026 18:39
@ludfjig
ludfjig marked this pull request as ready for review November 12, 2026 20:31
@ludfjig
ludfjig added this pull request to stack #576 November 13, 2026 00:42
Comment thread .github/workflows/dep_rust.yml Resolved
Comment thread dotnet/Directory.Build.props Resolved
Comment thread dotnet/README.md Resolved
Comment thread dotnet/README.md Resolved
Comment thread dotnet/README.md Resolved
Comment thread src/hyperlight_wasm_bindgen/Cargo.toml Resolved
@ludfjig
ludfjig force-pushed the hyperlight-0.18-capi branch 2 times, most recently from 1baa590 to 95f1991 Compare November 16, 2026 18:46
Comment thread .github/workflows/dep_rust.yml Resolved
Comment thread dotnet/README.md Resolved
Comment thread dotnet/README.md Resolved
@ludfjig
ludfjig force-pushed the hyperlight-0.18-capi branch from 95f1991 to 9fc835f Compare November 17, 2026 00:03

@simongdavies simongdavies left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

a few comments/questions.

I am not a fan of the with_runtime_file, it would be better if the runtime was either created at build time or the world was seperate

Comment thread src/hyperlight_wasm_capi/src/lib.rs Resolved
Comment thread src/hyperlight_wasm_capi/src/lib.rs Resolved
Comment thread src/hyperlight_wasm_capi/src/lib.rs Resolved
Comment thread src/hyperlight_wasm_capi/src/lib.rs Resolved
Comment thread .github/workflows/dep_rust.yml Resolved
@ludfjig
ludfjig force-pushed the hyperlight-0.18-capi branch 2 times, most recently from 1d8d096 to 9db79f3 Compare November 17, 2026 19:33
@ludfjig

ludfjig commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor Author

I am not a fan of the with_runtime_file, it would be better if the runtime was either created at build time or the world was seperate

Agree, unfortunately only rust can create it at build time, not c#(c).

@ludfjig
ludfjig force-pushed the hyperlight-0.18-capi branch 2 times, most recently from 1586dd4 to 0baba7a Compare November 17, 2026 21:39
The experimental_runtime_file feature adds
SandboxBuilder::with_runtime_file, which loads the guest runtime from
a file instead of the one built into the crate. A host built once can
then run components of any world whose runtime was built separately.

The runtime records its hyperlight-wasm version and a hash of its WIT
world in an ELF section. with_runtime_file rejects a runtime from
another version, and snapshots of the sandbox record the runtime's
world, so they can be saved and loaded. A host built without WIT_WORLD
has no bindings of its own, so it loads snapshots of any world.

SandboxBuilder::with_interrupt_vcpu_sigrtmin_offset changes the signal
that interrupts a running guest on Linux. Hosts such as .NET use
SIGRTMIN themselves.

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>
Add hyperlight-wasm-capi, a C library declared in
include/hyperlight_wasm.h. Callers register host functions, load a
component and call its functions. They can also snapshot, restore and
interrupt a sandbox. It is experimental and not published.

The C API works with any component, because it never decodes values.
Callers pass each argument as a byte buffer in hyperlight's component
wire format and get the result back the same way. Generated bindings,
such as the .NET ones, do the encoding. Host functions take up to 32
parameters. Calls from a host function into its own sandbox fail.

just examples-components runs its tests against the component_sample
example world.

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>
@ludfjig
ludfjig force-pushed the hyperlight-0.18-capi branch from 0baba7a to c234b2f Compare November 17, 2026 22:16
Comment thread .github/workflows/dep_rust.yml Resolved
Hyperlight.Wasm runs components from .NET through the C API. WasmSandbox
registers host functions, loads components and calls them, with
snapshots, interrupts and CancellationToken support. Host exceptions
become the InnerException of the failed call. Their messages do not
reach the guest. The interrupt signal defaults to SIGRTMIN + 1, because
the .NET runtime suspends threads for garbage collection with SIGRTMIN.
With offset 0 a collection can hang.

Hyperlight.Wasm.Build generates C# bindings from HyperlightWit items at
build time. Its MSBuild task loads hyperlight-wasm-csharp-bindgen, a
native library around hyperlight's C# generator, so builds need no Rust.

Both packages are experimental and take the workspace version with a
preview suffix. They are not published yet.

just dotnet-test runs the tests against the component_sample example
world. CI runs them with the prebuilt component on every platform. The
tests build as an xUnit.net v3 executable, so macOS signs it with the
hypervisor entitlement and runs it directly. dotnet test would run them
inside the unsigned dotnet host. just dotnet-pack packs both packages
for the build machine's runtime identifier.

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>
@ludfjig
ludfjig force-pushed the hyperlight-0.18-capi branch from c234b2f to f43b1b0 Compare November 18, 2026 21:45
@ludfjig
ludfjig merged commit 62d51d9 into main Nov 18, 2026
51 checks passed
@ludfjig
ludfjig deleted the hyperlight-0.18-capi branch November 18, 2026 22:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

kind/enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants