smaoog 0.0.1

package/src/response.js

@@ -0,0 +1,256 @@
+import { RESPONSE_HEADER } from "./protocol.js";
+import { renderIntentToHtml, renderIntentToNav } from "./render.js";
+
+// Marks a value as a terminal framework response so the dispatcher can tell a
+// real response apart from a handler that forgot to return one.
+const TERMINAL = Symbol("smaoog.terminal");
+
+function terminal(result) {
+  Object.defineProperty(result, TERMINAL, { value: true });
+  return result;
+}
+
+export function isTerminal(value) {
+  return Boolean(value) && value[TERMINAL] === true;
+}
+
+function assertSerializableProps(value, what = "res.render()") {
+  const prefix = `${what} props must be JSON-serializable`;
+  try {
+    JSON.stringify(value, (key, item) => {
+      if (
+        item === undefined ||
+        typeof item === "function" ||
+        typeof item === "symbol" ||
+        typeof item === "bigint"
+      ) {
+        throw new Error(`${prefix}; "${key}" is ${typeof item}`);
+      }
+      return item;
+    });
+  } catch (err) {
+    if (err.message?.startsWith(prefix)) throw err;
+    throw new Error(prefix);
+  }
+}
+
+// Shared shape for a render intent. Both producers — res.render() and the
+// router's error-page path — build intents through here so the structure can't
+// drift; hydration fields (Phase 15) get added in one place.
+export function createRenderIntent({
+  status,
+  headers,
+  props,
+  routeId = null,
+  Page,
+  Document,
+  routeModule,
+  client = null,
+}) {
+  return { kind: "render", status, headers, props, routeId, Page, Document, routeModule, client };
+}
+
+// Wrap a Node ServerResponse in smaoog's response surface. The helpers are
+// "terminal": they describe the response and return it; the dispatcher is what
+// writes it to the socket. They never touch the Node response directly (use
+// res.raw for that) — that is what makes missing-return detection possible.
+//
+// `canRender` is whether the route has a default export (a page component) to
+// render. The route dispatcher sets it; standalone callers default to true.
+export function createResponse(nodeRes, { canRender = true, renderInfo = {} } = {}) {
+  let status = 200;
+  const headers = {};
+
+  const res = {
+    // Escape hatch: the raw Node ServerResponse.
+    raw: nodeRes,
+
+    // Chainable status setter.
+    status(code) {
+      status = code;
+      return res;
+    },
+
+    // Chainable header setter (merges).
+    headers(object) {
+      Object.assign(headers, object);
+      return res;
+    },
+
+    text(body) {
+      return terminal({
+        kind: "send",
+        status,
+        headers: { "content-type": "text/plain; charset=utf-8", ...headers },
+        body: String(body),
+      });
+    },
+
+    json(data) {
+      return terminal({
+        kind: "send",
+        status,
+        headers: { "content-type": "application/json; charset=utf-8", ...headers },
+        body: JSON.stringify(data),
+      });
+    },
+
+    // Redirects default to 303 (See Other). The location argument is explicit
+    // intent, so it wins over any chained `headers({ location })`.
+    redirect(location, code = 303) {
+      return terminal({
+        kind: "send",
+        status: code,
+        headers: { ...headers, location },
+        body: "",
+      });
+    },
+
+    // Placeholder RenderIntent until React SSR exists (Phase 8). Rendering is
+    // only meaningful when the route has a page (default export); an
+    // endpoint-only route has nothing to render.
+    render(props = {}) {
+      if (arguments.length > 1) {
+        throw new Error("res.render() takes only props, not a component or element");
+      }
+      if (!canRender) {
+        throw new Error(
+          "res.render() requires the route to have a default export (the page component); this route has none.",
+        );
+      }
+      assertSerializableProps(props);
+      return terminal(
+        createRenderIntent({
+          status,
+          headers: { ...headers },
+          props,
+          routeId: renderInfo.routeId ?? null,
+          Page: renderInfo.Page,
+          Document: renderInfo.Document,
+          routeModule: renderInfo.routeModule,
+          client: renderInfo.client,
+        }),
+      );
+    },
+
+    // Render the app's 404 page (or the framework default) through the router.
+    // notFound props are serialized for hydration just like render() props, so
+    // they get the same JSON-serializable guarantee.
+    notFound(props = {}) {
+      assertSerializableProps(props, "res.notFound()");
+      return terminal({
+        kind: "notFound",
+        status: 404,
+        headers: { ...headers },
+        props,
+      });
+    },
+  };
+
+  return res;
+}
+
+// Headers the framework owns on the wire and a route must never set, so a
+// handler can't forge or clobber the envelope marker / content type.
+const RESERVED_JSON_HEADERS = new Set(["content-type", RESPONSE_HEADER]);
+
+// Write a JSON body, applying route-set headers but never the framework-reserved
+// ones — the body shape and the envelope marker are the framework's, not the
+// handler's. (The caller sets RESPONSE_HEADER directly when an envelope needs it,
+// and that survives because it isn't part of `headers`.)
+export function sendJson(nodeRes, status, payload, headers = {}) {
+  nodeRes.statusCode = status;
+  for (const [key, value] of Object.entries(headers)) {
+    if (RESERVED_JSON_HEADERS.has(key.toLowerCase())) continue;
+    nodeRes.setHeader(key, value);
+  }
+  nodeRes.setHeader("content-type", "application/json; charset=utf-8");
+  nodeRes.end(JSON.stringify(payload));
+}
+
+// Write a plain `send` result (text/json/redirect) exactly as the handler
+// described it. This is the full-load form and also what an enhanced <Form>
+// receives for a handler's own res.json()/res.text() (so onSuccess/onError see
+// the real status and body).
+function sendPlain(nodeRes, result, head) {
+  nodeRes.statusCode = result.status;
+  for (const [key, value] of Object.entries(result.headers)) {
+    // RESPONSE_HEADER is framework-owned; a plain passthrough must not carry one
+    // (real for a form's onSuccess/onError) or the client would misread it as an
+    // envelope. content-type is the handler's here, so it is preserved.
+    if (key.toLowerCase() === RESPONSE_HEADER) continue;
+    nodeRes.setHeader(key, value);
+  }
+  nodeRes.end(head ? undefined : result.body);
+}
+
+// Serialize a terminal result for an "enhanced" client request — `nav` (a
+// /_smaoog/nav GET) or `form` (a <Form> mutation). render() and redirect()
+// become JSON envelopes the client runtime swaps/navigates on; the RESPONSE_HEADER
+// names the envelope kind so the client can tell it apart from a handler's own
+// JSON. Everything is sent 200 so the browser's fetch doesn't follow a redirect
+// as a real one — the directive lives in the body. Route-set headers ride along
+// so an enhanced request matches a full load (a handler's Set-Cookie, cache
+// directives, etc. take effect either way).
+//
+// The two modes differ only on a plain `send`: a `form` passes it through for
+// the callbacks, while `nav` (which only ever targets pages) asks for a full
+// reload.
+function sendEnhancedResult(nodeRes, result, mode) {
+  if (result.kind === "render") {
+    nodeRes.setHeader(RESPONSE_HEADER, "render");
+    sendJson(nodeRes, result.status, renderIntentToNav(result), result.headers);
+    return;
+  }
+  if (result.kind === "send") {
+    const location = result.headers?.location;
+    if (location && result.status >= 300 && result.status < 400) {
+      nodeRes.setHeader(RESPONSE_HEADER, "redirect");
+      // The destination lives in the payload body; drop the Location header
+      // (any casing) so it isn't a stray Location on a 200, but keep the rest
+      // (e.g. Set-Cookie).
+      const rest = Object.fromEntries(
+        Object.entries(result.headers).filter(([key]) => key.toLowerCase() !== "location"),
+      );
+      sendJson(nodeRes, 200, { kind: "redirect", location, status: result.status }, rest);
+      return;
+    }
+    if (mode === "form") {
+      // A handler's own response: hand it back verbatim for onSuccess/onError.
+      sendPlain(nodeRes, result, false);
+      return;
+    }
+    // nav mode: the target wasn't a page, so the client does a full load.
+    sendJson(nodeRes, 200, { kind: "reload" }, result.headers);
+    return;
+  }
+  throw new Error(`Cannot send a "${result.kind}" ${mode} result`);
+}
+
+// Write a terminal result to the Node response. `head` writes the status and
+// headers but omits the body, for HEAD requests served from a GET handler.
+// `mode` selects the wire format: "html" (full load), "nav" (client navigation
+// payload), or "form" (enhanced form mutation response).
+export function sendResult(nodeRes, result, { head = false, mode = "html" } = {}) {
+  if (mode === "nav" || mode === "form") {
+    sendEnhancedResult(nodeRes, result, mode);
+    return;
+  }
+
+  if (result.kind === "send") {
+    sendPlain(nodeRes, result, head);
+    return;
+  }
+
+  if (result.kind === "render") {
+    nodeRes.statusCode = result.status;
+    nodeRes.setHeader("content-type", "text/html; charset=utf-8");
+    for (const [key, value] of Object.entries(result.headers)) {
+      nodeRes.setHeader(key, value);
+    }
+    nodeRes.end(head ? undefined : renderIntentToHtml(result));
+    return;
+  }
+
+  throw new Error(`Cannot send a "${result.kind}" result yet`);
+}