@yunzai-ng/core 0.1.0

package/src/plugin/services.test.ts

@@ -0,0 +1,135 @@
+/**
+ * 模块职责：`ServiceRegistry` 行为测试
+ * 依赖方向：测试文件
+ * 生命周期：每个用例一个注册表
+ * 注意事项：重点覆盖"取代 runtime.js 硬编码 getter"这项设计的边界：重复注册须抛错、
+ *          缺失须给出可操作的错误、卸载后不得残留失效引用、等待者不得阻止进程退出。
+ */
+import { describe, expect, it } from "vitest"
+import { createServiceRegistry } from "./services.js"
+
+describe("ServiceRegistry", () => {
+  it("provide 后可被 get / has / require 取到", () => {
+    const reg = createServiceRegistry()
+    const api = { hello: () => "hi" }
+    reg.provide("mihoyo.api", api, "mhy-game")
+
+    expect(reg.has("mihoyo.api")).toBe(true)
+    expect(reg.get<typeof api>("mihoyo.api")).toBe(api)
+    expect(reg.require<typeof api>("mihoyo.api", "other")).toBe(api)
+    expect(reg.size).toBe(1)
+  })
+
+  it("键名非法时立即抛错", () => {
+    const reg = createServiceRegistry()
+    expect(() => reg.provide("2bad", 1, "p")).toThrow(/不合法/)
+    expect(() => reg.provide("has space", 1, "p")).toThrow(/不合法/)
+    expect(() => reg.provide("ok.key-1:sub", 1, "p")).not.toThrow()
+  })
+
+  it("同键重复注册抛错，且错误里点明是谁先占的", () => {
+    const reg = createServiceRegistry()
+    reg.provide("x.y", 1, "first")
+    expect(() => reg.provide("x.y", 2, "second")).toThrow(/first/)
+    // 冲突不该破坏已有记录
+    expect(reg.get("x.y")).toBe(1)
+  })
+
+  it("require 缺失时的错误同时说明谁要用、要什么、现在有什么", () => {
+    const reg = createServiceRegistry()
+    reg.provide("a.b", 1, "p1")
+    try {
+      reg.require("missing.key", "mhy-game")
+      expect.unreachable("require 应当抛错")
+    } catch (err) {
+      const msg = (err as Error).message
+      expect(msg).toContain("mhy-game")
+      expect(msg).toContain("missing.key")
+      expect(msg).toContain("a.b")
+    }
+  })
+
+  it("没有任何服务时 require 的错误也说得清楚", () => {
+    const reg = createServiceRegistry()
+    expect(() => reg.require("k", "p")).toThrow(/没有任何插件提供服务/)
+  })
+
+  it("disposer 摘除服务；重复调用无副作用", () => {
+    const reg = createServiceRegistry()
+    const undo = reg.provide("k", 1, "p")
+    undo()
+    undo()
+    expect(reg.has("k")).toBe(false)
+    expect(reg.size).toBe(0)
+  })
+
+  it("延迟到达的卸载 disposer 不会摘除后注册者的同名服务", () => {
+    const reg = createServiceRegistry()
+    const stale = reg.provide("k", "old", "old-plugin")
+    // 模拟：旧插件的服务先由 removeByOwner 摘除，新插件随后注册，旧 disposer 最后到达
+    reg.removeByOwner("old-plugin")
+    reg.provide("k", "new", "new-plugin")
+    stale()
+    expect(reg.get("k")).toBe("new")
+  })
+
+  it("waitFor 在服务已就绪时立即返回", async () => {
+    const reg = createServiceRegistry()
+    reg.provide("k", 42, "p")
+    await expect(reg.waitFor<number>("k")).resolves.toBe(42)
+  })
+
+  it("waitFor 等到后来的 provide", async () => {
+    const reg = createServiceRegistry()
+    const pending = reg.waitFor<string>("late.key")
+    expect(reg.pending()).toEqual(["late.key"])
+    reg.provide("late.key", "arrived", "p")
+    await expect(pending).resolves.toBe("arrived")
+    // 兑现后等待队列要清空，否则 list() 里的 waiting 永远挂着
+    expect(reg.pending()).toEqual([])
+  })
+
+  it("waitFor 超时返回 undefined 而不是抛错", async () => {
+    const reg = createServiceRegistry()
+    await expect(reg.waitFor("never", 10)).resolves.toBeUndefined()
+  })
+
+  it("多个等待者会被同一次 provide 一起唤醒", async () => {
+    const reg = createServiceRegistry()
+    const all = Promise.all([reg.waitFor<number>("k"), reg.waitFor<number>("k"), reg.waitFor<number>("k")])
+    reg.provide("k", 7, "p")
+    await expect(all).resolves.toEqual([7, 7, 7])
+  })
+
+  it("removeByOwner 摘除该插件的全部服务并返回键名", () => {
+    const reg = createServiceRegistry()
+    reg.provide("a", 1, "p1")
+    reg.provide("b", 2, "p1")
+    reg.provide("c", 3, "p2")
+
+    expect(reg.removeByOwner("p1").sort()).toEqual(["a", "b"])
+    expect(reg.size).toBe(1)
+    expect(reg.get("c")).toBe(3)
+  })
+
+  it("list 按键排序并带上等待者数量", async () => {
+    const reg = createServiceRegistry()
+    reg.provide("z.svc", 1, "p2")
+    reg.provide("a.svc", 2, "p1")
+    void reg.waitFor("a.svc")
+
+    const list = reg.list()
+    expect(list.map(i => i.key)).toEqual(["a.svc", "z.svc"])
+    expect(list[0]?.owner).toBe("p1")
+    // a.svc 已就绪，waitFor 会立即返回、不进等待队列
+    expect(list[0]?.waiting).toBe(0)
+  })
+
+  it("clear 唤醒全部等待者，避免停机时被阻塞", async () => {
+    const reg = createServiceRegistry()
+    const waiting = reg.waitFor("never.coming", 0)
+    reg.clear()
+    await expect(waiting).resolves.toBeUndefined()
+    expect(reg.size).toBe(0)
+  })
+})

package/src/plugin/services.ts

@@ -0,0 +1,261 @@
+/**
+ * 模块职责：插件间服务注册表（provide / inject / require / waitFor）
+ * 依赖方向：依赖 util/defer、util/duration、类型包
+ * 生命周期：应用级单例；每个插件卸载时其提供的服务被自动摘除
+ * 注意事项：这是本框架对「插件间协作」的唯一答案。提供方 `ctx.provide("mihoyo.api", impl)`，
+ *          使用方 `ctx.inject("mihoyo.api")`；内核只维护一张 `key → 值` 的表，对表里装的是什么
+ *          毫无认知，故内核到任何插件都是零依赖。
+ *
+ *          它取代两种坏做法：把业务对象硬写成内核的 getter（那会让内核反向依赖插件，删掉一个插件
+ *          内核就起不来），以及插件之间靠 `global.xxx` 或跨插件相对路径互相摸（路径一改全体崩，
+ *          且无从知道谁在用谁）。
+ *
+ *          键的所有者被记录下来，插件卸载时它提供的服务一起消失 —— 使用方拿到的是 undefined，
+ *          而不是一个指向已卸载模块的失效引用。
+ */
+import type { Disposer, DurationLike } from "@yunzai-ng/types"
+import { defer, type Deferred } from "../util/defer.js"
+import { parseDuration } from "../util/duration.js"
+
+/** `waitFor` 的默认等待上限 */
+const DEFAULT_WAIT = 30_000
+
+/** 服务键的合法形式：字母开头，允许点号分域 */
+const KEY_RE = /^[a-z][a-z0-9]*(?:[.:-][a-z0-9]+)*$/i
+
+/** 一条服务记录 */
+interface ServiceEntry {
+  /** 服务实例 */
+  value: unknown
+  /** 提供方插件名 */
+  owner: string
+  /** 注册时间（毫秒） */
+  since: number
+}
+
+/** 服务的对外描述（WebUI / `yzng doctor` 用） */
+export interface ServiceInfo {
+  /** 服务键 */
+  key: string
+  /** 提供方插件名 */
+  owner: string
+  /** 注册时间（毫秒） */
+  since: number
+  /** 当前有多少个等待者（诊断"谁在等一个没人提供的服务"） */
+  waiting: number
+}
+
+/**
+ * 服务注册表
+ *
+ * 线程模型：同进程单线程，无锁。
+ */
+export class ServiceRegistry {
+  /** 已注册的服务 */
+  readonly #entries = new Map<string, ServiceEntry>()
+  /** 等待中的 `waitFor` 调用，按键分组 */
+  readonly #waiters = new Map<string, Set<Deferred<unknown>>>()
+
+  /** 已注册的服务数 */
+  get size(): number {
+    return this.#entries.size
+  }
+
+  /**
+   * 注册服务
+   *
+   * 同一键被两个插件同时提供时**抛出异常**，而非由后者覆盖前者：此类冲突
+   * 多数源于插件作者复制代码后未修改键名，静默覆盖只会使排障难以进行。
+   * @param key 服务键，建议 `"<插件域>.<能力>"`
+   * @param value 服务实例
+   * @param owner 提供方插件名
+   * @returns 注销句柄；注销后等待者重新回到"等待"状态
+   * @throws 键名非法或已被他人占用时
+   */
+  provide<T>(key: string, value: T, owner: string): Disposer {
+    if (!KEY_RE.test(key)) {
+      throw new Error(`服务键 ${key} 不合法：需以字母开头，只含字母数字与 . : -`)
+    }
+    const exists = this.#entries.get(key)
+    if (exists) {
+      throw new Error(`服务 ${key} 已由插件 ${exists.owner} 提供，${owner} 不能重复注册`)
+    }
+
+    const entry: ServiceEntry = { value, owner, since: Date.now() }
+    this.#entries.set(key, entry)
+    this.#flushWaiters(key, value)
+
+    let disposed = false
+    return () => {
+      if (disposed) return
+      disposed = true
+      // 仅当仍为自身那份记录时才删除：避免延迟到达的卸载摘除他方刚注册的服务
+      if (this.#entries.get(key) === entry) this.#entries.delete(key)
+    }
+  }
+
+  /**
+   * 取服务
+   * @param key 服务键
+   * @returns 服务实例；未注册时 undefined
+   */
+  get<T>(key: string): T | undefined {
+    return this.#entries.get(key)?.value as T | undefined
+  }
+
+  /**
+   * 是否已注册
+   * @param key 服务键
+   * @returns 是否存在
+   */
+  has(key: string): boolean {
+    return this.#entries.has(key)
+  }
+
+  /**
+   * 取服务，缺失即抛错
+   *
+   * 错误信息中必须同时出现"由谁使用"与"需要什么"，否则使用者仅看到
+   * "服务不存在"，无从判断应当安装哪一个插件。
+   * @param key 服务键
+   * @param requester 使用方插件名，用于错误信息
+   * @returns 服务实例
+   * @throws 服务未注册时
+   */
+  require<T>(key: string, requester = "未知插件"): T {
+    const entry = this.#entries.get(key)
+    if (!entry) {
+      const available = [...this.#entries.keys()].sort()
+      const hint = available.length > 0 ? `当前可用：${available.join("、")}` : "当前没有任何插件提供服务"
+      throw new Error(`插件 ${requester} 需要服务 ${key}，但没有插件提供它。${hint}`)
+    }
+    return entry.value as T
+  }
+
+  /**
+   * 等待服务就绪
+   *
+   * 用于弱依赖：A 需要使用 B 的能力，但 B 可能晚于 A 加载，亦可能并未安装。
+   * 超时返回 undefined 而非抛错 —— 弱依赖的语义即"不存在时亦可继续运行"。
+   * @param key 服务键
+   * @param timeout 等待上限，缺省 30s；传 0 表示不限时
+   * @returns 服务实例；超时返回 undefined
+   */
+  async waitFor<T>(key: string, timeout?: DurationLike): Promise<T | undefined> {
+    const ready = this.#entries.get(key)
+    if (ready) return ready.value as T
+
+    const ms = parseDuration(timeout, DEFAULT_WAIT)
+    const waiter = defer<unknown>()
+    let bucket = this.#waiters.get(key)
+    if (!bucket) {
+      bucket = new Set()
+      this.#waiters.set(key, bucket)
+    }
+    bucket.add(waiter)
+
+    /** 从等待队列中摘除自身，并一并清除空桶 */
+    const cleanup = (): void => {
+      bucket!.delete(waiter)
+      if (bucket!.size === 0) this.#waiters.delete(key)
+    }
+
+    if (ms <= 0) {
+      try {
+        return (await waiter.promise) as T
+      } finally {
+        cleanup()
+      }
+    }
+
+    // 超时按"没等到"处理：resolve(undefined) 而非 reject，
+    // 调用方就不必为一个正常结局写 try/catch
+    const timer = setTimeout(() => waiter.resolve(undefined), ms)
+    // unref：只剩这个等待时进程仍应能退出，否则插件写错一个 key 就永远关不掉
+    if (typeof timer.unref === "function") timer.unref()
+
+    try {
+      return (await waiter.promise) as T | undefined
+    } finally {
+      clearTimeout(timer)
+      cleanup()
+    }
+  }
+
+  /**
+   * 摘除某插件提供的全部服务
+   *
+   * 插件卸载时由宿主调用。尽管每个 `provide` 均返回 disposer 且已登记进
+   * DisposalRegistry，此处仍作为兜底：插件若在 setup 之外的异步回调中 provide，
+   * 有可能绕过登记。
+   * @param owner 插件名
+   * @returns 被摘除的服务键
+   */
+  removeByOwner(owner: string): string[] {
+    const removed: string[] = []
+    for (const [key, entry] of this.#entries) {
+      if (entry.owner !== owner) continue
+      this.#entries.delete(key)
+      removed.push(key)
+    }
+    return removed
+  }
+
+  /**
+   * 列出全部服务
+   * @returns 服务描述，按键名排序
+   */
+  list(): ServiceInfo[] {
+    return [...this.#entries.entries()]
+      .map(([key, entry]) => ({
+        key,
+        owner: entry.owner,
+        since: entry.since,
+        waiting: this.#waiters.get(key)?.size ?? 0
+      }))
+      .sort((a, b) => a.key.localeCompare(b.key))
+  }
+
+  /**
+   * 列出"存在等待者但无提供方"的服务键
+   *
+   * `yzng doctor` 以其给出"可能缺少某个插件"的提示。
+   * @returns 键名数组
+   */
+  pending(): string[] {
+    return [...this.#waiters.keys()].filter(key => !this.#entries.has(key)).sort()
+  }
+
+  /**
+   * 清空注册表并唤醒所有等待者
+   *
+   * 停机时调用，避免等待者阻止进程退出。
+   */
+  clear(): void {
+    this.#entries.clear()
+    for (const bucket of this.#waiters.values()) {
+      for (const waiter of bucket) waiter.resolve(undefined)
+    }
+    this.#waiters.clear()
+  }
+
+  /**
+   * 唤醒某个键上的全部等待者
+   * @param key 服务键
+   * @param value 服务实例
+   */
+  #flushWaiters(key: string, value: unknown): void {
+    const bucket = this.#waiters.get(key)
+    if (!bucket) return
+    // 先取快照再唤醒：resolve 的 finally 会改动这个 Set
+    for (const waiter of [...bucket]) waiter.resolve(value)
+  }
+}
+
+/**
+ * 创建服务注册表
+ * @returns 注册表实例
+ */
+export function createServiceRegistry(): ServiceRegistry {
+  return new ServiceRegistry()
+}

package/src/plugin/tar.test.ts

@@ -0,0 +1,158 @@
+/**
+ * 模块职责：tar.gz 解包器的行为测试
+ * 依赖方向：测试文件，依赖 plugin/tar
+ * 生命周期：每个用例一套临时目录，afterEach 全部删除
+ * 注意事项：归档由 `buildTarGz` 现场构造，不使用预置的二进制夹具。解包器的校验对象是
+ *          归档头部的字节内容，而预置夹具无法表达"路径写成 `../`"这类恶意结构 ——
+ *          需要断言的正是这些结构被拒绝。
+ */
+import { readFile, mkdtemp, rm } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { afterEach, describe, expect, it } from "vitest"
+import { isFile } from "../util/fs.js"
+import { buildTarGz, extractTarGz, joinWithin, singleRoot } from "./tar.js"
+
+let root: string | undefined
+
+/**
+ * 建一个临时目录，并返回其中的解包目标目录
+ *
+ * 目标目录嵌在临时根目录之内，因此"越界写入"若真的发生，落点也在本用例的清理范围内，
+ * 不会残留到系统临时目录并影响后续用例。
+ * @returns 解包目标目录绝对路径
+ */
+async function temp(): Promise<string> {
+  root = await mkdtemp(join(tmpdir(), "yzng-tar-"))
+  return join(root, "dest")
+}
+
+afterEach(async () => {
+  if (root !== undefined) await rm(root, { recursive: true, force: true })
+  root = undefined
+})
+
+describe("extractTarGz", () => {
+  it("解出文件与目录，返回写入的相对路径", async () => {
+    const dir = await temp()
+    const archive = buildTarGz([
+      { path: "pkg/", content: "", type: "5" },
+      { path: "pkg/index.js", content: "export default 1\n" },
+      { path: "pkg/lib/util.js", content: "export const a = 1\n" }
+    ])
+
+    const written = await extractTarGz(archive, dir)
+
+    expect(written).toEqual(["pkg/index.js", "pkg/lib/util.js"])
+    expect(await readFile(join(dir, "pkg", "index.js"), "utf8")).toBe("export default 1\n")
+    expect(await readFile(join(dir, "pkg", "lib", "util.js"), "utf8")).toBe("export const a = 1\n")
+  })
+
+  it("strip 剥掉 GitHub 归档外层的仓库名目录", async () => {
+    const dir = await temp()
+    const archive = buildTarGz([{ path: "repo-abc123/index.js", content: "1" }])
+
+    const written = await extractTarGz(archive, dir, { strip: 1 })
+
+    expect(written).toEqual(["index.js"])
+    expect(await isFile(join(dir, "index.js"))).toBe(true)
+  })
+
+  it("剥空的条目被跳过，而不是写到目标目录本身", async () => {
+    const dir = await temp()
+    const archive = buildTarGz([{ path: "repo/", content: "", type: "5" }, { path: "repo/a.js", content: "1" }])
+
+    const written = await extractTarGz(archive, dir, { strip: 1 })
+    expect(written).toEqual(["a.js"])
+  })
+
+  it("越出目标目录的条目被丢弃，其余条目照常解出", async () => {
+    const dir = await temp()
+    const archive = buildTarGz([
+      { path: "../escaped.js", content: "恶意内容" },
+      { path: "a/../../escaped2.js", content: "恶意内容" },
+      { path: "ok.js", content: "正常内容" }
+    ])
+
+    const written = await extractTarGz(archive, dir)
+
+    expect(written).toEqual(["ok.js"])
+    expect(await isFile(join(dir, "..", "escaped.js"))).toBe(false)
+    expect(await isFile(join(dir, "..", "escaped2.js"))).toBe(false)
+  })
+
+  it("绝对路径条目被丢弃", async () => {
+    const dir = await temp()
+    const archive = buildTarGz([{ path: "/tmp/yzng-absolute.js", content: "恶意内容" }, { path: "ok.js", content: "1" }])
+
+    const written = await extractTarGz(archive, dir)
+    expect(written).toEqual(["ok.js"])
+  })
+
+  it("软链接与硬链接条目被丢弃", async () => {
+    const dir = await temp()
+    const archive = buildTarGz([
+      { path: "link.js", content: "", type: "2" },
+      { path: "hard.js", content: "", type: "1" },
+      { path: "real.js", content: "1" }
+    ])
+
+    const written = await extractTarGz(archive, dir)
+
+    expect(written).toEqual(["real.js"])
+    expect(await isFile(join(dir, "link.js"))).toBe(false)
+  })
+
+  it("pax 扩展头部声明的长路径生效", async () => {
+    const dir = await temp()
+    const long = `deep/${"seg/".repeat(30)}index.js`
+    const record = `path=${long}\n`
+    const archive = buildTarGz([
+      { path: "PaxHeader", content: `${record.length + 4} ${record}`, type: "x" },
+      { path: "short.js", content: "1" }
+    ])
+
+    const written = await extractTarGz(archive, dir)
+    expect(written).toEqual([long])
+  })
+
+  it("条目数超过上限时抛错", async () => {
+    const dir = await temp()
+    const archive = buildTarGz([
+      { path: "a.js", content: "1" },
+      { path: "b.js", content: "1" },
+      { path: "c.js", content: "1" }
+    ])
+
+    await expect(extractTarGz(archive, dir, { maxEntries: 2 })).rejects.toThrow("条目数超过上限")
+  })
+
+  it("解包后体积超过上限时抛错", async () => {
+    const dir = await temp()
+    const archive = buildTarGz([{ path: "big.js", content: "x".repeat(4096) }])
+
+    await expect(extractTarGz(archive, dir, { maxBytes: 1024 })).rejects.toThrow("体积超过上限")
+  })
+})
+
+describe("singleRoot", () => {
+  it("唯一顶层目录时返回该目录名", () => {
+    expect(singleRoot(["repo-1/index.js", "repo-1/lib/a.js"])).toBe("repo-1")
+  })
+
+  it("存在顶层文件或多个顶层目录时返回 undefined", () => {
+    expect(singleRoot(["index.js", "lib/a.js"])).toBeUndefined()
+    expect(singleRoot(["a/x.js", "b/y.js"])).toBeUndefined()
+  })
+})
+
+describe("joinWithin", () => {
+  it("越界名称一律抛错", () => {
+    expect(() => joinWithin("/plugins", "../etc/passwd")).toThrow("路径越界")
+    expect(() => joinWithin("/plugins", "/etc/passwd")).toThrow("路径越界")
+  })
+
+  it("正常名称拼出目标路径", () => {
+    expect(joinWithin("/plugins", "demo")).toContain("demo")
+  })
+})