@tinvar/renderer 0.0.0-stage → 0.4.0

package/src/render-session.js

@@ -0,0 +1,580 @@
+// One render: the exchange that happens over a single connection.
+//
+// PHP sends `render`; the renderer streams `chunk` frames back and sends
+// `query` frames when a server component needs data, which PHP answers with
+// `result` on the same socket. Frames are one-way by type: the renderer never
+// sends anything PHP would persist.
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { encodeFrame, msgpackCodec } from './codec.js';
+import { FRAME } from './protocol.js';
+import { MintClient } from './mint-client.js';
+import { QueryClient } from './query-client.js';
+import { injectRscPayload } from './html-stream.js';
+import { describe } from './classify.js';
+import { withHead } from './head.js';
+import { logError, requestIdOf } from './log.js';
+
+/** How much of an email's HTML goes in one chunk frame. */
+const MAIL_CHUNK_BYTES = 64 * 1024;
+
+/**
+ * The phases a render times, by the names PHP takes (Frame::PHASES): when
+ * the Flight payload had all been written, when the HTML shell was ready,
+ * the server-side render of the HTML after it, and an email's render. Each
+ * is milliseconds from the moment this session was handed its frame, on
+ * this process's monotonic clock. PHP draws them as child spans of the
+ * render's (ADR 0128): the renderer reports timings and nothing else of
+ * telemetry, and holds no exporter, credential or secret to send them
+ * anywhere itself.
+ */
+export const PHASES = Object.freeze(['flight', 'shell', 'ssr', 'mail']);
+
+export class RenderSession {
+  #write;
+  #drained;
+  #app;
+  #codec;
+  #maxFrameBytes;
+  #client = null;
+  #mints = null;
+  #finished = false;
+
+  /**
+   * Fired when no one will read the render any more: PHP closed the socket
+   * (abort()). Handed to each of the app's entries, which pass it to
+   * React's renderToReadableStream, so React stops rendering -- and asking
+   * for data -- instead of finishing a page for a reader that is gone.
+   */
+  #controller = new AbortController();
+
+  /** The reader the pump holds, while it holds one: abort() cancels it. */
+  #reader = null;
+
+  /**
+   * What this render's components threw, by the digest each was reported
+   * under. A server component's error reaches the HTML render a second
+   * time, rebuilt from its error row with the digest on it, and is the
+   * same failure.
+   */
+  #reported = new Map();
+
+  /** When this session was handed its frame, on performance.now()'s clock. */
+  #began = 0;
+
+  /** The phases timed so far, by name: [start, end] in ms since #began. */
+  #phases = new Map();
+
+  /**
+   * Reports an HTML render holds while its shell is pending: a failure
+   * that fails the shell is the render's error frame, and is said once.
+   * Null for any other render, and once the shell is out.
+   */
+  #held = null;
+
+  /**
+   * @param {(bytes: Uint8Array) => boolean | void} write returns false, as
+   *        a Node stream's write() does, when the destination is full
+   * @param {{ renderHtml: Function, renderRsc: Function, renderFragment?: Function }} app
+   *        each entry is handed, last, the AbortSignal that fires when the
+   *        render is abandoned -- renderRsc(frame, client, mints, onError,
+   *        signal), renderHtml(frame, client, onError, mints, signal),
+   *        renderFragment(frame, client, onError, signal) -- for React's
+   *        renderToReadableStream `signal` option
+   * @param {{codec?: object, maxFrameBytes?: number, drained?: () => Promise<void>}} [options]
+   *        `drained` settles once a full destination has room again
+   */
+  constructor(write, app, options = {}) {
+    this.#write = write;
+    this.#drained = options.drained ?? (() => Promise.resolve());
+    this.#app = app;
+    this.#codec = options.codec ?? msgpackCodec;
+    this.#maxFrameBytes = options.maxFrameBytes;
+  }
+
+  get client() {
+    return this.#client;
+  }
+
+  get mints() {
+    return this.#mints;
+  }
+
+  /**
+   * Abandons the render: PHP has gone, so nothing it writes is read. The
+   * app's stream is cancelled and its signal fired, the clients fail what
+   * they wait on, and the render settles without a done or error frame --
+   * a closed connection is not a failed render, and is not logged as one.
+   *
+   * @param {unknown} [reason]
+   */
+  abort(reason = 'socket_closed') {
+    if (this.#controller.signal.aborted) return;
+    this.#controller.abort(reason);
+    this.#reader?.cancel(reason).catch(() => {});
+    this.#client?.close(reason);
+    this.#mints?.close(reason);
+  }
+
+  /** @param {Record<string, any>} frame */
+  async render(frame) {
+    this.#began = performance.now();
+
+    // What route() writes URLs across hosts with, where PHP routes by host
+    // (ADR 0149): this render's, the host it draws among them, read by
+    // route() from the store it runs in -- one renderer draws several hosts'
+    // pages at once, and each render sees its own.
+    // Outside the store -- work a stream's reader drives later, in its own
+    // context -- route() falls back to what every render shares: the
+    // scheme, the port and the primary host's domain, with no host drawn,
+    // so every link is absolute -- never a path on the wrong host -- and one
+    // to any other host is refused. Never a render's own domains: the last
+    // one written would be another page's, an admin host's domain handed to
+    // a storefront page drawn beside it.
+    if (frame.hosts && typeof frame.hosts === 'object') {
+      globalThis.__TINVAR_HOSTS__ = sharedHosts(frame.hosts);
+      return hostsStore().run(frame.hosts, () => this.#render(frame));
+    }
+    return this.#render(frame);
+  }
+
+  /** @param {Record<string, any>} frame */
+  async #render(frame) {
+    const isFragment = frame.t === FRAME.FRAGMENT;
+
+    // A fragment is always payload-only. There is no shell to send: React
+    // mounts the result into a boundary that is already on the page, so
+    // emitting HTML here would be a second document inside the first.
+    const payloadOnly = isFragment || frame.rsc === true;
+
+    // Both clients are built here and BOTH have to reach the app. The mint
+    // client was built, exposed through a getter, closed in the finally --
+    // and never passed, so getRenderContext().mints was always undefined and
+    // every <Deferred> threw. One missing argument made the whole exchange,
+    // its ADR, its frame types and its caps dead in the composed system.
+    this.#client = new QueryClient((calls) => {
+      this.#send({ t: FRAME.QUERY, q: calls });
+    });
+
+    // Fragment tokens are signed by PHP, which holds the key; the renderer
+    // only knows which boundaries exist.
+    this.#mints = new MintClient((requests) => {
+      this.#send({ t: FRAME.MINT, m: requests });
+    });
+
+    // Until its shell is out, an HTML render's reports wait: see #held.
+    this.#held = isFragment || payloadOnly ? null : [];
+
+    try {
+      // Awaited, not just called: an RSC entry has to await a fragment token
+      // before it can return its stream, which is precisely what a page with
+      // a <Deferred> boundary does. Without this it returned a promise and
+      // the pump asked it for a reader.
+      const signal = this.#controller.signal;
+      const stream = isFragment
+        ? await this.#fragmentStream(frame)
+        : payloadOnly
+          ? await this.#app.renderRsc(
+              frame,
+              this.#client,
+              this.#mints,
+              this.#reporter(frame, 'render error'),
+              signal,
+            )
+          : await this.#htmlStream(frame);
+
+      // Abandoned while the app was still answering: its stream is for no
+      // one, and is stopped before it renders any further.
+      if (signal.aborted) {
+        await cancelQuietly(stream, signal.reason);
+        return;
+      }
+
+      // The shell has rendered: what failed so far failed inside a Suspense
+      // boundary, and the document goes on without it.
+      this.#release();
+      await this.#pump(stream);
+      if (this.#controller.signal.aborted) return;
+      // A payload's stream is the Flight payload itself; a document's is
+      // the HTML, which went on from its shell to here.
+      if (payloadOnly) this.#phase('flight', 0);
+      else this.#phase('ssr', this.#phases.get('shell')?.[1] ?? 0);
+      this.#done();
+    } catch (error) {
+      // What an abandoned render throws -- React's abort, a query the
+      // closed socket failed -- is for no one, and no failure of its own.
+      if (this.#controller.signal.aborted) return;
+      // Stacks, source locations and hints go to logs, never to the browser.
+      // PHP is handed them with the classified code, and decides: the dev
+      // overlay shows them, and anywhere else they are dropped there.
+      //
+      // A server component's error that failed the shell arrives here
+      // rebuilt from its error row -- in a production build with React's
+      // stand-in message -- so it is described from the error the component
+      // threw, under the digest it was reported with, and that report is
+      // not sent as well: one failure, one line in PHP's log.
+      const digest = this.#knownDigest(error);
+      const thrown = digest === undefined ? error : this.#reported.get(digest);
+      this.#release(digest);
+      const { code, ...cause } = describe(thrown);
+      logError('render failed', thrown, { request_id: requestIdOf(frame), code });
+      this.#send({
+        t: FRAME.ERROR,
+        code,
+        digest: digest ?? digestOf(thrown),
+        message: String(thrown?.message ?? thrown),
+        ...cause,
+      });
+    } finally {
+      this.#finished = true;
+      this.#client.close();
+      this.#mints.close();
+    }
+  }
+
+  /**
+   * One deferred subtree, rendered on its own.
+   *
+   * The token arrives ALREADY VERIFIED: PHP checked its signature, session,
+   * build and expiry, and ran the originating route's #[Authorize] chain
+   * before opening this channel. The renderer never verifies anything -- it
+   * holds no key, and the trust boundary puts it on the "runs third-party npm
+   * code" side.
+   *
+   * Queries inside the subtree go through the same client as a page render,
+   * so they batch into one frame and resolve with Level 2 lazy loading, as
+   * the spec requires.
+   */
+  #fragmentStream(frame) {
+    if (typeof this.#app.renderFragment !== 'function') {
+      throw new Error('This app has no renderFragment entry; it cannot serve deferred components.');
+    }
+
+    // No mint client: a deferred boundary does not nest. A fragment render
+    // that could mint would let one boundary spawn others without the page
+    // ever having declared them.
+    return this.#app.renderFragment(
+      frame,
+      this.#client,
+      this.#reporter(frame, 'fragment error'),
+      this.#controller.signal,
+    );
+  }
+
+  /**
+   * The onError a render hands React: for a fragment's
+   * renderToReadableStream, and for a page's -- the RSC serialization and,
+   * for a document, the HTML render beside it.
+   *
+   * A component that throws inside a Suspense boundary is an error row in
+   * the payload, not a failed render: React carries on, and the browser
+   * shows the boundary's error state -- a fragment's `rescue` slot
+   * (tinvar-spec.md, "Rescue and reloading"). Left to React's default, the
+   * failure went to this process's console and nowhere else, and PHP
+   * answered 200 with nothing logged. So each is reported over the socket,
+   * classified as an error frame is, and the digest returned is the one
+   * React writes on the row, so the browser's reference and PHP's log line
+   * are the same string. A failure met twice -- a server component's error
+   * that the HTML render reads back off its row -- is reported once.
+   *
+   * @param {Record<string, any>} frame
+   * @param {string} what how the renderer's own log names it
+   * @returns {(error: unknown) => string}
+   */
+  #reporter(frame, what) {
+    return (error) => {
+      const known = this.#knownDigest(error);
+      if (known !== undefined) return known;
+
+      const digest = reportedDigest(error);
+      this.#reported.set(digest, error);
+      const { code, ...cause } = describe(error);
+      logError(what, error, { request_id: requestIdOf(frame), code, digest });
+      const report = { t: FRAME.REPORT, code, digest, message: String(error?.message ?? error), ...cause };
+      if (this.#held !== null) this.#held.push(report);
+      else this.#send(report);
+      return digest;
+    };
+  }
+
+  /**
+   * The digest `error` was already reported under: the error itself, or
+   * one React rebuilt from its row, which carries the digest.
+   *
+   * @returns {string | undefined}
+   */
+  #knownDigest(error) {
+    for (const [digest, reported] of this.#reported) {
+      if (reported === error) return digest;
+    }
+    const carried = error?.digest;
+    return typeof carried === 'string' && this.#reported.has(carried) ? carried : undefined;
+  }
+
+  /**
+   * Sends the reports held while the shell was pending, but the one the
+   * render's error frame is about to say.
+   *
+   * @param {string} [failed] the digest of the failure that failed the shell
+   */
+  #release(failed) {
+    const held = this.#held ?? [];
+    this.#held = null;
+    for (const report of held) {
+      if (report.digest !== failed) this.#send(report);
+    }
+  }
+
+  async #htmlStream(frame) {
+    // Reported as each happens. Collected and read once, before the
+    // document streamed, they missed every error from a Suspense boundary
+    // that failed after the shell -- the usual kind. The app hands this to
+    // both of the page's renders, so its server components and its client
+    // components rendered here are reported alike.
+    const onError = this.#reporter(frame, 'render error');
+    const rendered = await this.#app.renderHtml(
+      frame,
+      this.#client,
+      onError,
+      this.#mints,
+      this.#controller.signal,
+    );
+    // React resolves the HTML render once its shell is ready.
+    this.#phase('shell', 0);
+    let htmlStream = rendered?.htmlStream;
+    let rscStream = rendered?.rscStream;
+
+    try {
+      rscStream = this.#timed(rscStream, 'flight');
+
+      // One title and one meta tag of each key in the head, PHP's fallbacks
+      // among them until a component's replace them. What the head preloads
+      // goes to PHP as a `meta` frame -- the page's client references, for its
+      // Link header -- before the first byte of the document does.
+      htmlStream = withHead(htmlStream, frame.head, ({ preload }) => {
+        if (preload.length > 0) this.#send({ t: FRAME.META, preload });
+      });
+      return injectRscPayload(htmlStream, rscStream, frame.nonce, frame.page);
+    } catch (error) {
+      // Both renders are running by now, and neither has a reader: left
+      // alone, they went on to the end of the page for no one.
+      await Promise.all([cancelQuietly(htmlStream, error), cancelQuietly(rscStream, error)]);
+      throw error;
+    }
+  }
+
+  async #pump(stream) {
+    const reader = stream.getReader();
+    this.#reader = reader;
+    let finished = false;
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) {
+          finished = true;
+          return;
+        }
+        if (this.#controller.signal.aborted) return;
+        if (!value?.length) continue;
+
+        // PHP reads the socket between writes to the browser, so a slow
+        // browser fills it. Written regardless, the app's whole output
+        // collected in the socket's buffer; the next chunk is read once
+        // there is room for it.
+        if (this.#send({ t: FRAME.CHUNK, b: value }) === false) await this.#drained();
+      }
+    } finally {
+      this.#reader = null;
+      // Left any other way -- abandoned, a chunk that could not be sent, a
+      // stream that failed -- the app's render is told to stop: a reader
+      // merely dropped leaves React rendering the rest of the page.
+      if (!finished) {
+        const reason = this.#controller.signal.aborted ? this.#controller.signal.reason : 'render_stopped';
+        await reader.cancel(reason).catch(() => {});
+      }
+    }
+  }
+
+  /**
+   * One email: the app's renderMail() draws the template from its props,
+   * and the HTML goes back as chunks and the plain-text part -- every link
+   * spelled out, which PHP checks -- in a meta frame.
+   *
+   * No query client and no mint client. A template is handed everything it
+   * shows, and an email has no boundary to defer: a component that awaited
+   * a query here would be one PHP never authorised for this render.
+   *
+   * @param {Record<string, any>} frame
+   */
+  async mail(frame) {
+    this.#began = performance.now();
+    try {
+      if (typeof this.#app.renderMail !== 'function') {
+        throw new Error('This app has no renderMail entry; it cannot render email.');
+      }
+      const mail = await this.#app.renderMail(frame);
+      if (typeof mail?.html !== 'string' || typeof mail?.text !== 'string') {
+        throw new TypeError('renderMail must resolve to { html, text }, both strings.');
+      }
+      this.#phase('mail', 0);
+
+      const bytes = new TextEncoder().encode(mail.html);
+      for (let at = 0; at < bytes.length; at += MAIL_CHUNK_BYTES) {
+        if (this.#send({ t: FRAME.CHUNK, b: bytes.subarray(at, at + MAIL_CHUNK_BYTES) }) === false) {
+          await this.#drained();
+        }
+      }
+      this.#send({ t: FRAME.META, mail: { text: mail.text } });
+      this.#done();
+    } catch (error) {
+      logError('mail render failed', error, { request_id: requestIdOf(frame) });
+      this.#send({
+        t: FRAME.ERROR,
+        code: 'render_failed',
+        digest: digestOf(error),
+        message: String(error?.message ?? error),
+      });
+    } finally {
+      this.#finished = true;
+    }
+  }
+
+  /**
+   * Times a phase as ending now, from `start` -- milliseconds since the
+   * frame arrived -- and answers when it ended. The first time alone: a
+   * phase is timed once a render.
+   *
+   * @param {string} name one of PHASES
+   * @param {number} start
+   * @returns {number}
+   */
+  #phase(name, start) {
+    const end = performance.now() - this.#began;
+    if (!this.#phases.has(name)) this.#phases.set(name, [start, end]);
+    return end;
+  }
+
+  /**
+   * `stream` as it was, with `name` timed from the frame's arrival to the
+   * moment it ended. Read through as injectRscPayload reads its sources --
+   * pulled, nothing read ahead -- so what was read when is unchanged. Not
+   * timed where it is cancelled or fails: that render ends in an error
+   * frame, which carries no phases.
+   *
+   * @param {ReadableStream<Uint8Array>} stream
+   * @param {string} name
+   */
+  #timed(stream, name) {
+    if (!(stream instanceof ReadableStream)) return stream;
+    const reader = stream.getReader();
+    return new ReadableStream(
+      {
+        pull: async (controller) => {
+          const { done, value } = await reader.read();
+          if (!done) {
+            controller.enqueue(value);
+            return;
+          }
+          this.#phase(name, 0);
+          controller.close();
+        },
+        cancel: (reason) => reader.cancel(reason),
+      },
+      { highWaterMark: 0 },
+    );
+  }
+
+  /** The done frame, with the phases timed: start and end in ms, to the microsecond. */
+  #done() {
+    const phases = [...this.#phases].map(([n, [s, e]]) => ({ n, s: round(s), e: round(e) }));
+    this.#send(phases.length === 0 ? { t: FRAME.DONE } : { t: FRAME.DONE, ph: phases });
+  }
+
+  /** @param {Array<{id: number}>} results */
+  settle(results) {
+    this.#client?.settle(results);
+  }
+
+  /** @param {Array<{id: number, token: string | null}>} tokens */
+  settleMints(tokens) {
+    this.#mints?.settle(tokens);
+  }
+
+  /** @returns {boolean | void} false when the destination is full */
+  #send(frame) {
+    if (this.#finished && frame.t !== FRAME.DONE && frame.t !== FRAME.ERROR) return;
+    return this.#write(encodeFrame(frame, this.#maxFrameBytes, this.#codec));
+  }
+}
+
+/**
+ * Cancels `stream` where it is one that can be: a render's output nothing
+ * will read. What cancelling throws -- a stream already locked or errored --
+ * changes nothing about why it was cancelled.
+ *
+ * @param {unknown} stream
+ * @param {unknown} reason
+ */
+async function cancelQuietly(stream, reason) {
+  if (!(stream instanceof ReadableStream) || stream.locked) return;
+  await stream.cancel(reason).catch(() => {});
+}
+
+/**
+ * The digest a failure is reported under. A failed query already has one --
+ * PHP logged the exception under it when it sent the error record -- and
+ * keeping it means the reference a visitor quotes finds that line, which
+ * names the cause, rather than one that says a query failed.
+ */
+function reportedDigest(error) {
+  const digest = error?.name === 'QueryFailed' ? error.digest : undefined;
+  return typeof digest === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(digest) ? digest : digestOf(error);
+}
+
+function round(ms) {
+  return Math.round(Math.max(ms, 0) * 1000) / 1000;
+}
+
+function digestOf(error) {
+  const text = String(error?.stack ?? error?.message ?? error);
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash.toString(16).padStart(8, '0');
+}
+
+/**
+ * What every render's hosts have in common: the scheme, the port, the
+ * primary host's pattern and its configured domain alone -- the one every
+ * page is told, whichever host it is on.
+ *
+ * @param {Record<string, any>} hosts
+ */
+function sharedHosts(hosts) {
+  const primary = typeof hosts.primary === 'string' ? hosts.primary : '';
+  const last = primary.split('.').pop() ?? '';
+  const name = last.startsWith('{') && last.endsWith('}') ? last.slice(1, -1) : null;
+  const roots = hosts.roots && typeof hosts.roots === 'object' ? hosts.roots : {};
+  return {
+    scheme: hosts.scheme,
+    port: hosts.port,
+    primary,
+    roots: name !== null && typeof roots[name] === 'string' ? { [name]: roots[name] } : {},
+  };
+}
+
+/**
+ * The store each render's hosts are read from (route(), ADR 0149): one per
+ * process, under the global route() reads it by, so the app's server and
+ * client component bundles -- each with its own copy of route() -- see the
+ * same one.
+ *
+ * @returns {AsyncLocalStorage<unknown>}
+ */
+function hostsStore() {
+  const g = /** @type {Record<string, any>} */ (globalThis);
+  g.__TINVAR_HOSTS_STORE__ ??= new AsyncLocalStorage();
+  return g.__TINVAR_HOSTS_STORE__;
+}