@tinvar/renderer 0.0.0-stage → 0.4.1

package/src/mint-client.js

@@ -0,0 +1,142 @@
+// Asking PHP to sign a fragment token.
+//
+// The renderer holds no signing key -- the brief's security rules say it gets
+// no secrets, and the trust boundary puts it on the "runs third-party npm
+// code" side. But it is the only side that knows which <Deferred> boundaries
+// a tree contains and what props they were given, because those facts exist
+// only while the tree renders.
+//
+// So it asks. It sends the component and the props; PHP chooses the route,
+// params, panel, build, session hash and expiry, and signs. A compromised
+// renderer can therefore ask for a token it should not have, and PHP will
+// sign it -- bounded on purpose: the token is not a capability (the fragment
+// endpoint re-runs the originating route's #[Authorize] chain on use), the
+// binding fields it cannot influence are the ones that matter, and PHP caps
+// the requests one render may make (RenderChannel; Frame::MAX_MINTS_PER_RENDER):
+// nothing here counts them, since nothing here is to be trusted to.
+//
+// Shaped like QueryClient deliberately: same batching, same settle-by-id, so
+// there is one pattern on this socket rather than two.
+
+export class MintFailed extends Error {}
+
+export class MintClient {
+  #send;
+  #pending = new Map();
+  #queued = [];
+  // The ids of each batch sent and not yet answered, oldest first. PHP
+  // answers every mint frame with one minted frame, in order, so a reply
+  // belongs to the oldest batch here.
+  #sent = [];
+  #nextId = 0;
+  #scheduled = false;
+  #closed = null;
+
+  /** @param {(requests: Array<{id: number, component: string, props: object}>) => void} send */
+  constructor(send) {
+    this.#send = send;
+  }
+
+  /**
+   * @param {string} component
+   * @param {Record<string, unknown>} props
+   * @returns {Promise<string>} the encoded token
+   */
+  mint(component, props = {}) {
+    if (this.#closed) return Promise.reject(new MintFailed(this.#closed));
+
+    const id = this.#nextId++;
+
+    const promise = new Promise((resolve, reject) => {
+      this.#pending.set(id, { resolve, reject });
+      this.#queued.push({ id, component, props });
+      this.#schedule();
+    });
+
+    // A subtree that started a mint and was then abandoned -- its render
+    // threw, or the boundary was discarded -- leaves nobody attached to this
+    // promise. close() rejects it, and Node treats an unhandled rejection as
+    // fatal, so tearing down a failed render killed the process. The caller's
+    // own rejection path is unaffected: this handler is attached to an
+    // internal reference, not to what is returned.
+    promise.catch(() => {});
+
+    return promise;
+  }
+
+  // One frame per tick, as queries do: a page with twelve <Deferred>
+  // boundaries costs one round trip, not twelve.
+  #schedule() {
+    if (this.#scheduled) return;
+    this.#scheduled = true;
+
+    queueMicrotask(() => {
+      this.#scheduled = false;
+      if (this.#queued.length === 0) return;
+
+      const batch = this.#queued;
+      this.#queued = [];
+
+      // Encoded here, in a microtask with nobody above it: props a frame
+      // cannot carry threw out of it and took the whole renderer down. They
+      // fail this batch's boundaries and nothing else -- and a batch that
+      // never left expects no reply.
+      try {
+        this.#send(batch);
+      } catch (error) {
+        for (const { id } of batch) {
+          this.#pending
+            .get(id)
+            ?.reject(new MintFailed(`The token request could not be sent: ${error?.message ?? error}`));
+          this.#pending.delete(id);
+        }
+        return;
+      }
+      this.#sent.push(batch.map(({ id }) => id));
+    });
+  }
+
+  /**
+   * The reply to the oldest batch still waiting.
+   *
+   * A null token is PHP refusing that one boundary. A boundary the reply
+   * leaves out is refused too: nothing else will ever answer it, and
+   * waiting for an answer held the whole render until PHP's deadline. Both
+   * reject only that boundary's promise, so <Deferred> reports it and the
+   * page completes.
+   *
+   * @param {Array<{id: number, token: string | null}>} tokens
+   */
+  settle(tokens) {
+    const batch = this.#sent.shift() ?? [];
+
+    for (const { id, token } of tokens) {
+      const waiting = this.#pending.get(id);
+      if (!waiting) continue;
+      this.#pending.delete(id);
+
+      if (typeof token === 'string' && token !== '') {
+        waiting.resolve(token);
+      } else {
+        waiting.reject(new MintFailed('PHP returned no token for this boundary.'));
+      }
+    }
+
+    for (const id of batch) {
+      const waiting = this.#pending.get(id);
+      if (!waiting) continue;
+      this.#pending.delete(id);
+      waiting.reject(new MintFailed('PHP returned no token for this boundary.'));
+    }
+  }
+
+  /** @param {string} [reason] */
+  close(reason = 'render_finished') {
+    this.#closed = reason;
+    for (const { reject } of this.#pending.values()) {
+      reject(new MintFailed(`Fragment token never arrived: ${reason}.`));
+    }
+    this.#pending.clear();
+    this.#queued = [];
+  }
+}

package/src/panel-styles.js

@@ -0,0 +1,254 @@
+// A panel's styles, in a stylesheet of its own.
+//
+// panelChunks() keeps a panel's client code out of every other page's
+// downloads; its styles went everywhere still. StyleX compiles every
+// stylex.create() the build reaches -- the admin panel's pages' and their
+// components' as well as the shop's -- into one stylesheet, which the
+// document links on every page. Nothing in it runs, but it maps out what
+// staff see, it grows every customer's download, and a panel is meant to be
+// a boundary (ADR 0109).
+//
+// So, given the StyleX plugin, panelChunks() splits StyleX's rules once the
+// client build has the rest of the graph. The stylesheet the document links
+// on every page keeps the app's own CSS and the shared rules alone, and each
+// panel with rules of its own gets a sheet holding the shared rules and its
+// own, whole, which its pages link after it: the panel's rules in StyleX's
+// own order, where they meet the shared ones repeated after themselves, so
+// two rules never meet out of it. A rule goes to a panel's sheet alone when
+// every view that reaches the module declaring it -- through server imports,
+// then a client component's own -- is in that panel, and nothing reaches it
+// outside the views: the document, a layout kept outside the pages, the
+// client entry. Anything the build cannot trace stays shared.
+//
+// A page outside every panel links one stylesheet, as before: a second, even
+// one of nothing, put a page's queries in two frames instead of one, React
+// scheduling its render around the stylesheet. A panel's page links its
+// sheet through `virtual:tinvar/styles`, read from the RSC plugin's assets
+// manifest, which the client build fills in; in dev StyleX hands the browser
+// its CSS itself, and the component renders nothing.
+
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+
+/** The module the document imports its stylesheet component from. */
+export const STYLES_MODULE = 'virtual:tinvar/styles';
+
+/** Where the client build records the sheets, in the RSC plugin's assets manifest. */
+export const MANIFEST_STYLES = 'tinvarStyles';
+
+/** A client-reference group's virtual module, as @vitejs/plugin-rsc names it. */
+const GROUP_PREFIX = '\0virtual:vite-rsc/client-references/group/';
+
+/** @param {string} id */
+function fileOf(id) {
+  return id.replace(/[?#].*$/, '');
+}
+
+/**
+ * The client graph's id for a client reference the rsc graph names: its
+ * import id, which a package's proxy names by URL.
+ *
+ * @param {string} importId
+ */
+export function clientIdOf(importId) {
+  return importId.startsWith('/@id/__x00__') ? `\0${importId.slice('/@id/__x00__'.length)}` : importId;
+}
+
+/**
+ * Which panel owns each module the build reached, by file: a module is a
+ * panel's when every view reaching it is that panel's and nothing reaches
+ * it outside the views.
+ *
+ * @param {{
+ *   rsc: Map<string, string[]>,
+ *   client: Map<string, string[]>,
+ *   references: Map<string, string>,
+ *   views: Map<string, string>,
+ *   rscEntries: string[],
+ *   clientEntries: string[],
+ *   panelOf: (view: string) => string | null,
+ * }} graphs `references` maps a client reference's rsc id to its import id;
+ *        `views` each view's name to its rsc id
+ * @returns {Map<string, string>} file => the panel that owns it
+ */
+export function moduleOwnership({ rsc, client, references, views, rscEntries, clientEntries, panelOf }) {
+  const viewIds = new Set(views.values());
+
+  /**
+   * Every file reached from $starts: server imports, and at a client
+   * reference, its client module's imports -- never into another view (from
+   * an entry), nor into the client-reference groups the client entry loads
+   * on demand.
+   *
+   * @param {string[]} starts rsc ids
+   * @param {string[]} clientStarts client ids
+   * @param {boolean} stopAtViews
+   */
+  const reach = (starts, clientStarts, stopAtViews) => {
+    const files = new Set();
+    const seen = new Set();
+    /** @type {Array<[string, 'rsc' | 'client']>} */
+    const queue = [
+      ...starts.map((id) => /** @type {[string, 'rsc']} */ ([id, 'rsc'])),
+      ...clientStarts.map((id) => /** @type {[string, 'client']} */ ([id, 'client'])),
+    ];
+    while (queue.length > 0) {
+      const [id, side] = /** @type {[string, 'rsc' | 'client']} */ (queue.shift());
+      const key = `${side}:${id}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      // Another view is that view's own: the entry imports every page, and
+      // reaches none of them for that.
+      if (side === 'rsc' && stopAtViews && viewIds.has(id) && !starts.includes(id)) continue;
+      files.add(fileOf(id));
+
+      if (side === 'rsc') {
+        const reference = references.get(id);
+        if (reference !== undefined) {
+          const clientId = clientIdOf(reference);
+          const found = client.has(clientId) ? clientId : client.has(id) ? id : null;
+          // None in the client build: a reference the server bundle shook
+          // out, whose code never ships -- nothing past it to follow.
+          if (found === null) continue;
+          queue.push([found, 'client']);
+          continue;
+        }
+        for (const next of rsc.get(id) ?? []) queue.push([next, 'rsc']);
+        continue;
+      }
+      for (const next of client.get(id) ?? []) {
+        if (!next.startsWith(GROUP_PREFIX)) queue.push([next, 'client']);
+      }
+    }
+    return files;
+  };
+
+  const shared = reach(rscEntries, clientEntries, true);
+  /** @type {Map<string, Set<string>>} panel => files */
+  const byPanel = new Map();
+  for (const [view, id] of views) {
+    const panel = panelOf(view);
+    const files = reach([id], [], true);
+    if (panel === null) {
+      for (const file of files) shared.add(file);
+      continue;
+    }
+    if (!byPanel.has(panel)) byPanel.set(panel, new Set());
+    const own = /** @type {Set<string>} */ (byPanel.get(panel));
+    for (const file of files) own.add(file);
+  }
+
+  /** @type {Map<string, string>} */
+  const owned = new Map();
+  /** @type {Map<string, number>} */
+  const claims = new Map();
+  for (const files of byPanel.values()) {
+    for (const file of files) claims.set(file, (claims.get(file) ?? 0) + 1);
+  }
+  for (const [panel, files] of byPanel) {
+    for (const file of files) {
+      if (!shared.has(file) && claims.get(file) === 1) owned.set(file, panel);
+    }
+  }
+
+  return owned;
+}
+
+/**
+ * The StyleX rules each sheet holds: the shared sheet every rule no panel
+ * owns, and each panel's sheet the same and its own.
+ *
+ * @param {Map<string, unknown[]>} rulesById StyleX's rules, by the module that declared them
+ * @param {Map<string, string>} owned file => panel, from moduleOwnership()
+ * @param {string[]} panels
+ * @returns {{ shared: unknown[], panels: Record<string, unknown[]>, owned: Record<string, number> }}
+ *          the rules, and how many each panel owns
+ */
+export function partitionRules(rulesById, owned, panels) {
+  const shared = [];
+  /** @type {Record<string, unknown[]>} */
+  const own = Object.fromEntries(panels.map((panel) => [panel, []]));
+  for (const [id, rules] of [...rulesById].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+    const panel = owned.get(fileOf(id));
+    if (panel !== undefined && own[panel] !== undefined) own[panel].push(...rules);
+    else shared.push(...rules);
+  }
+
+  return {
+    shared,
+    panels: Object.fromEntries(panels.map((panel) => [panel, [...shared, ...(own[panel] ?? [])]])),
+    owned: Object.fromEntries(panels.map((panel) => [panel, own[panel]?.length ?? 0])),
+  };
+}
+
+/**
+ * Renders StyleX rules as the StyleX plugin does -- its babel plugin's
+ * ordering, then lightningcss for the browsers the app names -- with the
+ * plugin's own copies of both, found beside it.
+ *
+ * @param {string} root the app's root, which resolves @stylexjs/unplugin
+ * @returns {(rules: unknown[]) => string}
+ */
+export function styleXRenderer(root) {
+  const fromApp = createRequire(join(root, 'package.json'));
+  const fromPlugin = createRequire(fromApp.resolve('@stylexjs/unplugin'));
+  const babel = fromPlugin('@stylexjs/babel-plugin');
+  const lightningcss = fromPlugin('lightningcss');
+  const browserslist = fromPlugin('browserslist');
+  const process = babel.processStylexRules ?? babel.default?.processStylexRules;
+
+  return (rules) => {
+    if (rules.length === 0) return '';
+    const css = process(rules, { useLayers: false });
+    const { code } = lightningcss.transform({
+      targets: lightningcss.browserslistToTargets(browserslist()),
+      filename: 'stylex.css',
+      code: Buffer.from(css),
+    });
+    return code.toString();
+  };
+}
+
+/**
+ * The module the document imports `Stylesheets` from: a panel's view's
+ * sheet, read from the assets manifest, with its digest where the build has
+ * them -- and refused without one there. Any other view, and dev, nothing.
+ *
+ * @param {Record<string, string>} panels panel => directory under the pages
+ * @param {boolean} build
+ */
+export function stylesModule(panels, build) {
+  if (!build) return 'export function Stylesheets() {\n  return null;\n}\n';
+
+  const directories = Object.entries(panels).map(([panel, directory]) => [
+    panel,
+    directory.replace(/\/+$/, ''),
+  ]);
+  return `import __tinvar_manifest__ from 'virtual:vite-rsc/assets-manifest';
+import { createElement } from 'react';
+
+const sheets = __tinvar_manifest__[${JSON.stringify(MANIFEST_STYLES)}] ?? null;
+const digests = __tinvar_manifest__.tinvarIntegrity ?? null;
+const panels = ${JSON.stringify(directories)};
+
+function panelOf(view) {
+  for (const [panel, directory] of panels) {
+    if (view === directory || view.startsWith(directory + '/')) return panel;
+  }
+  return null;
+}
+
+export function Stylesheets({ view }) {
+  if (sheets === null) return null;
+  const panel = typeof view === 'string' ? panelOf(view) : null;
+  if (panel === null || !Object.hasOwn(sheets.panels, panel)) return null;
+  const href = sheets.panels[panel];
+  const props = { rel: 'stylesheet', href, precedence: 'tinvar/styles', crossOrigin: 'anonymous' };
+  if (digests !== null) {
+    if (!Object.hasOwn(digests, href)) throw new Error('[tinvar] No digest for the stylesheet ' + href + '; build again.');
+    props.integrity = digests[href];
+  }
+  return createElement('link', props);
+}
+`;
+}