Skip to content

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.md
index 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.zig
index 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 age
try 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.zon
index 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 be
diff --git a/src/main.zig b/src/main.zig
index 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.zig
index 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.zig
index 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.