@finesoft/front 0.1.76 → 0.1.77

package/docs/engineering/testing.md

@@ -0,0 +1,317 @@
+# Engineering: 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.
+
+## 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`:
+
+```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
+});
+```
+
+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

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

@@ -0,0 +1,215 @@
+# Pitfall: container scope leak
+
+## 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)