Skip to content

Lightpanda: the headless browser designed for AI and automation

cdp: add debugger domain

Pierre Tachoireb905084ba074
diff --git a/src/server/cdp/CDP.zig b/src/server/cdp/CDP.zig
index 13faa5fb5..88652b9af 100644
--- a/src/server/cdp/CDP.zig
+++ b/src/server/cdp/CDP.zig
@@ -322,6 +322,7 @@ fn dispatchCommand(command: *Command, method: []const u8) !void {
},
8 => switch (@as(u64, @bitCast(domain[0..8].*))) {
asUint(u64, "Security") => return @import("domains/security.zig").processMessage(command),
+ asUint(u64, "Debugger") => return @import("domains/debugger.zig").processMessage(command),
else => {},
},
9 => switch (@as(u72, @bitCast(domain[0..9].*))) {
diff --git a/src/server/cdp/domains/debugger.zig b/src/server/cdp/domains/debugger.zig
new file mode 100644
index 000000000..987a22a9c
--- /dev/null
+++ b/src/server/cdp/domains/debugger.zig
@@ -0,0 +1,199 @@
+// Copyright (C) 2023-2024 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/>.
+
+const std = @import("std");
+const CDP = @import("../CDP.zig");
+
+// The V8 inspector implements the Debugger domain: forward the methods and
+// let it answer (and emit Debugger.scriptParsed & co) on the sending session.
+// Pausing isn't supported: runMessageLoopOnPause doesn't block, so a pause
+// can't be inspected or stepped through. The commands that set up or drive a
+// pause are rejected. A `debugger;` statement still reports Debugger.paused
+// then Debugger.resumed, and execution goes on.
+pub fn processMessage(cmd: *CDP.Command) !void {
+ const action = std.meta.stringToEnum(enum {
+ enable,
+ disable,
+ getPossibleBreakpoints,
+ getScriptSource,
+ getStackTrace,
+ getWasmBytecode,
+ disassembleWasmModule,
+ nextWasmDisassemblyChunk,
+ removeBreakpoint,
+ searchInContent,
+ setAsyncCallStackDepth,
+ setBlackboxExecutionContexts,
+ setBlackboxPatterns,
+ setBlackboxedRanges,
+ setBreakpointsActive,
+ setScriptSource,
+ setSkipAllPauses,
+ setPauseOnExceptions,
+ // pause
+ pause,
+ pauseOnAsyncCall,
+ @"resume",
+ stepInto,
+ stepOver,
+ stepOut,
+ continueToLocation,
+ restartFrame,
+ evaluateOnCallFrame,
+ setReturnValue,
+ setVariableValue,
+ setBreakpoint,
+ setBreakpointByUrl,
+ setBreakpointOnFunctionCall,
+ setInstrumentationBreakpoint,
+ }, cmd.input.action) orelse return error.UnknownMethod;
+
+ switch (action) {
+ .setPauseOnExceptions => return setPauseOnExceptions(cmd),
+ .pause,
+ .pauseOnAsyncCall,
+ .@"resume",
+ .stepInto,
+ .stepOver,
+ .stepOut,
+ .continueToLocation,
+ .restartFrame,
+ .evaluateOnCallFrame,
+ .setReturnValue,
+ .setVariableValue,
+ .setBreakpoint,
+ .setBreakpointByUrl,
+ .setBreakpointOnFunctionCall,
+ .setInstrumentationBreakpoint,
+ => return pauseNotSupported(cmd),
+ else => return sendInspector(cmd),
+ }
+}
+
+// "none" is V8's default: nothing to pause on.
+fn setPauseOnExceptions(cmd: *CDP.Command) !void {
+ const params = (try cmd.params(struct { state: []const u8 })) orelse return error.InvalidParams;
+ if (std.mem.eql(u8, params.state, "none")) {
+ return sendInspector(cmd);
+ }
+ return pauseNotSupported(cmd);
+}
+
+fn pauseNotSupported(cmd: *CDP.Command) !void {
+ return cmd.sendError(-32000, "Debugger pausing is not supported", .{});
+}
+
+fn sendInspector(cmd: *CDP.Command) !void {
+ const bc = cmd.browser_context orelse return error.BrowserContextNotLoaded;
+
+ // the result to return is handled directly by the inspector.
+ try bc.callInspector(cmd);
+}
+
+const testing = @import("../testing.zig");
+
+test "cdp.debugger: enable returns a debuggerId" {
+ var ctx = try testing.context();
+ defer ctx.deinit();
+
+ _ = try ctx.loadBrowserContext(.{ .id = "BID-DBG", .url = "hi.html", .target_id = "FID-00000DBG01".* });
+ try ctx.processMessage(.{ .id = 1, .method = "Debugger.enable" });
+
+ var i: usize = 0;
+ const result = blk: while (try ctx.getSentMessage(i)) |msg| : (i += 1) {
+ const id = msg.object.get("id") orelse continue;
+ if (id == .integer and id.integer == 1) break :blk msg.object.get("result").?;
+ } else return error.NoResult;
+ const debugger_id = result.object.get("debuggerId") orelse return error.NoDebuggerId;
+ try testing.expectEqual(true, debugger_id == .string and debugger_id.string.len > 0);
+
+ try ctx.processMessage(.{ .id = 2, .method = "Debugger.disable" });
+ try ctx.expectSentResult(null, .{ .id = 2 });
+}
+
+test "cdp.debugger: scriptParsed is sent to the session that enabled it" {
+ var ctx = try testing.context();
+ defer ctx.deinit();
+
+ const bc = try ctx.loadBrowserContext(.{ .id = "BID-DBG2", .url = "hi.html", .target_id = "FID-00000DBG02".*, .session_id = "SID-PRIMARY" });
+ _ = try bc.attachSession("SID-AUX", null);
+
+ try ctx.processMessage(.{ .id = 10, .method = "Debugger.enable", .sessionId = "SID-AUX" });
+ try ctx.processMessage(.{ .id = 11, .method = "Runtime.evaluate", .sessionId = "SID-AUX", .params = .{ .expression = "1 + 1\n//# sourceURL=dbg-test.js" } });
+ try ctx.expectSentEvent("Debugger.scriptParsed", .{ .url = "dbg-test.js" }, .{ .session_id = "SID-AUX" });
+
+ try ctx.processMessage(.{ .id = 12, .method = "Debugger.setSkipAllPauses", .sessionId = "SID-AUX", .params = .{ .skip = true } });
+ try ctx.expectSentResult(null, .{ .id = 12, .session_id = "SID-AUX" });
+}
+
+test "cdp.debugger: a debugger statement does not block execution" {
+ var ctx = try testing.context();
+ defer ctx.deinit();
+
+ _ = try ctx.loadBrowserContext(.{ .id = "BID-DBG3", .url = "hi.html", .target_id = "FID-00000DBG03".*, .session_id = "SID-PRIMARY" });
+ try ctx.processMessage(.{ .id = 20, .method = "Debugger.enable" });
+ try ctx.processMessage(.{ .id = 21, .method = "Runtime.evaluate", .params = .{ .expression = "debugger; 40 + 2", .returnByValue = true } });
+ try ctx.expectSentEvent("Debugger.paused", .{ .reason = "other" }, .{ .session_id = "SID-PRIMARY" });
+ try ctx.expectSentEvent("Debugger.resumed", null, .{ .session_id = "SID-PRIMARY" });
+ try ctx.expectSentResult(.{ .result = .{ .type = "number", .value = 42 } }, .{ .id = 21, .session_id = "SID-PRIMARY" });
+}
+
+test "cdp.debugger: pause commands are rejected" {
+ var ctx = try testing.context();
+ defer ctx.deinit();
+
+ _ = try ctx.loadBrowserContext(.{ .id = "BID-DBG4", .url = "hi.html", .target_id = "FID-00000DBG04".* });
+ try ctx.processMessage(.{ .id = 30, .method = "Debugger.enable" });
+
+ var id: usize = 31;
+ for ([_][]const u8{
+ "Debugger.pause",
+ "Debugger.pauseOnAsyncCall",
+ "Debugger.resume",
+ "Debugger.stepInto",
+ "Debugger.stepOver",
+ "Debugger.stepOut",
+ "Debugger.continueToLocation",
+ "Debugger.restartFrame",
+ "Debugger.evaluateOnCallFrame",
+ "Debugger.setReturnValue",
+ "Debugger.setVariableValue",
+ "Debugger.setBreakpoint",
+ "Debugger.setBreakpointByUrl",
+ "Debugger.setBreakpointOnFunctionCall",
+ "Debugger.setInstrumentationBreakpoint",
+ }) |method| {
+ try ctx.processMessage(.{ .id = id, .method = method });
+ try ctx.expectSentError(-32000, "Debugger pausing is not supported", .{ .id = id });
+ id += 1;
+ }
+}
+
+test "cdp.debugger: setPauseOnExceptions only accepts none" {
+ var ctx = try testing.context();
+ defer ctx.deinit();
+
+ _ = try ctx.loadBrowserContext(.{ .id = "BID-DBG5", .url = "hi.html", .target_id = "FID-00000DBG05".* });
+ try ctx.processMessage(.{ .id = 50, .method = "Debugger.enable" });
+
+ try ctx.processMessage(.{ .id = 51, .method = "Debugger.setPauseOnExceptions", .params = .{ .state = "none" } });
+ try ctx.expectSentResult(null, .{ .id = 51 });
+
+ try ctx.processMessage(.{ .id = 52, .method = "Debugger.setPauseOnExceptions", .params = .{ .state = "all" } });
+ try ctx.expectSentError(-32000, "Debugger pausing is not supported", .{ .id = 52 });
+}