BinaryLibs.Wasm 0.169.1

BinaryLibs.Wasm

BinaryLibs.Wasm provides .NET abstractions for validating, loading, invoking, and supervising WebAssembly modules with Wasmtime. It targets netstandard2.0 and exposes library-owned values and results rather than making callers depend on Wasmtime types.

The package is intentionally generic. It does not define a game protocol, command model, serialization format, or application-specific callback names.

What it provides

• Contract validation for required and optional imports and exports.
• In-process execution through WasmRuntime.
• Managed import callbacks using Value and InvocationContext.
• Invocation results that distinguish completion, traps, cancellation, timeouts, import failures, invalid signatures, and memory-limit failures.
• Worker lifecycle management through Supervisor and Worker.
• Protocol version and capability negotiation.
• Injectable transports, including InMemoryTransport and NamedPipeTransport.
• Bounded local callback queues for opaque application-defined records.
• Payload hardening and explicit queue-overflow policies.

Install

dotnet add package BinaryLibs.Wasm

The package currently depends on Wasmtime. Applications should use a compatible .NET SDK and test the Wasmtime runtime behavior on each deployment platform.

Validate a module contract

Validation parses the module without instantiating it. Imports are matched by the exact (module name, function name) pair; exports are matched by function name. Extra declarations produce warnings by default and errors when StrictAllowlist is enabled.

using BinaryLibs.Wasm;

var contract = new ModuleContract(
	new[]
	{
		new ImportDescriptor(
			"host",
			"log",
			new FunctionSignature(
				new[] { ValueType.I32 },
				Array.Empty<ValueType>()),
			is_required: true)
	},
	new[]
	{
		new ExportDescriptor(
			"add",
			new FunctionSignature(
				new[] { ValueType.I32, ValueType.I32 },
				new[] { ValueType.I32 }))
	});

var validation = ModuleValidator.Validate(
	File.ReadAllBytes("module.wasm"),
	contract,
	new ValidationOptions(strict_allowlist: true));

if (!validation.IsValid)
{
	foreach (var diagnostic in validation.Diagnostics)
	{
		Console.Error.WriteLine($"{diagnostic.Code}: {diagnostic.Message}");
	}
}

ValidationResult.Diagnostics identifies malformed modules, missing or incompatible declarations, duplicates, and extra declarations. Validate before instantiation when the module is supplied by an untrusted or changing source.

Execute a module in process

WasmRuntime owns one Wasmtime engine, module, store, and instance. Register every import before the first invocation. The callback receives library-owned values and the current cancellation token.

using BinaryLibs.Wasm;

using var runtime = WasmRuntime.Load(File.ReadAllBytes("module.wasm"));

runtime.RegisterImport(
	"host",
	"log",
	(arguments, context) =>
	{
		Console.WriteLine(arguments[0].AsI32());
		return Array.Empty<Value>();
	});

var result = runtime.Invoke(
	"add",
	new[] { Value.FromI32(2), Value.FromI32(3) },
	new ExecutionOptions(TimeSpan.FromSeconds(1)));

if (result.Status == InvocationStatus.Completed)
{
	Console.WriteLine(result.Results[0].AsI32());
}
else
{
	Console.Error.WriteLine($"{result.Status}: {result.Message}");
}

Supported numeric values are i32, i64, f32, and f64. A call must match the exported function's parameter types. ExecutionOptions can apply a timeout, cancellation token, and maximum linear-memory size in Wasm pages (64 KiB per page).

An invocation can return these statuses:

Timeouts and cancellation cannot forcibly abort a managed import callback that is already running. Use a worker process when a hard process-level boundary is required.

Supervise workers

Use Supervisor and Worker when the application needs lifecycle state, heartbeats, protocol negotiation, graceful shutdown, restart, or a separate worker process.

using BinaryLibs.Wasm;

var supervisor = new Supervisor();
var worker = await supervisor.CreateWorkerAsync(
	new WorkerOptions
	{
		ModuleSource = File.ReadAllBytes("module.wasm"),
		ExecutionOptions = new ExecutionOptions(TimeSpan.FromSeconds(1))
	},
	cancellationToken);

var result = await worker.InvokeAsync(
	"add",
	new[] { Value.FromI32(2), Value.FromI32(3) },
	null,
	cancellationToken);

await worker.StopAsync(cancellationToken);

Worker states include Starting, Handshaking, Ready, Running, Draining, Stopping, Stopped, Failed, and Terminated. A worker can be stopped gracefully, terminated explicitly, awaited with WaitForExitAsync, or restarted according to its configured WorkerRestartPolicy.

Separate-process hosting

Set WorkerExecutablePath, WorkerArguments, ProcessStartInfo, or ProcessFactory on WorkerOptions and provide an IProtocolTransport. The companion process is responsible for loading the module and handling the generic invocation protocol. The package does not ship a universal worker executable or hide an operating-system-specific process model.

The recommended topology is:

Application -> Supervisor -> transport -> worker process -> Wasmtime -> module

Use a separate process for potentially hostile modules or when managed callback code must not share the application's process. Process termination is still the responsibility of the host policy; in-process Wasmtime execution is not a complete security sandbox.

Protocol and transports

ProtocolHello negotiates supported versions and ProtocolCapability values. ProtocolLimits bounds encoded frame length, payload length, and queued frames. Protocol envelopes include message categories, correlation identifiers, and sequence numbers so callers can enforce ordering and correlate responses.

InMemoryTransport.CreatePair(...) is useful for deterministic tests and local host/worker wiring. NamedPipeTransport provides a named-pipe transport where the host platform supports it. Implement IProtocolTransport to integrate another IPC or test transport.

Local callback queue

High-frequency callbacks can append opaque payloads to a bounded LocalCallbackQueue instead of crossing the supervisor boundary on every call. LocalOperationRecord preserves a caller-defined correlation ID and payload; the library does not interpret the payload.

var queue = new LocalCallbackQueue(new LocalCallbackOptions
{
	MaxQueueDepth = 256,
	OverflowPolicy = QueueOverflowPolicy.Throw
});

queue.Enqueue(new LocalOperationRecord("operation-1", payloadBytes));
var next = queue.Peek();
var batch = queue.Flush();

Flush() drains records in FIFO order. Overflow policies are Throw, DropOldest, DropNewest, and Terminate. Block is defined for API compatibility but is not implemented and throws NotSupportedException.

Hardening

HardeningPolicy validates local records against HardeningLimits, including maximum payload length. A violation throws HardeningException with a HardeningFailure category. ProcessTerminationPolicy expresses whether the host should gracefully stop and then kill, kill immediately, or leave termination to the caller.

Use protocol limits, execution options, queue limits, hardening limits, and supervisor deadlines together. A single limit should not be treated as a complete security policy.

Design boundaries

• The core API supports only numeric WebAssembly values at the function boundary: i32, i64, f32, and f64.
• Callbacks are synchronous at the Wasmtime boundary. Async callbacks require an application-level suspension or message protocol.
• The package does not define domain commands, queries, events, snapshots, or payload codecs.
• netstandard2.0 compatibility means the application supplies any required platform-specific worker entry point and process integration.

License

See the repository LICENSE.txt.