@koishi-ce/plugin-market 1.1.3 → 1.2.0

package/src/node/__tests__/retry.test.ts

@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2019-present Shigma and Koishijs contributors.
+// Copyright (c) 2026-present Koishi-CE contributors.
+
+import {
+	afterAll,
+	beforeAll,
+	describe,
+	expect,
+	it,
+} from "bun:test";
+import net from "node:net";
+import type { Plugin } from "@koishi-ce/koishi";
+import {
+	App,
+	FakeConsole,
+	FakeLoader,
+	flakyIndexHits,
+	http,
+	itQuiet,
+	market,
+	memory,
+	registryServer,
+	setFlakyIndexHits,
+	setFlakyIndexMisses,
+	setSlowIndexHits,
+	slowIndexHits,
+	startApp,
+	stopApp,
+	type TestApp,
+} from "./helpers.ts";
+
+beforeAll(startApp);
+afterAll(stopApp);
+
+describe("镜像索引瞬态重试", () => {
+	/** 搭建配了 search.endpoint 的独立宿主（镜像索引经本测试桩提供）。 */
+	async function createMirrorApp(search: {
+		endpoint: string;
+		timeout?: number;
+	}) {
+		const mirror = new App();
+		// 类型层转型缘由见 helpers 的 app.plugin(memory) 注释
+		mirror.plugin(
+			memory as unknown as Plugin.Object<TestApp>,
+		);
+		mirror.plugin(http);
+		mirror.plugin(
+			FakeConsole as unknown as Plugin.Constructor<TestApp>,
+		);
+		mirror.plugin(FakeLoader);
+		mirror.plugin(market, {
+			registry: {
+				endpoint: `http://127.0.0.1:${registryServer.port}/`,
+			},
+			search,
+		});
+		await mirror.start();
+		return mirror;
+	}
+
+	it("镜像索引部署窗口 404 经退避重试后恢复", async () => {
+		setFlakyIndexHits(0);
+		setFlakyIndexMisses(2);
+		const mirror = await createMirrorApp({
+			endpoint: `http://127.0.0.1:${registryServer.port}/flaky-index`,
+		});
+		const svc = mirror.get("console.services.market");
+		// start(true) 内部 await prepare：前两次 404，退避重试后第三次成功
+		await svc?.start(true);
+		expect(flakyIndexHits).toBeGreaterThanOrEqual(3);
+		const payload = await svc?.get();
+		expect(Object.keys(payload?.data ?? {})).toEqual([
+			"koishi-plugin-demo",
+		]);
+		expect(payload?.total).toBe(1);
+		await mirror.stop();
+	}, 10000);
+
+	itQuiet(
+		"镜像索引持续超时经重试后优雅失败",
+		async () => {
+			setSlowIndexHits(0);
+			const mirror = await createMirrorApp({
+				endpoint: `http://127.0.0.1:${registryServer.port}/slow-index`,
+				timeout: 50,
+			});
+			const svc = mirror.get("console.services.market");
+			// 每次尝试 50ms 即超时，退避 1s + 2s 后仍失败；重试确实发生
+			await svc?.start(true);
+			expect(slowIndexHits).toBeGreaterThanOrEqual(3);
+			// start 末尾的 refresh 会再触发一轮 collect，等待其失败落地
+			await new Promise((resolve) =>
+				setTimeout(resolve, 3600),
+			);
+			const error = svc?.["_error" as keyof typeof svc];
+			expect(error).toBeDefined();
+			await mirror.stop();
+		},
+		15000,
+	);
+
+	// 裸 TCP 桩：前 planned 次请求收到请求头后直接销毁连接（复现
+	// 证书验证失败 / 连接重置等 fetch 网络层瞬态错误），随后回正常索引
+	function startFlakyTcpServer(planned: number) {
+		let hits = 0;
+		const server = net.createServer((socket) => {
+			socket.on("data", () => {
+				hits++;
+				if (hits <= planned) {
+					socket.destroy();
+					return;
+				}
+				const body = JSON.stringify({
+					version: "4",
+					objects: [
+						{
+							package: {
+								name: "koishi-plugin-demo",
+								version: "2.0.0",
+								date: "2024-06-01T00:00:00Z",
+								keywords: ["koishi", "plugin"],
+							},
+						},
+					],
+				});
+				socket.end(
+					`HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: ${body.length}\r\nConnection: close\r\n\r\n${body}`,
+				);
+			});
+		});
+		return new Promise<{
+			port: number;
+			hits: () => number;
+			close: () => void;
+		}>((resolve) => {
+			server.listen(0, "127.0.0.1", () => {
+				const { port } =
+					server.address() as net.AddressInfo;
+				resolve({
+					port,
+					hits: () => hits,
+					close: () => {
+						server.close();
+					},
+				});
+			});
+		});
+	}
+
+	it("网络层瞬态错误（连接重置）经退避重试后恢复", async () => {
+		const stub = await startFlakyTcpServer(2);
+		const mirror = await createMirrorApp({
+			endpoint: `http://127.0.0.1:${stub.port}/`,
+		});
+		const svc = mirror.get("console.services.market");
+		// 前两次连接被重置（fetch 抛 TypeError，plugin-http 包装为无 code
+		// 无 response 的 HTTP.Error），退避重试后第三次成功
+		await svc?.start(true);
+		expect(stub.hits()).toBeGreaterThanOrEqual(3);
+		const payload = await svc?.get();
+		expect(Object.keys(payload?.data ?? {})).toEqual([
+			"koishi-plugin-demo",
+		]);
+		expect(payload?.total).toBe(1);
+		await mirror.stop();
+		stub.close();
+	}, 10000);
+});

package/src/node/dependencies/service.ts

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2019-present Shigma and Koishijs contributors.
+// Copyright (c) 2026-present Koishi-CE contributors.
+
+/**
+ * 依赖管理数据服务（`dependencies` 通道）。
+ *
+ * 单向数据流的 node 侧源头：get() 同步构建本地快照（纯磁盘读取）先行
+ * 推送（条目带 fetching 标记），随后在后台并发拉取 registry 元数据填充
+ * latest / error，完成后触发通道刷新二拍推送——前端首屏因此有明确的
+ * 「加载中」态，不会把未拉取完的条目误显示为错误。
+ *
+ * node 侧并发纪律（对标参照实现）：
+ * - 单飞去重：元数据刷新任务同一时刻至多一个，并发调用复用同一任务；
+ * - 循环重扫：刷新循环每轮从快照里重新收集 fetching 条目，期间新的
+ *   get()（安装完成、客户端接入）带来的新条目自动被后续轮次接管，
+ *   不会因单飞复用旧任务而漏拉；
+ * - 过期不覆盖：拉取完成后若快照代次已更新，跳过通道刷新（新循环
+ *   完成后自会推送）。
+ */
+import { DataService } from "@koishi-ce/console";
+import type { Context, Dict } from "@koishi-ce/koishi";
+import { mapLimit } from "@koishi-ce/registry";
+import { loadManifest } from "../installer/manifest.ts";
+import {
+	collectDependencyRequests,
+	resolveLocalDependency,
+} from "./snapshot.ts";
+import type { Dependency } from "./types.ts";
+
+/** registry 元数据并发拉取上限 */
+const CONCURRENCY = 4;
+
+export class DependencyService extends DataService<
+	Dict<Dependency>
+> {
+	// 基类 DataService 声明了 console 注入，子类覆盖须一并保留
+	static override inject = ["console", "installer"];
+
+	/** 快照代次：每次 get() 自增，用于判定后台刷新结果是否已过期 */
+	private serial = 0;
+	/** 进行中的元数据刷新任务（单飞去重） */
+	declare private task: Promise<void> | undefined;
+	/** 最近一轮快照（新快照构建时复用 latest 与 404 负缓存） */
+	private snapshot: Dict<Dependency> = {};
+
+	constructor(ctx: Context) {
+		super(ctx, "dependencies", { authority: 4 });
+	}
+
+	override async get() {
+		this.serial++;
+		const manifest = loadManifest(this.ctx.baseDir);
+		const snapshot = collectDependencyRequests(
+			manifest.dependencies,
+		);
+		for (const [name, dep] of Object.entries(snapshot)) {
+			resolveLocalDependency(name, dep, {
+				previous: this.snapshot[name],
+			});
+		}
+		this.snapshot = snapshot;
+		this.ensureMetadata();
+		return snapshot;
+	}
+
+	private ensureMetadata() {
+		if (this.task) return;
+		this.task = this.refreshMetadata().finally(() => {
+			this.task = undefined;
+		});
+	}
+
+	/**
+	 * 元数据刷新循环：拉完本轮全部 fetching 条目后，若快照代次未变则
+	 * 触发通道刷新（二拍推送）；代次已变（期间有新的 get()）则重扫
+	 * fetching 条目继续，直到无新增且代次一致。
+	 */
+	private async refreshMetadata() {
+		for (;;) {
+			const serial = this.serial;
+			const targets = Object.entries(this.snapshot)
+				.filter(([, dep]) => dep.fetching)
+				.map(([name]) => name);
+			if (!targets.length) return;
+			await mapLimit(targets, CONCURRENCY, async (name) => {
+				await this.resolveMetadata(name);
+			});
+			if (serial !== this.serial) continue;
+			// 版本表经 registry 通道下发（版本下拉消费），一并刷新
+			this.ctx.get("console")?.refresh("dependencies");
+			this.ctx.get("console")?.refresh("registry");
+			return;
+		}
+	}
+
+	/** 单个条目的元数据解析：拉取版本表并填充 latest / error。 */
+	private async resolveMetadata(name: string) {
+		const dep = this.snapshot[name];
+		if (!dep?.fetching) return;
+		const installer = this.ctx.installer;
+		// getPackage 内部单飞去重并写 fullCache；失败也 resolve 空表
+		const versions = await installer.getPackage(name);
+		delete dep.fetching;
+		if (!Object.keys(versions).length) {
+			// 拉取失败：404 归类 not-found（负缓存），其余为网络错误
+			dep.error = installer.pkgErrors[name]?.notFound
+				? "not-found"
+				: "network";
+			delete dep.latest;
+			return;
+		}
+		const [latest] = Object.keys(versions);
+		if (latest !== undefined) dep.latest = latest;
+	}
+}
+
+export default DependencyService;

package/src/node/dependencies/snapshot.test.ts

@@ -0,0 +1,176 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2019-present Shigma and Koishijs contributors.
+// Copyright (c) 2026-present Koishi-CE contributors.
+
+import { describe, expect, it } from "bun:test";
+import {
+	mkdirSync,
+	mkdtempSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	collectDependencyRequests,
+	resolveLocalDependency,
+} from "./snapshot.ts";
+import type { Dependency } from "./types.ts";
+
+/** 造一个临时宿主目录,并在 node_modules 内放置指定包的清单。 */
+function setupHost(installed: Record<string, string> = {}) {
+	const cwd = mkdtempSync(join(tmpdir(), "deps-snapshot-"));
+	for (const [name, version] of Object.entries(installed)) {
+		const dir = join(cwd, "node_modules", name);
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(
+			join(dir, "package.json"),
+			JSON.stringify({ name, version }),
+		);
+	}
+	process.chdir(cwd);
+	return () => {
+		process.chdir(join(cwd, ".."));
+		rmSync(cwd, { recursive: true, force: true });
+	};
+}
+
+describe("collectDependencyRequests", () => {
+	it("以依赖声明为底建骨架并剥掉 ^/~ 前缀", () => {
+		const result = collectDependencyRequests({
+			"koishi-plugin-demo": "^1.2.3",
+			cosmokit: "~1.8.0",
+			pinned: "2.0.0",
+		});
+		expect(result["koishi-plugin-demo"]).toEqual({
+			request: "1.2.3",
+			fetching: true,
+		});
+		expect(result["cosmokit"]?.request).toBe("1.8.0");
+		expect(result["pinned"]?.request).toBe("2.0.0");
+		// 元数据全部置为待拉取
+		expect(result["pinned"]?.fetching).toBe(true);
+	});
+});
+
+describe("resolveLocalDependency", () => {
+	it("补已装版本并保持待拉取形态", () => {
+		const teardown = setupHost({ "pkg-a": "1.0.0" });
+		try {
+			const dep: Dependency = {
+				request: "1.0.0",
+				fetching: true,
+			};
+			resolveLocalDependency("pkg-a", dep, {
+				previous: undefined,
+			});
+			expect(dep.resolved).toBe("1.0.0");
+			expect(dep.workspace).toBe(false);
+			expect(dep.invalid).toBeUndefined();
+			// 已装且合法 semver:继续等待元数据刷新
+			expect(dep.fetching).toBe(true);
+		} finally {
+			teardown();
+		}
+	});
+
+	it("未安装的包 resolved 留空、不标 invalid", () => {
+		const teardown = setupHost();
+		try {
+			const dep: Dependency = {
+				request: "1.0.0",
+				fetching: true,
+			};
+			resolveLocalDependency("pkg-missing", dep, {
+				previous: undefined,
+			});
+			expect(dep.resolved).toBeUndefined();
+			expect(dep.invalid).toBeUndefined();
+			expect(dep.fetching).toBe(true);
+		} finally {
+			teardown();
+		}
+	});
+
+	it("非精确 semver 的请求标记 invalid 且不参与拉取", () => {
+		const teardown = setupHost();
+		try {
+			const dep: Dependency = {
+				request: "file:./plugins/foo",
+				fetching: true,
+			};
+			resolveLocalDependency("local-thing", dep, {
+				previous: undefined,
+			});
+			expect(dep.invalid).toBe(true);
+			expect(dep.fetching).toBeUndefined();
+		} finally {
+			teardown();
+		}
+	});
+
+	it("上一轮 latest 与 404 负缓存被复用,网络错误不沿用", () => {
+		const teardown = setupHost({ "pkg-a": "1.0.0" });
+		try {
+			const base = { request: "1.0.0", resolved: "1.0.0" };
+			// latest 复用:fetching 随之消除
+			const withLatest: Dependency = {
+				...base,
+				fetching: true,
+				latest: "2.0.0",
+			};
+			resolveLocalDependency("pkg-a", withLatest, {
+				previous: { ...base, latest: "2.0.0" },
+			});
+			expect(withLatest.latest).toBe("2.0.0");
+			expect(withLatest.fetching).toBeUndefined();
+
+			// not-found 复用(会话内不再重试)
+			const notFound: Dependency = {
+				...base,
+				fetching: true,
+			};
+			resolveLocalDependency("pkg-a", notFound, {
+				previous: { ...base, error: "not-found" },
+			});
+			expect(notFound.error).toBe("not-found");
+			expect(notFound.fetching).toBeUndefined();
+
+			// 网络错误不沿用:下一轮重新拉取
+			const network: Dependency = {
+				...base,
+				fetching: true,
+			};
+			resolveLocalDependency("pkg-a", network, {
+				previous: { ...base, error: "network" },
+			});
+			expect(network.error).toBeUndefined();
+			expect(network.fetching).toBe(true);
+		} finally {
+			teardown();
+		}
+	});
+
+	it("request 或 resolved 变化的条目不复用上一轮结果", () => {
+		const teardown = setupHost({ "pkg-a": "1.5.0" });
+		try {
+			const dep: Dependency = {
+				request: "1.5.0",
+				fetching: true,
+			};
+			resolveLocalDependency("pkg-a", dep, {
+				previous: {
+					request: "1.0.0",
+					resolved: "1.0.0",
+					latest: "2.0.0",
+					error: "not-found",
+				},
+			});
+			expect(dep.latest).toBeUndefined();
+			expect(dep.error).toBeUndefined();
+			expect(dep.fetching).toBe(true);
+		} finally {
+			teardown();
+		}
+	});
+});

package/src/node/dependencies/snapshot.ts

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2019-present Shigma and Koishijs contributors.
+// Copyright (c) 2026-present Koishi-CE contributors.
+
+/**
+ * 宿主依赖本地快照的构建纯函数。
+ *
+ * 两步：collectDependencyRequests 以宿主 package.json 的依赖声明为底
+ * 构建骨架；resolveLocalDependency 逐包读 node_modules 补已装版本与
+ * workspace 标记。全程只碰本地磁盘、不发网络请求——registry 元数据由
+ * DependencyService 的刷新阶段另行填充。
+ *
+ * 上一轮条目的复用规则（防闪烁 + 负缓存语义）：
+ * - request 与 resolved 未变时沿用 latest（省一次 registry 往返）；
+ * - 仅 404（not-found）的 error 被沿用（registry 确认无此包，会话内
+ *   不再重试）；网络错误的 error 不沿用，下一轮 get() 会重新拉取。
+ */
+import type { Dict } from "@koishi-ce/koishi";
+import { valid } from "semver";
+import { loadManifest } from "../installer/manifest.ts";
+import type { Dependency } from "./types.ts";
+
+/** 以宿主 dependencies 声明为底构建快照骨架（元数据字段全部置为待拉取）。 */
+export function collectDependencyRequests(
+	dependencies: Record<string, string>,
+): Dict<Dependency> {
+	const result: Dict<Dependency> = {};
+	for (const [name, request] of Object.entries(
+		dependencies,
+	)) {
+		// 剥掉 ^/~ 前缀：后续 valid() 判定与 latest 比较都按精确版本语义进行
+		result[name] = {
+			request: request.replace(/^[~^]/, ""),
+			fetching: true,
+		};
+	}
+	return result;
+}
+
+/** 逐包本地解析所需的上下文：上一轮同名条目（复用 latest 与 404 负缓存）。 */
+export interface LocalResolveContext {
+	previous: Dependency | undefined;
+}
+
+/**
+ * 单个依赖条目的本地解析：已装版本 / workspace 标记 / invalid 标记，
+ * 就地修改传入的 dep。node_modules 内无此包时 resolved 留空，由后续
+ * 元数据刷新阶段补齐。
+ */
+export function resolveLocalDependency(
+	name: string,
+	dep: Dependency,
+	ctx: LocalResolveContext,
+): void {
+	try {
+		// 已装版本读 node_modules 内的 package.json；未安装/读取失败留空
+		const meta = loadManifest(name);
+		dep.resolved = meta.version;
+		dep.workspace = meta.$workspace;
+		if (meta.$workspace) {
+			// workspace 包不参与 registry 拉取与更新判定
+			delete dep.fetching;
+		}
+	} catch {
+		// 尚未安装（或残留声明）：保持待拉取形态
+	}
+
+	if (!dep.workspace && !valid(dep.request)) {
+		// 非精确 semver 的请求（file: 路径、git/url 串等）：不参与
+		// latest 刷新，前端据此降级展示
+		dep.invalid = true;
+		delete dep.fetching;
+	}
+
+	const { previous } = ctx;
+	if (
+		previous &&
+		previous.request === dep.request &&
+		previous.resolved === dep.resolved
+	) {
+		if (previous.latest) {
+			dep.latest = previous.latest;
+			delete dep.fetching;
+		}
+		// 404 负缓存：registry 已确认无此包，会话内不再重试；
+		// 网络错误不沿用，下一轮 get() 重新拉取
+		if (previous.error === "not-found") {
+			dep.error = "not-found";
+			delete dep.fetching;
+		}
+	}
+}

package/src/node/dependencies/types.ts

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2019-present Shigma and Koishijs contributors.
+// Copyright (c) 2026-present Koishi-CE contributors.
+
+/**
+ * 依赖条目类型定义（dependencies 数据通道的值类型）。
+ *
+ * 单个依赖条目的请求范围、已装版本与来源标记；latest / error / fetching
+ * 三个可选字段由元数据刷新阶段填充，前端依赖页的分类状态机据此判定
+ * 六态。类型集中在此，node 侧声明与 client 侧镜像（console-services.ts）
+ * 均从这里取形状。
+ */
+
+/** registry 元数据拉取失败的归类：404（registry 无此包）与其余（网络等） */
+export type DependencyError = "not-found" | "network";
+
+/** 依赖条目：请求范围、已装版本、来源标记与最新版信息。 */
+export interface Dependency {
+	/**
+	 * requested semver range
+	 * @example `^1.2.3` -> `1.2.3`
+	 */
+	request: string;
+	/**
+	 * installed package version
+	 * @example `1.2.5`
+	 */
+	resolved?: string | undefined;
+	/** whether it is a workspace package */
+	workspace?: boolean | undefined;
+	/** valid (unsupported) syntax */
+	invalid?: boolean | undefined;
+	/** latest version */
+	latest?: string | undefined;
+	/** registry 元数据拉取失败的归类（缺失代表尚在拉取或已成功） */
+	error?: DependencyError | undefined;
+	/** 本轮元数据尚未拉取完成（前端据此显示加载中而非错误） */
+	fetching?: boolean | undefined;
+}

package/src/node/deps.ts

@@ -8,19 +8,6 @@ import type {
 	DependencyMetaKey,
 	RemotePackage,
 } from "@koishi-ce/registry";
-import type { Dependency } from "./installer/index.ts";
-
-class DependencyProvider extends DataService<
-	Dict<Dependency>
-> {
-	constructor(ctx: Context) {
-		super(ctx, "dependencies", { authority: 4 });
-	}
-
-	override async get() {
-		return this.ctx.installer.getDeps();
-	}
-}
 
 class RegistryProvider extends DataService<
 	Dict<Dict<Pick<RemotePackage, DependencyMetaKey>>>
@@ -34,4 +21,4 @@ class RegistryProvider extends DataService<
 	}
 }
 
-export { DependencyProvider, RegistryProvider };
+export { RegistryProvider };

package/src/node/index.ts

@@ -16,16 +16,15 @@ import type {
 import { gt } from "semver";
 import messageZhCN from "../../locales/message.zh-CN.yml";
 import schemaZhCN from "../../locales/schema.zh-CN.yml";
-import {
-	DependencyProvider,
-	RegistryProvider,
-} from "./deps.ts";
+import { DependencyService } from "./dependencies/service.ts";
+import type { Dependency } from "./dependencies/types.ts";
+import { RegistryProvider } from "./deps.ts";
 import Installer from "./installer/index.ts";
 import MarketProvider from "./market.ts";
 
 export * from "../shared/index.ts";
-
-export { DependencyProvider, Installer, RegistryProvider };
+export type { Dependency };
+export { DependencyService, Installer, RegistryProvider };
 
 declare module "@koishi-ce/koishi" {
 	interface Context {
@@ -36,7 +35,7 @@ declare module "@koishi-ce/koishi" {
 declare module "@koishi-ce/console" {
 	namespace Console {
 		interface Services {
-			dependencies: DependencyProvider;
+			dependencies: DependencyService;
 			registry: RegistryProvider;
 		}
 	}
@@ -243,7 +242,7 @@ export function apply(ctx: Context, config: Config) {
 	});
 
 	ctx.inject(["console", "installer"], (ctx) => {
-		ctx.plugin(DependencyProvider);
+		ctx.plugin(DependencyService);
 		ctx.plugin(RegistryProvider);
 		ctx.plugin(MarketProvider, config.search);