npm - what-server - Versions diffs - 0.12.2 → 0.12.4 - Mend

what-server 0.12.2 → 0.12.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/index.d.ts CHANGED Viewed

@@ -14,6 +14,13 @@ export interface RenderRequestContext {
   params?: Record<string, string>;
   query?: Record<string, string>;
   request?: any;
+  /**
+   * The visitor's per-request CSRF token, on directly-rendered routes only.
+   * Return it from the loader to pass into <Form csrfToken> so the no-JS submit
+   * survives the double-submit check. A CACHED route never has one: its HTML is
+   * shared, so a form there only submits with the client enhancer active.
+   */
+  csrfToken?: string;
   [key: string]: any;
 }
@@ -66,10 +73,21 @@ export type { IslandOptions, IslandStore, IslandStatus } from './islands.js';
 // --- Server Actions ---
 export interface ActionOptions {
+  /** Stable id shared by the client and server bundles. The compiler emits one; pass it by hand only for uncompiled builds. */
   id?: string;
   onError?: (error: Error) => void;
   onSuccess?: (result: any) => void;
+  /** Paths to revalidate after the action succeeds. */
   revalidate?: string[];
+  /**
+   * Cache tags to purge after the action succeeds (handleActionRequest reads
+   * these off the registered action). The only way to purge by tag from an
+   * action declaration, so leaving it undeclared made the documented call a
+   * compile error.
+   */
+  revalidateTags?: string[];
+  /** Client-side fetch timeout in ms. Default 30000. */
+  timeout?: number;
 }
 /** Define a server action */
@@ -189,13 +207,21 @@ export function renderToStringAsync(
   ctx?: unknown,
 ): Promise<{ body: string; head: string; resources: Record<string, unknown> }>;
+// The five keys wrapHtmlDocument reads. `bodyAttrs`, `scripts` and `styles`
+// were declared here and read by nothing: `styles: ['/app.css']` typechecked,
+// shipped, and produced a page with no stylesheet and no error. (PageConfig's
+// scripts/styles are real; these were not.)
 export interface DocumentOptions {
+  /** <html lang>, default 'en'. */
   lang?: string;
+  /** Raw markup appended to <head>. */
   head?: string;
-  bodyAttrs?: string;
-  scripts?: string[];
-  styles?: string[];
-  [key: string]: any;
+  /** class attribute for <body>. */
+  bodyClass?: string;
+  /** Module script src for the hydration entry. */
+  clientEntry?: string;
+  /** Per-request CSRF token, inlined as <meta name="what-csrf-token">. The deploy adapter supplies this. */
+  csrfToken?: string;
 }
 /**
@@ -208,9 +234,6 @@ export function renderDocument(
   options?: DocumentOptions,
 ): Promise<string>;
-/** Render a PageConfig to a complete static HTML document. */
-export function generateStaticPage(page: PageConfig, data?: any): string;
 // --- <Form> ---
 // A real <form method="post"> that posts to the action endpoint, so it submits
 // with JavaScript disabled and is enhanced to a fetch when JS is present.
@@ -248,10 +271,17 @@ export function csrfMetaTag(token: string): string;
 // --- Action handlers ---
 // Runtime-neutral core, plus the two host bindings.
+// The three options createActionHandler reads, and only those. `csrfSecret` and
+// `onError` were declared here and read by nothing: an `onError` handler that
+// is never called is worse than no handler, so the open index signature that
+// hid the mismatch is gone too.
 export interface ActionHandlerOptions {
-  csrfSecret?: string;
-  onError?: (error: unknown) => void;
-  [key: string]: any;
+  /** Resolve the session's CSRF token for a request (sync or async). Omit together with `skipCsrf: true`. */
+  getCsrfToken?: (reqLike: any) => string | null | undefined | Promise<string | null | undefined>;
+  /** Opt out of CSRF validation (e.g. a token-authed API behind another gateway). */
+  skipCsrf?: boolean;
+  /** Mount path, default '/__what_action'. Read by nodeActionMiddleware. */
+  basePath?: string;
 }
 export function createActionHandler(options?: ActionHandlerOptions): (request: any) => Promise<any>;
@@ -260,14 +290,123 @@ export function fetchActionHandler(options?: ActionHandlerOptions): (request: Re
 // --- Deploy adapters ---
-export interface RequestHandlerOptions {
-  routes?: any[];
-  documentOptions?: DocumentOptions;
+/**
+ * A route the adapter can match and render. Open on purpose: routes carry
+ * app-specific metadata (titles, guards, nested children) the adapter ignores.
+ */
+export interface RouteDefinition {
+  path: string;
+  /**
+   * The page component. The `any` in `VNode<any>` is load-bearing, NOT laziness:
+   * `VNode<P>` carries P through `tag: string | Component<P>`, and `Component<P>`
+   * is contravariant in its props under strictFunctionTypes, so `VNode<P>` is
+   * effectively invariant. `h('div', { class: 'x' })` returns
+   * `VNode<{ class: string }>`, which is therefore NOT assignable to bare
+   * `VNode` (= `VNode<Record<string, any>>`). Writing `VNode` here made every
+   * route component built with h() and any props at all a TS2322, including the
+   * `h(Form, { csrfToken: loaderData.token })` page the csrfToken plumbing above
+   * exists to make writable. Only `() => null` and `h('div', {})` survived it.
+   */
+  component: (props: any) => VNode<any> | null;
+  /** Runs per request before the component. Receives `csrfToken` on directly-rendered (uncached) routes. */
+  loader?: (ctx: RenderRequestContext) => any;
+  mode?: 'static' | 'server' | 'client' | 'hybrid';
+  /** The route's cache config. Mirrors what-isr's PageCacheConfig structurally so what-server keeps working without what-isr installed. */
+  page?: {
+    mode?: 'static' | 'server' | 'client' | 'hybrid';
+    revalidate?: number;
+    swr?: number;
+    tags?: string[];
+    vary?: string[] | string;
+    [key: string]: any;
+  };
   [key: string]: any;
 }
+/** What the adapter passes to (and expects back from) a render function. */
+export interface RouteMatchContext {
+  path: string;
+  query: Record<string, string>;
+  params: Record<string, string>;
+  config: Record<string, any>;
+  route: RouteDefinition;
+  request: Request;
+  /** Present only on the direct-render path. Cached HTML is shared, so it never carries a per-visitor token. */
+  csrfToken?: string;
+  varyHeaders?: Record<string, string>;
+}
+// What a `render` override hands back. Closed, like the options above, so every
+// key has to be one the runtime reads: the adapter reads `html` and `status`,
+// and when a cache engine is present what-isr's makeEntry reads the whole object
+// (see its own declaration of the makeEntry input, which this mirrors).
+export interface RenderRouteResult {
+  html: string;
+  status?: number;
+  tags?: string[];
+  path?: string;
+  head?: string;
+  state?: unknown;
+  /**
+   * Keep this render out of the shared cache. what-isr stores an entry only when
+   * `status === 200 && !private`, and buildCacheHeaders strips the public
+   * directives from it. Leaving it off this interface made the one switch that
+   * stops a per-visitor page being served to every visitor a compile error,
+   * which is the same shape of hazard as baking a per-visitor CSRF token into
+   * cached HTML.
+   */
+  private?: boolean;
+  /** The render read request headers, so it is per-user: makeEntry folds this into `private`. */
+  usedRequestHeaders?: boolean;
+  /** A partial render (skeleton or streamed shell). buildCacheHeaders forces its s-maxage to 0. */
+  partial?: boolean;
+}
+/**
+ * The subset of what-isr's CacheEngine the adapter touches. Structural so
+ * what-server never has to import what-isr (an optional peer).
+ */
+export interface CacheEngineLike {
+  handle(routeMatch: RouteMatchContext, render?: () => any): Promise<{
+    html: string;
+    status?: number;
+    headers?: Record<string, string>;
+  }>;
+  revalidatePath?: (path: string, options?: any) => any;
+  revalidateTag?: (tag: string, options?: any) => any;
+}
+// Every key here is destructured by createRequestHandler. There is no index
+// signature: an option the adapter does not read is dead config, and
+// `documentOptions` (declared here, never read, the real key is `document`)
+// silently rendered every page without the caller's document options.
+export interface RequestHandlerOptions {
+  routes?: RouteDefinition[];
+  /** ISR engine. Omit for no caching. */
+  cache?: CacheEngineLike;
+  /** Replace the built-in route renderer. */
+  render?: (routeMatch: RouteMatchContext) => RenderRouteResult | Promise<RenderRouteResult>;
+  /** Handler for POST /__what_revalidate, e.g. what-isr's createRevalidateWebhook. */
+  revalidateWebhook?: (req: { headers: Record<string, string>; body: any }) => Promise<{ status: number; body: any }>;
+  /** Document shell options passed to renderDocument. */
+  document?: DocumentOptions;
+  /** Body for unmatched paths. */
+  notFound?: () => string;
+  /** Path prefix stripped before matching. */
+  basePath?: string;
+  /** Double-submit CSRF, on by default. */
+  csrf?: boolean;
+  /** Take over /__what_action entirely. A custom handler owns its own CSRF policy, so cookie/meta auto-provisioning is skipped. */
+  actionHandler?: (reqLike: any) => Promise<{ status: number; headers: Record<string, string>; body: any }>;
+}
+// Request in, Response out, and nothing else: the handler takes ONE argument.
+// It was declared with (request, env, ctx) like a Workers fetch handler, which
+// it is not. It can still BE one (createCloudflareHandler wraps it and puts
+// env/ctx on the request), and a one-argument function is assignable where a
+// three-argument one is expected, so nothing that worked stops working.
 /** Runtime-neutral request handler: Request in, Response out. */
-export function createRequestHandler(options?: RequestHandlerOptions): (request: Request, env?: any, ctx?: any) => Promise<Response>;
+export function createRequestHandler(options?: RequestHandlerOptions): (request: Request) => Promise<Response>;
 /** Cloudflare Workers entry wrapping createRequestHandler. */
 export function createCloudflareHandler(options?: RequestHandlerOptions): { fetch: (request: Request, env?: any, ctx?: any) => Promise<Response> };

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "what-server",
-  "version": "0.12.2",
+  "version": "0.12.4",
   "description": "What Framework - SSR, islands architecture, static generation",
   "type": "module",
   "main": "src/index.js",
@@ -51,8 +51,8 @@
   "author": "ZVN DEV (https://zvndev.com)",
   "license": "MIT",
   "peerDependencies": {
-    "what-core": "^0.12.2",
-    "what-router": "^0.12.2"
+    "what-core": "^0.12.4",
+    "what-router": "^0.12.4"
   },
   "peerDependenciesMeta": {
     "what-router": {

package/src/adapter/core.js CHANGED Viewed

@@ -51,12 +51,25 @@ async function readJsonBody(request) {
 function defaultRenderRoute(documentOptions) {
   return async function renderRoute(routeMatch) {
-    const { route, params, query, request } = routeMatch;
+    const { route, params, query, request, csrfToken } = routeMatch;
     const pageModule = { default: route.component, loader: route.loader };
-    const opts = routeMatch.csrfToken
-      ? { ...documentOptions, csrfToken: routeMatch.csrfToken }
+    // The token goes to the LOADER as well as the document. A server-rendered
+    // <Form> has to put the per-visitor token in a hidden field, and the loader
+    // is the only per-request hook a page has before its component runs, so
+    // without this the token exists (as a cookie and a <meta> tag) and is still
+    // unreachable from the markup: the form ships an empty field and the no-JS
+    // submit dies on the double-submit check with a silent 403. The create-what
+    // scaffold already hand-rolled its own renderRoute to do exactly this.
+    //
+    // Only the direct-render branch below sets routeMatch.csrfToken, so a
+    // CACHED route's loader still sees no token. That is deliberate, not an
+    // omission: cached HTML is shared between visitors and must never carry one
+    // visitor's token.
+    const reqCtx = csrfToken ? { params, query, request, csrfToken } : { params, query, request };
+    const opts = csrfToken
+      ? { ...documentOptions, csrfToken }
       : documentOptions;
-    const html = await renderDocument(pageModule, { params, query, request }, opts);
+    const html = await renderDocument(pageModule, reqCtx, opts);
     return {
       html,
       status: 200,

package/src/form.js CHANGED Viewed

@@ -35,8 +35,10 @@ function resolveActionId(action) {
   throw new Error('[what] <Form> requires an `action` prop: a server action or its id.');
 }
-// On the server there is no document, so the per-request token must be handed in
-// (typically from a loader). On the client it can be recovered from the page.
+// On the server there is no document, so the per-request token must be handed
+// in: the adapter puts it on the loader context as `ctx.csrfToken`, and the
+// page returns it in loader data. On the client it can be recovered from the
+// page (meta tag, then cookie).
 function readClientCsrfToken() {
   if (typeof document === 'undefined') return null;
   const meta = document.querySelector('meta[name="what-csrf-token"]');
@@ -62,10 +64,15 @@ export function Form({
     && typeof process !== 'undefined'
     && process.env?.NODE_ENV !== 'production'
   ) {
+    // Both halves of the contract, because only naming the first one sends
+    // developers looking for a token on a cached page that will never have one.
     console.warn(
-      `[what] <Form action="${actionId}"> has no CSRF token. Server-rendered forms must ` +
-      'receive one (`csrfToken` is passed to loaders), otherwise the double-submit ' +
-      'check rejects the POST and the failure is silent.'
+      `[what] <Form action="${actionId}"> has no CSRF token. Pass one: the adapter hands ` +
+      'the per-request token to the route loader as `ctx.csrfToken`, so return it in ' +
+      'loader data and set `csrfToken` on the form. Cached routes (page mode "static" or ' +
+      '"hybrid") have no per-visitor token by design, since their HTML is shared, so a ' +
+      'form that must submit without JavaScript belongs on a "server" mode route. ' +
+      'Otherwise the double-submit check rejects the POST and the failure is silent.'
     );
   }