dsh-panel-control 0.3.14 → 0.3.16

package/README.md

@@ -109,6 +109,16 @@ python -m http.server 8787 --bind 127.0.0.1   # 在仓库根目录
 - 文案改成「刷新后仍然缺：重启 DSH 才会应用新的插件清单」——这才是真正有效的动作。
 - 缺口修复后自动清除记忆，下次真出现新缺口还会提示。
 
+## 为什么重启后偶尔看不到入口（0.3.16）
+
+DSH 给每个插件的脚本算一个**版本号**，来源是文件的 `mtime / ctime / 大小`，注册表只认它自己在组装那一刻读到的那个版本。页面拿到的是**启动时那份清单**，只要 `client.js` 在清单发出去之后被重写过（编辑器保存、`git` 换行归一化、或者早先那个"自愈"改写），页面手里的版本号就成了作废的号，请求回 404，而页面**不会报错**——入口就这么没了。
+
+0.3.16 的处理：
+
+- Host 半只对本插件包装注册表的资源查询：页面若拿旧版本号来要，先用**本进程发过的同一版本字节**回答（缓存最近 5 个版本），再退到"用当前版本回答"，其余请求原样放行，卸载时撤掉包装。别家插件的行为一点不改。
+- 早先的"自愈"（改写 `client.js` 强制热加载）**默认关闭**：它会重跑所有插件的注册，邻居不幂等就会丢入口——`dsh-workspace-control` 就是这么被弄掉的。需要时用 `DPC_NUDGE=on` 显式打开。
+- `host.log` 每次 apply 打两行结论：`graph: lists|does not list <包名>` 和 `graph: own bundle at rev … answers 200|404`，一次就能分清是"没进清单"还是"清单有但取不到"。
+
 ## 代码审查后的加固（0.3.11）
 
 一轮完整审查（正确性 / 安全 / 可维护性 / 性能）之后改掉的东西，按主题记在这里，免得以后又踩回去。

package/index.js

@@ -33,7 +33,12 @@ const ROUTE_PATH = `/api/${ENDPOINT}`;
  * back to registration order. A file under the profile's data directory
  * survives restarts, upgrades and origin changes alike.
  */
-const STATE_DIR = path.join(os.homedir(), '.dsh', 'panel-control');
+// Tests (and anyone sandboxing this plugin) point DPC_STATE_DIR somewhere else;
+// the smoke harness writes here, and it must not touch the real preferences or
+// the real log that support questions get asked about.
+const STATE_DIR = process.env.DPC_STATE_DIR
+  ? path.resolve(process.env.DPC_STATE_DIR)
+  : path.join(os.homedir(), '.dsh', 'panel-control');
 const PREFS_FILE = path.join(STATE_DIR, 'prefs.json');
 const HOST_LOG = path.join(STATE_DIR, 'host.log');
 const CLIENT_LOG = path.join(STATE_DIR, 'client.log');
@@ -537,11 +542,140 @@ function logInventoryOnApply(scope) {
       `graph: ${listed ? 'lists' : 'does not list'} ${PACKAGE} · rev ${value.rev} · ` +
         `${value.ids.length} client entr${value.ids.length === 1 ? 'y' : 'ies'}`,
     );
+    if (listed) void probeOwnBundle(scope);
   } catch (error) {
     logHost(`graph: probe failed (${describeError(error)})`);
   }
 }
 
+/**
+ * Serve the current revision when a page asks for one this process has retired.
+ *
+ * The registry addresses every bundle by a revision derived from the file's
+ * mtime, ctime and size, and it answers only the revisions it read at
+ * composition time ("versioned code is immutable"). A page keeps the list it
+ * booted with, so as soon as this package's file is rewritten - by an editor, by
+ * git normalising line endings, or by the retry nudge that used to live here -
+ * the page's revision stops existing and its request becomes a 404 that nothing
+ * reports: the plugin is simply absent from the sidebar.
+ *
+ * This wraps the registry's own resource lookup for this one package. A 404 for
+ * a stale revision is retried at the revision the Host holds now, and the page
+ * gets the bytes it needs; everything else passes straight through, and the
+ * patch is undone on teardown.
+ */
+const SERVE_CURRENT = String(process.env.DPC_SERVE_CURRENT || '').toLowerCase() !== 'off';
+let servePatched = null;
+let serveLoggedAt = 0;
+/**
+ * Bytes this Host has already served, kept by revision.
+ *
+ * The registry serves a revision only while it is the current one. A page
+ * (or a page rebuilt by another tool) keeps asking for the revision it booted
+ * with, so the copy we handed out is the only thing that can answer it later.
+ * Five revisions is a few hundred kilobytes and covers a run of edits.
+ */
+const servedBytes = new Map();
+const SERVED_BYTES_KEPT = 5;
+
+function revisionOf(url) {
+  const match = /[?&]rev=([A-Za-z0-9._-]+)/.exec(String(url || ''));
+  return match ? match[1] : null;
+}
+
+function serveCurrentRevision(scope) {
+  if (!SERVE_CURRENT || servePatched) return;
+  const modules = clientModules || serviceOf(scope, 'clientModules');
+  if (!modules || typeof modules.bundleResource !== 'function') return;
+  const original = modules.bundleResource.bind(modules);
+  servePatched = modules;
+  modules.bundleResource = async function bundleResourceWithFallback(method, url) {
+    const answer = await original(method, url);
+    if (answer && answer.status === 200 && method === 'GET' && String(url || '').includes(PACKAGE)) {
+      const rev = revisionOf(url);
+      if (rev && typeof answer.body === 'string') {
+        servedBytes.delete(rev);
+        servedBytes.set(rev, answer);
+        while (servedBytes.size > SERVED_BYTES_KEPT) {
+          servedBytes.delete(servedBytes.keys().next().value);
+        }
+      }
+    }
+    if (answer && answer.status !== 404) return answer;
+    try {
+      const requested = String(url || '');
+      if (!requested.includes(PACKAGE)) return answer;
+      // A revision this Host already handed out outranks the current one: the
+      // page booted with it, and its list will keep naming it.
+      const asked = revisionOf(requested);
+      const remembered = asked ? servedBytes.get(asked) : undefined;
+      if (remembered !== undefined) {
+        if (Date.now() - serveLoggedAt > 30_000) {
+          serveLoggedAt = Date.now();
+          logHost(
+            `served ${PACKAGE} again at revision ${asked}: the page still runs the list it booted with`,
+          );
+        }
+        return method === 'HEAD' ? { ...remembered, body: undefined } : remembered;
+      }
+      const graph = typeof modules.graph === 'function' ? modules.graph() : null;
+      const rows = graph && Array.isArray(graph.entries) ? graph.entries : [];
+      const entry = rows.find((row) => row && row.id === PACKAGE);
+      if (!entry || typeof entry.url !== 'string') return answer;
+      const retryUrl = entry.url.startsWith('/') ? entry.url : `/${entry.url}`;
+      if (retryUrl === requested) return answer;
+      const retried = await original(method, retryUrl);
+      if (!retried || retried.status !== 200) return answer;
+      if (Date.now() - serveLoggedAt > 30_000) {
+        serveLoggedAt = Date.now();
+        logHost(
+          `served ${PACKAGE} at the current revision: the page asked for a retired one ` +
+            '(its plugin list predates the last write to client.js)',
+        );
+      }
+      return retried;
+    } catch (error) {
+      logHost(`stale revision fallback failed: ${describeError(error)}`);
+      return answer;
+    }
+  };
+}
+
+function releaseServeCurrent() {
+  const modules = servePatched;
+  servePatched = null;
+  if (!modules) return;
+  try {
+    delete modules.bundleResource;
+  } catch {
+    /* a frozen service keeps the wrapper; it only ever adds a retry */
+  }
+}
+
+/**
+ * Ask the Host to serve this package's own bundle, the way the page would.
+ *
+ * A row can be advertised and still be unservable: the registry answers only
+ * the revisions it read at composition time, and everything else is a 404 that
+ * the page drops without a word. Runs the same request the browser would make.
+ */
+async function probeOwnBundle(scope) {
+  try {
+    const modules = clientModules || serviceOf(scope, 'clientModules');
+    const graph = modules && typeof modules.graph === 'function' ? modules.graph() : null;
+    const entries = graph && Array.isArray(graph.entries) ? graph.entries : [];
+    const entry = entries.find((row) => row && row.id === PACKAGE);
+    if (!entry || typeof entry.url !== 'string' || typeof modules.fetchBundle !== 'function') return;
+    const response = await modules.fetchBundle({ method: 'GET', url: entry.url });
+    logHost(
+      `graph: own bundle at rev ${String(entry.rev)} answers ${response.status}` +
+        (response.status === 200 ? '' : ' — the page cannot load a bundle the Host will not serve'),
+    );
+  } catch (error) {
+    logHost(`graph: own bundle probe failed (${describeError(error)})`);
+  }
+}
+
 /**
  * Say it out loud when the page never came back.
  *
@@ -663,6 +797,7 @@ export function apply(ctx) {
     if (dispose) {
       logHost(`route mounted at ${ROUTE_PATH} (attempt ${attempts})`);
       logInventoryOnApply(scope);
+      serveCurrentRevision(scope);
       const startedAt = Date.now();
       // A timer callback that throws is fatal for the Host: contain it here and
       // again inside the async body.
@@ -699,6 +834,7 @@ export function apply(ctx) {
           }
         }
         dispose = null;
+        releaseServeCurrent();
       },
       `${PACKAGE}: classification route`,
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-panel-control",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "type": "module",
   "description": "Manage the global panel navigation at the top of the DSH sidebar: reorder, hide and group every entry, with the layout persisted per installation.",
   "keywords": [

package/scripts/host-smoke.mjs

@@ -10,9 +10,17 @@
  *   node .scratch/host-smoke.mjs
  */
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import fs from 'node:fs/promises';
 import path from 'node:path';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
+
+// Keep the harness out of the real preferences and the real host.log: the
+// module resolves its state directory at import time, so this must be set first.
+const STATE = path.join(here, '..', '.scratch', 'smoke-state');
+process.env.DPC_STATE_DIR = STATE;
+await fs.mkdir(STATE, { recursive: true });
+
 // `npm run smoke -- <file>` points the harness at another copy, which is how
 // a regression (or the broken revision that shipped once) gets reproduced.
 const override = process.argv[2];
@@ -43,6 +51,29 @@ function check(name, ok, detail) {
   }
 }
 
+// The registry currently holds revision "rev-now" for this package; the page
+// below asks for "rev-old", which is the 404 that silently drops a plugin.
+const clientModulesStub = {
+  served: [],
+  graph: () => ({
+    rev: 'rev-test',
+    release: 'rel',
+    entries: [
+      { id: 'a' },
+      { id: 'b' },
+      { id: 'dsh-panel-control', rev: 'rev-now', url: 'plugins/??dsh-panel-control/client.js&rev=rev-now' },
+    ],
+    batches: [],
+  }),
+  async bundleResource(method, url) {
+    clientModulesStub.served.push(String(url));
+    if (String(url).includes('rev-now') && !clientModulesStub.dropRev) {
+      return { status: 200, headers: { 'content-type': 'text/javascript' }, body: 'current' };
+    }
+    return { status: 404 };
+  },
+};
+
 const registrations = [];
 const scope = {
   get(key) {
@@ -58,7 +89,7 @@ const scope = {
       };
     }
     if (key === 'clientModules') {
-      return { graph: () => ({ rev: 'rev-test', release: 'rel', entries: [{ id: 'a' }, { id: 'b' }], batches: [] }) };
+      return clientModulesStub;
     }
     return undefined;
   },
@@ -158,7 +189,35 @@ if (route) {
     const body = await response.json();
     check('inventory answers', body && body.result && body.result.ok === true, JSON.stringify(body).slice(0, 160));
     check('inventory rev matches graph', body.result.value.rev === 'rev-test', body.result.value && body.result.value.rev);
-    check('inventory ids', Array.isArray(body.result.value.ids) && body.result.value.ids.join() === 'a,b');
+
+    const stale = await clientModulesStub.bundleResource(
+      'GET',
+      '/plugins/??dsh-panel-control/client.js&rev=rev-old',
+    );
+    check('stale revision is served at the current one', stale.status === 200, `status ${stale.status}`);
+    // A revision this Host already handed out must survive the registry
+    // forgetting it: the page keeps asking for the list it booted with.
+    await clientModulesStub.bundleResource('GET', '/plugins/??dsh-panel-control/client.js&rev=rev-now');
+    clientModulesStub.dropRev = true;
+    const remembered = await clientModulesStub.bundleResource(
+      'GET',
+      '/plugins/??dsh-panel-control/client.js&rev=rev-now',
+    );
+    check('a remembered revision is served after the registry drops it', remembered.status === 200, `status ${remembered.status}`);
+    clientModulesStub.dropRev = false;
+    const fresh = await clientModulesStub.bundleResource(
+      'GET',
+      '/plugins/??dsh-panel-control/client.js&rev=rev-now',
+    );
+    check('current revision passes straight through', fresh.status === 200, `status ${fresh.status}`);
+    const other = await clientModulesStub.bundleResource('GET', '/plugins/??someone-else/client.js&rev=old');
+    check('other packages keep their 404', other.status === 404, `status ${other.status}`);
+    check(
+      'inventory ids',
+      Array.isArray(body.result.value.ids) &&
+        body.result.value.ids.join() === 'a,b,dsh-panel-control',
+      body.result.value && body.result.value.ids.join(),
+    );
   } catch (error) {
     check('inventory answers', false, error.message);
   }