dsh-builtin-browser 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -4,6 +4,54 @@
 
 ---
 
+# 第四十三轮(2026-10-12,三个"看起来无关"的缺陷:载体被写死、宿主死了不换、设置读了不生效)
+
+这一轮的共同点不是症状,而是**判断被做了一次就再也不做了**:载体在启动时选一次、连接端口在建立时记一次、`browser.channel` 在 apply 时读一次。三次都发生在"当时是对的"的情况下,三次的后果都是"之后永远不对"。
+
+## 一、标签级三件套 + 裸根拦截(issue #26,@dengyun2018-commits)
+
+他带着一份本地 patch 来,已在 0.4.0 → 0.4.5 四个版本上实跑、每次 `apply --check` 零偏移。四条全部收下,两条判据换了实现:
+
+**标签 URL 跟踪**:每个标签记住"最后一次被接受的 URL"。`listTabs` 不再探测它已知为空的标签——未提交的视图上那次往返只能回答"没有";而"从未导航"与"导航过但读不出来"终于可区分(此前两者都塌进同一个空字符串)。读失败时保留上次的 URL,而不是把标签报成空的。
+
+**空白标签短路**:`snapshot` / `a11y` 在未导航的标签上立即返回空页,而不是在一个没有文档可提交的视图里跑采集器、先耗尽整个 30 秒预算。
+
+**超时自愈**:超时的读操作**原位替换**卡死的视图(标签对调用方保持同一个 id),并抛出 `BROWSER_SNAPSHOT_TIMEOUT` / `BROWSER_A11Y_TIMEOUT`。此前视图留在会话里,于是**之后的每一次读都要再付一遍 30 秒**——`terminatePage` 只中断正在跑的脚本,并不会让视图变得可读。它还有个每视图 3 次的待终止上限,所以反复读会累积挂起的 evaluate。
+
+**裸根拦截**:`browser_open` 拒绝不带 token 的 DSH web 根地址——它返回 401 页面,读起来像一个真站点。**判据用的是 `DSH_WEB_URL`(harness 自己导出的环境变量),而不是端口号**:这台机器的 GUI 在 3080 和 19387 上都跑过,硬编码端口会在最需要它的那次不匹配。识别陷阱靠的是形状——同源 + 根路径 + 无 token——不是数字。
+
+## 二、桌面壳退出后,浏览器面板跟着一起死
+
+用户报的是"浏览器不能正常使用了,只能重启 DSH"。
+
+链条是两处叠加:**载体只在启动时选一次,而且只能向上走**——自托管先注册,发现桌面 bridge 后把它换成 provider,紧接着 `selfHosted.dispose()`。**没有回退目标。**启动时那四次重试只覆盖"bridge 出现得晚",而代码注释自己写着这个交换是单向的。
+
+**`refreshEndpoint` 也救不了,原因很精确**:它比较 port 和 token,而死掉的 shell 留下的文件**内容原封不动**——文件看着是新的,指向的是尸体。
+
+**判据来自文件里本来就有的字段**:活的 shell 每 15 秒重写 `updatedAt`,所以**四次没刷新就不是"慢",是"没了"**。超过一分钟的端点现在被判定为墓碑,一次性上报,经由载体接口上新增的 `onLost`;entry 收到后用自托管把 provider 重新注册回来。**缺失 `updatedAt` 刻意不算过期**,否则所有比这个字段更老的 shell 都会在首次使用时就判死。
+
+失败信息也不再是裸的 `ECONNREFUSED`——它点名原因,因为读它的人正是决定要不要回退的那个。
+
+## 三、`browser.channel` 只在 apply 时读一次(issue #27,@sbtxdy)
+
+他给了一组对照测量:`Electron/44.5.1` 对 `Edg/155.0.0.0`,以及"改完不重启、进程里没有任何带插件自有 `--user-data-dir` 的 msedge.exe"。三条建议全收,第一条选了**热切换**而不是退让到 `restartRequired`。
+
+**载体实时重选**:选择逻辑改成一个 `chooseCarrier()`,设置路由在写入改变 channel 时重跑它。这里有一处必须一起动:`adopt` 原有的一次性 guard 会把晚到的载体直接 `dispose` 掉——**防两个载体抢入是对的,对"用户改设置"恰好是错的**,因为那正是"写成功了、然后新载体被安静丢掉"的来源。现在换掉旧载体的是新载体,且在装好之后才释放。
+
+**不生效的写会说出来**:响应区分"已应用"和"只存了"(`carrierRechosen`);载体由 composition 提供(桌面 shell)而 channel 无法生效时打 WARN。**对一次没人会读的写回 `ok`,是调用方唯一分不出"成功"和"什么都没做"的地方**。
+
+**拼错的值不再静默**:`resolveChannel` 把未知值退回默认——它的注释写着这是有意为之("手改的错别字不该静默选中别的浏览器"),**但结果让错别字和"设置没生效"长得一模一样**。退回是对的,静默退回不是:现在会报出原值并列出接受集合。**缺席保持安静**,否则警告会变成噪音。
+
+## 四、自我更正
+
+**第二节的光标是我的**:`BridgeConnection.refreshEndpoint` 的存在恰恰证明我知道"端口会变"这件事,但判据选成了"与当前不同",而墓碑的特征是"与当前相同但已经死了"。同一个字段的两端,我只写了会变的那一端。
+
+**测试**:237 → 250(本轮新增 13 条:标签 URL 与空白短路 3 条、墓碑与回退 4 条、channel 重选 6 条)。`tsc` 干净。其中超时自愈那条是**形状断言**而不是行为断言——真跑 30 秒太慢——这一点写进了 commit 和给报告者的回复里,免得以后有人把它读强。
+
+**发布**:0.4.7。`npm` 与仓库同步。
+
+---
+
 # 第四十二轮(2026-10-08,三个"能看见的"缺陷:跨会话读错、空白页堆积、升级登出)
 
 0.4.5 发布后,用户连续报了三个现象。**三个都在同一段代码的新实现里**,而它们看着毫不相干——一个是"别的会话读到我这边",一个是"一次开一堆空白页",一个是"升级后所有站点被登出"。前两个实际上是**同一个会话在两种状态下的两种表现**。

package/lib/browser-electron/bridge-connection.d.ts

@@ -23,6 +23,7 @@ export interface BridgeEndpoint {
 export declare class BridgeConnection {
     private endpoint;
     private readonly endpointPath?;
+    private readonly onLost?;
     private socket;
     private buffer;
     /** Outstanding requests by id. */
@@ -34,11 +35,14 @@ export declare class BridgeConnection {
     private idLessBridge;
     /** True once this connection may only have one request in flight at a time. */
     private serialisable;
+    /** True once the shell behind this connection has been reported gone. */
+    private lostNotified;
     /**
      * @param endpoint - the shell's published bridge endpoint.
      * @param endpointPath - where that endpoint is republished, so a moved port can be followed.
+     * @param onLost - called once when this connection concludes the shell behind it is gone.
      */
-    constructor(endpoint: BridgeEndpoint, endpointPath?: string | undefined);
+    constructor(endpoint: BridgeEndpoint, endpointPath?: string | undefined, onLost?: (() => void) | undefined);
     /**
      * Re-read the published endpoint, and adopt it if the shell has moved.
      *
@@ -53,6 +57,8 @@ export declare class BridgeConnection {
      * @returns true when a different endpoint was adopted.
      */
     private refreshEndpoint;
+    /** Report once that the shell is gone, so the surface can fall back instead of dialling it. */
+    private notifyLost;
     /**
      * Send one request, reusing the socket if it is still healthy.
      *

package/lib/browser-electron/bridge-connection.js

@@ -33,6 +33,15 @@ const MAX_BUFFER_BYTES = 128 * 1024 * 1024;
  * client then falls back to arrival order, which is what the protocol guaranteed before.
  */
 const REQUEST_ID_FIELD = 'bridgeRequestId';
+/**
+ * How long the published endpoint may go un-refreshed before its shell is presumed gone.
+ *
+ * A live shell rewrites the file every fifteen seconds (its keep-alive), so four missed refreshes
+ * is not a slow shell — it is a shell that exited and left its last write behind. The distinction
+ * matters because the file is the ONLY thing that says where the bridge is: a tombstone names a
+ * port nobody owns, and a client that trusts it dials that port for the rest of its life.
+ */
+const ENDPOINT_TTL_MS = 60_000;
 /**
  * A reusable connection to the bridge.
  *
@@ -51,6 +60,7 @@ const REQUEST_ID_FIELD = 'bridgeRequestId';
 export class BridgeConnection {
     endpoint;
     endpointPath;
+    onLost;
     socket;
     buffer = '';
     /** Outstanding requests by id. */
@@ -62,13 +72,17 @@ export class BridgeConnection {
     idLessBridge = false;
     /** True once this connection may only have one request in flight at a time. */
     serialisable = false;
+    /** True once the shell behind this connection has been reported gone. */
+    lostNotified = false;
     /**
      * @param endpoint - the shell's published bridge endpoint.
      * @param endpointPath - where that endpoint is republished, so a moved port can be followed.
+     * @param onLost - called once when this connection concludes the shell behind it is gone.
      */
-    constructor(endpoint, endpointPath) {
+    constructor(endpoint, endpointPath, onLost) {
         this.endpoint = endpoint;
         this.endpointPath = endpointPath;
+        this.onLost = onLost;
     }
     /**
      * Re-read the published endpoint, and adopt it if the shell has moved.
@@ -90,6 +104,13 @@ export class BridgeConnection {
             const raw = JSON.parse(readFileSync(this.endpointPath, 'utf8'));
             if (typeof raw.port !== 'number' || typeof raw.token !== 'string')
                 return false;
+            // A shell that exited stops refreshing the file, and what it left names a port nobody owns.
+            // Trusting it is how a host ends up dialling a dead port for the rest of the process's life
+            // — reported as "the browser stopped working and only restarting DSH brought it back".
+            if (endpointExpired(raw.updatedAt)) {
+                this.notifyLost();
+                return false;
+            }
             if (raw.port === this.endpoint.port && raw.token === this.endpoint.token)
                 return false;
             this.endpoint = {
@@ -105,6 +126,18 @@ export class BridgeConnection {
             return false;
         }
     }
+    /** Report once that the shell is gone, so the surface can fall back instead of dialling it. */
+    notifyLost() {
+        if (this.lostNotified)
+            return;
+        this.lostNotified = true;
+        try {
+            this.onLost?.();
+        }
+        catch {
+            // A listener must never break the transport: the caller's error is the one that matters.
+        }
+    }
     /**
      * Send one request, reusing the socket if it is still healthy.
      *
@@ -126,6 +159,14 @@ export class BridgeConnection {
         // when the condition could not clear, spun until the process ran out of heap.
         // Follow the shell if its bridge moved to a new port (see refreshEndpoint).
         this.refreshEndpoint();
+        // The shell behind this connection is gone, and the endpoint file says so. Refusing here is
+        // what turns a permanent ECONNREFUSED into one named error the surface can act on — by
+        // falling back to the browser it hosts itself, instead of dialling a dead port until DSH is
+        // restarted.
+        if (this.lostNotified) {
+            throw new Error('dsh-builtin-browser: the desktop shell that backed this browser has exited '
+                + '(its published endpoint stopped being refreshed)');
+        }
         let socket = this.ensureSocket();
         if (this.serialisable && this.queue.length > 0) {
             this.reset(new Error('dsh-builtin-browser: bridge connection reopened so replies stay attributable'));
@@ -281,8 +322,22 @@ export class BridgeConnection {
             entry.reject(error);
     }
 }
-/** The request id a raw answer line echoes back, when it carries one. */
-function echoOf(line) {
+/**
+ * Whether a published endpoint has gone un-refreshed long enough to be a tombstone.
+ *
+ * A missing or unparseable stamp is NOT expired: an older bridge that never wrote one must keep
+ * working, and guessing "stale" from absence would break every shell that predates the field.
+ * @param updatedAt - the file's own refresh stamp, when it carries one.
+ */
+function endpointExpired(updatedAt) {
+    if (typeof updatedAt !== 'string')
+        return false;
+    const at = Date.parse(updatedAt);
+    if (!Number.isFinite(at))
+        return false;
+    return Date.now() - at > ENDPOINT_TTL_MS;
+}
+/** The request id a raw answer line echoes back, when it carries one. */ function echoOf(line) {
     try {
         const answer = JSON.parse(line);
         const value = answer[REQUEST_ID_FIELD];

package/lib/browser-electron/desktop-bridge-host.d.ts

@@ -94,10 +94,21 @@ export declare class DesktopBridgeViewHost implements ElectronBrowserViewHost {
      * the desktop sidebar is the carrier — by design, not by omission.
      */
     private userActionHandler;
+    /** Told when the shell behind this bridge exits; see `onLost`. */
+    private lostListener;
     /**
      * @param endpoint - the shell's published bridge endpoint.
      */
     private constructor();
+    /**
+     * Called by the transport once the shell behind it is gone.
+     *
+     * Forwarded rather than acted on here: only the entry point owns the swap back to the self-hosted
+     * browser, and a host that tried to replace itself would be reaching outside its own contract.
+     */
+    private reportLost;
+    /** Register the "this carrier is gone" listener (see the interface's `onLost`). */
+    onLost(listener: () => void): void;
     /**
      * Find a usable desktop bridge, if this surface has one.
      *

package/lib/browser-electron/desktop-bridge-host.js

@@ -111,12 +111,32 @@ export class DesktopBridgeViewHost {
      * the desktop sidebar is the carrier — by design, not by omission.
      */
     userActionHandler;
+    /** Told when the shell behind this bridge exits; see `onLost`. */
+    lostListener;
     /**
      * @param endpoint - the shell's published bridge endpoint.
      */
     constructor(endpoint, sessionId) {
         this.owner = sessionId !== undefined && sessionId !== String.fromCharCode(39, 39) ? sessionId : randomUUID();
-        this.connection = new BridgeConnection(endpoint, bridgeEndpointPath());
+        this.connection = new BridgeConnection(endpoint, bridgeEndpointPath(), () => this.reportLost());
+    }
+    /**
+     * Called by the transport once the shell behind it is gone.
+     *
+     * Forwarded rather than acted on here: only the entry point owns the swap back to the self-hosted
+     * browser, and a host that tried to replace itself would be reaching outside its own contract.
+     */
+    reportLost() {
+        try {
+            this.lostListener?.();
+        }
+        catch {
+            // The listener's failure is not the transport's problem.
+        }
+    }
+    /** Register the "this carrier is gone" listener (see the interface's `onLost`). */
+    onLost(listener) {
+        this.lostListener = listener;
     }
     /**
      * Find a usable desktop bridge, if this surface has one.