@finesoft/front 0.1.76 → 0.1.78

package/docs/08-observability.md

@@ -0,0 +1,290 @@
+# 8. Observability
+
+Three primitives, each composable, each replaceable:
+
+- **`Logger`** — line-oriented (debug/info/warn/error)
+- **`EventRecorder`** — structured event records (`{ name, fields }`)
+- **`ReportCallback`** — fan-out of `warn`/`error` logs to external monitoring
+
+Plus impression tracking via `IntersectionImpressionObserver`.
+
+## Logger
+
+The base `ConsoleLogger` writes to `console.{debug,info,warn,error}` with a category prefix. Scoped loggers add nested prefixes.
+
+```ts
+import { ConsoleLogger } from "@finesoft/front";
+
+const logger = new ConsoleLogger("app");
+logger.info("hello"); // [app] hello
+
+const auth = logger.scope("auth");
+auth.warn("token expired"); // [app:auth] token expired
+```
+
+Levels: `debug`, `info`, `warn`, `error`. The framework calls `warn`/`error` on its own logger for internal failures (failed guards, dispatch errors).
+
+### Replacing the framework logger
+
+```ts
+import { DEP_KEYS } from "@finesoft/front";
+
+framework.container.register(DEP_KEYS.LOGGER, () => myLogger);
+framework.container.register(DEP_KEYS.LOGGER_FACTORY, () => ({
+    create(category) {
+        return myLoggerImpl.scope(category);
+    },
+}));
+```
+
+## `ReportCallback` — forwarding logs to monitoring
+
+The cleanest way to ship `warn`/`error` logs to Sentry / Datadog / your own collector:
+
+```ts
+import { Framework, type ReportCallback } from "@finesoft/front";
+
+const reportCallback: ReportCallback = (level, category, args) => {
+    Sentry.captureMessage(`[${category}] ${args.join(" ")}`, level);
+};
+
+const framework = Framework.create({
+    reportCallback,
+    // ...
+});
+```
+
+How it works:
+
+- `Framework.create({ reportCallback })` installs `ReportingLoggerFactory` over `ConsoleLogger`
+- All `logger.warn(...)` and `logger.error(...)` calls fire the callback **and** continue to the console
+- `debug` and `info` are not forwarded (avoid burying signal in volume)
+- The callback runs inside `try/catch` — a failure in the reporter cannot crash the framework
+
+### Categories
+
+Each `logger.scope("auth")` becomes a category passed to the callback. Use them for routing in your monitoring system:
+
+```ts
+reportCallback(level, category, args) {
+    if (category.startsWith("auth")) {
+        sentry.captureMessage(/* go to auth project */);
+    } else {
+        sentry.captureMessage(/* default project */);
+    }
+}
+```
+
+### Anti-spam
+
+`ReportCallback` runs every time. If you have a hot loop logging the same warning a thousand times, you'll send a thousand events. Add deduplication in the callback itself:
+
+```ts
+const seen = new Map<string, number>();
+const reportCallback: ReportCallback = (level, category, args) => {
+    const key = `${category}:${args[0]}`;
+    const now = Date.now();
+    const last = seen.get(key) ?? 0;
+    if (now - last < 60_000) return; // 1 per minute per (category, message)
+    seen.set(key, now);
+    Sentry.captureMessage(/* ... */);
+};
+```
+
+## `EventRecorder` — structured events
+
+When you want events with fields, not free-form log lines, use `EventRecorder`.
+
+```ts
+import { Framework, ConsoleEventRecorder, type EventRecorder } from "@finesoft/front";
+
+const recorder: EventRecorder = new ConsoleEventRecorder();
+const framework = Framework.create({ eventRecorder: recorder });
+
+// Anywhere:
+recorder.record({
+    name: "PageView",
+    fields: { url: "/products/42", referrer: "/search?q=widget" },
+});
+```
+
+### Built-in events
+
+The framework records `PageView` automatically via `framework.didEnterPage(page)`. This fires:
+
+- After every successful navigation (SSR + CSR)
+- With fields: `{ intentId, url, renderMode }`
+
+### Composing recorders
+
+`CompositeEventRecorder` fans events to multiple sinks:
+
+```ts
+import { ConsoleEventRecorder, CompositeEventRecorder } from "@finesoft/front";
+
+const recorder = new CompositeEventRecorder([
+    new ConsoleEventRecorder(), // dev visibility
+    productionAnalyticsRecorder, // ship to backend
+]);
+```
+
+If one recorder throws, the others still receive the event.
+
+### Adding common fields
+
+`WithFieldsRecorder` decorates another recorder, prepending fields to every event:
+
+```ts
+import { WithFieldsRecorder, ConsoleEventRecorder } from "@finesoft/front";
+
+const recorder = new WithFieldsRecorder(new ConsoleEventRecorder(), [
+    { getFields: () => ({ app: "myApp", version: "1.0.0" }) },
+    { getFields: () => ({ userId: getCurrentUserId() }) },
+]);
+
+recorder.record({ name: "Click", fields: { id: "buy" } });
+// → { app, version, userId, id }
+```
+
+Use this for session-scoped fields you don't want to repeat in every `record()` call.
+
+### Building your own recorder
+
+Implement the `EventRecorder` interface:
+
+```ts
+import type { EventRecorder, EventRecord } from "@finesoft/front";
+
+class HttpEventRecorder implements EventRecorder {
+    constructor(private endpoint: string) {}
+    record(event: EventRecord): void {
+        // fire-and-forget; do NOT await — record() shouldn't block UI
+        navigator.sendBeacon(this.endpoint, JSON.stringify(event));
+    }
+    destroy(): void {
+        // flush, close connections, etc.
+    }
+}
+```
+
+See [advanced/custom-event-recorder](./advanced/custom-event-recorder.md) for batching, retries, and lifecycle handling.
+
+## Impression tracking
+
+Track when elements enter the viewport using `IntersectionObserver` plumbing:
+
+```ts
+import { IntersectionImpressionObserver, type EventRecorder } from "@finesoft/front";
+
+const observer = new IntersectionImpressionObserver((entries) => {
+    for (const entry of entries) {
+        recorder.record({
+            name: "Impression",
+            fields: { id: entry.id, ...entry.metadata },
+        });
+    }
+});
+
+// Attach to an element when it mounts
+observer.observe(productCardElement, "product-card-123", {
+    category: "featured",
+    position: 3,
+});
+
+// Detach when it unmounts
+observer.unobserve(productCardElement);
+
+// On app teardown
+observer.destroy();
+```
+
+The observer fires the callback once per element per visibility transition. It does not deduplicate across observe/unobserve cycles — your callback should decide whether to record again.
+
+## Error handling via `fallback`
+
+A controller error becomes a recorded event automatically:
+
+```ts
+class HomeController extends BaseController<{}, HomePage> {
+    readonly intentId = "home";
+
+    async execute(_params, container) {
+        const api = container.resolve<UserApi>("userApi");
+        return { kind: "home", users: await api.list() };
+    }
+
+    fallback(_params, error) {
+        // 1. framework logs the error via its logger (→ reportCallback)
+        // 2. you return a degraded page
+        return { kind: "home", users: [], degraded: true };
+    }
+}
+```
+
+Order of operations on error:
+
+1. `execute()` throws.
+2. `BaseController` catches, calls `framework.logger.error("[controller:home]", error)`.
+3. Logger fires `reportCallback("error", "controller:home", [error])` → Sentry.
+4. `fallback()` returns a `Page` of your design.
+5. Render proceeds with the fallback page (HTTP 200 by default).
+
+To set a non-200 status, return a page with an "error" marker and check it in an `afterLoad` guard:
+
+```ts
+afterLoad: [
+    (ctx) => {
+        if ("degraded" in ctx.page && ctx.page.degraded) {
+            return deny(503, "Service degraded");
+        }
+        return next();
+    },
+],
+```
+
+## Metrics (counters / gauges / timing)
+
+The framework's `MetricsClient` is minimal:
+
+```ts
+import { DEP_KEYS } from "@finesoft/front";
+
+const metrics = framework.container.resolve(DEP_KEYS.METRICS);
+
+metrics.increment("requests.total");
+metrics.increment("login.failed", { reason: "wrong_password" });
+metrics.gauge("queue.depth", 17);
+metrics.timing("render.duration", 142);
+```
+
+The default implementation is a no-op. Register your own:
+
+```ts
+framework.container.register(DEP_KEYS.METRICS, () => new StatsdMetrics(/* ... */));
+```
+
+For most apps, `EventRecorder` is enough — your analytics backend already aggregates events into metrics.
+
+## Trace IDs and request correlation
+
+A common pattern: tag every log and event with a per-request trace id.
+
+```ts
+// beforeLoad guard
+function traceIdGuard(ctx) {
+    const traceId = ctx.getHeader("x-request-id") ?? crypto.randomUUID();
+    ctx.container.register("traceId", () => traceId);
+    ctx.container.register(
+        DEP_KEYS.EVENT_RECORDER,
+        () => new WithFieldsRecorder(baseRecorder, [{ getFields: () => ({ traceId }) }]),
+    );
+    return next();
+}
+```
+
+Register the scoped recorder via `WithFieldsRecorder` so every event in this request automatically carries the trace id.
+
+## Next
+
+- [Server & deployment](./09-server-and-deployment.md) — where these primitives meet HTTP
+- [Advanced: custom event recorder](./advanced/custom-event-recorder.md) — production-grade implementation

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