@finesoft/front 0.1.75 → 0.1.77

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

@@ -0,0 +1,242 @@
+# 9. Server & deployment
+
+The server side of the framework. This chapter covers:
+
+- 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
+
+```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",
+            isr: { routes: ["/blog/*"], ttl: 300 },
+        }),
+    ],
+});
+```
+
+### 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.        |
+| `isr`              | `{ routes, ttl }`         | Incremental Static Regeneration for prerendered routes. |
+
+### 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 a function that gives you a ready-to-run Hono app:
+
+```ts
+import { createServer } from "@finesoft/front";
+
+const app = createServer({
+    ssrEntry: "./dist/server/ssr.js",
+    proxies: [{ prefix: "/api", target: "https://upstream.example" }],
+    staticDir: "./dist/client",
+    isr: { routes: ["/blog/*"], ttl: 300 },
+});
+
+// app is a Hono instance — mount it however your runtime expects
+import { serve } from "@hono/node-server";
+serve({ fetch: app.fetch, port: 3000 });
+```
+
+### 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)
+
+```ts
+isr: {
+    routes: ["/blog/*", "/products/*"],
+    ttl: 300,  // seconds
+}
+```
+
+How it works:
+
+1. First request to `/blog/hello-world`: render fully, cache the HTML, set expiry to now + 300s
+2. Subsequent requests within TTL: serve cached HTML directly
+3. After expiry: next request triggers re-render; concurrent requests get stale HTML until re-render finishes
+
+The cache is in-memory per server instance. For multi-instance deployments where consistency matters, put a CDN in front and use HTTP `Cache-Control` headers instead.
+
+Routes not matched by `isr.routes` always render fresh.
+
+### Cache invalidation
+
+Programmatic invalidation is not exposed in the public API. To force a refresh:
+
+- Restart the server (loses entire cache)
+- Wait for TTL
+- Add a cache-busting query param the controller can ignore but that bypasses the cache key
+
+For production, push invalidation up to CDN level — the framework's in-memory cache is for single-instance serving.
+
+## Custom Hono middleware
+
+If you need server logic outside the proxy and SSR (e.g., a webhook endpoint, a health check), mount it on the same Hono app:
+
+```ts
+const app = createServer({ ssrEntry: "./dist/server/ssr.js" });
+
+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 });
+});
+
+// SSR catch-all is registered last by createServer — your routes win.
+```
+
+## 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
+import { serve } from "@hono/node-server";
+
+const app = createServer({
+    /* ... */
+});
+app.get("/health", (c) => c.json({ ok: true }));
+
+const server = serve({ fetch: app.fetch, port: 3000 });
+
+process.on("SIGTERM", () => {
+    server.close(() => {
+        // dispose Framework if you held a reference
+        framework.dispose();
+        process.exit(0);
+    });
+});
+```
+
+`framework.dispose()` recursively disposes the container, calls `destroy()` on registered recorders/loggers, and unregisters all routes.
+
+## Next
+
+- [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

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

@@ -0,0 +1,238 @@
+# 10. Features, platform, PWA
+
+Three small, independent runtime helpers:
+
+- **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
+
+```ts
+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();
+}
+```
+
+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

package/docs/README.md

@@ -0,0 +1,72 @@
+# `@finesoft/front` documentation
+
+> **Language:** English (this page) · **[简体中文](./zh/README.md)**
+
+Full-stack TypeScript framework — router, DI, actions, SSR, and server — in one package. Works with **Vue**, **React**, or **Svelte**. Deploys to Node.js, Vercel, Cloudflare Workers, Netlify, or static hosting.
+
+## Three entry points
+
+Pick where to start based on what you need.
+
+### New to the framework — read top to bottom
+
+A linear path. Each chapter assumes the previous one. By the end you can build, render, and deploy a real app.
+
+1. [Getting started](./01-getting-started.md) — install, Vite config, first page
+2. [Routing & controllers](./02-routing-and-controllers.md) — route definitions, intents, controllers, render modes
+3. [Middleware](./03-middleware.md) — `beforeLoad` / `afterLoad`, redirect / rewrite / deny
+4. [Rendering & hydration](./04-rendering-and-hydration.md) — SSR / CSR / Prerender, `PrefetchedIntents`
+5. [Internationalization](./05-i18n.md) — `locale`, `Translator`, dictionary loading, RTL
+6. [HTTP client](./06-http-client.md) — `HttpClient` subclassing, interceptors, `HttpError`
+7. [DI container](./07-di-container.md) — registration, scopes, `DEP_KEYS`, dispose
+8. [Observability](./08-observability.md) — `Logger`, `EventRecorder`, impression tracking, `ReportCallback`
+9. [Server & deployment](./09-server-and-deployment.md) — `createServer`, proxy, adapters, Vite plugin
+10. [Features, platform, PWA](./10-features-platform-pwa.md) — feature flags, platform detection, PWA mode
+
+### Engineer working on an existing app — jump to practice
+
+Cross-cutting concerns and conventions. Read after you understand the basics.
+
+- [Project structure](./engineering/project-structure.md) — recommended layout, `bootstrap.ts` splitting, single source of truth
+- [Testing](./engineering/testing.md) — controllers, middleware, scoped DI, mocking the framework
+- [CI & release flow](./engineering/ci-release-flow.md) — changesets, the bundled release workflow, version reconciliation
+
+### Hit a problem — go to pitfalls
+
+Each entry is **symptom → root cause → fix**, kept short.
+
+- [SSR hydration mismatch](./pitfalls/ssr-hydration-mismatch.md)
+- [SSR vs CSR globals](./pitfalls/ssr-vs-csr-globals.md)
+- [Redirect vs rewrite](./pitfalls/redirect-vs-rewrite.md)
+- [Proxy binary payloads](./pitfalls/proxy-binary-payloads.md)
+- [Container scope leak](./pitfalls/container-scope-leak.md)
+- [i18n bundle size](./pitfalls/i18n-bundle-size.md)
+
+### Extending the framework — advanced recipes
+
+Each recipe is a complete, runnable extension example with explanation.
+
+- [Custom action handler](./advanced/custom-action-handler.md) — beyond `FlowAction` / `ExternalUrlAction`
+- [Custom event recorder](./advanced/custom-event-recorder.md) — wire Sentry / Datadog / your own pipeline
+- [Custom adapter](./advanced/custom-adapter.md) — target a new platform
+- [Inline proxy codegen](./advanced/inline-proxy-codegen.md) — generate self-contained proxy routes for serverless / edge
+- [Multi-tenant scopes](./advanced/multi-tenant-scopes.md) — per-tenant DI containers
+
+## At-a-glance
+
+```
+URL/Action → Router.resolve()
+          → beforeLoad chain   (NavigationContext: redirect/rewrite/deny/next)
+          → IntentDispatcher   (controller.execute() → Page; fallback() on error)
+          → afterLoad chain    (PostLoadContext)
+          → render             (SSR: HTML + serialized PrefetchedIntents; CSR: shell)
+```
+
+The same `bootstrap()` runs on the server and in the browser. SSR serializes prefetched intent results into HTML; the browser deserializes them into `PrefetchedIntents` so the first client navigation reuses server results without a refetch.
+
+## Conventions used in these docs
+
+- **Code blocks** are runnable as written unless a comment says otherwise.
+- **File paths** are relative to the project root (the directory containing `vite.config.ts`).
+- **`vp`** is the [Vite+](https://github.com/voidzero-dev/setup-vp) CLI. Use it instead of calling `pnpm` / `npm` / `vitest` / `tsdown` directly.
+- **`@finesoft/front`** is the only import surface for application code. Internal packages (`core`, `browser`, `ssr`, `server`) are bundled in and not published.