@finesoft/front 0.5.1 → 0.5.2

package/docs/02-routing-and-controllers.md

@@ -1,314 +1,236 @@
-# 2. Routing & controllers
+# Routes, controllers and typed pages
 
-The framework's routing layer maps URLs to **intents**, intents to **controllers**, and controllers produce **pages**. This chapter covers all three.
+All six templates load pages with `BaseController`, which remains a public API. `definePage` connects a controller factory or a function handler to a Web application. Both forms share the runtime, execution scopes and policies.
 
-## The mental model
+## Responsibilities
 
-```
-URL  ──Router.resolve()──▶  RouteMatch { intent, renderMode, guards }
-                                │
-                                ▼
-                       IntentDispatcher.dispatch(intent)
-                                │
-                                ▼
-                         Controller.execute()  →  Page
-```
+| API                               | Responsibility                                                                                  |
+| --------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `BaseController<TInput, TResult>` | Implement `execute`; inherited `perform` handles parameters, cancellation and `fallback`        |
+| `definePage({ id, create })`      | Declare the page-loading factory and provide reusable `route`, `leaf` and `bindView` references |
+| `defineWebApp`                    | Assemble page declarations, routes, guards and optional navigation structure                    |
+| Native page component             | Receive `page` data, render UI and handle interactions                                          |
 
-A route definition combines:
+Import controllers, pages, routes and public-data declarations from `@finesoft/front`.
 
-- A **path pattern** (`/products/:id`)
-- An **intent id** (logical name for the operation; one intent can have multiple routes)
-- A **controller instance** (where the page data is produced)
-- Optional **param codecs** (`params` / `query`) that validate and type the URL params
-- An optional **render mode** (`ssr` / `csr` / `prerender`)
-- Optional **guards** (`beforeLoad` / `afterLoad`)
+## Load a page with BaseController
 
-## Defining routes
+`src/lib/controllers/product.ts`:
 
 ```ts
-// src/bootstrap.ts
-import { type Framework, defineRoutes } from "@finesoft/front";
-import { HomeController } from "./lib/controllers/home";
-import { ProductController } from "./lib/controllers/product";
-import { authGuard } from "./lib/guards/auth";
-
-export function bootstrap(framework: Framework): void {
-    defineRoutes(framework, [
-        // Plain SSR route
-        { path: "/", intentId: "home", controller: new HomeController() },
-
-        // Dynamic segment
-        { path: "/products/:id", intentId: "product", controller: new ProductController() },
-
-        // CSR-only (server returns an empty shell)
-        {
-            path: "/dashboard",
-            intentId: "dashboard",
-            controller: new DashboardController(),
-            renderMode: "csr",
-        },
-
-        // Statically prerendered at build time
-        {
-            path: "/about",
-            intentId: "about",
-            controller: new AboutController(),
-            renderMode: "prerender",
-        },
-
-        // Protected route — reuses the home intent but gates with a guard
-        {
-            path: "/admin",
-            intentId: "home",
-            controller: new HomeController(),
-            beforeLoad: [authGuard],
-        },
-    ]);
+import { BaseController, DEP_KEYS } from "@finesoft/front";
+import { markPublic, type BasePage } from "@finesoft/front";
+
+export interface ProductPage extends BasePage {
+    pageType: "product";
+    product: { id: number; name: string };
 }
-```
 
-### Route options
+export class ProductController extends BaseController {
+    async execute({ params, context }): Promise<ProductPage> {
+        const logger = await context.get(DEP_KEYS.LOGGER_FACTORY);
+        logger.loggerFor("ProductController").info(`Loading product ${params.id}`);
+        context.record("product.load", { productId: params.id });
+
+        return markPublic(
+            {
+                id: String(params.id),
+                pageType: "product",
+                title: `Product ${params.id}`,
+                product: { id: params.id, name: `Product ${params.id}` },
+            },
+            { product: { id: true, name: true } },
+        );
+    }
 
-| Field        | Type                             | Notes                                                                    |
-| ------------ | -------------------------------- | ------------------------------------------------------------------------ |
-| `path`       | `string`                         | Path pattern with `:param` placeholders. Trailing `/` is normalized.     |
-| `intentId`   | `string`                         | Logical operation name. Used to register the controller.                 |
-| `controller` | `BaseController<TParams, TPage>` | Optional if the intent is already registered.                            |
-| `params`     | codec map                        | Validate/convert **path** params. Keys must appear in `path`. See below. |
-| `query`      | codec map                        | Validate/convert **query** params. Keys are open. See below.             |
-| `renderMode` | `"ssr" \| "csr" \| "prerender"`  | Default `"ssr"`. See [chapter 4](./04-rendering-and-hydration.md).       |
-| `beforeLoad` | `BeforeLoadGuard[]`              | Run before the controller. See [chapter 3](./03-middleware.md).          |
-| `afterLoad`  | `AfterLoadGuard[]`               | Run after the page is produced.                                          |
+    override fallback({ params }): ProductPage {
+        return markPublic(
+            {
+                id: String(params.id),
+                pageType: "product",
+                title: "Product unavailable",
+                product: { id: params.id, name: "Unavailable" },
+            },
+            { product: { id: true, name: true } },
+        );
+    }
+}
+```
+
+The framework maintains type imports, method annotations and base-class generics from the route declaration below; these are omitted in the initial source shown here. Run `vp dev`, `vp check` or the build to generate them. Types live in `.finesoft/controller-types.d.ts`, with no declaration block appended to the controller. See [automatic controller types](./11-navigation.md) for setup.
 
-### Path patterns
+Both methods receive one object: `execute({ params, query, context })` and `fallback({ params, query, context, error })`. Destructure only the fields you need. Query remains separate from path parameters and is inferred from the route's `query` schemas.
 
-- Static: `/about`
-- Parameterized: `/products/:id`, `/users/:userId/posts/:postId`
-- Optional param: `/blog/:slug?` matches both `/blog` and `/blog/hello`.
+This example uses local data; application controllers can call services from `execute`. `context` provides its `signal`, `fetch`, `get(token)` and `execute(operation, input)`. Pass `context.signal` to asynchronous request APIs so cancellation reaches the actual work.
 
-By default, path and query params arrive in `controller.execute(params, container)` as a **string-keyed object**. Attach codecs (next section) to validate and convert them.
+`fallback` runs when `execute` throws an ordinary error and still returns `ProductPage`; this example chooses to display an unavailable state. The default implementation rethrows so page loading can handle the error. Cancellation, `AbortError` and `ExecutionError("cancelled")` propagate without entering `fallback`. Runtime policies execute outside the controller, so policy rejection also bypasses controller recovery.
 
-## Typed route params
+## Register a factory, route and navigation target
 
-Codecs turn raw string params into validated, converted, **compile-time-typed** values. Built-ins cover the common cases with zero dependencies; any [Standard Schema](https://standardschema.dev) (zod, valibot, arktype, …) works too.
+`src/app-definition.ts`:
 
 ```ts
-import { defineRoutes, int, list, oneOf, optional, str, withDefault } from "@finesoft/front";
-
-defineRoutes(framework, [
-    {
-        path: "/products/:id",
-        intentId: "product",
-        controller: new ProductController(),
-        params: { id: int({ min: 1 }) }, // :id validated as a positive integer, converted to number
-        query: {
-            page: withDefault(int({ min: 1 }), 1), // ?page= → number, defaults to 1 when absent
-            sort: optional(oneOf(["asc", "desc"] as const)), // optional "asc" | "desc"
-            tags: list(str()), // ?tags=a&tags=b → string[]
-        },
-    },
-]);
+import { int } from "@finesoft/front";
+import { definePage, defineWebApp } from "@finesoft/front";
+import { ProductController } from "./lib/controllers/product";
+
+export const product = definePage({
+    id: "load-product",
+    create: () => new ProductController(),
+    routes: [{ path: "/products/:id", params: { id: int() } }],
+});
+export const target = product.leaf({ id: 42 });
+
+export const app = defineWebApp({
+    id: "example",
+    pages: [product],
+    getErrorPage: (status, message) => ({ id: String(status), pageType: "error", title: message }),
+});
 ```
 
-### Built-in codecs
+The page declaration owns the operation id; controllers do not repeat it. The URL `/products/42` is decoded by `int()`, so `execute` receives `params: { id: 42 }`. In application code, `product.leaf({ id: 42 })` retains the same parameter type.
 
-| Codec                   | Output        | Validates                                                   |
-| ----------------------- | ------------- | ----------------------------------------------------------- |
-| `str(opts?)`            | `string`      | `minLength` / `maxLength` / `pattern` (`RegExp`)            |
-| `int(opts?)`            | `number`      | integer + `min` / `max`                                     |
-| `num(opts?)`            | `number`      | finite number + `min` / `max`                               |
-| `bool()`                | `boolean`     | `"true" \| "1" \| "false" \| "0"`                           |
-| `oneOf([...] as const)` | literal union | membership                                                  |
-| `uuid()`                | `string`      | UUID v1–v5                                                  |
-| `list(item, opts?)`     | `T[]`         | multi-value query; each item via `item` + `min`/`max` count |
+`create` returns a new controller for each actual execution. Declaration, route discovery and reference helpers only read definitions; consuming a prefetched or retained page result also skips controller creation. Keep request identity in execution context or scoped providers, and page drafts in page instances.
 
-Modifiers wrap a codec (codecs stay plain serializable data — no chained `.optional()`):
+`id` is operation identity, `pageType` selects a view, and each leaf receives a fresh EntryId. `product.bindView("product", ProductView)` checks literal result page types without inferring one from the operation id. Retain `ProductPage.pageType: "product"` to get this check; a widened `BasePage.pageType: string` cannot constrain view names.
 
-- `optional(codec)` — missing input → `undefined`; renders the key as **optional** (`page?: T`).
-- `withDefault(codec, fallback)` — missing input → `fallback`; key stays required.
+Typed leaf parameters retain controller types. External URLs still require explicit codec decoding. Generics provide compile-time constraints, not runtime input validation, and cannot prove that an arbitrary codec matches business validation rules.
 
-### Validation = fall-through to 404
+## Function handlers for simple pages
 
-A failed codec means the route **doesn't match** — the router continues to the next route, falling through to your existing 404 if nothing else catches it. There is no separate `400` channel. This lets overlapping routes disambiguate by type:
+Use `handler` when a page only needs a direct data-loading function. It can also access dependencies, cancellation and nested operations through execution context. Handle any required recovery inside the function. Choose either `create` or `handler`.
 
 ```ts
-defineRoutes(framework, [
-    { path: "/item/:id", intentId: "item-by-id", controller, params: { id: int() } },
-    { path: "/item/:slug", intentId: "item-by-slug", controller, params: { slug: str() } },
-]);
-// /item/42    → item-by-id   (int matches)
-// /item/hello → item-by-slug (int rejects → falls through to str)
+import { definePage, markPublic } from "@finesoft/front";
+
+export const home = definePage({
+    id: "load-home",
+    handler: () => markPublic({ id: "home", pageType: "home" as const, title: "Home" }, []),
+});
 ```
 
-### Compile-time param types
+Templates use controller classes for consistent organization; function handlers suit short loading logic. Existing function handlers receive `(params, context, query)`. Inheritance is optional: a `create` factory can also return an object implementing `perform(params, context, query)`.
+
+## Controllers for independent business operations
 
-`InferParams` / `InferQuery` derive the controller's param type straight from the codec objects — no hand-written generics to keep in sync:
+The result generic of `BaseController` does not require a page. Bind a class to an operation with `implementController` to execute it in a standalone data runtime. HTTP and Worker hosts can also invoke that operation.
 
 ```ts
 import {
     BaseController,
-    type InferParams,
-    type InferQuery,
-    int,
-    oneOf,
-    optional,
+    createRuntime,
+    defineApp,
+    defineOperation,
+    implementController,
+    type ControllerInput,
 } from "@finesoft/front";
 
-const params = { id: int() };
-const query = { sort: optional(oneOf(["asc", "desc"] as const)) };
+type TotalInput = { unitPrice: number; quantity: number };
+interface TotalResult {
+    total: number;
+}
 
-class ProductController extends BaseController<
-    InferParams<typeof params> & InferQuery<typeof query>, // { id: number; sort?: "asc" | "desc" }
-    ProductPage
-> {
-    readonly intentId = "product";
-    execute(params) {
-        // params.id: number, params.sort: "asc" | "desc" | undefined
+class TotalController extends BaseController<ControllerInput<TotalInput>, TotalResult> {
+    execute({ params }: ControllerInput<TotalInput>): TotalResult {
+        return { total: params.unitPrice * params.quantity };
     }
 }
-```
-
-### `route()` — param-key safety
 
-The plain array-object form already checks that every `params` key appears in the `path`. The `route(path, def)` helper gives the same check as a standalone, composable entry:
+const calculateTotal = defineOperation<TotalInput, TotalResult>({
+    id: "calculate-total",
+    kind: "query",
+});
+const runtime = createRuntime({
+    app: defineApp({
+        id: "data-example",
+        operations: [calculateTotal],
+        implementations: [implementController(calculateTotal, () => new TotalController())],
+    }),
+});
 
-```ts
-route("/products/:id", { intentId: "product", params: { id: int() } }); // ✓
-route("/products/:id", { intentId: "product", params: { slug: str() } }); // ✗ compile error: "slug" is not in the path
+try {
+    const result = await runtime.execute(calculateTotal, { unitPrice: 29, quantity: 2 });
+    console.log(result); // { total: 58 }
+} finally {
+    await runtime.dispose();
+}
 ```
 
-### `defineRoute()` — auto-typed handlers
-
-`defineRoute(path, def)` takes a **handler** function instead of a controller class, and infers its params type from the codecs automatically — no `InferParams` needed. It mirrors `BaseController`'s `try/catch → fallback`:
+The operation declaration defines the input/output contract; the controller supplies the implementation. Exposing the operation over HTTP still requires an explicit endpoint. Registering a controller does not publish an API.
 
-```ts
-defineRoute("/products/:id", {
-    intentId: "product",
-    params: { id: int() },
-    query: { page: withDefault(int(), 1) },
-    handler: (params, container) => {
-        // params: { id: number; page: number } — inferred from the codecs
-        return loadProduct(params.id, params.page);
-    },
-    fallback: (params, error) => errorPage(error), // optional
-});
-```
+<Ch02RouteResolver />
 
-Routes without `params` / `query` behave exactly as before — params stay strings, runtime is unchanged.
+## Server controllers and request context
 
-## Writing a controller
+Use `BaseServerController` from `@finesoft/front` for pages requiring secrets, HttpOnly cookies, or response mutation. Keep `execute({ params, query, context })`, `fallback({ params, query, context, error })`, and the same `definePage({ create, routes })` registration. The type generator maintains the existing compact `Input` / `Failure` references and selects the context from the base class.
 
 ```ts
-// src/lib/controllers/product.ts
-import { BaseController, type Container, type HttpClient } from "@finesoft/front";
-
-interface ProductPage {
-    kind: "product";
-    id: string;
-    name: string;
-    price: number;
-}
-
-export class ProductController extends BaseController<{ id: string }, ProductPage> {
-    readonly intentId = "product";
-
-    async execute(params: { id: string }, container: Container): Promise<ProductPage> {
-        const http = container.resolve<HttpClient>("http");
-        const product = await http.get<{ name: string; price: number }>(
-            `/api/products/${params.id}`,
+import { BaseServerController } from "@finesoft/front";
+import { markPublic } from "@finesoft/front";
+import { loadAccount } from "./account-service";
+
+export class AccountController extends BaseServerController {
+    async execute({ params, context }) {
+        const account = await loadAccount(params.id, context.getCookie("session"));
+        context.responseHeaders.set("Cache-Control", "private, no-store");
+        return markPublic(
+            { id: String(params.id), pageType: "account", title: account.name, account },
+            { account: { id: true, name: true } },
         );
-        return {
-            kind: "product",
-            id: params.id,
-            name: product.name,
-            price: product.price,
-        };
-    }
-
-    fallback(params: { id: string }, _error: unknown): ProductPage {
-        return { kind: "product", id: params.id, name: "Not available", price: 0 };
     }
 }
 ```
 
-### Controller contract
-
-| Member     | Required | Purpose                                                                            |
-| ---------- | -------- | ---------------------------------------------------------------------------------- |
-| `intentId` | yes      | Must match the route's `intentId` (or the `IntentDispatcher.register` call).       |
-| `execute`  | yes      | Produce the page. Receives parsed path params and the request-scoped DI container. |
-| `fallback` | yes      | Return a degraded page when `execute()` throws. Must be synchronous and total.     |
-
-`BaseController` wraps `execute()` in `try/catch` and routes any error through `fallback()`. The framework never throws out of `dispatch()` — your `fallback()` is the last line of defense.
+Generated annotations are omitted above; `account-service` is application code. The controller may live in any directory. Vite replaces its entire module with browser references, while SSR executes the original implementation directly. Browser navigation uses same-origin `POST /__finesoft/controller`; the server revalidates routes and executes policies and guards. Hydration consumes existing SSR data without another call.
 
-### Why `fallback` is mandatory
+| Capability                                      | Shared page ControllerContext                    | ServerControllerContext                             |
+| ----------------------------------------------- | ------------------------------------------------ | --------------------------------------------------- |
+| `params`, `query`                               | Separate, route-inferred inputs                  | Same                                                |
+| `url`, `path`, `intent`, `isServer`             | Current page and execution environment           | Same; `isServer: true`                              |
+| `getCookie(name)`                               | Browser-readable cookies, or SSR request cookies | Original request cookies, including HttpOnly        |
+| `getHeader(name)`                               | SSR request headers; unavailable in the browser  | Current request headers                             |
+| DI, fetch, signal, operations, logging, tracing | Existing execution capabilities                  | Same                                                |
+| `request`, `responseHeaders`                    | No dedicated interface                           | Original Request and outgoing Headers               |
+| `setCookie`, `deleteCookie`                     | No dedicated interface                           | Write outgoing cookies; leave the request unchanged |
 
-A thrown error in `execute()` during SSR would otherwise crash the request and either 500 or render a blank document. `fallback()` lets you return a structured "error" `Page` that your view layer renders as a graceful failure (banner, retry button, etc.). See the [error handling section in observability](./08-observability.md#error-handling-via-fallback) for patterns.
+Generated page inputs use `ControllerContext` or `ServerControllerContext`. Portable data operations continue to use `ExecutionContext`. Direct page-operation execution without navigation has empty `url` / `path`. For remote loads, `request.url` names the transport endpoint; use `context.url` for the page address.
 
-## Render modes
+### Module isolation
 
-| Mode          | Server returns                               | When to use                                              |
-| ------------- | -------------------------------------------- | -------------------------------------------------------- |
-| `"ssr"`       | Fully rendered HTML + serialized data        | Default. Best for SEO and TTFB-sensitive pages.          |
-| `"csr"`       | Empty shell HTML; controller runs in browser | Authenticated dashboards, heavy-personalization pages.   |
-| `"prerender"` | Static HTML built at deploy time             | Marketing, docs, blog. Combine with ISR (see chapter 4). |
+A server controller module may export controller classes and types only. Its local runtime imports are also private to the server; importing these dependencies from client code fails. Use `import type` for shared contracts and separate modules for client implementations. Keep secret-dependent construction inside the protected module or server configuration, rather than arguments to the shared `create` factory.
 
-The mode is **per-route**, so you can mix freely. The framework rebuilds prerendered routes at build time; SSR routes execute on every request.
+Client bundles and source maps omit the replaced implementation. The development plugin rejects raw controller assets and direct browser source requests for protected dependencies. It indexes modules once, caches ASTs, and reanalyzes changed files. Dependencies remain protected for the lifetime of a development server; restart when intentionally moving one back into shared code. Computed file paths, `public/` assets, and independently copied source are outside the static import boundary. Development servers still belong on trusted development networks.
 
-## Registering controllers without routes
+Use the framework Vite plugin and a request host such as Node or Worker. Static-only hosting cannot run the remote endpoint. The endpoint loads registered server page controllers; it does not expose arbitrary methods or replace explicit login/registration command endpoints.
 
-You can register a controller for an intent without exposing it as a route. This is useful for intents triggered only by `dispatchAction`:
+### Explicit request and response tools
 
-```ts
-framework.intentDispatcher.register("checkout", new CheckoutController());
-
-// Elsewhere:
-const page = await framework.intentDispatcher.dispatch({
-    intentId: "checkout",
-    params: { cartId },
-});
-```
+The framework supplies `request`, `getHeader`, `getCookie`, `fetch`, `responseHeaders`, `setCookie` and `deleteCookie`. Applications own login state, authentication, token storage/refresh and the choice to forward credentials.
 
-Routes are simply intent dispatches keyed by URL.
+Server `context.fetch` uses only caller-supplied headers. It does not inherit Cookie/Authorization from the outer request or copy internal Set-Cookie values to the page response. The credentials option does not create a server-side cookie store. Requests made by the browser retain the browser's native same-origin cookie behavior.
 
-## One intent, many routes
-
-Same intent can serve different URLs:
+For example, application code can choose to forward Authorization to a particular internal endpoint and copy that endpoint's cookies to the outgoing response:
 
 ```ts
-defineRoutes(framework, [
-    { path: "/", intentId: "home", controller: new HomeController() },
-    { path: "/welcome", intentId: "home" }, // reuses the registered HomeController
-    { path: "/landing/:slug", intentId: "home" }, // same intent, params differ
-]);
-```
+const headers = new Headers();
+const authorization = context.getHeader("authorization");
+if (authorization) headers.set("authorization", authorization);
 
-This avoids duplicating controller instances when only the URL surface differs. Authenticated `/admin` reusing the `home` intent in the earlier example is the same pattern.
+const response = await context.fetch("/api/account", { headers });
+for (const cookie of response.headers.getSetCookie()) {
+    context.responseHeaders.append("set-cookie", cookie);
+}
+```
 
-## Inspecting the resolved match
+The destination and header/cookie selection are application decisions. Reuse a business HttpClient interceptor or request-scoped provider through context.get when several controllers share the policy.
 
-For diagnostics or custom routing, call `Router.resolve()` directly. It is **async** (codecs may validate asynchronously), so `await` it:
+Applications can also construct outgoing cookies directly:
 
 ```ts
-const match = await framework.router.resolve("/products/42");
-// {
-//   intent: { id: "product", params: { id: "42" } },
-//   action: { kind: "flow", url: "/products/42" },
-//   renderMode: "ssr",
-//   beforeGuards: [...],
-//   afterGuards: [...],
-// }
+context.setCookie("theme", "dark", { path: "/", sameSite: "Lax" });
+context.deleteCookie("theme", { path: "/" });
 ```
 
-`router.resolve()` resolves to `null` for unmatched URLs — handle this in your server-side 404 logic.
-
-## Try it
-
-A live `Router` instance is registered with the sample routes below. Type a URL on the left and watch `Router.resolve()` produce a `RouteMatch` on the right — the same code path the framework uses at runtime.
-
-<Ch02RouteResolver />
-
-## Next
+getCookie always reads the incoming request. Writing a response cookie does not change that request view or update identity. Later business logic uses its own result when it needs a new value. Explicit response headers are assembled into the final response, including error responses, with the framework retaining control of its error body content type and no-store policy.
 
-- [Middleware](./03-middleware.md) — gating navigation, redirects, denies
-- [Rendering & hydration](./04-rendering-and-hydration.md) — what happens after the controller produces a page
+Client-supplied context or bindings are never accepted as identity. markPublic continues to control data sent to the browser; secrets must also stay out of rendered HTML.