@yunzai-ng/core 0.1.0

package/src/store/sql.ts

@@ -0,0 +1,324 @@
+/**
+ * 模块职责：SQLite 关系存储（语句缓存、异步事务、迁移）
+ * 依赖方向：动态依赖可选原生模块 better-sqlite3；依赖 util/{lru,queue}、类型包
+ * 生命周期：`openSql()` 打开，`close()` 关闭
+ * 注意事项：**不引 ORM**，只暴露 run/all/get/transaction/migrate。
+ *
+ *          **事务手写 BEGIN/COMMIT 并用互斥锁串行化**：better-sqlite3 的 `db.transaction()`
+ *          只收同步函数，而本框架的接口是异步的（要容得下别的驱动）。一条连接上开不了两个
+ *          事务，故事务之间必须排队；嵌套事务改用 SAVEPOINT，不重复抢锁。
+ *
+ *          **语句缓存有界。** `prepare()` 有真实开销，但无上限的缓存在动态拼 SQL 的插件手里
+ *          就是内存泄漏。
+ */
+import type { SqlHandle, SqlMigration, SqlParam } from "@yunzai-ng/types"
+import { dirname } from "node:path"
+import { LruCache } from "../util/lru.js"
+import { Semaphore } from "../util/queue.js"
+import { ensureDir } from "../util/fs.js"
+
+/** 语句缓存条目上限 */
+const STMT_CACHE_MAX = 200
+
+/** 迁移记录表名 */
+const MIGRATION_TABLE = "_yzng_migrations"
+
+/** better-sqlite3 的语句最小面 */
+interface SqliteStatement {
+  /** 执行不取行 */
+  run(...params: SqlParam[]): { changes: number; lastInsertRowid: number | bigint }
+  /** 取全部行 */
+  all(...params: SqlParam[]): unknown[]
+  /** 取首行 */
+  get(...params: SqlParam[]): unknown
+}
+
+/** better-sqlite3 的连接最小面 */
+interface SqliteDb {
+  /** 预编译语句 */
+  prepare(sql: string): SqliteStatement
+  /** 直接执行脚本（可含多条语句，不支持绑定参数） */
+  exec(sql: string): void
+  /** 读写 pragma */
+  pragma(source: string): unknown
+  /** 关闭连接 */
+  close(): void
+}
+
+/** better-sqlite3 的构造签名 */
+type SqliteCtor = new (file: string, opts?: { readonly?: boolean }) => SqliteDb
+
+/** 一条连接上的共享状态 */
+interface SqlState {
+  /** 连接 */
+  db: SqliteDb
+  /** 语句缓存 */
+  stmts: LruCache<SqliteStatement>
+  /** 事务互斥锁 */
+  mutex: Semaphore
+  /** SAVEPOINT 命名计数器 */
+  savepoint: number
+}
+
+/**
+ * 尝试加载 better-sqlite3
+ * @returns 构造函数；模块不可用时 undefined
+ */
+export async function loadSqlite(): Promise<SqliteCtor | undefined> {
+  try {
+    const mod = (await import("better-sqlite3")) as unknown as { default?: SqliteCtor }
+    return mod.default
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * SQLite 句柄
+ *
+ * 根句柄由 `openSql()` 创建；事务内传给回调的是 `depth > 0` 的子句柄，
+ * 它们共享同一条连接，因此**不能**在事务回调里持有子句柄留到事务外使用。
+ */
+export class SqliteHandle implements SqlHandle {
+  /** 共享状态 */
+  readonly #state: SqlState
+  /** 事务嵌套深度，0 表示不在事务中 */
+  readonly #depth: number
+
+  /**
+   * @param state 共享状态
+   * @param depth 事务嵌套深度
+   */
+  constructor(state: SqlState, depth = 0) {
+    this.#state = state
+    this.#depth = depth
+  }
+
+  /**
+   * 执行不返回行的语句
+   *
+   * 不带参数且含多条语句时走 `exec()`，方便迁移里一次建表 + 建索引；
+   * 这种情况下无法报告受影响行数，返回 0。
+   * @param sql SQL 文本
+   * @param params 绑定参数
+   * @returns 受影响行数与最后插入 id
+   */
+  async run(sql: string, params: SqlParam[] = []): Promise<{ changes: number; lastInsertRowid: number | bigint }> {
+    if (params.length === 0 && isMultiStatement(sql)) {
+      this.#state.db.exec(sql)
+      return { changes: 0, lastInsertRowid: 0 }
+    }
+    return this.#prepare(sql).run(...params)
+  }
+
+  /**
+   * 查询多行
+   * @param sql SQL 文本
+   * @param params 绑定参数
+   * @returns 结果行数组
+   */
+  async all<T = Record<string, unknown>>(sql: string, params: SqlParam[] = []): Promise<T[]> {
+    return this.#prepare(sql).all(...params) as T[]
+  }
+
+  /**
+   * 查询首行
+   * @param sql SQL 文本
+   * @param params 绑定参数
+   * @returns 首行；无结果时 undefined
+   */
+  async get<T = Record<string, unknown>>(sql: string, params: SqlParam[] = []): Promise<T | undefined> {
+    return (this.#prepare(sql).get(...params) as T | undefined) ?? undefined
+  }
+
+  /**
+   * 在事务中执行
+   *
+   * 最外层用 `BEGIN IMMEDIATE`（立刻拿写锁，避免升级锁时才发现冲突而整段重来）；
+   * 嵌套层用 SAVEPOINT，实现"内层回滚不牵连外层"。
+   * @param fn 事务体，抛错即回滚
+   * @returns 事务体的返回值
+   */
+  async transaction<T>(fn: (tx: SqlHandle) => Promise<T>): Promise<T> {
+    if (this.#depth > 0) return this.#savepoint(fn)
+    // 同一条连接上不能并发开事务，排队等前一个事务结束
+    return this.#state.mutex.use(async () => {
+      const tx = new SqliteHandle(this.#state, 1)
+      this.#state.db.exec("BEGIN IMMEDIATE")
+      try {
+        const result = await fn(tx)
+        this.#state.db.exec("COMMIT")
+        return result
+      } catch (err) {
+        // 回滚本身也可能失败（连接已断），此时保留原始错误更有诊断价值
+        try {
+          this.#state.db.exec("ROLLBACK")
+        } catch {
+          /* 忽略 */
+        }
+        throw err
+      }
+    })
+  }
+
+  /**
+   * 应用迁移
+   *
+   * 每条迁移单独一个事务：失败只回滚这一条，已成功的保持生效，修好后重跑从断点继续。
+   * 版本号落在迁移表里，故"这个库到哪一版了"有确定答案，不必靠"存在则忽略"的 try/catch。
+   * @param migrations 迁移列表
+   * @throws 版本号未严格递增，或某条迁移执行失败
+   */
+  async migrate(migrations: SqlMigration[]): Promise<void> {
+    await this.run(
+      `CREATE TABLE IF NOT EXISTS ${MIGRATION_TABLE} (
+         version INTEGER PRIMARY KEY,
+         name TEXT NOT NULL,
+         applied_at INTEGER NOT NULL
+       )`
+    )
+
+    const sorted = [...migrations].sort((a, b) => a.version - b.version)
+    for (let i = 1; i < sorted.length; i++) {
+      if (sorted[i]!.version === sorted[i - 1]!.version) {
+        throw new Error(`迁移版本号重复：${sorted[i]!.version}`)
+      }
+    }
+
+    const rows = await this.all<{ version: number }>(`SELECT version FROM ${MIGRATION_TABLE}`)
+    const applied = new Set(rows.map(r => r.version))
+
+    for (const migration of sorted) {
+      if (applied.has(migration.version)) continue
+      await this.transaction(async tx => {
+        await migration.up(tx)
+        await tx.run(`INSERT INTO ${MIGRATION_TABLE} (version, name, applied_at) VALUES (?, ?, ?)`, [
+          migration.version,
+          migration.name,
+          Date.now()
+        ])
+      })
+    }
+  }
+
+  /**
+   * 嵌套事务：SAVEPOINT
+   * @param fn 事务体
+   * @returns 事务体的返回值
+   */
+  async #savepoint<T>(fn: (tx: SqlHandle) => Promise<T>): Promise<T> {
+    const name = `yzng_sp_${++this.#state.savepoint}`
+    const tx = new SqliteHandle(this.#state, this.#depth + 1)
+    this.#state.db.exec(`SAVEPOINT ${name}`)
+    try {
+      const result = await fn(tx)
+      this.#state.db.exec(`RELEASE ${name}`)
+      return result
+    } catch (err) {
+      try {
+        this.#state.db.exec(`ROLLBACK TO ${name}`)
+        this.#state.db.exec(`RELEASE ${name}`)
+      } catch {
+        /* 忽略 */
+      }
+      throw err
+    }
+  }
+
+  /**
+   * 取（并缓存）预编译语句
+   * @param sql SQL 文本
+   * @returns 预编译语句
+   */
+  #prepare(sql: string): SqliteStatement {
+    const cached = this.#state.stmts.get(sql)
+    if (cached) return cached
+    const stmt = this.#state.db.prepare(sql)
+    this.#state.stmts.set(sql, stmt)
+    return stmt
+  }
+}
+
+/** 打开 SQL 存储的参数 */
+export interface OpenSqlOptions {
+  /** 数据库文件绝对路径 */
+  file: string
+  /** 构造函数，缺省自动加载 */
+  ctor?: SqliteCtor
+}
+
+/** 已打开的 SQL 存储 */
+export interface SqlStore {
+  /** 句柄 */
+  readonly handle: SqlHandle
+  /** 数据库文件路径 */
+  readonly file: string
+  /** 关闭连接 */
+  close(): void
+}
+
+/**
+ * 打开 SQLite 数据库
+ * @param opts 参数
+ * @returns 已打开的 SQL 存储；原生模块不可用时 undefined（调用方应降级为纯 KV）
+ */
+export async function openSql(opts: OpenSqlOptions): Promise<SqlStore | undefined> {
+  const ctor = opts.ctor ?? (await loadSqlite())
+  if (!ctor) return undefined
+
+  await ensureDir(dirname(opts.file))
+  const db = new ctor(opts.file)
+
+  // WAL：读不阻塞写，且断电时不会像 rollback journal 那样留下半个事务
+  db.pragma("journal_mode = WAL")
+  // NORMAL 在 WAL 下依然崩溃安全（只可能丢最后一个未 checkpoint 的事务），
+  // 却比 FULL 快一个数量级；机器人数据不是账本，这个取舍是合适的
+  db.pragma("synchronous = NORMAL")
+  db.pragma("foreign_keys = ON")
+  // 被别的连接短暂锁住时等一会儿再报错，而不是立刻抛 SQLITE_BUSY
+  db.pragma("busy_timeout = 5000")
+
+  const state: SqlState = {
+    db,
+    stmts: new LruCache<SqliteStatement>({ max: STMT_CACHE_MAX }),
+    mutex: new Semaphore(1),
+    savepoint: 0
+  }
+
+  return {
+    handle: new SqliteHandle(state),
+    file: opts.file,
+    close: () => {
+      // 缓存里的语句必须先丢掉：连接关了之后再用它们会直接崩进程
+      state.stmts.clear()
+      db.close()
+    }
+  }
+}
+
+/**
+ * 判断 SQL 是否包含多条语句
+ *
+ * 只做粗判：跳过字符串字面量后看是否还有 `;` 跟着非空白内容。
+ * 粗判失败的后果仅仅是走 `prepare()` 然后由 SQLite 自己报错，可接受。
+ * @param sql SQL 文本
+ * @returns 是否多语句
+ */
+function isMultiStatement(sql: string): boolean {
+  let inString = false
+  let quote = ""
+  for (let i = 0; i < sql.length; i++) {
+    const ch = sql[i]!
+    if (inString) {
+      if (ch === quote) inString = false
+      continue
+    }
+    if (ch === "'" || ch === '"') {
+      inString = true
+      quote = ch
+      continue
+    }
+    if (ch === ";" && sql.slice(i + 1).trim() !== "") return true
+  }
+  return false
+}

package/src/testing/fake.ts

@@ -0,0 +1,297 @@
+/**
+ * 模块职责：测试替身（假日志器、录制型子系统接缝、最小应用视图）
+ * 依赖方向：依赖 plugin/hooks、类型包；只被 `*.test.ts` 使用
+ * 生命周期：每个用例新建一套
+ * 注意事项：这些替身**刻意采用真实实现而非 mock 框架的自动桩** —— 注册后必须可查得到、
+ *          注销后必须可查得已不存在，否则"卸载是否确实归还了资源"这类断言无从落地。
+ *
+ *          目前仅用于内核自身的测试。将来若需使插件作者亦可借其编写单元测试，
+ *          须同时放开分层门禁中 `@yunzai-ng/core/*` 的深引限制 ——
+ *          那是一次独立的、需要写入文档的决定，不在此处附带开放。
+ */
+import type {
+  AdapterProvider,
+  AppView,
+  HttpClient,
+  KvDriver,
+  LogLevel,
+  Logger,
+  RenderRequest,
+  RendererProvider,
+  SqlHandle
+} from "@yunzai-ng/types"
+import type {
+  CommandRegistration,
+  KernelHooks,
+  MiddlewareRegistration,
+  TaskRegistration
+} from "../plugin/hooks.js"
+
+/** 带行记录的假日志器 */
+export interface FakeLogger extends Logger {
+  /** 已记录的日志行，形如 `"warn 消息 附加参数"` */
+  readonly lines: string[]
+}
+
+/**
+ * 创建假日志器
+ *
+ * 断言"出错时给了提示"而不是"抛异常中断"时用它 —— 框架里大量路径的正确行为
+ * 就是"记一条能照着解决的 warn 然后继续跑"，没有日志断言就测不到。
+ * @returns 假日志器
+ */
+export function fakeLogger(): FakeLogger {
+  const lines: string[] = []
+  /** 生成某个级别的记录函数 */
+  const push =
+    (level: string) =>
+    (msg: unknown, ...args: unknown[]): void => {
+      const extra = args.map(a => (a instanceof Error ? a.message : String(a))).join(" ")
+      lines.push(`${level} ${String(msg)} ${extra}`.trim())
+    }
+
+  const logger: FakeLogger = {
+    lines,
+    level: "trace" as LogLevel,
+    trace: push("trace"),
+    debug: push("debug"),
+    info: push("info"),
+    warn: push("warn"),
+    error: push("error"),
+    fatal: push("fatal"),
+    mark: push("info"),
+    child: () => logger,
+    isLevelEnabled: () => true
+  }
+  return logger
+}
+
+/** 一条静态目录挂载记录 */
+export interface StaticMount {
+  /** URL 作用域；面板挂载记为归属标识（如 `plugin:webui-next`） */
+  scope: string
+  /** URL 前缀；面板挂载记为 `"/"` */
+  urlPath: string
+  /** 本地目录 */
+  dir: string
+  /** 是否为单页应用挂载（`ctx.panel()` 记为真） */
+  spa: boolean
+}
+
+/** 一条路由记录 */
+export interface RouteMount {
+  /** URL 作用域 */
+  scope: string
+  /** 方法，WebSocket 记为 `"WS"` */
+  method: string
+  /** 路径 */
+  path: string
+}
+
+/** 录制到的全部注册 */
+export interface Recorded {
+  /** 命令 */
+  commands: CommandRegistration[]
+  /** 重新索引的次数（按命令去重前的调用计数） */
+  reindexed: CommandRegistration[]
+  /** 中间件 */
+  middlewares: MiddlewareRegistration[]
+  /** 定时任务 */
+  tasks: TaskRegistration[]
+  /** 路由与 WebSocket */
+  routes: RouteMount[]
+  /** 静态目录 */
+  statics: StaticMount[]
+  /** 适配器 */
+  adapters: AdapterProvider[]
+  /** 渲染器 */
+  renderers: RendererProvider[]
+  /** 收到的渲染请求（断言 templateRoot/resourceRoot 是否算对） */
+  renders: RenderRequest[]
+  /** KV 驱动 */
+  kvDrivers: KvDriver[]
+  /** 已打开的 SQL 库，形如 `"插件名/库名"` */
+  sqlOpened: string[]
+  /** 被要求关闭全部库的插件名 */
+  sqlClosed: string[]
+}
+
+/** 录制型接缝与其录制结果 */
+export interface RecordingHooks {
+  /** 交给上下文的接缝 */
+  hooks: KernelHooks
+  /** 录制结果 */
+  recorded: Recorded
+}
+
+/**
+ * 从数组里移除某项的 disposer
+ * @param list 数组
+ * @param item 待移除项
+ * @returns 注销函数
+ */
+function remover<T>(list: T[], item: T): () => void {
+  return () => {
+    const index = list.indexOf(item)
+    if (index >= 0) list.splice(index, 1)
+  }
+}
+
+/**
+ * 创建录制型子系统接缝
+ *
+ * 每个 `register` 均确实将登记写入数组，返回的 disposer 亦确实将其摘除。
+ * 因此"插件卸载后残留多少条命令"可直接断言 `recorded.commands.length === 0`。
+ * @returns 接缝与录制结果
+ */
+export function recordingHooks(): RecordingHooks {
+  const recorded: Recorded = {
+    commands: [],
+    reindexed: [],
+    middlewares: [],
+    tasks: [],
+    routes: [],
+    statics: [],
+    adapters: [],
+    renderers: [],
+    renders: [],
+    kvDrivers: [],
+    sqlOpened: [],
+    sqlClosed: []
+  }
+
+  /** 假 SQL 句柄：只记录被调用过，不真的建库 */
+  const sqlHandle = {
+    file: ":fake:",
+    exec: () => undefined,
+    run: () => ({ changes: 0, lastInsertRowid: 0 }),
+    get: () => undefined,
+    all: () => [],
+    transaction: <T>(fn: () => T) => fn(),
+    pragma: () => undefined
+  } as unknown as SqlHandle
+
+  const hooks: KernelHooks = {
+    commands: {
+      register: reg => {
+        recorded.commands.push(reg)
+        return remover(recorded.commands, reg)
+      },
+      reindex: reg => void recorded.reindexed.push(reg)
+    },
+    middlewares: {
+      register: reg => {
+        recorded.middlewares.push(reg)
+        return remover(recorded.middlewares, reg)
+      }
+    },
+    tasks: {
+      register: reg => {
+        recorded.tasks.push(reg)
+        return remover(recorded.tasks, reg)
+      }
+    },
+    server: {
+      info: { enabled: true, host: "127.0.0.1", port: 2536, publicUrl: "http://127.0.0.1:2536" },
+      route: (scope, method, path) => {
+        const mount: RouteMount = { scope, method, path }
+        recorded.routes.push(mount)
+        return remover(recorded.routes, mount)
+      },
+      websocket: (scope, path) => {
+        const mount: RouteMount = { scope, method: "WS", path }
+        recorded.routes.push(mount)
+        return remover(recorded.routes, mount)
+      },
+      static: (scope, urlPath, dir) => {
+        const mount: StaticMount = { scope, urlPath, dir, spa: false }
+        recorded.statics.push(mount)
+        return remover(recorded.statics, mount)
+      },
+      panel: (owner, dir) => {
+        const mount: StaticMount = { scope: owner, urlPath: "/", dir, spa: true }
+        recorded.statics.push(mount)
+        return remover(recorded.statics, mount)
+      },
+      // 只按 urlPath 相等判断：录制型接缝不实现路径表，而调用方（内核挂载内置面板）
+      // 问的只是"根路径有没有人接管"这一种情况
+      claimant: path => recorded.statics.find(m => m.urlPath === path)?.scope
+    },
+    render: {
+      register: provider => {
+        recorded.renderers.push(provider)
+        return remover(recorded.renderers, provider)
+      },
+      // 一张 3 字节的假图：断言"渲染结果被包成 ImageSegment"用得到，
+      // 不需要真的产生 PNG
+      render: async req => {
+        recorded.renders.push(req)
+        return { images: [new Uint8Array([1, 2, 3])], cost: 1, renderer: "fake" }
+      }
+    },
+    adapters: {
+      register: provider => {
+        recorded.adapters.push(provider)
+        return remover(recorded.adapters, provider)
+      }
+    },
+    kvDrivers: {
+      register: driver => {
+        recorded.kvDrivers.push(driver)
+        return remover(recorded.kvDrivers, driver)
+      }
+    },
+    sql: {
+      open: async (plugin, name) => {
+        recorded.sqlOpened.push(`${plugin}/${name}`)
+        return sqlHandle
+      },
+      close: async plugin => void recorded.sqlClosed.push(plugin)
+    },
+    bots: { pick: () => undefined }
+  }
+
+  return { hooks, recorded }
+}
+
+/**
+ * 创建最小应用视图
+ *
+ * 只填测试真正会读的字段，其余用类型断言留空 —— `AppView` 聚合了适配器、
+ * 账号、策略等一大票子系统视图，为一个上下文测试把它们全造出来毫无收益。
+ * 一旦某个用例真的要读某字段，就在这里补上真的实现。
+ * @returns 应用视图
+ */
+export function fakeAppView(): AppView {
+  return {
+    version: "0.0.0-test",
+    startedAt: 0,
+    usage: () => ({ rss: 0, heapUsed: 0, heapTotal: 0, external: 0, uptime: 0, cpu: 0 })
+  } as unknown as AppView
+}
+
+/**
+ * 创建假 HTTP 客户端
+ *
+ * 任何调用均抛错：网络请求出现在单元测试中几乎总属设计问题，应使其显式失败。
+ *
+ * 方法列表与 `HttpClient` 逐一对齐，且**不使用 as unknown as 断言** ——
+ * 经断言的替身对象会掩盖"契约已变更"一事：真实客户端新增一个方法后，
+ * 只有被测代码调用它时才在运行时抛错，而编译期不会报告任何问题。
+ * @returns HTTP 客户端
+ */
+export function fakeHttp(): HttpClient {
+  /** 统一拒绝 */
+  const fail = (): never => {
+    throw new Error("测试中不应发起真实 HTTP 请求")
+  }
+  const client: HttpClient = {
+    request: fail,
+    get: fail,
+    post: fail,
+    buffer: fail,
+    download: fail,
+    extend: () => client
+  }
+  return client
+}

package/src/testing/index.ts

@@ -0,0 +1,15 @@
+/**
+ * 模块职责：`@yunzai-ng/core/testing` 的入口，汇总内核提供的测试替身
+ * 依赖方向：只做转发
+ * 生命周期：无
+ * 注意事项：这些替身刻意**不**从主入口 `@yunzai-ng/core` 导出 —— 一并导出会使测试替身
+ *          进入生产依赖图（见 src/index.ts 的说明）。适配器与插件作者编写测试时：
+ *          ```ts
+ *          import { createMockAdapter, fakeLogger } from "@yunzai-ng/core/testing"
+ *          ```
+ *
+ *          与内核自身那些 `*.test.ts` 的分工：后者是内部单元测试，直接以相对路径 import
+ *          内部模块；此处是**对外公开**的替身，因此每次改动均应视为 API 变更。
+ */
+export * from "./fake.js"
+export * from "./mock-adapter.js"