Skip to content

Lightpanda: the headless browser designed for AI and automation

Implement WebAssembly.compileStreaming and instantiateStreaming

Adrià Arrufatab8e9622e201
diff --git a/build.zig.zon b/build.zig.zon
index ea2aad0ba..1f01544d8 100644
--- a/build.zig.zon
+++ b/build.zig.zon
@@ -5,8 +5,8 @@
.minimum_zig_version = "0.16.0",
.dependencies = .{
.v8 = .{
- .url = "https://github.com/lightpanda-io/zig-v8-fork/archive/31b233ce6162c18eb37cacd001473057f75daad9.tar.gz",
- .hash = "v8-0.0.0-xddH62IdAwCZid1vyAzg_8IiWG4ovW7DbcnSvZd12I9p",
+ .url = "https://github.com/lightpanda-io/zig-v8-fork/archive/fb337c774a5313aa5e2dcb044ca723cf6e304ba2.tar.gz",
+ .hash = "v8-0.0.0-xddH65ovAwBmolwHZrPk83tl-ZgdOMy2SYQ5ViaZ-P1f",
},
// .v8 = .{ .path = "../zig-v8-fork" },
.brotli = .{
diff --git a/src/TestHTTPServer.zig b/src/TestHTTPServer.zig
index 877ee82b5..2613e9205 100644
--- a/src/TestHTTPServer.zig
+++ b/src/TestHTTPServer.zig
@@ -163,6 +163,10 @@ fn getContentType(file_path: []const u8) []const u8 {
return "text/xml";
}
+ if (std.mem.endsWith(u8, file_path, ".wasm")) {
+ return "application/wasm";
+ }
+
if (std.mem.endsWith(u8, file_path, ".mjs")) {
// mjs are ECMAScript modules
return "application/json";
diff --git a/src/browser/js/Context.zig b/src/browser/js/Context.zig
index e57740f34..b5709758b 100644
--- a/src/browser/js/Context.zig
+++ b/src/browser/js/Context.zig
@@ -24,6 +24,7 @@ const Env = @import("Env.zig");
const Origin = @import("Origin.zig");
const Scheduler = @import("Scheduler.zig");
const Execution = @import("Execution.zig");
+const WasmStreaming = @import("WasmStreaming.zig");
const Frame = @import("../Frame.zig");
const Page = @import("../Page.zig");
@@ -104,6 +105,9 @@ identity_arena: Allocator,
// across origins.
global_modules: std.ArrayList(v8.Global) = .empty,
+// WebAssembly streaming compilations still waiting on their Response.
+wasm_streams: std.ArrayList(*WasmStreaming) = .empty,
+
// Our module cache: normalized module specifier => module.
module_cache: std.StringHashMapUnmanaged(ModuleEntry) = .empty,
@@ -201,6 +205,10 @@ pub fn deinit(self: *Context) void {
v8.v8__Global__Reset(global);
}
+ while (self.wasm_streams.pop()) |stream| {
+ stream.abort(null);
+ }
+
self.page.releaseOrigin(self.origin);
// Clear the embedder data so that if V8 keeps this context alive
diff --git a/src/browser/js/Env.zig b/src/browser/js/Env.zig
index 38a9c8edd..55dc7ff03 100644
--- a/src/browser/js/Env.zig
+++ b/src/browser/js/Env.zig
@@ -22,6 +22,7 @@ const lp = @import("lightpanda");
const js = @import("js.zig");
const bridge = @import("bridge.zig");
const Context = @import("Context.zig");
+const WasmStreaming = @import("WasmStreaming.zig");
const Isolate = @import("Isolate.zig");
const Platform = @import("Platform.zig");
const Inspector = @import("Inspector.zig");
@@ -156,6 +157,8 @@ pub fn init(app: *App, opts: InitOpts) !Env {
v8.v8__Isolate__SetHostImportModuleDynamicallyCallback(isolate_handle, Context.dynamicModuleCallback);
v8.v8__Isolate__SetPromiseRejectCallback(isolate_handle, promiseRejectCallback);
+ // Also set on the snapshot isolate, see Snapshot.create.
+ v8.v8__Isolate__SetWasmStreamingCallback(isolate_handle, WasmStreaming.callback);
v8.v8__Isolate__SetMicrotasksPolicy(isolate_handle, v8.kExplicit);
v8.v8__Isolate__SetFatalErrorHandler(isolate_handle, fatalCallback);
v8.v8__Isolate__SetOOMErrorHandler(isolate_handle, oomCallback);
diff --git a/src/browser/js/Snapshot.zig b/src/browser/js/Snapshot.zig
index 1a88e6832..fcd1c6428 100644
--- a/src/browser/js/Snapshot.zig
+++ b/src/browser/js/Snapshot.zig
@@ -20,6 +20,7 @@ const std = @import("std");
const lp = @import("lightpanda");
const js = @import("js.zig");
+const WasmStreaming = @import("WasmStreaming.zig");
const bridge = @import("bridge.zig");
const reflect = @import("../reflect.zig");
@@ -151,6 +152,11 @@ pub fn create() !Snapshot {
const isolate = v8.v8__SnapshotCreator__getIsolate(snapshot_creator).?;
defer v8.v8__Isolate__LowMemoryNotification(isolate);
+ // WebAssembly.compileStreaming/instantiateStreaming are installed at
+ // context genesis, and only if the isolate has a streaming callback. The
+ // pointer is not serialized; the runtime isolate registers its own.
+ v8.v8__Isolate__SetWasmStreamingCallback(isolate, WasmStreaming.callback);
+
{
// CreateBlob, which we'll call once everything is setup, MUST NOT
// be called from an active HandleScope. Hence we have this scope to
diff --git a/src/browser/js/WasmStreaming.zig b/src/browser/js/WasmStreaming.zig
new file mode 100644
index 000000000..835973357
--- /dev/null
+++ b/src/browser/js/WasmStreaming.zig
@@ -0,0 +1,152 @@
+// Copyright (C) 2023-2025 Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <[email protected]>
+// Pierre Tachoire <[email protected]>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+//! The embedder half of `WebAssembly.compileStreaming` and
+//! `WebAssembly.instantiateStreaming`. V8 only installs the two functions
+//! when the isolate has a streaming callback; when a page calls one, V8 hands
+//! us the `Response | Promise<Response>` argument and a WasmStreaming handle
+//! we feed the module bytes into.
+//!
+//! https://webassembly.github.io/spec/web-api/#compile-a-potential-webassembly-response
+
+const std = @import("std");
+const lp = @import("lightpanda");
+
+const js = @import("js.zig");
+const v8 = js.v8;
+const Caller = @import("Caller.zig");
+const Context = @import("Context.zig");
+const Mime = @import("../Mime.zig");
+const Response = @import("../webapi/net/Response.zig");
+
+const log = lp.log;
+
+const WasmStreaming = @This();
+
+ctx: *Context,
+handle: v8.SharedPtr,
+
+pub fn callback(info_handle: ?*const v8.FunctionCallbackInfo) callconv(.c) void {
+ var caller: Caller = undefined;
+ if (!caller.initFromHandle(info_handle)) {
+ return;
+ }
+ defer caller.deinit();
+ const local = &caller.local;
+
+ const info = Caller.FunctionCallbackInfo{ .handle = info_handle.? };
+ var shared = v8.v8__WasmStreaming__Unpack(local.isolate.handle, v8.v8__FunctionCallbackInfo__Data(info.handle).?);
+
+ const ctx = local.ctx;
+ const self = ctx.arena.allocator().create(WasmStreaming) catch |err| {
+ log.err(.js, "wasm streaming", .{ .err = err });
+ v8.v8__WasmStreaming__Abort(&shared, local.isolate.createError("Out of memory"));
+ v8.std__shared_ptr__v8__WasmStreaming__reset(&shared);
+ return;
+ };
+ self.* = .{ .ctx = ctx, .handle = shared };
+
+ self.start(local, info.getArg(0, local)) catch |err| self.abortZigError(local, err);
+}
+
+fn start(self: *WasmStreaming, local: *const js.Local, source: js.Value) !void {
+ const ctx = self.ctx;
+ try ctx.wasm_streams.append(ctx.arena.allocator(), self);
+
+ const promise = if (source.isPromise()) source.toPromise() else try local.resolvePromise(source);
+ _ = try promise.thenAndCatch(
+ local.newCallback(onResponse, self),
+ local.newCallback(onFailure, self),
+ );
+}
+
+fn onResponse(self: *WasmStreaming, value: js.Value, exec: *js.Execution) void {
+ const local = exec.js.local.?;
+ const response = value.toZig(*Response) catch {
+ return self.abortTypeError(local, "Argument 0 must be a Response or a Promise resolving to a Response");
+ };
+
+ const content_type = response.getHeaders().get("content-type", exec) catch |err| return self.abortZigError(local, err);
+ const essence = Mime.ContentTypeIterator.init(content_type orelse "").essence;
+ if (!std.ascii.eqlIgnoreCase(essence, "application/wasm")) {
+ return self.abortTypeError(local, "Incorrect response MIME type. Expected 'application/wasm'.");
+ }
+ if (!response.isOK()) {
+ return self.abortTypeError(local, "HTTP status code is not ok");
+ }
+
+ const bytes = response.bytes(exec) catch |err| return self.abortZigError(local, err);
+
+ const url = response.getURL();
+ v8.v8__WasmStreaming__SetUrl(&self.handle, url.ptr, url.len);
+
+ _ = bytes.thenAndCatch(
+ local.newCallback(onBytes, self),
+ local.newCallback(onFailure, self),
+ ) catch |err| self.abortZigError(local, err);
+}
+
+fn onBytes(self: *WasmStreaming, bytes: []const u8) void {
+ v8.v8__WasmStreaming__OnBytesReceived(&self.handle, bytes.ptr, bytes.len);
+ v8.v8__WasmStreaming__Finish(&self.handle);
+ self.release();
+}
+
+fn onFailure(self: *WasmStreaming, reason: js.Value) void {
+ self.abort(reason.handle);
+}
+
+fn abortTypeError(self: *WasmStreaming, local: *const js.Local, message: []const u8) void {
+ self.abort(local.isolate.createTypeError(message));
+}
+
+// Body accessors report a TypeError through the context's error_message,
+// the same way the bridge surfaces it to JS.
+fn abortZigError(self: *WasmStreaming, local: *const js.Local, err: anyerror) void {
+ switch (err) {
+ error.TypeError => {
+ const env = local.ctx.env;
+ self.abortTypeError(local, env.error_message orelse "Response body is not usable");
+ env.error_message = null;
+ },
+ else => {
+ log.err(.js, "wasm streaming", .{ .err = err });
+ self.abort(local.isolate.createError(@errorName(err)));
+ },
+ }
+}
+
+/// With a null exception the promise is never settled, which is what a
+/// context being torn down wants.
+pub fn abort(self: *WasmStreaming, exception: ?*const v8.Value) void {
+ v8.v8__WasmStreaming__Abort(&self.handle, exception);
+ self.release();
+}
+
+fn release(self: *WasmStreaming) void {
+ v8.std__shared_ptr__v8__WasmStreaming__reset(&self.handle);
+ const streams = &self.ctx.wasm_streams;
+ if (std.mem.indexOfScalar(*WasmStreaming, streams.items, self)) |i| {
+ _ = streams.swapRemove(i);
+ }
+}
+
+const testing = @import("../../testing.zig");
+test "WebApi: WebAssembly" {
+ try testing.htmlRunner("wasm", .{});
+}
diff --git a/src/browser/tests/wasm/add.wasm b/src/browser/tests/wasm/add.wasm
new file mode 100644
index 000000000..357f72da7
Binary files /dev/null and b/src/browser/tests/wasm/add.wasm differ
diff --git a/src/browser/tests/wasm/streaming.html b/src/browser/tests/wasm/streaming.html
new file mode 100644
index 000000000..1673589d4
--- /dev/null
+++ b/src/browser/tests/wasm/streaming.html
@@ -0,0 +1,77 @@
+<!DOCTYPE html>
+<script src="../testing.js"></script>
+
+<!-- add.wasm exports add(i32, i32) -> i32. -->
+
+<script id=instantiate_streaming type=module>
+ const state = await testing.async();
+ const result = await WebAssembly.instantiateStreaming(fetch('add.wasm'), {});
+ state.resolve(result);
+ await state.done((result) => {
+ testing.expectEqual(true, result.module instanceof WebAssembly.Module);
+ testing.expectEqual(true, result.instance instanceof WebAssembly.Instance);
+ testing.expectEqual(7, result.instance.exports.add(3, 4));
+ });
+</script>
+
+<script id=compile_streaming type=module>
+ const state = await testing.async();
+ const mod = await WebAssembly.compileStreaming(fetch('add.wasm'));
+ const instance = await WebAssembly.instantiate(mod);
+ state.resolve({ mod, instance });
+ await state.done(({ mod, instance }) => {
+ testing.expectEqual(['add'], WebAssembly.Module.exports(mod).map((e) => e.name));
+ testing.expectEqual(3, instance.exports.add(1, 2));
+ });
+</script>
+
+<script id=response_argument type=module>
+ // A Response rather than a promise, built in-page, with MIME type
+ // parameters and mixed case: only the essence has to match.
+ const state = await testing.async();
+ const bytes = await (await fetch('add.wasm')).arrayBuffer();
+ const response = new Response(bytes, {
+ headers: { 'Content-Type': 'Application/WASM; charset=binary' },
+ });
+ const { instance } = await WebAssembly.instantiateStreaming(response);
+ state.resolve(instance);
+ await state.done((instance) => {
+ testing.expectEqual(11, instance.exports.add(5, 6));
+ });
+</script>
+
+<script id=rejections type=module>
+ const state = await testing.async();
+ const errors = {};
+ const attempt = async (name, source) => {
+ try {
+ await WebAssembly.compileStreaming(source);
+ errors[name] = 'resolved';
+ } catch (e) {
+ errors[name] = e;
+ }
+ };
+
+ const wasmHeaders = { 'Content-Type': 'application/wasm' };
+ const bytes = await (await fetch('add.wasm')).arrayBuffer();
+ const used = await fetch('add.wasm');
+ await used.arrayBuffer();
+
+ await attempt('not_a_response', Promise.resolve({}));
+ await attempt('wrong_mime', new Response(bytes, { headers: { 'Content-Type': 'application/octet-stream' } }));
+ await attempt('not_ok', new Response(bytes, { status: 404, headers: wasmHeaders }));
+ await attempt('body_used', used);
+ await attempt('rejected_source', Promise.reject(new RangeError('boom')));
+ await attempt('invalid_module', new Response('not wasm', { headers: wasmHeaders }));
+
+ state.resolve(errors);
+ await state.done((errors) => {
+ testing.expectEqual(true, errors.not_a_response instanceof TypeError);
+ testing.expectEqual(true, errors.wrong_mime instanceof TypeError);
+ testing.expectEqual(true, errors.not_ok instanceof TypeError);
+ testing.expectEqual(true, errors.body_used instanceof TypeError);
+ testing.expectEqual(true, errors.rejected_source instanceof RangeError);
+ testing.expectEqual('boom', errors.rejected_source.message);
+ testing.expectEqual(true, errors.invalid_module instanceof WebAssembly.CompileError);
+ });
+</script>
diff --git a/src/browser/webapi/net/Response.zig b/src/browser/webapi/net/Response.zig
index 9cc1a0202..822154698 100644
--- a/src/browser/webapi/net/Response.zig
+++ b/src/browser/webapi/net/Response.zig
@@ -297,7 +297,7 @@ fn lockStream(stream: *ReadableStream, exec: *const Execution) !void {
stream._disturbed = true;
}
-fn isOK(self: *const Response) bool {
+pub fn isOK(self: *const Response) bool {
return self._status >= 200 and self._status <= 299;
}