@finesoft/front 0.1.76 → 0.1.77

package/docs/zh/advanced/custom-event-recorder.md

@@ -0,0 +1,318 @@
+# 高阶：自定义 event recorder
+
+构建生产级的 `EventRecorder`，做批处理、重试、跨导航存活。本配方假设你已经读了[第 8 章：可观测性](../08-observability.md)。
+
+## 目标
+
+好 recorder 的特性：
+
+- **不阻塞。** `record()` 同步返回；传输后台进行。
+- **批处理。** 每 N 个事件或 T 秒一个 HTTP 请求，不是每个事件一个。
+- **跨导航存活。** unload 时通过 `sendBeacon` flush 待发事件。
+- **优雅降级。** 网络失败不让应用崩；发不出去的事件不无限堆积。
+- **生命周期感知。** `destroy()` flush 所有待发事件后销毁。
+
+## 骨架
+
+```ts
+// src/lib/recorders/http-recorder.ts
+import type { EventRecorder, EventRecord } from "@finesoft/front";
+
+export interface HttpRecorderOptions {
+    endpoint: string;
+    batchSize?: number;
+    flushIntervalMs?: number;
+    maxQueueSize?: number;
+}
+
+export class HttpEventRecorder implements EventRecorder {
+    private queue: EventRecord[] = [];
+    private timer: ReturnType<typeof setInterval> | null = null;
+    private flushing = false;
+    private readonly opts: Required<HttpRecorderOptions>;
+
+    constructor(options: HttpRecorderOptions) {
+        this.opts = {
+            batchSize: 50,
+            flushIntervalMs: 5000,
+            maxQueueSize: 1000,
+            ...options,
+        };
+
+        if (typeof window !== "undefined") {
+            this.timer = setInterval(() => this.flush(), this.opts.flushIntervalMs);
+            window.addEventListener("pagehide", this.beaconFlush);
+            window.addEventListener("beforeunload", this.beaconFlush);
+        }
+    }
+
+    record(event: EventRecord): void {
+        if (this.queue.length >= this.opts.maxQueueSize) {
+            // 溢出保护 —— 丢最旧，控内存
+            this.queue.shift();
+        }
+        this.queue.push(event);
+        if (this.queue.length >= this.opts.batchSize) {
+            void this.flush();
+        }
+    }
+
+    destroy(): void {
+        if (this.timer) clearInterval(this.timer);
+        if (typeof window !== "undefined") {
+            window.removeEventListener("pagehide", this.beaconFlush);
+            window.removeEventListener("beforeunload", this.beaconFlush);
+        }
+        this.beaconFlush();
+    }
+
+    private async flush(): Promise<void> {
+        if (this.flushing || this.queue.length === 0) return;
+        this.flushing = true;
+        const batch = this.queue.splice(0, this.opts.batchSize);
+
+        try {
+            const resp = await fetch(this.opts.endpoint, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(batch),
+                keepalive: true,
+            });
+            if (!resp.ok) {
+                // 4xx —— 丢。5xx —— 放回队头。
+                if (resp.status >= 500) this.queue.unshift(...batch);
+            }
+        } catch {
+            // 网络失败 —— 放回队头
+            this.queue.unshift(...batch);
+        } finally {
+            this.flushing = false;
+        }
+    }
+
+    private beaconFlush = (): void => {
+        if (this.queue.length === 0) return;
+        if (typeof navigator === "undefined" || !navigator.sendBeacon) return;
+        const batch = this.queue.splice(0, this.queue.length);
+        navigator.sendBeacon(this.opts.endpoint, JSON.stringify(batch));
+    };
+}
+```
+
+## 每块为什么存在
+
+### `keepalive: true`
+
+告诉浏览器即使页面正在导航离开也要完成请求。有 body 大小上限（~64 KB）但能跨导航。配 `sendBeacon` 处理 unload —— beacon 更小更可靠。
+
+### `pagehide` 和 `beforeunload`
+
+`pagehide` 在页面进 bfcache（前进/后退）时触发。`beforeunload` 在常规导航/关闭时触发。两者都该 flush 待发事件。有些浏览器只触发一个，所以两个都监听。
+
+### `keepalive` vs `sendBeacon`
+
+| 方法                   | body 上限 | 返回响应？ | 时机                   |
+| ---------------------- | --------- | ---------- | ---------------------- |
+| `fetch(..keepalive)`   | ~64KB     | 是         | 页面生命中的周期 flush |
+| `navigator.sendBeacon` | ~64KB     | 否         | unload 时最终 flush    |
+
+两个都用：周期 `fetch` 看成功/失败，`sendBeacon` 作为最后逃生口。
+
+### 5xx 放回，4xx 丢
+
+5xx 是服务端错 —— 之后重试。4xx 是你错 —— 重试无用，无限重试会冲垮服务器。丢 batch 继续。
+
+### 溢出保护
+
+网络挂几小时，应用还在发事件，队列无界增长。`maxQueueSize` 限制；新事件来时最旧的掉。这是用完整性换内存安全 —— 按你能丢多少 vs 能用多少内存挑大小。
+
+## 接上
+
+```ts
+// src/main.ts
+import { startBrowserApp, CompositeEventRecorder, ConsoleEventRecorder } from "@finesoft/front/browser";
+import { bootstrap } from "./bootstrap";
+import { HttpEventRecorder } from "./lib/recorders/http-recorder";
+
+startBrowserApp({
+    bootstrap,
+    frameworkConfig: {
+        eventRecorder: new CompositeEventRecorder([
+            new ConsoleEventRecorder(),
+            new HttpEventRecorder({
+                endpoint: "/api/events",
+                batchSize: 50,
+                flushIntervalMs: 5000,
+            }),
+        ]),
+    },
+    mount: /* ... */,
+});
+```
+
+`CompositeEventRecorder` 包两个，事件**同时**送到 console（dev 可见）**和**后端。
+
+## 加横切字段
+
+用 `WithFieldsRecorder` 装饰附加 session 级字段：
+
+```ts
+import { WithFieldsRecorder, type FieldProvider } from "@finesoft/front";
+
+const sessionFields: FieldProvider = {
+    getFields: () => ({
+        sessionId: getSessionId(),
+        appVersion: __APP_VERSION__,
+        userAgent: navigator.userAgent,
+    }),
+};
+
+const userFields: FieldProvider = {
+    getFields: () => {
+        const user = getCurrentUser();
+        return user ? { userId: user.id, role: user.role } : {};
+    },
+};
+
+new WithFieldsRecorder(new HttpEventRecorder({ endpoint: "/api/events" }), [
+    sessionFields,
+    userFields,
+]);
+```
+
+`getFields` **每个事件**跑一次，所以事件之间的用户状态变化能正确反映。
+
+## 服务端记录
+
+框架对每个 SSR 请求记录 `PageView`。要在服务端捕获：
+
+```ts
+// src/ssr.ts
+import { createSSRRender } from "@finesoft/front";
+import { HttpEventRecorder } from "./lib/recorders/http-recorder";
+
+// 跨所有 SSR 请求共享的单实例 recorder
+const serverRecorder = new HttpEventRecorder({
+    endpoint: "https://internal-events.example/v1/events",
+    batchSize: 100, // 服务端更激进的批量
+    flushIntervalMs: 1000,
+});
+
+export const render = createSSRRender({
+    bootstrap,
+    frameworkConfig: {
+        eventRecorder: serverRecorder,
+    },
+    /* ... */
+});
+
+process.on("SIGTERM", () => serverRecorder.destroy());
+```
+
+服务端 recorder 应该：
+
+- 跨请求共享单实例（别按请求构造）
+- 用大 batch / 长 flush 间隔（没 UI 要阻塞）
+- 把 `destroy()` 接进优雅关闭，在途事件能 flush
+
+## 与 Sentry / Datadog 集成
+
+同时用 `ReportCallback`（送 `warn`/`error` 到 Sentry）和 `EventRecorder`（送结构化事件到后端）的话，分开：
+
+```ts
+Framework.create({
+    reportCallback: (level, category, args) => {
+        Sentry.captureMessage(`[${category}] ${args.join(" ")}`, level);
+    },
+    eventRecorder: new CompositeEventRecorder([
+        new HttpEventRecorder({ endpoint: "/api/events" }),
+        // 可选：也转给 Datadog
+        new DatadogEventRecorder({ apiKey: env.DD_API_KEY }),
+    ]),
+});
+```
+
+不同 sink 不同用途 —— 错误送 Sentry triage，结构化事件送数据仓库做分析。别想着一个 recorder 包办两件。
+
+## 采样
+
+高流量应用要采样事件：
+
+```ts
+class SamplingRecorder implements EventRecorder {
+    constructor(
+        private inner: EventRecorder,
+        private rate: number,
+    ) {}
+    record(event: EventRecord): void {
+        if (Math.random() < this.rate) this.inner.record(event);
+    }
+    destroy(): void {
+        this.inner.destroy?.();
+    }
+}
+
+new SamplingRecorder(new HttpEventRecorder({ endpoint: "/api/events" }), 0.1);
+// 记 10% 的事件
+```
+
+在 recorder 层采样，不在调用点 —— 调用点不该知道是否被采样。
+
+## 测试
+
+```ts
+import { afterEach, describe, expect, test, vi } from "vite-plus/test";
+import { HttpEventRecorder } from "./http-recorder";
+
+afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+});
+
+describe("HttpEventRecorder", () => {
+    test("flushes when batch fills", async () => {
+        const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 200 }));
+        vi.stubGlobal("fetch", fetchMock);
+
+        const recorder = new HttpEventRecorder({
+            endpoint: "/api/events",
+            batchSize: 3,
+            flushIntervalMs: 60_000,
+        });
+
+        recorder.record({ name: "A", fields: {} });
+        recorder.record({ name: "B", fields: {} });
+        recorder.record({ name: "C", fields: {} });
+
+        await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1));
+        expect(JSON.parse(fetchMock.mock.calls[0][1].body)).toHaveLength(3);
+    });
+
+    test("re-queues batch on 5xx", async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(new Response(null, { status: 503 }))
+            .mockResolvedValueOnce(new Response(null, { status: 200 }));
+        vi.stubGlobal("fetch", fetchMock);
+
+        const recorder = new HttpEventRecorder({
+            endpoint: "/api/events",
+            batchSize: 1,
+            flushIntervalMs: 60_000,
+        });
+
+        recorder.record({ name: "A", fields: {} });
+        await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1));
+
+        // 模拟下一次 flush
+        await (recorder as any).flush();
+
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+});
+```
+
+## 参考
+
+- [第 8 章：可观测性](../08-observability.md) —— 基础原语和内置事件
+- 框架自己的 composite / with-fields recorder：`packages/core/src/metrics/`

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

@@ -0,0 +1,200 @@
+# 高阶：内联 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。
+
+## 生成的输出
+
+输入：
+
+```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);
+```
+
+得到大概这样的：
+
+```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"
+```
+
+抓配置错误在部署发出之前。
+
+## 参考
+
+- [第 9 章：服务器与部署 · proxy 路由](../09-server-and-deployment.md#proxy-路由)
+- 实现：`packages/server/src/proxy.ts`
+- parity 测试：`packages/server/test/proxy.test.ts`