@finesoft/front 0.5.0 → 0.5.2

package/docs/engineering/testing.md

@@ -1,317 +1,15 @@
-# Engineering: testing
+# Testing
 
-The framework is built to be tested. Routes, controllers, and middleware all run through the same dispatch path on server and browser, so a single test exercises both worlds.
+Test operation contracts directly, then verify actual host responses and native UI lifetimes. Source exports alone do not prove packed consumer isolation.
 
-## What to test
-
-| Subject        | What to assert                                                                                   | Layer       |
-| -------------- | ------------------------------------------------------------------------------------------------ | ----------- |
-| Controllers    | Given params + scoped container, the page produced is correct.                                   | unit        |
-| Guards         | Given a `NavigationContext`, the result is `next` / `redirect` / `rewrite` / `deny` as expected. | unit        |
-| Routes         | URL → expected intent + render mode.                                                             | unit        |
-| Full request   | URL → final HTML / status code through the full pipeline.                                        | integration |
-| Proxy / server | Hono routes return the right responses for synthetic requests.                                   | integration |
-
-## Vitest setup
-
-The repo uses Vite+. Always import from `vite-plus/test`:
-
-```ts
-import { describe, expect, test, vi, beforeEach, afterEach } from "vite-plus/test";
-```
-
-Run tests with:
-
-```bash
-vp test                     # all
-vp test path/to/file.test.ts # one file
-vp test -t "name match"     # filter by test name
-vp test --coverage          # with coverage
-```
-
-## Testing a 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",
-        });
-    });
-});
-```
-
-Key idea: **build a `Container` per test, register only what the controller needs.** Don't pull in a real `Framework` — you'd be testing the framework, not your controller.
-
-## Testing a guard
-
-Guards take a `NavigationContext` and return a `MiddlewareResult`. Build a fake context inline:
-
-```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" });
-    });
-});
-```
-
-The factory function (`makeCtx`) is the pattern — keep it co-located with the guard, parameterize the bits the test actually cares about.
-
-## Testing routes
-
-To assert URL → intent mapping:
-
-```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();
-    });
-});
-```
-
-This catches route regressions during refactors — a renamed intent shows up as a failing test, not a 404 in production.
-
-## Testing the full request pipeline
-
-For SSR end-to-end tests, exercise `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");
-    });
-});
-```
-
-This is the highest-value test layer — it exercises routing, middleware, controllers, and rendering together.
-
-## Mocking the network
-
-`HttpClient` uses `fetch` directly. Stub it via `vi.stubGlobal`:
-
-```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));
-});
-```
-
-For tests with many fetches, build a small registry:
-
-```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 }),
-});
-```
-
-This makes "what does my test expect to be fetched" readable at a glance.
-
-## Disposing scopes in tests
-
-If your test creates a scope, dispose it in `afterEach`:
+## Direct operation / 直接操作
 
 ```ts
-let scope: Container | null = null;
-
-afterEach(() => {
-    scope?.dispose();
-    scope = null;
-});
-
-test("...", () => {
-    scope = framework.container.createScope();
-    scope.register("api", () => mockApi);
-    // ...
-});
-```
-
-Vitest isolates tests by default, but disposing exposes leaks if the scope had `destroy()`-able resources (recorders, etc.).
-
-## Testing middleware with `rewrite`
-
-`rewrite` in `beforeLoad` recurses through the router. Test both the rewrite signal and the resolved final route:
-
-```ts
-test("legacy URL rewrites to canonical", async () => {
-    const render = createSSRRender({ bootstrap /* ... */ });
-    const result = await render("/old/products/42");
-
-    // The user-visible URL stays unchanged
-    expect(result.status).toBe(200);
-
-    // But the rendered controller was for /products/42 — assert via the rendered HTML
-    expect(result.html).toContain("Widget"); // product 42's name
+import { expect, test } from "vite-plus/test";
+import { runtime, double } from "./data-app";
+test("double", async () => {
+    expect(await runtime.execute(double, 3)).toBe(6);
 });
 ```
 
-For `afterLoad` rewrites (canonicalization), assert the `Content-Location` header:
-
-```ts
-const result = await render("/page?utm=x");
-expect(result.headers["Content-Location"]).toBe("/page");
-```
-
-## Coverage targets
-
-The framework itself targets >95% on `core` and >85% on `server`. For application code, aim for:
-
-- **Controllers**: 100% of `execute()` happy paths + at least one `fallback()` test.
-- **Guards**: every branch (pass / redirect / deny).
-- **Routes**: at least one assertion per route group that the URLs resolve as expected.
-
-Don't chase 100% on view components — those test the view layer, not the framework. Test the page-shape contracts the controllers produce instead.
-
-## Speed
-
-Vitest with vite-plus is fast — ~1ms per test for unit, ~10ms for integration. If you see slower:
-
-- Avoid creating a full `Framework` in tight loops; build a `Container` directly.
-- Mock heavy `bootstrap()` calls in unit tests.
-- Use `vi.useFakeTimers()` for tests that wait on `setTimeout` (retry logic, debouncing).
-
-## See also
-
-- [Testing the proxy](../09-server-and-deployment.md#proxy-routes) — the framework's own tests at `packages/server/test/proxy.test.ts` are good references
+Run `vp check`, `vp test --coverage` and `vp run -r build`. Repository artifact runners cover Node/workerd, real browser Worker, native React/Vue/Svelte, wire protocol and installed local tarballs. Dispose runtimes, listeners and browser instances owned by each test. `scripts/verify-runtime-boundaries.mjs` exercises public packed entries without workspace aliases.

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

@@ -1,215 +1,3 @@
-# Pitfall: container scope leak
+# Resource cleanup boundaries
 
-## Symptom
-
-Memory usage on the server climbs over hours of uptime and never recovers. Eventually:
-
-- Garbage collection pauses get longer and longer
-- Heap snapshots show retained `Container`, `HttpClient`, `Logger`, `EventRecorder` instances that should have died with their requests
-- The server eventually OOMs or gets killed by your orchestrator
-
-This is a leak that doesn't show up in tests — they finish too fast — but compounds in production.
-
-## Root cause
-
-A scoped `Container` (typically a request scope) was created but **never disposed**. The framework caches every resolved factory result inside the scope. Anything resolved during the request stays referenced until the scope is collected.
-
-Worse: if the scope has child scopes, **they** also stay referenced. A request that creates 3 child scopes for sub-operations leaks all 4.
-
-The fix (already in the framework) tracks children explicitly and recursively disposes:
-
-```ts
-// packages/core/src/dependencies/container.ts
-dispose(): void {
-    // Snapshot children first — child.dispose() removes itself from this.children
-    const childSnapshot = Array.from(this.children);
-    for (const child of childSnapshot) {
-        child.dispose();
-    }
-    this.children.clear();
-    // ...dispose own resources...
-    if (this.parent) {
-        this.parent.children.delete(this);
-    }
-}
-```
-
-But this only helps if **someone calls `dispose()` on the root scope.**
-
-## When the framework disposes for you
-
-- Request scopes created by `createSSRRender` are disposed after the response is sent (success or failure)
-- The browser-side framework's main container lives for the lifetime of the page, then is GC'd when the page navigates away
-
-So if you're only using the standard request lifecycle, you don't leak.
-
-## When you leak
-
-### Long-lived background work
-
-```ts
-// BAD
-async execute(params, container) {
-    setTimeout(async () => {
-        const api = container.resolve("api");
-        await api.cleanup();
-    }, 60_000);
-    return { kind: "done" };
-}
-```
-
-The `container` reference inside the closure keeps the request scope alive for 60 seconds **after the response was already sent**. The framework disposed the scope, but your closure resurrected the reference. Anything else resolved through `container.resolve()` is now reached through this dangling closure.
-
-Fix: capture the resolved value before the response, not the container:
-
-```ts
-// GOOD
-async execute(params, container) {
-    const api = container.resolve("api");
-    setTimeout(async () => {
-        await api.cleanup();   // closure captures the resolved value, not the scope
-    }, 60_000);
-    return { kind: "done" };
-}
-```
-
-Even better: don't fire-and-forget from inside a request. Queue the work somewhere persistent.
-
-### Manually created scopes you forgot to dispose
-
-```ts
-// BAD
-async function bulkOperation() {
-    const scope = framework.container.createScope();
-    scope.register("tenantId", () => "tenant-42");
-
-    for (const item of items) {
-        await processItem(scope, item);
-    }
-    // forgot scope.dispose()
-}
-```
-
-The scope outlives the function. Every `processItem` call resolved logger, API client, recorder — all retained. If `bulkOperation` runs once per request, that's a leak per request.
-
-Fix: dispose in `finally`:
-
-```ts
-// GOOD
-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();
-    }
-}
-```
-
-### Storing references at module scope
-
-```ts
-// BAD
-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();
-}
-```
-
-The scope grows monotonically — `cachedScope` survives forever, and every dependency resolved through it is pinned in memory.
-
-Fix: either (a) make the scope properly request-scoped, or (b) make it deliberately app-scoped on the parent container instead of a scope.
-
-## Diagnosing
-
-### Symptom-level check
-
-Watch RSS over time with a steady workload:
-
-```bash
-# In production
-ps -o pid,rss,command -p $(pidof node)
-# RSS climbing without bound = likely leak
-```
-
-A healthy server has fluctuating but bounded RSS. A leaking server's RSS grows monotonically.
-
-### Heap snapshots
-
-```bash
-# Add to your Node startup
-node --inspect=0.0.0.0:9229 server.js
-
-# In Chrome DevTools → Memory → Take heap snapshot
-# Run load, take another snapshot, look at "Comparison"
-```
-
-Look for:
-
-- `Container` instances increasing
-- `HttpClient` instances increasing
-- `EventRecorder` instances increasing
-- Any of your own registered service classes increasing
-
-The retainer chain in DevTools tells you what holds the reference. Usually a closure or a setTimeout / setInterval.
-
-### Targeted test
-
-For unit testing, instrument `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();
-});
-```
-
-## Idempotent disposal
-
-The framework's `dispose()` is **idempotent** — calling it twice is safe:
-
-```ts
-scope.dispose();
-scope.dispose(); // no-op, no error
-```
-
-So if you're unsure whether something already disposed, just call dispose anyway in your cleanup. Defensive coding here costs nothing.
-
-## What `destroy()` does
-
-If your registered factory returns something with a `destroy()` method (loggers, recorders, custom services), `dispose()` calls it:
-
-```ts
-class MyService {
-    destroy() {
-        // close DB connections, flush queues, etc.
-    }
-}
-
-container.register("myService", () => new MyService());
-// When the scope is disposed, MyService.destroy() runs.
-```
-
-Failure inside `destroy()` is swallowed and logged — one failing service can't prevent the rest from being cleaned up.
-
-## Related
-
-- [Chapter 7: DI container](../07-di-container.md) — the full lifecycle model
-- The fix that introduced recursive child disposal: `packages/core/src/dependencies/container.ts` (see the `children: Set<Container>` field)
+Use the standard runtime/HTTP/browser owners instead of manually opening scopes in ordinary application code. runtime.execute completes its invocation and cleanup; HTTP streaming retains the scope until the body finishes, fails or is cancelled. Await browser handle.dispose when removing an embedded app. Disposal waits for in-flight initialization and releases owned values once in dependency order. Never retain a request context, resolved request resource or getter in detached work. runManagedTask provides a separate task context and uses host waitUntil; unavailable host support is an explicit capability error. Cancellation prevents later framework commits, but does not roll back external mutations.