@finesoft/front 0.5.1 → 0.5.2

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

@@ -1,200 +1,21 @@
-# 高阶：内联 proxy 代码生成
+# 进阶：代理代码生成
 
-serverless 和 edge 部署，想把 proxy 逻辑内联到函数 bundle 里 —— 不在运行时调 `registerProxyRoutes`，不带额外依赖 —— 框架暴露 `generateProxyCode`。
-
-## 用例
-
-部署到 Cloudflare Workers / Vercel Edge / AWS Lambda@Edge。每个函数有：
-
-- 紧的冷启动预算
-- 紧的冷 bundle 体积预算（Workers：1 MB 压缩后）
-- 某些运行时没有 `process.env`
-
-import proxy router 和它的支持文件（validator、Hono 集成）增字节。`generateProxyCode` **只**发出你声明的路由需要的那几行。输出自包含：几个 `app.get(...)` / `app.all(...)` 调用加一个 `_sanitizeProxyPath` helper。
-
-## 生成的输出
-
-输入：
+`generateProxyCode` 是 `@finesoft/front` 导出的构建期扩展。标准适配器已经集成声明式代理路由。业务模块需要校验、策略和作用域服务时，应使用可移植的操作与 HTTP API。
 
 ```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);
-```
-
-得到大概这样的：
-
-```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);
-    }
-});
-```
-
-所有都内联。proxy 路径不从 `@finesoft/front` import 任何东西。把这放进函数 bundle 里，跟 SSR 入口一起。
-
-## 代码生成 vs 运行时注册 怎么选
-
-| 关注点                        | 运行时（`registerProxyRoutes`） | 代码生成（`generateProxyCode`） |
-| ----------------------------- | ------------------------------- | ------------------------------- |
-| 长跑服务器（Node、Workers）   | ✅ 优先                         | ✅ 也行                         |
-| 微小 edge 函数（Lambda@Edge） | import 更重                     | ✅ 最小                         |
-| 不重新部署就更新路由          | ✅ 改配置，重启                 | ❌ 需重新部署                   |
-| 配置来自远端服务              | ✅ 支持                         | ❌ 代码生成在构建期跑           |
-| 多个 proxy 共享 helper        | ✅ 运行时共享                   | 自己去重否则代码重复            |
-
-bundle 体积重要时用代码生成。多数部署运行时路径就好。
-
-## 构建期集成
-
-典型设置：
-
-```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");
-```
-
-然后在 serverless 函数入口 import `./proxy.js`：
-
-```ts
-// dist/main.ts（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;
-```
-
-## 生成代码替你做了什么
-
-生成的 handler 强制和运行时路径同样的保证：
-
-- **SSRF 保护**：path 校验拒绝编码字符、`//` 前缀、不允许字符集外字符
-- **开放重定向保护**：`target.origin` 必须与配置的 target origin 一致
-- **10 MB 响应大小限制**：`Content-Length` 快速拒绝 + `byteLength` 实际字节检查
-- **二进制完整性**：`arrayBuffer()` 转发（不 UTF-8 解码）
-- **从环境读 auth**：请求时读 `process.env[envKey]`
-
-框架测试套件断言运行时和生成代码的**parity**：
-
-```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}`);
-});
-```
-
-你改运行时路径的大小限制，生成代码的限制锁步更新。
-
-## 注意事项
-
-### `process.env` 可能不存在
-
-生成的代码用 `typeof process !== "undefined"` 守卫。没有 `process` 的运行时（某些 edge 环境），auth 头根本不会加 —— 上游看不到 auth。
-
-像 Cloudflare Workers 用函数 arg 注入 env 而不是 `process.env` 的平台，你要：
-
-- 包一层生成代码，从 worker 的 env arg 注入 auth 头
-- 或生成后替换 auth 那段，改成平台对应的访问方式
-
-### 无重试、无熔断
-
-生成的 handler 一次 `fetch`，失败冒成 `502 Proxy request failed`。要重试 / 熔断逻辑，自己写 proxy 代码 —— `generateProxyCode` 有意最小。
-
-### 多个 proxy 共享 helper 代码
-
-`_sanitizeProxyPath` 在生成字符串顶部发一次。多个 `app.all` 共用。每个路由单独 `generateProxyCode` 然后拼接，helper 会重复 —— 一次传所有路由调用。
-
-### 生成时校验
-
-`generateProxyCode` 跑和 `registerProxyRoutes` 一样的 `validateConfig`。无效配置构建期就抛：
-
-```ts
-generateProxyCode([{ prefix: "/api", target: "file:///etc/passwd" }]);
-// Error: [proxy] target must start with "https://" or "http://": "file:///etc/passwd"
 ```
 
-抓配置错误在部署发出之前。
+返回的源码调用 `registerProxyRoutes(app, config)`。自定义生成入口需要从 `@finesoft/front` 导入 `registerProxyRoutes` 并提供 Hono `app`；标准适配器自动完成这些绑定。开发环境和生成主机共用路径校验、二进制响应与大小限制实现。它属于构建产物，不是应用启动 API。密钥值配置在主机上，路由声明变化后重新构建。`auth.envKey` 在可用时读取 `process.env`；没有 `process` 的主机可在运行时注册配置中提供 Authorization 请求头。平台包体限制及部署规则以该平台当前文档为准。
 
-## 参考
+普通应用配置 Vite 插件并使用标准适配器即可，无需把生成的 handler 源码复制到业务文件。见 [HTTP 与部署](../09-server-and-deployment.md)。
 
-- [第 9 章：服务器与部署 · proxy 路由](../09-server-and-deployment.md#proxy-路由)
-- 实现：`packages/server/src/proxy.ts`
-- parity 测试：`packages/server/test/proxy.test.ts`
+默认不跟随重定向；`followRedirects: true` 只允许目标 origin 内的跳转，最多 20 次。响应按块计数，超过 10 MiB 立即取消读取并返回 502，即使 Content-Length 缺失或不实也执行限制。

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

@@ -1,330 +1,17 @@
-# 高阶：多租户 scope
+# 请求隔离
 
-多租户应用一份部署服务多个客户，每个客户的请求要看到自己的：
+运行时自动打开、关闭调用 scope。可信主机绑定传递租户和身份，嵌套操作继承当前上下文。
 
-- 数据库连接 / API 客户端
-- 带租户 tag 的 logger / 指标
-- Feature flag / 价格 / 品牌
-- 缓存的翻译 / 内容
-
-DI 容器的子 scope 是正确的原语。本配方展示通过 `beforeLoad` 守卫接通按租户隔离。
-
-## 心智模型
-
-```
-Framework
-  └── 父 Container        ← 共享服务（HTTP 池、基础 recorder、...）
-      └── 每个请求 scope  ← 框架为每个 SSR 请求创建
-          ↑
-          └── 一个 beforeLoad 守卫注册的租户覆盖
-```
-
-每请求 scope 由框架自动创建。你的守卫在它之上注册租户级覆盖。你没覆盖的东西都回退到父。
-
-## 步骤 1：识别租户
-
-这是你的业务逻辑。常见来源：
-
-- **子域**：`acme.myapp.com` → `acme`
-- **路径前缀**：`/t/acme/...` → `acme`
-- **头**：`X-Tenant-Id: acme`
-- **鉴权用户**：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;
-}
-```
-
-## 步骤 2:加载租户配置
-
-```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)!;
-
-    // 从配置存储读 —— 文件、DB、KV
-    const config = await loadFromStore(tenantId);
-    if (!config) return null;
-
-    cache.set(tenantId, config);
-    return config;
-}
-```
-
-真实实现要在配置更新时让缓存失效。多数应用按定时器刷或通过 webhook 即可。
-
-## 步骤 3：在守卫里注册租户服务
-
-```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");
-
-    // 在请求 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,
-    }));
-
-    // 用租户上下文装饰父的 recorder
-    const baseRecorder = scope.parent!.resolve(DEP_KEYS.EVENT_RECORDER);
-    scope.register(
-        DEP_KEYS.EVENT_RECORDER,
-        () => new WithFieldsRecorder(baseRecorder, [{ getFields: () => ({ tenantId }) }]),
-    );
-
-    return next();
-}
-```
-
-要点：
-
-- **scope 已经由框架创建。** 你在 `ctx.container` 上注册 —— 那就是请求 scope。
-- **回退自动。** 这里没注册的会从父容器 resolve。
-- **装饰而不替换。** recorder 用租户字段包起来而不是替换 —— 基础行为（HTTP 传输、批处理）保持原样。
-
-## 步骤 4：全局安装守卫
-
-```ts
-// src/bootstrap.ts
-import { type Framework, defineRoutes } from "@finesoft/front";
-import { tenantGuard } from "./lib/guards/tenant";
-// ... 其他 import
-
-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` 在任何路由级守卫之前跑，所以任何 Controller 跑时租户 scope 都已经设好。
-
-## 步骤 5：Controller 透明地拿到正确的服务
-
-```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"); // 租户专属客户端
-
-        const usage = await api.getUsage();
-        const invoices = await api.getInvoices();
-
-        return {
-            kind: "billing",
-            tenantName: config.displayName,
-            usage,
-            invoices,
-        };
-    }
-}
-```
-
-Controller 不知道租户存在 —— 它只 resolve `userApi`，拿到本请求对应的那个。
-
-## 跨租户禁止
-
-防 A 租户认证的用户访问 B 租户数据：
-
-```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();
-}
-
-// 在 tenantGuard 之后应用：
-framework.middleware.use("beforeLoad", tenantGuard);
-framework.middleware.use("beforeLoad", sameTenantGuard);
-```
-
-守卫顺序重要 —— `tenantGuard` 必须先注册 `tenantConfig`，`sameTenantGuard` 才能读到。
-
-## Hydration 考虑
-
-租户配置含 `featureFlags`，两端都读。框架的 `PrefetchedIntents` 序列化处理这个 —— 浏览器拿到服务端看到的同样 flag 值，所以客户端读保持一致。
-
-租户配置本身**不**自动序列化。view 要显示 `tenantConfig.displayName` 的话，Controller 应该把它放进 `Page`：
-
-```ts
-async execute(_params, container) {
-    const config = container.resolve<TenantConfig>("tenantConfig");
-    return {
-        kind: "home",
-        tenant: {
-            id: config.tenantId,
-            displayName: config.displayName,
-        },
-        // ...
-    };
-}
-```
-
-`Page` 被序列化所以能跨 SSR → CSR 边界。完整 `TenantConfig`（含秘密）永不应该出现在 `Page` 里。
-
-## 浏览器端考虑
-
-`tenantGuard` 在浏览器也跑 —— 首次导航和每次后续导航。仅浏览器应用（`renderMode: "csr"`）只在这跑。
-
-但浏览器不能安全地 resolve `apiToken` 这种秘密。两种方法：
-
-**方法 1：服务器代理所有 API 调用。** 浏览器打 `/api/users`（你的 proxy），它转发到 `${upstreamUrl}/users` 并从 `process.env[apiTokenEnvKey]` 注入 auth 头。浏览器从不见 token。
-
-**方法 2：短期 session token。** 服务器颁发 scope 到租户的 JWT；浏览器用它直接调上游。token 轮换由你的 auth 层处理。
-
-多数应用走方法 1。框架的 proxy router 就是为这个设计的。
-
-## 注意事项
-
-### 别跨请求缓存租户 scope
+## Invocation / 调用
 
 ```ts
-// 不好
-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);
-    }
-    // 用 scope...
-}
-```
-
-每个请求需要自己的 scope —— 即使同租户 —— 因为：
-
-- 其他守卫加请求专属覆盖（auth、trace id），不该跨请求泄漏
-- scope 持有有状态服务的 resolve 实例；跨请求共享破坏隔离
-
-租户**配置**可以缓存。租户**scope**不行。
-
-### 共享服务实例要小心
-
-把 `UserApi` 实例缓存到模块级而不是注册工厂，所有请求共享状态：
-
-```ts
-// 不好
-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;
-});
-```
-
-`UserApi` 有任何请求级状态（捕获请求专属值的拦截器闭包）就跨租户泄。注册新鲜工厂；让容器按 scope 缓存。
-
-## 测试
-
-```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);
 ```
 
-## 参考
-
-- [第 7 章：DI 容器](../07-di-container.md) —— scope 和回退 resolve
-- [第 3 章：中间件](../03-middleware.md) —— 全局守卫
-- [陷阱：container scope 泄漏](../pitfalls/container-scope-leak.md) —— 缓存 scope 会出什么问题
+每请求资源使用 `provide({ token, lifetime: "scope", create, dispose })`。并发初始化去重，初始化失败可重试。runtime 生命周期不能依赖请求生命周期值。外部传入值默认由外部管理，创建值按依赖顺序释放。command 不自动重试或缓存，取消也不会回滚已生效修改。