@opentf/web 0.7.0 → 0.8.0

package/server/adapters/node.d.ts

@@ -0,0 +1,28 @@
+// Type definitions for the Node.js adapter (SPEC §11.4).
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { RequestHandler } from "../api.js";
+
+export interface NodeAdapterOptions {
+  /** Response for requests that match no API route (default: a 404). */
+  fallback?: (request: Request) => Response | Promise<Response>;
+}
+
+/** Build a WHATWG `Request` from a Node `IncomingMessage`. */
+export function toWebRequest(req: IncomingMessage, options?: { protocol?: string }): Promise<Request>;
+
+/** Write a WHATWG `Response` to a Node `ServerResponse`. */
+export function sendWebResponse(res: ServerResponse, webRes: Response): Promise<void>;
+
+/**
+ * Turn a Fetch handler into a Node `(req, res)` listener:
+ *
+ *   import { createServer } from "node:http";
+ *   import { apiHandler } from "./dist/server/api.js";
+ *   import { toNodeListener } from "@opentf/web/server/adapters/node";
+ *   createServer(toNodeListener(apiHandler)).listen(3000);
+ */
+export function toNodeListener(
+  handler: RequestHandler,
+  options?: NodeAdapterOptions,
+): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/server/adapters/node.js

@@ -0,0 +1,74 @@
+// Node.js adapter for OTF Web API routes (SPEC §11.4). The API handler speaks the
+// standard Fetch `Request`/`Response`; Bun, Cloudflare Workers, and Deno provide
+// those natively, but `node:http` speaks its own `IncomingMessage`/`ServerResponse`.
+// This adapter translates between the two so `dist/server/api.js` runs on Node.
+//
+//   import { createServer } from "node:http";
+//   import { apiHandler } from "./dist/server/api.js";
+//   import { toNodeListener } from "@opentf/web/server/adapters/node";
+//   createServer(toNodeListener(apiHandler)).listen(3000);
+
+/** Build a WHATWG `Request` from a Node `IncomingMessage`. */
+export async function toWebRequest(req, { protocol = "http" } = {}) {
+  const host = req.headers.host ?? "localhost";
+  const url = `${protocol}://${host}${req.url}`;
+  const method = req.method ?? "GET";
+  const headers = new Headers();
+  for (const [k, v] of Object.entries(req.headers)) {
+    if (Array.isArray(v)) for (const one of v) headers.append(k, one);
+    else if (v != null) headers.set(k, v);
+  }
+  // GET/HEAD must not carry a body; everything else streams the request in.
+  const hasBody = method !== "GET" && method !== "HEAD";
+  const body = hasBody ? await readBody(req) : undefined;
+  return new Request(url, { method, headers, body });
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}
+
+/** Write a WHATWG `Response` to a Node `ServerResponse`. */
+export async function sendWebResponse(res, webRes) {
+  const headers = {};
+  webRes.headers.forEach((value, key) => {
+    if (key !== "set-cookie") headers[key] = value;
+  });
+  // `Headers` iteration collapses repeated Set-Cookie values into one string, which
+  // breaks multi-cookie responses (session + CSRF). Recover the individual cookies;
+  // Node accepts an array header value and writes one Set-Cookie line per entry.
+  const cookies = webRes.headers.getSetCookie?.() ?? [];
+  if (cookies.length > 0) headers["set-cookie"] = cookies;
+  res.writeHead(webRes.status, headers);
+  if (webRes.body) {
+    const buf = Buffer.from(await webRes.arrayBuffer());
+    res.end(buf);
+  } else {
+    res.end();
+  }
+}
+
+/**
+ * Turn a Fetch handler `(request) => Response | null` into a Node
+ * `(req, res)` listener. A `null` result (no API route matched) becomes the
+ * optional `fallback(request)` response, or a 404.
+ */
+export function toNodeListener(handler, { fallback } = {}) {
+  return async (req, res) => {
+    try {
+      const request = await toWebRequest(req);
+      let webRes = await handler(request);
+      if (!webRes) webRes = fallback ? await fallback(request) : new Response("Not Found", { status: 404 });
+      await sendWebResponse(res, webRes);
+    } catch (e) {
+      if (!res.headersSent) res.writeHead(500, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: "Internal Server Error" }));
+      console.error("✗ API (node adapter):", e?.stack ?? e);
+    }
+  };
+}

package/server/api.d.ts

@@ -0,0 +1,106 @@
+// Type definitions for file-based API routes (SPEC §11). Authoring handlers in
+// TypeScript: annotate the method exports with `ApiHandler` and the `_middleware`
+// default export with `Middleware`.
+//
+//   import type { ApiHandler, Middleware } from "@opentf/web/server";
+//   export const GET: ApiHandler = (request, { params }) => Response.json({ id: params.id });
+
+type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Route params resolved from `[param]` / `[...rest]` segments. A `[param]` segment
+ * resolves to a `string`; a `[...rest]` catch-all resolves to a `string[]`. Values
+ * arrive percent-decoded (`/users/John%20Doe` → `"John Doe"`).
+ */
+export type RouteParams = Record<string, string | string[]>;
+
+/** Per-request context, passed as the second argument to handlers and middleware. */
+export interface ApiContext {
+  /** Dynamic route params resolved from the matched path. */
+  params: RouteParams;
+  /** Parsed query-string parameters. */
+  query: Record<string, string>;
+  /** The parsed request URL. */
+  url: URL;
+  /**
+   * Mutable per-request bag. Middleware writes to it (e.g. an authenticated user
+   * or a validated body) and downstream middleware / the handler reads from it.
+   */
+  locals: Record<string, unknown>;
+}
+
+/**
+ * An HTTP method handler (`GET`, `POST`, …). Receives the standard Fetch `Request`
+ * plus the {@link ApiContext}. Should return (or throw) a `Response`; a plain value
+ * is a convenience that gets JSON-encoded.
+ */
+export type ApiHandler = (request: Request, context: ApiContext) => MaybePromise<Response>;
+
+/** Continue to the next middleware, or ultimately the route handler. */
+export type NextFn = () => Promise<Response>;
+
+/**
+ * Folder middleware — the default export of a `_middleware.{js,ts}` file. Applies
+ * to its folder and everything nested under it; multiple middleware compose
+ * outermost-first. Call `next()` to continue, or return a `Response` to
+ * short-circuit (e.g. an auth guard).
+ */
+export type Middleware = (request: Request, context: ApiContext, next: NextFn) => MaybePromise<Response>;
+
+/**
+ * The composed request handler produced by {@link createApiHandler}: resolves to a
+ * `Response`, or `null` when no API route matched (so the caller can fall through
+ * to SSR or a 404).
+ */
+export type RequestHandler = (request: Request) => Promise<Response | null>;
+
+/** A discovered route module: its method-named handler exports, keyed by method. */
+export type RouteModule = Partial<Record<string, ApiHandler>>;
+
+/** A discovered `_middleware` module: the middleware is the default export. */
+export interface MiddlewareModule {
+  default?: Middleware;
+  middleware?: Middleware;
+}
+
+export interface FetchHandlerOptions {
+  /** Response for requests that match no API route (default: a 404). */
+  fallback?: (request: Request) => MaybePromise<Response>;
+}
+
+export interface ApiHandlerOptions {
+  /**
+   * Absolute path of the app directory the module keys live under. When given, the
+   * route is derived by stripping this exact prefix (the CLI always passes it);
+   * without it a `/app` path-segment heuristic is used.
+   */
+  appDir?: string;
+}
+
+/** Derive the route path from an `app/**/route.{js,ts}` file path (folder = URL). */
+export function apiRouteFromPath(filePath: string, appDir?: string): string;
+
+/** Derive the folder route a `_middleware` file governs from its file path. */
+export function middlewareScopeFromPath(filePath: string, appDir?: string): string;
+
+/**
+ * Build the API request handler from discovered route + middleware modules (both
+ * keyed by absolute file path so routes are derived from the path).
+ */
+export function createApiHandler(
+  routeModules?: Record<string, RouteModule>,
+  middlewareModules?: Record<string, MiddlewareModule>,
+  options?: ApiHandlerOptions,
+): RequestHandler;
+
+/**
+ * Wrap a {@link RequestHandler} into a total Fetch handler that always returns a
+ * `Response` — a `null` (no route matched) becomes the `fallback` or a 404. Use it
+ * to mount the handler on Fetch-native runtimes (Bun, Cloudflare Workers, Deno):
+ *
+ *   export default { fetch: createFetchHandler(apiHandler) };
+ */
+export function createFetchHandler(
+  handler: RequestHandler,
+  options?: FetchHandlerOptions,
+): (request: Request) => Promise<Response>;

package/server/api.js

@@ -0,0 +1,208 @@
+// File-based API routes for the OTF Web runtime — the API backend (ARCHITECTURE
+// §6, SPEC §11). An endpoint is a `route.{js,ts}` file — the API analogue of a
+// page's `page.{jsx,tsx}` — so the folder is the URL (`app/api/users/[id]/route.ts`
+// → `/api/users/:id`), exactly like pages. Handlers are *plain server modules*
+// (not JSX/DOM-compiled): each exports named functions per HTTP method that take a
+// standard `Request` and return a standard `Response`, portable across Bun / Node /
+// Cloudflare Workers (SPEC §11.1). A folder may hold a `page.*` or a `route.*`, not
+// both — the toolchain errors on the conflict (like Next.js's App Router).
+//
+// This module is runtime-agnostic: `createApiHandler` turns a discovered route
+// map into a single `(request) => Response | null` function. `null` means "no
+// API route matched" so the caller (dev/serve/adapter) can fall through to SSR
+// or a 404. Matching reuses the `[param]` / `[...rest]` convention and regex
+// approach of the page router (runtime/router.js `matchRoute`) so behavior is
+// identical across pages and API and across every deployment target.
+
+const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+
+/**
+ * Strip the app-directory prefix from a route/middleware file path. When the
+ * caller knows the app dir (the CLI always does), the exact prefix is removed —
+ * unambiguous even for an `app/app/...` folder. Without it, fall back to the last
+ * complete `/app` path segment; the lookahead keeps folders that merely *start*
+ * with "app" (`/appointments`, `/apps`) intact.
+ */
+function stripAppDir(filePath, appDir) {
+  if (appDir) {
+    const base = appDir.replace(/\/+$/, "");
+    if (filePath.startsWith(base + "/")) return filePath.slice(base.length);
+  }
+  return filePath.replace(/^.*\/app(?=\/)/, "");
+}
+
+/**
+ * Derive the API route path from a `.../app/<...>/route.{js,ts}` file path — the
+ * folder is the URL, mirroring `routeFromPath` in the page router.
+ * `app/api/status/route.js` → `/api/status`, `app/api/users/[id]/route.ts` →
+ * `/api/users/[id]`, `app/route.js` → `/`. Pass `appDir` (the absolute app
+ * directory) when known so the prefix is stripped exactly.
+ */
+export function apiRouteFromPath(filePath, appDir) {
+  const r = stripAppDir(filePath, appDir).replace(/\/route\.(jsx?|tsx?)$/, "");
+  return r === "" ? "/" : r;
+}
+
+/** The folder route a `_middleware.{js,ts}` file governs: `app/api/_middleware.js`
+ *  → `/api` (applies to `/api` and everything nested under it). */
+export function middlewareScopeFromPath(filePath, appDir) {
+  const r = stripAppDir(filePath, appDir).replace(/\/_middleware\.(jsx?|tsx?)$/, "");
+  return r === "" ? "/" : r;
+}
+
+/** Compile a route path with `[param]` / `[...rest]` segments to a matcher regex.
+ *  Named groups become route params; literal parts are regex-escaped (a `v1.0`
+ *  folder must not match `v1X0`); the optional trailing slash is tolerated. */
+function compilePattern(route) {
+  const src = route
+    .split(/(\[\.\.\.[^\]]+\]|\[[^\]]+\])/)
+    .map((part) => {
+      if (part.startsWith("[...")) return `(?<${part.slice(4, -1)}>.+)`;
+      if (part.startsWith("[")) return `(?<${part.slice(1, -1)}>[^/]+)`;
+      return part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    })
+    .join("");
+  return new RegExp(`^${src}/?$`);
+}
+
+// Percent-decode a matched param segment; malformed input stays raw rather than throwing.
+const decodeParam = (s) => {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+};
+
+const normalize = (p) => (p || "/").replace(/(.)\/+$/, "$1");
+
+/** The `Allow` header value for a handler module: the methods it exports, plus the
+ *  auto-provided HEAD (when GET exists) and OPTIONS. */
+function allowedMethods(mod) {
+  const set = new Set(METHODS.filter((m) => typeof mod[m] === "function"));
+  if (set.has("GET")) set.add("HEAD");
+  set.add("OPTIONS");
+  return [...set].join(", ");
+}
+
+/**
+ * Build the API request handler from a discovered route + middleware map.
+ *
+ * @param {Record<string, object>} routeModules  `{ [absFilePath]: moduleNamespace }`
+ *        — each module exports method handlers (`GET`, `POST`, …).
+ * @param {Record<string, object>} middlewareModules  `{ [absFilePath]: moduleNamespace }`
+ *        for `_middleware.{js,ts}` files; the middleware is the default export.
+ * @param {{ appDir?: string }} [options]  `appDir` — the absolute app directory the
+ *        module keys live under, for exact route derivation (the CLI passes it).
+ * @returns {(request: Request) => Promise<Response | null>}
+ */
+export function createApiHandler(routeModules = {}, middlewareModules = {}, { appDir } = {}) {
+  const routes = [];
+  for (const file in routeModules) {
+    const route = apiRouteFromPath(file, appDir);
+    routes.push({ route, pattern: compilePattern(route), module: routeModules[file], dynamic: route.includes("[") });
+  }
+  // Static routes before dynamic, longer (more specific) before shorter, so the
+  // most specific match wins deterministically regardless of discovery order.
+  routes.sort((a, b) => a.dynamic - b.dynamic || b.route.length - a.route.length);
+
+  const middleware = [];
+  for (const file in middlewareModules) {
+    const mod = middlewareModules[file];
+    const fn = mod.default ?? mod.middleware;
+    if (typeof fn === "function") middleware.push({ scope: middlewareScopeFromPath(file, appDir), fn });
+  }
+  // Outermost (shortest scope) runs first, so `/api/_middleware` wraps `/api/users/_middleware`.
+  middleware.sort((a, b) => a.scope.length - b.scope.length);
+
+  return async function handle(request) {
+    const url = new URL(request.url);
+    const pathname = normalize(url.pathname);
+
+    let matched = null;
+    let params = {};
+    for (const r of routes) {
+      const m = pathname.match(r.pattern);
+      if (!m) continue;
+      matched = r;
+      params = { ...(m.groups || {}) };
+      // Params reach handlers percent-decoded (`/users/John%20Doe` → "John Doe");
+      // catch-all segments are split first so an encoded `%2F` never adds a segment.
+      for (const k in params) {
+        params[k] = r.route.includes(`[...${k}]`)
+          ? params[k].split("/").map(decodeParam)
+          : decodeParam(params[k]);
+      }
+      break;
+    }
+    if (!matched) return null; // no API route — fall through to SSR / 404
+
+    // Shared per-request context. `locals` is the channel middleware uses to pass
+    // data (auth user, validated body) down to the handler.
+    const context = {
+      params,
+      query: Object.fromEntries(url.searchParams),
+      url,
+      locals: {},
+    };
+
+    const dispatch = async (req) => {
+      const mod = matched.module;
+      const method = req.method.toUpperCase();
+      const fn = mod[method];
+      if (typeof fn === "function") return fn(req, context);
+      // Auto HEAD from GET (drop the body); auto OPTIONS; else 405.
+      if (method === "HEAD" && typeof mod.GET === "function") {
+        const got = await mod.GET(req, context);
+        // GET may lean on the plain-value → JSON convenience; HEAD must then carry
+        // the same status/headers that GET response would have had.
+        const res = got instanceof Response ? got : Response.json(got);
+        return new Response(null, { status: res.status, headers: res.headers });
+      }
+      if (method === "OPTIONS") return new Response(null, { status: 204, headers: { Allow: allowedMethods(mod) } });
+      return new Response(null, { status: 405, headers: { Allow: allowedMethods(mod) } });
+    };
+
+    // Compose the applicable middleware chain around dispatch (outermost first).
+    // The root scope ("/", from an `app/_middleware.*`) governs every route.
+    const chain = middleware.filter(
+      (mw) => mw.scope === "/" || pathname === mw.scope || pathname.startsWith(mw.scope + "/"),
+    );
+    let next = dispatch;
+    for (let i = chain.length - 1; i >= 0; i--) {
+      const { fn } = chain[i];
+      const downstream = next;
+      next = (req) => fn(req, context, () => downstream(req));
+    }
+
+    try {
+      const res = await next(request);
+      if (res instanceof Response) return res;
+      if (res === undefined) {
+        throw new Error(`API handler for ${request.method} ${pathname} returned no Response`);
+      }
+      return Response.json(res); // lenient: a plain value becomes a JSON response
+    } catch (e) {
+      if (e instanceof Response) return e; // handlers/middleware may throw a Response
+      console.error(`✗ API ${request.method} ${pathname}:`, e?.stack ?? e);
+      return Response.json({ error: "Internal Server Error" }, { status: 500 });
+    }
+  };
+}
+
+/**
+ * Wrap an API handler (`(request) => Response | null`) into a total Fetch handler
+ * that always returns a `Response` — a `null` (no route matched) becomes the
+ * optional `fallback(request)` or a 404. Fetch-native runtimes (Bun, Cloudflare
+ * Workers, Deno) can export it directly:
+ *
+ *   import { apiHandler } from "./dist/server/api.js";
+ *   export default { fetch: createFetchHandler(apiHandler) };
+ */
+export function createFetchHandler(handler, { fallback } = {}) {
+  return async (request) => {
+    const res = await handler(request);
+    if (res) return res;
+    return fallback ? fallback(request) : new Response("Not Found", { status: 404 });
+  };
+}

package/server/index.d.ts

@@ -0,0 +1,92 @@
+// Types for the `@opentf/web/server` entry. The API-routes surface is fully typed
+// (./api); the SSG string-builders and render helpers — authored in JS and mostly
+// consumed by generated entry code — are declared with permissive signatures.
+
+export * from "./api.js";
+
+// ── Render / route API (render.js) ─────────────────────────────────────────────
+export interface RenderResult {
+  html: string;
+  metadata: Record<string, unknown>;
+  hydration: unknown;
+  status?: number;
+}
+export function renderRoute(
+  pathname: string,
+  params?: Record<string, unknown> | null,
+  search?: string,
+  options?: { data?: unknown },
+): Promise<RenderResult | null>;
+export function renderToString(pathname: string, search?: string): Promise<string>;
+export function collectRoutePaths(): Promise<string[]>;
+
+// ── <head> / metadata (head.js) ─────────────────────────────────────────────────
+export function resolveMetadata(args?: {
+  route?: string;
+  entry?: unknown;
+  params?: Record<string, unknown>;
+  query?: Record<string, unknown>;
+}): Promise<Record<string, unknown>>;
+export function renderHead(meta?: Record<string, unknown>, opts?: { path?: string; baseUrl?: string }): string;
+export function localeAlternateLinks(
+  routePath: string,
+  cfg?: { locales?: string[]; defaultLocale?: string },
+  localize?: (path: string, locale: string) => string,
+): Array<Record<string, string>>;
+
+// ── Route loaders (loader.js) ───────────────────────────────────────────────────
+import type { RouteParams } from "./api.js";
+
+/** The context a route loader receives (docs/DATA.md). `request` is the live
+ *  Request under serve/dev and undefined at SSG prerender; `locals` is reserved. */
+export interface LoaderContext {
+  params: RouteParams;
+  query: Record<string, string>;
+  request?: Request;
+  locale: string | null;
+  locals: Record<string, unknown>;
+}
+
+/** A route loader — the default (or named `loader`) export of a `loader.{js,ts}`
+ *  file. Returns the page's JSON-serializable data. */
+export type Loader = (context: LoaderContext) => unknown | Promise<unknown>;
+
+export interface LoaderMatch {
+  route: string;
+  params: RouteParams;
+  locale: string | null;
+}
+
+export interface LoaderRegistry {
+  routes: string[];
+  match(pathname: string): LoaderMatch | null;
+  load(m: LoaderMatch, ctx?: { request?: Request; query?: Record<string, string> }): Promise<unknown>;
+  loadSerialized(
+    m: LoaderMatch,
+    ctx?: { request?: Request; query?: Record<string, string> },
+  ): Promise<{ data: unknown; json: string }>;
+  handle(request: Request): Promise<Response | null>;
+}
+
+export function createLoaderRegistry(
+  loaderModules?: Record<string, { default?: Loader; loader?: Loader }>,
+  options?: { appDir?: string; i18n?: { locales?: string[]; defaultLocale?: string } },
+): LoaderRegistry;
+export function loaderRouteFromPath(filePath: string, appDir?: string): string;
+/** Throw "this page does not exist" from inside a loader (404 semantics). */
+export function notFound(message?: string): never;
+export function isNotFound(e: unknown): boolean;
+export function serializeRouteData(value: unknown): string;
+
+// ── SSG string-builder helpers (ssg-runtime.js) ─────────────────────────────────
+export function defineSSG(tag: string, render: (...args: any[]) => string): void;
+export function beginHydrationCollect(): void;
+export function endHydrationCollect(): unknown;
+export function escapeHtml(s: unknown): string;
+export function escapeAttr(s: unknown): string;
+export function clsx(value: unknown): string;
+export function styleString(value: unknown): string;
+export function attr(name: string, value: unknown): string;
+export function ssgText(v: unknown): string;
+export function ssgList<T>(arr: T[], fn: (item: T, index: number) => string): string;
+export function ssgComponent(tag: string, props?: Record<string, unknown>, children?: unknown): string;

package/server/index.js

@@ -5,4 +5,6 @@
 export * from "./ssg-runtime.js";
 export * from "./head.js";
 export * from "./render.js";
+export * from "./api.js";
+export * from "./loader.js";
 import "./builtins.js";