@finesoft/front 0.5.1 → 0.5.3

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

@@ -1,242 +1,82 @@
-# 9. Server & deployment
+# HTTP and deployment hosts
 
-The server side of the framework. This chapter covers:
+Portable data handlers return standard Responses. Bind the same operation to Node or Worker without pages, DOM, Hono, or Vite in its business module.
 
-- The Vite plugin (`finesoftFrontViteConfig`) — dev server, build config, code generation
-- `createServer` — the standalone Hono server
-- The proxy router — declarative API forwarding with SSRF / binary integrity guards
-- Adapters — Node, Vercel, Cloudflare, Netlify, static
-
-## The Vite plugin
+## Data endpoint / 数据接口
 
 ```ts
-// vite.config.ts
-import { finesoftFrontViteConfig } from "@finesoft/front";
-import { defineConfig } from "vite";
-
-export default defineConfig({
-    plugins: [
-        // ... view layer plugin (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 };
+}
 ```
 
-### Options
-
-| Option             | Type                         | Notes                                                                          |
-| ------------------ | ---------------------------- | ------------------------------------------------------------------------------ |
-| `ssr.entry`        | `string`                     | Path to your SSR entry (default `src/ssr.ts`).                                 |
-| `i18n.messagesDir` | `string`                     | Folder with `{locale}.json` files (default off).                               |
-| `proxies`          | `ProxyRouteConfig[]`         | Declarative API forwarding. See below.                                         |
-| `adapter`          | `"auto" \| "node" \| ...`    | Target platform. `"auto"` detects from env vars.                               |
-| `renderModes`      | `Record<string, RenderMode>` | Per-route render-mode override (glob keys); `"prerender"` enables ISR caching. |
-
-### What it does
-
-In dev:
-
-- Starts a Hono server that runs your SSR entry on every request
-- Hot-reloads SSR code via Vite's module graph
-- Serves the proxy routes locally so client-side `fetch("/api/...")` works
-
-In build:
-
-- Bundles the client bundle with Vite's standard pipeline
-- Bundles the SSR entry as a separate module
-- Generates an adapter-specific entry file (`vercel.func`, `_worker.js`, `node-server.js`, etc.)
-- Prerenders any `renderMode: "prerender"` routes to static HTML
-
-## `createServer` — the standalone Hono server
-
-For Node deployments and tests, the framework exports an async factory. It loads `.env`, detects the runtime, builds the Hono app, registers proxies + your `setup` routes, mounts the SSR catch-all, and **starts listening** (port from config or `PORT`, default `3000`) — then returns `{ app, vite, runtime }`:
+## Separate platform entries / 独立平台入口
 
 ```ts
-import { createServer } from "@finesoft/front";
-
-const { app } = await createServer({
-    ssr: { ssrProductionModule: "./dist/server/ssr.js" }, // or ssrEntryPath in dev
-    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` is the started Hono instance — export it for serverless runtimes whose
-// adapter imports the fetch handler (Vercel / Cloudflare / Netlify).
-export { app };
-```
-
-### What it includes
-
-- Static file serving for the client bundle
-- All your proxy routes (registered via `registerProxyRoutes`)
-- SSR rendering with full middleware pipeline
-- ISR cache for prerendered routes
-- Locale resolution from `Accept-Language`
-
-## Proxy routes
-
-Declarative API forwarding with built-in SSRF protection, binary-safe forwarding, and configurable auth/cache.
-
-### Basic config
-
-```ts
-proxies: [
-    {
-        prefix: "/api",                    // must start with /
-        target: "https://api.example.com", // must be https:// or http://
-    },
-],
-```
-
-Now `GET /api/users/42` → `GET https://api.example.com/users/42`. Query params and request headers are forwarded.
-
-### Full options
-
-```ts
-{
-    prefix: "/api/apple",
-    target: "https://api.music.apple.com",
-    methods: ["get", "post"],                          // default ["all"]
-    headers: { "X-App": "finesoft" },                  // injected per request
-    auth: { type: "bearer", envKey: "APPLE_TOKEN" },   // reads process.env.APPLE_TOKEN
-    cache: "public, max-age=60",                       // Cache-Control on response
-    followRedirects: false,                            // default false (redirect: "manual")
-}
-```
-
-`auth.type`: `"bearer"` → `Authorization: Bearer <token>`. `"basic"` → `Authorization: Basic <token>`. The `envKey` is read at request time, so changing it (or unsetting it) does not require a restart.
-
-### What the framework enforces
-
-- **SSRF protection**: path is rejected if URL-encoded (any `%`-encoded char), starts with `//`, or contains characters outside the allowed set (`[/\w.\-~%:@!$&'()*+,;=]`). Decoded ≠ raw also rejected (prevents `%2F` smuggling).
-- **Open-redirect protection**: the constructed target URL must have the same `origin` as the configured `target`. Different origin → `400 Invalid proxy target`.
-- **Binary integrity**: response body forwarded via `arrayBuffer()`, not `text()` — preserves bytes exactly. PDF, image, protobuf responses are byte-identical to the upstream response.
-- **Size limit**: 10 MB. `Content-Length` header is checked first for fast rejection; actual body byte length is checked after fetch.
-- **HTTP warning**: any `http://` target logs a warning at startup. Use HTTPS in production.
-
-### Generated proxy code (serverless / edge)
-
-For serverless functions, the proxy logic is inlined into the deployed function bundle instead of relying on `registerProxyRoutes` at runtime. See [advanced/inline-proxy-codegen](./advanced/inline-proxy-codegen.md).
-
-## Adapters
-
-| Adapter        | Target                     | Build output                                           |
-| -------------- | -------------------------- | ------------------------------------------------------ |
-| `"node"`       | Standalone Node.js server  | `dist/server/index.js` — `serve({ fetch: app.fetch })` |
-| `"vercel"`     | Vercel Build Output API v3 | `.vercel/output/` with `functions/` and `static/`      |
-| `"cloudflare"` | Cloudflare Workers         | `dist/_worker.js` + `dist/_routes.json`                |
-| `"netlify"`    | Netlify Functions v2       | `netlify/functions/` + `_redirects`                    |
-| `"static"`     | Pre-rendered static files  | `dist/client/` only (no server)                        |
-| `"auto"`       | Auto-detect at build time  | Picks one of the above by environment variable         |
-
-### Auto-detection
-
-`adapter: "auto"` checks (in order):
-
-1. `VERCEL=1` → vercel
-2. `CF_PAGES=1` → cloudflare
-3. `NETLIFY=1` → netlify
-4. otherwise → node
-
-This works for most CI environments — Vercel / Cloudflare / Netlify all set these automatically during their build.
-
-## ISR (Incremental Static Regeneration)
-
-Mark routes `prerender` — per route (`renderMode: "prerender"`) or per glob via the Vite plugin's `renderModes` (config-level wins over route-level):
-
-```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);
 ```
 
-A `prerender` route is served two ways:
-
-1. **Build-time static** — the static adapter renders each prerender route at build and writes `dist/<route>.html` (one per locale when i18n is on). Served as plain static files; no controller runs at request time.
-2. **Runtime cache** — the bundled server (`createServer`) and `vp preview` render a prerender route on its **first** request and store the HTML in an in-memory LRU (`ISR_CACHE_MAX = 1000` entries, evicted least-recently-used). Subsequent requests serve the cached HTML without re-running the controller.
-
-> **No TTL, no background regeneration.** The runtime cache has no time-based expiry and no stale-while-revalidate — an entry lives until it is LRU-evicted or the process restarts. The "regenerate after N seconds" semantics live at the **CDN**, not in the framework (below). There is no `isr` config option and no programmatic invalidation API.
-
-### Stale-while-revalidate is delegated to the CDN
-
-Platform adapters set cache headers on prerender responses so the edge does the real ISR:
-
-| Adapter                   | Header on prerender responses                                                              |
-| ------------------------- | ------------------------------------------------------------------------------------------ |
-| Netlify                   | `Netlify-CDN-Cache-Control: max-age=3600, stale-while-revalidate=3600, durable` (true SWR) |
-| Cloudflare                | `Cache-Control: public, max-age=3600`                                                      |
-| Node (self-host) / Vercel | none — relies on the in-memory LRU                                                         |
-
-The `3600`s window is a hard-coded per-adapter constant, not user-configurable. For multi-instance / multi-region deployments the CDN headers are what give you consistent caching; the in-memory LRU is per-instance single-server serving.
-
-### Cache invalidation
-
-There is no programmatic invalidation API. To force a refresh:
-
-- Restart the server (clears the entire in-memory LRU)
-- Redeploy (rebuilds build-time static and resets caches)
-- On Netlify / Cloudflare, purge the CDN cache for the path
-
-## Custom Hono middleware
+The HTTP owner executes requests through `handler.fetch(request, bindings, host)`. Node and Worker use the same object; `startNodeHandler` takes the object rather than a detached function. A factory argument initializes once inside the first request, avoiding Runtime creation during workerd module evaluation; bindings, cancellation and task hosts remain per request. `createWorkerHandler` has been removed.
 
-If you need server logic outside the proxy and SSR (e.g., a webhook endpoint, a health check), register it via the `setup` hook — it runs after proxies but **before** the SSR catch-all, so your routes win:
+## 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" },
+        }),
+    ],
 });
 ```
 
-## Environment variables
-
-The framework reads:
-
-- `NODE_ENV` — `"production"` enables prod-only optimizations
-- `PROXY_TOKEN` / `BASIC_TOKEN` / any `auth.envKey` — proxy auth secrets
-- `VERCEL`, `CF_PAGES`, `NETLIFY` — adapter auto-detection
-
-Anything else is yours. Access via `process.env` directly or by registering a config object in the DI container:
-
-```ts
-framework.container.register("config", () => ({
-    upstreamUrl: process.env.UPSTREAM_URL ?? "https://api.example.com",
-    sessionSecret: requireEnv("SESSION_SECRET"),
-}));
-```
-
-## Health checks and graceful shutdown
-
-For Node deployments behind a load balancer:
-
-```ts
-await createServer({
-    ssr: { ssrProductionModule: "./dist/server/ssr.js" },
-    setup: (app) => app.get("/health", (c) => c.json({ ok: true })),
-});
-
-// createServer starts the listener itself — no manual serve() needed.
-process.on("SIGTERM", () => process.exit(0));
-```
+Node’s host requires `@hono/node-server`. Worker fetch has no Node compatibility requirement for the portable graph. DNS enforcement belongs to the Node host; an unavailable required capability fails explicitly. Browser networking uses an explicit browser policy. Streaming resources live until consumption, cancellation or failure. Background work uses `runManagedTask` and host `waitUntil`; detached tasks must not retain response-owned resources. The Vite adapters emit thin host modules using the same SSR response assembler; building locally does not deploy or publish.
 
-`createServer` does not return the underlying `http.Server`, so there's no built-in `server.close()` connection-drain. If you need graceful draining — or a handle to call `framework.dispose()` (recursively disposes the container, calls `destroy()` on recorders/loggers, unregisters routes) on shutdown — compose the lower level instead: build the Hono app and own framework yourself and `serve()` it so you keep both handles.
+When `setup` is a module path, that module must `export default` its setup function. Development, preview and generated hosts use this explicit export; named functions are not discovered automatically.
 
-## Next
+## Static hosting boundary
 
-- [Features, platform, PWA](./10-features-platform-pwa.md) — feature flags, platform detection
-- [Engineering: CI & release flow](./engineering/ci-release-flow.md) — automating releases
-- [Pitfalls: proxy binary payloads](./pitfalls/proxy-binary-payloads.md) — why `arrayBuffer` matters
+`staticAdapter` reads built `render.routes` by default, uses the same SSR host to generate HTML and awaits cleanup. `dynamicRoutes` supplies concrete dynamic paths; `routesExport` is an explicit extension. Discovery and rendering failures fail the build. Plain HTML cannot express redirects, error status, Set-Cookie or custom HTTP response headers, so the adapter rejects these responses; choose a request host when they are required.

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

@@ -1,238 +1,14 @@
-# 10. Features, platform, PWA
+# Features, platform and PWA
 
-Three small, independent runtime helpers:
+Portable detection and feature contracts belong to the root entry. Browser-only PWA and DOM behavior belongs to the browser entry.
 
-- **Feature flags** — config that can change without redeploy
-- **Platform detection** — user-agent parsing for OS / browser / engine
-- **PWA mode** — detect whether the app is installed (standalone)
-
-Each is replaceable, each composable with custom providers.
-
-## 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"
-```
-
-Flags can be any JSON-serializable value: booleans, strings, numbers, arrays, objects.
-
-### Static config
-
-The simplest case — flags shipped with the bundle:
-
-```ts
-Framework.create({
-    featureFlags: {
-        darkMode: process.env.NODE_ENV !== "production",
-        analytics: true,
-        cdnUrl: "https://cdn.example.com",
-    },
-});
-```
-
-Use this for flags driven by environment, not user attributes.
-
-### Remote providers
-
-Plug in a provider that fetches from a remote service (LaunchDarkly, GrowthBook, Unleash, your own config service):
-
-```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],
-});
-```
-
-Providers run in registration order. Later providers override earlier values for the same key — "last registered wins."
-
-### Cache lifecycle
-
-The framework loads provider values once during `Framework.create()`. After that, flags are read synchronously from memory.
-
-To refresh, call `flags.refresh()`:
-
-```ts
-const flags = framework.container.resolve(DEP_KEYS.FEATURE_FLAGS);
-await flags.refresh(); // re-runs all providers
-```
-
-You'd typically call this on a timer or in response to a server-sent event.
-
-### Targeting
-
-Built-in flags are global (same value for every user). For per-user targeting, structure your provider to return a function or use a separate evaluation step:
-
-```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();
-    }
-}
-
-// Register per-request in a beforeLoad guard:
-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();
-}
-```
-
-For complex bucketing, hand the user id to a dedicated service (GrowthBook SDK, etc.) and store its evaluator in DI.
-
-### SSR / CSR consistency
-
-Flags evaluated on the server and not re-evaluated on the browser would cause hydration mismatch. The framework serializes flag values into `PrefetchedIntents` if a controller reads them. Browser-side reads return the same value the server saw.
-
-For flags that _should_ differ (e.g., A/B variants), evaluate them in a `beforeLoad` guard and store the result in the request scope — both server and browser will use the value resolved by the server.
-
-## Platform detection
-
-```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,
-// }
-```
-
-In the browser, `detectPlatform()` reads `navigator.userAgent`. On the server, parsing the request's `User-Agent` header is automatic via the framework:
-
-```ts
-const platform = framework.getPlatform();
-```
-
-For controllers and guards, resolve from DI:
-
-```ts
-const platform = ctx.container.resolve(DEP_KEYS.PLATFORM);
-if (platform.isMobile) {
-    return rewrite("/m" + ctx.url.pathname);
-}
-```
-
-### Reliability
-
-User-Agent strings lie — every modern browser embeds substrings of every other browser for compatibility. The framework's detection prioritizes well-known patterns and falls back to `"other"` on ambiguity. Don't make critical decisions on `browser` alone:
-
-- ✅ Adjust layout for `isMobile`
-- ✅ Hide Safari-only features for non-WebKit
-- ❌ Lock specific browsers out
-- ❌ Choose code paths based on browser version
-
-## PWA detection
+## Imports / 入口
 
 ```ts
+import { detectPlatform, type FeatureFlagsProvider } from "@finesoft/front";
 import { getPWADisplayMode } from "@finesoft/front";
-
-const mode = getPWADisplayMode();
-// "standalone" | "twa" | "browser"
-```
-
-- `"standalone"` — running as an installed PWA (Safari add-to-home, Chrome install)
-- `"twa"` — Trusted Web Activity (Android, wrapped as a native app)
-- `"browser"` — regular browser tab
-
-The function reads `window.matchMedia("(display-mode: standalone)")` and Android's TWA referrer. Server-side: returns `"browser"`.
-
-### Common uses
-
-```ts
-const mode = getPWADisplayMode();
-
-if (mode === "browser") {
-    showInstallBanner();
-}
-
-if (mode === "standalone") {
-    // Customize navigation — installed app shouldn't show "Install" prompt
-    hideInstallButton();
-    enableNativeBackButtonHandling();
-}
-```
-
-### Service worker registration
-
-PWA install is independent of service workers — you can have one without the other. To register a service worker:
-
-```ts
-// src/main.ts
-startBrowserApp({
-    bootstrap,
-    mount,
-    onAfterStart() {
-        if ("serviceWorker" in navigator) {
-            navigator.serviceWorker.register("/sw.js");
-        }
-    },
-});
-```
-
-The framework does not ship a service worker generator. Use [Vite PWA](https://vite-pwa-org.netlify.app/) or hand-roll one.
-
-## Composing them
-
-A common navigation guard combining all three:
-
-```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.
 ```
 
-This routes installed mobile PWA users to a different page tree without affecting other users.
-
-## Caveats
-
-- **Feature flags resolved server-side ship in HTML.** Don't store secrets in flags.
-- **Platform detection on the server uses request headers.** A bot or curl might not send a useful User-Agent — handle `"other"` gracefully.
-- **PWA detection on the server always returns `"browser"`.** Don't rely on it in SSR rendering paths; conditional UI based on PWA mode should be client-only or use `<noscript>` fallbacks.
-
-## Next
-
-- [Engineering: project structure](./engineering/project-structure.md) — where to put flag config, platform-aware code
+Feature flags are application decisions, not authentication. Enforce protected operations with runtime policies. A service worker manifest/caching strategy remains application work; selecting the browser host does not install one.