@uniflowed/vite 0.0.0-alpha.13 → 0.0.0-alpha.14

package/internal/diagnostics.js

@@ -0,0 +1,366 @@
+// @noflow
+//
+// Plain JavaScript: executed by the host that runs Vite, before any transform.
+//
+// The channel a browser reports on.
+//
+// Every other uf diagnostic — a type error, a lint finding, a failing test, a
+// page that rendered its error boundary — arrives in the terminal the
+// developer already has open. A diagnostic the *browser* produces had nowhere
+// to go: the page is the only process that knows about it, and it has no
+// channel back. So it lived in a browser overlay, which has to be noticed, in
+// a window that may not be in front, by somebody who does not know to look.
+//
+// This is that channel, and it is deliberately one channel rather than one per
+// feature. Two things report on it today:
+//
+//   * `POST /__uf/diagnostic` — a diagnostic a browser-side runtime produced
+//     and wants a person to read. `@uniflowed/router`'s `internal/diagnostics.js`
+//     is the client half, and the hydration-mismatch report beside it is what
+//     calls it.
+//   * `POST /__uf/vitals`     — the five numbers `@uniflowed/web/vitals`
+//     measures, posted by `vitalsBeacon()`. In production a project points the
+//     beacon at an endpoint of its own; in development there was nothing at
+//     the default path, so the one place the numbers are most useful — while
+//     you are looking at the page — was the one place they went nowhere.
+//
+// Both end up as the same `diagnostic` event on the driver's control channel
+// (see `./events.js`), which is what gets them uf's own rendering: a severity,
+// a location, and a code frame when the browser had a position to give.
+//
+// # The terminal, and not a browser overlay
+//
+// ubugeeei-prod/uf#557 asked for the vitals to be shown in the overlay. They
+// are shown in the terminal instead, and the later issue that generalised this
+// — #583 — is the argument: a diagnostic that exists only in a browser window
+// has to be noticed by somebody who does not know to look, which is the defect
+// rather than the delivery. Sending these *back* to an overlay would also be
+// circular for the diagnostic half, which arrived from the page in the first
+// place, and an overlay covers the page a performance number is about. What it
+// costs is that a reader watching the browser rather than the terminal sees
+// nothing until they look, which is where every other uf diagnostic already
+// is.
+//
+// # Nothing leaves the machine
+//
+// This module opens no connection. It reads a request that the page on the
+// other end of the dev server's own socket made, writes a line to the terminal
+// that started the dev server, and answers `204`. There is no destination, no
+// third party and nothing to configure, in development or otherwise.
+//
+// # Why the paths are written out here
+//
+// `VITALS_ENDPOINT` in `@uniflowed/web/vitals` and `DIAGNOSTIC_ENDPOINT` in
+// `@uniflowed/router`'s `internal/diagnostics.js` are the same two strings, and
+// they are the contract. They cannot be *imported* here: this module is loaded
+// by Vite before any Flow transform exists, and both of those are Flow. So they
+// are written out, and `tests/library/dev-channel.test.js` asserts that all
+// four spellings agree — a duplicated constant with a test on it is honest, and
+// one without is how the browser ends up posting to a path nothing serves.
+//
+// # Why `/__uf/`
+//
+// A directory under `app/` whose name begins with `_` is not a route, so no
+// application can put anything at this prefix and nothing here can shadow a
+// path a project wrote. That is what makes it safe as a default destination
+// and available to the dev server.
+
+/** Where `@uniflowed/router`'s `reportDiagnostic` posts. */
+export const DIAGNOSTIC_ENDPOINT = "/__uf/diagnostic";
+
+/** Where `@uniflowed/web/vitals`'s `vitalsBeacon()` posts by default. */
+export const VITALS_ENDPOINT = "/__uf/vitals";
+
+/**
+ * The most a report may weigh.
+ *
+ * A diagnostic is a headline and a few lines of context; a vitals report is
+ * five numbers. Neither is close to this, and the ceiling is here because the
+ * body arrives from a page — "no unbounded anything" in `docs/security.md`
+ * covers a dev server reading a request as much as it covers a production one,
+ * and a page with a runaway loop in it must not be able to make `uf dev` grow
+ * without bound.
+ */
+export const MAX_BODY_BYTES = 64 * 1024;
+
+/** The most detail lines one diagnostic prints. */
+const MAX_DETAIL_LINES = 40;
+
+/** The most characters any single line of a diagnostic prints. */
+const MAX_LINE_CHARS = 400;
+
+/** The most metrics one vitals report is read for; there are five names. */
+const MAX_VITALS = 16;
+
+/** The most characters a metric's name or its rating may print as. */
+const MAX_NAME_CHARS = 32;
+
+/** The severities the channel accepts, and the words the terminal uses. */
+const SEVERITIES = new Set(["error", "warn", "info"]);
+
+/**
+ * The connect middleware that answers the channel.
+ *
+ * Mounted **before** the application middleware, so a request under `/__uf/`
+ * never reaches a project's `_uf.middleware.js` or its route table. A guard
+ * that ran for a page's own telemetry would be a guard asked a question the
+ * application never asks, and one that redirected it would turn a report into
+ * a login page.
+ *
+ * `report` is injected rather than reached for so that this module can be
+ * driven without a terminal, a socket or a driver; `internal/events.js`'s
+ * `emit` is what the plugin passes.
+ *
+ * @param {(diagnostic: object) => void} report
+ */
+export function createChannelMiddleware(report) {
+  return async function channel(request, response, next) {
+    const pathname = (request.url ?? "/").split("?")[0];
+    const isVitals = pathname === VITALS_ENDPOINT;
+    if (!isVitals && pathname !== DIAGNOSTIC_ENDPOINT) {
+      next();
+      return;
+    }
+
+    // A `GET` on either path is somebody checking whether the dev server has
+    // them, and `405` with `Allow` answers that exactly. `404` would have said
+    // the opposite of the truth.
+    if (request.method !== "POST") {
+      response.statusCode = 405;
+      response.setHeader("allow", "POST");
+      response.end();
+      return;
+    }
+
+    let body;
+    try {
+      body = await readBody(request, MAX_BODY_BYTES);
+    } catch {
+      // A socket that went away mid-body. There is nothing to report and
+      // nobody left to answer.
+      response.statusCode = 400;
+      response.end();
+      return;
+    }
+    if (body == null) {
+      response.statusCode = 413;
+      response.end();
+      return;
+    }
+
+    let payload = null;
+    try {
+      payload = JSON.parse(body);
+    } catch {
+      payload = null;
+    }
+    const diagnostic = isVitals ? vitalsDiagnostic(payload) : browserDiagnostic(payload);
+    if (diagnostic == null) {
+      // The body was not the shape this path promises. Refused rather than
+      // guessed at: a diagnostic assembled out of a malformed report is a line
+      // in somebody's terminal that describes nothing.
+      response.statusCode = 400;
+      response.end();
+      return;
+    }
+
+    // Everything above either answered or handed the request on, so nothing
+    // below can leave one hanging — and an exception from `report` is the dev
+    // server's own failure rather than the page's, so it goes to Vite's error
+    // handler like any other. An `async` connect middleware whose rejection
+    // nobody catches is an unhandled rejection, which on a modern Node ends
+    // the process: `uf dev` would exit on a malformed telemetry post.
+    try {
+      report(diagnostic);
+    } catch (error) {
+      next(error);
+      return;
+    }
+    // No body, and nothing about the machine in the answer. The page posted
+    // this and is not owed a reading of it back.
+    response.statusCode = 204;
+    response.end();
+  };
+}
+
+/**
+ * One diagnostic a browser-side runtime produced, or `null`.
+ *
+ * Every field is checked and every string is bounded, because all of it is
+ * page-authored: a hydration mismatch on a page whose difference is in
+ * somebody's comment carries that comment into this terminal. Nothing here is
+ * interpreted — the terminal renderer prints text — but a report with a
+ * thousand lines in it would still scroll the reason for it off the screen.
+ *
+ * @param {unknown} payload
+ */
+export function browserDiagnostic(payload) {
+  if (payload == null || typeof payload !== "object" || Array.isArray(payload)) return null;
+  const message = line(payload.message);
+  if (message === "") return null;
+
+  const severity = SEVERITIES.has(payload.severity) ? payload.severity : "error";
+  const diagnostic = { severity, message };
+  const origin = line(payload.url);
+  if (origin !== "") diagnostic.origin = origin;
+  const detail = lines(payload.detail);
+  if (detail.length > 0) diagnostic.detail = detail;
+  // A position, when the browser had one. It is what turns the status line
+  // into a code frame on the other side, and a browser that only knows "this
+  // component" rather than "this line" is expected: the frame is the better
+  // rendering when it is available and never a requirement.
+  const file = line(payload.file);
+  if (file !== "" && Number.isInteger(payload.line) && payload.line > 0) {
+    diagnostic.file = file;
+    diagnostic.line = payload.line;
+    if (Number.isInteger(payload.column) && payload.column >= 0) {
+      diagnostic.column = payload.column;
+    }
+  }
+  return diagnostic;
+}
+
+/**
+ * A `VitalsReport` as one diagnostic, or `null` when it carries no metric.
+ *
+ * One diagnostic per report rather than one per metric, because the beacon
+ * already coalesces across a microtask and a page load would otherwise be five
+ * separate lines interleaved with whatever else the terminal is saying. The
+ * severity is the worst rating in the report, which is the rule the issue asks
+ * for: a rating that is not `good` is the interesting one and has to read as
+ * one.
+ *
+ * @param {unknown} payload
+ */
+export function vitalsDiagnostic(payload) {
+  if (payload == null || typeof payload !== "object" || Array.isArray(payload)) return null;
+  if (!Array.isArray(payload.vitals)) return null;
+
+  const measured = [];
+  for (const vital of payload.vitals.slice(0, MAX_VITALS)) {
+    if (vital == null || typeof vital !== "object") continue;
+    if (typeof vital.name !== "string" || typeof vital.value !== "number") continue;
+    if (!Number.isFinite(vital.value)) continue;
+    // The name and the rating are the page's strings, not this module's, even
+    // though a beacon written by `@uniflowed/web/vitals` only ever sends the
+    // five names and the three ratings. Anything can post here, so they go
+    // through the same bounding and control-character scrub as a diagnostic's
+    // own text, and a *word* has no business being longer than a word.
+    const name = line(vital.name).slice(0, MAX_NAME_CHARS);
+    if (name === "") continue;
+    const rating = line(vital.rating).slice(0, MAX_NAME_CHARS) || "unknown";
+    measured.push({ name, value: vital.value, rating });
+  }
+  if (measured.length === 0) return null;
+
+  // Worst first, so the line the reader needs is the line under the headline
+  // rather than wherever the browser happened to finish measuring.
+  measured.sort((left, right) => severityOf(right.rating) - severityOf(left.rating));
+  const worst = measured[0];
+  const severity = ratingSeverity(worst.rating);
+  const message =
+    severity === "info"
+      ? `web vitals: ${measured.map((vital) => vital.name).join(", ")} good`
+      : `web vitals: ${worst.name} is ${worst.rating} (${formatValue(worst)})`;
+
+  const diagnostic = {
+    severity,
+    message,
+    detail: measured.map((vital) => `${vital.name} ${formatValue(vital)} — ${vital.rating}`),
+  };
+  const origin = line(payload.url);
+  if (origin !== "") diagnostic.origin = origin;
+  return diagnostic;
+}
+
+/** How bad a rating is, for ordering; an unknown word sorts as the worst. */
+function severityOf(rating) {
+  if (rating === "good") return 0;
+  if (rating === "needs-improvement") return 1;
+  return 2;
+}
+
+/** The channel severity a rating maps to. */
+function ratingSeverity(rating) {
+  if (rating === "good") return "info";
+  if (rating === "needs-improvement") return "warn";
+  return "error";
+}
+
+/**
+ * A metric's value with its unit.
+ *
+ * CLS is a unitless layout-shift score and everything else is milliseconds,
+ * which is the one thing a reader has to know to act on the number — a `0.24`
+ * printed as `0.24 ms` reads as the best result in the report rather than a
+ * failing one.
+ */
+function formatValue(vital) {
+  if (vital.name === "CLS") return String(Math.round(vital.value * 1000) / 1000);
+  return `${Math.round(vital.value)} ms`;
+}
+
+/** One bounded single-line string, or `""` for anything that is not one. */
+function line(value) {
+  if (typeof value !== "string") return "";
+  return printable(value).trim();
+}
+
+/** A bounded list of bounded lines, from a string or an array of them. */
+function lines(value) {
+  const source = typeof value === "string" ? value.split("\n") : value;
+  if (!Array.isArray(source)) return [];
+  const kept = [];
+  for (const entry of source) {
+    if (kept.length === MAX_DETAIL_LINES) {
+      kept.push("…");
+      break;
+    }
+    if (typeof entry !== "string") continue;
+    kept.push(printable(entry));
+  }
+  return kept;
+}
+
+/**
+ * One line of page-authored text, safe to write to a terminal and bounded.
+ *
+ * Every control character becomes a space, `ESC` included, and that is the
+ * point rather than tidiness: what is being rendered was written by a page, and
+ * a page that could put `ESC [` into a diagnostic could move the cursor,
+ * recolour the rest of the session or overwrite the line above its own report.
+ * `uf` owns this terminal — see `internal/events.js` — and nothing that arrives
+ * over a socket gets to draw on it.
+ *
+ * A scan rather than a regular expression, per `docs/security.md`'s "no regex
+ * on untrusted input": the rule is about backtracking and a character class
+ * cannot backtrack, but a loop needs no argument at all and is no longer.
+ */
+function printable(value) {
+  let text = "";
+  for (const character of value.slice(0, MAX_LINE_CHARS)) {
+    const code = character.codePointAt(0);
+    text += code < 0x20 || code === 0x7f ? " " : character;
+  }
+  return text;
+}
+
+/**
+ * The whole request body, or `null` when it is over `limit`.
+ *
+ * Counted as it arrives rather than trusting `content-length`: the header is
+ * the sender's claim and the bytes are the fact, and `sendBeacon` sends
+ * neither a length this side should rely on nor a content type worth reading —
+ * a string payload goes out as `text/plain`, so the type says nothing about
+ * whether the body is the JSON both endpoints document.
+ */
+async function readBody(request, limit) {
+  let size = 0;
+  const chunks = [];
+  for await (const chunk of request) {
+    size += chunk.length;
+    if (size > limit) return null;
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}

package/internal/events.js

@@ -54,11 +54,11 @@ export function stripAnsi(text) {
 /**
  * Report a page that rendered its error boundary instead of itself.
  *
- * `uf dev` has two renderers — the plugin's middleware and the driver's — and
- * this is the one place either of them says so, because a message written
- * twice is a message that ends up saying two things. The document the browser
- * gets is the application's error page, which is what a visitor would see;
- * the exception belongs in the terminal, which is uf's.
+ * The document the browser gets is the application's error page, which is what
+ * a visitor would see; the exception belongs in the terminal, which is uf's.
+ * There is one renderer under `uf dev` and therefore one caller of this — see
+ * `../index.js` — where there used to be two middlewares and a message that
+ * could be written twice.
  *
  * The stack is mapped back onto the Flow source first, so the frames name the
  * file that was written rather than the one that was compiled.

package/internal/routes.js

@@ -547,6 +547,25 @@ export const VIRTUAL = Object.freeze({
  * `virtual:uf/server` is generated with the default and always will be: the
  * server renders every route, so its table is the complete one.
  *
+ * # `relativeTo`, and the one string in this table a browser can read
+ *
+ * Every `import()` here is a specifier Vite resolves and rewrites to a chunk
+ * URL, so no absolute path survives the build — except `file`, which is a
+ * string. It is the route's source path, kept for diagnostics: the middleware
+ * table's is what names a module in an error, and `router.js`'s generated
+ * types are about the same files.
+ *
+ * The server's table can hold an absolute path; it is read on the machine that
+ * has those files. The browser's cannot, because that table is downloaded:
+ * uf's own manual shipped `/home/<user>/…/docs/app/guide/cache/_uf.page.mdx`
+ * for each of thirty-four routes to every visitor, which publishes the build
+ * machine's layout and its user's name for nothing — the browser has no
+ * filesystem to resolve them against and reads them only in a message.
+ *
+ * So the client call passes the project root and every `file` here is emitted
+ * relative to it. Diagnostics keep a path a person can act on — a shorter one
+ * — and a deploy stops describing the machine it was built on.
+ *
  * @param {{
  *   routes: Route[],
  *   handlers?: Handler[],
@@ -554,10 +573,29 @@ export const VIRTUAL = Object.freeze({
  *   notFound?: NotFoundBoundary[],
  *   errors?: ErrorBoundary[],
  * }} table
- * @param {{shipsPage?: (route: Route) => boolean}} [options]
+ * @param {{
+ *   shipsPage?: (route: Route) => boolean,
+ *   relativeTo?: string,
+ * }} [options]
  */
 export function routesModuleSource(table, options = {}) {
   const shipsPage = options.shipsPage ?? (() => true);
+  const relativeTo = options.relativeTo ?? null;
+  /**
+   * A `file` as this table should state it.
+   *
+   * Relative even when that means leading `..` segments — a module outside the
+   * project root is rare and a `../` path still says where it is without
+   * saying where the machine is, which is the whole property. Separators are
+   * POSIX because this string is read wherever the bundle is opened rather
+   * than where it was written.
+   */
+  const displayFile = (file) => {
+    if (relativeTo == null || file == null) {
+      return file;
+    }
+    return path.relative(relativeTo, file).split(path.sep).join("/");
+  };
   const layoutIds = new Map();
   const layoutImports = [];
   const layoutId = (file) => {
@@ -616,7 +654,7 @@ export function routesModuleSource(table, options = {}) {
     path: ${JSON.stringify(route.path)},
     params: ${JSON.stringify(route.params)},
     mdx: ${route.mdx},
-    file: ${JSON.stringify(route.page)},
+    file: ${JSON.stringify(displayFile(route.page))},
     layouts: [],
     loading: [],
     templates: [],
@@ -633,7 +671,7 @@ export function routesModuleSource(table, options = {}) {
     path: ${JSON.stringify(route.path)},
     params: ${JSON.stringify(route.params)},
     mdx: ${route.mdx},
-    file: ${JSON.stringify(route.page)},
+    file: ${JSON.stringify(displayFile(route.page))},
     page: () => import(${JSON.stringify(route.page)}),
     layouts: [${layouts.join(", ")}],
     loading: [${loading.join(", ")}],
@@ -648,7 +686,7 @@ export function routesModuleSource(table, options = {}) {
   const SYNTHESISED = JSON.stringify("@uniflowed/router");
   const boundaryModule = (file) =>
     file == null ? "null" : `() => import(${JSON.stringify(file)})`;
-  const boundaryFile = (file) => (file == null ? SYNTHESISED : JSON.stringify(file));
+  const boundaryFile = (file) => (file == null ? SYNTHESISED : JSON.stringify(displayFile(file)));
 
   // A list, because a not-found is a segment file: every directory may declare
   // one and the router takes the nearest above the path. `layoutId` is the
@@ -684,7 +722,7 @@ export function routesModuleSource(table, options = {}) {
     (handler) => `  {
     path: ${JSON.stringify(handler.path)},
     params: ${JSON.stringify(handler.params)},
-    file: ${JSON.stringify(handler.module)},
+    file: ${JSON.stringify(displayFile(handler.module))},
     load: () => import(${JSON.stringify(handler.module)}),
   }`,
   );
@@ -697,7 +735,7 @@ export function routesModuleSource(table, options = {}) {
   const middlewareEntries = (table.middleware ?? []).map(
     (entry) => `  {
     path: ${JSON.stringify(entry.path)},
-    file: ${JSON.stringify(entry.module)},
+    file: ${JSON.stringify(displayFile(entry.module))},
     load: () => import(${JSON.stringify(entry.module)}),
   }`,
   );

package/internal/serve.js

@@ -245,21 +245,7 @@ export function assetsFromManifest(manifest) {
  * @param {() => Promise<mixed>} body
  */
 export async function withRequest(entry, request, body) {
-  const lifecycle = entry.beginRequest(request);
-  const { run, settle } = lifecycle;
-  // What this host can do, put on the request the way `createFetchHandler`
-  // puts it on the one it owns. `uf dev` and `uf build --compile` reach a
-  // route handler without going through that function, and a handler that
-  // streams events or queues work has to get the same answer from all four
-  // front doors — a capability that is present under `uf start` and absent
-  // under `uf dev` is the difference this whole seam exists to remove.
-  //
-  // `nodeCapabilities`, because both of those *are* a Node process with a
-  // socket: a body reaches the client as it is written, and the process is
-  // still there afterwards. Neither passes an upgrader or a queue, because uf
-  // defines both and implements neither.
-  const { nodeCapabilities } = await deployment();
-  lifecycle.context.capabilities ??= nodeCapabilities();
+  const { run, settle } = await beginRequest(entry, request);
   try {
     return await run(body);
   } finally {
@@ -267,6 +253,44 @@ export async function withRequest(entry, request, body) {
   }
 }
 
+/**
+ * Begin a request on this host, with what this host can do already on it.
+ *
+ * The half of [`withRequest`] that a caller which may *not* answer needs.
+ * `uf dev` runs the application's middleware, its action endpoint and its
+ * dispatcher for every request, and hands the ones none of them claimed back
+ * to Vite's chain — at which point the response is written somewhere this
+ * module cannot see, so settling has to wait for the socket rather than for a
+ * `finally` here. A caller that always answers should use [`withRequest`] and
+ * not think about it.
+ *
+ * `entry.beginRequest` and not an import: the request lives in an
+ * `AsyncLocalStorage` belonging to one copy of `@uniflowed/server`, and the
+ * copy that matters is the one inside the application bundle. See
+ * `serverModuleSource` in `./routes.js`.
+ *
+ * What this host can do is put on the request the way `createFetchHandler`
+ * puts it on the one it owns. `uf dev` and `uf build --compile` reach a route
+ * handler without going through that function, and a handler that streams
+ * events or queues work has to get the same answer from all four front doors —
+ * a capability that is present under `uf start` and absent under `uf dev` is
+ * the difference this whole seam exists to remove.
+ *
+ * `nodeCapabilities`, because both of those *are* a Node process with a
+ * socket: a body reaches the client as it is written, and the process is still
+ * there afterwards. Neither passes an upgrader or a queue, because uf defines
+ * both and implements neither.
+ *
+ * @param {{beginRequest: (request: Request) => {context: object, run: <T>(body: () => Promise<T>) => Promise<T>, settle: () => Promise<void>}}} entry
+ * @param {Request} request
+ */
+export async function beginRequest(entry, request) {
+  const lifecycle = entry.beginRequest(request);
+  const { nodeCapabilities } = await deployment();
+  lifecycle.context.capabilities ??= nodeCapabilities();
+  return lifecycle;
+}
+
 /**
  * The application half: route handlers, then rendering.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/vite",
-  "version": "0.0.0-alpha.13",
+  "version": "0.0.0-alpha.14",
   "description": "Vite, driven by uf.config.js: every Flow module through `uf transform`, MDX, the file-system router and static rendering as Vite plugins.",
   "type": "module",
   "license": "MIT",
@@ -10,6 +10,14 @@
     "url": "git+https://github.com/ubugeeei-prod/uf.git",
     "directory": "packages/vite"
   },
+  "uf": {
+    "builder": {
+      "driver": "./driver.js",
+      "preload": {
+        "bun": "@uniflowed/host/bun-preload"
+      }
+    }
+  },
   "exports": {
     ".": "./index.js",
     "./driver": "./driver.js",
@@ -25,8 +33,8 @@
   "dependencies": {
     "@mdx-js/rollup": "^3.1.1",
     "@shikijs/rehype": "^3.23.0",
-    "@uniflowed/host": "0.0.0-alpha.13",
-    "@uniflowed/server": "0.0.0-alpha.13",
+    "@uniflowed/host": "0.0.0-alpha.14",
+    "@uniflowed/server": "0.0.0-alpha.14",
     "rehype-slug": "^6.0.0",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.1",