@finesoft/front 0.1.75 → 0.1.77

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)

package/docs/pitfalls/i18n-bundle-size.md

@@ -0,0 +1,182 @@
+# Pitfall: i18n bundle size
+
+## Symptom
+
+Lighthouse complains about a large initial JS payload. Network panel shows a huge chunk on first request. Your `dist/client/assets/index-*.js` is bigger than it should be, and `vp build --analyze` shows the messages folder dominating the bundle.
+
+## Root cause
+
+Translations got bundled into the main client chunk instead of being split per locale. Either:
+
+- You imported `src/locales/*.json` directly at module top:
+
+    ```ts
+    import zh from "../locales/zh-Hans.json";
+    import en from "../locales/en-US.json";
+    import ja from "../locales/ja-JP.json";
+    ```
+
+    All three locales now live in every user's bundle, even though each user only sees one.
+
+- You built a `Translator` with all messages inlined at module top:
+
+    ```ts
+    const t = new SimpleTranslator({
+        locale: "en-US",
+        messages: { ...zhMessages, ...enMessages, ...jaMessages },
+    });
+    ```
+
+- You serialized translations into HTML via `serializeServerData`, so every SSR page response includes the full dictionary.
+
+## Fix
+
+### Use `messagesDir` instead of static imports
+
+Configure the Vite plugin:
+
+```ts
+finesoftFrontViteConfig({
+    i18n: { messagesDir: "src/locales" },
+});
+```
+
+The plugin generates a per-locale loader. On the server it reads from disk; on the browser it dynamic-imports the appropriate chunk. Vite splits each locale's JSON into its own chunk, and only the chunk matching the resolved locale is fetched.
+
+```
+dist/client/assets/
+├── index-abc123.js       ← main bundle (no translations)
+├── locale-en-US-def456.js ← only loaded for en-US visitors
+├── locale-zh-Hans-789.js  ← only loaded for zh-Hans visitors
+└── locale-ja-JP-xyz.js    ← only loaded for ja-JP visitors
+```
+
+### Don't serialize translations into HTML
+
+The framework deliberately does **not** include the dictionary in `PrefetchedIntents`. The browser fetches its locale chunk in parallel with the initial render.
+
+If you've been manually injecting translations into the page via your own mechanism, stop:
+
+```html
+<!-- BAD — every SSR response carries the dictionary -->
+<script>
+    window.__TRANSLATIONS__ = { hello: "你好" /* hundreds of keys */ };
+</script>
+```
+
+```ts
+// GOOD — the framework loads it as a separate chunk
+// (handled automatically when you use messagesDir)
+```
+
+### Check what's actually shipping
+
+```bash
+vp build
+ls -lah dist/client/assets/locale-*
+ls -lah dist/client/assets/index-*
+```
+
+The index chunk should not change when you add a new locale's JSON. If it does, something's wrong.
+
+For a visual breakdown:
+
+```bash
+vp build --analyze
+```
+
+This opens an interactive treemap of bundle contents. Locale chunks should be small (KB), separate, and named.
+
+## How big is "too big"?
+
+Rough thresholds for first-paint critical JS (the index chunk):
+
+- Static marketing site: <50 KB gzipped
+- Standard SPA: <150 KB gzipped
+- Heavy dashboard: <300 KB gzipped
+
+If translations push your index chunk past these, separate them. Per-locale chunks of 10-50 KB are normal and shouldn't worry you.
+
+## Server-side: the dictionary is cached, not bundled
+
+On the server, the framework reads the locale JSON from disk on first request and caches it for subsequent requests:
+
+```
+Request 1 (zh-Hans): disk read of zh-Hans.json, cached
+Request 2 (zh-Hans): served from cache
+Request 3 (en-US):   disk read of en-US.json, cached
+```
+
+You don't ship a huge SSR bundle either — `tsdown` packages your server entry, but the locale JSONs are read from disk at runtime, not embedded.
+
+This means:
+
+- ✅ Cold-start cost: one disk read per locale, once per worker
+- ✅ Steady-state: zero overhead — locales sit in a `Map`
+- ❌ Mutability: edit a JSON, server keeps the cached old version until restart
+
+The mutability issue isn't usually a problem because you commit translations to source control and a redeploy reloads them. For runtime-updated translations, use the custom `loadMessages` callback to fetch from a service.
+
+## What if my dictionary is genuinely huge?
+
+If a single locale's dictionary is multiple MB (rare — most apps fit in <100 KB):
+
+### Split by namespace
+
+```
+src/locales/
+├── en-US/
+│   ├── common.json
+│   ├── checkout.json
+│   ├── admin.json
+│   └── help-center.json
+└── zh-Hans/
+    └── ...
+```
+
+Build a custom `loadMessages` that loads only the namespaces a given page needs:
+
+```ts
+createSSRRender({
+    bootstrap,
+    async loadMessages(locale) {
+        // load only "common" eagerly; lazy-load others on demand
+        return import(`./locales/${locale}/common.json`);
+    },
+    async renderApp(page) {
+        /* ... */
+    },
+});
+```
+
+The view layer can then call `await translator.loadNamespace("admin")` before rendering admin-specific strings.
+
+### Lazy-load on view mount
+
+For very large optional dictionaries (help content, error code messages), fetch them on demand from the view layer rather than at framework startup. The framework doesn't need to know about them — they're just data.
+
+## Network-side optimization
+
+Even with proper splitting, you can speed up the locale fetch:
+
+- Set long `Cache-Control` on locale chunks (Vite's content-hash filenames make this safe)
+- Preload the user's locale chunk:
+    ```html
+    <link rel="preload" href="/assets/locale-en-US-def456.js" as="script" crossorigin />
+    ```
+- For high-traffic apps, push the locale chunk over the same HTTP/2 connection as the main JS
+
+## Why not just put translations in the HTML?
+
+Because:
+
+- Every page response ships the entire dictionary — including content for pages the user never visits
+- HTML can't be cached at the CDN level when it varies by locale and contains the dictionary
+- SSR latency increases linearly with dictionary size
+
+The per-locale chunk is the right tradeoff: shipped once, cached forever, only for the locale the user actually has.
+
+## Related
+
+- [Chapter 5: i18n](../05-i18n.md) — the full picture of locale handling
+- The Vite plugin source: `packages/server/src/vite-plugin.ts` (search for `messagesDir`)

package/docs/pitfalls/proxy-binary-payloads.md

@@ -0,0 +1,133 @@
+# Pitfall: proxy binary payloads
+
+## Symptom
+
+You proxy an upstream that returns an image / PDF / protobuf, and:
+
+- Images come through corrupted (broken thumbnails, gray boxes)
+- PDFs fail to open ("invalid PDF structure")
+- Protobuf clients throw "unexpected wire type" / decoding errors
+- File sizes are slightly different between source and proxied response
+
+The headers look fine. The status is 200. The body is what's broken.
+
+## Root cause
+
+Earlier versions of the proxy forwarded responses via `response.text()`. `text()` decodes bytes as **UTF-8** — which works for JSON and HTML but **destroys** any non-UTF-8 byte sequence:
+
+- Bytes that aren't valid UTF-8 are replaced with `U+FFFD` (the replacement character, `0xEF 0xBF 0xBD`)
+- The decoded string is then re-encoded as UTF-8 when it goes back into the response, producing a **different byte sequence than the original**
+
+A PNG file starts with `0x89 0x50 0x4E 0x47 0x0D 0x0A 0x1A 0x0A` — the leading `0x89` is not valid UTF-8, so it becomes `0xEF 0xBF 0xBD`. The browser's image decoder sees garbage starting at byte 0 and bails.
+
+The current implementation uses `response.arrayBuffer()` and forwards bytes verbatim:
+
+```ts
+// packages/server/src/proxy.ts
+const body = await resp.arrayBuffer();
+return c.newResponse(body, resp.status, respHeaders);
+```
+
+This preserves the response byte-for-byte. Images render correctly, PDFs open, protobuf decodes.
+
+## Verifying
+
+The framework's own test (`packages/server/test/proxy.test.ts`) checks this with a PNG signature:
+
+```ts
+const binary = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0xff, 0xfe]);
+const fetchMock = vi.fn(
+    async () =>
+        new Response(binary, {
+            status: 200,
+            headers: { "Content-Type": "image/png" },
+        }),
+);
+
+// ... after the handler runs ...
+
+expect(new Uint8Array(capturedBuffer)).toEqual(binary);
+```
+
+If you suspect a proxy is corrupting binaries:
+
+```bash
+# Compare hashes of direct vs proxied
+curl -s https://upstream.example/image.png | sha256sum
+curl -s http://localhost:3000/api/image.png | sha256sum
+```
+
+Different hash = corruption. Same hash = the proxy is fine, look elsewhere.
+
+## When you'd hit this
+
+If you're on the current version (which uses `arrayBuffer`), you won't. This pitfall exists primarily as historical context for:
+
+- **Upgrading from an older version** — verify your binary endpoints after upgrade
+- **Building your own custom proxy logic** — if you copy from older examples, you'll reintroduce the bug
+- **Diagnosing if a third-party proxy in front of yours has the same issue** — apply the same `arrayBuffer` test against it
+
+## Custom proxies — get this right
+
+If you write your own proxy code (outside the framework's `registerProxyRoutes`), use `arrayBuffer`:
+
+```ts
+// GOOD
+app.all("/api/*", async (c) => {
+    const resp = await fetch(targetUrl);
+    const body = await resp.arrayBuffer();
+    return c.newResponse(body, resp.status, {
+        "Content-Type": resp.headers.get("Content-Type") ?? "application/octet-stream",
+    });
+});
+```
+
+```ts
+// BAD — corrupts non-UTF-8 bytes
+app.all("/api/*", async (c) => {
+    const resp = await fetch(targetUrl);
+    return c.text(await resp.text(), resp.status);
+});
+```
+
+## Streaming for large bodies
+
+For responses >10 MB, the framework's bundled proxy rejects with HTTP 502 to avoid loading them entirely into memory. If you need to support larger responses, write a streaming proxy:
+
+```ts
+app.all("/api/*", async (c) => {
+    const resp = await fetch(targetUrl);
+    return new Response(resp.body, {
+        status: resp.status,
+        headers: {
+            "Content-Type": resp.headers.get("Content-Type") ?? "application/octet-stream",
+        },
+    });
+});
+```
+
+`resp.body` is a `ReadableStream`. Returning it directly streams bytes without buffering. But you lose the size-limit guard — only do this if you trust the upstream.
+
+## The size limit lives in two places
+
+The framework enforces `MAX_RESPONSE_SIZE = 10 * 1024 * 1024` (10 MB) in two paths:
+
+1. **Runtime** (`registerProxyRoutes`): checks `Content-Length` header first, then `body.byteLength` after fetch
+2. **Generated code** (`generateProxyCode`): the inlined version for serverless emits the same two checks
+
+If you change the limit in one place, change both. The test `generated proxy code embeds the same response size limit as runtime (parity)` enforces this.
+
+## Why `Content-Length` and `byteLength` both
+
+`Content-Length` is what the upstream **claims**. `byteLength` is what actually arrived. Some upstreams send `Content-Length: 1000` but stream 10MB. Some omit `Content-Length` entirely.
+
+The double check covers both:
+
+- Fast-reject on declared `Content-Length` to avoid downloading 100MB just to reject it
+- Final reject on actual bytes received in case `Content-Length` was missing or lying
+
+## Related
+
+- [Chapter 9: Server & deployment — proxy routes](../09-server-and-deployment.md#proxy-routes)
+- The actual implementation: `packages/server/src/proxy.ts`
+- The regression test: `packages/server/test/proxy.test.ts`

package/docs/pitfalls/redirect-vs-rewrite.md

@@ -0,0 +1,147 @@
+# Pitfall: redirect vs rewrite
+
+## Symptom A — wrong URL in the address bar
+
+A guard runs `rewrite("/canonical")`, but the user sees `/canonical` in the address bar. You wanted the original URL preserved.
+
+## Symptom B — extra round-trip
+
+A guard runs `redirect("/login")`, the browser shows a flicker / network panel shows a 302 → 200 round-trip. You wanted in-process re-routing.
+
+## Symptom C — `afterLoad` rewrite seemed to issue a 301
+
+A guard in `afterLoad` returns `rewrite("/clean-url")`. The browser hits the rewrite URL, gets the canonical content, and your server logs show two requests. You expected one.
+
+## Root cause
+
+`redirect` and `rewrite` look similar but mean fundamentally different things, and `rewrite` itself behaves differently in `beforeLoad` vs `afterLoad`.
+
+| Result                            | What happens                                                             | Visible to user as                           | Use for                                           |
+| --------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------- | ------------------------------------------------- |
+| `redirect("/foo", 302)`           | HTTP 302 with `Location: /foo` (server) or `pushState("/foo")` (browser) | Address bar changes to `/foo`                | Auth gates, locale redirects, deprecated paths    |
+| `redirect("/foo", 301)`           | Same but cacheable as permanent                                          | Address bar changes; cached                  | Permanent canonicalization                        |
+| `rewrite("/foo")` in `beforeLoad` | Router resolves `/foo` instead; new match's guards + controller run      | Address bar stays original                   | A/B tests, feature-flag routing, internal aliases |
+| `rewrite("/foo")` in `afterLoad`  | `Content-Location: /foo` header; controller already ran                  | Address bar stays original; no extra request | Canonical-URL signal to crawlers; analytics dedup |
+
+## The semantic difference
+
+**Redirect** = "the user should be at a different URL." The address bar is the source of truth, and the framework tells the browser to update it.
+
+**Rewrite in `beforeLoad`** = "this URL maps to another internally." The user's URL stays; the framework picks a different controller to satisfy the request. Like Nginx's `rewrite ... last;`.
+
+**Rewrite in `afterLoad`** = "this content is also available at a canonical URL." The page already rendered (the controller already ran); the response just includes a hint via `Content-Location`. The browser does **not** follow it as a redirect — it's metadata.
+
+## Fix Symptom A — you used `redirect` when you wanted `rewrite`
+
+```ts
+// BAD — user sees /landing-v2 in address bar
+function abTestGuard(ctx: NavigationContext) {
+    if (ctx.url.pathname !== "/landing") return next();
+    return bucket(ctx) === "B" ? redirect("/landing-v2") : next();
+}
+```
+
+```ts
+// GOOD — user keeps /landing, server renders /landing-v2 internally
+function abTestGuard(ctx: NavigationContext) {
+    if (ctx.url.pathname !== "/landing") return next();
+    return bucket(ctx) === "B" ? rewrite("/landing-v2") : next();
+}
+```
+
+Same applies to mobile routing, feature flags, locale-based content swapping — anything where the user shouldn't notice the underlying URL changed.
+
+## Fix Symptom B — you used `rewrite` when you wanted `redirect`
+
+```ts
+// BAD — user remains on the protected URL; the wrong controller runs
+function authGuard(ctx: NavigationContext) {
+    if (!ctx.getCookie("token")) return rewrite("/login");
+    return next();
+}
+```
+
+If `rewrite` is used here:
+
+- The address bar stays at `/admin` (confusing — the user thinks they're already at admin)
+- A reload re-runs the login page logic but doesn't change the URL
+- Bookmarking `/admin` from this state bookmarks a broken URL
+
+```ts
+// GOOD — actually navigate to /login
+function authGuard(ctx: NavigationContext) {
+    if (!ctx.getCookie("token"))
+        return redirect("/login?next=" + encodeURIComponent(ctx.url.pathname));
+    return next();
+}
+```
+
+## Fix Symptom C — `afterLoad` rewrite is canonicalization, not 301
+
+If you actually want a 301 from `afterLoad`, use `redirect`:
+
+```ts
+afterLoad: [
+    (ctx) => {
+        if (ctx.url.search.includes("utm_")) {
+            const clean = ctx.url.pathname;
+            return redirect(clean, 301);
+        }
+        return next();
+    },
+],
+```
+
+But note: by the time `afterLoad` runs, **the controller already executed**. If `execute()` had side effects (writes, expensive computation), they happened. Use `beforeLoad` for redirects you want to fire before the work runs.
+
+If you want to ship the rendered page **and** signal "by the way, the canonical URL is /clean":
+
+```ts
+afterLoad: [
+    (ctx) => {
+        if (ctx.url.search.includes("utm_")) {
+            return rewrite(ctx.url.pathname);  // no extra request
+        }
+        return next();
+    },
+],
+```
+
+The response includes `Content-Location: /clean`. Crawlers (Google, Bing) use this for canonical resolution; analytics tools can deduplicate the variants.
+
+## The `rewrite` recursion depth limit
+
+`beforeLoad` rewrites recurse — the new URL's `beforeLoad` chain runs in full, including any rewrites it triggers. The framework caps this at **5 levels** (`MAX_SSR_REWRITE_DEPTH`) to prevent runaway loops.
+
+If you hit:
+
+```
+Error: Too many SSR rewrites (max 5): /a → /b → /c → /d → /e → /f
+```
+
+You have a guard loop. Common cause: a guard rewrites to a URL whose own guard rewrites back.
+
+```ts
+// BAD — /landing rewrites to /v2 which rewrites to /landing
+const landingGuard = (ctx) => (ctx.url.pathname === "/landing" ? rewrite("/v2") : next());
+const v2Guard = (ctx) =>
+    ctx.url.pathname === "/v2" && !ctx.getCookie("v2") ? rewrite("/landing") : next();
+```
+
+Fix the loop, not the depth limit.
+
+## Decision tree
+
+```
+Need to change what URL the user sees?
+├── Yes → redirect (302 for temporary, 301 for permanent)
+└── No, URL stays the same
+    ├── Need to swap which controller runs?    → rewrite in beforeLoad
+    ├── Already rendered; want canonical hint? → rewrite in afterLoad
+    └── Need to abort with an error?           → deny(status, message)
+```
+
+## Related
+
+- [Chapter 3: Middleware](../03-middleware.md) — the four results explained
+- The behavior change was deliberately introduced — see `packages/ssr/src/render.ts` `ssrRenderInternal` and the `rewriteUrl` field