feat(tracing): export wrapHandlerWithTracing for manual handler wrapping

src/tracing.ts

@@ -83,6 +83,30 @@ 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. Use a getter/setter so later
+    // reassignment of ~findRoute remains wrapped.
+    let originalFindRoute = h3["~findRoute"];
+    const wrappedFindRoute = (event: H3Event) => {
+      const route = originalFindRoute.call(h3, event);
+      if (route?.data.handler) {
+        route.data.handler = wrapEventHandler(route.data.handler);
+      }
+      if (route?.data.middleware) {
+        route.data.middleware = route.data.middleware.map((m) => wrapMiddleware(m));
+      }
+      return route;
+    };
+    Object.defineProperty(h3, "~findRoute", {
+      configurable: true,
+      enumerable: true,
+      get: () => wrappedFindRoute,
+      set: (fn: typeof originalFindRoute) => {
+        originalFindRoute = fn;
+      },
+    });
+
     if ("on" in h3 && typeof h3.on === "function") {
       const originalOn = h3.on;
 

test/tracing.test.ts

@@ -1156,4 +1156,94 @@ describe("tracing channels for H3Core instances", () => {
       listener.cleanup();
     }
   });
+
+  it("traces handlers returned from a custom ~findRoute (nitro-style file routes)", 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 = () => "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) => {
+        if (event.url.pathname === "/file-route" && event.req.method === "GET") {
+          return {
+            data: {
+              method: "GET",
+              route: "/file-route",
+              handler: routeHandler,
+            },
+            params: {},
+          };
+        }
+        return undefined;
+      };
+
+      // Apply tracing plugin after ~findRoute is set (mirrors the order
+      // documented in the suggested fix).
+      tracingPlugin()(app 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.length).toBeGreaterThan(0);
+    } finally {
+      listener.cleanup();
+    }
+  });
+
+  it("does not double-wrap handlers across repeated ~findRoute calls", 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";
+
+      // 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,
+        },
+        params: {},
+      };
+      app["~findRoute"] = () => cachedRoute;
+
+      tracingPlugin()(app 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();
+      await run();
+      await run();
+
+      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();
+    }
+  });
 });