@finesoft/front 0.5.1 → 0.5.3

package/docs/zh/engineering/testing.md

@@ -1,317 +1,15 @@
-# 工程实践：测试
+# 测试
 
-框架为可测试性而设计。路由、Controller、中间件在服务端和浏览器都走同一个 dispatch 路径，所以一个测试同时检验两端。
+先直接测操作契约，再验证主机响应和原生 UI 生命周期。仅测源码导出不能证明打包消费者隔离。
 
-## 测什么
-
-| 对象           | 断言什么                                                                             | 层级 |
-| -------------- | ------------------------------------------------------------------------------------ | ---- |
-| Controller     | 给定 params + scope 化容器，产出的 page 正确。                                       | 单元 |
-| 守卫           | 给定 `NavigationContext`，结果是 `next` / `redirect` / `rewrite` / `deny` 的预期值。 | 单元 |
-| 路由           | URL → 预期的 intent + 渲染模式。                                                     | 单元 |
-| 完整请求       | URL → 经完整管线产出的最终 HTML / 状态码。                                           | 集成 |
-| Proxy / 服务器 | Hono 路由对合成请求返回正确的响应。                                                  | 集成 |
-
-## Vitest 设置
-
-仓库用 Vite+。总是从 `vite-plus/test` 导入：
-
-```ts
-import { describe, expect, test, vi, beforeEach, afterEach } from "vite-plus/test";
-```
-
-跑测试：
-
-```bash
-vp test                      # 全部
-vp test path/to/file.test.ts # 一个文件
-vp test -t "name match"      # 按测试名过滤
-vp test --coverage           # 带覆盖率
-```
-
-## 测一个 Controller
-
-```ts
-// src/controllers/product.test.ts
-import { afterEach, describe, expect, test, vi } from "vite-plus/test";
-import { Container } from "@finesoft/front";
-import { ProductController } from "./product";
-
-describe("ProductController", () => {
-    afterEach(() => {
-        vi.restoreAllMocks();
-    });
-
-    test("returns product page on success", async () => {
-        const container = new Container();
-        container.register("productApi", () => ({
-            getById: vi.fn(async (id) => ({ name: "Widget", price: 9.99 })),
-        }));
-
-        const controller = new ProductController();
-        const page = await controller.execute({ id: "42" }, container);
-
-        expect(page).toEqual({
-            kind: "product",
-            id: "42",
-            name: "Widget",
-            price: 9.99,
-        });
-    });
-
-    test("fallback returns degraded page on api failure", () => {
-        const controller = new ProductController();
-        const page = controller.fallback({ id: "42" }, new Error("network down"));
-
-        expect(page).toMatchObject({
-            kind: "product",
-            id: "42",
-            name: "Not available",
-        });
-    });
-});
-```
-
-关键点：**每个测试建一个 `Container`，只注册 Controller 真正需要的。** 别拉一个真实的 `Framework` 进来 —— 那是在测框架而不是测你的 Controller。
-
-## 测一个守卫
-
-守卫接 `NavigationContext` 返回 `MiddlewareResult`。内联构造一个假 context：
-
-```ts
-import { afterEach, describe, expect, test, vi } from "vite-plus/test";
-import { Container } from "@finesoft/front";
-import { authGuard } from "./auth";
-
-function makeCtx(overrides: Partial<{ cookie: string | null }> = {}) {
-    return {
-        url: new URL("http://app.test/admin"),
-        intent: { intentId: "admin", params: {} },
-        container: new Container(),
-        getCookie: vi.fn((name: string) => overrides.cookie ?? null),
-        getHeader: vi.fn(() => null),
-        isSsr: true,
-    };
-}
-
-describe("authGuard", () => {
-    test("redirects unauthenticated user to /login", () => {
-        const ctx = makeCtx({ cookie: null });
-        const result = authGuard(ctx);
-
-        expect(result).toEqual({
-            kind: "redirect",
-            url: "/login?next=%2Fadmin",
-            status: 302,
-        });
-    });
-
-    test("passes through when token is present", () => {
-        const ctx = makeCtx({ cookie: "valid-token" });
-        const result = authGuard(ctx);
-
-        expect(result).toEqual({ kind: "next" });
-    });
-});
-```
-
-工厂函数（`makeCtx`）是套路 —— 跟守卫放一起，把测试真正关心的位参数化。
-
-## 测路由
-
-断言 URL → intent 映射：
-
-```ts
-import { describe, expect, test } from "vite-plus/test";
-import { Framework } from "@finesoft/front";
-import { bootstrap } from "./bootstrap";
-
-describe("routes", () => {
-    test("resolves /products/42 to product intent", () => {
-        const framework = Framework.create({});
-        bootstrap(framework);
-
-        const match = framework.router.resolve("/products/42");
-
-        expect(match).toMatchObject({
-            intent: { intentId: "product", params: { id: "42" } },
-            renderMode: "ssr",
-        });
-    });
-
-    test("returns null for unmatched URL", () => {
-        const framework = Framework.create({});
-        bootstrap(framework);
-
-        expect(framework.router.resolve("/does-not-exist")).toBeNull();
-    });
-});
-```
-
-这能在重构时抓住路由回归 —— 一个改名的 intent 表现为失败的测试，而不是生产里的 404。
-
-## 测完整请求管线
-
-SSR 端到端测试，调 `createSSRRender`：
-
-```ts
-import { describe, expect, test } from "vite-plus/test";
-import { createSSRRender } from "@finesoft/front";
-import { bootstrap } from "./bootstrap";
-
-describe("SSR pipeline", () => {
-    test("renders home page with serialized data", async () => {
-        const render = createSSRRender({
-            bootstrap,
-            getErrorPage: () => ({ kind: "error", title: "Error" }),
-            async renderApp(page) {
-                return {
-                    html: `<main>${(page as any).title}</main>`,
-                    head: "",
-                    css: "",
-                };
-            },
-        });
-
-        const result = await render("/", {
-            template: `<!doctype html><html><head><!--head--></head><body><!--ssr--></body></html>`,
-        });
-
-        expect(result.status).toBe(200);
-        expect(result.html).toContain("<main>Welcome</main>");
-        expect(result.html).toContain('id="__finesoft_data__"');
-    });
-
-    test("returns 302 when guard redirects", async () => {
-        const render = createSSRRender({
-            /* ... */
-        });
-        const result = await render("/admin");
-
-        expect(result.status).toBe(302);
-        expect(result.redirectUrl).toBe("/login?next=%2Fadmin");
-    });
-});
-```
-
-这是最高价值的测试层 —— 同时检验路由、中间件、Controller、渲染。
-
-## Mock 网络
-
-`HttpClient` 直接用 `fetch`。通过 `vi.stubGlobal` stub：
-
-```ts
-import { afterEach, beforeEach, test, vi, expect } from "vite-plus/test";
-
-let fetchMock: ReturnType<typeof vi.fn>;
-
-beforeEach(() => {
-    fetchMock = vi.fn();
-    vi.stubGlobal("fetch", fetchMock);
-});
-
-afterEach(() => {
-    vi.unstubAllGlobals();
-});
-
-test("UserApi.list parses JSON response", async () => {
-    fetchMock.mockResolvedValueOnce(
-        new Response(JSON.stringify([{ id: "1", name: "Alice" }]), {
-            status: 200,
-            headers: { "Content-Type": "application/json" },
-        }),
-    );
-
-    const api = new UserApi({ baseUrl: "/api" });
-    const users = await api.list();
-
-    expect(users).toEqual([{ id: "1", name: "Alice" }]);
-    expect(fetchMock).toHaveBeenCalledWith("/api/users", expect.any(Object));
-});
-```
-
-测试里 fetch 多时建个小注册表：
-
-```ts
-function setupFetch(routes: Record<string, () => Response>) {
-    fetchMock.mockImplementation(async (url: string) => {
-        const handler = routes[url];
-        if (!handler) throw new Error(`Unexpected fetch: ${url}`);
-        return handler();
-    });
-}
-
-setupFetch({
-    "/api/users": () => new Response(JSON.stringify(users), { status: 200 }),
-    "/api/products": () => new Response(JSON.stringify(products), { status: 200 }),
-});
-```
-
-让「测试预期 fetch 什么」一眼可读。
-
-## 测试中 dispose scope
-
-测试里创建了 scope，在 `afterEach` 里 dispose：
+## Direct operation / 直接操作
 
 ```ts
-let scope: Container | null = null;
-
-afterEach(() => {
-    scope?.dispose();
-    scope = null;
-});
-
-test("...", () => {
-    scope = framework.container.createScope();
-    scope.register("api", () => mockApi);
-    // ...
-});
-```
-
-Vitest 默认隔离测试，但 dispose 能暴露 scope 含 `destroy()` 资源（recorder 等）时的泄漏。
-
-## 测带 `rewrite` 的中间件
-
-`beforeLoad` 里的 rewrite 通过 router 递归。测试时同时断言 rewrite 信号和最终解析到的路由：
-
-```ts
-test("legacy URL rewrites to canonical", async () => {
-    const render = createSSRRender({ bootstrap /* ... */ });
-    const result = await render("/old/products/42");
-
-    // 用户可见的 URL 不变
-    expect(result.status).toBe(200);
-
-    // 但渲染走的 Controller 是 /products/42 的 —— 通过渲染后 HTML 断言
-    expect(result.html).toContain("Widget"); // product 42 的名字
+import { expect, test } from "vite-plus/test";
+import { runtime, double } from "./data-app";
+test("double", async () => {
+    expect(await runtime.execute(double, 3)).toBe(6);
 });
 ```
 
-`afterLoad` rewrite（canonicalization），断言 `Content-Location` 头：
-
-```ts
-const result = await render("/page?utm=x");
-expect(result.headers["Content-Location"]).toBe("/page");
-```
-
-## 覆盖率目标
-
-框架本身在 `core` 上瞄准 >95%，`server` 上 >85%。应用代码目标：
-
-- **Controller**：100% `execute()` 主路径 + 至少一个 `fallback()` 测试。
-- **守卫**：每个分支（通过 / redirect / deny）。
-- **路由**：每个路由组至少一个 URL 解析断言。
-
-视图组件不必追求 100% —— 那是测视图层，不是测框架。测 Controller 产出的 page 形状契约就够了。
-
-## 速度
-
-vite-plus 的 Vitest 很快 —— 单元 ~1ms 一个测试，集成 ~10ms。慢的话：
-
-- 紧密循环里别建完整 `Framework`；直接建 `Container`。
-- 单元测试里 mock 重的 `bootstrap()`。
-- 等 `setTimeout`（重试、debounce）的测试用 `vi.useFakeTimers()`。
-
-## 参考
-
-- [测试 proxy](../09-server-and-deployment.md#proxy-路由) —— 框架自己的 proxy 测试 `packages/server/test/proxy.test.ts` 是好参考
+运行 `vp check`、`vp test --coverage`、`vp run -r build`。仓库产物验证覆盖 Node/workerd、真实浏览器 Worker、React/Vue/Svelte、wire 协议、本地 tarball 安装。测试需释放自己拥有的运行时、监听器、浏览器实例。`scripts/verify-runtime-boundaries.mjs` 在无 workspace 别名的环境验证公开打包入口。

package/docs/zh/pitfalls/container-scope-leak.md

@@ -1,215 +1,3 @@
-# 陷阱：Container scope 泄漏
+# 资源释放边界
 
-## 症状
-
-服务器内存随运行时间上涨从不回落。最终：
-
-- GC 暂停越来越长
-- 堆快照显示该跟着请求死掉的 `Container`、`HttpClient`、`Logger`、`EventRecorder` 实例被保留
-- 服务器最终 OOM 或被编排器杀掉
-
-测试里看不到的泄漏 —— 测试结束太快 —— 但生产里累积。
-
-## 根因
-
-scope 化的 `Container`（通常是请求 scope）被创建了但**从未 dispose**。框架在 scope 里缓存每个 resolve 过的工厂结果。请求中 resolve 的任何东西都被引用持有直到 scope 被 GC。
-
-更糟：如果 scope 有子 scope，**它们**也持续被引用。一个请求创建 3 个子 scope 做子操作，泄漏 4 个。
-
-修复（框架内已有）显式跟踪子 scope 并递归 dispose：
-
-```ts
-// packages/core/src/dependencies/container.ts
-dispose(): void {
-    // 先快照 children —— child.dispose() 会自己从 this.children 移除
-    const childSnapshot = Array.from(this.children);
-    for (const child of childSnapshot) {
-        child.dispose();
-    }
-    this.children.clear();
-    // ...dispose 自身资源...
-    if (this.parent) {
-        this.parent.children.delete(this);
-    }
-}
-```
-
-但这只在**有人调用根 scope 的 `dispose()`** 时管用。
-
-## 什么时候框架替你 dispose
-
-- `createSSRRender` 创建的请求 scope，在响应发送后（无论成功失败）dispose
-- 浏览器端框架的主容器活到页面生命周期结束，导航离开后 GC
-
-只用标准请求生命周期就不会泄漏。
-
-## 什么时候你会泄漏
-
-### 长跑后台工作
-
-```ts
-// 不好
-async execute(params, container) {
-    setTimeout(async () => {
-        const api = container.resolve("api");
-        await api.cleanup();
-    }, 60_000);
-    return { kind: "done" };
-}
-```
-
-闭包里 `container` 引用让请求 scope 在响应已发送**之后**活了 60 秒。框架 dispose 了 scope，但你的闭包让引用复活。任何通过 `container.resolve()` resolve 出的东西现在都通过这个悬挂闭包能到达。
-
-修：捕获 resolve 后的值，不捕获 container：
-
-```ts
-// 好
-async execute(params, container) {
-    const api = container.resolve("api");
-    setTimeout(async () => {
-        await api.cleanup();   // 闭包捕获 resolve 后的值，不是 scope
-    }, 60_000);
-    return { kind: "done" };
-}
-```
-
-更好：请求内别 fire-and-forget。把工作排到持久的地方。
-
-### 自己开的 scope 忘了 dispose
-
-```ts
-// 不好
-async function bulkOperation() {
-    const scope = framework.container.createScope();
-    scope.register("tenantId", () => "tenant-42");
-
-    for (const item of items) {
-        await processItem(scope, item);
-    }
-    // 忘了 scope.dispose()
-}
-```
-
-scope 活过函数。每次 `processItem` 调用 resolve 了 logger、API 客户端、recorder —— 都被保留。`bulkOperation` 一次请求跑一次，每个请求都泄漏。
-
-修：在 `finally` 里 dispose：
-
-```ts
-// 好
-async function bulkOperation() {
-    const scope = framework.container.createScope();
-    try {
-        scope.register("tenantId", () => "tenant-42");
-        for (const item of items) {
-            await processItem(scope, item);
-        }
-    } finally {
-        scope.dispose();
-    }
-}
-```
-
-### 模块级存引用
-
-```ts
-// 不好
-let cachedScope: Container | null = null;
-
-async function withTenantContext(tenantId: string, fn: () => Promise<void>) {
-    if (!cachedScope) {
-        cachedScope = framework.container.createScope();
-        cachedScope.register("tenantId", () => tenantId);
-    }
-    return fn();
-}
-```
-
-scope 单调增长 —— `cachedScope` 永远活着，通过它 resolve 的每个依赖都被钉在内存里。
-
-修：要么 (a) 让 scope 正确按请求 scope 化，要么 (b) 把它有意按应用级注册到父容器，而不是 scope。
-
-## 诊断
-
-### 症状级检查
-
-稳定负载下观察 RSS：
-
-```bash
-# 生产
-ps -o pid,rss,command -p $(pidof node)
-# RSS 无界增长 = 多半泄漏
-```
-
-健康服务器 RSS 浮动但有界。泄漏服务器 RSS 单调增长。
-
-### 堆快照
-
-```bash
-# Node 启动加
-node --inspect=0.0.0.0:9229 server.js
-
-# Chrome DevTools → Memory → Take heap snapshot
-# 跑负载，再拍一张，看 "Comparison"
-```
-
-找：
-
-- `Container` 实例增多
-- `HttpClient` 实例增多
-- `EventRecorder` 实例增多
-- 你自己注册的服务类增多
-
-DevTools 里的 retainer chain 告诉你什么持有引用。通常是闭包或 setTimeout / setInterval。
-
-### 针对性测试
-
-单元测试，给 `dispose()` 加监控：
-
-```ts
-test("scope is disposed after request", async () => {
-    const disposeSpy = vi.fn();
-    const scope = framework.container.createScope();
-    const original = scope.dispose.bind(scope);
-    scope.dispose = vi.fn(() => {
-        disposeSpy();
-        original();
-    });
-
-    await processRequest(scope);
-
-    expect(disposeSpy).toHaveBeenCalled();
-});
-```
-
-## 幂等 dispose
-
-框架的 `dispose()` 是**幂等**的 —— 调两次安全：
-
-```ts
-scope.dispose();
-scope.dispose(); // no-op，不报错
-```
-
-不确定是不是已经 dispose 过，直接调 dispose。这里防御性写代码不花成本。
-
-## `destroy()` 做什么
-
-注册的工厂返回的对象有 `destroy()` 方法（logger、recorder、自定义服务），`dispose()` 会调它：
-
-```ts
-class MyService {
-    destroy() {
-        // 关 DB 连接、flush 队列等
-    }
-}
-
-container.register("myService", () => new MyService());
-// scope dispose 时，MyService.destroy() 跑。
-```
-
-`destroy()` 里抛错被吞掉并记录 —— 一个服务失败不阻止其他服务清理。
-
-## 参考
-
-- [第 7 章：DI 容器](../07-di-container.md) —— 完整生命周期模型
-- 引入递归子 dispose 的修复：`packages/core/src/dependencies/container.ts`（看 `children: Set<Container>` 字段）
+普通业务使用 runtime/HTTP/browser 标准所有者，不手动开 scope。runtime.execute 完成调用与清理；HTTP 流保留 scope 至响应体完成、失败或取消。移除嵌入应用时等待 handle.dispose。释放等待正在初始化的资源，再按依赖顺序恰好一次释放拥有值。后台任务不能保留请求上下文、请求资源或 getter。runManagedTask 使用独立任务上下文及主机 waitUntil，不支持时返回能力错误。取消阻止框架后续提交，不回滚外部修改。