@textjs/app 0.0.0-stage → 1.0.3

package/src/server/adapters/vercel.ts

@@ -0,0 +1,149 @@
+/**
+ * `text build --adapter vercel`: Vercel Build Output API v3 in `.vercel/output`.
+ *
+ * - `static/`: the client build (under `basePath`).
+ * - `functions/_textjs/server.func`: one Node.js function for every route handler.
+ * - `functions/_middleware.func`: `middleware.ts` as Edge Routing Middleware,
+ *   speaking the `x-middleware-*` protocol Vercel's router understands.
+ * - `config.json`: asset headers, middleware, rewrites, handler routes and the
+ *   SPA fallback.
+ */
+
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { VERSION } from "@textjs/core";
+import type { MiddlewareModule } from "../middleware";
+import { middlewareMatchers } from "../middleware-runtime";
+import { bundleServerEntry, frameworkFile } from "./bundle";
+import { assertNoServerRoutes, copyStatic, escapeRegex, matcherRegex, patternRegex, rewriteRoute, serverEntry, type AdapterContext, type AdapterResult } from "./shared";
+
+export const VERCEL_FUNCTION = "_textjs/server";
+export const VERCEL_MIDDLEWARE = "_middleware";
+/** Query parameter carrying the routed path into the function. */
+export const PATH_PARAM = "__textjs_path";
+export const VERCEL_NODE_RUNTIME = "nodejs22.x";
+
+/** A routed path the function accepts: one leading slash, no backslashes or control characters. */
+export const ROUTED_PATH = /^\/(?![/\\])[^\\\u0000-\u001f\u007f]*$/;
+
+const FUNCTION_BODY = `
+import { normalizeRequestTarget, requestOrigin, sendWebResponse, toWebRequest } from ${JSON.stringify(frameworkFile("server/http.ts"))};
+
+// Middleware already ran in Vercel's router. The function is only reachable
+// through the handler routes in config.json, which reject client-supplied
+// ${PATH_PARAM} parameters and direct requests to /_textjs/*.
+const handler = createRequestHandler({ ...options, skipMiddleware: true });
+const REQUEST_CONTEXT = Symbol.for("@vercel/request-context");
+const ROUTED_PATH = ${ROUTED_PATH.toString()};
+
+export default async function textjs(req, res) {
+  const url = new URL(normalizeRequestTarget(req.url), "http://vercel.internal");
+  const routed = url.searchParams.getAll(${JSON.stringify(PATH_PARAM)});
+  if (routed.length !== 1 || !ROUTED_PATH.test(routed[0])) {
+    res.statusCode = 400;
+    res.end();
+    return;
+  }
+  url.searchParams.delete(${JSON.stringify(PATH_PARAM)});
+  req.url = routed[0] + url.search;
+  const request = toWebRequest(req, requestOrigin(req, { trustProxy: true, protocol: "https" }), res);
+  const vercel = globalThis[REQUEST_CONTEXT]?.get?.();
+  try {
+    const response = await handler(request, { waitUntil: (p) => vercel?.waitUntil?.(p) });
+    await sendWebResponse(res, response, request.method);
+  } catch (error) {
+    console.error(error);
+    if (!res.headersSent) res.statusCode = 500;
+    res.end();
+  }
+}
+`;
+
+const MIDDLEWARE_BODY = `
+import { runMiddleware, toMiddlewareResponse } from ${JSON.stringify(frameworkFile("server/middleware-runtime.ts"))};
+
+export default async function textjsMiddleware(request, context) {
+  const outcome = await runMiddleware(middleware, request, { basePath: options.basePath, waitUntil: (p) => context?.waitUntil?.(p) });
+  return toMiddlewareResponse(outcome, request);
+}
+`;
+
+export interface VercelRoute {
+  src?: string;
+  dest?: string;
+  headers?: Record<string, string>;
+  continue?: boolean;
+  override?: boolean;
+  check?: boolean;
+  status?: number;
+  middlewarePath?: string;
+  middlewareRawSrc?: string[];
+  has?: unknown[];
+  missing?: unknown[];
+  handle?: "filesystem" | "rewrite" | "miss" | "hit" | "error" | "resource";
+}
+
+export interface VercelConfig {
+  version: 3;
+  routes: VercelRoute[];
+  framework: { version: string };
+}
+
+export function vercelConfig(ctx: AdapterContext, middleware: MiddlewareModule | null): VercelConfig {
+  const base = ctx.basePath;
+  const routes: VercelRoute[] = [
+    // The handler function is internal: only the handler routes below may reach it, with a path they set.
+    { src: `^\\/${escapeRegex(VERCEL_FUNCTION.split("/")[0] as string)}(?:\\/.*)?$`, status: 404 },
+    { src: "^.*$", has: [{ type: "query", key: PATH_PARAM }], status: 400 },
+    { src: `^${escapeRegex(base)}\\/assets\\/(.*)$`, headers: { "cache-control": "public, max-age=31536000, immutable" }, continue: true },
+  ];
+  if (middleware) {
+    const matchers = middlewareMatchers(middleware);
+    const list = matchers ?? [{ source: "/:path*", regex: "", has: undefined, missing: undefined }];
+    for (const m of list) {
+      routes.push({
+        src: matchers ? matcherRegex(m.source, base) : `^${escapeRegex(base)}(?:\\/.*)?$`,
+        middlewarePath: VERCEL_MIDDLEWARE,
+        middlewareRawSrc: [m.source],
+        continue: true,
+        override: true,
+        ...(m.has ? { has: m.has } : {}),
+        ...(m.missing ? { missing: m.missing } : {}),
+      });
+    }
+  }
+  for (const r of ctx.rewrites) {
+    const { src, dest } = rewriteRoute(r, base);
+    routes.push(/^[a-z]+:\/\//i.test(dest) ? { src, dest } : { src, dest, continue: true });
+  }
+  for (const a of ctx.api) routes.push({ src: patternRegex(a.pattern, base), dest: `/${VERCEL_FUNCTION}?${PATH_PARAM}=$1` });
+  routes.push({ handle: "filesystem" });
+  // Extensionless paths are console pages: serve the SPA document.
+  routes.push({ src: `^${escapeRegex(base)}(?:\\/(?:[^/]+\\/)*[^/.]*)?$`, dest: `${base}/index.html` });
+  return { version: 3, routes, framework: { version: VERSION } };
+}
+
+export async function adaptVercel(ctx: AdapterContext, middleware: MiddlewareModule | null): Promise<AdapterResult> {
+  assertNoServerRoutes(ctx, "vercel");
+  const out = join(ctx.root, ".vercel", "output");
+  if (existsSync(out)) rmSync(out, { recursive: true, force: true });
+  copyStatic(ctx.outDir, join(out, "static", ...ctx.basePath.split("/").filter(Boolean)));
+
+  if (ctx.api.length > 0) {
+    const dir = join(out, "functions", `${VERCEL_FUNCTION}.func`);
+    mkdirSync(dir, { recursive: true });
+    await bundleServerEntry({ root: ctx.root, config: ctx.config, code: serverEntry(ctx, { body: FUNCTION_BODY, middleware: false }), outFile: join(dir, "index.mjs"), target: "node" });
+    writeFileSync(
+      join(dir, ".vc-config.json"),
+      `${JSON.stringify({ runtime: VERCEL_NODE_RUNTIME, handler: "index.mjs", launcherType: "Nodejs", shouldAddHelpers: false, supportsResponseStreaming: true }, null, 2)}\n`,
+    );
+  }
+  if (middleware && ctx.middlewareFile) {
+    const dir = join(out, "functions", `${VERCEL_MIDDLEWARE}.func`);
+    mkdirSync(dir, { recursive: true });
+    await bundleServerEntry({ root: ctx.root, config: ctx.config, code: serverEntry(ctx, { body: MIDDLEWARE_BODY, handlers: false, runtime: false }), outFile: join(dir, "index.js"), target: "edge" });
+    writeFileSync(join(dir, ".vc-config.json"), `${JSON.stringify({ runtime: "edge", entrypoint: "index.js" }, null, 2)}\n`);
+  }
+  writeFileSync(join(out, "config.json"), `${JSON.stringify(vercelConfig(ctx, middleware), null, 2)}\n`);
+  return { adapter: "vercel", output: out, notes: ["Deploy: vercel deploy --prebuilt (or push: Vercel runs `text build` and picks up .vercel/output)"] };
+}

package/src/server/bun-jsx.ts

@@ -0,0 +1,65 @@
+/**
+ * Async Server Components for app files Bun imports in-process (`text mcp`,
+ * `text run`). `text dev` / `text build` alias `react/jsx-runtime` for project
+ * files to `@textjs/app/server/jsx-runtime` in Vite; here a Bun runtime
+ * plugin does the same by adding a `@jsxImportSource` pragma to every
+ * `.tsx` / `.jsx` file under the project root (dependencies are untouched).
+ */
+
+import { readFileSync, realpathSync } from "node:fs";
+import { resolve, sep } from "node:path";
+
+/** Bun appends `/jsx-runtime` or `/jsx-dev-runtime` (see the package `exports`). */
+export const SERVER_JSX_IMPORT_SOURCE = "@textjs/app/server";
+
+interface BunPluginBuilder {
+  onLoad(options: { filter: RegExp }, callback: (args: { path: string }) => { contents: string; loader: "tsx" | "jsx" }): void;
+}
+interface BunRuntime {
+  plugin(options: { name: string; target?: "bun"; setup(build: BunPluginBuilder): void }): void;
+}
+
+const installed = new Set<string>();
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function realpath(p: string): string {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+/** The source as Bun should compile it: JSX through the server runtime, line numbers unchanged. */
+export function withServerJsxPragma(source: string): string {
+  return `/** @jsxImportSource ${SERVER_JSX_IMPORT_SOURCE} */ ${source}`;
+}
+
+/**
+ * Compile JSX in project files under `root` against the server JSX runtime,
+ * so `async function` components suspend instead of failing on the console
+ * reconciler. Idempotent per root; returns `false` outside Bun.
+ */
+export function installServerJsxRuntime(root: string): boolean {
+  const bun = (globalThis as { Bun?: BunRuntime }).Bun;
+  if (!bun?.plugin) return false;
+  const dirs = [...new Set([resolve(root), realpath(resolve(root))])].map((d) => (d.endsWith(sep) ? d : d + sep)).filter((d) => !installed.has(d));
+  if (dirs.length === 0) return true;
+  for (const d of dirs) installed.add(d);
+  const nm = escapeRegExp(`${sep}node_modules${sep}`);
+  const filter = new RegExp(`^(?:${dirs.map(escapeRegExp).join("|")})(?!.*${nm}).*\\.[jt]sx$`);
+  bun.plugin({
+    name: `textjs-server-jsx:${dirs[0]}`,
+    target: "bun",
+    setup(build) {
+      build.onLoad({ filter }, (args) => ({
+        contents: withServerJsxPragma(readFileSync(args.path, "utf8")),
+        loader: args.path.endsWith(".jsx") ? "jsx" : "tsx",
+      }));
+    },
+  });
+  return true;
+}

package/src/server/cache-route.ts

@@ -0,0 +1,139 @@
+/**
+ * Full-route caching for `app/**\/route.ts` handlers: `export const dynamic`
+ * and `export const revalidate` (Next.js route segment config).
+ *
+ * - `dynamic = "force-static"` or `revalidate = N` (N > 0): `GET` / `HEAD` are
+ *   cached per pathname with stale-while-revalidate. The handler receives a
+ *   build-time-like request (no query string, headers, cookies or body).
+ * - Default, `"force-dynamic"` or `revalidate = 0`: run on every request.
+ */
+
+import { txError } from "@textjs/core";
+import { markGeneratedCacheControl, PRIVATE_CACHE_CONTROL, runRouteHandler, type RouteHandlerModule } from "./http";
+import type { RouteParams } from "../routing";
+import { __validateRevalidate, EXPIRE_SECONDS, getOrCompute, implicitTags, normalizeCachePath, runInCacheScope, type CacheScope } from "./cache";
+
+export const CACHE_HEADER = "x-textjs-cache";
+
+export interface RouteCacheConfig {
+  /** Cached (static / ISR) for GET and HEAD. */
+  static: boolean;
+  revalidate: number | false;
+}
+
+// Next.js's `"error"` (static, failing on request reads) is rejected: Text.js can't detect request reads.
+const DYNAMIC_VALUES = new Set(["auto", "force-static", "force-dynamic"]);
+
+/** Read and validate a route module's `dynamic` / `revalidate` exports. */
+export function routeCacheConfig(mod: RouteHandlerModule, where = "route handler"): RouteCacheConfig {
+  const dynamic = mod.dynamic ?? "auto";
+  if (typeof dynamic !== "string" || !DYNAMIC_VALUES.has(dynamic)) throw txError("TX031", JSON.stringify(dynamic), where);
+  const revalidate = __validateRevalidate(mod.revalidate, where);
+  if (dynamic === "force-dynamic" || revalidate === 0) return { static: false, revalidate: 0 };
+  if (dynamic === "force-static") return { static: true, revalidate };
+  return { static: typeof revalidate === "number" && revalidate > 0, revalidate };
+}
+
+export interface RouteCacheContext {
+  params: RouteParams;
+  /** Route pattern, e.g. `/api/posts/[id]`. */
+  pattern: string;
+  /** Pathname without `basePath` (defaults to the request URL's). */
+  pathname?: string;
+  /** `false` in `text dev`: static semantics without storing responses (default `true`). */
+  cache?: boolean;
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+
+interface StoredResponse {
+  status: number;
+  statusText: string;
+  headers: Array<[string, string]>;
+  /** Base64. */
+  body: string;
+}
+
+function toBase64(bytes: Uint8Array): string {
+  let s = "";
+  for (let i = 0; i < bytes.length; i += 0x8000) s += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  return btoa(s);
+}
+
+function fromBase64(b64: string): Uint8Array<ArrayBuffer> {
+  const s = atob(b64);
+  const out = new Uint8Array(new ArrayBuffer(s.length));
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
+  return out;
+}
+
+/** The request a static handler sees: same origin and path, nothing request-specific. */
+export function staticRequest(request: Request): Request {
+  const url = new URL(request.url);
+  return new Request(new URL(url.pathname, url.origin), { method: "GET" });
+}
+
+/** `Cache-Control` for a cached route (Next.js: `s-maxage=N, stale-while-revalidate=<expire - N>`). */
+export function cacheControlFor(revalidate: number | false): string {
+  if (revalidate === false || !Number.isFinite(revalidate)) return `s-maxage=${EXPIRE_SECONDS}`;
+  const seconds = Math.min(EXPIRE_SECONDS, Math.max(1, Math.ceil(revalidate)));
+  return `s-maxage=${seconds}, stale-while-revalidate=${EXPIRE_SECONDS - seconds}`;
+}
+
+/** Responses a shared cache must never replay to other visitors. */
+export function isUncacheableResponse(res: Response): boolean {
+  if (res.status >= 500) return true;
+  if (res.headers.has("set-cookie")) return true;
+  const cc = (res.headers.get("cache-control") ?? "").toLowerCase();
+  return /(?:^|,)\s*(?:private|no-store)\b/.test(cc);
+}
+
+/** Run a route handler with route segment config caching. */
+export async function runRouteHandlerWithCache(mod: RouteHandlerModule, request: Request, ctx: RouteCacheContext): Promise<Response> {
+  const pathname = normalizeCachePath(ctx.pathname ?? new URL(request.url).pathname);
+  const config = routeCacheConfig(mod, `${ctx.pattern}/route`);
+  const method = request.method.toUpperCase();
+  const tags = implicitTags(pathname, ctx.pattern);
+  const scope = (): CacheScope => ({ tags: new Set(tags), revalidate: config.revalidate, implicitTags: tags, waitUntil: ctx.waitUntil });
+
+  if (!config.static || (method !== "GET" && method !== "HEAD") || typeof mod.GET !== "function") {
+    return runInCacheScope(scope(), () => runRouteHandler(mod, request, ctx.params));
+  }
+  const input = staticRequest(request);
+  if (ctx.cache === false) {
+    const res = await runInCacheScope(scope(), () => runRouteHandler(mod, input, ctx.params));
+    return method === "HEAD" ? new Response(null, { status: res.status, statusText: res.statusText, headers: res.headers }) : res;
+  }
+
+  const resolved = await getOrCompute(
+    `route:${pathname}`,
+    async () => {
+      const s = scope();
+      const res = await runInCacheScope(s, () => runRouteHandler(mod, input, ctx.params));
+      if ((res.headers.get("content-type") ?? "").includes("text/event-stream")) {
+        await res.body?.cancel().catch(() => undefined);
+        throw new Error(`Route ${ctx.pattern} is static (dynamic = "force-static" / revalidate) but returned a text/event-stream response. Streaming route handlers must be dynamic: export const dynamic = "force-dynamic".`);
+      }
+      const body = new Uint8Array(await res.arrayBuffer());
+      const value: StoredResponse = { status: res.status, statusText: res.statusText, headers: [...res.headers], body: toBase64(body) };
+      // Server errors, cookies and private responses are returned to this request but never stored.
+      return { value, tags: [...s.tags], revalidate: isUncacheableResponse(res) ? 0 : s.revalidate };
+    },
+    ctx.waitUntil,
+  );
+  const stored = resolved.entry.value as StoredResponse;
+  const headers = new Headers();
+  for (const [k, v] of stored.headers) headers.append(k, v);
+  let generated = false;
+  if (resolved.entry.revalidate === 0) {
+    if (stored.status >= 500 || !headers.has("cache-control")) headers.set("cache-control", PRIVATE_CACHE_CONTROL);
+  } else {
+    headers.set(CACHE_HEADER, resolved.status);
+    if (!headers.has("cache-control")) {
+      headers.set("cache-control", cacheControlFor(resolved.entry.revalidate));
+      generated = true;
+    }
+  }
+  const body = method === "HEAD" || stored.status === 204 || stored.status === 304 ? null : fromBase64(stored.body);
+  const response = new Response(body, { status: stored.status, statusText: stored.statusText, headers });
+  return generated ? markGeneratedCacheControl(response) : response;
+}