feat(tracing): export wrapHandlerWithTracing for manual handler wrapping

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";
 
 /**
@@ -142,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

@@ -1157,3 +1157,132 @@ describe("tracing channels for H3Core instances", () => {
     }
   });
 });
+
+describe("wrapFindRouteWithTracing", () => {
+  it("wraps route handlers returned by findRoute", async () => {
+    const listener = createTracingListener();
+    const { H3Core } = await import("../src/h3.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";
+
+      const baseFindRoute = (event: any) => {
+        if (event.url.pathname === "/file-route" && event.req.method === "GET") {
+          return {
+            data: { method: "GET", route: "/file-route", handler: routeHandler },
+            params: {},
+          };
+        }
+        return undefined;
+      };
+
+      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,
+      );
+    } finally {
+      listener.cleanup();
+    }
+  });
+
+  it("does not double-wrap handlers across repeated calls", async () => {
+    const listener = createTracingListener();
+    const { H3Core } = await import("../src/h3.ts");
+    const { wrapFindRouteWithTracing } = await import("../src/tracing.ts");
+    const { H3Event } = await import("../src/event.ts");
+
+    try {
+      const app = new H3Core();
+      const routeHandler = () => "ok";
+
+      const cachedRoute = {
+        data: { method: "GET" as const, route: "/cached", handler: routeHandler },
+        params: {},
+      };
+
+      app["~findRoute"] = wrapFindRouteWithTracing((() => cachedRoute) as any);
+
+      const run = async () => {
+        const request = new Request("http://localhost/cached", { method: "GET" });
+        const event = new H3Event(request, undefined, app as any);
+        await app.handler(event);
+      };
+
+      await run();
+      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", async () => {
+    const listener = createTracingListener();
+    const { H3Core } = await import("../src/h3.ts");
+    const { wrapFindRouteWithTracing } = await import("../src/tracing.ts");
+    const { H3Event } = await import("../src/event.ts");
+
+    try {
+      const app = new H3Core();
+      const mw = (event: any) => {
+        event.context.mw = true;
+      };
+      const cachedRoute = {
+        data: {
+          method: "GET" as const,
+          route: "/cached",
+          handler: () => "ok",
+          middleware: [mw],
+        },
+        params: {},
+      };
+
+      app["~findRoute"] = wrapFindRouteWithTracing((() => cachedRoute) as any);
+
+      const run = async () => {
+        const request = new Request("http://localhost/cached", { method: "GET" });
+        const event = new H3Event(request, undefined, app as any);
+        await app.handler(event);
+      };
+
+      await run();
+      const middlewareArray = cachedRoute.data.middleware;
+      const wrappedMw = middlewareArray[0];
+      expect((wrappedMw as any).__traced__).toBe(true);
+
+      await run();
+      await run();
+
+      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");
+      expect(routeAsyncStarts.length).toBe(3);
+    } finally {
+      listener.cleanup();
+    }
+  });
+});