@finesoft/front 0.5.0 → 0.5.2

package/docs/zh/09-server-and-deployment.md

@@ -1,242 +1,82 @@
-# 9. 服务器与部署
+# HTTP 与部署主机
 
-框架的服务端。本章覆盖：
+可移植数据处理器返回标准 Response。同一操作可绑定 Node 或 Worker，业务模块无需页面、DOM、Hono、Vite。
 
-- Vite 插件（`finesoftFrontViteConfig`）—— dev server、构建配置、代码生成
-- `createServer` —— 独立的 Hono 服务器
-- Proxy 路由 —— 带 SSRF / 二进制完整性守卫的声明式 API 转发
-- Adapter —— Node、Vercel、Cloudflare、Netlify、静态
-
-## Vite 插件
+## Data endpoint / 数据接口
 
 ```ts
-// vite.config.ts
-import { finesoftFrontViteConfig } from "@finesoft/front";
-import { defineConfig } from "vite";
-
-export default defineConfig({
-    plugins: [
-        // ... 视图层插件（Vue/React/Svelte）
-        finesoftFrontViteConfig({
-            ssr: { entry: "src/ssr.ts" },
-            i18n: { messagesDir: "src/locales" },
-            proxies: [{ prefix: "/api", target: "https://upstream.example" }],
-            adapter: "auto",
-            renderModes: { "/blog/*": "prerender" },
-        }),
-    ],
+import { defineApp, defineOperation, createRuntime, ExecutionError } from "@finesoft/front";
+import { defineEndpoint } from "@finesoft/front";
+export const double = defineOperation({
+    id: "double",
+    kind: "query",
+    handler: (value: number) => value * 2,
 });
+export const endpoints = [
+    defineEndpoint({
+        method: "POST",
+        path: "/double",
+        operation: double,
+        decode: async (request) => {
+            const body: unknown = await request.json();
+            if (typeof body !== "number" || !Number.isFinite(body))
+                throw new ExecutionError("validation");
+            return body;
+        },
+        encode: (value) => Response.json({ value }),
+    }),
+];
+export function createDataApp() {
+    const runtime = createRuntime({ app: defineApp({ id: "data-app", operations: [double] }) });
+    return { runtime, endpoints };
+}
 ```
 
-### 选项
-
-| 选项               | 类型                         | 说明                                                         |
-| ------------------ | ---------------------------- | ------------------------------------------------------------ |
-| `ssr.entry`        | `string`                     | SSR 入口路径（默认 `src/ssr.ts`）。                          |
-| `i18n.messagesDir` | `string`                     | 含 `{locale}.json` 文件的目录（默认关闭）。                  |
-| `proxies`          | `ProxyRouteConfig[]`         | 声明式 API 转发。详见下文。                                  |
-| `adapter`          | `"auto" \| "node" \| ...`    | 目标平台。`"auto"` 从环境变量检测。                          |
-| `renderModes`      | `Record<string, RenderMode>` | 按路由覆盖渲染模式（glob 键）；`"prerender"` 启用 ISR 缓存。 |
-
-### 它做什么
-
-Dev：
-
-- 启动 Hono 服务器，每个请求都跑你的 SSR 入口
-- 通过 Vite 模块图热重载 SSR 代码
-- 本地服务 proxy 路由，让客户端 `fetch("/api/...")` 能跑通
-
-Build：
-
-- 用 Vite 标准管线打包客户端 bundle
-- 把 SSR 入口打包成独立模块
-- 生成 adapter 特定的入口文件（`vercel.func`、`_worker.js`、`node-server.js` 等）
-- 把 `renderMode: "prerender"` 的路由预渲染成静态 HTML
-
-## `createServer` —— 独立 Hono 服务器
-
-Node 部署和测试时，框架导出一个 async 工厂。它加载 `.env`、检测运行时、构建 Hono app、注册 proxies + 你的 `setup` 路由、挂 SSR catch-all，并**启动监听**（端口取自配置或 `PORT`，默认 `3000`）—— 然后返回 `{ app, vite, runtime }`：
+## Separate platform entries / 独立平台入口
 
 ```ts
-import { createServer } from "@finesoft/front";
-
-const { app } = await createServer({
-    ssr: { ssrProductionModule: "./dist/server/ssr.js" }, // dev 用 ssrEntryPath
-    proxies: [{ prefix: "/api", target: "https://upstream.example" }],
+// node.ts
+import { startNodeHandler } from "@finesoft/front";
+import { createHttpHandler } from "@finesoft/front";
+import { createDataApp } from "./data-app";
+const options = createDataApp();
+const handler = createHttpHandler(options);
+const server = await startNodeHandler({
+    handler,
     port: 3000,
+    disposeApp: () => options.runtime.dispose(),
 });
+// await server.dispose();
 
-// `app` 是已启动的 Hono 实例 —— 导出给 adapter 导入 fetch handler 的 serverless 运行时
-// （Vercel / Cloudflare / Netlify）。
-export { app };
-```
-
-### 包含什么
-
-- 客户端 bundle 的静态文件服务
-- 所有 proxy 路由（通过 `registerProxyRoutes` 注册）
-- 带完整中间件管线的 SSR 渲染
-- prerendered 路由的 ISR 缓存
-- 从 `Accept-Language` 解析 locale
-
-## Proxy 路由
-
-带内置 SSRF 保护、二进制安全转发、可配置 auth/cache 的声明式 API 转发。
-
-### 基础配置
-
-```ts
-proxies: [
-    {
-        prefix: "/api",                    // 必须以 / 开头
-        target: "https://api.example.com", // 必须以 https:// 或 http:// 开头
-    },
-],
-```
-
-现在 `GET /api/users/42` → `GET https://api.example.com/users/42`。query 参数和请求头都转发。
-
-### 完整选项
-
-```ts
-{
-    prefix: "/api/apple",
-    target: "https://api.music.apple.com",
-    methods: ["get", "post"],                          // 默认 ["all"]
-    headers: { "X-App": "finesoft" },                  // 注入到每个请求
-    auth: { type: "bearer", envKey: "APPLE_TOKEN" },   // 读 process.env.APPLE_TOKEN
-    cache: "public, max-age=60",                       // 响应的 Cache-Control
-    followRedirects: false,                            // 默认 false（redirect: "manual"）
-}
-```
-
-`auth.type`：`"bearer"` → `Authorization: Bearer <token>`。`"basic"` → `Authorization: Basic <token>`。`envKey` 在请求时读取，所以改它（或 unset）不需要重启。
-
-### 框架强制的保证
-
-- **SSRF 保护**：path 包含任何 `%` 编码字符、以 `//` 开头、或含允许字符集之外的字符（`[/\w.\-~%:@!$&'()*+,;=]`）就被拒。解码后 ≠ 原始也拒（防止 `%2F` 走私）。
-- **开放重定向保护**：构造出的目标 URL 必须与配置的 `target` 同 `origin`。不同 origin → `400 Invalid proxy target`。
-- **二进制完整性**：响应 body 通过 `arrayBuffer()` 转发，不用 `text()` —— 精确保留字节。PDF、图片、protobuf 响应与上游响应字节相同。
-- **大小限制**：10 MB。先查 `Content-Length` 头快速拒绝；fetch 后再查实际 body 长度。
-- **HTTP 警告**：任何 `http://` 目标启动时打 warning。生产用 HTTPS。
-
-### 生成的 proxy 代码（serverless / edge）
-
-serverless 函数下，proxy 逻辑可以内联到部署的函数 bundle 而不依赖运行时的 `registerProxyRoutes`。详见 [advanced/inline-proxy-codegen](./advanced/inline-proxy-codegen.md)。
-
-## Adapter
-
-| Adapter        | 目标                       | 构建产物                                                |
-| -------------- | -------------------------- | ------------------------------------------------------- |
-| `"node"`       | 独立 Node.js 服务器        | `dist/server/index.js` —— `serve({ fetch: app.fetch })` |
-| `"vercel"`     | Vercel Build Output API v3 | `.vercel/output/` 含 `functions/` 和 `static/`          |
-| `"cloudflare"` | Cloudflare Workers         | `dist/_worker.js` + `dist/_routes.json`                 |
-| `"netlify"`    | Netlify Functions v2       | `netlify/functions/` + `_redirects`                     |
-| `"static"`     | 预渲染静态文件             | 只有 `dist/client/`（无服务器）                         |
-| `"auto"`       | 构建期自动检测             | 按环境变量挑上面之一                                    |
-
-### 自动检测
-
-`adapter: "auto"` 按顺序检查：
-
-1. `VERCEL=1` → vercel
-2. `CF_PAGES=1` → cloudflare
-3. `NETLIFY=1` → netlify
-4. 否则 → node
-
-对大多数 CI 环境管用 —— Vercel / Cloudflare / Netlify 构建期都自动设置这些。
-
-## ISR（增量静态再生成）
-
-把路由标 `prerender`：路由级（`renderMode: "prerender"`）或经 Vite 插件按 glob 配置（配置级优先于路由级）：
-
-```ts
-finesoftFrontViteConfig({
-    ssr: { entry: "src/ssr.ts" },
-    renderModes: { "/blog/*": "prerender", "/products/*": "prerender" },
-});
+// worker.ts (a separate host entry)
+import { createHttpHandler } from "@finesoft/front";
+import { createDataApp } from "./data-app";
+export default createHttpHandler(createDataApp);
 ```
 
-`prerender` 路由有两种服务方式：
-
-1. **构建期静态化** —— static adapter 在 build 时渲染每个 prerender 路由、写 `dist/<route>.html`（开 i18n 时按 locale 各一份）。当作纯静态文件服务，请求时不跑 controller。
-2. **运行时缓存** —— 打包服务器（`createServer`）和 `vp preview` 在路由**首次**请求时渲染、把 HTML 存入内存 LRU（`ISR_CACHE_MAX = 1000` 条，按最近最少使用驱逐）。后续请求直接吐缓存、不再跑 controller。
-
-> **无 TTL、无后台再生成。** 运行时缓存没有基于时间的过期、也没有 stale-while-revalidate —— 条目存活到被 LRU 驱逐或进程重启。「N 秒后再生成」的语义在 **CDN**、不在框架（见下）。没有 `isr` 配置项，也没有程序化失效 API。
-
-### stale-while-revalidate 委托给 CDN
-
-平台 adapter 在 prerender 响应上设缓存头，让边缘做真正的 ISR：
-
-| Adapter                | prerender 响应的缓存头                                                                    |
-| ---------------------- | ----------------------------------------------------------------------------------------- |
-| Netlify                | `Netlify-CDN-Cache-Control: max-age=3600, stale-while-revalidate=3600, durable`（真 SWR） |
-| Cloudflare             | `Cache-Control: public, max-age=3600`                                                     |
-| Node（自托管）/ Vercel | 无 —— 依赖内存 LRU                                                                        |
-
-`3600` 秒窗口是各 adapter 里硬编码的常量，不可配。多实例 / 多区域部署靠 CDN 头保证一致缓存；内存 LRU 是单实例单服务器的服务。
-
-### 缓存失效
-
-没有程序化失效 API。要强制刷新：
-
-- 重启服务器（清空整个内存 LRU）
-- 重新部署（重建构建期静态 + 重置缓存）
-- 在 Netlify / Cloudflare 上 purge 该路径的 CDN 缓存
-
-## 自定义 Hono 中间件
+HTTP 处理器本身通过 `handler.fetch(request, bindings, host)` 执行请求，Node 与 Worker 使用同一对象；`startNodeHandler` 接收该对象，不接收单独的函数。工厂参数在首个请求内初始化一次，避免 workerd 在模块求值阶段创建 Runtime；每个请求的 bindings、取消与后台任务宿主仍独立传入。旧 `createWorkerHandler` 已删除。
 
-如果你需要 proxy 和 SSR 之外的服务端逻辑（如 webhook、健康检查），通过 `setup` 钩子注册 —— 它在 proxies 之后、SSR catch-all **之前**跑，所以你的路由优先：
+## Web build / 页面构建
 
 ```ts
-await createServer({
-    ssr: { ssrProductionModule: "./dist/server/ssr.js" },
-    setup: (app) => {
-        app.get("/health", (c) => c.json({ status: "ok" }));
-        app.post("/webhook", async (c) => {
-            const body = await c.req.json();
-            await handleWebhook(body);
-            return c.json({ ok: true });
-        });
-    },
+import { defineConfig } from "vite-plus";
+import react from "@vitejs/plugin-react";
+import { finesoftFrontViteConfig } from "@finesoft/front";
+export default defineConfig({
+    plugins: [
+        react(),
+        finesoftFrontViteConfig({
+            adapter: "node",
+            ssr: { entry: "src/ssr.ts" },
+        }),
+    ],
 });
 ```
 
-## 环境变量
-
-框架读取：
-
-- `NODE_ENV` —— `"production"` 启用生产专用优化
-- `PROXY_TOKEN` / `BASIC_TOKEN` / 任何 `auth.envKey` —— proxy 鉴权密钥
-- `VERCEL`、`CF_PAGES`、`NETLIFY` —— adapter 自动检测
-
-其他都是你的。通过 `process.env` 直接访问，或在 DI 容器里注册 config 对象：
-
-```ts
-framework.container.register("config", () => ({
-    upstreamUrl: process.env.UPSTREAM_URL ?? "https://api.example.com",
-    sessionSecret: requireEnv("SESSION_SECRET"),
-}));
-```
-
-## 健康检查和优雅关闭
-
-负载均衡器后的 Node 部署：
-
-```ts
-await createServer({
-    ssr: { ssrProductionModule: "./dist/server/ssr.js" },
-    setup: (app) => app.get("/health", (c) => c.json({ ok: true })),
-});
-
-// createServer 自身启动监听 —— 不需要再手动 serve()。
-process.on("SIGTERM", () => process.exit(0));
-```
+Node 主机需要 `@hono/node-server`。可移植 Worker 图无需 Node 兼容开关。DNS 校验属于 Node 主机，必需能力不可用时明确失败。浏览器网络使用显式策略。流资源保留到消费、取消或失败。后台任务使用 `runManagedTask` 与主机 `waitUntil`，不能保留响应所有的资源。Vite 适配器生成使用同一 SSR 响应组装器的薄主机模块；本地构建不等于部署发布。
 
-`createServer` 不返回底层 `http.Server`，因此没有内建的 `server.close()` 连接 drain。若你需要优雅 drain —— 或需要句柄在关闭时调 `framework.dispose()`（递归 dispose 容器、对 recorder/logger 调 `destroy()`、注销路由）—— 改用更底层的搭建：自己建 Hono app 和 framework 并 `serve()`，从而同时握住两个句柄。
+当 `setup` 是模块路径时，该模块必须通过 `export default` 导出 setup 函数。开发、预览与生成的部署主机统一使用这个导出，不再自动猜测命名函数。
 
-## 下一步
+## 静态托管边界
 
-- [Feature flags、平台、PWA](./10-features-platform-pwa.md) —— 特性开关、平台检测
-- [工程实践 · CI 与发布流程](./engineering/ci-release-flow.md) —— 自动化发布
-- [陷阱：proxy 二进制载荷](./pitfalls/proxy-binary-payloads.md) —— 为什么 `arrayBuffer` 重要
+`staticAdapter` 默认读取构建产物的 `render.routes`，通过同一 SSR host 生成 HTML 并等待释放；`dynamicRoutes` 提供具体动态路径，`routesExport` 仅作显式扩展。发现路由或渲染失败会令构建失败。纯 HTML 不能表达重定向、错误状态、Set-Cookie 或自定义 HTTP 响应头，因此适配器拒绝这些响应；需要它们时选择 Node/Worker 等请求主机。

package/docs/zh/10-features-platform-pwa.md

@@ -1,238 +1,14 @@
-# 10. Feature flags、平台、PWA
+# 功能开关、平台与 PWA
 
-三个小而独立的运行时辅助：
+可移植检测、功能开关契约属于根入口；PWA、DOM 行为使用浏览器入口。
 
-- **Feature flags** —— 不重新部署就能变的配置
-- **平台检测** —— 解析 User-Agent 得到 OS / 浏览器 / 引擎
-- **PWA 模式** —— 检测应用是否已安装（standalone）
-
-每个都可替换，每个都可组合自定义 provider。
-
-## Feature flags
-
-```ts
-const framework = Framework.create({
-    featureFlags: {
-        darkMode: true,
-        maxRetries: 3,
-        experimentalCheckout: false,
-    },
-});
-
-const flags = framework.container.resolve(DEP_KEYS.FEATURE_FLAGS);
-flags.get("darkMode"); // true
-flags.get("maxRetries"); // 3
-flags.get("missing"); // undefined
-flags.get("missing", "fallback"); // "fallback"
-```
-
-Flag 值可以是任何 JSON 可序列化的：布尔、字符串、数字、数组、对象。
-
-### 静态配置
-
-最简单的情况 —— flag 跟 bundle 一起发：
-
-```ts
-Framework.create({
-    featureFlags: {
-        darkMode: process.env.NODE_ENV !== "production",
-        analytics: true,
-        cdnUrl: "https://cdn.example.com",
-    },
-});
-```
-
-适用于由环境驱动的 flag，而不是用户属性驱动的。
-
-### 远端 provider
-
-接入从远端服务拉的 provider（LaunchDarkly、GrowthBook、Unleash、自家配置服务）：
-
-```ts
-import { type FeatureFlagsProvider } from "@finesoft/front";
-
-const remoteConfigProvider: FeatureFlagsProvider = {
-    async load() {
-        const resp = await fetch("https://config.example.com/flags");
-        return resp.json(); // { ...flags }
-    },
-};
-
-const framework = Framework.create({
-    featureFlags: {
-        darkMode: false,
-        maxRetries: 3,
-    },
-    featureFlagsProviders: [remoteConfigProvider],
-});
-```
-
-provider 按注册顺序跑。后注册的 provider 对同 key 覆盖之前的值 —— 「后注册者胜」。
-
-### 缓存生命周期
-
-框架在 `Framework.create()` 期间加载一次 provider 值。之后 flag 同步从内存读。
-
-调 `flags.refresh()` 刷新：
-
-```ts
-const flags = framework.container.resolve(DEP_KEYS.FEATURE_FLAGS);
-await flags.refresh(); // 重跑所有 provider
-```
-
-通常按定时器或响应服务端推送事件调。
-
-### 用户级 targeting
-
-内置 flag 是全局的（每个用户同一个值）。需要用户级 targeting 的话，让你的 provider 返回函数，或用单独的评估步骤：
-
-```ts
-class TargetingProvider implements FeatureFlagsProvider {
-    constructor(private userId: string) {}
-    async load() {
-        const resp = await fetch(`https://config.example.com/flags?userId=${this.userId}`);
-        return resp.json();
-    }
-}
-
-// 在 beforeLoad 守卫里按请求注册：
-async function flagsGuard(ctx) {
-    const userId = await getUserIdFromCookie(ctx);
-    const targeting = new TargetingProvider(userId);
-    const flags = await targeting.load();
-    ctx.container.register(DEP_KEYS.FEATURE_FLAGS, () => ({
-        get: (key, fallback) => flags[key] ?? fallback,
-    }));
-    return next();
-}
-```
-
-复杂分桶交给专门的服务（GrowthBook SDK 等），把它的 evaluator 存进 DI。
-
-### SSR / CSR 一致性
-
-服务端评估而浏览器端不重新评估的 flag 会引起 hydration 不匹配。Controller 读 flag 时框架会把 flag 值序列化进 `PrefetchedIntents`。浏览器读到的就是服务端看到的值。
-
-对于*应当*不同的 flag（如 A/B 变体），在 `beforeLoad` 守卫里评估并存到请求 scope 里 —— 服务端和浏览器都会用服务端解析出的值。
-
-## 平台检测
-
-```ts
-import { detectPlatform } from "@finesoft/front";
-
-const info = detectPlatform();
-// {
-//   os: "ios" | "android" | "macos" | "windows" | "linux" | "other",
-//   browser: "safari" | "chrome" | "firefox" | "edge" | ...,
-//   engine: "webkit" | "blink" | "gecko" | "other",
-//   isMobile: boolean,
-//   isTouch: boolean,
-//   isServer: boolean,
-// }
-```
-
-浏览器端 `detectPlatform()` 读 `navigator.userAgent`。服务端框架自动解析请求的 `User-Agent` 头：
-
-```ts
-const platform = framework.getPlatform();
-```
-
-Controller 和守卫从 DI resolve：
-
-```ts
-const platform = ctx.container.resolve(DEP_KEYS.PLATFORM);
-if (platform.isMobile) {
-    return rewrite("/m" + ctx.url.pathname);
-}
-```
-
-### 可靠性
-
-User-Agent 字符串会撒谎 —— 每个现代浏览器为了兼容性嵌入了其他浏览器的子串。框架的检测优先匹配众所周知的模式，遇到模糊就回退到 `"other"`。别单纯靠 `browser` 做关键决策：
-
-- ✅ 按 `isMobile` 调整布局
-- ✅ 非 WebKit 浏览器隐藏 Safari 专有特性
-- ❌ 锁定特定浏览器
-- ❌ 按浏览器版本选代码路径
-
-## PWA 检测
+## Imports / 入口
 
 ```ts
+import { detectPlatform, type FeatureFlagsProvider } from "@finesoft/front";
 import { getPWADisplayMode } from "@finesoft/front";
-
-const mode = getPWADisplayMode();
-// "standalone" | "twa" | "browser"
-```
-
-- `"standalone"` —— 作为已安装 PWA 跑（Safari 加到主屏、Chrome install）
-- `"twa"` —— Trusted Web Activity（Android，包装成原生应用）
-- `"browser"` —— 普通浏览器标签
-
-函数读 `window.matchMedia("(display-mode: standalone)")` 和 Android 的 TWA referrer。服务端返回 `"browser"`。
-
-### 常见用途
-
-```ts
-const mode = getPWADisplayMode();
-
-if (mode === "browser") {
-    showInstallBanner();
-}
-
-if (mode === "standalone") {
-    // 自定义导航 —— 已安装的应用不应再显示 install 提示
-    hideInstallButton();
-    enableNativeBackButtonHandling();
-}
-```
-
-### Service worker 注册
-
-PWA install 与 service worker 独立 —— 可以只要一个。注册 service worker：
-
-```ts
-// src/main.ts
-startBrowserApp({
-    bootstrap,
-    mount,
-    onAfterStart() {
-        if ("serviceWorker" in navigator) {
-            navigator.serviceWorker.register("/sw.js");
-        }
-    },
-});
-```
-
-框架不内置 service worker 生成器。用 [Vite PWA](https://vite-pwa-org.netlify.app/) 或手写。
-
-## 组合三者
-
-一个组合三者的常见导航守卫：
-
-```ts
-import { next, rewrite, DEP_KEYS } from "@finesoft/front";
-
-function mobilePwaGuard(ctx) {
-    const platform = ctx.container.resolve(DEP_KEYS.PLATFORM);
-    const flags = ctx.container.resolve(DEP_KEYS.FEATURE_FLAGS);
-
-    if (flags.get("mobilePwaRedesign") && platform.isMobile && !ctx.isSsr) {
-        if (getPWADisplayMode() === "standalone") {
-            return rewrite(`/pwa${ctx.url.pathname}`);
-        }
-    }
-    return next();
-}
+// Configure configuration.featureFlags and configuration.platform in the Web declaration.
+// Call getPWADisplayMode only in a browser-owned lifecycle.
 ```
 
-把已安装移动 PWA 用户路由到不同的页面树，不影响其他用户。
-
-## 注意事项
-
-- **服务端解析出的 flag 会进 HTML。** flag 里别存秘密。
-- **服务端平台检测靠请求头。** 爬虫或 curl 可能没发有用的 User-Agent —— 优雅处理 `"other"`。
-- **服务端 PWA 检测永远返回 `"browser"`。** 不要在 SSR 渲染路径里依赖；按 PWA 模式做条件 UI 应该仅客户端，或用 `<noscript>` 兜底。
-
-## 下一步
-
-- [工程实践 · 项目结构](./engineering/project-structure.md) —— flag config、平台感知代码放哪
+功能开关是应用决策，不是身份授权；受保护操作仍需运行时策略。Service Worker 清单、缓存策略由应用决定，选择浏览器主机不会自动安装。