bun-app-window 0.6.2 → 0.8.0

package/src/shell/ipc.ts

@@ -34,8 +34,7 @@ export type IpcRequestMessage = {
 };
 
 export type IpcReplyMessage =
-    | { t: "ipc:res"; id: number; ok: true; r: unknown }
-    | { t: "ipc:res"; id: number; ok: false; e: IpcErrorPayload };
+    { t: "ipc:res"; id: number; ok: true; r: unknown } | { t: "ipc:res"; id: number; ok: false; e: IpcErrorPayload };
 
 export type IpcEventMessage = {
     t: "ipc:evt";
@@ -65,17 +64,53 @@ export type IpcServerOptions = {
     service: ServiceMethods;
     /** 错误里是否回传 stack。开发期有用，生产应保持关闭 */
     exposeStack?: boolean;
+    /**
+     * 服务表出现客户端保留名时报错。默认 `true`。
+     *
+     * 保留名的表现是：服务端注册成功，客户端调用时解析为客户端自身成员，
+     * 请求不会发出，两端都不产生任何错误。默认终止启动的原因见 ADR 0020。
+     *
+     * 关闭此项仅应在服务表由外部输入动态生成、且已用别的手段校验时使用。
+     */
+    rejectReservedNames?: boolean;
+};
+
+/**
+ * IPC 客户端自身占用的属性名。
+ *
+ * 客户端是一个 Proxy，这些名字在 `get` 陷阱中解析为客户端成员，不会派发为远程调用。
+ * 服务表中同名的项因此永远不会被调用，而 `await client.close()` 也不会抛错
+ * （`await undefined` 是合法表达式），调用方无法区分「执行完毕」与「未派发」。
+ *
+ * 这份清单与客户端代理的拦截分支必须一致。`tests/ipc.test.ts` 中有一条断言逐名
+ * 验证「该名字不派发为远程调用」，两者分叉时该断言失败。
+ */
+export const RESERVED_CLIENT_KEYS = ["on", "off", "close", "connected", "pending", "then"] as const;
+
+/** 广播事件的选项 */
+export type EmitOptions = {
+    /**
+     * 保留最后一次载荷，在连接建立时向该连接回放一次。
+     *
+     * 用途是状态同步。宿主通常在 `createApp` 返回后立即广播一次窗口状态，而此刻
+     * 页面仍在加载、WebSocket 尚未建立，广播投递给零个连接且不回放，页面据此
+     * 获取的初始状态将永远为空。粘性事件使新连接在 `attach` 时立即获得当前值。
+     *
+     * 默认关闭。逐条通知类的事件若开启粘性，新连接会额外收到一条历史消息，
+     * 与「只推变化」的预期不符。
+     */
+    sticky?: boolean;
 };
 
 export type IpcServer = {
     /** 处理一条来自连接的原始消息。非 IPC 消息会被静默忽略 */
     handle(peer: IpcPeer, raw: string | Buffer | Uint8Array): Promise<void>;
-    /** 登记连接，`emit` 才会送到它 */
+    /** 登记连接，`emit` 才会送到它。粘性事件在此同步回放 */
     attach(peer: IpcPeer): void;
     /** 注销连接。close 时必须调，否则 emit 会向死连接写入 */
     detach(peer: IpcPeer): void;
     /** 广播事件给所有已登记连接。返回实际投递数 */
-    emit(event: string, payload?: unknown): number;
+    emit(event: string, payload?: unknown, options?: EmitOptions): number;
     /** 服务暴露的方法名（创建时的快照）。用于自检与文档 */
     readonly methods: readonly string[];
     /** 当前登记连接数 */
@@ -87,12 +122,7 @@ function isRequest(v: unknown): v is IpcRequestMessage {
         return false;
     }
     const o = v as Record<string, unknown>;
-    return (
-        o.t === "ipc:req" &&
-        typeof o.id === "number" &&
-        typeof o.m === "string" &&
-        Array.isArray(o.a)
-    );
+    return o.t === "ipc:req" && typeof o.id === "number" && typeof o.m === "string" && Array.isArray(o.a);
 }
 
 /**
@@ -123,6 +153,28 @@ export function createIpcServer(opts: IpcServerOptions): IpcServer {
     // 创建时快照：之后往 service 上挂东西不会改变对外声明
     const methods = Object.keys(service);
 
+    // 保留名冲突在创建时终止，而不是留到首次调用。
+    // 该冲突的既有表现是「调用成功、返回 undefined、服务端未执行」，
+    // 既无异常也无日志，只能靠阅读客户端实现才能定位（ADR 0020）。
+    if (opts.rejectReservedNames !== false) {
+        const conflicts = methods.filter((m) => (RESERVED_CLIENT_KEYS as readonly string[]).includes(m));
+        if (conflicts.length > 0) {
+            throw new Error(
+                `IPC 服务表包含客户端保留名：${conflicts.join(", ")}。\n` +
+                    `这些名字由 bun-app-window/ipc 的客户端自身占用，同名服务方法永远不会被调用，` +
+                    `且调用方不会收到任何错误。请改用其他名字（例如 close 改为 winClose）。\n` +
+                    `若服务表由外部输入生成且已另行校验，可传入 { rejectReservedNames: false } 关闭本检查。`,
+            );
+        }
+    }
+
+    /**
+     * 粘性事件的最后一次载荷。
+     *
+     * 每个事件名只保留一条，不累计：粘性的语义是「当前值」，不是「历史」。
+     */
+    const stickyEvents = new Map<string, IpcEventMessage>();
+
     const send = (peer: IpcPeer, msg: IpcMessage): void => {
         try {
             peer.send(JSON.stringify(msg));
@@ -162,9 +214,7 @@ export function createIpcServer(opts: IpcServerOptions): IpcServer {
             // hasOwnProperty 而非 `service[m]` 直接取：否则 "constructor" /
             // "__proto__" / "toString" 这类名字会命中原型链上的函数，
             // 等于把一个未知形状的东西当服务方法调用。
-            const fn = Object.prototype.hasOwnProperty.call(service, parsed.m)
-                ? service[parsed.m]
-                : undefined;
+            const fn = Object.prototype.hasOwnProperty.call(service, parsed.m) ? service[parsed.m] : undefined;
 
             if (!fn) {
                 send(peer, {
@@ -187,14 +237,27 @@ export function createIpcServer(opts: IpcServerOptions): IpcServer {
 
         attach(peer): void {
             connected.add(peer);
+            // 粘性事件在登记后同步回放：`attach` 返回时，新连接已收到全部当前值。
+            // 不引入定时器，避免「回放尚未到达」这一中间态。
+            for (const msg of stickyEvents.values()) {
+                try {
+                    peer.send(JSON.stringify(msg));
+                } catch {
+                    // 与 emit 一致：写入失败不中断其余回放
+                }
+            }
         },
 
         detach(peer): void {
             connected.delete(peer);
         },
 
-        emit(event, payload): number {
+        emit(event, payload, options): number {
             const msg: IpcEventMessage = { t: "ipc:evt", e: event, p: payload ?? null };
+            if (options?.sticky === true) {
+                // 同名事件覆盖上一次：粘性表示「当前值」，不是历史队列
+                stickyEvents.set(event, msg);
+            }
             const body = JSON.stringify(msg);
             let delivered = 0;
             for (const peer of connected) {
@@ -235,24 +298,21 @@ export type Channel = {
 
 /** 把方法表映射成「返回 Promise 的同名方法」 */
 export type ClientMethods<T> = {
-    [K in keyof T]: T[K] extends (...args: infer A) => infer R
-        ? (...args: A) => Promise<Awaited<R>>
-        : never;
+    [K in keyof T]: T[K] extends (...args: infer A) => infer R ? (...args: A) => Promise<Awaited<R>> : never;
 };
 
-export type IpcClient<T, E extends Record<string, unknown> = Record<string, never>> =
-    ClientMethods<T> & {
-        /** 订阅宿主推送的事件。返回取消订阅函数 */
-        on<K extends keyof E & string>(event: K, handler: (payload: E[K]) => void): () => void;
-        /** 取消订阅 */
-        off(event: string, handler: (payload: unknown) => void): void;
-        /** 关闭通道。未完成的调用会被 reject */
-        close(): void;
-        /** 通道当前是否可用 */
-        readonly connected: boolean;
-        /** 尚未收到回复的调用数 */
-        readonly pending: number;
-    };
+export type IpcClient<T, E extends Record<string, unknown> = Record<string, never>> = ClientMethods<T> & {
+    /** 订阅宿主推送的事件。返回取消订阅函数 */
+    on<K extends keyof E & string>(event: K, handler: (payload: E[K]) => void): () => void;
+    /** 取消订阅 */
+    off(event: string, handler: (payload: unknown) => void): void;
+    /** 关闭通道。未完成的调用会被 reject */
+    close(): void;
+    /** 通道当前是否可用 */
+    readonly connected: boolean;
+    /** 尚未收到回复的调用数 */
+    readonly pending: number;
+};
 
 export type ConnectOptions = {
     /** 已建立的通道。给了就不再自己连 */
@@ -388,9 +448,7 @@ export async function connect<T, E extends Record<string, unknown> = Record<stri
 ): Promise<IpcClient<T, E>> {
     const timeoutMs = opts.timeoutMs ?? 30000;
 
-    const channel =
-        opts.channel ??
-        (await webSocketChannel(opts.url ?? deriveUrl(opts.token)));
+    const channel = opts.channel ?? (await webSocketChannel(opts.url ?? deriveUrl(opts.token)));
 
     const pending = new Map<number, Pending>();
     const listeners = new Map<string, Set<(payload: unknown) => void>>();

package/src/shell/native.ts

@@ -10,61 +10,66 @@ import type { Pointer } from "bun:ffi";
 /**
  * 打开 libshell.dll。
  *
- * 导出面说明：DLL 实际导出 34 个符号，其中 `shell_start` 是 1.x 遗留入口，
- * TS 侧不声明、也不对外承诺（故下方声明 33 个）；`shell_debug_*` / `shell_self_*` 属排障面。
+ * 导出面说明：`shell_start` 是 1.x 遗留入口，TS 侧不声明、也不对外承诺；
+ * `shell_debug_*` / `shell_self_*` 属排障面。声明总数由
+ * `tests/native-surface.test.ts` 的 `DECLARED` 钉住——本文不写数字，避免随增删漂移。
  */
 export function openNativeLib(path: string) {
-  return dlopen(path, {
-    shell_start_ex: {
-      args: [FFIType.ptr, FFIType.ptr, FFIType.i32, FFIType.i32, FFIType.i32],
-      returns: FFIType.i32,
-    },
-    shell_post: { args: [FFIType.ptr], returns: FFIType.i32 },
-    shell_title: { args: [FFIType.ptr], returns: FFIType.i32 },
-    shell_minimize: { args: [], returns: FFIType.i32 },
-    shell_toggle_maximize: { args: [], returns: FFIType.i32 },
-    shell_close: { args: [], returns: FFIType.i32 },
-    shell_drag: { args: [], returns: FFIType.i32 },
-    shell_begin_resize: { args: [FFIType.i32], returns: FFIType.i32 },
-    shell_set_min_size: { args: [FFIType.i32, FFIType.i32], returns: FFIType.void },
-    shell_get_state: { args: [], returns: FFIType.i32 },
-    shell_is_alive: { args: [], returns: FFIType.i32 },
-    // 窗口生命周期事件：批量拉取（消费式），capacity 是记录条数
-    shell_poll_events: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
-    shell_stop: { args: [], returns: FFIType.void },
-    shell_error: { args: [], returns: FFIType.ptr },
-    // 系统集成面
-    shell_show: { args: [], returns: FFIType.i32 },
-    shell_set_app_id: { args: [FFIType.ptr], returns: FFIType.i32 },
-    shell_is_dark: { args: [], returns: FFIType.i32 },
-    shell_pick_folder: { args: [FFIType.ptr, FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
-    shell_error_text: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+    return dlopen(path, {
+        shell_start_ex: {
+            args: [FFIType.ptr, FFIType.ptr, FFIType.i32, FFIType.i32, FFIType.i32],
+            returns: FFIType.i32,
+        },
+        shell_post: { args: [FFIType.ptr], returns: FFIType.i32 },
+        shell_title: { args: [FFIType.ptr], returns: FFIType.i32 },
+        shell_minimize: { args: [], returns: FFIType.i32 },
+        shell_toggle_maximize: { args: [], returns: FFIType.i32 },
+        shell_close: { args: [], returns: FFIType.i32 },
+        shell_drag: { args: [], returns: FFIType.i32 },
+        shell_begin_resize: { args: [FFIType.i32], returns: FFIType.i32 },
+        shell_set_min_size: { args: [FFIType.i32, FFIType.i32], returns: FFIType.void },
+        shell_get_state: { args: [], returns: FFIType.i32 },
+        shell_is_alive: { args: [], returns: FFIType.i32 },
+        // 窗口生命周期事件：批量拉取（消费式），capacity 是记录条数
+        shell_poll_events: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+        shell_stop: { args: [], returns: FFIType.void },
+        shell_error: { args: [], returns: FFIType.ptr },
+        // 系统集成面
+        shell_show: { args: [], returns: FFIType.i32 },
+        shell_set_app_id: { args: [FFIType.ptr], returns: FFIType.i32 },
+        shell_is_dark: { args: [], returns: FFIType.i32 },
+        shell_pick_folder: { args: [FFIType.ptr, FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+        shell_error_text: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
 
-    // 应用化面（关掉浏览器行为 + 应用自定义右键菜单）
-    shell_set_browser_ui: { args: [FFIType.i32], returns: FFIType.i32 },
-    shell_show_app_menu: { args: [FFIType.i32, FFIType.i32, FFIType.ptr], returns: FFIType.i32 },
+        // 应用化面（关掉浏览器行为 + 应用自定义右键菜单）
+        shell_set_browser_ui: { args: [FFIType.i32], returns: FFIType.i32 },
+        shell_show_app_menu: { args: [FFIType.i32, FFIType.i32, FFIType.ptr], returns: FFIType.i32 },
 
-    // 窗口位置面
-    shell_get_bounds: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
-    shell_restore_bounds: {
-      args: [FFIType.i32, FFIType.i32, FFIType.i32, FFIType.i32, FFIType.i32, FFIType.i32],
-      returns: FFIType.i32,
-    },
+        // 窗口位置面
+        shell_get_bounds: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+        shell_restore_bounds: {
+            args: [FFIType.i32, FFIType.i32, FFIType.i32, FFIType.i32, FFIType.i32, FFIType.i32],
+            returns: FFIType.i32,
+        },
 
-    // 输入与视图面
-    shell_set_zoom: { args: [FFIType.f64], returns: FFIType.i32 },
-    shell_get_zoom: { args: [], returns: FFIType.f64 },
-    shell_reload: { args: [], returns: FFIType.i32 },
-    shell_devtools: { args: [], returns: FFIType.i32 },
-    shell_toggle_fullscreen: { args: [], returns: FFIType.i32 },
+        // 输入与视图面
+        shell_set_zoom: { args: [FFIType.f64], returns: FFIType.i32 },
+        shell_get_zoom: { args: [], returns: FFIType.f64 },
+        shell_reload: { args: [], returns: FFIType.i32 },
+        shell_devtools: { args: [], returns: FFIType.i32 },
+        shell_toggle_fullscreen: { args: [], returns: FFIType.i32 },
+        // 运行时形态切换（ADR 0019）。只在创建期给了 SHELL_FLAG_FRAMELESS 时可用，
+        // 否则 set 返回 -1 并把理由写进 shell_error_text；is 恒回创建期形态。
+        shell_set_frameless: { args: [FFIType.i32], returns: FFIType.i32 },
+        shell_is_frameless: { args: [], returns: FFIType.i32 },
 
-    // 排障面：不进稳定契约
-    shell_debug_hittest: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
-    shell_debug_metrics: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
-    shell_debug_dpi: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
-    shell_self_base: { args: [], returns: FFIType.u64 },
-    shell_self_path: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
-  });
+        // 排障面：不进稳定契约
+        shell_debug_hittest: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+        shell_debug_metrics: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+        shell_debug_dpi: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+        shell_self_base: { args: [], returns: FFIType.u64 },
+        shell_self_path: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+    });
 }
 
 export type NativeLib = ReturnType<typeof openNativeLib>;
@@ -75,20 +80,17 @@ export const cstr = (s: string) => ptr(new TextEncoder().encode(`${s}\0`));
 
 /** C 字符串指针 → JS 字符串；空指针或异常返回空串 */
 export function readCStr(p: unknown): string {
-  if (!p) return "";
-  try {
-    return new CString(p as never).toString();
-  } catch {
-    return "";
-  }
+    if (!p) return "";
+    try {
+        return new CString(p as never).toString();
+    } catch {
+        return "";
+    }
 }
 
 /** 读取原生侧写入定长缓冲的 UTF-8 文本 */
-export function readBuffer(
-  fill: (p: Pointer, len: number) => number,
-  size = 1024,
-): string {
-  const buf = new Uint8Array(size);
-  const n = fill(ptr(buf), buf.length);
-  return n > 0 ? new TextDecoder().decode(buf.subarray(0, n)) : "";
+export function readBuffer(fill: (p: Pointer, len: number) => number, size = 1024): string {
+    const buf = new Uint8Array(size);
+    const n = fill(ptr(buf), buf.length);
+    return n > 0 ? new TextDecoder().decode(buf.subarray(0, n)) : "";
 }