@finesoft/front 0.5.0 → 0.5.2

package/docs/zh/advanced/custom-adapter.md

@@ -1,264 +1,12 @@
-# 高阶：自定义 adapter
+# 自定义部署适配器
 
-适配框架未内置的平台。内置 adapter 有 Node、Vercel、Cloudflare、Netlify、Static。其他 —— Deno Deploy、Bun、AWS Lambda、自建本地 —— 就是自定义 adapter。
-
-本配方端到端写一个。模式：构建期发出平台专属的入口文件，让该入口指向框架的 SSR + proxy 管线。
-
-## adapter 做什么
-
-构建期：
-
-1. 把 SSR 入口（`src/ssr.ts`）打包成单 JS 文件，依赖内联。
-2. 把客户端入口打成平台预期的形状（多数是 `dist/client/`）。
-3. 发出**平台专属入口**，做以下事：
-    - import SSR bundle
-    - 以平台原生形状（Request、Lambda event 等）接收请求
-    - 调 `createServer({ ssrEntry, proxies })` 并 serve 响应
-
-框架在 `packages/server/src/adapters/shared.ts` 提供 `buildBundle`、`generateSSREntry`、`copyStaticAssets`、`prerenderRoutes`。用它们 —— 它们一致地处理了所有 adapter 的重活。
-
-## 示例：Deno Deploy adapter
-
-Deno Deploy 跑 ES 模块，Web 标准 Request/Response。工作流类似 Cloudflare Workers 但带原生 Deno API。
-
-### adapter 接口
-
-```ts
-// src/lib/adapters/deno-deploy.ts
-import type { AdapterDefinition, AdapterContext } from "@finesoft/front";
-import { buildBundle, copyStaticAssets, generateSSREntry, prerenderRoutes } from "@finesoft/front";
-
-export const denoDeployAdapter: AdapterDefinition = {
-    name: "deno-deploy",
-
-    async build(ctx: AdapterContext): Promise<void> {
-        // 1. 打包 SSR
-        const ssrEntry = generateSSREntry(ctx, {
-            // Deno 支持原生 fetch / URL / Response，无需 shim
-            external: [],
-        });
-        await buildBundle(ctx, {
-            entry: ssrEntry,
-            outFile: "dist/server.js",
-            format: "esm",
-        });
-
-        // 2. 拷静态资源
-        copyStaticAssets(ctx, "dist/client", "dist/static");
-
-        // 3. 预渲染 prerender 路由
-        await prerenderRoutes(ctx);
-
-        // 4. 发出 Deno 入口
-        writeEntryFile(
-            ctx,
-            "dist/main.ts",
-            `
-            import { createServer } from "./server.js";
-            const app = createServer({
-                ssrEntry: "./server.js",
-                staticDir: "./static",
-            });
-            Deno.serve(app.fetch);
-        `,
-        );
-    },
-};
-```
-
-### 注册
-
-```ts
-// vite.config.ts
-import { finesoftFrontViteConfig } from "@finesoft/front";
-import { denoDeployAdapter } from "./src/lib/adapters/deno-deploy";
-
-export default {
-    plugins: [
-        finesoftFrontViteConfig({
-            ssr: { entry: "src/ssr.ts" },
-            adapter: denoDeployAdapter,
-        }),
-    ],
-};
-```
-
-`adapter` 选项接受字符串（内置）或 `AdapterDefinition`（自定义）。
-
-## adapter context
-
-`AdapterContext` 传给 `build()`，暴露：
-
-```ts
-interface AdapterContext {
-    root: string; // 项目根的绝对路径
-    outDir: string; // dist 目录的绝对路径
-    ssrEntryPath: string; // src/ssr.ts 的解析后路径
-    routes: RouteDefinition[]; // 来自 bootstrap 的路由（用于 prerender）
-    proxies: ProxyRouteConfig[]; // 来自 finesoftFrontViteConfig 的 proxy 配置
-    isr: IsrConfig | null; // 启用时的 ISR 配置
-    env: Record<string, string>; // 构建期环境变量
-}
-```
-
-通常不会用全部 —— `buildBundle` 和 `generateSSREntry` 拿它们需要的。
-
-## 常见模式
-
-### Edge 运行时（Workers / Deno / Bun）
-
-标准 Web API（Request、Response、fetch）。打 ESM，target `webworker`。大多数 edge 运行时接受 default-exported handler：
-
-```ts
-export default {
-    async fetch(request, env) {
-        return app.fetch(request, env);
-    },
-};
-```
-
-`packages/server/src/adapters/cloudflare.ts` 是 Cloudflare 的标准参考。
-
-### Lambda 风格（AWS Lambda、GCF、Azure Functions）
-
-平台专属 event 形状。在 `Request` 之间转换：
-
-```ts
-import { app } from "./server.js";
-
-export const handler = async (event: APIGatewayProxyEventV2) => {
-    const request = lambdaEventToRequest(event);
-    const response = await app.fetch(request);
-    return responseToLambdaResult(response);
-};
-```
-
-每个云的 SDK 都自带 event-to-request 转换的类型和 helper。直接复用，别重造。
-
-### 多进程服务器（Bun cluster、PM2）
-
-Bun 和现代 Node 支持 `cluster` 风格多进程 serve 利用 CPU 并行：
-
-```ts
-import { app } from "./server.js";
-import { serve } from "@hono/node-server";
-
-const port = parseInt(process.env.PORT ?? "3000", 10);
-serve({ fetch: app.fetch, port });
-```
-
-每个进程独立。ISR 缓存按进程 —— 真正共享缓存要前置 CDN。
-
-## 静态（无服务器）
-
-`adapter: "static"` 是最简单目标 —— 一切预渲染，请求时啥都不跑。
-
-```ts
-export const staticAdapter: AdapterDefinition = {
-    name: "static",
-    async build(ctx) {
-        // 完全跳过 SSR bundle
-        await prerenderRoutes(ctx); // 每个路由都必须是 renderMode: "prerender"
-        copyStaticAssets(ctx, "dist/client", "dist/static");
-        // 无服务器入口 —— 只有静态文件
-    },
-};
-```
-
-验证每个路由都能预渲染：
-
-```ts
-if (!ctx.routes.every((r) => r.renderMode === "prerender")) {
-    throw new Error("Static adapter requires every route to be renderMode: 'prerender'");
-}
-```
-
-## 自动检测扩展
-
-内置 `"auto"` adapter 按顺序查环境变量：
+构建适配器实现 Vite 入口的 Adapter，负责生成部署文件、绑定平台 Request/Response 和清理能力。运行时 SSR 使用 SSR 入口的 createSSRHandler。保留唯一响应组装器，生成器必须传递请求上下文、状态、响应头、Cookie、语言和重定向。内部 buildBundle/generateSSREntry 不是公开 API。仓库 Node/Cloudflare/Netlify/Vercel 实现可作参考，宣称支持前需在目标运行时执行产物。
 
 ```ts
-function detectAdapter(env: Record<string, string>): string {
-    if (env.VERCEL === "1") return "vercel";
-    if (env.CF_PAGES === "1") return "cloudflare";
-    if (env.NETLIFY === "true") return "netlify";
-    return "node";
-}
-```
-
-自定义 adapter 有已知环境标签的话，在项目 `vite.config.ts` 自己包一层自动检测：
-
-```ts
-function pickAdapter() {
-    if (process.env.DENO_DEPLOYMENT_ID) return denoDeployAdapter;
-    return "node";
-}
-
-finesoftFrontViteConfig({
-    adapter: pickAdapter(),
-});
+import type { Adapter, AdapterContext } from "@finesoft/front";
+// Supply { name, async build(context: AdapterContext) { ... } } as the Vite adapter.
+// Runtime module:
+import { createSSRHandler } from "@finesoft/front";
 ```
 
-## 测 adapter
-
-集成测试：跑构建，验证发出的入口：
-
-```ts
-import { describe, test, expect } from "vite-plus/test";
-import { build } from "vite";
-import { denoDeployAdapter } from "./deno-deploy";
-
-describe("denoDeployAdapter", () => {
-    test("emits a Deno-compatible entry", async () => {
-        await build({
-            root: "test/fixtures/basic",
-            plugins: [
-                finesoftFrontViteConfig({
-                    ssr: { entry: "src/ssr.ts" },
-                    adapter: denoDeployAdapter,
-                }),
-            ],
-        });
-
-        const entry = await readFile("test/fixtures/basic/dist/main.ts", "utf-8");
-        expect(entry).toContain("Deno.serve");
-        expect(entry).toContain("./server.js");
-    });
-});
-```
-
-冒烟测试运行时：本地起平台真打 `/`。这能抓单元测试抓不到的平台怪癖（CORS、头归一化、body 解码）。
-
-## 坑
-
-### 别把 Node 内置模块打进 edge 运行时
-
-`fs`、`path`、`http` 等在 Workers / Deno 不存在。`generateSSREntry` 接 `external` 列表 —— 设成平台不兼容的模块，让打包器在构建期出错而不是部署时请求崩。
-
-### `process.env` 每个平台不同
-
-- Node、Vercel：`process.env.FOO`
-- Cloudflare Workers：通过 `fetch()` 的 `env` 参注入秘密
-- Deno：`Deno.env.get("FOO")`
-
-框架对声明的 proxy auth key 处理 `process.env`，但你自己的运行时 env 读取要包成平台感知的 helper。
-
-### 资源的文件系统访问
-
-你在请求时依赖读文件（罕见；多数通过 `staticDir` serve），只有 Node 类 adapter 有原生 fs 访问。edge 运行时要把资源嵌入 bundle 或通过 KV 存代理。
-
-## 上游贡献
-
-自定义 adapter 针对的是流行平台但框架未内置，考虑开 PR。adapter 住 `packages/server/src/adapters/`，结构一致 —— `cloudflare.ts` 是最干净参考。
-
-框架 adapter API 有意保持小。贡献保持最小：
-
-- `adapters/` 里一个文件
-- `auto.ts` 里一个条目用于自动检测（若适用）
-- 本文档里一段
-
-## 参考
-
-- 内置 adapter：`packages/server/src/adapters/`
-- 你会用的共享 helper：`packages/server/src/adapters/shared.ts`
-- [第 9 章：服务器与部署](../09-server-and-deployment.md) —— adapter 包的是什么
+`createSSRHandler` 返回直接拥有 `fetch(request, bindings)` 与 `dispose()` 的执行对象，替代原 `createSSRHost(...).handle(...)`。标准宿主设置 `ownRenderers: true`，关闭时先等待全部响应组装结束，再按身份去重释放 renderer；未设置时 renderer 仍由调用者拥有。`createSSRRender` 自身管理原生渲染的等待与 runtime 释放。

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

@@ -1,318 +1,13 @@
-# 高阶：自定义 event recorder
+# 事件记录
 
-构建生产级的 `EventRecorder`，做批处理、重试、跨导航存活。本配方假设你已经读了[第 8 章：可观测性](../08-observability.md)。
+可移植操作通过执行上下文发送结构化事件，runtime 接收 recorder。
 
-## 目标
-
-好 recorder 的特性：
-
-- **不阻塞。** `record()` 同步返回；传输后台进行。
-- **批处理。** 每 N 个事件或 T 秒一个 HTTP 请求，不是每个事件一个。
-- **跨导航存活。** unload 时通过 `sendBeacon` flush 待发事件。
-- **优雅降级。** 网络失败不让应用崩；发不出去的事件不无限堆积。
-- **生命周期感知。** `destroy()` flush 所有待发事件后销毁。
-
-## 骨架
+## Recorder / 记录器
 
 ```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));
-    };
-}
+import { ConsoleEventRecorder, createRuntime } from "@finesoft/front";
+const runtime = createRuntime({ app, recorder: new ConsoleEventRecorder() });
+// In a handler: context.record("cart.updated", { itemCount: 3 });
 ```
 
-## 每块为什么存在
-
-### `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/`
+记录业务结果时不要复制凭据、请求原文或私有页面数据。记录器故障与执行隔离。浏览器曝光使用显式浏览器 observer，可移植 core 只定义事件契约。