@uniflowed/router 0.0.0-alpha.41 → 0.0.0-alpha.43

package/instrumentation.js

@@ -0,0 +1,92 @@
+// @flow
+
+export type NavigationTiming = {|
+  readonly kind: "document" | "router",
+  readonly pathname: string,
+  readonly duration: number,
+  readonly status: "complete" | "error",
+|};
+
+export type ClientInstrumentation = {|
+  readonly register?: () => void | Promise<void>,
+  readonly onError?: (
+    error: mixed,
+    context: {| readonly source: "error" | "unhandledrejection" | "navigation" | "startup" |},
+  ) => void | Promise<void>,
+  readonly onNavigation?: (timing: NavigationTiming) => void | Promise<void>,
+|};
+
+const observers: Set<ClientInstrumentation> = new Set();
+
+function notify(body: () => mixed): void {
+  Promise.resolve()
+    .then(body)
+    .catch((error) => console.error("uf client instrumentation failed", error));
+}
+
+/** Installed by the client entry before hydration, with disposal during HMR. */
+export async function installClientInstrumentation(
+  hooks: ClientInstrumentation,
+): Promise<() => void> {
+  const error = (event: ErrorEvent) =>
+    notify(() => hooks.onError?.(event.error ?? event.message, { source: "error" }));
+  const rejection = (event: PromiseRejectionEvent) =>
+    notify(() => hooks.onError?.(event.reason, { source: "unhandledrejection" }));
+  window.addEventListener("error", error);
+  window.addEventListener("unhandledrejection", rejection);
+  observers.add(hooks);
+  let performanceObserver = null;
+  if (
+    typeof PerformanceObserver === "function" &&
+    PerformanceObserver.supportedEntryTypes.includes("navigation")
+  ) {
+    performanceObserver = new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        const timing: NavigationTiming = {
+          kind: "document",
+          pathname: new URL(entry.name).pathname,
+          duration: entry.duration,
+          status: "complete",
+        };
+        notify(() => hooks.onNavigation?.(timing));
+      }
+    });
+    performanceObserver.observe({ type: "navigation", buffered: true });
+  }
+  const dispose = () => {
+    window.removeEventListener("error", error);
+    window.removeEventListener("unhandledrejection", rejection);
+    observers.delete(hooks);
+    performanceObserver?.disconnect();
+  };
+  try {
+    await hooks.register?.();
+  } catch (failure) {
+    notify(() => hooks.onError?.(failure, { source: "startup" }));
+    dispose();
+  }
+  return dispose;
+}
+
+/** The router's asynchronous navigation work; a hard navigation has browser timing entries. */
+export async function observeNavigation<T>(to: string, body: () => Promise<T>): Promise<T> {
+  if (observers.size === 0) return body();
+  const started = performance.now();
+  const pathname = new URL(to, window.location.href).pathname;
+  let status: NavigationTiming["status"] = "complete";
+  try {
+    return await body();
+  } catch (error) {
+    status = "error";
+    for (const hooks of observers) notify(() => hooks.onError?.(error, { source: "navigation" }));
+    throw error;
+  } finally {
+    const timing: NavigationTiming = {
+      kind: "router",
+      pathname,
+      duration: performance.now() - started,
+      status,
+    };
+    for (const hooks of observers) notify(() => hooks.onNavigation?.(timing));
+  }
+}

package/internal/action-endpoint.js

@@ -88,6 +88,8 @@
 // it. Written here because this is the file somebody reads before deciding
 // otherwise.
 
+import { traceRequestPhase, reportRequestError } from "@uniflowed/server/instrumentation";
+
 import { asResponder, nativeActionAllowed } from "@uniflowed/server/host";
 
 import {
@@ -232,7 +234,7 @@ export function createActionDispatcher(options: {|
         // `decodeActionArguments` produced, so what is unchecked here is the
         // shape of the function and not the shape of the payload.
         const call = action as $FlowFixMe;
-        result = await call(...args);
+        result = await traceRequestPhase("action", () => call(...args));
       } catch (error) {
         report(record, error);
         return refusal(500);
@@ -430,6 +432,7 @@ function refusal(status: number): Response {
  * here and nowhere the caller can read.
  */
 function report(record: ActionRecord, error: mixed): void {
+  reportRequestError(error, "action");
   // eslint-disable-next-line no-console
   console.error(`uf: server action \`${record.export}\` in \`${record.module}\` failed`, error);
 }

package/internal/resolve.js

@@ -722,6 +722,8 @@ export type ResolveOptions = {|
   readonly defer?: boolean,
   /** The route pattern, the moment the URL matches one; see [`resolveMatch`]. */
   readonly onMatch?: (pattern: string) => void,
+  /** The server supplies tracing without importing server code into the browser. */
+  readonly runLoader?: (body: () => mixed | Promise<mixed>) => Promise<mixed>,
 |};
 
 async function resolveRoute(
@@ -799,7 +801,9 @@ async function resolveRoute(
   let data: mixed = options?.data;
   let deferred: ?Promise<mixed> = null;
   if (options?.skipLoader !== true && typeof page.loader === "function") {
-    const running = page.loader({ params: matched.params, searchParams, pathname });
+    const loader = page.loader;
+    const loadData = () => loader({ params: matched.params, searchParams, pathname });
+    const running = options?.runLoader == null ? loadData() : options.runLoader(loadData);
     const canDefer =
       options?.defer === true &&
       (matched.route.loading ?? []).length > 0 &&

package/internal/runtime.js

@@ -20,6 +20,8 @@
 
 "use client";
 
+import { observeNavigation } from "../instrumentation.js";
+
 import type * as React from "react";
 import {
   Suspense,
@@ -665,7 +667,9 @@ component ModuleRouter(url: string, initial: ResolvedRoute, children: React.Node
     setResolved(next);
   };
 
-  const navigate = async (to: string, options?: NavigateOptions): Promise<void> => {
+  const navigate = (to: string, options?: NavigateOptions): Promise<void> =>
+    observeNavigation(to, () => navigateTo(to, options));
+  const navigateTo = async (to: string, options?: NavigateOptions): Promise<void> => {
     if (!isBrowser()) {
       return;
     }
@@ -985,7 +989,9 @@ component FlightRouter(flight: Promise<FlightRoot>, children: React.Node) {
   // Read once per render, for the reason `ModuleRouter` reads it once.
   const navigation = navigationMode();
 
-  const navigate = async (to: string, options?: NavigateOptions): Promise<void> => {
+  const navigate = (to: string, options?: NavigateOptions): Promise<void> =>
+    observeNavigation(to, () => navigateTo(to, options));
+  const navigateTo = async (to: string, options?: NavigateOptions): Promise<void> => {
     if (!isBrowser()) {
       return;
     }

package/internal/server-instrumentation.js

@@ -0,0 +1,12 @@
+// @flow
+
+import { traceRequestPhase } from "@uniflowed/server/instrumentation";
+import { NotFoundError, RedirectError } from "./routing.js";
+
+export function traceLoader(body: () => mixed | Promise<mixed>): Promise<mixed> {
+  return traceRequestPhase(
+    "loader",
+    async () => body(),
+    (error) => error instanceof RedirectError || error instanceof NotFoundError,
+  );
+}

package/internal/stream.js

@@ -311,9 +311,16 @@ async function* assembled(
   chunks: AsyncGenerator<string, void, void>,
   shell: DocumentShell,
   transformHead?: (html: string) => Promise<string>,
+  layout?: Layout,
 ): AsyncGenerator<string, void, void> {
   let held = "";
   let shape = "unknown";
+  // A document uf wraps is the only one whose root is not `<body>` itself.
+  const wrapped = () => {
+    if (layout != null) {
+      layout.rootDepth = advanced(NOTHING_WRITTEN, shell.open + shell.body, 0).depth ?? 0;
+    }
+  };
   // The opening chunk is the only one the hook sees, and every path below
   // reaches exactly one of them. Awaiting here rather than at each `yield`
   // keeps them from drifting apart. The hook sees only the document opening:
@@ -343,6 +350,7 @@ async function* assembled(
         continue;
       }
       shape = "shell-open";
+      wrapped();
       yield await opening(shell.open + split.head + shell.body, split.rest);
       held = "";
       continue;
@@ -382,6 +390,7 @@ async function* assembled(
     // still open is over and whatever was left of it is markup like any other.
     const split = hoisted(held);
     shape = "shell-open";
+    wrapped();
     yield await opening(shell.open + split.head + shell.body, split.rest);
   }
   if (shape === "shell-open") {
@@ -721,7 +730,9 @@ export function renderDocument(node: React.Node, options: RenderOptions): Promis
             bodyOf(
               outgoing(
                 withPayload(
-                  assembled(queue.chunks(), options.shell, options.transformHead),
+                  queue.chunks(),
+                  options.shell,
+                  options.transformHead,
                   options.payload,
                   options.nonce,
                 ),
@@ -801,7 +812,9 @@ export function renderWithReadableStream(
     bodyOf(
       outgoing(
         withPayload(
-          assembled(decoded(stream), options.shell, options.transformHead),
+          decoded(stream),
+          options.shell,
+          options.transformHead,
           options.payload,
           options.nonce,
         ),
@@ -861,26 +874,54 @@ export async function prerenderDocument(node: React.Node, options: RenderOptions
       : await ReactDOMStatic.prerender(node, settings);
   return bodyOf(
     withPayload(
-      assembled(preludeChunks(result.prelude), options.shell, options.transformHead),
+      preludeChunks(result.prelude),
+      options.shell,
+      options.transformHead,
       options.payload,
     ),
   ).text();
 }
 
-/** `chunks` unchanged when there is no payload, and [`interleaved`] with one. */
+/**
+ * What [`assembled`] learns about a document that [`interleaved`] needs.
+ *
+ * Which shape a document has is decided on its opening bytes, inside
+ * `assembled`, and `interleaved` reads that document's chunks — so by the time
+ * it has HTML to follow, the answer is here.
+ */
+type Layout = {|
+  /**
+   * How many elements are open inside `<body>` where React's root begins: none
+   * for a document React wrote, and uf's own container for one uf wraps.
+   */
+  rootDepth: number,
+|};
+
+/** [`assembled`] alone when there is no payload, and [`interleaved`] with one. */
 function withPayload(
   chunks: AsyncGenerator<string, void, void>,
+  shell: DocumentShell,
+  transformHead: ?(html: string) => Promise<string>,
   payload: ?ReadableStream<Uint8Array>,
   nonce?: string | null,
 ): AsyncGenerator<string, void, void> {
-  return payload == null ? chunks : interleaved(chunks, payload, nonce);
+  if (payload == null) {
+    return assembled(chunks, shell, transformHead ?? undefined);
+  }
+  const layout: Layout = { rootDepth: 0 };
+  return interleaved(
+    assembled(chunks, shell, transformHead ?? undefined, layout),
+    payload,
+    nonce,
+    layout,
+  );
 }
 
 /**
  * A document's chunks, with the Flight payload it was rendered from written
  * into it as it arrives.
  *
- * Four rules, and each is the answer to a way the obvious version is wrong.
+ * Six rules, and each is the answer to a way the obvious version is wrong.
  *
  * **Nothing before the head.** The first chunk this is handed is the whole
  * opening of the document — `assembled` does not let one go until the head is
@@ -906,6 +947,19 @@ function withPayload(
  * from chunk to chunk, and otherwise waits for the HTML that finishes what is
  * open.
  *
+ * **Only where React steps over it.** Between elements is where the *parser*
+ * keeps a payload element. React is stricter: hydrating, it steps over an
+ * element it did not render only among the children of its root and of
+ * `<html>`, `<head>` and `<body>`. Anywhere deeper the element is a child the
+ * tree has no fiber for, the hydration fails there, and React throws the
+ * server's markup away and renders the document again. A shell that is one
+ * large element — a frame around the page, all of it rendered on the server —
+ * is written in many pieces, several of which end between two of its children,
+ * and a payload that was already waiting used to go out at the first of them.
+ * So [`advanced`] also follows how many elements are open inside `<body>`, and
+ * a payload waits for the root's own level: between React's top-level
+ * elements, which is where every streamed segment is written anyway.
+ *
  * **Outside replaceable boundaries.** Even between tags, a payload inside a
  * Suspense fallback disappears when React reveals its content. A browser that
  * loads the Flight reader afterwards then sees an incomplete stream. React's
@@ -927,6 +981,7 @@ async function* interleaved(
   chunks: AsyncGenerator<string, void, void>,
   payload: ReadableStream<Uint8Array>,
   nonce?: string | null,
+  layout?: Layout,
 ): AsyncGenerator<string, void, void> {
   const encoder = createChunkEncoder(nonce);
   const reader = payload.getReader();
@@ -992,7 +1047,7 @@ async function* interleaved(
       }
       if (text !== "") {
         yield text;
-        boundary = advanced(boundary, text);
+        boundary = advanced(boundary, text, layout?.rootDepth ?? 0);
       }
       next = chunks.next();
     }
@@ -1029,9 +1084,35 @@ type Boundary = {|
   readonly replaceable: number,
   /** A tag, or a comment, the HTML has started and not yet finished. */
   readonly open: string,
+  /** How many elements are open inside `<body>`; `null` until it has opened. */
+  readonly depth: number | null,
 |};
 
-const NOTHING_WRITTEN: Boundary = { safe: false, rawText: null, replaceable: 0, open: "" };
+const NOTHING_WRITTEN: Boundary = {
+  safe: false,
+  rawText: null,
+  replaceable: 0,
+  open: "",
+  depth: null,
+};
+
+/** Elements with no closing tag, for markup whose `/>` React did not write. */
+const VOID_ELEMENTS: $ReadOnlySet<string> = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr",
+]);
 
 /**
  * `boundary`, once `html` has been written after it.
@@ -1044,12 +1125,21 @@ const NOTHING_WRITTEN: Boundary = { safe: false, rawText: null, replaceable: 0,
  * the content of an inline script or stylesheet, where a `>` is code, so an
  * opening `<script>` or `<style>` is followed to its closing tag. A tag split
  * across two chunks is carried in `open` and read whole with the next one.
+ *
+ * And it may follow only HTML that leaves `rootDepth` elements open inside
+ * `<body>`, or none: the children of React's root and of `<body>` are the ones
+ * hydration steps over. Every tag from `<body>` on is counted for that, React's
+ * void elements by the `/>` it writes them with. Markup React did not write —
+ * `dangerouslySetInnerHTML` — can leave a tag open that the parser would close,
+ * and the count then stays too deep for the rest of the document. That errs the
+ * safe way: the payload waits, and goes out before `</body>` as it always can.
  */
-function advanced(boundary: Boundary, html: string): Boundary {
+function advanced(boundary: Boundary, html: string, rootDepth: number): Boundary {
   const text = boundary.open + html;
   let rawText = boundary.rawText;
   let replaceable = boundary.replaceable;
-  const tags = /<!--([\s\S]*?)-->|<(\/?)(script|style)(?=[\s/>])[^>]*>/gi;
+  let depth = boundary.depth;
+  const tags = /<!--([\s\S]*?)-->|<(\/?)([a-z][^\s/>]*)[^>]*?(\/?)>/gi;
   let tag = tags.exec(text);
   while (tag != null) {
     const comment = tag[1];
@@ -1060,20 +1150,36 @@ function advanced(boundary: Boundary, html: string): Boundary {
       }
     } else {
       const name = tag[3].toLowerCase();
-      if (tag[2] === "/") {
-        if (rawText === name) rawText = null;
-      } else if (rawText == null) {
-        rawText = name;
+      const closes = tag[2] === "/";
+      if (rawText != null) {
+        // Inside a script or a stylesheet a `<` is code, up to its own end tag.
+        if (closes && rawText === name) {
+          rawText = null;
+          if (depth != null) depth -= 1;
+        }
+      } else if (closes) {
+        if (depth != null) depth -= 1;
+      } else if (depth == null) {
+        if (name === "body") depth = 0;
+        else if (name === "script" || name === "style") rawText = name;
+      } else if (tag[4] !== "/" && !VOID_ELEMENTS.has(name)) {
+        depth += 1;
+        if (name === "script" || name === "style") rawText = name;
       }
     }
     tag = tags.exec(text);
   }
   const start = text.lastIndexOf("<");
   return {
-    safe: rawText == null && replaceable === 0 && text.endsWith(">"),
+    safe:
+      rawText == null &&
+      replaceable === 0 &&
+      text.endsWith(">") &&
+      (depth === 0 || (depth != null && depth === rootDepth)),
     rawText,
     replaceable,
     open: start > text.lastIndexOf(">") ? text.slice(start) : "",
+    depth,
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/router",
-  "version": "0.0.0-alpha.41",
+  "version": "0.0.0-alpha.43",
   "description": "The file-system router for Flow React applications: matching, layouts, loaders, navigation, server rendering and hydration.",
   "type": "module",
   "license": "MIT",
@@ -27,7 +27,8 @@
     "./handler": "./handler.js",
     "./middleware": "./middleware.js",
     "./native-navigation": "./native-navigation.js",
-    "./http-client": "./http-client.js"
+    "./http-client": "./http-client.js",
+    "./instrumentation": "./instrumentation.js"
   },
   "files": [
     "action.js",
@@ -45,6 +46,7 @@
     "server.js",
     "native-navigation.js",
     "http-client.js",
+    "instrumentation.js",
     "!*.test.js"
   ],
   "peerDependencies": {
@@ -69,7 +71,7 @@
     }
   },
   "dependencies": {
-    "@uniflowed/hooks": "0.0.0-alpha.41",
-    "@uniflowed/server": "0.0.0-alpha.41"
+    "@uniflowed/hooks": "0.0.0-alpha.43",
+    "@uniflowed/server": "0.0.0-alpha.43"
   }
 }

package/rsc.js

@@ -44,6 +44,8 @@
 // in this graph, and a boundary module without the directive is refused here,
 // with its file named, rather than by React with a sentence about functions.
 
+import { traceLoader } from "./internal/server-instrumentation.js";
+
 import * as React from "react";
 import { use } from "react";
 // React's Flight server. Only this graph can load it: it refuses to evaluate
@@ -51,6 +53,7 @@ import { use } from "react";
 import { renderToReadableStream } from "react-server-dom-parcel/server";
 
 import { noteRoute } from "@uniflowed/server/host";
+import { reportRequestError } from "@uniflowed/server/instrumentation";
 
 import { BoundaryReporter } from "./internal/boundaries.js";
 import { routeBoundaries } from "./internal/boundary-data.js";
@@ -175,7 +178,7 @@ export function createFlightRenderer(options: {|
           intercepted ??
           // `onMatch` records the route pattern on the request before the
           // loader runs, so every line the loader logs names its route.
-          (await resolveMatch(table, url, { defer, onMatch: noteRoute }));
+          (await resolveMatch(table, url, { defer, onMatch: noteRoute, runLoader: traceLoader }));
       } else {
         resolved = await resolveFailure(table, url, failure.error);
       }
@@ -199,13 +202,20 @@ export function createFlightRenderer(options: {|
       </>
     );
     const root: FlightRoot = { route: state, tree };
-    const report = settings?.onError;
+    const failure = renderFailure(route);
+    if (failure != null) reportRequestError(failure, "render");
+    const report = (error) => {
+      reportRequestError(error, "render");
+      if (settings?.onError != null) return settings.onError(error);
+      console.error(error);
+      return undefined;
+    };
     // Inside the route's store, so a server component's `useRoute()` finds the
     // route however many `await`s into the render it asks.
     const stream = withServerRoute(state, () =>
       renderToReadableStream(root, {
         // Handed over as it is, so that the digest it returns reaches the row.
-        // Absent, React logs the exception to the console itself.
+        // Our callback preserves React's console fallback when none was given.
         onError: report,
         signal: settings?.signal,
       }),
@@ -225,7 +235,11 @@ async function resolveFlightInterception(
     return null;
   }
   try {
-    const base = await resolveMatch(table, baseUrl, { defer });
+    const base = await resolveMatch(table, baseUrl, {
+      defer,
+      onMatch: noteRoute,
+      runLoader: traceLoader,
+    });
     return await resolveInterception(table, base, url);
   } catch (error) {
     if (error instanceof RedirectError) {

package/server.js

@@ -24,6 +24,8 @@
 // which.
 
 import { currentNonce, noteRoute } from "@uniflowed/server/host";
+import { traceLoader } from "./internal/server-instrumentation.js";
+
 import * as React from "react";
 
 import {
@@ -335,7 +337,11 @@ export function createRenderer(options: {|
     try {
       return {
         kind: "route",
-        route: await resolveMatch(table, url, { defer, onMatch: noteRoute }),
+        route: await resolveMatch(table, url, {
+          defer,
+          onMatch: noteRoute,
+          runLoader: traceLoader,
+        }),
       };
     } catch (error) {
       if (error instanceof RedirectError) {
@@ -512,3 +518,9 @@ export function shellDocument(assets: RenderAssets): string {
   const shell = shellFor(assets);
   return `${shell.open}${shell.body}${shell.close}`;
 }
+
+export {
+  createInstrumentation,
+  instrumentRender,
+  traceRequestPhase,
+} from "@uniflowed/server/instrumentation";