@tinvar/renderer 0.0.0-stage → 0.4.0

package/src/asset-origin.js

@@ -0,0 +1,306 @@
+// Where the browser loads the build's client assets from, and what each
+// script's bytes must be (ADR 0097).
+//
+// tinvar-spec.md, "Deployment": "Static assets from Vite go to a CDN or are
+// served by PHP with long cache headers." TINVAR_ASSET_ORIGIN, at build
+// time, names the CDN: an https origin and nothing after it. The build's
+// base becomes that origin, so every URL the build writes -- the client
+// entry, each client component's chunk in the payload, every preload and
+// stylesheet, a chunk's import of another -- is on it. Unset, the base is
+// `/` and the assets are this origin's, served by Caddy or, without it, by
+// PHP (Tinvar\Http\BuiltAssets).
+//
+// A CDN is another party's server between the build and the browser, so a
+// build for one also records what every script it wrote is: a SHA-384
+// digest of each file as written, put in the document's import map
+// (`integrity`), which the browser holds every module it loads to --
+// statically, dynamically, or preloaded by a <link> after the map. A CDN
+// that serves different bytes for a script serves a page that does not
+// run, rather than one that runs what it chose. `integrity: true` adds the
+// map to a same-origin build as well; `false` leaves it out of either.
+//
+// Stylesheets are held to theirs too (ADR 0108). An import map covers
+// modules alone, so the digest goes on the <link> itself: the RSC plugin's
+// loadCss() writes each stylesheet's link from its assets manifest, and the
+// module it makes is wrapped here to add the link's `integrity` from the
+// same manifest, which the client build fills in -- on the server render and
+// in every payload, so a stylesheet React inserts on a client navigation is
+// held to it as well. A stylesheet a client component imports itself is
+// preinited by the plugin's own code, which no digest reaches: a build with
+// digests that has one is refused, not shipped unchecked.
+//
+// The origin is recorded in the rsc output, `rsc/assets.json`, where PHP
+// reads it (Tinvar\Http\BuiltAssets) to name it in the page's
+// Content-Security-Policy -- and, once the client build is written, the
+// digests and what every page loads first: the client entry, its imports and
+// the stylesheets every page links. PHP sends those as 103 Early Hints
+// before a page renders, and the page's own modules in its Link header
+// after, each with its digest, so a preload fetched from a header -- before
+// the document's import map is read -- is held to it too. Chromium honours
+// `integrity` on a header's modulepreload and on an Early Hint; a header
+// preload without one put the module in the module map unchecked, and the
+// import map's digest was never asked. The import map reaches the ssr entry
+// through a module the build makes, `virtual:tinvar/assets`: the ssr
+// environment is built after the client one, so the digests are those of
+// the files the client build wrote.
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import { getPluginApi } from '@vitejs/plugin-rsc';
+
+/** The record's name, in the rsc environment's output. */
+export const ASSETS_FILE = 'assets.json';
+
+/** The module the ssr entry reads the import map from. */
+export const ASSETS_MODULE = 'virtual:tinvar/assets';
+
+const RESOLVED = `\0${ASSETS_MODULE}`;
+
+/** The modules the RSC plugin makes for each loadCss(). */
+const CSS_MODULE = '\0virtual:vite-rsc/css?';
+
+/** The component loadCss() renders, as the plugin's module exports it. */
+const RESOURCES_EXPORT = 'export const Resources = (';
+
+/** Where the client build's digests go in the plugin's assets manifest. */
+export const MANIFEST_INTEGRITY = 'tinvarIntegrity';
+
+/** A build asked for an asset origin it may not have. */
+export class AssetOriginRefused extends Error {}
+
+/**
+ * The asset origin $env names, or null for none: https, a host, perhaps a
+ * port, and nothing else -- no path, no query, no credentials, written as
+ * a browser writes an origin.
+ *
+ * @param {Record<string, string | undefined>} env
+ * @returns {string | null}
+ */
+export function assetOriginOf(env) {
+  const raw = (env.TINVAR_ASSET_ORIGIN ?? '').trim();
+  if (raw === '') return null;
+
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    url = null;
+  }
+  if (url === null || url.protocol !== 'https:' || url.origin !== raw) {
+    throw new AssetOriginRefused(
+      `TINVAR_ASSET_ORIGIN='${raw}' is not an origin assets are served from: https, a host and perhaps a port, ` +
+        'as https://cdn.example.com, with no path and no trailing slash.',
+    );
+  }
+
+  return raw;
+}
+
+/**
+ * Whether TINVAR_ASSET_INTEGRITY asks for the digests: `1` for them on any
+ * build, `0` for none, or null to leave it to the asset origin.
+ *
+ * @param {Record<string, string | undefined>} env
+ * @returns {boolean | null}
+ */
+export function integrityAskedOf(env) {
+  const raw = (env.TINVAR_ASSET_INTEGRITY ?? '').trim();
+  if (raw === '') return null;
+  if (raw === '1') return true;
+  if (raw === '0') return false;
+  throw new AssetOriginRefused(`TINVAR_ASSET_INTEGRITY='${raw}' is neither 1 nor 0.`);
+}
+
+/**
+ * The digest of $bytes, as an integrity value.
+ *
+ * @param {Uint8Array | string} bytes
+ */
+export function integrityOf(bytes) {
+  return `sha384-${createHash('sha384').update(bytes).digest('base64')}`;
+}
+
+/**
+ * The plugin.
+ *
+ * @param {{ env?: Record<string, string | undefined>, integrity?: boolean | undefined }} [options]
+ *        the environment, the process's own by default; and whether to hold
+ *        the assets to their digests -- the import map, the stylesheets'
+ *        links and the preload headers -- which TINVAR_ASSET_INTEGRITY says
+ *        where this does not, and which is otherwise on with an asset origin
+ *        and off without
+ * @returns {import('vite').Plugin}
+ */
+export function assetOrigin({ env = process.env, integrity } = {}) {
+  const origin = assetOriginOf(env);
+  const withIntegrity = integrity ?? integrityAskedOf(env) ?? origin !== null;
+  /** @type {Record<string, string>} */
+  const digests = {};
+  let base = '/';
+  /** @type {import('vite').ResolvedConfig | null} */
+  let resolved = null;
+
+  return {
+    name: 'tinvar:asset-origin',
+    // After every other plugin has had the bundle, so what is hashed is
+    // what was written.
+    enforce: 'post',
+    config(_config, { command }) {
+      if (command === 'build' && origin !== null) return { base: `${origin}/` };
+      return undefined;
+    },
+    configResolved(config) {
+      base = config.base;
+      resolved = config;
+    },
+    resolveId(id) {
+      return id === ASSETS_MODULE ? RESOLVED : undefined;
+    },
+    transform(code, id) {
+      if (!withIntegrity || !id.startsWith(CSS_MODULE) || this.environment?.name !== 'rsc') return undefined;
+      if (this.environment.config.command !== 'build') return undefined;
+      // The plugin's first pass, which reads the module graph alone, strips
+      // every module to its imports: nothing of it is shipped.
+      if (resolved !== null && getPluginApi(resolved)?.manager?.isScanBuild === true) return undefined;
+      return withStylesheetIntegrity(code, id);
+    },
+    load(id) {
+      if (id !== RESOLVED) return undefined;
+      // Modules alone: an import map says nothing about a stylesheet.
+      const scripts = Object.fromEntries(Object.entries(digests).filter(([url]) => url.endsWith('.js')));
+      const map = withIntegrity && Object.keys(scripts).length > 0 ? { integrity: scripts } : undefined;
+
+      return `export const importMap = ${JSON.stringify(map)};\nexport const assetOrigin = ${JSON.stringify(origin)};\n`;
+    },
+    generateBundle() {
+      if (this.environment?.name !== 'rsc' || this.environment.config.command !== 'build') return;
+      this.emitFile({
+        type: 'asset',
+        fileName: ASSETS_FILE,
+        source: JSON.stringify({ format: 1, origin }) + '\n',
+      });
+    },
+    writeBundle(options, bundle) {
+      if (this.environment?.name !== 'client') return;
+      const outDir = options.dir ?? this.environment.config.build.outDir;
+      if (withIntegrity) {
+        // Read back as written: a plugin before this one may have appended
+        // to a stylesheet as it wrote it, as StyleX does.
+        for (const fileName of Object.keys(bundle)) {
+          if (!fileName.endsWith('.js') && !fileName.endsWith('.css')) continue;
+          digests[`${base}${fileName}`] = integrityOf(readFileSync(join(outDir, fileName)));
+        }
+      }
+
+      const manifest = resolved === null ? undefined : getPluginApi(resolved)?.manager?.buildAssetsManifest;
+      if (manifest === undefined) return;
+      if (withIntegrity) {
+        refuseUncheckedStylesheets(manifest);
+        // Read where loadCss() renders each stylesheet's link: the manifest
+        // is written for the server builds once every environment is built.
+        manifest[MANIFEST_INTEGRITY] = Object.fromEntries(
+          Object.entries(digests).filter(([url]) => url.endsWith('.css')),
+        );
+      }
+
+      const rscOut = resolve(resolved?.root ?? '.', resolved?.environments?.rsc?.build?.outDir ?? 'dist/rsc');
+      writeFileSync(
+        join(rscOut, ASSETS_FILE),
+        JSON.stringify({
+          format: 1,
+          origin,
+          ...(withIntegrity ? { integrity: { ...digests } } : {}),
+          hints: hintsOf(manifest),
+        }) + '\n',
+      );
+    },
+  };
+}
+
+/**
+ * What every page loads first, from the RSC plugin's assets manifest: the
+ * client entry and what it imports, and the stylesheets every loadCss()
+ * links -- those all of them share, so a stylesheet one view links alone,
+ * a panel's, is never hinted to another's pages.
+ *
+ * @param {Record<string, any>} manifest
+ * @returns {{ modules: string[], styles: string[] }}
+ */
+export function hintsOf(manifest) {
+  const modules = [manifest.clientEntryUrl, ...(manifest.clientEntryDeps?.js ?? [])].filter(
+    (url) => typeof url === 'string',
+  );
+  /** @type {string[][]} */
+  const sheets = Object.values(manifest.serverResources ?? {}).map((deps) =>
+    (deps?.css ?? []).filter((/** @type {unknown} */ url) => typeof url === 'string'),
+  );
+  const styles =
+    sheets.length === 0 ? [] : sheets[0].filter((url) => sheets.every((list) => list.includes(url)));
+
+  return { modules: [...new Set(modules)], styles: [...new Set(styles)] };
+}
+
+/**
+ * Refuses a build with digests that has a stylesheet the RSC plugin links
+ * itself: one a client component or the client entry imports, which its
+ * runtime preinits by URL alone.
+ *
+ * @param {Record<string, any>} manifest
+ */
+function refuseUncheckedStylesheets(manifest) {
+  const unchecked = new Set([
+    ...(manifest.clientEntryDeps?.css ?? []),
+    ...Object.values(manifest.clientReferenceDeps ?? {}).flatMap((deps) => deps?.css ?? []),
+  ]);
+  if (unchecked.size > 0) {
+    throw new Error(
+      `[tinvar] A build held to its digests has stylesheets client code imports, which nothing would hold to theirs: ` +
+        `${[...unchecked].join(', ')}. Import them from a server component, whose loadCss() links them with their digest.`,
+    );
+  }
+}
+
+/**
+ * The module the RSC plugin makes for a loadCss(), with each stylesheet's
+ * link given its digest from the assets manifest. A stylesheet the manifest
+ * has no digest for is refused as the page renders, never linked unchecked.
+ *
+ * @param {string} code the plugin's module
+ * @param {string} id
+ * @returns {string}
+ */
+export function withStylesheetIntegrity(code, id) {
+  if (!code.includes(RESOURCES_EXPORT) || !code.includes('__vite_rsc_assets_manifest__')) {
+    throw new Error(
+      `[tinvar] The RSC plugin's stylesheet module (${id}) is not of the shape assetOrigin() holds to digests; ` +
+        'its links would go out unchecked.',
+    );
+  }
+
+  return (
+    code.replace(RESOURCES_EXPORT, 'const __tinvar_unchecked_resources = (') +
+    `
+const __tinvar_digests = __vite_rsc_assets_manifest__[${JSON.stringify(MANIFEST_INTEGRITY)}] ?? {};
+function __tinvar_held(element) {
+  if (element === null || typeof element !== 'object' || element.props == null) return element;
+  const { rel, href } = element.props;
+  if (element.type === 'link' && rel === 'stylesheet') {
+    const digest = typeof href === 'string' && Object.hasOwn(__tinvar_digests, href) ? __tinvar_digests[href] : null;
+    if (digest === null) throw new Error('[tinvar] No digest for the stylesheet ' + String(href) + '; build again.');
+    return __vite_rsc_react__.cloneElement(element, { integrity: digest });
+  }
+  const children = element.props.children;
+  if (children === undefined) return element;
+  return __vite_rsc_react__.cloneElement(
+    element,
+    undefined,
+    ...(Array.isArray(children) ? children.map(__tinvar_held) : [__tinvar_held(children)]),
+  );
+}
+export function Resources(props) {
+  return __tinvar_held(__tinvar_unchecked_resources(props));
+}
+`
+  );
+}

package/src/build-profile.js

@@ -0,0 +1,108 @@
+// The build's profile, written into the build (ADR 0066).
+//
+// tinvar-spec.md, "Dev and test tooling": tooling is controlled by the build
+// profile -- only `--profile=test` has the browser test helpers. PHP is not
+// built, so the helpers' code cannot be left out of it; what can be made a
+// property of the artefact is the JavaScript build. `tinvar build
+// --profile=test` runs Vite with TINVAR_PROFILE=test, and this plugin records
+// the profile in the rsc environment's output, `rsc/profile.json`, where PHP
+// reads it (Tinvar\Support\BuildProfile): a server whose profile is test
+// refuses a build that does not say test, and a server whose profile is not
+// refuses one that does. A build with no record is a production build, so an
+// application without this plugin simply cannot serve the test profile.
+//
+// TINVAR_BUILD_DIR, when set, is where the build goes -- `<dir>/client`,
+// `<dir>/ssr`, `<dir>/rsc` -- so a test build can sit beside the production
+// one rather than over it.
+
+import { isAbsolute, resolve } from 'node:path';
+
+/** The record's name, in the rsc environment's output. */
+export const PROFILE_FILE = 'profile.json';
+
+export const PROFILES = ['production', 'staging', 'test'];
+
+/** The variables any of which, saying production, rule the test and staging profiles out. */
+const PRODUCTION_MARKERS = ['TINVAR_ENV', 'APP_ENV'];
+
+/** A build asked for a profile it may not have. */
+export class BuildProfileRefused extends Error {}
+
+/**
+ * The profile $env asks for: production unless TINVAR_PROFILE says staging
+ * or test.
+ *
+ * NODE_ENV is not read as a production marker here: Vite sets it to
+ * production for every build. The server reads it, beside the others, when
+ * it decides whether to serve.
+ *
+ * @param {Record<string, string | undefined>} env
+ * @returns {'production' | 'staging' | 'test'}
+ */
+export function profileOf(env) {
+  const profile = (env.TINVAR_PROFILE ?? '').trim().toLowerCase() || 'production';
+  if (!PROFILES.includes(profile)) {
+    throw new BuildProfileRefused(
+      `TINVAR_PROFILE='${profile}' is not a profile: it is production, staging or test.`,
+    );
+  }
+  if (profile !== 'production') {
+    for (const name of PRODUCTION_MARKERS) {
+      if ((env[name] ?? '').trim().toLowerCase() === 'production') {
+        throw new BuildProfileRefused(
+          `A ${profile} build is refused: ${name}=production. ` +
+            (profile === 'test'
+              ? 'The test profile serves the browser test endpoint, which never runs in production.'
+              : 'A staging build is served under keys bound to staging, which production never has.'),
+        );
+      }
+    }
+  }
+
+  return /** @type {'production' | 'staging' | 'test'} */ (profile);
+}
+
+/**
+ * The plugin: the profile recorded in the rsc output, and the build put in
+ * TINVAR_BUILD_DIR when that is set. Listed after the RSC plugin, so the
+ * output directories it gives win over that plugin's defaults.
+ *
+ * @param {{ env?: Record<string, string | undefined> }} [options] the environment; the process's own by default
+ * @returns {import('vite').Plugin}
+ */
+export function buildProfile({ env = process.env } = {}) {
+  const profile = profileOf(env);
+  const out = (env.TINVAR_BUILD_DIR ?? '').trim();
+  // Absolute, as the server requires: each process that reads the build
+  // runs in a directory of its own.
+  if (out !== '' && !isAbsolute(out)) {
+    throw new BuildProfileRefused(
+      `TINVAR_BUILD_DIR='${out}' is not an absolute path; name the build by one.`,
+    );
+  }
+
+  return {
+    name: 'tinvar:build-profile',
+    apply: 'build',
+    config() {
+      if (out === '') return undefined;
+      const directory = resolve(out);
+
+      return {
+        environments: {
+          client: { build: { outDir: resolve(directory, 'client') } },
+          ssr: { build: { outDir: resolve(directory, 'ssr') } },
+          rsc: { build: { outDir: resolve(directory, 'rsc') } },
+        },
+      };
+    },
+    generateBundle() {
+      if (this.environment?.name !== 'rsc') return;
+      this.emitFile({
+        type: 'asset',
+        fileName: PROFILE_FILE,
+        source: JSON.stringify({ format: 1, profile }) + '\n',
+      });
+    },
+  };
+}