@vigilon/nextjs 0.0.0-stage → 0.2.15

package/dist/server.d.ts

@@ -0,0 +1,116 @@
+import { VigilonRegisterParams, register as register$1 } from '@vigilon/node';
+export * from '@vigilon/node';
+import { Context } from '@opentelemetry/api';
+import { SpanProcessor, Span, ReadableSpan } from '@opentelemetry/sdk-trace-node';
+
+type VigilonNextjsRegisterParams = Omit<VigilonRegisterParams, "extendSpanProcessors">;
+/**
+ * Starts Vigilon in the Next.js Node.js runtime: @vigilon/node's register()
+ * plus route attribution from Next's own spans and, on Vercel, the
+ * end-of-request flush and real response status. Call it from
+ * instrumentation.ts. Every parameter is optional, as with @vigilon/node.
+ */
+declare function register(params?: VigilonNextjsRegisterParams): ReturnType<typeof register$1>;
+
+declare const NEXT_ROUTE_ATTRIBUTE = "next.route";
+declare const HTTP_ROUTE_ATTRIBUTE = "http.route";
+/**
+ * Propagates the route Next.js resolves to the two places the rest of the
+ * pipeline reads it from, neither of which Next.js reliably fills itself:
+ *
+ * 1. The incoming request's RPC metadata — where the HTTP instrumentation
+ *    reads `http.route` when labelling its server span. Express and Fastify
+ *    instrumentations write the matched route there; Next.js never does.
+ *
+ * 2. Next's own `BaseServer.handleRequest` entry span. Next normally copies
+ *    `next.route` onto it via a tracer-internal root-span-attribute store,
+ *    but bundled runtimes (Vercel's serverless build) load private copies of
+ *    Next's tracer per route chunk, so the route module writes to one store
+ *    while the base server reads another and the entry span exports without
+ *    a route. Endpoint metrics are collector-derived from entry spans, so
+ *    every Vercel request was bucketed as "unknown".
+ *
+ * A span processor is used instead of patching Next's internals because the
+ * global tracer provider is the one channel every bundled copy of Next's
+ * tracer shares — proven by child spans parenting correctly even where the
+ * attribute store is split.
+ */
+declare class NextRouteSpanProcessor implements SpanProcessor {
+    onStart(span: Span, parentContext: Context): void;
+    onEnd(): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+type Flushable = {
+    forceFlush(): Promise<void>;
+};
+/**
+ * Exports telemetry at the end of every request instead of trusting timers.
+ *
+ * Vercel suspends the function instance the moment a response is sent, so the
+ * BatchSpanProcessor's export timer rarely gets to run, and even an export
+ * started at span end freezes mid-POST: it only completes if another request
+ * thaws the instance before the connection dies.
+ * Observed in production as "N consecutive requests record N-1", "spaced-out
+ * requests record nothing", and stale spans surfacing alongside later
+ * traffic.
+ *
+ * The keep-alive is therefore registered with Vercel's waitUntil when the
+ * entry span STARTS — registrations made after the response settles are
+ * silently dropped, and the entry span only ends after that point. The
+ * deferred handed to waitUntil at start is resolved once the end-of-request
+ * flush completes, so the instance stays alive exactly long enough for the
+ * export POST to land.
+ *
+ * Must be registered AFTER the BatchSpanProcessor: processors run in order,
+ * and the entry span must already be enqueued when the flush starts.
+ */
+declare class VercelFlushSpanProcessor implements SpanProcessor {
+    private readonly flushables;
+    private readonly keepAlives;
+    constructor(flushables: Flushable[]);
+    onStart(span: Span, _parentContext: Context): void;
+    onEnd(span: ReadableSpan): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+declare const HTTP_RESPONSE_STATUS_CODE_ATTRIBUTE = "http.response.status_code";
+/**
+ * Records the real HTTP response status onto the service-entry span on Vercel.
+ *
+ * Vercel's bundled Next.js runtime stamps the entry span's status from the
+ * response object before the handler's response is written, so the span always
+ * reports the default 200 — a 429 or 500 to the client still exports as 200,
+ * and warn/error rates flatline. The truth passes through
+ * `ServerResponse.prototype.writeHead` when the response is actually written,
+ * so this processor tracks live entry spans by trace id and a prototype patch
+ * (see `patchServerResponseStatus`) reports the written status back to the
+ * entry span of whichever trace is active.
+ *
+ * The stable `http.response.status_code` key is set deliberately: the bundled
+ * runtime writes only the old `http.status_code` key, and the collector only
+ * normalizes old → stable when the stable key is absent, so the value recorded
+ * here survives regardless of what the runtime writes afterwards.
+ */
+declare class VercelResponseStatusProcessor implements SpanProcessor {
+    private readonly entrySpans;
+    onStart(span: Span, _parentContext: Context): void;
+    onEnd(span: ReadableSpan): void;
+    /** Called from the ServerResponse patch when a response's head is written. */
+    recordStatus(statusCode: number): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/**
+ * Patches `ServerResponse.prototype.writeHead` to report the written status to
+ * the processor. Prototype patching works regardless of when the server was
+ * created, which is what makes this viable on Vercel where the runtime's
+ * server exists before the SDK starts (the reason HttpInstrumentation never
+ * engages there). Node's implicit header write on `res.end()` also goes
+ * through `writeHead`, so unwritten-head responses are covered too.
+ */
+declare function patchServerResponseStatus(processor: VercelResponseStatusProcessor): void;
+
+export { type Flushable, HTTP_RESPONSE_STATUS_CODE_ATTRIBUTE, HTTP_ROUTE_ATTRIBUTE, NEXT_ROUTE_ATTRIBUTE, NextRouteSpanProcessor, VercelFlushSpanProcessor, VercelResponseStatusProcessor, type VigilonNextjsRegisterParams, patchServerResponseStatus, register };

package/dist/server.mjs

@@ -0,0 +1,180 @@
+// src/server/index.ts
+export * from "@vigilon/node";
+
+// src/server/register.ts
+import { register as registerNode } from "@vigilon/node";
+
+// src/server/nextRouteSpanProcessor.ts
+import { trace } from "@opentelemetry/api";
+import { getRPCMetadata, RPCType } from "@opentelemetry/core";
+var NEXT_ROUTE_ATTRIBUTE = "next.route";
+var HTTP_ROUTE_ATTRIBUTE = "http.route";
+var NEXT_SPAN_TYPE_ATTRIBUTE = "next.span_type";
+var NEXT_ENTRY_SPAN_TYPE = "BaseServer.handleRequest";
+var NextRouteSpanProcessor = class {
+  onStart(span, parentContext) {
+    const route = span.attributes[NEXT_ROUTE_ATTRIBUTE];
+    if (typeof route !== "string" || route.length === 0) return;
+    const rpcMetadata = getRPCMetadata(parentContext);
+    if (rpcMetadata?.type === RPCType.HTTP) {
+      rpcMetadata.route = route;
+    }
+    const parentSpan = trace.getSpan(parentContext);
+    if (!parentSpan?.isRecording()) return;
+    const parentAttributes = parentSpan.attributes;
+    if (parentAttributes?.[NEXT_SPAN_TYPE_ATTRIBUTE] === NEXT_ENTRY_SPAN_TYPE && parentAttributes[HTTP_ROUTE_ATTRIBUTE] === void 0) {
+      parentSpan.setAttribute(HTTP_ROUTE_ATTRIBUTE, route);
+      parentSpan.setAttribute(NEXT_ROUTE_ATTRIBUTE, route);
+    }
+  }
+  onEnd() {
+  }
+  forceFlush() {
+    return Promise.resolve();
+  }
+  shutdown() {
+    return Promise.resolve();
+  }
+};
+
+// src/server/entrySpan.ts
+import { SpanKind } from "@opentelemetry/api";
+function isEntrySpan(span) {
+  if (span.kind !== SpanKind.SERVER) return false;
+  const parent = span.parentSpanContext;
+  return !parent || parent.isRemote === true;
+}
+
+// src/server/vercelFlushSpanProcessor.ts
+var VERCEL_REQUEST_CONTEXT = /* @__PURE__ */ Symbol.for("@vercel/request-context");
+var KEEP_ALIVE_TIMEOUT_MS = 15e3;
+function vercelWaitUntil(promise) {
+  const requestContext = globalThis[VERCEL_REQUEST_CONTEXT];
+  requestContext?.get?.()?.waitUntil?.(promise);
+}
+var VercelFlushSpanProcessor = class {
+  constructor(flushables) {
+    this.flushables = flushables;
+    this.keepAlives = /* @__PURE__ */ new Map();
+  }
+  onStart(span, _parentContext) {
+    if (!isEntrySpan(span)) return;
+    let resolveKeepAlive;
+    const keepAlive = new Promise((resolve) => {
+      resolveKeepAlive = resolve;
+    });
+    vercelWaitUntil(keepAlive);
+    const backstop = setTimeout(resolveKeepAlive, KEEP_ALIVE_TIMEOUT_MS);
+    backstop.unref?.();
+    this.keepAlives.set(span.spanContext().spanId, () => {
+      clearTimeout(backstop);
+      resolveKeepAlive();
+    });
+  }
+  onEnd(span) {
+    if (!isEntrySpan(span)) return;
+    const spanId = span.spanContext().spanId;
+    const release = this.keepAlives.get(spanId);
+    this.keepAlives.delete(spanId);
+    const exportDone = Promise.allSettled(
+      this.flushables.map((flushable) => flushable.forceFlush())
+    ).then(() => void 0);
+    if (release) void exportDone.finally(release);
+  }
+  forceFlush() {
+    return Promise.resolve();
+  }
+  shutdown() {
+    for (const release of this.keepAlives.values()) release();
+    this.keepAlives.clear();
+    return Promise.resolve();
+  }
+};
+
+// src/server/vercelResponseStatusProcessor.ts
+import * as http from "http";
+import { trace as trace2 } from "@opentelemetry/api";
+var HTTP_RESPONSE_STATUS_CODE_ATTRIBUTE = "http.response.status_code";
+var VercelResponseStatusProcessor = class {
+  constructor() {
+    this.entrySpans = /* @__PURE__ */ new Map();
+  }
+  onStart(span, _parentContext) {
+    if (!isEntrySpan(span)) return;
+    this.entrySpans.set(span.spanContext().traceId, span);
+  }
+  onEnd(span) {
+    if (!isEntrySpan(span)) return;
+    this.entrySpans.delete(span.spanContext().traceId);
+  }
+  /** Called from the ServerResponse patch when a response's head is written. */
+  recordStatus(statusCode) {
+    const traceId = trace2.getActiveSpan()?.spanContext().traceId;
+    if (!traceId) return;
+    const entrySpan = this.entrySpans.get(traceId);
+    if (entrySpan?.isRecording()) {
+      entrySpan.setAttribute(HTTP_RESPONSE_STATUS_CODE_ATTRIBUTE, statusCode);
+    }
+  }
+  forceFlush() {
+    return Promise.resolve();
+  }
+  shutdown() {
+    this.entrySpans.clear();
+    return Promise.resolve();
+  }
+};
+var PATCHED_FLAG = /* @__PURE__ */ Symbol.for("vigilon.writeHead.patched");
+function patchServerResponseStatus(processor) {
+  const prototype = http.ServerResponse.prototype;
+  if (prototype[PATCHED_FLAG]) return;
+  prototype[PATCHED_FLAG] = true;
+  const originalWriteHead = prototype.writeHead;
+  prototype.writeHead = function patchedWriteHead(...args) {
+    const statusCode = typeof args[0] === "number" ? args[0] : this.statusCode;
+    try {
+      processor.recordStatus(statusCode);
+    } catch {
+    }
+    return originalWriteHead.apply(this, args);
+  };
+}
+
+// src/server/register.ts
+var NODE_REGISTER_STATE_KEY = /* @__PURE__ */ Symbol.for("vigilon.register.started");
+var NEXTJS_REGISTER_STATE_KEY = /* @__PURE__ */ Symbol.for("vigilon.register.nextjs");
+function register(params = {}) {
+  const globalState = globalThis;
+  if (globalState[NODE_REGISTER_STATE_KEY] && !globalState[NEXTJS_REGISTER_STATE_KEY]) {
+    console.warn(
+      "Vigilon is already registered by plain @vigilon/node (most likely a NODE_OPTIONS preload of @vigilon/node/register), so the Next.js extensions (route attribution and the Vercel runtime fixes) are not active. Preload @vigilon/nextjs/register instead, or remove the preload and register from instrumentation.ts."
+    );
+    return void 0;
+  }
+  const sdk = registerNode({
+    ...params,
+    extendSpanProcessors: ({ batchSpanProcessor }) => {
+      const append = [];
+      if (process.env.VERCEL) {
+        append.push(new VercelFlushSpanProcessor([batchSpanProcessor]));
+        const responseStatusProcessor = new VercelResponseStatusProcessor();
+        append.push(responseStatusProcessor);
+        patchServerResponseStatus(responseStatusProcessor);
+      }
+      return { prepend: [new NextRouteSpanProcessor()], append };
+    }
+  });
+  globalState[NEXTJS_REGISTER_STATE_KEY] = true;
+  return sdk;
+}
+export {
+  HTTP_RESPONSE_STATUS_CODE_ATTRIBUTE,
+  HTTP_ROUTE_ATTRIBUTE,
+  NEXT_ROUTE_ATTRIBUTE,
+  NextRouteSpanProcessor,
+  VercelFlushSpanProcessor,
+  VercelResponseStatusProcessor,
+  patchServerResponseStatus,
+  register
+};
+//# sourceMappingURL=server.mjs.map

package/dist/server.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server/index.ts","../src/server/register.ts","../src/server/nextRouteSpanProcessor.ts","../src/server/entrySpan.ts","../src/server/vercelFlushSpanProcessor.ts","../src/server/vercelResponseStatusProcessor.ts"],"sourcesContent":["/**\n * @vigilon/nextjs/server: the Node.js runtime half of @vigilon/nextjs, for\n * instrumentation.ts. Re-exports @vigilon/node (recordException,\n * withJobMonitor, and the rest), with a Next.js-aware register().\n */\nexport * from \"@vigilon/node\";\nexport { register, type VigilonNextjsRegisterParams } from \"./register\";\nexport {\n  HTTP_ROUTE_ATTRIBUTE,\n  NEXT_ROUTE_ATTRIBUTE,\n  NextRouteSpanProcessor,\n} from \"./nextRouteSpanProcessor\";\nexport { type Flushable, VercelFlushSpanProcessor } from \"./vercelFlushSpanProcessor\";\nexport {\n  HTTP_RESPONSE_STATUS_CODE_ATTRIBUTE,\n  patchServerResponseStatus,\n  VercelResponseStatusProcessor,\n} from \"./vercelResponseStatusProcessor\";\n","import type { SpanProcessor } from \"@opentelemetry/sdk-trace-node\";\nimport { register as registerNode, type VigilonRegisterParams } from \"@vigilon/node\";\nimport { NextRouteSpanProcessor } from \"./nextRouteSpanProcessor\";\nimport { VercelFlushSpanProcessor } from \"./vercelFlushSpanProcessor\";\nimport {\n  patchServerResponseStatus,\n  VercelResponseStatusProcessor,\n} from \"./vercelResponseStatusProcessor\";\n\nexport type VigilonNextjsRegisterParams = Omit<VigilonRegisterParams, \"extendSpanProcessors\">;\n\n// Shared with @vigilon/node: set once any register() variant has started an\n// SDK in this process.\nconst NODE_REGISTER_STATE_KEY = Symbol.for(\"vigilon.register.started\");\n// Set only by this register(), so a plain @vigilon/node start followed by\n// this call is told apart from a harmless second call of this one.\nconst NEXTJS_REGISTER_STATE_KEY = Symbol.for(\"vigilon.register.nextjs\");\n\n/**\n * Starts Vigilon in the Next.js Node.js runtime: @vigilon/node's register()\n * plus route attribution from Next's own spans and, on Vercel, the\n * end-of-request flush and real response status. Call it from\n * instrumentation.ts. Every parameter is optional, as with @vigilon/node.\n */\nexport function register(\n  params: VigilonNextjsRegisterParams = {},\n): ReturnType<typeof registerNode> {\n  const globalState = globalThis as Record<symbol, unknown>;\n  if (globalState[NODE_REGISTER_STATE_KEY] && !globalState[NEXTJS_REGISTER_STATE_KEY]) {\n    console.warn(\n      \"Vigilon is already registered by plain @vigilon/node (most likely a NODE_OPTIONS preload of @vigilon/node/register), so the Next.js extensions (route attribution and the Vercel runtime fixes) are not active. Preload @vigilon/nextjs/register instead, or remove the preload and register from instrumentation.ts.\",\n    );\n    return undefined;\n  }\n  const sdk = registerNode({\n    ...params,\n    extendSpanProcessors: ({ batchSpanProcessor }) => {\n      const append: SpanProcessor[] = [];\n      // Vercel suspends the instance as soon as the response is sent, which\n      // stops the batch and export timers, so telemetry would leave late or\n      // not at all. Flush when each entry span ends instead. Must come after\n      // the batch processor so the ending span is already enqueued.\n      if (process.env.VERCEL) {\n        append.push(new VercelFlushSpanProcessor([batchSpanProcessor]));\n        // Vercel's bundled Next.js runtime stamps the entry span's status\n        // before the response is written (always 200), so the real status is\n        // recorded from ServerResponse.writeHead instead.\n        const responseStatusProcessor = new VercelResponseStatusProcessor();\n        append.push(responseStatusProcessor);\n        patchServerResponseStatus(responseStatusProcessor);\n      }\n      return { prepend: [new NextRouteSpanProcessor()], append };\n    },\n  });\n  globalState[NEXTJS_REGISTER_STATE_KEY] = true;\n  return sdk;\n}\n","import { Context, trace } from \"@opentelemetry/api\";\nimport { getRPCMetadata, RPCType } from \"@opentelemetry/core\";\nimport {\n  SpanProcessor,\n  Span,\n  ReadableSpan,\n} from \"@opentelemetry/sdk-trace-node\";\n\nexport const NEXT_ROUTE_ATTRIBUTE = \"next.route\";\nexport const HTTP_ROUTE_ATTRIBUTE = \"http.route\";\n\nconst NEXT_SPAN_TYPE_ATTRIBUTE = \"next.span_type\";\nconst NEXT_ENTRY_SPAN_TYPE = \"BaseServer.handleRequest\";\n\n/**\n * Propagates the route Next.js resolves to the two places the rest of the\n * pipeline reads it from, neither of which Next.js reliably fills itself:\n *\n * 1. The incoming request's RPC metadata — where the HTTP instrumentation\n *    reads `http.route` when labelling its server span. Express and Fastify\n *    instrumentations write the matched route there; Next.js never does.\n *\n * 2. Next's own `BaseServer.handleRequest` entry span. Next normally copies\n *    `next.route` onto it via a tracer-internal root-span-attribute store,\n *    but bundled runtimes (Vercel's serverless build) load private copies of\n *    Next's tracer per route chunk, so the route module writes to one store\n *    while the base server reads another and the entry span exports without\n *    a route. Endpoint metrics are collector-derived from entry spans, so\n *    every Vercel request was bucketed as \"unknown\".\n *\n * A span processor is used instead of patching Next's internals because the\n * global tracer provider is the one channel every bundled copy of Next's\n * tracer shares — proven by child spans parenting correctly even where the\n * attribute store is split.\n */\nexport class NextRouteSpanProcessor implements SpanProcessor {\n  onStart(span: Span, parentContext: Context): void {\n    const route = span.attributes[NEXT_ROUTE_ATTRIBUTE];\n    if (typeof route !== \"string\" || route.length === 0) return;\n\n    const rpcMetadata = getRPCMetadata(parentContext);\n    if (rpcMetadata?.type === RPCType.HTTP) {\n      rpcMetadata.route = route;\n    }\n\n    const parentSpan = trace.getSpan(parentContext);\n    if (!parentSpan?.isRecording()) return;\n    // Only SDK spans expose attributes; a NonRecordingSpan (remote or no-op\n    // parent) has none and is skipped by the checks below.\n    const parentAttributes = (parentSpan as unknown as ReadableSpan).attributes;\n    if (\n      parentAttributes?.[NEXT_SPAN_TYPE_ATTRIBUTE] === NEXT_ENTRY_SPAN_TYPE &&\n      parentAttributes[HTTP_ROUTE_ATTRIBUTE] === undefined\n    ) {\n      parentSpan.setAttribute(HTTP_ROUTE_ATTRIBUTE, route);\n      parentSpan.setAttribute(NEXT_ROUTE_ATTRIBUTE, route);\n    }\n  }\n\n  onEnd(): void {}\n\n  forceFlush(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  shutdown(): Promise<void> {\n    return Promise.resolve();\n  }\n}\n","import { SpanKind } from \"@opentelemetry/api\";\nimport { ReadableSpan, Span } from \"@opentelemetry/sdk-trace-node\";\n\n/**\n * A service-entry span: the one SERVER span that marks a request entering\n * this service — its parent is either absent or remote. Matches the\n * definition the collector counts for endpoint metrics.\n */\nexport function isEntrySpan(span: Span | ReadableSpan): boolean {\n  if (span.kind !== SpanKind.SERVER) return false;\n  const parent = (span as ReadableSpan).parentSpanContext;\n  return !parent || parent.isRemote === true;\n}\n","import { Context } from \"@opentelemetry/api\";\nimport { SpanProcessor, Span, ReadableSpan } from \"@opentelemetry/sdk-trace-node\";\nimport { isEntrySpan } from \"./entrySpan\";\n\nexport type Flushable = { forceFlush(): Promise<void> };\n\n// The request-context global that @vercel/functions uses to reach waitUntil.\n// Reading it directly keeps the SDK dependency-free; it is simply absent\n// outside Vercel's runtime.\nconst VERCEL_REQUEST_CONTEXT = Symbol.for(\"@vercel/request-context\");\n\n// Backstop so a request that never ends its entry span (crash, client\n// disconnect edge cases) cannot pin the instance — and its billing — open\n// indefinitely via the keep-alive registered at span start.\nconst KEEP_ALIVE_TIMEOUT_MS = 15_000;\n\nfunction vercelWaitUntil(promise: Promise<unknown>): void {\n  const requestContext = (\n    globalThis as Record<symbol, unknown> as {\n      [VERCEL_REQUEST_CONTEXT]?: {\n        get?: () => { waitUntil?: (p: Promise<unknown>) => void } | undefined;\n      };\n    }\n  )[VERCEL_REQUEST_CONTEXT];\n  requestContext?.get?.()?.waitUntil?.(promise);\n}\n\n/**\n * Exports telemetry at the end of every request instead of trusting timers.\n *\n * Vercel suspends the function instance the moment a response is sent, so the\n * BatchSpanProcessor's export timer rarely gets to run, and even an export\n * started at span end freezes mid-POST: it only completes if another request\n * thaws the instance before the connection dies.\n * Observed in production as \"N consecutive requests record N-1\", \"spaced-out\n * requests record nothing\", and stale spans surfacing alongside later\n * traffic.\n *\n * The keep-alive is therefore registered with Vercel's waitUntil when the\n * entry span STARTS — registrations made after the response settles are\n * silently dropped, and the entry span only ends after that point. The\n * deferred handed to waitUntil at start is resolved once the end-of-request\n * flush completes, so the instance stays alive exactly long enough for the\n * export POST to land.\n *\n * Must be registered AFTER the BatchSpanProcessor: processors run in order,\n * and the entry span must already be enqueued when the flush starts.\n */\nexport class VercelFlushSpanProcessor implements SpanProcessor {\n  private readonly keepAlives = new Map<string, () => void>();\n\n  constructor(private readonly flushables: Flushable[]) {}\n\n  onStart(span: Span, _parentContext: Context): void {\n    if (!isEntrySpan(span)) return;\n\n    let resolveKeepAlive!: () => void;\n    const keepAlive = new Promise<void>((resolve) => {\n      resolveKeepAlive = resolve;\n    });\n    vercelWaitUntil(keepAlive);\n\n    const backstop = setTimeout(resolveKeepAlive, KEEP_ALIVE_TIMEOUT_MS);\n    backstop.unref?.();\n    this.keepAlives.set(span.spanContext().spanId, () => {\n      clearTimeout(backstop);\n      resolveKeepAlive();\n    });\n  }\n\n  onEnd(span: ReadableSpan): void {\n    if (!isEntrySpan(span)) return;\n\n    const spanId = span.spanContext().spanId;\n    const release = this.keepAlives.get(spanId);\n    this.keepAlives.delete(spanId);\n\n    const exportDone = Promise.allSettled(\n      this.flushables.map((flushable) => flushable.forceFlush()),\n    ).then(() => undefined);\n    if (release) void exportDone.finally(release);\n  }\n\n  forceFlush(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  shutdown(): Promise<void> {\n    for (const release of this.keepAlives.values()) release();\n    this.keepAlives.clear();\n    return Promise.resolve();\n  }\n}\n","import * as http from \"node:http\";\nimport { Context, trace } from \"@opentelemetry/api\";\nimport {\n  SpanProcessor,\n  Span,\n  ReadableSpan,\n} from \"@opentelemetry/sdk-trace-node\";\nimport { isEntrySpan } from \"./entrySpan\";\n\nexport const HTTP_RESPONSE_STATUS_CODE_ATTRIBUTE = \"http.response.status_code\";\n\n/**\n * Records the real HTTP response status onto the service-entry span on Vercel.\n *\n * Vercel's bundled Next.js runtime stamps the entry span's status from the\n * response object before the handler's response is written, so the span always\n * reports the default 200 — a 429 or 500 to the client still exports as 200,\n * and warn/error rates flatline. The truth passes through\n * `ServerResponse.prototype.writeHead` when the response is actually written,\n * so this processor tracks live entry spans by trace id and a prototype patch\n * (see `patchServerResponseStatus`) reports the written status back to the\n * entry span of whichever trace is active.\n *\n * The stable `http.response.status_code` key is set deliberately: the bundled\n * runtime writes only the old `http.status_code` key, and the collector only\n * normalizes old → stable when the stable key is absent, so the value recorded\n * here survives regardless of what the runtime writes afterwards.\n */\nexport class VercelResponseStatusProcessor implements SpanProcessor {\n  private readonly entrySpans = new Map<string, Span>();\n\n  onStart(span: Span, _parentContext: Context): void {\n    if (!isEntrySpan(span)) return;\n    this.entrySpans.set(span.spanContext().traceId, span);\n  }\n\n  onEnd(span: ReadableSpan): void {\n    if (!isEntrySpan(span)) return;\n    this.entrySpans.delete(span.spanContext().traceId);\n  }\n\n  /** Called from the ServerResponse patch when a response's head is written. */\n  recordStatus(statusCode: number): void {\n    const traceId = trace.getActiveSpan()?.spanContext().traceId;\n    if (!traceId) return;\n    const entrySpan = this.entrySpans.get(traceId);\n    if (entrySpan?.isRecording()) {\n      entrySpan.setAttribute(HTTP_RESPONSE_STATUS_CODE_ATTRIBUTE, statusCode);\n    }\n  }\n\n  forceFlush(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  shutdown(): Promise<void> {\n    this.entrySpans.clear();\n    return Promise.resolve();\n  }\n}\n\nconst PATCHED_FLAG = Symbol.for(\"vigilon.writeHead.patched\");\n\n/**\n * Patches `ServerResponse.prototype.writeHead` to report the written status to\n * the processor. Prototype patching works regardless of when the server was\n * created, which is what makes this viable on Vercel where the runtime's\n * server exists before the SDK starts (the reason HttpInstrumentation never\n * engages there). Node's implicit header write on `res.end()` also goes\n * through `writeHead`, so unwritten-head responses are covered too.\n */\nexport function patchServerResponseStatus(\n  processor: VercelResponseStatusProcessor,\n): void {\n  const prototype = http.ServerResponse.prototype as typeof http.ServerResponse.prototype & {\n    [PATCHED_FLAG]?: boolean;\n  };\n  if (prototype[PATCHED_FLAG]) return;\n  prototype[PATCHED_FLAG] = true;\n\n  const originalWriteHead = prototype.writeHead;\n  prototype.writeHead = function patchedWriteHead(\n    this: http.ServerResponse,\n    ...args: Parameters<typeof originalWriteHead>\n  ) {\n    const statusCode = typeof args[0] === \"number\" ? args[0] : this.statusCode;\n    try {\n      processor.recordStatus(statusCode);\n    } catch {\n      // Never let telemetry break the response path.\n    }\n    return originalWriteHead.apply(this, args);\n  } as typeof originalWriteHead;\n}\n"],"mappings":"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","names":["trace","trace"]}

package/package.json

@@ -1,6 +1,104 @@
 {
   "name": "@vigilon/nextjs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.15",
+  "description": "Vigilon monitoring for Next.js applications: server traces and browser errors",
+  "license": "ISC",
+  "author": "Vigilon",
+  "homepage": "https://vigilon.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vigilonio/js.git",
+    "directory": "packages/nextjs"
+  },
+  "keywords": [
+    "vigilon",
+    "nextjs",
+    "error-monitoring",
+    "opentelemetry",
+    "observability"
+  ],
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./server": {
+      "import": {
+        "types": "./dist/server.d.mts",
+        "default": "./dist/server.mjs"
+      },
+      "require": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.cjs"
+      }
+    },
+    "./config": {
+      "import": {
+        "types": "./dist/config.d.mts",
+        "default": "./dist/config.mjs"
+      },
+      "require": {
+        "types": "./dist/config.d.ts",
+        "default": "./dist/config.cjs"
+      }
+    },
+    "./register": {
+      "import": "./register.mjs",
+      "require": "./register.cjs",
+      "default": "./register.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "register.mjs",
+    "register.cjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/core": "^2.11.0",
+    "@opentelemetry/sdk-trace-node": "^2.11.0",
+    "@vigilon/cli": "0.2.15",
+    "@vigilon/node": "0.2.15",
+    "@vigilon/react": "0.2.15"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.19.2",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "happy-dom": "^20.0.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "tsup": "^8.5.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "rm -rf dist && tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/register.cjs

@@ -0,0 +1,5 @@
+// CommonJS preload entrypoint for self-hosted Next.js:
+// `NODE_OPTIONS='--require @vigilon/nextjs/register' next start`.
+// register() is idempotent, so this preload plus a register() call from
+// instrumentation.ts cannot start two SDKs.
+require("./dist/server.cjs").register();

package/register.mjs

@@ -0,0 +1,12 @@
+// Preload entrypoint for self-hosted Next.js:
+// `NODE_OPTIONS='--import @vigilon/nextjs/register' next start`.
+import { register as registerLoaderHook } from "node:module";
+
+// Lets OpenTelemetry's instrumentations intercept ESM imports as well as
+// require(), as @vigilon/node/register does.
+registerLoaderHook("@opentelemetry/instrumentation/hook.mjs", import.meta.url);
+
+// register() is idempotent, so this preload plus a register() call from
+// instrumentation.ts cannot start two SDKs.
+const { register } = await import("./dist/server.mjs");
+register();