refactor: export wrapFindRouteWithTracing helper, remove plugin-side ~findRoute patching

Per maintainer feedback, move ~findRoute wrapping out of the tracing
plugin and into a standalone exported helper. Frameworks like nitro can
opt in by calling wrapFindRouteWithTracing() on their own ~findRoute
function, keeping h3's plugin lean and the runtime cost explicit.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: logaretm

src/tracing.ts

@@ -1,6 +1,11 @@
 import type { H3Event } from "./event.ts";
 import type { H3, H3Core } from "./h3.ts";
-import { type H3Plugin, type H3Route, type MiddlewareOptions } from "./types/h3.ts";
+import {
+  type H3Plugin,
+  type H3Route,
+  type MatchedRoute,
+  type MiddlewareOptions,
+} from "./types/h3.ts";
 import type { EventHandler, Middleware } from "./types/handler.ts";
 
 /**
@@ -83,40 +88,6 @@ export function tracingPlugin(traceOpts?: TracingPluginOptions): H3Plugin {
       } satisfies H3Route;
     });
 
-    // Wrap route handlers returned by ~findRoute so frameworks that resolve
-    // routes at request time (e.g. nitro file-based routes) without pushing
-    // into ~routes still emit route traces. A fresh wrapper is rebuilt on
-    // every assignment so previously-captured references stay stable — a
-    // framework pattern like `const prev = app["~findRoute"]; app["~findRoute"]
-    // = (e) => prev(e)` must not recurse into itself.
-    const wrapFindRoute = (fn: H3Core["~findRoute"]): H3Core["~findRoute"] => {
-      return (event: H3Event) => {
-        const route = fn.call(h3, event);
-        // Mutate route.data in place: findRoute often returns shared references
-        // (e.g. entries from ~routes), and the wrappers are idempotent via
-        // __traced__, so repeated calls on the same object are cheap. Do not
-        // clone — a cloned route would re-wrap on every request.
-        if (route?.data.handler) {
-          route.data.handler = wrapEventHandler(route.data.handler);
-        }
-        if (route?.data.middleware) {
-          for (let i = 0; i < route.data.middleware.length; i++) {
-            route.data.middleware[i] = wrapMiddleware(route.data.middleware[i]);
-          }
-        }
-        return route;
-      };
-    };
-    let wrappedFindRoute = wrapFindRoute(h3["~findRoute"]);
-    Object.defineProperty(h3, "~findRoute", {
-      configurable: true,
-      enumerable: false,
-      get: () => wrappedFindRoute,
-      set: (fn: H3Core["~findRoute"]) => {
-        wrappedFindRoute = wrapFindRoute(fn);
-      },
-    });
-
     if ("on" in h3 && typeof h3.on === "function") {
       const originalOn = h3.on;
 
@@ -176,3 +147,68 @@ export function tracingPlugin(traceOpts?: TracingPluginOptions): H3Plugin {
     return h3;
   };
 }
+
+type FindRouteFunction = (event: H3Event) => MatchedRoute<H3Route> | void;
+
+/**
+ * Wraps a `~findRoute` function so that returned route handlers and middleware
+ * are traced via the `h3.request` diagnostics channel. Intended for frameworks
+ * (e.g. nitro) that resolve routes at request time without pushing them into
+ * `h3["~routes"]`.
+ *
+ * Returns the original function unchanged when `diagnostics_channel` is not
+ * available.
+ */
+export function wrapFindRouteWithTracing(
+  findRoute: FindRouteFunction,
+  traceOpts?: TracingPluginOptions,
+): FindRouteFunction {
+  const { tracingChannel } = globalThis.process?.getBuiltinModule?.("diagnostics_channel") ?? {};
+
+  if (!tracingChannel) {
+    return findRoute;
+  }
+
+  const channel = tracingChannel("h3.request");
+
+  function wrapHandler(handler: MaybeTracedEventHandler): EventHandler {
+    if (handler.__traced__ || traceOpts?.traceRoutes === false) {
+      return handler;
+    }
+    const wrapped: MaybeTracedEventHandler = (...args) => {
+      return channel.tracePromise(async () => handler(...args), {
+        event: args[0],
+        type: "route",
+      } satisfies TracingRequestEvent);
+    };
+    wrapped.__traced__ = true;
+    return wrapped;
+  }
+
+  function wrapMiddleware(middleware: MaybeTracedMiddleware): Middleware {
+    if (middleware.__traced__ || traceOpts?.traceMiddleware === false) {
+      return middleware;
+    }
+    const wrapped: MaybeTracedMiddleware = (...args) => {
+      return channel.tracePromise(async () => middleware(...args), {
+        event: args[0],
+        type: "middleware",
+      } satisfies TracingRequestEvent);
+    };
+    wrapped.__traced__ = true;
+    return wrapped;
+  }
+
+  return (event: H3Event) => {
+    const route = findRoute(event);
+    if (route?.data.handler) {
+      route.data.handler = wrapHandler(route.data.handler);
+    }
+    if (route?.data.middleware) {
+      for (let i = 0; i < route.data.middleware.length; i++) {
+        route.data.middleware[i] = wrapMiddleware(route.data.middleware[i]);
+      }
+    }
+    return route;
+  };
+}

test/tracing.test.ts

@@ -1156,47 +1156,38 @@ describe("tracing channels for H3Core instances", () => {
       listener.cleanup();
     }
   });
+});
 
-  it("traces handlers returned from a custom ~findRoute (nitro-style file routes)", async () => {
+describe("wrapFindRouteWithTracing", () => {
+  it("wraps route handlers returned by findRoute", async () => {
     const listener = createTracingListener();
     const { H3Core } = await import("../src/h3.ts");
-    const { tracingPlugin } = await import("../src/tracing.ts");
+    const { wrapFindRouteWithTracing } = await import("../src/tracing.ts");
     const { H3Event } = await import("../src/event.ts");
 
     try {
       const app = new H3Core();
       const routeHandler = () => "file-based response";
 
-      // Simulate a framework that resolves routes at request time and never
-      // pushes them into app["~routes"]. The handler only exists inside the
-      // custom ~findRoute implementation.
-      app["~findRoute"] = (event: any) => {
+      const baseFindRoute = (event: any) => {
         if (event.url.pathname === "/file-route" && event.req.method === "GET") {
           return {
-            data: {
-              method: "GET",
-              route: "/file-route",
-              handler: routeHandler,
-            },
+            data: { method: "GET", route: "/file-route", handler: routeHandler },
             params: {},
           };
         }
         return undefined;
       };
 
-      // Apply tracing plugin after ~findRoute is set to verify the wrapper
-      // picks up the already-installed resolver.
-      tracingPlugin()(app as any);
+      app["~findRoute"] = wrapFindRouteWithTracing(baseFindRoute as any);
 
       const request = new Request("http://localhost/file-route", { method: "GET" });
       const event = new H3Event(request, undefined, app as any);
 
       await app.handler(event);
-
       await new Promise((resolve) => setTimeout(resolve, 10));
 
       const routeEvents = listener.events.filter((e) => e.asyncStart?.data.type === "route");
-
       expect(routeEvents.some((e) => e.asyncStart?.data.event.url.pathname === "/file-route")).toBe(
         true,
       );
@@ -1205,124 +1196,22 @@ describe("tracing channels for H3Core instances", () => {
     }
   });
 
-  it("traces handlers when ~findRoute is reassigned after tracingPlugin is applied", async () => {
-    const listener = createTracingListener();
-    const { H3Core } = await import("../src/h3.ts");
-    const { tracingPlugin } = await import("../src/tracing.ts");
-    const { H3Event } = await import("../src/event.ts");
-
-    try {
-      const app = new H3Core();
-      const routeHandler = () => "late-bound response";
-
-      // Apply plugin BEFORE the framework wires up routing (typical nitro
-      // order: plugins register, then file-based routing installs ~findRoute).
-      tracingPlugin()(app as any);
-
-      app["~findRoute"] = (event: any) => {
-        if (event.url.pathname === "/late-route" && event.req.method === "GET") {
-          return {
-            data: {
-              method: "GET",
-              route: "/late-route",
-              handler: routeHandler,
-            },
-            params: {},
-          };
-        }
-        return undefined;
-      };
-
-      const request = new Request("http://localhost/late-route", { method: "GET" });
-      const event = new H3Event(request, undefined, app as any);
-
-      await app.handler(event);
-      await new Promise((resolve) => setTimeout(resolve, 10));
-
-      const routeEvents = listener.events.filter((e) => e.asyncStart?.data.type === "route");
-      expect(routeEvents.some((e) => e.asyncStart?.data.event.url.pathname === "/late-route")).toBe(
-        true,
-      );
-    } finally {
-      listener.cleanup();
-    }
-  });
-
-  it("keeps ~findRoute non-enumerable after tracingPlugin is applied", async () => {
-    const { H3Core } = await import("../src/h3.ts");
-    const { tracingPlugin } = await import("../src/tracing.ts");
-
-    const app = new H3Core();
-    tracingPlugin()(app as any);
-
-    expect(Object.keys(app)).not.toContain("~findRoute");
-    const descriptor = Object.getOwnPropertyDescriptor(app, "~findRoute");
-    expect(descriptor?.enumerable).toBe(false);
-  });
-
-  it("does not recurse when a framework wraps ~findRoute via captured reference", async () => {
-    const listener = createTracingListener();
-    const { H3Core } = await import("../src/h3.ts");
-    const { tracingPlugin } = await import("../src/tracing.ts");
-    const { H3Event } = await import("../src/event.ts");
-
-    try {
-      const app = new H3Core();
-      const routeHandler = () => "ok";
-
-      tracingPlugin()(app as any);
-
-      // Common framework pattern: capture current ~findRoute then replace with
-      // a wrapper that delegates to the captured reference. Must not recurse.
-      const prev = app["~findRoute"];
-      app["~findRoute"] = (event: any) => {
-        const matched = prev.call(app, event);
-        if (matched) return matched;
-        if (event.url.pathname === "/wrapped" && event.req.method === "GET") {
-          return {
-            data: { method: "GET", route: "/wrapped", handler: routeHandler },
-            params: {},
-          };
-        }
-        return undefined;
-      };
-
-      const request = new Request("http://localhost/wrapped", { method: "GET" });
-      const event = new H3Event(request, undefined, app as any);
-
-      await app.handler(event);
-      await new Promise((resolve) => setTimeout(resolve, 10));
-
-      const routeEvents = listener.events.filter((e) => e.asyncStart?.data.type === "route");
-      expect(routeEvents.length).toBe(1);
-    } finally {
-      listener.cleanup();
-    }
-  });
-
-  it("does not double-wrap handlers across repeated ~findRoute calls", async () => {
+  it("does not double-wrap handlers across repeated calls", async () => {
     const listener = createTracingListener();
     const { H3Core } = await import("../src/h3.ts");
-    const { tracingPlugin } = await import("../src/tracing.ts");
+    const { wrapFindRouteWithTracing } = await import("../src/tracing.ts");
     const { H3Event } = await import("../src/event.ts");
 
     try {
       const app = new H3Core();
       const routeHandler = () => "ok";
 
-      // Cached route object returned from every ~findRoute call — mirrors a
-      // framework that memoizes resolved routes.
       const cachedRoute = {
-        data: {
-          method: "GET" as const,
-          route: "/cached",
-          handler: routeHandler,
-        },
+        data: { method: "GET" as const, route: "/cached", handler: routeHandler },
         params: {},
       };
-      app["~findRoute"] = () => cachedRoute;
 
-      tracingPlugin()(app as any);
+      app["~findRoute"] = wrapFindRouteWithTracing((() => cachedRoute) as any);
 
       const run = async () => {
         const request = new Request("http://localhost/cached", { method: "GET" });
@@ -1331,24 +1220,27 @@ describe("tracing channels for H3Core instances", () => {
       };
 
       await run();
-      // Handler wrapped in place on first call; reference should stay stable
-      // across subsequent calls (wrapEventHandler short-circuits on __traced__).
       const wrappedHandler = cachedRoute.data.handler;
       expect((wrappedHandler as any).__traced__).toBe(true);
 
       await run();
       await run();
 
       expect(cachedRoute.data.handler).toBe(wrappedHandler);
+
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const routeAsyncStarts = listener.events.filter((e) => e.asyncStart?.data.type === "route");
+      expect(routeAsyncStarts.length).toBe(3);
     } finally {
       listener.cleanup();
     }
   });
 
-  it("mutates cached route.data.middleware in place without reallocating the array", async () => {
+  it("mutates cached route.data.middleware in place without reallocating", async () => {
     const listener = createTracingListener();
     const { H3Core } = await import("../src/h3.ts");
-    const { tracingPlugin } = await import("../src/tracing.ts");
+    const { wrapFindRouteWithTracing } = await import("../src/tracing.ts");
     const { H3Event } = await import("../src/event.ts");
 
     try {
@@ -1365,9 +1257,8 @@ describe("tracing channels for H3Core instances", () => {
         },
         params: {},
       };
-      app["~findRoute"] = () => cachedRoute;
 
-      tracingPlugin()(app as any);
+      app["~findRoute"] = wrapFindRouteWithTracing((() => cachedRoute) as any);
 
       const run = async () => {
         const request = new Request("http://localhost/cached", { method: "GET" });
@@ -1383,15 +1274,12 @@ describe("tracing channels for H3Core instances", () => {
       await run();
       await run();
 
-      // Array identity and entry identity must remain stable — no per-request
-      // allocations once the middleware is already traced.
       expect(cachedRoute.data.middleware).toBe(middlewareArray);
       expect(cachedRoute.data.middleware[0]).toBe(wrappedMw);
 
       await new Promise((resolve) => setTimeout(resolve, 10));
 
       const routeAsyncStarts = listener.events.filter((e) => e.asyncStart?.data.type === "route");
-      // Exactly one route trace per request — no double-wrapping.
       expect(routeAsyncStarts.length).toBe(3);
     } finally {
       listener.cleanup();