@jhh96/light-app-bridge 1.0.4 → 1.0.6

package/README.md

@@ -15,16 +15,15 @@
 | `window.worklink`（含 `invokeModuleMethodSync`） | 发送消息 / 取 webContentsId | preload 注入 |
 | `window.worklink.plugin.getContentContext` | 解析目标轻应用 webContentsId（**仅 plugin 角色**） | pluginLightAppPreload 注入 |
 
-**收消息（二选一，自动选择，不强依赖 waltz）：**
+**收消息（自动选择，不强依赖 waltz）：**
 
 | 监听后端 | 优先级 | 适用环境 | 说明 |
 |---------|--------|---------|------|
 | `window.waltz.event.on('native-call-js')` | 高（优先） | 有 waltz 注入的环境 | 推荐路径，立即可用 |
-| `window.handleMessageFromNative` | 低（回退） | 无 waltz 的环境 | hook 此全局方法（waltzBridge 投递消息的统一入口）。**可能晚于构造注入**，SDK 会轮询等待（上限 10s） |
+| `window.handleMessageFromNative` | 低（回退） | 无 waltz 的环境 | 由 SDK 定义此全局方法（该方法原本由 waltz.min.js 注册；无 waltz 时为 undefined，renderer 投递消息前会检查其类型，没人定义则消息被丢弃）。renderer 收到消息后主动调用它传入消息。若该方法已存在则包装透传，不破坏原逻辑 |
 
-- 两者都始终不可用时，`connect()`/`ready()` reject（构造不抛，因监听后端允许稍后出现）
 - SDK 内部按 waltz → handleMessageFromNative 顺序探测，无需手动指定
-- 握手会等监听就绪后才开始，避免早到的 ack/hello 丢失
+- 握手会等监听绑定后才开始，避免早到的 ack/hello 丢失
 
 ## 安装（两个项目）
 
@@ -59,14 +58,21 @@ bridge.onMessage((data, id) => {
 
 ```js
 {
-  __sdk: 'lightAppBridge',   // 标识：在 plugin-message 流中过滤出本 SDK 的消息
-  id: 'r_xxx',               // 关联 id：send 生成，回复原样带回
-  type: 'req' | 'res',       // 请求 / 响应
-  data: any                  // 任意业务数据
+  __sdk: 'LightAppBridge',    // SDK 标识：过滤出本 SDK 的消息，隔离其它消息
+  v: 1,                       // 协议版本号
+  id: 'r_xxx',                // 关联 id：send 生成，回复原样带回
+  type: 'hello'|'ack'|'req'|'res',  // 握手 hello/ack；业务 req/res
+  data: any                   // 任意业务数据
 }
 ```
 
+## 连接与生命周期
+
+- 构造即自动握手（插件发 hello 每秒重试；轻应用持续等待、不超时）
+- 握手失败后**再次 `connect()` 可重连**（自动重置状态，无需重建实例）
+- `destroy()` 销毁实例：解绑监听、拒绝未完成请求；销毁后 `send`/`connect` 立即 reject
+
 ## 文件
 
-- `src/lightAppBridge.js` —— SDK 源码（ESM，可直接 import）
-- `src/index.js` —— barrel re-export
+- `src/lightAppBridge.ts` —— SDK 源码（TypeScript，构建产物为 ESM）
+- `src/index.ts` —— barrel re-export

package/dist/lightAppBridge.d.ts

@@ -37,7 +37,7 @@ export interface Envelope {
 export interface BridgeOptions {
     /** send 默认超时(ms)，默认 3000 */
     timeout?: number;
-    /** 握手超时(ms)，默认 30000 */
+    /** 握手超时(ms)，默认 30000。仅 plugin 角色生效；lightapp 端持续等待，不超时 */
     handshakeTimeout?: number;
 }
 /** send 单次调用选项 */
@@ -70,6 +70,8 @@ export default class LightAppBridge {
     private _connectPromise;
     private _unlisten;
     private _listenerReady;
+    private _connectFailed;
+    private _destroyed;
     /**
      * @param role 角色，省略时按 window.worklink.plugin 是否存在自动探测
      * @param options 超时配置
@@ -85,13 +87,21 @@ export default class LightAppBridge {
     /** 处理一条归一化后的消息 */
     private _onMessage;
     /**
-     * 建立连接（握手）。构造时已自动调用，通常无需手动调；如需重新握手可再次调用。
-     *   - 插件：发起握手（解析目标 id → 发 hello → 每秒重试直到收到 ack）
-     *   - 轻应用：启动握手等待（被动等 hello；若插件始终未来则超时）
-     * 多次调用幂等，返回同一个连接 Promise。
+     * 建立连接（握手）。构造时已自动调用，通常无需手动调。
+     *   - 已连接 / 握手进行中：幂等，返回同一个 Promise
+     *   - 上次握手失败：重新发起（内部自动重置状态，无需重建实例——
+     *     典型场景：插件先启动、轻应用窗口尚未打开导致超时，对端就绪后再次 connect 即可）
+     *   - 实例已销毁：reject
+     * 行为：
+     *   - 插件：发起握手（解析目标 id → 发 hello → 每秒重试直到收到 ack 或超时）
+     *   - 轻应用：被动等待 hello（持续监听，不超时）
      * @returns 对端 webContentsId
      */
     connect(): Promise<number | null>;
+    /** 重置连接状态（用于首次握手或失败后重连） */
+    private _resetConnectState;
+    /** 连接失败：标记失败并 reject（再次 connect 可重试） */
+    private _failConnect;
     /** 发送 hello（携带自身 webContentsId） */
     private _sendHello;
     /** 收到 hello（轻应用侧）：记录对端、回 ack、完成握手 */
@@ -132,7 +142,7 @@ export default class LightAppBridge {
      * @returns 调用以取消监听
      */
     onMessage(handler: MessageHandler): () => void;
-    /** 销毁实例：解绑消息监听、清空待处理请求、停止握手重试 */
+    /** 销毁实例：解绑消息监听、清空待处理请求、停止握手重试。销毁后实例不可再用 */
     destroy(): void;
 }
 /**

package/dist/lightAppBridge.js

@@ -163,6 +163,8 @@ export default class LightAppBridge {
         this._started = false;
         this._unlisten = null;
         this._listenerReady = null;
+        this._connectFailed = false;
+        this._destroyed = false;
         let r = role === 'plugin' || role === 'lightapp' ? role : 'lightapp';
         if (role !== 'plugin' && role !== 'lightapp') {
             const wl = window.worklink;
@@ -204,7 +206,7 @@ export default class LightAppBridge {
         })
             .catch((e) => {
             // 理论上不会发生（无 waltz 时必走定义路径），保险起见让连接失败并给出原因
-            this._connectDeferred.reject(new Error('LightAppBridge 监听后端绑定失败 (' +
+            this._failConnect(new Error('LightAppBridge 监听后端绑定失败 (' +
                 (e && e.message ? e.message : String(e)) + ')'));
         });
     }
@@ -236,26 +238,40 @@ export default class LightAppBridge {
     }
     // —— 连接 / 握手 —— //
     /**
-     * 建立连接（握手）。构造时已自动调用，通常无需手动调；如需重新握手可再次调用。
-     *   - 插件：发起握手（解析目标 id → 发 hello → 每秒重试直到收到 ack）
-     *   - 轻应用：启动握手等待（被动等 hello；若插件始终未来则超时）
-     * 多次调用幂等，返回同一个连接 Promise。
+     * 建立连接（握手）。构造时已自动调用，通常无需手动调。
+     *   - 已连接 / 握手进行中：幂等，返回同一个 Promise
+     *   - 上次握手失败：重新发起（内部自动重置状态，无需重建实例——
+     *     典型场景：插件先启动、轻应用窗口尚未打开导致超时，对端就绪后再次 connect 即可）
+     *   - 实例已销毁：reject
+     * 行为：
+     *   - 插件：发起握手（解析目标 id → 发 hello → 每秒重试直到收到 ack 或超时）
+     *   - 轻应用：被动等待 hello（持续监听，不超时）
      * @returns 对端 webContentsId
      */
     connect() {
         var _a;
-        if (this._connectStarted)
+        if (this._destroyed) {
+            return Promise.reject(new Error('实例已销毁，请重建实例'));
+        }
+        if (this._connected)
+            return this._connectPromise;
+        if (this._connectStarted && !this._connectFailed)
             return this._connectPromise;
+        // 首次调用，或上次握手失败：重置连接状态重新发起
+        this._resetConnectState();
         this._connectStarted = true;
         // 等监听后端绑定完成后再握手，避免对端的 ack/hello 在监听绑定前到达而丢失
         const listenerReady = (_a = this._listenerReady) !== null && _a !== void 0 ? _a : Promise.resolve();
-        // 握手超时保护
-        this._handshakeTimer = setTimeout(() => {
-            if (!this._connected) {
-                this._connectDeferred.reject(new Error(`握手超时 (${this.handshakeTimeout}ms)，对端未响应`));
-                this._clearHelloTimer();
-            }
-        }, this.handshakeTimeout);
+        // 握手超时保护：仅插件（主动方）需要——它发了 hello 却收不到 ack 说明对端异常。
+        // 轻应用（被动方）持续等待，不超时：插件可能任意晚才发起连接。
+        if (this.role === 'plugin') {
+            this._handshakeTimer = setTimeout(() => {
+                if (!this._connected) {
+                    this._failConnect(new Error(`握手超时 (${this.handshakeTimeout}ms)，对端未响应`));
+                    this._clearHelloTimer();
+                }
+            }, this.handshakeTimeout);
+        }
         listenerReady
             .then(() => {
             if (this._connected)
@@ -277,9 +293,31 @@ export default class LightAppBridge {
             }
             // lightapp 被动等待 hello（listener 已绑定），收到后在 _onHello 中回 ack 并 resolve
         })
-            .catch((e) => this._connectDeferred.reject(e));
+            .catch((e) => this._failConnect(e));
         return this._connectPromise;
     }
+    /** 重置连接状态（用于首次握手或失败后重连） */
+    _resetConnectState() {
+        this._connectDeferred = deferred();
+        this._connectPromise = this._connectDeferred.promise.then((peerId) => {
+            this._onConnected(peerId);
+            return peerId;
+        });
+        this._connectFailed = false;
+        this._connectStarted = false;
+        this._clearHelloTimer();
+        if (this._handshakeTimer) {
+            clearTimeout(this._handshakeTimer);
+            this._handshakeTimer = null;
+        }
+    }
+    /** 连接失败：标记失败并 reject（再次 connect 可重试） */
+    _failConnect(e) {
+        if (this._destroyed)
+            return;
+        this._connectFailed = true;
+        this._connectDeferred.reject(e instanceof Error ? e : new Error(String(e)));
+    }
     /** 发送 hello（携带自身 webContentsId） */
     _sendHello() {
         if (this._target == null)
@@ -288,16 +326,18 @@ export default class LightAppBridge {
     }
     /** 收到 hello（轻应用侧）：记录对端、回 ack、完成握手 */
     _onHello(fromId) {
-        if (fromId != null)
-            this._recordPeer(fromId);
+        if (fromId == null)
+            return; // 无法定位对端则忽略（真实环境该字段恒有值），握手不完成
+        this._recordPeer(fromId);
         // 回 ack，携带自身 webContentsId
-        if (fromId != null)
-            this._send(fromId, this._envelope('ack', { from: this.getId() }));
+        this._send(fromId, this._envelope('ack', { from: this.getId() }));
         // 握手完成（resolve 幂等，重复 hello 只回 ack）
         this._connectDeferred.resolve(fromId);
     }
     /** 收到 ack（插件侧）：确认连接 */
     _onAck(fromId) {
+        if (fromId == null)
+            return; // 无法定位对端则忽略
         this._recordPeer(fromId);
         this._connectDeferred.resolve(fromId);
     }
@@ -399,6 +439,8 @@ export default class LightAppBridge {
      * @returns 对端回调返回的数据
      */
     send(data, options = {}) {
+        if (this._destroyed)
+            return Promise.reject(new Error('实例已销毁'));
         const timeout = options.timeout != null ? options.timeout : this.timeout;
         return this.ready().then((targetId) => {
             const id = genId();
@@ -434,8 +476,11 @@ export default class LightAppBridge {
                 this._messageHandlers.splice(i, 1);
         };
     }
-    /** 销毁实例：解绑消息监听、清空待处理请求、停止握手重试 */
+    /** 销毁实例：解绑消息监听、清空待处理请求、停止握手重试。销毁后实例不可再用 */
     destroy() {
+        if (this._destroyed)
+            return;
+        this._destroyed = true;
         if (this._unlisten) {
             try {
                 this._unlisten();
@@ -448,6 +493,8 @@ export default class LightAppBridge {
             clearTimeout(this._handshakeTimer);
             this._handshakeTimer = null;
         }
+        // 进行中的握手直接失败（已 resolve 的话 reject 是 no-op）
+        this._connectDeferred.reject(new Error('实例已销毁'));
         // 拒绝所有未完成的请求
         this._pending.forEach((p) => {
             clearTimeout(p.timer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhh96/light-app-bridge",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "type": "module",
   "description": "招商随行（WorkLink）插件窗口(plugin)与轻应用窗口(lightapp)之间的双向通信 SDK",
   "main": "./dist/index.js",