@finesoft/front 0.1.76 → 0.1.77

package/docs/advanced/inline-proxy-codegen.md

@@ -0,0 +1,200 @@
+# Advanced: inline proxy codegen
+
+For serverless and edge deployments where you want proxy logic inlined into the function bundle — no runtime call to `registerProxyRoutes`, no extra dependencies — the framework exposes `generateProxyCode`.
+
+## Use case
+
+You're deploying to Cloudflare Workers / Vercel Edge / AWS Lambda@Edge. Each function has:
+
+- Tight cold-start budget
+- Cold-bundle-size budget (Workers: 1 MB compressed)
+- No `process.env` in some runtimes
+
+Importing the proxy router and its support files (validators, Hono integration) adds bytes. `generateProxyCode` emits **only** the lines you need for the routes you declared. The output is self-contained: a few `app.get(...)` / `app.all(...)` calls plus a single `_sanitizeProxyPath` helper.
+
+## Generated output
+
+Given this input:
+
+```ts
+import { generateProxyCode } from "@finesoft/front";
+
+const code = generateProxyCode([
+    {
+        prefix: "/api",
+        target: "https://upstream.example",
+        headers: { "X-App": "myapp" },
+        auth: { type: "bearer", envKey: "API_TOKEN" },
+        cache: "max-age=60",
+    },
+]);
+
+console.log(code);
+```
+
+You get something like:
+
+```js
+// ─── 框架声明式代理路由 ───
+function _sanitizeProxyPath(raw) {
+    if (raw.length > 2048) return null;
+    try {
+        if (decodeURIComponent(raw) !== raw) return null;
+    } catch {
+        return null;
+    }
+    if (raw.startsWith("//")) return null;
+    if (!/^[/\w.\-~%:@!$&'()*+,;=]*$/.test(raw)) return null;
+    return raw.startsWith("/") ? raw : "/" + raw;
+}
+
+app.all("/api/*", async (c) => {
+    const _sub = _sanitizeProxyPath(c.req.path.replace("/api", ""));
+    if (!_sub) return c.text("Invalid path", 400);
+    const _target = new URL(_sub, "https://upstream.example");
+    if (_target.origin !== "https://upstream.example") return c.text("Invalid proxy target", 400);
+    const _reqUrl = new URL(c.req.url);
+    _reqUrl.searchParams.forEach((v, k) => _target.searchParams.set(k, v));
+    const _headers = { "X-App": "myapp" };
+    const _token =
+        (typeof process !== "undefined" && process.env && process.env["API_TOKEN"]) || "";
+    if (_token) _headers.Authorization = "Bearer " + _token;
+    try {
+        const _resp = await fetch(_target.toString(), { headers: _headers, redirect: "manual" });
+        const _cl = _resp.headers.get("Content-Length");
+        if (_cl && parseInt(_cl, 10) > 10485760) {
+            return c.text("Proxy response too large", 502);
+        }
+        const _body = await _resp.arrayBuffer();
+        if (_body.byteLength > 10485760) {
+            return c.text("Proxy response too large", 502);
+        }
+        const _rh = { "Content-Type": _resp.headers.get("Content-Type") || "application/json" };
+        if ("max-age=60") _rh["Cache-Control"] = "max-age=60";
+        return c.newResponse(_body, _resp.status, _rh);
+    } catch (_e) {
+        console.error("[Proxy /api]", _e);
+        return c.json({ error: "Proxy request failed" }, 502);
+    }
+});
+```
+
+Everything is inline. No imports from `@finesoft/front` for the proxy path. Drop this into your function bundle alongside the SSR entry.
+
+## When to use codegen vs runtime registration
+
+| Concern                                   | Runtime (`registerProxyRoutes`) | Codegen (`generateProxyCode`)               |
+| ----------------------------------------- | ------------------------------- | ------------------------------------------- |
+| Long-lived server (Node, Workers)         | ✅ preferred                    | ✅ also fine                                |
+| Tiny edge functions (Lambda@Edge)         | Heavier import                  | ✅ minimal                                  |
+| Need to update routes without redeploying | ✅ change config, restart       | ❌ redeploy required                        |
+| Config from a remote service              | ✅ supported                    | ❌ codegen runs at build time               |
+| Multiple proxies sharing helpers          | ✅ shared at runtime            | Code duplication unless you dedupe yourself |
+
+Use codegen specifically when bundle size matters. For most deployments, the runtime path is fine.
+
+## Build-time integration
+
+A typical setup:
+
+```ts
+// scripts/build-proxy.mjs
+import { generateProxyCode } from "@finesoft/front";
+import { writeFile } from "node:fs/promises";
+
+const code = generateProxyCode([
+    { prefix: "/api/users", target: "https://users.internal" },
+    { prefix: "/api/products", target: "https://products.internal", cache: "max-age=30" },
+    {
+        prefix: "/api/orders",
+        target: "https://orders.internal",
+        auth: { type: "bearer", envKey: "ORDERS_TOKEN" },
+    },
+]);
+
+const wrapper = `
+import { Hono } from "hono";
+const app = new Hono();
+
+${code}
+
+export default app;
+`;
+
+await writeFile("dist/proxy.js", wrapper, "utf8");
+```
+
+Then import `./proxy.js` from your serverless function entry:
+
+```ts
+// dist/main.ts (for Cloudflare Worker)
+import proxyApp from "./proxy.js";
+import ssrApp from "./ssr-bundle.js";
+
+const app = new Hono();
+app.route("/", proxyApp);
+app.route("/", ssrApp);
+
+export default app;
+```
+
+## What the generated code does for you
+
+The generated handler enforces the same guarantees as the runtime path:
+
+- **SSRF protection**: path validation rejects encoded chars, `//` prefix, non-allowed characters
+- **Open-redirect protection**: `target.origin` must match the configured target's origin
+- **10 MB response size limit**: `Content-Length` fast-reject + `byteLength` actual-bytes check
+- **Binary integrity**: `arrayBuffer()` forwarding (no UTF-8 decoding)
+- **Auth from env**: reads `process.env[envKey]` at request time
+
+The framework's test suite asserts **parity** between runtime and generated code with these checks:
+
+```ts
+// packages/server/test/proxy.test.ts
+test("generated proxy code embeds the same response size limit as runtime (parity)", () => {
+    const code = generateProxyCode([{ prefix: "/api", target: "https://upstream.example" }]);
+
+    const MAX = String(10 * 1024 * 1024);
+    expect(code).toContain(`parseInt(_cl, 10) > ${MAX}`);
+    expect(code).toContain(`_body.byteLength > ${MAX}`);
+});
+```
+
+If you patch the runtime path's size limit, the generated code's limit is updated in lockstep.
+
+## Caveats
+
+### `process.env` may not exist
+
+The generated code guards with `typeof process !== "undefined"`. On runtimes without `process` (some edge environments), the auth header is simply not added — the upstream sees no auth.
+
+For platforms like Cloudflare Workers that inject env via function args instead of `process.env`, you'll need to either:
+
+- Wrap the generated code to inject the auth header from the worker's env arg
+- Replace the auth section after generation with the platform-appropriate access
+
+### No retries, no breakers
+
+The generated handler does one `fetch` and bubbles failures up as `502 Proxy request failed`. For retry / breaker logic, write your own proxy code — `generateProxyCode` is intentionally minimal.
+
+### Multiple proxies share helper code
+
+`_sanitizeProxyPath` is emitted once at the top of the generated string. Multiple `app.all` calls share it. If you `generateProxyCode` separately for each route and concatenate, you'll get the helper repeated — call it once with all routes.
+
+### Validation at generation time
+
+`generateProxyCode` runs the same `validateConfig` as `registerProxyRoutes`. Invalid configs throw at build time:
+
+```ts
+generateProxyCode([{ prefix: "/api", target: "file:///etc/passwd" }]);
+// Error: [proxy] target must start with "https://" or "http://": "file:///etc/passwd"
+```
+
+This catches config errors before the deploy ships.
+
+## Related
+
+- [Chapter 9: Server & deployment — proxy routes](../09-server-and-deployment.md#proxy-routes)
+- The implementation: `packages/server/src/proxy.ts`
+- The parity test: `packages/server/test/proxy.test.ts`

package/docs/advanced/multi-tenant-scopes.md

@@ -0,0 +1,330 @@
+# Advanced: multi-tenant scopes
+
+A multi-tenant app serves multiple customers from one deployment, but each customer's request must see their own:
+
+- Database connection / API client
+- Logger / metrics tagged with the tenant
+- Feature flags / pricing / branding
+- Cached translations / content
+
+The DI container's child scopes are the right primitive. This recipe shows how to wire per-tenant isolation through a `beforeLoad` guard.
+
+## Mental model
+
+```
+Framework
+  └── parent Container        ← shared services (HTTP pool, base recorder, ...)
+      └── per-request scope   ← framework creates this for every SSR request
+          ↑
+          └── tenant overrides registered by a beforeLoad guard
+```
+
+The per-request scope is created by the framework automatically. Your guard registers tenant-specific overrides on top. Anything you don't override falls through to the parent.
+
+## Step 1: identify the tenant
+
+This is your business logic. Common sources:
+
+- **Subdomain**: `acme.myapp.com` → `acme`
+- **Path prefix**: `/t/acme/...` → `acme`
+- **Header**: `X-Tenant-Id: acme`
+- **Authenticated user**: cookie → session → tenant
+
+```ts
+// src/lib/tenants/resolve.ts
+import type { NavigationContext } from "@finesoft/front";
+
+export function resolveTenant(ctx: NavigationContext): string | null {
+    const host = ctx.url.hostname;
+    const sub = host.split(".")[0];
+    if (sub && sub !== "www" && sub !== "myapp") return sub;
+    return null;
+}
+```
+
+## Step 2: load tenant config
+
+```ts
+// src/lib/tenants/config.ts
+export interface TenantConfig {
+    tenantId: string;
+    displayName: string;
+    upstreamUrl: string;
+    apiToken: string;
+    featureFlags: Record<string, unknown>;
+    locale: string;
+}
+
+const cache = new Map<string, TenantConfig>();
+
+export async function getTenantConfig(tenantId: string): Promise<TenantConfig | null> {
+    if (cache.has(tenantId)) return cache.get(tenantId)!;
+
+    // Load from your config store — file, DB, KV
+    const config = await loadFromStore(tenantId);
+    if (!config) return null;
+
+    cache.set(tenantId, config);
+    return config;
+}
+```
+
+A real implementation would have cache invalidation on config updates. For most apps, refresh on a timer or via a webhook is enough.
+
+## Step 3: register tenant services in a guard
+
+```ts
+// src/lib/guards/tenant.ts
+import { deny, next, type NavigationContext, DEP_KEYS } from "@finesoft/front";
+import { resolveTenant } from "../tenants/resolve";
+import { getTenantConfig } from "../tenants/config";
+import { UserApi } from "../api/user";
+import { WithFieldsRecorder } from "@finesoft/front";
+
+export async function tenantGuard(ctx: NavigationContext) {
+    const tenantId = resolveTenant(ctx);
+    if (!tenantId) return deny(404, "Unknown tenant");
+
+    const config = await getTenantConfig(tenantId);
+    if (!config) return deny(404, "Tenant not found");
+
+    // Register tenant-specific services on the request scope
+    const scope = ctx.container;
+    scope.register("tenantConfig", () => config);
+
+    scope.register(
+        "userApi",
+        () =>
+            new UserApi({
+                baseUrl: config.upstreamUrl,
+                defaultHeaders: { Authorization: `Bearer ${config.apiToken}` },
+            }),
+    );
+
+    scope.register(DEP_KEYS.FEATURE_FLAGS, () => ({
+        get: (key, fallback) => config.featureFlags[key] ?? fallback,
+    }));
+
+    // Decorate the parent's recorder with tenant context
+    const baseRecorder = scope.parent!.resolve(DEP_KEYS.EVENT_RECORDER);
+    scope.register(
+        DEP_KEYS.EVENT_RECORDER,
+        () => new WithFieldsRecorder(baseRecorder, [{ getFields: () => ({ tenantId }) }]),
+    );
+
+    return next();
+}
+```
+
+Key insights:
+
+- **The scope is already created by the framework.** You register on `ctx.container` — that's the request scope.
+- **Fall-through is automatic.** Anything not registered here resolves from the parent container.
+- **Decorate, don't replace.** The recorder is wrapped with tenant fields rather than replaced — base behavior (HTTP transmission, batching) stays in place.
+
+## Step 4: install the guard globally
+
+```ts
+// src/bootstrap.ts
+import { type Framework, defineRoutes } from "@finesoft/front";
+import { tenantGuard } from "./lib/guards/tenant";
+// ... other imports
+
+export function bootstrap(framework: Framework): void {
+    framework.middleware.use("beforeLoad", tenantGuard);
+
+    defineRoutes(framework, [
+        { path: "/", intentId: "home", controller: new HomeController() },
+        { path: "/billing", intentId: "billing", controller: new BillingController() },
+        // ...
+    ]);
+}
+```
+
+`tenantGuard` runs before any route-specific guard, so by the time any controller executes, the tenant scope is set up.
+
+## Step 5: controllers transparently get the right services
+
+```ts
+// src/controllers/billing.ts
+export class BillingController extends BaseController<{}, BillingPage> {
+    readonly intentId = "billing";
+
+    async execute(_params, container) {
+        const config = container.resolve<TenantConfig>("tenantConfig");
+        const api = container.resolve<UserApi>("userApi"); // tenant-specific client
+
+        const usage = await api.getUsage();
+        const invoices = await api.getInvoices();
+
+        return {
+            kind: "billing",
+            tenantName: config.displayName,
+            usage,
+            invoices,
+        };
+    }
+}
+```
+
+The controller doesn't know about tenants — it just resolves `userApi` and gets the right one for this request.
+
+## Cross-tenant prohibitions
+
+To prevent a user authenticated for tenant A from accessing tenant B's data:
+
+```ts
+async function sameTenantGuard(ctx: NavigationContext) {
+    const session = await ctx.container.resolve<SessionService>("session").current();
+    const requestedTenant = ctx.container.resolve<TenantConfig>("tenantConfig").tenantId;
+
+    if (!session) return redirect("/login");
+    if (session.tenantId !== requestedTenant) return deny(403, "Cross-tenant access forbidden");
+
+    return next();
+}
+
+// Apply after tenantGuard:
+framework.middleware.use("beforeLoad", tenantGuard);
+framework.middleware.use("beforeLoad", sameTenantGuard);
+```
+
+Guard order matters — `tenantGuard` must register `tenantConfig` before `sameTenantGuard` reads it.
+
+## Hydration considerations
+
+Tenant configs include `featureFlags`, which are read on both server and client. The framework's `PrefetchedIntents` serialization handles this — the browser receives the same flag values the server saw, so client-side reads stay consistent.
+
+Tenant config itself is **not** automatically serialized. If your view needs to display `tenantConfig.displayName`, the controller should include it in the `Page` object:
+
+```ts
+async execute(_params, container) {
+    const config = container.resolve<TenantConfig>("tenantConfig");
+    return {
+        kind: "home",
+        tenant: {
+            id: config.tenantId,
+            displayName: config.displayName,
+        },
+        // ...
+    };
+}
+```
+
+The `Page` is serialized, so it survives the SSR → CSR boundary. The full `TenantConfig` (with secrets) should never end up in a `Page`.
+
+## Browser-side considerations
+
+`tenantGuard` runs on the browser too — on initial navigation and on every subsequent navigation. For browser-only apps (`renderMode: "csr"`), this is the only time it runs.
+
+But the browser can't safely resolve secrets like `apiToken`. Two approaches:
+
+**Approach 1: server proxies all API calls.** The browser hits `/api/users` (your proxy), which forwards to `${upstreamUrl}/users` with the auth header injected from `process.env[apiTokenEnvKey]`. The browser never sees the token.
+
+**Approach 2: short-lived session token.** The server issues a JWT scoped to the tenant; the browser uses it for direct upstream calls. Token rotation handled by your auth layer.
+
+Most apps go with approach 1. The framework's proxy router is designed for it.
+
+## Caveats
+
+### Don't cache tenant scopes across requests
+
+```ts
+// BAD
+const tenantScopeCache = new Map<string, Container>();
+
+async function tenantGuard(ctx) {
+    let scope = tenantScopeCache.get(tenantId);
+    if (!scope) {
+        scope = framework.container.createScope();
+        tenantScopeCache.set(tenantId, scope);
+    }
+    // Use scope...
+}
+```
+
+Each request needs its own scope — even for the same tenant — because:
+
+- Other guards add request-specific overrides (auth, trace id) that shouldn't leak across requests
+- The scope holds resolved instances of stateful services; sharing them across requests breaks isolation
+
+Tenant **config** can be cached. Tenant **scope** cannot.
+
+### Be careful with shared service instances
+
+If you cache the `UserApi` instance at module level instead of registering a factory, all requests share state:
+
+```ts
+// BAD
+const apiByTenant = new Map<string, UserApi>();
+scope.register("userApi", () => {
+    let api = apiByTenant.get(tenantId);
+    if (!api) {
+        api = new UserApi({ baseUrl: config.upstreamUrl });
+        apiByTenant.set(tenantId, api);
+    }
+    return api;
+});
+```
+
+If `UserApi` has any request-scoped state (interceptors that capture closures over request-specific values), they'll bleed across tenants. Register a fresh factory; let the container cache it per scope.
+
+## Testing
+
+```ts
+import { describe, test, expect, vi, afterEach } from "vite-plus/test";
+import { Container } from "@finesoft/front";
+import { tenantGuard } from "./tenant";
+
+afterEach(() => vi.restoreAllMocks());
+
+describe("tenantGuard", () => {
+    test("registers tenant services for known tenant", async () => {
+        const parent = new Container();
+        const scope = parent.createScope();
+
+        vi.spyOn(await import("../tenants/config"), "getTenantConfig").mockResolvedValue({
+            tenantId: "acme",
+            displayName: "Acme Co",
+            upstreamUrl: "https://acme.example",
+            apiToken: "token-123",
+            featureFlags: { darkMode: true },
+            locale: "en-US",
+        });
+
+        const ctx = {
+            url: new URL("https://acme.myapp.com/"),
+            container: scope,
+            intent: { intentId: "home", params: {} },
+            getCookie: () => null,
+            getHeader: () => null,
+            isSsr: true,
+        };
+
+        const result = await tenantGuard(ctx as any);
+
+        expect(result).toEqual({ kind: "next" });
+        expect(scope.resolve("tenantConfig")).toMatchObject({ tenantId: "acme" });
+    });
+
+    test("denies unknown tenant", async () => {
+        const ctx = {
+            url: new URL("https://unknown.myapp.com/"),
+            container: new Container(),
+            intent: { intentId: "home", params: {} },
+            getCookie: () => null,
+            getHeader: () => null,
+            isSsr: true,
+        };
+
+        const result = await tenantGuard(ctx as any);
+        expect(result).toMatchObject({ kind: "deny", status: 404 });
+    });
+});
+```
+
+## Related
+
+- [Chapter 7: DI container](../07-di-container.md) — scopes and fallback resolution
+- [Chapter 3: Middleware](../03-middleware.md) — global guards
+- [Pitfall: container scope leak](../pitfalls/container-scope-leak.md) — what goes wrong if you cache scopes