@tinvar/renderer 0.0.0-stage → 0.4.0

package/src/protocol.js

@@ -0,0 +1,71 @@
+// Mirror of packages/framework/src/Protocol/Frame.php.
+
+export const FRAME = {
+  RENDER: 'render',
+  FRAGMENT: 'fragment',
+  RESULT: 'result',
+  MINTED: 'minted',
+  // An email template to render from its props: answered with the HTML as
+  // chunks and the plain-text part in a meta frame.
+  MAIL: 'mail',
+  CHUNK: 'chunk',
+  QUERY: 'query',
+  META: 'meta',
+  MINT: 'mint',
+  // A fragment subtree failed and was rendered as an error row; PHP logs it.
+  REPORT: 'report',
+  DONE: 'done',
+  ERROR: 'error',
+  // A health check: the only frame on its connection, answered with one
+  // 'healthy' frame and the end of it. renderer:check and the pool's
+  // supervisor ask it; it carries nothing of any request, and an answer
+  // proves the event loop turns, which a connect alone does not -- the
+  // kernel accepts connections for a process that is stuck.
+  HEALTH: 'health',
+  HEALTHY: 'healthy',
+  // Asked first on a connection by PHP where the renderer runs as a user of
+  // its own, and answered at once: the kernel attaches the writing
+  // process's user to the answer (SCM_CREDENTIALS), which is how PHP knows
+  // who is at the other end before it sends anything of a request. It
+  // carries nothing, either way.
+  HELLO: 'hello',
+  READY: 'ready',
+};
+
+/** What PHP may send. Anything else on this socket is refused. */
+export const FROM_PHP = [
+  FRAME.RENDER,
+  FRAME.FRAGMENT,
+  FRAME.RESULT,
+  FRAME.MINTED,
+  FRAME.MAIL,
+  FRAME.HEALTH,
+  FRAME.HELLO,
+];
+
+/** What the renderer may send. One-way: no flash data, nothing PHP persists. */
+export const FROM_RENDERER = [
+  FRAME.CHUNK,
+  FRAME.QUERY,
+  FRAME.META,
+  FRAME.MINT,
+  FRAME.REPORT,
+  FRAME.DONE,
+  FRAME.ERROR,
+  FRAME.HEALTHY,
+  FRAME.READY,
+];
+
+export class ProtocolError extends Error {}
+
+/** @param {Record<string, unknown>} frame */
+export function assertFromPhp(frame) {
+  const type = frame?.t;
+  if (typeof type !== 'string' || type === '') {
+    throw new ProtocolError('Frame has a missing or non-string type.');
+  }
+  if (!FROM_PHP.includes(type)) {
+    throw new ProtocolError(`PHP may not send a '${type}' frame. Expected one of: ${FROM_PHP.join(', ')}.`);
+  }
+  return type;
+}

package/src/query-client.js

@@ -0,0 +1,198 @@
+// Per-tick query batching on the renderer side.
+//
+// "The renderer collects every query issued in one microtask tick and sends
+// them as one message." Identical calls collapse into one, and results are
+// memoized for the request, matching React cache() semantics.
+
+export class QueryFailed extends Error {
+  /** @param {{code: string, digest?: string, message?: string}} error */
+  constructor(error) {
+    super(error.message ?? `Query failed (${error.code})`);
+    this.name = 'QueryFailed';
+    this.code = error.code;
+    this.digest = error.digest;
+  }
+}
+
+/**
+ * A BigInt as its digits. An id past 2^53 arrives from PHP as one and is
+ * passed straight back into a query, and JSON.stringify throws on it. Raw,
+ * not a string: 5n and 5 are the same integer to PHP, and "5" is not.
+ */
+const bigIntAware = (_key, value) => (typeof value === 'bigint' ? JSON.rawJSON(value.toString()) : value);
+
+/** Key that ignores property order, so two spellings of one call dedupe. */
+function stableKey(name, args) {
+  const keys = Object.keys(args).sort();
+  const parts = keys.map((k) => `${JSON.stringify(k)}:${JSON.stringify(args[k], bigIntAware)}`);
+  return `${name}\0{${parts.join(',')}}`;
+}
+
+/** Callers kept on one call, however many components asked for it. */
+const MAX_BY = 16;
+
+/** Whether a chain of callers is what callers() makes: names, the component first. */
+const isChain = (chain) =>
+  Array.isArray(chain) && chain.length > 0 && chain.every((name) => typeof name === 'string');
+
+export class QueryClient {
+  #send;
+  #nextId = 0;
+  #inflight = new Map();
+  #memo = new Map();
+  #queue = [];
+  /** The calls in #queue by key, until they leave: a call made again before then adds its callers. */
+  #queued = new Map();
+  #scheduled = false;
+  #trailing = false;
+  #closed = false;
+
+  stats = { calls: 0, deduped: 0, batches: 0, largestBatch: 0 };
+
+  /** @param {(calls: Array<{id: number, name: string, args: Record<string, unknown>, by?: string[][]}>) => void} send */
+  constructor(send) {
+    this.#send = send;
+  }
+
+  /**
+   * A trailing call waits to leave with the next call that is not: in the
+   * same frame as the tick's queries, or -- if none comes before the event
+   * loop turns -- alone. A shared read is one (ADR 0060). The layout that
+   * reads it renders before the page inside it, whose components React
+   * renders a few microtasks later; leaving on its own tick, the read cost
+   * every page a round trip of its own.
+   *
+   * @param {string} name
+   * @param {Record<string, unknown>} args
+   * `by` names the component making the call and its owners, in
+   * development only (callers() in @tinvar/react/server). It travels beside
+   * the call as a list of such chains, for the dev toolbar, and PHP reads
+   * the call without it. A call made again before it leaves -- by another
+   * component, deduped into this one -- adds its chain.
+   *
+   * @param {{ trailing?: boolean, by?: string[] }} [options]
+   * @returns {Promise<unknown>}
+   */
+  call(name, args, options = {}) {
+    if (this.#closed) {
+      return Promise.reject(new QueryFailed({ code: 'render_closed' }));
+    }
+
+    const key = stableKey(name, args);
+    const memoized = this.#memo.get(key);
+    if (memoized) {
+      this.stats.deduped++;
+      const waiting = this.#queued.get(key);
+      const by = options.by;
+      if (waiting !== undefined && isChain(by) && waiting.by.length < MAX_BY) {
+        if (!waiting.by.some((chain) => chain.join('\0') === by.join('\0'))) waiting.by.push([...by]);
+      }
+      return memoized;
+    }
+
+    const id = this.#nextId++;
+    const promise = new Promise((resolve, reject) => {
+      this.#inflight.set(id, { resolve, reject });
+    });
+
+    // A component that started a query and never awaited it -- a prefetch,
+    // a subtree discarded mid-render -- leaves nobody attached, and Node
+    // treats an unhandled rejection as fatal: one request's failed query
+    // would end every render on the process. The caller's own rejection
+    // path is unaffected, as for MintClient.
+    promise.catch(() => {});
+
+    this.#memo.set(key, promise);
+    const call = { id, name, args };
+    if (isChain(options.by)) {
+      call.by = [[...options.by]];
+      this.#queued.set(key, call);
+    }
+    this.#queue.push(call);
+    this.stats.calls++;
+    if (options.trailing === true) this.#scheduleTrailing();
+    else this.#schedule();
+
+    return promise;
+  }
+
+  // One flush per microtask tick. Every component that asked during this tick
+  // -- 42 units, say -- leaves in a single frame.
+  #schedule() {
+    if (this.#scheduled) return;
+    this.#scheduled = true;
+
+    queueMicrotask(() => {
+      this.#scheduled = false;
+      this.#flush();
+    });
+  }
+
+  // Once the event loop turns, for trailing calls no other call took along.
+  #scheduleTrailing() {
+    if (this.#trailing) return;
+    this.#trailing = true;
+
+    setImmediate(() => {
+      this.#trailing = false;
+      this.#flush();
+    });
+  }
+
+  #flush() {
+    // A flush the closed render never reached sends nothing: its waiters
+    // were rejected by close(), and the socket is not theirs any more.
+    if (this.#closed) return;
+
+    const batch = this.#queue;
+    this.#queue = [];
+    this.#queued.clear();
+    if (batch.length === 0) return;
+
+    this.stats.batches++;
+    this.stats.largestBatch = Math.max(this.stats.largestBatch, batch.length);
+
+    // Encoded here, with nobody above it on the stack: a callback or a
+    // symbol among the arguments threw out of it and took the whole
+    // renderer down, every render on it included. It fails this batch
+    // and nothing else.
+    try {
+      this.#send(batch);
+    } catch (error) {
+      for (const { id } of batch) {
+        this.#inflight.get(id)?.reject(
+          new QueryFailed({
+            code: 'query_bad_arguments',
+            message: `The query could not be sent: ${error?.message ?? error}`,
+          }),
+        );
+        this.#inflight.delete(id);
+      }
+    }
+  }
+
+  /** @param {Array<{id: number, value?: unknown, error?: {code: string, digest?: string, message?: string}}>} results */
+  settle(results) {
+    for (const result of results) {
+      const waiter = this.#inflight.get(result.id);
+      if (!waiter) continue;
+      this.#inflight.delete(result.id);
+
+      if (result.error) waiter.reject(new QueryFailed(result.error));
+      else waiter.resolve(result.value);
+    }
+  }
+
+  /** Rejects anything still waiting, so a dead socket never hangs a render. */
+  close(reason = 'render_closed') {
+    this.#closed = true;
+    for (const [, waiter] of this.#inflight) {
+      waiter.reject(new QueryFailed({ code: reason }));
+    }
+    this.#inflight.clear();
+  }
+
+  get pending() {
+    return this.#inflight.size;
+  }
+}

package/src/query-map.js

@@ -0,0 +1,116 @@
+// What `tinvar codegen` writes about the queries, for the tools that read
+// server components' source: the renderer build (vite.js), which puts a
+// page's calls on its route's allowlist, and the lint (eslint.js), which
+// holds a query called inside a can() branch to its own #[Authorize].
+//
+// Its own module, apart from vite.js, so the lint loads it without loading
+// Vite and the RSC plugin into ESLint.
+
+import { existsSync, readFileSync } from 'node:fs';
+
+/** Where `tinvar codegen` writes which query each @queries/* function calls, under the root. */
+export const QUERY_MAP = 'resources/types/queries.json';
+
+/** A module codegen types: `@queries`, or `@queries/` and a prefix of query names. */
+export const QUERIES_MODULE = /^@queries(?:\/|$)/;
+
+/** Why the build cannot list the queries a module calls. */
+export class UnreadableQuery extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message);
+    this.name = 'UnreadableQuery';
+  }
+}
+
+/**
+ * The parsed file, or null when there is none.
+ *
+ * @param {string} file
+ * @returns {Record<string, unknown> | null}
+ * @throws {UnreadableQuery} for a file that is not one codegen writes
+ */
+function readFile(file) {
+  if (!existsSync(file)) return null;
+
+  let data;
+  try {
+    data = JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    throw malformed(file, 'is not valid JSON');
+  }
+  if (data?.format !== 1 || !isRecord(data.modules))
+    throw malformed(file, 'is not a query map this version reads');
+  return data;
+}
+
+/**
+ * The @queries/* functions and the query each calls, as `tinvar codegen`
+ * wrote them -- none when it has written nothing, and an import of one then
+ * fails the build rather than going unlisted. The names come from codegen,
+ * not from the function's name: `racks.UnitLoad` is typed as `unitLoad()`,
+ * and nothing in the name says which.
+ *
+ * @param {string} file
+ * @returns {Record<string, Record<string, string>>} module => function => query
+ * @throws {UnreadableQuery} for a file that is not one codegen writes
+ */
+export function readQueryMap(file) {
+  const data = readFile(file);
+  if (data === null) return {};
+
+  /** @type {Record<string, Record<string, string>>} */
+  const modules = Object.create(null);
+  for (const [module, functions] of Object.entries(/** @type {Record<string, unknown>} */ (data.modules))) {
+    if (!QUERIES_MODULE.test(module) || !isRecord(functions)) {
+      throw malformed(file, `lists ${module}, which is not a @queries module`);
+    }
+    modules[module] = Object.create(null);
+    for (const [name, query] of Object.entries(functions)) {
+      if (typeof query !== 'string' || query === '')
+        throw malformed(file, `names no query for ${module}'s ${name}()`);
+      modules[module][name] = query;
+    }
+  }
+  return modules;
+}
+
+/**
+ * The abilities each query's own #[Authorize] checks, as `tinvar codegen`
+ * wrote them: every query is listed, one declaring none -- a
+ * #[NoAuthorization] query -- with an empty list. Null when the map is
+ * missing or was written before codegen wrote this, which a reader asking
+ * about a query must refuse rather than read as "no checks".
+ *
+ * @param {string} file
+ * @returns {Record<string, string[]> | null} query => abilities
+ * @throws {UnreadableQuery} for a file that is not one codegen writes
+ */
+export function readQueryAuthorization(file) {
+  const data = readFile(file);
+  if (data === null || data.authorize === undefined) return null;
+  if (!isRecord(data.authorize)) throw malformed(file, "has an 'authorize' that is not a map");
+
+  /** @type {Record<string, string[]>} */
+  const queries = Object.create(null);
+  for (const [query, abilities] of Object.entries(data.authorize)) {
+    if (
+      !Array.isArray(abilities) ||
+      abilities.some((ability) => typeof ability !== 'string' || ability === '')
+    ) {
+      throw malformed(file, `lists the abilities of ${query} as something other than names`);
+    }
+    queries[query] = [...abilities];
+  }
+  return queries;
+}
+
+/** @param {string} file @param {string} why */
+function malformed(file, why) {
+  return new UnreadableQuery(`[tinvar] ${file} ${why}; run tinvar codegen to write it again.`);
+}
+
+/** @returns {value is Record<string, unknown>} */
+export function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}