Lightpanda: the headless browser designed for AI and automation
feat(server): add optional Unix-domain CDP socket
Robert McConnellea1167470d51
diff --git a/README.md b/README.mdindex d2bdf4a59..45f0eddac 100644--- a/README.md+++ b/README.md@@ -120,6 +120,28 @@ available to adjust waiting time before dump.```console./lightpanda serve --obey-robots --log-format pretty --log-level info --host 127.0.0.1 --port 9222```+For an optional **local Unix-domain socket listener** instead of TCP (on+Unix-like hosts), use an absolute socket path:++```sh+./lightpanda serve --socket /run/user/1000/lightpanda.sock+curl --unix-socket /run/user/1000/lightpanda.sock http://localhost/json/version+```++`--socket` cannot be combined with `--host`, `--port`, or+`--advertise-host`. The socket is created with owner-only (`0600`)+permissions, is not replaced if already present, and is unlinked on normal+server shutdown. Clients must support HTTP/WebSocket over Unix sockets and+connect directly to the specified socket path; `/json/version` reports a+null `webSocketDebuggerUrl` because no TCP endpoint exists. Ordinary+Puppeteer/Playwright connections to `ws://127.0.0.1:9222` still use the+existing TCP mode.++Unix socket permissions are **not** isolation from other processes sharing+the same Unix identity, including processes that can inspect or change the+server's runtime. Use separate OS users or an execution sandbox when+running untrusted agents.+Once the CDP server started, you can run a Puppeteer script by configuring the`browserWSEndpoint`.diff --git a/src/Config.zig b/src/Config.zigindex 71ed02546..d2cdbedf3 100644--- a/src/Config.zig+++ b/src/Config.zig@@ -405,8 +405,9 @@ pub const Commands = cli.Builder(.{.{.name = "serve",.options = .{- .{ .name = "host", .type = []const u8, .default = "127.0.0.1" },- .{ .name = "port", .type = u16, .default = 9222 },+ .{ .name = "host", .type = ?[]const u8 },+ .{ .name = "port", .type = ?u16 },+ .{ .name = "socket", .type = ?[:0]const u8, .path = true },.{ .name = "advertise_host", .type = ?[]const u8 },// Repeatable; one server can speak several on the same port..{ .name = "protocol", .type = Protocol, .multiple = true },@@ -846,7 +847,7 @@ pub fn cookieJarFile(self: *const Config) ?[]const u8 {pub fn port(self: *const Config) u16 {return switch (self.mode) {- .serve => |opts| opts.port,+ .serve => |opts| opts.port orelse 9222,.mcp => |opts| opts.cdp_port orelse 0,else => unreachable,};@@ -854,7 +855,7 @@ pub fn port(self: *const Config) u16 {pub fn advertiseHost(self: *const Config) []const u8 {return switch (self.mode) {- .serve => |opts| opts.advertise_host orelse advertiseHostFallback(opts.host),+ .serve => |opts| opts.advertise_host orelse advertiseHostFallback(opts.host orelse "127.0.0.1"),.mcp => "127.0.0.1",else => unreachable,};@@ -899,7 +900,7 @@ fn advertiseHostFallback(host: []const u8) []const u8 {// resolvable, but the caller still benefits from emitting a guidance log.pub fn bindIsWildcard(self: *const Config) bool {return switch (self.mode) {- .serve => |opts| opts.advertise_host == null and isHostWildcard(opts.host),+ .serve => |opts| opts.advertise_host == null and isHostWildcard(opts.host orelse "127.0.0.1"),else => false,};}@@ -1304,6 +1305,23 @@ pub fn parseArgs(allocator: Allocator, proc_args: std.process.Args) !Config {command = .{ .agent = agent_opts };}+ // A Unix listener must not quietly open a TCP endpoint as well.+ if (command == .serve) {+ const opts = command.serve;+ if (opts.socket != null) {+ if (opts.host != null or opts.port != null or opts.advertise_host != null) {+ log.fatal(.app, "socket conflicts with TCP", .{});+ return error.InvalidArgument;+ }+ for (opts.protocol.items) |protocol| {+ if (protocol != .cdp) {+ log.fatal(.app, "socket is CDP-only", .{});+ return error.InvalidArgument;+ }+ }+ }+ }+if (command == .fetch and command.fetch.url.items.len == 0) {log.fatal(.app, "missing URL", .{ .hint = "usage: lightpanda fetch <url>... [OPTIONS]" });return error.MissingArgument;@@ -1849,3 +1867,24 @@ test "Config: parseArgs --load-resources defaults stylesheets on for mcp and agetry std.testing.expectEqual(case.image, resources.image);}}++test "Config: unix socket serve flag refuses TCP flags" {+ log.expectLog(&.{.app});+ const vectors = [_][*:0]const u8{ "lightpanda", "serve", "--socket", "/tmp/lp-test.sock", "--port", "9322" };+ const proc_args: std.process.Args = .{ .vector = &vectors };+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);+ defer arena.deinit();+ try std.testing.expectError(error.InvalidArgument, parseArgs(arena.allocator(), proc_args));+}++test "Config: unix socket serve flag is parsed without opening TCP" {+ const vectors = [_][*:0]const u8{ "lightpanda", "serve", "--socket", "/tmp/lp-test.sock" };+ const proc_args: std.process.Args = .{ .vector = &vectors };+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);+ defer arena.deinit();+ const config = try parseArgs(arena.allocator(), proc_args);+ try std.testing.expect(config.mode == .serve);+ try std.testing.expectEqualStrings("/tmp/lp-test.sock", config.mode.serve.socket.?);+ try std.testing.expectEqual(@as(?u16, null), config.mode.serve.port);+ try std.testing.expectEqual(@as(?[]const u8, null), config.mode.serve.host);+}diff --git a/src/help.zon b/src/help.zonindex 7008da4f9..3e2160c36 100644--- a/src/help.zon+++ b/src/help.zon@@ -68,6 +68,11 @@\\ cdp Chrome DevTools Protocol (WebSocket on /).\\ webdriver WebDriver BiDi (WebSocket on /session) plus the\\ classic WebDriver session endpoints.+ \\ --socket <PATH>+ \\ Serve CDP over a local Unix-domain socket instead of TCP.+ \\ Must be absolute; cannot combine with --host, --port,+ \\ --advertise-host, or WebDriver BiDi. Owner-only mode 0600.+ \\ /json/version does not advertise a TCP WebSocket URL.\\ --remote-allow-origins <ORIGIN>\\ Origin (e.g. http://localhost:3000) allowed in the Origin header\\ of CDP and BiDi WebSocket upgrades, or * to allow any. Can bediff --git a/src/main.zig b/src/main.zigindex 5ddc47fd0..e15b32555 100644--- a/src/main.zig+++ b/src/main.zig@@ -123,23 +123,26 @@ fn run(allocator: Allocator, main_arena: Allocator, proc_args: std.process.Args)switch (args.mode) {.serve => |opts| {log.debug(.app, "startup", .{ .mode = "serve", .snapshot = app.snapshot.fromEmbedded() });- const address = std.Io.net.IpAddress.parse(opts.host, opts.port) catch |err| {- log.fatal(.app, "invalid server address", .{ .err = err, .host = opts.host, .port = opts.port });- return args.printUsageAndExit(main_arena, .serve, false);- };-- var server = lp.Server.init(app, address) catch |err| {- if (err == error.AddressInUse) {- log.fatal(.app, "address already in use", .{- .host = opts.host,- .port = opts.port,- .hint = "Another process is already listening on this address. " ++- "Stop the other process or use --port to choose a different port.",- });- } else {- log.fatal(.app, "server run error", .{ .err = err });+ const server = if (opts.socket) |path| blk: {+ if (opts.host != null or opts.port != null or opts.advertise_host != null) {+ log.fatal(.app, "socket conflicts with TCP", .{});+ return error.InvalidArgument;}- return err;+ break :blk lp.Server.initUnix(app, path) catch |err| {+ log.fatal(.app, "unix socket server error", .{ .err = err, .path = path });+ return err;+ };+ } else blk: {+ const host = opts.host orelse "127.0.0.1";+ const port = opts.port orelse 9222;+ const address = std.Io.net.IpAddress.parse(host, port) catch |err| {+ log.fatal(.app, "invalid server address", .{ .err = err, .host = host, .port = port });+ return args.printUsageAndExit(main_arena, .serve, false);+ };+ break :blk lp.Server.init(app, address) catch |err| {+ log.fatal(.app, "server run error", .{ .err = err, .host = host, .port = port });+ return err;+ };};defer server.deinit();diff --git a/src/server/Server.zig b/src/server/Server.zigindex 0107d9d16..859391a2e 100644--- a/src/server/Server.zig+++ b/src/server/Server.zig@@ -61,6 +61,7 @@ const WS_READ_BUDGET = 256 * 1024;app: *App,io_engine: IOEngine,listener: posix.socket_t,+unix_path: ?[:0]const u8,listener_paused: bool,@@ -123,7 +124,26 @@ bidi_session_url: []const u8,json_version_response: []const u8,+const ListenerTransport = union(enum) {+ tcp: sys_net.IpAddress,+ unix: [:0]const u8,+};+pub fn init(app: *App, address: sys_net.IpAddress) !*Server {+ return initWithTransport(app, .{ .tcp = address });+}++/// Bind the existing HTTP/WebSocket protocol on a local Unix socket.+/// Does not remove a pre-existing pathname (which might belong to another service).+pub fn initUnix(app: *App, path: [:0]const u8) !*Server {+ if (path.len == 0 or path.len >= @sizeOf(@FieldType(posix.sockaddr.un, "path"))) {+ return error.InvalidSocketPath;+ }+ if (path[0] != '/') return error.SocketPathMustBeAbsolute;+ return initWithTransport(app, .{ .unix = path });+}++fn initWithTransport(app: *App, transport: ListenerTransport) !*Server {const config = app.config;const allocator = app.allocator;@@ -138,34 +158,63 @@ pub fn init(app: *App, address: sys_net.IpAddress) !*Server {const max_connections = fdBudget(config);+ var unix_bound = false;+ errdefer if (unix_bound) switch (transport) {+ .unix => |path| {+ _ = std.c.unlink(path.ptr);+ },+ .tcp => {},+ };+const listener = blk: {const flags = posix.SOCK.STREAM | posix.SOCK.CLOEXEC | posix.SOCK.NONBLOCK;- const l = try sys_net.socket(sys_net.family(&address), flags, posix.IPPROTO.TCP);+ const l = switch (transport) {+ .tcp => |address| try sys_net.socket(sys_net.family(&address), flags, posix.IPPROTO.TCP),+ .unix => try sys_net.socket(posix.AF.UNIX, flags, 0),+ };errdefer sys_net.close(l);- try posix.setsockopt(l, posix.SOL.SOCKET, posix.SO.REUSEADDR, &std.mem.toBytes(@as(c_int, 1)));- if (@hasDecl(posix.TCP, "NODELAY")) {- try posix.setsockopt(l, posix.IPPROTO.TCP, posix.TCP.NODELAY, &std.mem.toBytes(@as(c_int, 1)));- }-- const sa = sys_net.sockaddrFromAddress(&address);- try sys_net.bind(l, sa.ptr(), sa.len);- {- // look this up incase --port 0 was used- const bound_address = try sys_net.boundAddress(l);-- json_version_response = try http.buildJSONVersionResponse(app, bound_address.getPort());- errdefer allocator.free(json_version_response);-- bidi_session_url = try allocator.print("ws://{s}:{d}/session/", .{ config.advertiseHost(), bound_address.getPort() });- errdefer allocator.free(bidi_session_url);+ const bound_port: u16 = switch (transport) {+ .tcp => |address| tcp_bound: {+ try posix.setsockopt(l, posix.SOL.SOCKET, posix.SO.REUSEADDR, &std.mem.toBytes(@as(c_int, 1)));+ if (@hasDecl(posix.TCP, "NODELAY")) {+ try posix.setsockopt(l, posix.IPPROTO.TCP, posix.TCP.NODELAY, &std.mem.toBytes(@as(c_int, 1)));+ }+ const sa = sys_net.sockaddrFromAddress(&address);+ try sys_net.bind(l, sa.ptr(), sa.len);+ break :tcp_bound (try sys_net.boundAddress(l)).getPort();+ },+ .unix => |path| unix_socket: {+ var sa: posix.sockaddr.un = std.mem.zeroes(posix.sockaddr.un);+ sa.family = posix.AF.UNIX;+ @memcpy(sa.path[0..path.len], path);+ try sys_net.bind(l, @ptrCast(&sa), @intCast(@offsetOf(posix.sockaddr.un, "path") + path.len + 1));+ unix_bound = true;+ if (std.c.chmod(path.ptr, 0o600) != 0) return error.SocketPermissions;+ break :unix_socket 0;+ },+ };- try sys_net.listen(l, config.maxPendingConnections());- log.note(.note, "server running", .{- .address = bound_address,+ json_version_response = try http.buildJSONVersionResponse(app, switch (transport) {+ .tcp => bound_port,+ .unix => null,+ });+ errdefer allocator.free(json_version_response);+ bidi_session_url = try allocator.print("ws://{s}:{d}/session/", .{ config.advertiseHost(), bound_port });+ errdefer allocator.free(bidi_session_url);++ try sys_net.listen(l, config.maxPendingConnections());+ switch (transport) {+ .tcp => log.note(.note, "server running", .{+ .address = try sys_net.boundAddress(l),+ .max_connections = max_connections,+ .max_browser_connections = config.maxConnections(),+ }),+ .unix => |path| log.note(.note, "server running on unix socket", .{+ .path = path,.max_connections = max_connections,.max_browser_connections = config.maxConnections(),- });+ }),}break :blk l;@@ -205,6 +254,10 @@ pub fn init(app: *App, address: sys_net.IpAddress) !*Server {.app = app,.io_engine = io_engine,.listener = listener,+ .unix_path = switch (transport) {+ .tcp => null,+ .unix => |path| path,+ },.listener_paused = false,.scratch = scratch,.request_arena = std.heap.ArenaAllocator.init(allocator),@@ -249,6 +302,9 @@ pub fn deinit(self: *Server) void {allocator.free(self.json_version_response);allocator.free(self.bidi_session_url);sys_net.close(self.listener);+ if (self.unix_path) |path| {+ _ = std.c.unlink(path.ptr);+ }self.io_engine.deinit();allocator.destroy(self);}@@ -347,9 +403,12 @@ fn accept(self: *Server, now: u64) !void {}};errdefer sys_net.close(socket);- configureSocket(socket);+ if (self.unix_path == null) configureSocket(socket);- const peer = sys_net.addressFromSockaddr(@ptrCast(&address));+ const peer: sys_net.IpAddress = if (self.unix_path != null)+ .{ .ip4 = .loopback(0) }+ else+ sys_net.addressFromSockaddr(@ptrCast(&address));if (comptime lp.IS_DEBUG) {log.debug(.serve, "client connected", .{ .address = peer });}@@ -3621,3 +3680,37 @@ test "server: http connections stay ordered by deadline" {http.disconnect(lt.server, conn_a);http.disconnect(lt.server, conn_b);}++test "server: unix listener accepts a client and removes owned socket on shutdown" {+ var tmp = std.testing.tmpDir(.{});+ defer tmp.cleanup();+ const absolute_dir = try tmp.dir.realPathFileAlloc(testing.io, ".", testing.allocator);+ defer testing.allocator.free(absolute_dir);+ const path = try std.fmt.allocPrintSentinel(testing.allocator, "{s}/cdp.sock", .{absolute_dir}, 0);+ defer testing.allocator.free(path);++ const server = try Server.initUnix(testing.test_app, path);+ var live = true;+ defer if (live) server.deinit();+ try testing.expectEqual(@as(c_int, 0), std.c.access(path.ptr, 0));+ try testing.expectError(error.AddressInUse, Server.initUnix(testing.test_app, path));+ try server.io_engine.monitorListener(server.listener);++ const client = try sys_net.socket(posix.AF.UNIX, posix.SOCK.STREAM | posix.SOCK.CLOEXEC, 0);+ defer sys_net.close(client);+ var address: posix.sockaddr.un = std.mem.zeroes(posix.sockaddr.un);+ address.family = posix.AF.UNIX;+ @memcpy(address.path[0..path.len], path);+ try testing.expectEqual(@as(c_int, 0), std.c.connect(client, @ptrCast(&address), @intCast(@offsetOf(posix.sockaddr.un, "path") + path.len + 1)));+ try server.accept(lp.datetime.milliTimestamp(.boot));+ try testing.expect(server.http_connections.first != null);+ server.deinit();+ live = false;+ try testing.expect(std.c.access(path.ptr, 0) != 0);+}++test "server: unix listener refuses non-absolute and overlong paths" {+ try testing.expectError(error.SocketPathMustBeAbsolute, Server.initUnix(testing.test_app, "cdp.sock"));+ const too_long = "/" ++ "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";+ try testing.expectError(error.InvalidSocketPath, Server.initUnix(testing.test_app, too_long));+}diff --git a/src/server/http.zig b/src/server/http.zigindex fd5302559..d3f64f4e9 100644--- a/src/server/http.zig+++ b/src/server/http.zig@@ -1030,7 +1030,22 @@ fn touch(server: *Server, conn: *Connection, now: u64) void {server.http_connections.append(&conn.node);}-pub fn buildJSONVersionResponse(app: *const App, port: u16) ![]const u8 {+pub fn buildJSONVersionResponse(app: *const App, port: ?u16) ![]const u8 {+ // Unix sockets have no connectable TCP WebSocket URL. Do not invent+ // ws://localhost:0/ and accidentally advertise an unsecured endpoint.+ // Unix-socket-aware clients should connect directly to the socket path.+ if (port == null) {+ const body =+ "{\"Browser\": \"Lightpanda/1.0\", " +++ "\"Protocol-Version\": \"1.3\", " +++ "\"User-Agent\": \"Lightpanda/1.0\", " +++ "\"Lightpanda-Version\": \"" ++ lp.build_config.version ++ "\", " +++ "\"webSocketDebuggerUrl\": null}";+ return app.allocator.print(+ "HTTP/1.1 200 OK\r\nContent-Length: {d}\r\nContent-Type: application/json; charset=UTF-8\r\n\r\n{s}",+ .{ body.len, body },+ );+ }const host = app.config.advertiseHost();if (app.config.bindIsWildcard()) {// Serve is bound to INADDR_ANY but no --advertise-host was given;@@ -1049,14 +1064,14 @@ pub fn buildJSONVersionResponse(app: *const App, port: u16) ![]const u8 {"\"Lightpanda-Version\": \"" ++ lp.build_config.version ++ "\", " ++"\"webSocketDebuggerUrl\": \"ws://{s}:{d}/\"" ++"}}";- const body_len = std.fmt.count(body_format, .{ host, port });+ const body_len = std.fmt.count(body_format, .{ host, port.? });const response_format ="HTTP/1.1 200 OK\r\n" ++"Content-Length: {d}\r\n" ++"Content-Type: application/json; charset=UTF-8\r\n\r\n" ++body_format;- return try app.allocator.print(response_format, .{ body_len, host, port });+ return try app.allocator.print(response_format, .{ body_len, host, port.? });}// Where the upgraded socket goes: a new worker, or an existing session's.