@finesoft/front 0.1.75 → 0.1.77

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

@@ -0,0 +1,318 @@
+# Advanced: custom event recorder
+
+Build a production-grade `EventRecorder` that batches, retries, and survives navigation. This recipe assumes you've read [chapter 8: observability](../08-observability.md).
+
+## Goals
+
+A good recorder:
+
+- **Doesn't block.** `record()` returns synchronously; transmission happens in the background.
+- **Batches.** One HTTP request per N events or T seconds, not per event.
+- **Survives navigation.** Pending events flush on page unload via `sendBeacon`.
+- **Drops gracefully.** Network failures don't crash the app; events that fail to send don't pile up forever.
+- **Lifecycle-aware.** `destroy()` flushes everything before disposal.
+
+## Skeleton
+
+```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) {
+            // overflow protection — drop the oldest to bound memory
+            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 — drop. 5xx — re-queue at the front.
+                if (resp.status >= 500) this.queue.unshift(...batch);
+            }
+        } catch {
+            // network failure — re-queue
+            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));
+    };
+}
+```
+
+## Why each piece exists
+
+### `keepalive: true`
+
+Tells the browser the request should complete even if the page is navigating away. Has a max body size (~64 KB) but works across navigation. Pair with `sendBeacon` for unload — beacons are smaller and more reliable for that case.
+
+### `pagehide` and `beforeunload`
+
+`pagehide` fires when the page enters the bfcache (back/forward navigation). `beforeunload` fires on regular navigation/close. Both should flush pending events. Some browsers fire one and not the other, so listen for both.
+
+### `keepalive` vs `sendBeacon`
+
+| Method                 | Body limit | Returns response? | When                            |
+| ---------------------- | ---------- | ----------------- | ------------------------------- |
+| `fetch(..keepalive)`   | ~64KB      | Yes               | Periodic flush during page life |
+| `navigator.sendBeacon` | ~64KB      | No                | Final flush on unload           |
+
+Use both: periodic `fetch` for visibility into successes/failures, `sendBeacon` as the final escape hatch.
+
+### Re-queue on 5xx, drop on 4xx
+
+A 5xx is the server's fault — retry later. A 4xx is your fault — retrying won't help, and infinite retry would flood the server. Drop the batch and move on.
+
+### Overflow protection
+
+If the network is down for hours and your app keeps emitting events, the queue would grow without bound. `maxQueueSize` caps it; oldest events drop when new ones arrive. This trades completeness for memory safety — pick the size based on how much you can afford to lose vs how much memory you can spend.
+
+## Wiring it up
+
+```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: /* ... */,
+});
+```
+
+The `CompositeEventRecorder` wraps both so events go to console (for dev visibility) **and** to your backend.
+
+## Adding cross-cutting fields
+
+Decorate with `WithFieldsRecorder` to attach session-level fields:
+
+```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` runs **per event**, so user-state changes between events reflect correctly.
+
+## Server-side recording
+
+The framework records `PageView` for every SSR request. If you want to capture those server-side:
+
+```ts
+// src/ssr.ts
+import { createSSRRender } from "@finesoft/front";
+import { HttpEventRecorder } from "./lib/recorders/http-recorder";
+
+// Single recorder shared across all SSR requests
+const serverRecorder = new HttpEventRecorder({
+    endpoint: "https://internal-events.example/v1/events",
+    batchSize: 100, // server batches more aggressively
+    flushIntervalMs: 1000,
+});
+
+export const render = createSSRRender({
+    bootstrap,
+    frameworkConfig: {
+        eventRecorder: serverRecorder,
+    },
+    /* ... */
+});
+
+process.on("SIGTERM", () => serverRecorder.destroy());
+```
+
+Server-side recorders should:
+
+- Share a single instance across requests (don't construct per-request)
+- Use a larger batch / longer flush interval (no UI to block)
+- Wire `destroy()` into graceful shutdown so in-flight events flush
+
+## Integration with Sentry / Datadog
+
+If you use both a `ReportCallback` (for `warn`/`error` logs to Sentry) and an `EventRecorder` (for structured events to your backend), keep them separate:
+
+```ts
+Framework.create({
+    reportCallback: (level, category, args) => {
+        Sentry.captureMessage(`[${category}] ${args.join(" ")}`, level);
+    },
+    eventRecorder: new CompositeEventRecorder([
+        new HttpEventRecorder({ endpoint: "/api/events" }),
+        // Optionally: forward to Datadog too
+        new DatadogEventRecorder({ apiKey: env.DD_API_KEY }),
+    ]),
+});
+```
+
+Different sinks for different purposes — errors go to Sentry for triage, structured events go to your warehouse for analytics. Don't try to make one recorder do both.
+
+## Sampling
+
+For high-traffic apps, sample events:
+
+```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);
+// Records 10% of events
+```
+
+Sample at the recorder level, not the call site — call sites shouldn't know whether they're being sampled.
+
+## Testing
+
+```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));
+
+        // simulate the next flush
+        await (recorder as any).flush();
+
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+});
+```
+
+## Related
+
+- [Chapter 8: Observability](../08-observability.md) — base primitives and built-in events
+- The framework's own composite/with-fields recorders: `packages/core/src/metrics/`

package/docs/advanced/inline-proxy-codegen.md

@@ -0,0 +1,200 @@
+# Advanced: inline proxy codegen
+
+For serverless and edge deployments where you want proxy logic inlined into the function bundle — no runtime call to `registerProxyRoutes`, no extra dependencies — the framework exposes `generateProxyCode`.
+
+## Use case
+
+You're deploying to Cloudflare Workers / Vercel Edge / AWS Lambda@Edge. Each function has:
+
+- Tight cold-start budget
+- Cold-bundle-size budget (Workers: 1 MB compressed)
+- No `process.env` in some runtimes
+
+Importing the proxy router and its support files (validators, Hono integration) adds bytes. `generateProxyCode` emits **only** the lines you need for the routes you declared. The output is self-contained: a few `app.get(...)` / `app.all(...)` calls plus a single `_sanitizeProxyPath` helper.
+
+## Generated output
+
+Given this input:
+
+```ts
+import { generateProxyCode } from "@finesoft/front";
+
+const code = generateProxyCode([
+    {
+        prefix: "/api",
+        target: "https://upstream.example",
+        headers: { "X-App": "myapp" },
+        auth: { type: "bearer", envKey: "API_TOKEN" },
+        cache: "max-age=60",
+    },
+]);
+
+console.log(code);
+```
+
+You get something like:
+
+```js
+// ─── 框架声明式代理路由 ───
+function _sanitizeProxyPath(raw) {
+    if (raw.length > 2048) return null;
+    try {
+        if (decodeURIComponent(raw) !== raw) return null;
+    } catch {
+        return null;
+    }
+    if (raw.startsWith("//")) return null;
+    if (!/^[/\w.\-~%:@!$&'()*+,;=]*$/.test(raw)) return null;
+    return raw.startsWith("/") ? raw : "/" + raw;
+}
+
+app.all("/api/*", async (c) => {
+    const _sub = _sanitizeProxyPath(c.req.path.replace("/api", ""));
+    if (!_sub) return c.text("Invalid path", 400);
+    const _target = new URL(_sub, "https://upstream.example");
+    if (_target.origin !== "https://upstream.example") return c.text("Invalid proxy target", 400);
+    const _reqUrl = new URL(c.req.url);
+    _reqUrl.searchParams.forEach((v, k) => _target.searchParams.set(k, v));
+    const _headers = { "X-App": "myapp" };
+    const _token =
+        (typeof process !== "undefined" && process.env && process.env["API_TOKEN"]) || "";
+    if (_token) _headers.Authorization = "Bearer " + _token;
+    try {
+        const _resp = await fetch(_target.toString(), { headers: _headers, redirect: "manual" });
+        const _cl = _resp.headers.get("Content-Length");
+        if (_cl && parseInt(_cl, 10) > 10485760) {
+            return c.text("Proxy response too large", 502);
+        }
+        const _body = await _resp.arrayBuffer();
+        if (_body.byteLength > 10485760) {
+            return c.text("Proxy response too large", 502);
+        }
+        const _rh = { "Content-Type": _resp.headers.get("Content-Type") || "application/json" };
+        if ("max-age=60") _rh["Cache-Control"] = "max-age=60";
+        return c.newResponse(_body, _resp.status, _rh);
+    } catch (_e) {
+        console.error("[Proxy /api]", _e);
+        return c.json({ error: "Proxy request failed" }, 502);
+    }
+});
+```
+
+Everything is inline. No imports from `@finesoft/front` for the proxy path. Drop this into your function bundle alongside the SSR entry.
+
+## When to use codegen vs runtime registration
+
+| Concern                                   | Runtime (`registerProxyRoutes`) | Codegen (`generateProxyCode`)               |
+| ----------------------------------------- | ------------------------------- | ------------------------------------------- |
+| Long-lived server (Node, Workers)         | ✅ preferred                    | ✅ also fine                                |
+| Tiny edge functions (Lambda@Edge)         | Heavier import                  | ✅ minimal                                  |
+| Need to update routes without redeploying | ✅ change config, restart       | ❌ redeploy required                        |
+| Config from a remote service              | ✅ supported                    | ❌ codegen runs at build time               |
+| Multiple proxies sharing helpers          | ✅ shared at runtime            | Code duplication unless you dedupe yourself |
+
+Use codegen specifically when bundle size matters. For most deployments, the runtime path is fine.
+
+## Build-time integration
+
+A typical setup:
+
+```ts
+// scripts/build-proxy.mjs
+import { generateProxyCode } from "@finesoft/front";
+import { writeFile } from "node:fs/promises";
+
+const code = generateProxyCode([
+    { prefix: "/api/users", target: "https://users.internal" },
+    { prefix: "/api/products", target: "https://products.internal", cache: "max-age=30" },
+    {
+        prefix: "/api/orders",
+        target: "https://orders.internal",
+        auth: { type: "bearer", envKey: "ORDERS_TOKEN" },
+    },
+]);
+
+const wrapper = `
+import { Hono } from "hono";
+const app = new Hono();
+
+${code}
+
+export default app;
+`;
+
+await writeFile("dist/proxy.js", wrapper, "utf8");
+```
+
+Then import `./proxy.js` from your serverless function entry:
+
+```ts
+// dist/main.ts (for Cloudflare Worker)
+import proxyApp from "./proxy.js";
+import ssrApp from "./ssr-bundle.js";
+
+const app = new Hono();
+app.route("/", proxyApp);
+app.route("/", ssrApp);
+
+export default app;
+```
+
+## What the generated code does for you
+
+The generated handler enforces the same guarantees as the runtime path:
+
+- **SSRF protection**: path validation rejects encoded chars, `//` prefix, non-allowed characters
+- **Open-redirect protection**: `target.origin` must match the configured target's origin
+- **10 MB response size limit**: `Content-Length` fast-reject + `byteLength` actual-bytes check
+- **Binary integrity**: `arrayBuffer()` forwarding (no UTF-8 decoding)
+- **Auth from env**: reads `process.env[envKey]` at request time
+
+The framework's test suite asserts **parity** between runtime and generated code with these checks:
+
+```ts
+// packages/server/test/proxy.test.ts
+test("generated proxy code embeds the same response size limit as runtime (parity)", () => {
+    const code = generateProxyCode([{ prefix: "/api", target: "https://upstream.example" }]);
+
+    const MAX = String(10 * 1024 * 1024);
+    expect(code).toContain(`parseInt(_cl, 10) > ${MAX}`);
+    expect(code).toContain(`_body.byteLength > ${MAX}`);
+});
+```
+
+If you patch the runtime path's size limit, the generated code's limit is updated in lockstep.
+
+## Caveats
+
+### `process.env` may not exist
+
+The generated code guards with `typeof process !== "undefined"`. On runtimes without `process` (some edge environments), the auth header is simply not added — the upstream sees no auth.
+
+For platforms like Cloudflare Workers that inject env via function args instead of `process.env`, you'll need to either:
+
+- Wrap the generated code to inject the auth header from the worker's env arg
+- Replace the auth section after generation with the platform-appropriate access
+
+### No retries, no breakers
+
+The generated handler does one `fetch` and bubbles failures up as `502 Proxy request failed`. For retry / breaker logic, write your own proxy code — `generateProxyCode` is intentionally minimal.
+
+### Multiple proxies share helper code
+
+`_sanitizeProxyPath` is emitted once at the top of the generated string. Multiple `app.all` calls share it. If you `generateProxyCode` separately for each route and concatenate, you'll get the helper repeated — call it once with all routes.
+
+### Validation at generation time
+
+`generateProxyCode` runs the same `validateConfig` as `registerProxyRoutes`. Invalid configs throw at build time:
+
+```ts
+generateProxyCode([{ prefix: "/api", target: "file:///etc/passwd" }]);
+// Error: [proxy] target must start with "https://" or "http://": "file:///etc/passwd"
+```
+
+This catches config errors before the deploy ships.
+
+## Related
+
+- [Chapter 9: Server & deployment — proxy routes](../09-server-and-deployment.md#proxy-routes)
+- The implementation: `packages/server/src/proxy.ts`
+- The parity test: `packages/server/test/proxy.test.ts`