Skip to content

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

Open
ludfjig wants to merge 3 commits into
mainfrom
hyperlight-0.18-capi
Open

ludfjig wants to merge 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 with Hyperlight's hyperlight-component-csharp, so builds need no Rust.
  • The C API loads a guest runtime built for the component's world from a file. SandboxBuilder::with_runtime_file is behind the experimental_runtime_file feature, and snapshots of such a sandbox cannot be saved.
  • 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.

@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 7 times, most recently from 400cf1e to 0bb6526 Compare November 12, 2026 17:49
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.
Snapshots of such a sandbox cannot be saved, because the host does not
know the runtime's 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>
@ludfjig
ludfjig force-pushed the hyperlight-0.18-capi branch 3 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
run: just test ${{ matrix.config }} ${{ env.FEATURES }}
working-directory: ./src/hyperlight_wasm

# Runs before Test Examples, which replaces the native modules with

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

this is a bit confusing... are we using pully modules of .net?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

its nice to see all the tests here!

Comment thread dotnet/README.md

`docs/component-wire-format.md` in hyperlight lists how WIT types map to C#.

## Guest runtime and components

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thanks, I wonder could we package this up in the hyperlight.wasm.build project tool too? so you don't have to do this out of band but as part of the build? (this could be a follow up)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Just thinking of ways to simplify the expereince

Comment thread dotnet/README.md
codesign -f -s - --entitlements macos-entitlements.plist bin/Release/net8.0/osx-arm64/publish/MyApp
```

`dotnet MyApp.dll` and `dotnet test` run inside the `dotnet` host, so they cannot create sandboxes on macOS.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I think it technically possible to create a test exe?

}

#[test]
#[ignore = "needs a guest runtime built for the component_sample example world"]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

are we ignoring all these test?

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>
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 except
macOS, where the tests run inside the dotnet host, which lacks the
hypervisor entitlement. 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 95f1991 to 9fc835f Compare November 17, 2026 00:03
ArgumentNullException.ThrowIfNull(value);
lock (_entries)
{
_entries.Add(new Entry { Value = value, Lent = lent });

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

looks like we always add here and clear doesn't remove the values so this always grows _entries

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.

3 participants