dsh-plugin-mobile-link 0.6.6 → 0.8.0

package/lib/files.js

@@ -26,6 +26,24 @@ export function isFileMethod(method) {
   return method === FILE_BEGIN || method === FILE_CHUNK || method === FILE_END
 }
 
+/**
+ * 多久没有新分片就认定这次上传已经没人要了。
+ *
+ * 这个时限不是"请求超时"：正在慢慢传的上传每来一片就重新计时。它要解决的是
+ * 一种**线上没有信号**的中断——relay 的 `PUT /files/up` 被手机掐掉之后，两个
+ * 中转（Python 与 Go）都只在本地摘掉桥接，**不会给连接器发任何取消帧**，也不会
+ * 断开 agent 的 WebSocket。连接器因此永远等不到下一次 `fsPutChunk`/`fsPutEnd`，
+ * `.part` 的 fd 就一直开着（M8 文件联调实测）。
+ *
+ * 取值要能容下慢速链路：1 MiB 一片，即便链路慢到 100 KB/s 也约 10 秒一片；
+ * 10 分钟的空档只可能是手机侧被系统挂起或请求早已死掉。真被清扫时，这次上传
+ * 会以 `fsErr`/HTTP 错误明确失败，用户重传即可，不会静默写出半截文件。
+ */
+export const DEFAULT_TRANSFER_IDLE_MS = 10 * 60 * 1000
+
+/** 空闲清扫的周期：只决定"最晚多久之后"释放，不决定"多久算空闲"。 */
+export const DEFAULT_SWEEP_MS = 30 * 1000
+
 /**
  * One in-flight transfer.
  *
@@ -40,7 +58,10 @@ export function isFileMethod(method) {
  * checks out, so a half-sent file is never mistaken for a complete one.
  */
 class Transfer {
-  constructor({ sessionId, name, bytes }) {
+  /** 注入的时钟；FileInbox 把它传给每次 Transfer，保证"空闲多久"只有一份口径。 */
+  #now
+
+  constructor({ sessionId, name, bytes, now = Date.now }) {
     this.sessionId = sessionId
     this.name = basename(name || 'file')
     this.bytes = Number.isFinite(bytes) ? bytes : undefined
@@ -51,6 +72,12 @@ class Transfer {
     this.directory = join(dshHome(), 'inbox', sessionId)
     mkdirSync(this.directory, { recursive: true, mode: 0o700 })
     this.staging = join(this.directory, `.${this.name}.part`)
+    // 最后一次收到分片的时刻（空闲清扫用）。时钟由 FileInbox 注入，测试里可精确推进。
+    this.#now = now
+    this.lastActivityAt = now()
+    // 释放只能发生一次：fd 与 `.part` 是同一份资源的两个面，重复释放要么是空操作、
+    // 要么会删到别人刚建好的同路径文件（重传接管时正好是这种情况）。
+    this.released = false
     // Opened once and kept: reopening per chunk would be a syscall per chunk for
     // no benefit. `w` truncates, which is what a retried transfer wants.
     this.fd = undefined
@@ -72,6 +99,7 @@ class Transfer {
     writeSync(this.#handle(), buffer)
     this.received += buffer.length
     this.expectedSeq += 1
+    this.lastActivityAt = this.#now()
   }
 
   finish() {
@@ -95,7 +123,15 @@ class Transfer {
     }
   }
 
+  /**
+   * 放弃这次上传：关句柄、删暂存文件，幂等。
+   *
+   * **只碰 `.part`**：`finish()` 已把暂存改名成成品，这里再调一次也只是对一个
+   * 不存在的暂存路径做 no-op，成品不会被误删（`已完成的文件不会被清理路径误删` 用例守着）。
+   */
   dispose() {
+    if (this.released) return
+    this.released = true
     this.#close()
     rmSync(this.staging, { force: true })
   }
@@ -105,9 +141,56 @@ class Transfer {
 export class FileInbox {
   #transfers = new Map()
   #logger
+  #idleMs
+  #now
+  #sweeper
 
-  constructor(logger) {
+  /**
+   * @param {object} [logger]
+   * @param {object} [options]
+   * @param {number} [options.idleMs] 多久没有新分片算"没人要了"
+   * @param {number} [options.sweepMs] 空闲清扫周期
+   * @param {() => number} [options.now] 注入时钟（测试用；生产就是 `Date.now`）
+   */
+  constructor(logger, {
+    idleMs = DEFAULT_TRANSFER_IDLE_MS,
+    sweepMs = DEFAULT_SWEEP_MS,
+    now = Date.now,
+  } = {}) {
     this.#logger = logger
+    this.#idleMs = idleMs
+    this.#now = now
+    // 定时器是**兜底信号**：relay 从不为上传发取消帧，也不在上传中断时断开
+    // agent 的 WebSocket，所以"再也不会来分片"只能由时间发现。`unref` 掉，
+    // 别让一个空的收件箱按住进程退出（与 link.js / jobs-roster.js 同一口径）。
+    this.#sweeper = setInterval(() => this.sweep(), Math.max(1, sweepMs))
+    this.#sweeper.unref?.()
+  }
+
+  /**
+   * 释放空闲超过 `idleMs` 的上传；返回本次释放的个数。
+   *
+   * 单独暴露是为了让测试给出确定时刻，而不是 sleep 等定时器；生产里由构造时
+   * 安好的 interval 调用。
+   */
+  sweep(now = this.#now()) {
+    let released = 0
+    for (const [transferId, transfer] of this.#transfers) {
+      const idle = now - transfer.lastActivityAt
+      if (idle < this.#idleMs) continue
+      this.#release(transferId, transfer)
+      this.#logger.warn?.(
+        `mobile-link: file transfer ${transferId} released after ${Math.round(idle / 1000)}s idle`,
+      )
+      released += 1
+    }
+    return released
+  }
+
+  /** 收掉一次在传上传；释放本身幂等，重复到达的取消/清扫都是空操作。 */
+  #release(transferId, transfer) {
+    transfer.dispose()
+    this.#transfers.delete(transferId)
   }
 
   /** Answers one reserved call. Throws `Error` for the router to report. */
@@ -118,12 +201,21 @@ export class FileInbox {
     if (method === FILE_BEGIN) {
       const sessionId = String(args.sessionId ?? '')
       if (!sessionId) throw new Error('sessionId is required')
-      this.#transfers.get(transferId)?.dispose()
-      this.#transfers.set(
-        transferId,
-        new Transfer({ sessionId, name: args.name, bytes: Number(args.bytes) })
+      const transfer = new Transfer({
+        sessionId, name: args.name, bytes: Number(args.bytes), now: this.#now,
+      })
+      // 一条 `.part` 同时只能有一个写者。两种"重来"都要在这里把旧的收掉：
+      // 同一个 bid 重来，以及手机换了新 bid 但落盘路径相同（中断后重传）。
+      // 不收的话旧 fd 会一直握着一个已被 unlink 的 inode——M8 联调实测的泄漏。
+      for (const [id, existing] of this.#transfers) {
+        if (id === transferId || existing.staging === transfer.staging) {
+          this.#release(id, existing)
+        }
+      }
+      this.#transfers.set(transferId, transfer)
+      this.#logger.debug?.(
+        `mobile-link: file transfer ${transferId} started for ${sessionId}`,
       )
-      this.#logger.debug?.(`mobile-link: file transfer ${transferId} started for ${sessionId}`)
       return { accepted: true }
     }
 
@@ -131,7 +223,14 @@ export class FileInbox {
     if (!transfer) throw new Error(`unknown transfer ${transferId}`)
 
     if (method === FILE_CHUNK) {
-      transfer.append(Number(args.seq ?? 0), String(args.data ?? ''))
+      try {
+        transfer.append(Number(args.seq ?? 0), String(args.data ?? ''))
+      } catch (error) {
+        // 这一片已经给这次上传判了死（调用方随后回 `fsErr`）：句柄与 `.part`
+        // 一起收掉，别等空闲清扫——它可能永远等不到下一次触发。
+        this.#release(transferId, transfer)
+        throw error
+      }
       return { received: transfer.received }
     }
 
@@ -143,14 +242,21 @@ export class FileInbox {
       )
       return done
     } finally {
-      transfer.dispose()
-      this.#transfers.delete(transferId)
+      this.#release(transferId, transfer)
     }
   }
 
+  /** 放弃一次上传（relay 的 `fsPutCancel`）。未知 id 是空操作，与 `fsGetCancel` 同口径。 */
+  cancel(transferId) {
+    const id = String(transferId ?? '')
+    const transfer = this.#transfers.get(id)
+    if (transfer) this.#release(id, transfer)
+  }
+
   /** Drops every in-flight transfer, e.g. when the link goes down. */
   clear() {
-    for (const transfer of this.#transfers.values()) transfer.dispose()
-    this.#transfers.clear()
+    for (const [transferId, transfer] of this.#transfers) {
+      this.#release(transferId, transfer)
+    }
   }
 }

package/lib/git.js

@@ -19,6 +19,7 @@
 import { execFile } from 'node:child_process'
 import { statSync } from 'node:fs'
 import { isAbsolute, resolve } from 'node:path'
+import { truncateSafe } from './unicode.js'
 
 /** Reserved method names this module answers; never forwarded to the Host. */
 export const GIT_STATUS = '_link/gitStatus'
@@ -44,10 +45,24 @@ export const LIMITS = {
   readTimeoutMs: 15_000,
 }
 
-/** The environment every git call runs in. */
-function gitEnv() {
+/** The environment every git call runs in.
+ *
+ * 导出给单测的 fixture 使用：测试自己也要起 git，两边必须是同一份环境口径，
+ * 否则 hook 里跑测试时 fixture 会写进外层仓库。
+ */
+export function gitEnv() {
+  const env = { ...process.env }
+  // "看哪个仓库"只由 `-C <dir>` 决定。调用方环境里可能带着仓库定位变量（从
+  // .githooks 里启动 DSH、或在 git rebase 里启动时都会这样），它们会盖掉 `-C`，
+  // 让手机看到另一个仓库、甚至报 "nothing to commit"。这里清掉，归属唯一。
+  for (const key of [
+    'GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_PREFIX', 'GIT_NAMESPACE',
+    'GIT_COMMON_DIR', 'GIT_OBJECT_DIRECTORY', 'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  ]) {
+    delete env[key]
+  }
   return {
-    ...process.env,
+    ...env,
     // Never wait for a credential prompt or open an editor: a phone review
     // must not be able to wedge a process on the computer.
     GIT_TERMINAL_PROMPT: '0',
@@ -400,7 +415,7 @@ export class GitBridge {
       staged,
       untracked,
       binary,
-      text: binary ? '' : text.slice(0, LIMITS.diffBytes),
+      text: binary ? '' : truncateSafe(text, LIMITS.diffBytes),
       truncated: !binary && buffer.length > LIMITS.diffBytes,
     }
   }
@@ -450,7 +465,7 @@ export class GitBridge {
         sha,
         path,
         binary,
-        text: binary ? '' : text.slice(0, LIMITS.diffBytes),
+        text: binary ? '' : truncateSafe(text, LIMITS.diffBytes),
         truncated: !binary && buffer.length > LIMITS.diffBytes,
       }
     }

package/lib/hello.js

@@ -65,7 +65,7 @@ export function hostVersion() {
  * - `qr-pairing`     this connector renders the pairing QR itself (the `svg`
  *                    field of `POST /mobile-link/pair-code`), so the DSH client
  *                    needs no QR library of its own
- * - `self-enroll`    this connector can register itself with an invite code
+ * - `self-enroll`    this connector can register itself without an invite code
  * - `git`            git status / diff / log / show can be read from the work
  *                    tree on this computer (see git.js)
  * - `background-transfer`
@@ -98,6 +98,28 @@ export const SERVER_CAPABILITIES = [
   // search-progress: 扫描式搜索的每一页都带 `totalChunks` / `remainingChunks`，
   // 界面据此从第一页起就能显示「已扫 k/N 片」（026 之后的 App 才读）。
   'search-progress',
+  // history-compression: `_link/sessionWindow` 可按要求把回包压成
+  // `deflate-raw` 的 base64 信封（见 history/compress.js）。手机只在看到这条
+  // 能力时请求；旧客户端不传 encoding，回包与改动前逐字一致。
+  'history-compression',
+  // history-fold-summary: `_link/sessionWindow` 接受 `fold: true`，把已完成轮次的
+  // 过程事件折成一条 `+link/fold` 摘要（见 history/fold.js）；手机展开时用普通请求取回。
+  'history-fold-summary',
+  // history-fold-summary-v2: `_link/sessionWindow` 另接受 `fold: "summary"`——概要先行
+  // 取数（只回讲话 + `+link/fold` v2 概要 + 正式回答，按整轮切页，见
+  // history/fold-summary.js 与 history/summary-window.js）。**独立能力位**：
+  // 不声明 `"summary"` 的老客户端拿到的回包与改动前逐字节相同。
+  'history-fold-summary-v2',
+  'history-coverage',
+  // jobs-roster: 连接器答 `_link/jobRoster`（逐活会话聚合宿主任务），并推
+  // `link/jobs` 帧（spec 018）。手机**只按这条能力**决定是否渲染任务面板、列表行
+  // 右侧计数与卡片新行：无此能力的旧连接器，手机整块不出现（界面与升级前逐屏一致）。
+  'jobs-roster',
+  // dir-mtimes: 连接器答 `_link/dirListing`——宿主 `workspaceFiles/list` 的同形副本，
+  // 在电脑本机对每个条目补一个 `mtimeMs`（宿主类型里没有时间字段，`stat` 的 version
+  // 是 opaque token，推不出时间）。手机**只按这条能力**决定要不要走新方法：没有它的
+  // 旧连接器仍走 `workspaceFiles/list`，文件页与升级前逐屏一致（只是没有时间），不报错。
+  'dir-mtimes',
   'device-subprotocol-auth', 'persistent-pair-code', 'account-state', 'account-state-push',
 ]
 

package/lib/history/compress.js

@@ -0,0 +1,40 @@
+/**
+ * `_link/sessionWindow` 的可选压缩（能力 `history-compression`）。
+ *
+ * 为什么在应用层压：中转的 WebSocket 关闭了 permessage-deflate（`compress=False`），
+ * iOS 的 `URLSessionWebSocketTask` 也不支持协商压缩。要在不动中转的前提下减少
+ * 公网字节，只能在连接器把 value 压成 DEFLATE、手机侧自己解（与 spec 021 的
+ * `_link/sessionDigest` 同一套信封与同一种编码）。
+ *
+ * 编码选 `deflate-raw`（RFC1951）而不是 gzip：Apple `Compression` 框架的
+ * `COMPRESSION_ZLIB` 直接解原始 DEFLATE，gzip 包装还得引 libz。
+ *
+ * 兼容：不传 `encoding` 或传了不认识的值时原样返回 JSON，老 App 行为不变；
+ * 新 App 只在 `_link/hello` 声明了 `history-compression` 时才请求压缩。
+ */
+
+import { deflateRawSync } from 'node:zlib'
+
+/// 与 `session-digest.js` 的 `DEFLATE_ENCODING` 同一词表（协议里只能有一个名字）。
+export const HISTORY_COMPRESSION_ENCODING = 'deflate-raw'
+
+/// 能力名：连接器在 `_link/hello` 里声明，手机据此决定要不要请求压缩。
+export const HISTORY_COMPRESSION_CAPABILITY = 'history-compression'
+
+/// 把一页的值包成 `{encoding, value(base64), rawBytes}` 信封。
+///
+/// `rawBytes` 是解压后的字节数：`compression_decode_buffer` 必须先知道输出多大，
+/// 让连接器一次给足，手机就不用"猜容量、失败再翻倍"。
+export function compressHistoryValue(value) {
+  const raw = Buffer.from(JSON.stringify(value ?? null), 'utf8')
+  return {
+    encoding: HISTORY_COMPRESSION_ENCODING,
+    value: deflateRawSync(raw).toString('base64'),
+    rawBytes: raw.length,
+  }
+}
+
+/// 按调用方要求决定压不压。只有明确要 `deflate-raw` 才压。
+export function maybeCompressHistoryValue(value, encoding) {
+  return encoding === HISTORY_COMPRESSION_ENCODING ? compressHistoryValue(value) : value
+}

package/lib/history/coverage.js

@@ -0,0 +1,21 @@
+/**
+ * 已知为空的推导：一次窗口回包里，哪些号确认没有内容。
+ *
+ * 只在"从最老一条返回到窗口上界"之间下结论：窗口下界到最老返回之间可能被
+ * 字节/条数截断，那一段没有被完整扫描，不能判空。上界取 `before - 1`。
+ */
+export function emptySpans(records, lower, upper) {
+  const seqs = (records ?? [])
+    .map((record) => record?.event?.seq)
+    .filter((seq) => Number.isInteger(seq) && seq >= lower && seq <= upper)
+    .sort((a, b) => a - b)
+  if (seqs.length === 0) return []
+  const spans = []
+  let cursor = seqs[0]
+  for (const seq of seqs) {
+    if (seq > cursor) spans.push([cursor, seq - 1])
+    cursor = seq + 1
+  }
+  if (upper >= cursor) spans.push([cursor, upper])
+  return spans
+}