@finesoft/front 0.1.76 → 0.1.78

package/docs/advanced/custom-adapter.md

@@ -0,0 +1,264 @@
+# Advanced: custom adapter
+
+Target a platform the framework doesn't ship with. The bundled adapters are Node, Vercel, Cloudflare, Netlify, and Static. Anything else — Deno Deploy, Bun, AWS Lambda, custom on-prem — is a custom adapter.
+
+This recipe walks through writing one end-to-end. The pattern: emit a platform-specific entry file at build time, then point that entry at the framework's SSR + proxy pipeline.
+
+## What an adapter does
+
+At build time:
+
+1. Bundle the SSR entry (`src/ssr.ts`) into a single JS file with all dependencies inlined.
+2. Bundle the client entry into the platform's expected shape (`dist/client/` for most).
+3. Emit a **platform-specific entry** that:
+    - Imports the SSR bundle
+    - Receives requests in the platform's native shape (Request, Lambda event, etc.)
+    - Calls `createServer({ ssrEntry, proxies })` and serves the response
+
+The framework provides `buildBundle`, `generateSSREntry`, `copyStaticAssets`, and `prerenderRoutes` helpers in `packages/server/src/adapters/shared.ts`. Use them — they handle the heavy lifting consistently across all adapters.
+
+## Example: Deno Deploy adapter
+
+Deno Deploy runs ES modules with web-standard Request/Response. Workflow is similar to Cloudflare Workers but with native Deno APIs available.
+
+### Adapter interface
+
+```ts
+// src/lib/adapters/deno-deploy.ts
+import type { AdapterDefinition, AdapterContext } from "@finesoft/front";
+import { buildBundle, copyStaticAssets, generateSSREntry, prerenderRoutes } from "@finesoft/front";
+
+export const denoDeployAdapter: AdapterDefinition = {
+    name: "deno-deploy",
+
+    async build(ctx: AdapterContext): Promise<void> {
+        // 1. Bundle SSR
+        const ssrEntry = generateSSREntry(ctx, {
+            // Deno supports native fetch / URL / Response, so no shims needed
+            external: [],
+        });
+        await buildBundle(ctx, {
+            entry: ssrEntry,
+            outFile: "dist/server.js",
+            format: "esm",
+        });
+
+        // 2. Copy static assets
+        copyStaticAssets(ctx, "dist/client", "dist/static");
+
+        // 3. Prerender any prerender routes
+        await prerenderRoutes(ctx);
+
+        // 4. Emit the Deno entry
+        writeEntryFile(
+            ctx,
+            "dist/main.ts",
+            `
+            import { createServer } from "./server.js";
+            const app = createServer({
+                ssrEntry: "./server.js",
+                staticDir: "./static",
+            });
+            Deno.serve(app.fetch);
+        `,
+        );
+    },
+};
+```
+
+### Registering
+
+```ts
+// vite.config.ts
+import { finesoftFrontViteConfig } from "@finesoft/front";
+import { denoDeployAdapter } from "./src/lib/adapters/deno-deploy";
+
+export default {
+    plugins: [
+        finesoftFrontViteConfig({
+            ssr: { entry: "src/ssr.ts" },
+            adapter: denoDeployAdapter,
+        }),
+    ],
+};
+```
+
+The `adapter` option accepts either a string (built-in) or an `AdapterDefinition` (custom).
+
+## Adapter context
+
+The `AdapterContext` passed to `build()` exposes:
+
+```ts
+interface AdapterContext {
+    root: string; // absolute path to project root
+    outDir: string; // absolute path to dist directory
+    ssrEntryPath: string; // resolved path to src/ssr.ts
+    routes: RouteDefinition[]; // routes from bootstrap (for prerendering)
+    proxies: ProxyRouteConfig[]; // proxy config from finesoftFrontViteConfig
+    isr: IsrConfig | null; // ISR config if enabled
+    env: Record<string, string>; // build-time env vars
+}
+```
+
+You don't typically read all of these — `buildBundle` and `generateSSREntry` take what they need.
+
+## Common patterns
+
+### Edge runtime (Workers / Deno / Bun)
+
+Standard Web APIs (Request, Response, fetch). Bundle as ESM, target `webworker`. Most edge runtimes accept a default-exported handler:
+
+```ts
+export default {
+    async fetch(request, env) {
+        return app.fetch(request, env);
+    },
+};
+```
+
+The Cloudflare adapter in `packages/server/src/adapters/cloudflare.ts` is the canonical reference.
+
+### Lambda-style (AWS Lambda, GCF, Azure Functions)
+
+Platform-specific event shapes. Convert to/from `Request`:
+
+```ts
+import { app } from "./server.js";
+
+export const handler = async (event: APIGatewayProxyEventV2) => {
+    const request = lambdaEventToRequest(event);
+    const response = await app.fetch(request);
+    return responseToLambdaResult(response);
+};
+```
+
+Each cloud's SDK ships type definitions and helpers for the event-to-request conversion. Lift-and-shift them; don't reinvent.
+
+### Multi-process server (Bun cluster, PM2)
+
+Bun and modern Node support `cluster`-style multi-process serving for CPU parallelism:
+
+```ts
+import { app } from "./server.js";
+import { serve } from "@hono/node-server";
+
+const port = parseInt(process.env.PORT ?? "3000", 10);
+serve({ fetch: app.fetch, port });
+```
+
+Each process is independent. The ISR cache is per-process — for a true shared cache, put a CDN in front.
+
+## Static (no server)
+
+`adapter: "static"` is the simplest target — everything is prerendered, nothing runs at request time.
+
+```ts
+export const staticAdapter: AdapterDefinition = {
+    name: "static",
+    async build(ctx) {
+        // Skip SSR bundle entirely
+        await prerenderRoutes(ctx); // every route must have renderMode: "prerender"
+        copyStaticAssets(ctx, "dist/client", "dist/static");
+        // No server entry — just the static files
+    },
+};
+```
+
+Verify every route is prerenderable:
+
+```ts
+if (!ctx.routes.every((r) => r.renderMode === "prerender")) {
+    throw new Error("Static adapter requires every route to be renderMode: 'prerender'");
+}
+```
+
+## Auto-detection extension
+
+The built-in `"auto"` adapter checks env vars in order:
+
+```ts
+function detectAdapter(env: Record<string, string>): string {
+    if (env.VERCEL === "1") return "vercel";
+    if (env.CF_PAGES === "1") return "cloudflare";
+    if (env.NETLIFY === "true") return "netlify";
+    return "node";
+}
+```
+
+If your custom adapter has a known env signature, you can wrap auto-detection yourself in your project's `vite.config.ts`:
+
+```ts
+function pickAdapter() {
+    if (process.env.DENO_DEPLOYMENT_ID) return denoDeployAdapter;
+    return "node";
+}
+
+finesoftFrontViteConfig({
+    adapter: pickAdapter(),
+});
+```
+
+## Testing the adapter
+
+Integration test: run the build, then exercise the emitted entry:
+
+```ts
+import { describe, test, expect } from "vite-plus/test";
+import { build } from "vite";
+import { denoDeployAdapter } from "./deno-deploy";
+
+describe("denoDeployAdapter", () => {
+    test("emits a Deno-compatible entry", async () => {
+        await build({
+            root: "test/fixtures/basic",
+            plugins: [
+                finesoftFrontViteConfig({
+                    ssr: { entry: "src/ssr.ts" },
+                    adapter: denoDeployAdapter,
+                }),
+            ],
+        });
+
+        const entry = await readFile("test/fixtures/basic/dist/main.ts", "utf-8");
+        expect(entry).toContain("Deno.serve");
+        expect(entry).toContain("./server.js");
+    });
+});
+```
+
+Smoke test the runtime: spin up the actual platform locally and hit `/`. This catches platform-specific quirks (CORS, header normalization, body decoding) that unit tests don't.
+
+## Gotchas
+
+### Don't bundle Node built-ins on edge runtimes
+
+`fs`, `path`, `http`, etc. don't exist on Workers / Deno. `generateSSREntry` accepts an `external` list — set it to the platform-incompatible modules so the bundler errors out at build time rather than the deploy crashing at request time.
+
+### `process.env` works differently per platform
+
+- Node, Vercel: `process.env.FOO`
+- Cloudflare Workers: secrets via `env` arg to `fetch()`
+- Deno: `Deno.env.get("FOO")`
+
+The framework handles `process.env` for declared proxy auth keys, but for your own runtime env reads, wrap them in a platform-aware helper.
+
+### File system access for assets
+
+If you rely on reading files at request time (rare; most serve through `staticDir`), only Node-like adapters have native fs access. For edge runtimes, embed assets into the bundle or proxy through KV stores.
+
+## Submitting upstream
+
+If your adapter targets a popular platform that doesn't ship with the framework, consider opening a PR. Adapters live in `packages/server/src/adapters/` and follow a consistent structure — `cloudflare.ts` is the cleanest reference.
+
+The framework's adapter API is intentionally small. Keep your contribution minimal:
+
+- One file in `adapters/`
+- One entry in `auto.ts` for auto-detection (if applicable)
+- One section in this doc
+
+## Related
+
+- The bundled adapters: `packages/server/src/adapters/`
+- The shared helpers you'll use: `packages/server/src/adapters/shared.ts`
+- [Chapter 9: Server & deployment](../09-server-and-deployment.md) — what the adapters wrap

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/`