@finesoft/front 0.5.1 → 0.5.2

package/docs/advanced/custom-adapter.md

@@ -1,264 +1,12 @@
-# Advanced: custom adapter
+# Custom deployment adapters
 
-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:
+A build adapter implements Adapter from the Vite entry. Its job is to emit deployment files and bind platform Request/Response and cleanup capabilities. Runtime SSR uses createSSRHandler from the SSR entry. Keep one shared response assembler; custom generators must preserve request context, status, headers, cookies, locale and redirects. The internal buildBundle/generateSSREntry helpers are private implementation, not exported public APIs. The repository’s Node/Cloudflare/Netlify/Vercel adapters are reference implementations; validate emitted code in the target runtime before claiming support.
 
 ```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(),
-});
+import type { Adapter, AdapterContext } from "@finesoft/front";
+// Supply { name, async build(context: AdapterContext) { ... } } as the Vite adapter.
+// Runtime module:
+import { createSSRHandler } from "@finesoft/front";
 ```
 
-## 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
+`createSSRHandler` returns the execution owner with `fetch(request, bindings)` and `dispose()`, replacing `createSSRHost(...).handle(...)`. Standard hosts set `ownRenderers: true`: shutdown drains response assembly, then disposes each owned renderer once. Without this option, renderers remain caller-owned. `createSSRRender` owns native rendering and Runtime shutdown itself.

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

@@ -1,318 +1,13 @@
-# Advanced: custom event recorder
+# Event recording
 
-Build a production-grade `EventRecorder` that batches, retries, and survives navigation. This recipe assumes you've read [chapter 8: observability](../08-observability.md).
+Portable operations emit structured events through their execution context; the runtime accepts a recorder.
 
-## 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
+## Recorder / 记录器
 
 ```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));
-    };
-}
+import { ConsoleEventRecorder, createRuntime } from "@finesoft/front";
+const runtime = createRuntime({ app, recorder: new ConsoleEventRecorder() });
+// In a handler: context.record("cart.updated", { itemCount: 3 });
 ```
 
-## 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/`
+Record business outcomes without copying credentials, raw request bodies or private page data. Recorder failures are isolated from execution. Browser impressions require the explicit browser observer; portable core only defines the event contract.