Add browser connection waiting

Author: jinzhongjia

README.md

@@ -11,6 +11,8 @@ The current phase provides:
 - one `App`, multiple isolated windows, and automatic port selection;
 - embedded HTML, static directories, custom resources, external URLs, and a
   built-in JavaScript bridge;
+- explicit browser connection waiting and timeout through
+  `Window.waitForConnection()`;
 - JavaScript calls to Zig bindings with return values;
 - typed integer, float, and boolean call arguments and replies;
 - owned one-shot delayed binding replies through `Call.deferReply()`;
@@ -96,6 +98,11 @@ Building and using the library does not require Node or npm. `Window.evalAll`
 returns owned results; call `deinit` on them after consuming every per-client
 outcome.
 
+`Window.open()` launches the browser and returns immediately. Call
+`Window.waitForConnection(io, timeout)` when startup must wait for a browser;
+it returns the first connected `Client`. `Window.eval()` uses the same total
+timeout for connection waiting and JavaScript execution.
+
 Serve a directory by setting
 `.content = .{ .directory = "path/to/public" }`. The path is opened when the
 app starts and closed when it stops. Custom resources receive `webui.Request`

docs/PURE_ZIG_REFACTOR.md

@@ -298,7 +298,6 @@ implementations.
 | `webui_show()`, `webui_set_root_folder()`, `webui_set_file_handler()`, `webui_set_file_handler_window()` | Content and resource handling can only be selected when creating a window; replacing them at runtime is not implemented. |
 | `webui_show_client()` | `Client` cannot replace the content of only one connected browser. |
 | `webui_is_shown()` | There is no window-level connected/shown query. |
-| `webui_set_config(show_wait_connection)`, `webui_set_timeout()` | `Window.open()` does not optionally wait for a browser connection. |
 | `webui_set_config(folder_monitor)` | Directory change monitoring and automatic browser reload are not implemented. |
 | `webui_set_default_root_folder()` | There is no application-wide default directory content setting. |
 | `webui_set_logger()` | There is no caller-provided logging callback. |
@@ -343,6 +342,7 @@ not implementation gaps:
 | `webui_return_string()`, `webui_return_int()`, `webui_return_float()`, `webui_return_bool()` | `Call.reply()`, `Call.replyInt()`, `Call.replyFloat()`, and `Call.replyBool()`. |
 | `webui_set_config(asynchronous_response)` | `Call.deferReply()` transfers the response to a bounded, owned, one-shot `PendingReply`. |
 | `webui_set_config(ui_event_blocking)`, `webui_set_event_blocking()` | `WindowOptions.event_mode` and `Window.setEventMode()` select serial or bounded concurrent binding and event execution. |
+| `webui_set_config(show_wait_connection)`, `webui_set_timeout()` | `Window.open()` remains non-blocking; callers explicitly compose it with `Window.waitForConnection(io, timeout)`. |
 | `webui_run()`, `webui_script()` | `Window.run()` and `Window.eval()`. |
 | `webui_run_client()`, `webui_script_client()` | `Client.run()` and `Client.eval()`. |
 | `webui_close_client()`, `webui_navigate_client()`, `webui_send_raw_client()` | `Client.close()`, `Client.navigate()`, and `Client.sendRaw()`. |
@@ -385,11 +385,9 @@ methods, and the public browser bridge surface.
 
 ### Handler and event lifecycle
 
-- Add optional wait-for-connection behavior and a connection timeout.
 - Add a caller-provided logger.
 
-This completes `webui_set_config(show_wait_connection)`,
-`webui_set_timeout()`, and `webui_set_logger()`.
+This completes `webui_set_logger()`.
 
 ### Dynamic content and client state
 
@@ -490,5 +488,4 @@ zig build -Dtarget=aarch64-macos
 
 Continue capability parity:
 
-1. Add optional wait-for-connection behavior and a connection timeout.
-2. Add a caller-provided logger.
+1. Add a caller-provided logger.

src/app.zig

@@ -232,6 +232,11 @@ const ConnectedClient = struct {
     peer: Linsang.WebSocketPeer,
 };
 
+const SelectedClient = struct {
+    id: u64,
+    peer: Linsang.WebSocketPeer,
+};
+
 const DirectoryContent = struct {
     path: []u8,
     dir: ?std.Io.Dir = null,
@@ -734,50 +739,68 @@ const WindowState = struct {
         return sent;
     }
 
-    fn eval(
+    fn waitForClient(
         self: *WindowState,
         io: std.Io,
         target_client_id: ?u64,
-        script: []const u8,
-        result_buffer: []u8,
-        timeout: std.Io.Duration,
-    ) !EvalResult {
-        try validateRunScript(script, self.limits.max_script_size);
-
-        const deadline = std.Io.Clock.Timestamp.fromNow(io, .{
-            .clock = .awake,
-            .raw = timeout,
-        });
-        var client_id: u64 = undefined;
-        var peer: Linsang.WebSocketPeer = while (true) {
+        require_single: bool,
+        deadline: std.Io.Clock.Timestamp,
+    ) !SelectedClient {
+        while (true) {
             self.mutex.lockUncancelable(io);
             if (target_client_id) |target| {
                 if (self.clientIndexById(target)) |index| {
-                    client_id = target;
-                    const owned = self.clients.items[index].peer.clone();
+                    const selected = SelectedClient{
+                        .id = target,
+                        .peer = self.clients.items[index].peer.clone(),
+                    };
                     self.mutex.unlock(io);
-                    break owned;
+                    return selected;
                 }
                 self.mutex.unlock(io);
                 return error.ConnectionClosed;
             }
-            if (self.clients.items.len == 1) {
-                client_id = self.clients.items[0].id;
-                const owned = self.clients.items[0].peer.clone();
-                self.mutex.unlock(io);
-                break owned;
-            }
-            if (self.clients.items.len > 1) {
+            if (self.clients.items.len > 0) {
+                if (require_single and self.clients.items.len > 1) {
+                    self.mutex.unlock(io);
+                    return error.MultipleClientsConnected;
+                }
+                const selected = SelectedClient{
+                    .id = self.clients.items[0].id,
+                    .peer = self.clients.items[0].peer.clone(),
+                };
                 self.mutex.unlock(io);
-                return error.MultipleClientsConnected;
+                return selected;
             }
             self.mutex.unlock(io);
             if (deadline.compare(.lte, .now(io, .awake))) return error.Timeout;
-            // ponytail: polling is enough while one window owns the server;
-            // replace it with an event when multiple windows are supported.
+            // ponytail: 1 ms polling is enough for browser startup; use a
+            // condition if sub-millisecond connection wakeups matter.
             try std.Io.sleep(io, .fromMilliseconds(1), .awake);
-        };
-        defer peer.deinit();
+        }
+    }
+
+    fn eval(
+        self: *WindowState,
+        io: std.Io,
+        target_client_id: ?u64,
+        script: []const u8,
+        result_buffer: []u8,
+        timeout: std.Io.Duration,
+    ) !EvalResult {
+        try validateRunScript(script, self.limits.max_script_size);
+
+        const deadline = std.Io.Clock.Timestamp.fromNow(io, .{
+            .clock = .awake,
+            .raw = timeout,
+        });
+        var selected = try self.waitForClient(
+            io,
+            target_client_id,
+            true,
+            deadline,
+        );
+        defer selected.peer.deinit();
 
         var pending: PendingEval = undefined;
         self.mutex.lockUncancelable(io);
@@ -787,7 +810,7 @@ const WindowState = struct {
         }
         pending = .{
             .id = self.nextEvalId(),
-            .client_id = client_id,
+            .client_id = selected.id,
             .buffer = result_buffer,
         };
         self.pending_evals.append(self.gpa, &pending) catch |err| {
@@ -804,7 +827,7 @@ const WindowState = struct {
             .id = pending.id,
             .command = .js,
         }, script);
-        peer.sendBinary(packet.items) catch |err| switch (err) {
+        selected.peer.sendBinary(packet.items) catch |err| switch (err) {
             error.Closed => return error.ConnectionClosed,
             else => return err,
         };
@@ -1132,6 +1155,22 @@ pub const Window = struct {
         try browser.open(self.state.gpa, io, page_url);
     }
 
+    /// Wait for at least one browser connection and return the first client.
+    pub fn waitForConnection(
+        self: Window,
+        io: std.Io,
+        timeout: std.Io.Duration,
+    ) !Client {
+        var selected = try self.state.waitForClient(
+            io,
+            null,
+            false,
+            .fromNow(io, .{ .clock = .awake, .raw = timeout }),
+        );
+        defer selected.peer.deinit();
+        return .{ .state = self.state, .client_id = selected.id };
+    }
+
     pub fn url(
         self: Window,
         running: *const Running,
@@ -2510,6 +2549,65 @@ fn authenticateTestClient(
     return std.mem.eql(u8, response.payload, &.{1});
 }
 
+test "window connection waiting observes clients and timeouts" {
+    if (@import("builtin").os.tag != .linux) return error.SkipZigTest;
+    const gpa = std.testing.allocator;
+    var threaded = std.Io.Threaded.init(gpa, .{ .async_limit = .unlimited });
+    defer threaded.deinit();
+    const io = threaded.io();
+
+    var app = App.init(gpa, .{});
+    defer app.deinit();
+    const window = try app.createWindow(.{
+        .content = .{ .html = "connection wait test" },
+    });
+    var running = try app.start(io);
+    defer running.stop() catch {};
+
+    try std.testing.expectError(
+        error.Timeout,
+        window.waitForConnection(io, .fromMilliseconds(5)),
+    );
+    var waiting = io.async(Window.waitForConnection, .{
+        window,
+        io,
+        std.Io.Duration.fromSeconds(1),
+    });
+    defer _ = waiting.cancel(io) catch {};
+
+    const stream = try connectTestWebSocket(
+        running.inner.address,
+        io,
+        &window.state.capability,
+    );
+    defer stream.close(io);
+    var response_buffer: [125]u8 = undefined;
+    try std.testing.expect(try authenticateTestClient(
+        stream,
+        io,
+        gpa,
+        window.state.token,
+        &window.state.capability,
+        &response_buffer,
+    ));
+
+    const delayed = try waiting.await(io);
+    try std.testing.expect(delayed.isConnected(io));
+    const immediate = try window.waitForConnection(io, .zero);
+    try std.testing.expectEqual(delayed.id(), immediate.id());
+
+    try stream.shutdown(io, .both);
+    for (0..100) |_| {
+        if (!delayed.isConnected(io)) break;
+        try std.Io.sleep(io, .fromMilliseconds(1), .awake);
+    }
+    try std.testing.expect(!delayed.isConnected(io));
+    try std.testing.expectError(
+        error.Timeout,
+        window.waitForConnection(io, .fromMilliseconds(5)),
+    );
+}
+
 test "binding replies can be deferred, bounded, and disconnected" {
     if (@import("builtin").os.tag != .linux) return error.SkipZigTest;
     const gpa = std.testing.allocator;