Add caller-provided logging

Author: jinzhongjia

README.md

@@ -34,6 +34,7 @@ The current phase provides:
 - per-window serial or concurrent binding and event execution through
   `Window.setEventMode()`;
 - bounded concurrent handlers through `WindowOptions.max_pending_events`;
+- caller-provided internal logging through `App.Options.logger`;
 - same-origin WebSocket validation for hosted content and external-page Origin
   validation for `.external_url`;
 - optional path-scoped `HttpOnly` cookie authorization through
@@ -120,6 +121,11 @@ Concurrent tasks own their event data, are bounded by
 `WindowOptions.max_pending_events`, and are canceled and joined by
 `Running.stop()`.
 
+Set `App.Options.logger` and optional `logger_user_data` to receive formatted
+internal messages with a `std.log.Level`. The message slice is valid only
+during the callback. The callback must be thread-safe when concurrent event
+handling is enabled. Without a callback, messages use `std.log`.
+
 `Window.bind("button", ...)` also dispatches clicks from elements with
 `id="button"`, including elements added after the bridge loads. DOM click
 handlers receive no arguments and their replies are ignored; explicit

docs/PURE_ZIG_REFACTOR.md

@@ -300,7 +300,6 @@ implementations.
 | `webui_is_shown()` | There is no window-level connected/shown query. |
 | `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. |
 | `webui_set_icon()`, `webui_set_icon_file()` | Window icon configuration is not implemented. |
 | `webui_open_url()` | The internal OS URL opener is not exposed as a general public API. |
 | `webui_get_best_browser()`, `webui_browser_exist()`, `webui_show_browser()`, `webui_set_browser_folder()` | Browser discovery, selection, and custom executable locations are not implemented. |
@@ -349,6 +348,7 @@ not implementation gaps:
 | `webui_navigate()`, `webui_send_raw()` | `Window.navigate()` and `Window.sendRaw()`. |
 | `webui_set_config(multi_client)` | `WindowOptions.max_clients`. |
 | `webui_set_config(use_cookies)` | `App.Options.use_cookies` adds a per-window, path-scoped `HttpOnly` authorization cookie while retaining capability URLs and protocol authentication. |
+| `webui_set_logger()` | `App.Options.logger` and `logger_user_data`; messages use `std.log.Level` and fall back to `std.log` when no callback is set. |
 | `webui_set_public()` | `App.Options.public` permits non-loopback listening only with TLS; Origin and explicit connection and protocol limits are enforced. |
 | `webui_set_tls_certificate()` | `App.Options.tls` accepts caller-provided PEM certificate and private-key bytes. |
 | `webui_set_port()`, `webui_get_port()`, `webui_get_free_port()` | `App.Options.port`, including `0` for automatic selection, and the running window URL. |
@@ -383,11 +383,10 @@ This completes the behavior represented by `webui_set_public()`,
 This completes `webui_bind()`, the remaining typed argument and return
 methods, and the public browser bridge surface.
 
-### Handler and event lifecycle
+### Handler and event lifecycle (complete)
 
-- Add a caller-provided logger.
-
-This completes `webui_set_logger()`.
+Implements asynchronous replies, per-window event scheduling, explicit
+connection waiting, and caller-provided logging.
 
 ### Dynamic content and client state
 
@@ -488,4 +487,7 @@ zig build -Dtarget=aarch64-macos
 
 Continue capability parity:
 
-1. Add a caller-provided logger.
+1. Allow runtime window content and resource handler replacement.
+2. Add targeted `Client.show()`.
+3. Add a window connected/shown query.
+4. Add an application default directory and window icons.

src/app.zig

@@ -49,6 +49,11 @@ pub const Limits = struct {
 };
 
 pub const Handler = *const fn (*Call, ?*anyopaque) anyerror!void;
+pub const Logger = *const fn (
+    level: std.log.Level,
+    message: []const u8,
+    user_data: ?*anyopaque,
+) void;
 pub const EventHandler = *const fn (
     *const Event,
     ?*anyopaque,
@@ -292,6 +297,8 @@ const WindowState = struct {
     token: u32 = 0,
     bindings: std.ArrayList(Binding) = .empty,
     event_binding: ?EventBinding = null,
+    logger: ?Logger,
+    logger_user_data: ?*anyopaque,
     mutex: std.Io.Mutex = .init,
     event_mutex: std.Io.Mutex = .init,
     event_mode: std.atomic.Value(EventMode),
@@ -324,6 +331,29 @@ const WindowState = struct {
         return null;
     }
 
+    fn log(
+        self: *const WindowState,
+        comptime level: std.log.Level,
+        comptime format: []const u8,
+        args: anytype,
+    ) void {
+        if (self.logger) |logger| {
+            // ponytail: internal messages are short; allocate only if
+            // caller-provided log text is added later.
+            var buffer: [512]u8 = undefined;
+            const message = std.fmt.bufPrint(&buffer, format, args) catch
+                "WebUI log message exceeded 512 bytes";
+            logger(level, message, self.logger_user_data);
+            return;
+        }
+        switch (level) {
+            .err => std.log.err(format, args),
+            .warn => std.log.warn(format, args),
+            .info => std.log.info(format, args),
+            .debug => std.log.debug(format, args),
+        }
+    }
+
     fn clientIndexById(self: *WindowState, id: u64) ?usize {
         // ponytail: max_clients is bounded and small; use a map if limits grow.
         for (self.clients.items, 0..) |connected, index|
@@ -547,7 +577,7 @@ const WindowState = struct {
                 event_binding_value.user_data,
             ) catch |err| {
                 if (err != error.Canceled)
-                    std.log.err("WebUI event handler failed: {}", .{err});
+                    self.log(.err, "WebUI event handler failed: {}", .{err});
             };
     }
 
@@ -1330,6 +1360,8 @@ pub const App = struct {
         public: bool = false,
         tls: ?Tls = null,
         use_cookies: bool = false,
+        logger: ?Logger = null,
+        logger_user_data: ?*anyopaque = null,
         limits: Limits = .{},
     };
 
@@ -1393,6 +1425,8 @@ pub const App = struct {
             .max_pending_replies = options.max_pending_replies,
             .max_pending_events = options.max_pending_events,
             .event_mode = .init(options.event_mode),
+            .logger = self.options.logger,
+            .logger_user_data = self.options.logger_user_data,
         };
         try self.windows.append(self.gpa, state);
         return .{ .state = state };
@@ -1404,6 +1438,8 @@ pub const App = struct {
         try self.validateNetworkOptions();
         for (self.windows.items) |window| {
             window.limits = self.options.limits;
+            window.logger = self.options.logger;
+            window.logger_user_data = self.options.logger_user_data;
             for (window.bindings.items) |binding|
                 if (binding.name.len > window.limits.max_binding_name_size)
                     return error.BindingNameTooLarge;
@@ -1835,7 +1871,7 @@ fn onMessage(
                 .kind = .connected,
                 .client = client,
             }) catch |err|
-                std.log.err("WebUI event dispatch failed: {}", .{err});
+                window.log(.err, "WebUI event dispatch failed: {}", .{err});
         }
         return;
     }
@@ -1913,7 +1949,7 @@ fn onMessage(
                 .client = client,
                 .data = data,
             }) catch |err|
-                std.log.err("WebUI event dispatch failed: {}", .{err});
+                window.log(.err, "WebUI event dispatch failed: {}", .{err});
         },
         else => connection.wsClose(.unsupported_data, ""),
     }
@@ -1928,7 +1964,7 @@ fn onClose(connection: *Linsang.Connection, user_data: ?*anyopaque) void {
                 .kind = .disconnected,
                 .client = client,
             }) catch |err|
-                std.log.err("WebUI event dispatch failed: {}", .{err});
+                window.log(.err, "WebUI event dispatch failed: {}", .{err});
             authenticated = true;
         }
     }
@@ -1940,6 +1976,63 @@ fn onClose(connection: *Linsang.Connection, user_data: ?*anyopaque) void {
         app.closed.store(true, .release);
 }
 
+const LoggerCapture = struct {
+    calls: usize = 0,
+    level: std.log.Level = .debug,
+    message: [128]u8 = undefined,
+    message_len: usize = 0,
+};
+
+fn captureLogger(
+    level: std.log.Level,
+    message: []const u8,
+    user_data: ?*anyopaque,
+) void {
+    const capture: *LoggerCapture = @ptrCast(@alignCast(user_data.?));
+    capture.calls += 1;
+    capture.level = level;
+    capture.message_len = @min(message.len, capture.message.len);
+    @memcpy(capture.message[0..capture.message_len], message[0..capture.message_len]);
+}
+
+fn failingEventHandler(_: *const Event, _: ?*anyopaque) !void {
+    return error.ExpectedLoggerFailure;
+}
+
+test "application logger receives level, message, and user data" {
+    const gpa = std.testing.allocator;
+    var capture: LoggerCapture = .{};
+    var app = App.init(gpa, .{
+        .logger = captureLogger,
+        .logger_user_data = &capture,
+    });
+    defer app.deinit();
+    const window = try app.createWindow(.{
+        .content = .{ .html = "logger test" },
+    });
+
+    window.state.log(.warn, "logger value {d}", .{42});
+    try std.testing.expectEqual(@as(usize, 1), capture.calls);
+    try std.testing.expectEqual(std.log.Level.warn, capture.level);
+    try std.testing.expectEqualStrings(
+        "logger value 42",
+        capture.message[0..capture.message_len],
+    );
+
+    window.onEvent(failingEventHandler, null);
+    window.state.invokeEvent(.{
+        .kind = .connected,
+        .client = .{ .state = window.state, .client_id = 1 },
+    }, null, window.state.event_binding);
+    try std.testing.expectEqual(@as(usize, 2), capture.calls);
+    try std.testing.expectEqual(std.log.Level.err, capture.level);
+    try std.testing.expect(std.mem.indexOf(
+        u8,
+        capture.message[0..capture.message_len],
+        "ExpectedLoggerFailure",
+    ) != null);
+}
+
 test "network options, origins, and protocol limits" {
     const gpa = std.testing.allocator;
     try (Limits{}).validate();

src/root.zig

@@ -9,6 +9,7 @@ pub const Running = @import("app.zig").Running;
 pub const Call = @import("app.zig").Call;
 pub const PendingReply = @import("app.zig").PendingReply;
 pub const Handler = @import("app.zig").Handler;
+pub const Logger = @import("app.zig").Logger;
 pub const Event = @import("app.zig").Event;
 pub const EventKind = @import("app.zig").EventKind;
 pub const EventMode = @import("app.zig").EventMode;