@honeybadger-io/nextjs 5.10.13 → 5.11.0

package/src/with-honeybadger.ts

@@ -1,7 +1,86 @@
 import Honeybadger from '@honeybadger-io/js';
 import { NextRequest, NextResponse } from 'next/server';
+import * as nextServer from 'next/server';
+import type { NextApiRequest, NextApiResponse } from 'next';
+import {
+  emitNodeRequestEvent,
+  emitRequestEvent,
+  insightsHttpEnabled,
+  now,
+  seedNodeRequestEventContext,
+  seedRequestEventContext,
+} from './insights-instrumentation';
+import type { NodeRequestLike } from './insights-instrumentation';
 
-function configure() {
+type WaitUntil = (promise: Promise<unknown>) => void
+
+/**
+ * The `waitUntil` primitive the hosting platform injects per request. Next.js
+ * resolves `after()` through this same accessor, and it is the only channel
+ * available in Pages Router API routes, which are invoked as `(req, res)` with
+ * no context argument to read it from.
+ */
+function requestContextWaitUntil(): WaitUntil | undefined {
+  const context = (globalThis as Record<symbol, unknown>)[Symbol.for('@next/request-context')] as
+    | { get?: () => { waitUntil?: WaitUntil } | undefined }
+    | undefined
+  const waitUntil = context?.get?.()?.waitUntil
+  return typeof waitUntil === 'function' ? waitUntil : undefined
+}
+
+/**
+ * Middleware receives a `NextFetchEvent` as its second argument. Duck-typed
+ * rather than `instanceof` so the edge bundle needs no runtime import, and
+ * bound because `waitUntil` is a class method that collects into the event.
+ */
+function eventWaitUntil(event: unknown): WaitUntil | undefined {
+  const waitUntil = (event as { waitUntil?: WaitUntil } | undefined)?.waitUntil
+  return typeof waitUntil === 'function' ? waitUntil.bind(event) : undefined
+}
+
+/**
+ * Ensure Insights events are delivered before the serverless/edge runtime
+ * freezes, without delaying the response where the runtime lets us avoid it.
+ *
+ * In order of preference: Next.js `after()` (stable in 15.1, App Router only —
+ * it needs App Router request context, so Pages Router must not call it), then
+ * a `waitUntil` from the middleware event or the platform request context,
+ * then a blocking `flushAsync()` when the runtime offers neither. Blocking is
+ * correct in that last case: no `waitUntil` means nothing is going to freeze
+ * the invocation out from under us.
+ *
+ * Delivery failures are logged by the events worker and must not break the handler.
+ */
+function scheduleFlush(options: { useAfter?: boolean; waitUntil?: WaitUntil } = {}): Promise<void> | void {
+  const flush = () => Honeybadger.flushAsync().catch(() => { /* logged by the events worker */ })
+
+  if (options.useAfter) {
+    const after = (nextServer as { after?: (cb: () => unknown) => void }).after
+    if (typeof after === 'function') {
+      // Exported but still refusable: `after()` throws outside a supported
+      // context. Fall through to the remaining strategies rather than failing
+      // the request.
+      try {
+        after(flush)
+        return
+      }
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      catch (error) {
+        // try waitUntil / blocking flush below
+      }
+    }
+  }
+
+  const waitUntil = options.waitUntil ?? requestContextWaitUntil()
+  if (waitUntil) {
+    waitUntil(flush())
+    return
+  }
+
+  return flush()
+}
+
+function configure(overrides?: Parameters<typeof Honeybadger.configure>[0]) {
   if (Honeybadger.config.apiKey?.length > 0) {
     return;
   }
@@ -21,7 +100,8 @@ function configure() {
       apiKey: process.env.NEXT_PUBLIC_HONEYBADGER_API_KEY,
       environment: process.env.NEXT_PUBLIC_VERCEL_ENV || process.env.VERCEL_ENV || process.env.NODE_ENV,
       revision: process.env.NEXT_PUBLIC_HONEYBADGER_REVISION,
-      projectRoot: 'webpack://_N_E/./'
+      projectRoot: 'webpack://_N_E/./',
+      ...overrides,
     })
     .beforeNotify((notice) => {
       if (!projectRoot) {
@@ -38,19 +118,169 @@ function configure() {
 }
 
 /**
- * Wraps a handler function with Honeybadger error reporting.
- * Use with Next.js API route handlers or middleware.
+ * Next.js uses thrown errors for control flow: `redirect()`, `notFound()`,
+ * `forbidden()` and `unauthorized()` all throw an error carrying a `digest`
+ * string (`NEXT_REDIRECT;...`, `NEXT_NOT_FOUND`, `NEXT_HTTP_ERROR_FALLBACK;...`).
+ * These are not real failures — the framework catches them upstream to produce
+ * the redirect/404/etc. — so we must let them propagate without reporting them,
+ * otherwise every redirect shows up as an error in Honeybadger.
+ *
+ * We match on the `NEXT_` prefix rather than an exhaustive list so that any
+ * present or future framework control-flow digest is covered. This is safe:
+ * genuine errors that React tags with a `digest` use an opaque hash, and other
+ * Next.js bailout signals (e.g. `BAILOUT_TO_CLIENT_SIDE_RENDERING`,
+ * `DYNAMIC_SERVER_USAGE`) are not `NEXT_`-prefixed, so neither is skipped.
+ */
+function isNextControlFlowError(error: unknown): boolean {
+  const digest = (error as { digest?: unknown } | null | undefined)?.digest
+  return typeof digest === 'string' && digest.startsWith('NEXT_')
+}
+
+type AppRouterHandler = (req: NextRequest | Request, ...args: unknown[]) => Promise<NextResponse>
+type PagesApiHandler = (req: NextApiRequest, res: NextApiResponse, ...args: unknown[]) => unknown
+
+/**
+ * Detects a Pages Router API invocation: `(req, res)` where `res` is a Node
+ * `ServerResponse`. We branch on this structurally because — unlike an App
+ * Router route handler — there is no returned `Response` to read the status
+ * from; it lives on `res.statusCode`.
+ */
+function isPagesApiInvocation(args: unknown[]): args is [NodeRequestLike, NextApiResponse] {
+  const req = args[0] as { headers?: unknown } | undefined
+  const res = args[1] as { statusCode?: unknown; end?: unknown } | undefined
+  return (
+    !!req && typeof req.headers === 'object' && req.headers !== null &&
+    !!res && typeof res.statusCode === 'number' && typeof res.end === 'function'
+  )
+}
+
+/**
+ * App Router route handlers and middleware: a web `Request`/`NextRequest` in, a
+ * `Response`/`NextResponse` out. The status comes from the returned response.
+ *
+ * `waitUntil` is present for middleware (from its `NextFetchEvent`); route
+ * handlers get `{ params }` as their second argument and rely on `after()`.
+ */
+async function handleAppRouterRequest(call: () => unknown, req: Request, canIsolate: boolean, waitUntil?: WaitUntil): Promise<unknown> {
+  const ids = seedRequestEventContext(req.headers)
+  if (canIsolate) {
+    Honeybadger.setEventContext(ids)
+  }
+  const start = insightsHttpEnabled() ? now() : null
+  try {
+    const response = await call()
+    if (start !== null) {
+      emitRequestEvent(req, (response as Response | undefined)?.status, start, ids)
+      await scheduleFlush({ useAfter: true, waitUntil })
+    }
+    return response
+  } catch (error) {
+    if (isNextControlFlowError(error)) {
+      throw error
+    }
+    if (start !== null) {
+      emitRequestEvent(req, 500, start, ids)
+      await scheduleFlush({ useAfter: true, waitUntil })
+    }
+    await Honeybadger.notifyAsync(error as Error)
+    throw error
+  }
+}
+
+/**
+ * Pages Router API routes: a Node `req`/`res` pair. The handler writes to `res`
+ * and returns nothing meaningful, so the final status is read from
+ * `res.statusCode` once it resolves.
+ */
+async function handlePagesApiRequest(call: () => unknown, req: NodeRequestLike, res: NextApiResponse, canIsolate: boolean): Promise<unknown> {
+  const ids = seedNodeRequestEventContext(req.headers)
+  if (canIsolate) {
+    Honeybadger.setEventContext(ids)
+  }
+  const start = insightsHttpEnabled() ? now() : null
+  try {
+    const result = await call()
+    if (start !== null) {
+      emitNodeRequestEvent(req, res.statusCode, start, ids)
+      // No after() here: Pages Router lacks the App Router request context it
+      // needs. scheduleFlush falls through to the platform waitUntil instead.
+      await scheduleFlush({ useAfter: false })
+    }
+    return result
+  } catch (error) {
+    if (isNextControlFlowError(error)) {
+      throw error
+    }
+    if (start !== null) {
+      emitNodeRequestEvent(req, 500, start, ids)
+      await scheduleFlush({ useAfter: false })
+    }
+    await Honeybadger.notifyAsync(error as Error)
+    throw error
+  }
+}
+
+/**
+ * Unrecognised invocation shape: still report errors, but emit no insights
+ * event since we can't reliably read the request.
+ */
+async function handleUninstrumented(call: () => unknown): Promise<unknown> {
+  try {
+    return await call()
+  } catch (error) {
+    if (isNextControlFlowError(error)) {
+      throw error
+    }
+    await Honeybadger.notifyAsync(error as Error)
+    throw error
+  }
+}
+
+/**
+ * Wraps a handler function with Honeybadger error reporting. Works with App
+ * Router route handlers, middleware, and Pages Router API routes.
+ *
+ * `request_id` / `correlation_id` are read from the `x-request-id` /
+ * `request-id` and `x-correlation-id` / `x-amzn-trace-id` headers (generated
+ * when absent). When `insights: { enabled: true, http: true }` is configured,
+ * a `request.handled` event carrying the ids plus method, path, status and
+ * duration is emitted per request.
+ *
+ * On the Node.js runtime each invocation additionally runs inside
+ * `Honeybadger.run(...)`, so context is isolated per request and the ids are
+ * seeded onto the event context — merged onto every event emitted during the
+ * request, including programmatic `Honeybadger.event(...)` calls. On the edge
+ * runtime (browser build, single global store) seeding the shared event
+ * context would leak ids between concurrent requests, so programmatic events
+ * there don't inherit them.
+ *
+ * The webpack config-file auto-injection (`honeybadger.*.config.js`) doesn't
+ * reach API routes or edge middleware, so pass `config` to configure
+ * Honeybadger explicitly there. It's ignored if Honeybadger is already
+ * configured (e.g. by the auto-injected file).
  */
-export function withHoneybadger(handler: (req: NextRequest | Request, ...args: unknown[]) => Promise<NextResponse>) {
-  configure();
+export function withHoneybadger(handler: AppRouterHandler, config?: Parameters<typeof Honeybadger.configure>[0]): AppRouterHandler
+export function withHoneybadger(handler: PagesApiHandler, config?: Parameters<typeof Honeybadger.configure>[0]): PagesApiHandler
+export function withHoneybadger(handler: AppRouterHandler | PagesApiHandler, config?: Parameters<typeof Honeybadger.configure>[0]) {
+  configure(config);
   return new Proxy(handler, {
-    apply: async (target, thisArg, args) => {
-      try {
-        return await Reflect.apply(target, thisArg, args);
-      } catch (error) {
-        await Honeybadger.notifyAsync(error as Error);
-        throw error; // Re-throw the error after reporting it
+    apply: (target, thisArg, args) => {
+      const canIsolate = typeof Honeybadger.run === 'function'
+      const call = () => Reflect.apply(target, thisArg, args)
+
+      const invoke = (): unknown => {
+        // App Router / middleware first: a web Request as the first argument.
+        if (typeof Request !== 'undefined' && args[0] instanceof Request) {
+          return handleAppRouterRequest(call, args[0], canIsolate, eventWaitUntil(args[1]))
+        }
+        // Pages Router API route: a Node req/res pair.
+        if (isPagesApiInvocation(args)) {
+          return handlePagesApiRequest(call, args[0], args[1], canIsolate)
+        }
+        return handleUninstrumented(call)
       }
+
+      return canIsolate ? Honeybadger.run(invoke) : invoke()
     },
   });
 }

package/templates/honeybadger.browser.config.js

@@ -1,11 +1,13 @@
 import { Honeybadger } from '@honeybadger-io/react'
 
-Honeybadger.configure({
+export const config = {
   apiKey: process.env.NEXT_PUBLIC_HONEYBADGER_API_KEY,
   environment: process.env.NEXT_PUBLIC_VERCEL_ENV || process.env.VERCEL_ENV || process.env.NODE_ENV,
   revision: process.env.NEXT_PUBLIC_HONEYBADGER_REVISION,
   projectRoot: 'webpack://_N_E/./',
   // debug: true,
   // reportData: true,
-})
+}
+
+Honeybadger.configure(config)
 Honeybadger.logger.debug('Honeybadger configured for browser')

package/templates/honeybadger.edge.config.js

@@ -1,11 +1,13 @@
 import Honeybadger from '@honeybadger-io/js'
 
-Honeybadger.configure({
+export const config = {
   apiKey: process.env.NEXT_PUBLIC_HONEYBADGER_API_KEY,
   environment: process.env.NEXT_PUBLIC_VERCEL_ENV || process.env.VERCEL_ENV || process.env.NODE_ENV,
   revision: process.env.NEXT_PUBLIC_HONEYBADGER_REVISION,
   projectRoot: 'webpack://_N_E/./',
   // debug: true,
   // reportData: true,
-})
+}
+
+Honeybadger.configure(config)
 Honeybadger.logger.debug('Honeybadger configured for edge')

package/templates/honeybadger.server.config.js

@@ -1,15 +1,18 @@
 import Honeybadger from '@honeybadger-io/js'
 
 const projectRoot = process.cwd()
+
+export const config = {
+  apiKey: process.env.NEXT_PUBLIC_HONEYBADGER_API_KEY,
+  environment: process.env.NEXT_PUBLIC_VERCEL_ENV || process.env.VERCEL_ENV || process.env.NODE_ENV,
+  revision: process.env.NEXT_PUBLIC_HONEYBADGER_REVISION,
+  projectRoot: 'webpack:///./',
+  // debug: true,
+  // reportData: true,
+}
+
 Honeybadger
-  .configure({
-    apiKey: process.env.NEXT_PUBLIC_HONEYBADGER_API_KEY,
-    environment: process.env.NEXT_PUBLIC_VERCEL_ENV || process.env.VERCEL_ENV || process.env.NODE_ENV,
-    revision: process.env.NEXT_PUBLIC_HONEYBADGER_REVISION,
-    projectRoot: 'webpack:///./',
-    // debug: true,
-    // reportData: true,
-  })
+  .configure(config)
   .beforeNotify((notice) => {
     if (!notice) {
       return