@finesoft/front 0.5.1 → 0.5.2

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

@@ -1,200 +1,21 @@
-# Advanced: inline proxy codegen
+# Advanced: proxy code generation
 
-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:
+`generateProxyCode` is a build-time extension exported from `@finesoft/front`. Standard adapters already integrate declared proxy routes. Application business modules should use the portable operation/HTTP APIs when they need validation, policies and scoped services.
 
 ```ts
 import { generateProxyCode } from "@finesoft/front";
-
-const code = generateProxyCode([
+const source = 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.
+The returned source calls `registerProxyRoutes(app, config)`. A custom generated entry must import `registerProxyRoutes` from `@finesoft/front` and provide its Hono `app`; standard adapters do this automatically. Both development and generated hosts use the same path, binary-response and size-limit implementation. Treat the source as generated build output, not an application startup API. Configure secret values on the host and rebuild when declared routes change. `auth.envKey` reads `process.env` when available; hosts without `process` can supply an Authorization header in their runtime registration config. Platform bundle limits and deployment rules belong to that platform's current documentation.
 
-## Related
+For ordinary applications, configure the Vite plugin and use the standard adapter rather than copying generated handler source into application files. See [HTTP and deployment](../09-server-and-deployment.md).
 
-- [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`
+Redirects are manual by default; `followRedirects: true` follows at most 20 hops within the configured origin. Responses are counted as chunks arrive and cancelled above 10 MiB with a 502, even when Content-Length is missing or false.

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

@@ -1,330 +1,17 @@
-# Advanced: multi-tenant scopes
+# Request isolation
 
-A multi-tenant app serves multiple customers from one deployment, but each customer's request must see their own:
+Runtime execution opens and closes an invocation scope automatically. Trusted host bindings carry tenant/identity; nested operations inherit the current context.
 
-- 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
+## Invocation / 调用
 
 ```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 });
-    });
+// Derive these values from trusted authentication at the host boundary.
+await runtime.execute(operation, input, {
+    identity: authenticatedUser,
+    bindings: { tenant: tenantId },
+    signal: request.signal,
 });
+// Inside an operation: await context.execute(otherOperation, input);
 ```
 
-## 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
+Use `provide({ token, lifetime: "scope", create, dispose })` for per-request resources. Concurrent initialization deduplicates and a failed initialization may retry. Runtime-scoped providers cannot depend on request-scoped values. Externally supplied values remain external unless owned explicitly; created values are released in dependency order. A command is not retried or cached automatically; cancellation does not roll back an already applied mutation.