dsh-mobile-plugin 0.1.57 → 0.1.59

package/lib/shell/runtime.js

@@ -0,0 +1,249 @@
+/**
+ * 代际运行时：把「外壳」和「某一代实现」缝在一起，并负责换代那一刻的秩序。
+ *
+ * 外壳（`lib/index.js`）只做两件事：启动时激活版本最高的一代，以及把换代请求转给这里。
+ * 实现侧完全不知道自己是被外壳装进来的 —— 它拿到的是一个普通的 cordis `Context`，
+ * 照常 `ctx.effect(...)` / `ctx.webServer.register(...)` / `ctx.reflect.provide(...)`。
+ *
+ * ## 换代为什么必须串行、而且先停后起
+ *
+ * 一个代在 `apply` 里会往宿主注册**同一条路径**的路由（`ctx.webServer.register` 撞路径会抛
+ * `webserver: duplicate exact route`），还会绑 sidecar、起镜像推送。所以不能「先装新的再
+ * 卸旧的」——只能先把旧代的 fiber dispose 掉（它的每个 `ctx.effect` 会反向执行清理：路由
+ * 摘掉、子进程收掉），再装新的。这个文件里的 `swapping` 锁就是保证同一时刻只有一次换代。
+ *
+ * ## 让路
+ *
+ * 手机那边随时可能有一个请求在读事件流。直接 dispose 会把 `ctx.effect` 的清理跑在别人的
+ * 请求中间。所以换代前先等 `inFlight` 归零，最多等 `DRAIN_TIMEOUT_MS`（等不到也照换——
+ * 卡住的请求不该拖住一次修复性更新）。
+ */
+
+import { importGeneration, resolveGeneration } from './manager.js'
+
+/** 换代前等在飞请求归零的上限。 */
+const DRAIN_TIMEOUT_MS = 2000
+/** 等一代装载完成的上限。装载卡住（依赖永远不来）时不能把整个外壳拖死。 */
+const ACTIVATE_TIMEOUT_MS = 20000
+
+/**
+ * 代没有声明 `inject` 时的兜底（只有测试里的假代会走这里）。
+ *
+ * 真实实现 `lib/impl.js` 一定声明 inject，而且是按运行时二选一的，所以这里**不能**
+ * 拿它去覆盖代自己的声明 —— 那会把旧运行时要用的 `apiProxy` 抹掉。
+ */
+const DEFAULT_INJECT = ['webServer', 'sessions']
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+
+export function createRuntime() {
+  /** 外壳那份 `apply` 拿到的 context。装载完成前是 null。 */
+  let ctx = null
+  /** 当前活跃的 fiber（旧代）。 */
+  let fiber = null
+  /**
+   * 当前这一代**已经 import 进来的模块本体**。
+   *
+   * 回滚必须用它，不能靠「按版本号再挑一次」：市场装新版会把旧的 store 目录整个带走，
+   * 那一刻盘上已经找不到旧代了 —— 照版本号找会拿到 null，于是回滚失败、插件彻底没有
+   * 活跃实现（手机连不上，日志里只剩一行 pending）。模块本体在内存里，重新 `apply`
+   * 一次就是完整的旧代。
+   */
+  let loadedCurrent = null
+  /** 当前代的描述（`{version, source, dir, hostPath}` 的子集）。 */
+  let current = null
+  /** 上一次成功激活过的代，供回滚。 */
+  let previous = null
+  /** 串行化所有换代动作。 */
+  let swapping = null
+  /** 在飞请求计数（`beginRequest` / `endRequest` 维护）。 */
+  let inFlight = 0
+  let lastError = null
+  let activatedAt = null
+  let detached = false
+
+  /** 对外状态快照。控制面接口直接把它交给客户端。 */
+  function status() {
+    return {
+      version: current?.version ?? null,
+      source: current?.source ?? null,
+      previousVersion: previous?.version ?? null,
+      activatedAt,
+      lastError,
+      inFlight,
+      swapping: swapping !== null,
+    }
+  }
+
+  /** 装载一代并等它真正 ACTIVE。失败抛错，由调用方决定是否回滚。 */
+  async function activate(generation) {
+    return activateLoaded(await importGeneration(generation))
+  }
+
+  /**
+   * 把已经 import 进来的那代装上去（回滚走这条）。
+   *
+   * 回滚**不重新 import**：新代装失败时旧代的目录可能已经被市场删掉了，重新读盘会
+   * MODULE_NOT_FOUND；而旧代的模块本体一直在内存里，重新 apply 一次就够了。
+   */
+  async function activateLoaded(loaded) {
+    let timer = null
+    // 用 `{ inject, apply }` 而不是裸函数：cordis 只有在**声明过** inject 的 fiber 上
+    // 才允许 `ctx.webServer` 这种取值（裸函数会以 "cannot get property without inject"
+    // 失败）。代里的实现自己声明了 `inject`，但它作为插件对象被装进来时那份声明不会
+    // 自动生效，所以外壳在这里转交给 cordis。
+    //
+    // 用代自己声明的 inject，不写死：`lib/impl.js` 的 inject 是**按运行时二选一**的
+    // （旧运行时多一个 `apiProxy`，0.2.0 没有）。写死成 `['webServer','sessions']` 会让
+    // 旧运行时上读 `ctx.apiProxy` 抛 "cannot get property apiProxy without inject"。
+    // 测试里的假代没声明 inject 时退回外壳默认值。
+    const inject = Array.isArray(loaded.inject) && loaded.inject.length > 0 ? loaded.inject : DEFAULT_INJECT
+    const result = await Promise.race([
+      Promise.resolve().then(() => ctx.plugin({ inject, apply: loaded.apply })),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`装载 ${loaded.version} 超时（${ACTIVATE_TIMEOUT_MS}ms）：它可能卡在等一个永远不来的依赖服务上`)), ACTIVATE_TIMEOUT_MS)
+      }),
+    ]).finally(() => {
+      if (timer) clearTimeout(timer)
+    })
+    return { loaded, fiber: result }
+  }
+
+  function describe(loaded, dir) {
+    return { version: loaded.version, source: loaded.source, hostPath: loaded.hostPath ?? dir ?? null }
+  }
+
+  /**
+   * 换到指定版本（默认版本最高的那一代）。
+   *
+   * 旧代先停、新代后起；新代起不来就回滚把旧代装回去，并把错误留在 `lastError` 里——
+   * 「更新把自己弄挂了」必须能被看见，而不是静默少个插件。
+   */
+  async function reload(preferVersion) {
+    if (detached) throw new Error('插件已经卸载，不能再换代')
+    if (swapping) return swapping
+    swapping = (async () => {
+      const target = resolveGeneration(preferVersion)
+      if (!target) throw new Error('找不到任何一代实现：包内的 lib/impl.js 缺失')
+      if (current && target.version === current.version) return status()
+
+      await drain()
+      const oldFiber = fiber
+      const oldCurrent = current
+      fiber = null
+      current = null
+      if (oldFiber) {
+        try {
+          await oldFiber.dispose()
+        } catch (error) {
+          // dispose 里的清理动作自己炸了：记下来，但不能因此不装新代。
+          lastError = `卸载 ${oldCurrent?.version ?? '旧代'} 时出错：${error?.message || error}`
+        }
+      }
+      try {
+        const { loaded, fiber: nextFiber } = await activate(target)
+        fiber = nextFiber
+        loadedCurrent = loaded
+        current = describe(loaded, target.dir)
+        if (oldCurrent) previous = oldCurrent
+        activatedAt = new Date().toISOString()
+        lastError = null
+        return status()
+      } catch (error) {
+        lastError = `装载 ${target.version} 失败：${error?.message || error}`
+        if (oldCurrent) {
+          // 回滚：把上一代装回去，尽量让插件保持可用。
+          //
+          // 顺序是刻意的：**先用内存里那份**（`loadedCurrent`），因为它一定还在；盘上那份
+          // 可能已经被市场这次安装带走了（pnpm 换 store 目录），照版本号找会找空。
+          try {
+            if (loadedCurrent) {
+              const { fiber: nextFiber } = await activateLoaded(loadedCurrent)
+              fiber = nextFiber
+              current = describe(loadedCurrent, oldCurrent.dir ?? null)
+              activatedAt = new Date().toISOString()
+            } else {
+              const fallback = resolveGeneration(oldCurrent.version)
+              if (fallback) {
+                const { loaded, fiber: nextFiber } = await activate(fallback)
+                fiber = nextFiber
+                loadedCurrent = loaded
+                current = describe(loaded, fallback.dir)
+                activatedAt = new Date().toISOString()
+              }
+            }
+          } catch (rollbackError) {
+            lastError = `${lastError}；回滚到 ${oldCurrent.version} 也失败：${rollbackError?.message || rollbackError}`
+          }
+        }
+        throw error
+      }
+    })().finally(() => {
+      swapping = null
+    })
+    return swapping
+  }
+
+  /** 第一次激活。 */
+  async function start(context) {
+    ctx = context
+    const target = resolveGeneration()
+    if (!target) throw new Error('找不到任何一代实现：包内的 lib/impl.js 缺失')
+    const { loaded, fiber: startedFiber } = await activate(target)
+    fiber = startedFiber
+    loadedCurrent = loaded
+    current = describe(loaded, target.dir)
+    activatedAt = new Date().toISOString()
+    return status()
+  }
+
+  /** 等在飞请求结束（最多 `DRAIN_TIMEOUT_MS`）。 */
+  async function drain() {
+    const deadline = Date.now() + DRAIN_TIMEOUT_MS
+    while (inFlight > 0 && Date.now() < deadline) {
+      await sleep(25)
+    }
+  }
+
+  /** 外壳被卸载时调用：停当前代，之后不再接受换代。 */
+  async function detach() {
+    detached = true
+    const oldFiber = fiber
+    fiber = null
+    current = null
+    if (oldFiber) await oldFiber.dispose()
+  }
+
+  return {
+    start,
+    reload,
+    detach,
+    status,
+    beginRequest: () => {
+      inFlight += 1
+    },
+    endRequest: () => {
+      inFlight = Math.max(0, inFlight - 1)
+    },
+    /**
+     * 把一个路由 handler 包成「进来 +1、出去 -1」。
+     *
+     * 宿主 webServer 没有 Koa 式中间件（只有 `register(route)` / `registerUpgrade` /
+     * `registerFallback` / `tapIndex`），所以「在飞请求」只能在 handler 外面数。包错
+     * 形状时原样返回，绝不因为统计把一条路由弄丢。
+     */
+    wrapHandler: (route) => {
+      if (!route || typeof route.handler !== 'function') return route
+      const handler = route.handler
+      route.handler = async (req, res) => {
+        inFlight += 1
+        try {
+          return await handler(req, res)
+        } finally {
+          inFlight = Math.max(0, inFlight - 1)
+        }
+      }
+      return route
+    },
+  }
+}

package/lib/shell/updater.js

@@ -0,0 +1,267 @@
+/**
+ * 更新编排：替用户去问 DSH 插件市场要新版，装完**就地换代**（不重启 DSH）。
+ *
+ * ## 为什么这件事归外壳做，而不是归面板（浏览器）
+ *
+ * 面板里那颗「更新」按钮只能覆盖「用户正开着页面点一下」这一种情形；自动更新的定义是
+ * **没人看着也要发生**。所以轮询和「装完切换」都必须在宿主进程里做，面板只是给它一个开关。
+ *
+ * ## 为什么下载交给市场、切换留给自己
+ *
+ * 市场在 profile 里跑 pnpm，还会做版本核验、release-age 策略、回滚点、重启守卫 —— 抄一遍
+ * 只会抄漏。它装完会报 `restartRequired: true`（因为绝大多数插件换版本确实得重启 DSH），
+ * 而本插件有外壳，可以自己把运行中的实现换掉，所以这里**故意不调它的重启**。
+ *
+ * 装完新一代是**新目录**（pnpm 换链接），外壳照着新 realpath 重新 import 一代即可，见
+ * `lib/shell/manager.js` 与 `lib/shell/runtime.js`。
+ *
+ * ## 这个模块不做的事
+ *
+ * 不下载、不解包、不校验、不写 profile —— 全是市场的职责。它只回答四个问题：有没有新版、
+ * 请它装、装完了没、盘上现在是什么版本。
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { createHash } from 'node:crypto'
+import { createRequire } from 'node:module'
+import { installedVersion } from './manager.js'
+
+const require_ = createRequire(import.meta.url)
+const { dshHome } = require_('../shared/paths.js')
+
+
+/**
+ * 外壳自己的指纹（`lib/index.js` + `lib/shell/*.js` 的内容哈希）。
+ *
+ * **外壳换不掉**：它在进程启动时被 Node 缓存，改它必须重启 DSH —— 而重启是被明令禁止的。
+ * 所以「新版本连外壳一起改了」这件事**不会**在这次更新里生效：实现换成新的了，装载它的
+ * 那层还是旧的。这本身通常无害（外壳的接口是加法式的），但用户有权知道，所以这里算一个
+ * 指纹，把「盘上的外壳和跑着的外壳不一样」如实报给面板。
+ *
+ * 缺文件按空串算：拿不到指纹时报「没变」，免得每次开面板都喊一句要重启。
+ */
+export function shellFingerprint(pkgDir) {
+  if (!pkgDir) return null
+  const files = ['lib/index.js', 'lib/shell/runtime.js', 'lib/shell/manager.js', 'lib/shell/updater.js']
+  const hash = createHash('sha256')
+  let seen = 0
+  for (const rel of files) {
+    try {
+      hash.update(rel).update(fs.readFileSync(path.join(pkgDir, rel)))
+      seen += 1
+    } catch {
+      // 缺一个文件就少算一个：宁愿指纹弱一点，也不要在这里抛。
+    }
+  }
+  return seen === 0 ? null : hash.digest('hex').slice(0, 16)
+}
+
+/** 本插件的 npm 包名（市场按它找依赖）。 */
+export const PACKAGE_NAME = 'dsh-mobile-plugin'
+
+/** 自动检查的间隔与「检查一次」的超时。 */
+export const AUTO_INTERVAL_MS = 10 * 60 * 1000
+const REQUEST_TIMEOUT_MS = 15000
+/** 等一次安装走完的上限：pnpm 装一个包 + 校验，给足但别无限等。 */
+const INSTALL_TIMEOUT_MS = 10 * 60 * 1000
+const POLL_INTERVAL_MS = 1000
+
+/** 宿主自己的 web 端口 → 市场的本机地址。端口拿不到就别问（自动更新如实报不可用）。 */
+export function marketBase(port) {
+  const value = Number(port)
+  if (!Number.isFinite(value) || value <= 0) return null
+  return `http://127.0.0.1:${value}`
+}
+
+/** 市场接口的错误：把状态码、它给的稳定 code 与给人看的话一起带出来。 */
+export class MarketError extends Error {
+  constructor(status, code, message) {
+    super(message)
+    this.name = 'MarketError'
+    this.status = status
+    this.code = code
+  }
+}
+
+/**
+ * 调一次市场接口。
+ *
+ * 形状是**外部契约**，一律防御式读：拿不到就当「没这个能力」，绝不让外壳因此崩掉
+ * （外壳崩掉等于插件从宿主里消失、手机连不上，是最贵的失败）。
+ *
+ * 不带 `Origin` 头：请求来自宿主进程而不是浏览器，本机来源由对端按 socket 判定。
+ */
+async function marketJson(base, route, init) {
+  if (!base) throw new MarketError(0, 'market-unavailable', '拿不到本机 web 端口，问不了市场')
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS)
+  let response
+  try {
+    response = await fetch(`${base}/dsh-market/api/v1${route}`, {
+      ...init,
+      signal: controller.signal,
+      headers: { 'content-type': 'application/json', ...(init?.headers || {}) },
+    })
+  } catch (error) {
+    throw new MarketError(0, 'market-unreachable', `插件市场不可达：${error?.message || error}`)
+  } finally {
+    clearTimeout(timer)
+  }
+  let body = null
+  try {
+    body = await response.json()
+  } catch {
+    body = null
+  }
+  if (!response.ok) {
+    const code = body?.error?.code || body?.code || `http-${response.status}`
+    const message = body?.error?.message || body?.message || `市场返回 ${response.status}`
+    throw new MarketError(response.status, code, message)
+  }
+  return body
+}
+
+/** 市场在不在、能不能代劳重启（我们不用后者，只为与面板口径一致）。 */
+export async function capabilities(base) {
+  const body = await marketJson(base, '/capabilities', { method: 'GET' })
+  return {
+    available: true,
+    restartSupported: body?.restart?.supported === true,
+  }
+}
+
+/**
+ * 问有没有新版。`installedVersion` 为 null = 市场看不见这个包（多半不是 npm 装的）。
+ *
+ * 路径与字段与面板那份客户端（`React/src/lib/market.ts`）逐字对齐：同一个市场接口，
+ * 两处写法不一致时踩的是「宿主能装、面板说看不见」这类最难查的偏差。
+ */
+export async function checkUpdate(base, name = PACKAGE_NAME, { force = false } = {}) {
+  const body = await marketJson(base, `/updates?name=${encodeURIComponent(name)}${force ? '&force=1' : ''}`, { method: 'GET' })
+  const update = body?.package || body || {}
+  return {
+    installedVersion: typeof update.installedVersion === 'string' ? update.installedVersion : null,
+    latestVersion: typeof update.latestVersion === 'string' ? update.latestVersion : null,
+    updateAvailable: update.updateAvailable === true,
+    source: typeof update.source === 'string' ? update.source : null,
+    channelSwitch: update.channelSwitch === true,
+  }
+}
+
+/**
+ * 这条链能不能自动更新。
+ *
+ * 市场只从注册表装包：本地 link / `file:` 装的那些（`source: 'linked'`）它一概拒绝
+ * （`locally linked plugins update from their checkout`）。所以「自动更新」在那种机器上
+ * **做不到**，而且必须**说出来** —— 否则用户开着开关等一晚上，什么都不会发生。
+ */
+export function updatableSource(source) {
+  return source === 'npm'
+}
+
+/** 请市场去装。返回它的 operationId，供轮询。 */
+export async function startUpdate(base, name = PACKAGE_NAME, { force = false } = {}) {
+  const body = await marketJson(base, '/updates', {
+    method: 'POST',
+    body: JSON.stringify({ packageName: name, ...(force ? { force: true } : {}) }),
+  })
+  const operation = body?.operation || body || {}
+  if (typeof operation.operationId !== 'string') {
+    throw new MarketError(200, 'market-bad-response', '市场没有给出 operationId，无法跟踪这次更新')
+  }
+  return operation
+}
+
+/** 查一次操作结果。 */
+export async function operation(base, operationId) {
+  const body = await marketJson(base, `/operations?operationId=${encodeURIComponent(operationId)}`, { method: 'GET' })
+  return body?.operation || body || {}
+}
+
+const TERMINAL = new Set(['succeeded', 'failed', 'cancelled', 'rolled-back'])
+
+/**
+ * 一套完整的「装新版」：问市场、请它装、盯到终态。
+ *
+ * **不重启 DSH**：市场报的 `restartRequired` 只往上传，装完由外壳换代解决（见 index.js）。
+ * 装完了但盘上版本没变（市场报成功、文件没落），这里如实返回 `installed: false`，不让调用方
+ * 以为换过代码 —— 「状态说成功、代码没换」是这个仓库吃过最贵的一次亏。
+ */
+export async function installIfNeeded(base, { name = PACKAGE_NAME, force = false, onEvent = () => {}, now = Date.now } = {}) {
+  const before = installedVersion()
+  const check = await checkUpdate(base, name, { force })
+  if (check.source !== null && !updatableSource(check.source)) {
+    // 本地 link / file: 装的：市场不会碰它（见 updatableSource）。如实返回，别去试。
+    return {
+      installed: false,
+      skipped: true,
+      reason: 'linked-source',
+      detail: `这台机器上的插件是 ${check.source} 来源装的（本地目录 / tgz），市场只从注册表更新；要自动更新得先在插件市场里按包名重装一次切到 npm 来源`,
+      beforeVersion: before,
+      installedVersion: before,
+      check,
+    }
+  }
+  if (!check.updateAvailable && !force) {
+    return { installed: false, skipped: true, beforeVersion: before, installedVersion: before, check }
+  }
+  const started = await startUpdate(base, name, { force })
+  onEvent({ phase: 'started', operationId: started.operationId })
+  const deadline = now() + INSTALL_TIMEOUT_MS
+  let last = started
+  while (!TERMINAL.has(last.state) && now() < deadline) {
+    await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS))
+    last = await operation(base, started.operationId)
+    onEvent({ phase: 'progress', state: last.state, operationId: started.operationId })
+  }
+  if (!TERMINAL.has(last.state)) {
+    throw new MarketError(0, 'market-operation-timeout', `更新操作 ${started.operationId} 在 ${Math.round(INSTALL_TIMEOUT_MS / 1000)}s 内没有结束`)
+  }
+  // 市场同一时刻只允许一个操作，有 agent 在跑时也会直接拒（`AGENTS_RUNNING`）—— 这类
+  // 失败是「现在不行」，不是「坏了」：自动更新下个 tick 再试就好，别当成故障喊。
+  const RETRYABLE_CODES = new Set(['OPERATION_BUSY', 'AGENTS_RUNNING', 'UPDATE_TIMEOUT', 'RELEASE_TOO_FRESH'])
+  const retryable = typeof last.failure?.code === 'string' ? RETRYABLE_CODES.has(last.failure.code) : false
+  const after = installedVersion()
+  return {
+    installed: last.state === 'succeeded' && after !== before && after !== null,
+    state: last.state,
+    operationId: started.operationId,
+    beforeVersion: last.beforeVersion ?? before,
+    installedVersion: after,
+    // 市场认为要重启：本插件自己换代，**故意不照做**。留着上报给面板做说明。
+    restartRequired: last.restartRequired === true,
+    refreshRequired: last.refreshRequired === true,
+    failure: last.failure || null,
+    retryable,
+    check,
+  }
+}
+
+/** 自动更新开关的落盘文件：`<DSH_HOME>/storages/mobile-plugin/auto-update.json`。 */
+function autoUpdateFile() {
+  return path.join(dshHome(), 'storages', 'mobile-plugin', 'auto-update.json')
+}
+
+/** 读开关。读不到 / 读坏了都当「关」——自动装东西这种事，缺省必须在用户这一侧。 */
+export function autoUpdateEnabled() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(autoUpdateFile(), 'utf8'))
+    return raw?.enabled === true
+  } catch {
+    return false
+  }
+}
+
+/** 写开关。 */
+export function setAutoUpdate(enabled) {
+  const file = autoUpdateFile()
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, `${JSON.stringify({ enabled: enabled === true }, null, 2)}\n`)
+  return autoUpdateEnabled()
+}
+
+/** 开关文件的路径（诊断用）。 */
+export function autoUpdateFilePath() {
+  return autoUpdateFile()
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "dsh-mobile-plugin",
-  "version": "0.1.57",
+  "version": "0.1.59",
   "description": "Mobile API (/api/mobile/v1) and relay client for the DSH mobile app — desktop profile build (0.2.0-rc.2 compatible, peers resolved by the host)",
   "license": "MIT",
   "type": "module",
-  "main": "lib/impl.js",
+  "main": "lib/index.js",
   "bin": "host.js",
   "exports": {
-    ".": "./lib/impl.js",
+    ".": "./lib/index.js",
     "./client": "./lib/client.js",
     "./package.json": "./package.json"
   },