@spotlightjs/spotlight 4.5.1 → 4.7.0

package/dist/server/routes/stream/debugLogging.js

@@ -0,0 +1,68 @@
+;
+!function() {
+  try {
+    var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {}, n = new e.Error().stack;
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "faef59ab-afce-40e0-b027-ea31b42dfa6e", e._sentryDebugIdIdentifier = "sentry-dbid-faef59ab-afce-40e0-b027-ea31b42dfa6e");
+  } catch (e2) {
+  }
+}();
+import { isDebugEnabled, logger } from "../../logger.js";
+import { isErrorEvent } from "../../parser/helpers.js";
+import "uuidv7";
+import "../../../_virtual/_sentry-release-injection-file.js";
+function logIncomingEvent(container) {
+  if (!isDebugEnabled()) return;
+  const contentType = container.getContentType();
+  if (contentType === "application/x-sentry-envelope") {
+    const parsedEnvelope = container.getParsedEnvelope();
+    if (!parsedEnvelope) {
+      const data = container.getData();
+      const size = data.length;
+      const firstNewline = data.indexOf("\n");
+      const headerPreview = firstNewline > 0 && firstNewline < 200 ? data.toString("utf-8", 0, firstNewline).replace(/\n/g, "\\n") : "header not found";
+      logger.debug(`→ envelope (parse error, ${size} bytes) | ${headerPreview}`);
+      return;
+    }
+    let logMessage = `→ ${formatEnvelopeMetadata(parsedEnvelope.envelope)}`;
+    for (const item of parsedEnvelope.envelope[1]) {
+      if (isErrorEvent(item[1])) {
+        logMessage += `
+  └ ${formatErrorDetails(item[1])}`;
+      }
+    }
+    logger.debug(logMessage);
+  } else {
+    logger.debug(`→ ${contentType || "unknown"}`);
+  }
+}
+function logOutgoingEvent(container, clientId) {
+  if (!isDebugEnabled()) return;
+  const typeInfo = container.getEventTypesString();
+  if (typeInfo === "envelope" && container.getContentType() === "application/x-sentry-envelope") {
+    const size = container.getData().length;
+    logger.debug(`← envelope (${size} bytes) to ${clientId}`);
+  } else {
+    logger.debug(`← ${typeInfo} to ${clientId}`);
+  }
+}
+function formatEnvelopeMetadata(envelope) {
+  const eventTypes = envelope[1].map((item) => item[0].type).filter(Boolean);
+  const typePrefix = eventTypes.length > 0 ? eventTypes.join("+") : "envelope";
+  const sdk = envelope[0].sdk?.name || "unknown";
+  const eventId = envelope[0].event_id;
+  return `${typePrefix} | sdk: ${sdk}${eventId ? ` | id: ${eventId}` : ""}`;
+}
+function formatErrorDetails(payload) {
+  const platform = payload.platform || "unknown";
+  const environment = payload.environment || "unknown";
+  const level = "level" in payload ? payload.level : "error";
+  const errorMsg = payload.exception?.values?.[0]?.value || String(payload.message) || "No error message";
+  const errorType = payload.exception?.values?.[0]?.type || "Error";
+  const truncatedMsg = errorMsg.substring(0, 80) + (errorMsg.length > 80 ? "..." : "");
+  return `${level} [${platform}/${environment}] ${errorType}: ${truncatedMsg}`;
+}
+export {
+  logIncomingEvent,
+  logOutgoingEvent
+};
+//# sourceMappingURL=debugLogging.js.map

package/dist/server/routes/stream/debugLogging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debugLogging.js","sources":["../../../../src/server/routes/stream/debugLogging.ts"],"sourcesContent":["import { isDebugEnabled, logger } from \"../../logger.ts\";\nimport { type ParsedEnvelope, type SentryErrorEvent, type SentryEvent, isErrorEvent } from \"../../parser/index.ts\";\nimport type { EventContainer } from \"../../utils/index.ts\";\n\n/**\n * Logs incoming event details when debug mode is enabled\n * Uses the container's parsed data if available\n */\nexport function logIncomingEvent(container: EventContainer): void {\n  if (!isDebugEnabled()) return;\n\n  const contentType = container.getContentType();\n\n  if (contentType === \"application/x-sentry-envelope\") {\n    const parsedEnvelope = container.getParsedEnvelope();\n\n    if (!parsedEnvelope) {\n      // Still log something useful even if parsing failed\n      const data = container.getData();\n      const size = data.length;\n      // Only show first line of envelope header for safety (should be JSON metadata, not user data)\n      const firstNewline = data.indexOf(\"\\n\");\n      const headerPreview =\n        firstNewline > 0 && firstNewline < 200\n          ? data.toString(\"utf-8\", 0, firstNewline).replace(/\\n/g, \"\\\\n\")\n          : \"header not found\";\n      logger.debug(`→ envelope (parse error, ${size} bytes) | ${headerPreview}`);\n      return;\n    }\n\n    // Build complete log message with all details\n    let logMessage = `→ ${formatEnvelopeMetadata(parsedEnvelope.envelope)}`;\n\n    // Add error event details to the same log message\n    for (const item of parsedEnvelope.envelope[1]) {\n      if (isErrorEvent(item[1] as SentryEvent)) {\n        logMessage += `\\n  └ ${formatErrorDetails(item[1] as SentryErrorEvent)}`;\n      }\n    }\n\n    // Single atomic log statement\n    logger.debug(logMessage);\n  } else {\n    logger.debug(`→ ${contentType || \"unknown\"}`);\n  }\n}\n\n/**\n * Logs outgoing event to client when debug mode is enabled\n * Uses the container's already-parsed data if available\n */\nexport function logOutgoingEvent(container: EventContainer, clientId: string): void {\n  if (!isDebugEnabled()) return;\n\n  // Use the container's event type string (which uses cached parsed data)\n  const typeInfo = container.getEventTypesString();\n\n  // If it's an envelope that failed to parse, add size info\n  if (typeInfo === \"envelope\" && container.getContentType() === \"application/x-sentry-envelope\") {\n    const size = container.getData().length;\n    logger.debug(`← envelope (${size} bytes) to ${clientId}`);\n  } else {\n    logger.debug(`← ${typeInfo} to ${clientId}`);\n  }\n}\n\n/**\n * Formats envelope metadata for logging\n */\nfunction formatEnvelopeMetadata(envelope: ParsedEnvelope[\"envelope\"]): string {\n  const eventTypes = envelope[1].map(item => item[0].type).filter(Boolean);\n\n  const typePrefix = eventTypes.length > 0 ? eventTypes.join(\"+\") : \"envelope\";\n  const sdk = envelope[0].sdk?.name || \"unknown\";\n  const eventId = envelope[0].event_id;\n\n  return `${typePrefix} | sdk: ${sdk}${eventId ? ` | id: ${eventId}` : \"\"}`;\n}\n\n/**\n * Formats error event details for logging\n */\nfunction formatErrorDetails(payload: SentryErrorEvent): string {\n  const platform = payload.platform || \"unknown\";\n  const environment = payload.environment || \"unknown\";\n  const level = \"level\" in payload ? payload.level : \"error\";\n\n  const errorMsg = payload.exception?.values?.[0]?.value || String(payload.message) || \"No error message\";\n\n  const errorType = payload.exception?.values?.[0]?.type || \"Error\";\n\n  const truncatedMsg = errorMsg.substring(0, 80) + (errorMsg.length > 80 ? \"...\" : \"\");\n\n  return `${level} [${platform}/${environment}] ${errorType}: ${truncatedMsg}`;\n}\n"],"names":[],"mappings":";;;;;;;;;;;;AAQO,SAAS,iBAAiB,WAAiC;AAChE,MAAI,CAAC,iBAAkB;AAEvB,QAAM,cAAc,UAAU,eAAA;AAE9B,MAAI,gBAAgB,iCAAiC;AACnD,UAAM,iBAAiB,UAAU,kBAAA;AAEjC,QAAI,CAAC,gBAAgB;AAEnB,YAAM,OAAO,UAAU,QAAA;AACvB,YAAM,OAAO,KAAK;AAElB,YAAM,eAAe,KAAK,QAAQ,IAAI;AACtC,YAAM,gBACJ,eAAe,KAAK,eAAe,MAC/B,KAAK,SAAS,SAAS,GAAG,YAAY,EAAE,QAAQ,OAAO,KAAK,IAC5D;AACN,aAAO,MAAM,4BAA4B,IAAI,aAAa,aAAa,EAAE;AACzE;AAAA,IACF;AAGA,QAAI,aAAa,KAAK,uBAAuB,eAAe,QAAQ,CAAC;AAGrE,eAAW,QAAQ,eAAe,SAAS,CAAC,GAAG;AAC7C,UAAI,aAAa,KAAK,CAAC,CAAgB,GAAG;AACxC,sBAAc;AAAA,MAAS,mBAAmB,KAAK,CAAC,CAAqB,CAAC;AAAA,MACxE;AAAA,IACF;AAGA,WAAO,MAAM,UAAU;AAAA,EACzB,OAAO;AACL,WAAO,MAAM,KAAK,eAAe,SAAS,EAAE;AAAA,EAC9C;AACF;AAMO,SAAS,iBAAiB,WAA2B,UAAwB;AAClF,MAAI,CAAC,iBAAkB;AAGvB,QAAM,WAAW,UAAU,oBAAA;AAG3B,MAAI,aAAa,cAAc,UAAU,eAAA,MAAqB,iCAAiC;AAC7F,UAAM,OAAO,UAAU,QAAA,EAAU;AACjC,WAAO,MAAM,eAAe,IAAI,cAAc,QAAQ,EAAE;AAAA,EAC1D,OAAO;AACL,WAAO,MAAM,KAAK,QAAQ,OAAO,QAAQ,EAAE;AAAA,EAC7C;AACF;AAKA,SAAS,uBAAuB,UAA8C;AAC5E,QAAM,aAAa,SAAS,CAAC,EAAE,IAAI,CAAA,SAAQ,KAAK,CAAC,EAAE,IAAI,EAAE,OAAO,OAAO;AAEvE,QAAM,aAAa,WAAW,SAAS,IAAI,WAAW,KAAK,GAAG,IAAI;AAClE,QAAM,MAAM,SAAS,CAAC,EAAE,KAAK,QAAQ;AACrC,QAAM,UAAU,SAAS,CAAC,EAAE;AAE5B,SAAO,GAAG,UAAU,WAAW,GAAG,GAAG,UAAU,UAAU,OAAO,KAAK,EAAE;AACzE;AAKA,SAAS,mBAAmB,SAAmC;AAC7D,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,cAAc,QAAQ,eAAe;AAC3C,QAAM,QAAQ,WAAW,UAAU,QAAQ,QAAQ;AAEnD,QAAM,WAAW,QAAQ,WAAW,SAAS,CAAC,GAAG,SAAS,OAAO,QAAQ,OAAO,KAAK;AAErF,QAAM,YAAY,QAAQ,WAAW,SAAS,CAAC,GAAG,QAAQ;AAE1D,QAAM,eAAe,SAAS,UAAU,GAAG,EAAE,KAAK,SAAS,SAAS,KAAK,QAAQ;AAEjF,SAAO,GAAG,KAAK,KAAK,QAAQ,IAAI,WAAW,KAAK,SAAS,KAAK,YAAY;AAC5E;"}

package/dist/server/routes/stream/index.d.ts

@@ -0,0 +1,34 @@
+import { HonoEnv } from '../../types/env.ts';
+declare const router: import('hono/hono-base').HonoBase<HonoEnv, {
+    "/stream": {
+        $get: {
+            input: {};
+            output: {};
+            outputFormat: string;
+            status: import('hono/utils/http-status').StatusCode;
+        };
+    };
+} & {
+    "/envelope/:id": {
+        $get: {
+            input: {
+                param: {
+                    id: string;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: import('hono/utils/http-status').StatusCode;
+        };
+    };
+} & {
+    [x: string]: {
+        [x: `$${Lowercase<string>}`]: {
+            input: {};
+            output: null;
+            outputFormat: "body";
+            status: 200;
+        };
+    };
+}, "/">;
+export default router;

package/dist/server/routes/stream/index.js

@@ -0,0 +1,110 @@
+;
+!function() {
+  try {
+    var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {}, n = new e.Error().stack;
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "30c2a21d-0350-4802-a8cb-86dc2894fef5", e._sentryDebugIdIdentifier = "sentry-dbid-30c2a21d-0350-4802-a8cb-86dc2894fef5");
+  } catch (e2) {
+  }
+}();
+import { createWriteStream } from "node:fs";
+import { decompressBody, pushToSpotlightBuffer } from "../../sdk.js";
+import { SENTRY_CONTENT_TYPE } from "../../../shared/constants.js";
+import { Hono } from "hono";
+import { logger } from "../../logger.js";
+import { getBuffer } from "../../utils/getBuffer.js";
+import "../../parser/helpers.js";
+import "uuidv7";
+import "../../../_virtual/_sentry-release-injection-file.js";
+import "node:http";
+import "@sentry/node";
+import "node:dns/promises";
+import "node:net";
+import "node:os";
+import { logOutgoingEvent, logIncomingEvent } from "./debugLogging.js";
+import { streamSSE } from "./streaming.js";
+import { parseBrowserFromUserAgent } from "./userAgent.js";
+const router = new Hono().get("/stream", (ctx) => {
+  const buffer = getBuffer();
+  const useBase64 = ctx.req.query("base64") != null;
+  const base64Indicator = useBase64 ? ";base64" : "";
+  let clientId = ctx.req.query("client");
+  if (!clientId) {
+    const userAgent = ctx.req.header("User-Agent") || "unknown";
+    clientId = parseBrowserFromUserAgent(userAgent);
+  }
+  clientId = clientId.replace(/[^\w\s.\-/()]/g, "");
+  if (!clientId) clientId = "unknown";
+  return streamSSE(ctx, async (stream) => {
+    const lastEventId = ctx.req.header("Last-Event-ID");
+    const sub = buffer.subscribe((container) => {
+      logOutgoingEvent(container, clientId);
+      const parsedEnvelope = container.getParsedEnvelope();
+      if (parsedEnvelope) {
+        stream.writeSSE({
+          id: parsedEnvelope.envelope[0].__spotlight_envelope_id.toString(),
+          event: `${container.getContentType()}${base64Indicator}`,
+          data: JSON.stringify(parsedEnvelope.envelope)
+        });
+      }
+    }, lastEventId);
+    stream.onAbort(() => {
+      buffer.unsubscribe(sub);
+    });
+  });
+}).get("/envelope/:id", (ctx) => {
+  const buffer = getBuffer();
+  const envelopeId = ctx.req.param("id");
+  const container = buffer.read({ envelopeId });
+  if (container.length === 0) {
+    return ctx.notFound();
+  }
+  return ctx.body(new Uint8Array(container[0].getData()), 200, {
+    "Content-Type": container[0].getContentType(),
+    "Cache-Control": "no-cache",
+    "Content-Disposition": `attachment; filename="${envelopeId}.bin"`,
+    Connection: "keep-alive"
+  });
+}).on("POST", ["/stream", "/api/:id/envelope"], async (ctx) => {
+  let contentType = ctx.req.header("content-type")?.split(";")[0].toLocaleLowerCase();
+  if (ctx.req.query("sentry_client")?.startsWith("sentry.javascript.browser") && ctx.req.header("Origin")) {
+    contentType = SENTRY_CONTENT_TYPE;
+  }
+  const body = decompressBody(Buffer.from(await ctx.req.arrayBuffer()), ctx.req.header("Content-Encoding"));
+  const container = pushToSpotlightBuffer({
+    body,
+    spotlightBuffer: getBuffer(),
+    contentType,
+    userAgent: ctx.req.header("User-Agent")
+  });
+  if (container) {
+    logIncomingEvent(container);
+  } else {
+    logger.warn("No content type, skipping payload...");
+  }
+  const incomingPayload = ctx.get("incomingPayload");
+  if (process.env.SPOTLIGHT_CAPTURE || incomingPayload) {
+    const contentType2 = container?.getContentType();
+    const timestamp = BigInt(Date.now()) * 1000000n + process.hrtime.bigint() % 1000000n;
+    const filename = `${contentType2?.replace(/[^a-z0-9]/gi, "_") || "no_content_type"}-${timestamp}.txt`;
+    if (incomingPayload) {
+      incomingPayload(body.toString("binary"));
+    } else {
+      const stream = createWriteStream(filename);
+      stream.on("error", (err) => {
+        logger.error(`Failed to save data to ${filename}: ${err}`);
+        stream.destroy();
+      });
+      stream.end(body, () => {
+        logger.info(`🗃️ Saved data to ${filename}`);
+      });
+    }
+  }
+  return ctx.body(null, 200, {
+    "Cache-Control": "no-cache",
+    Connection: "keep-alive"
+  });
+});
+export {
+  router as default
+};
+//# sourceMappingURL=index.js.map

package/dist/server/routes/stream/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../../src/server/routes/stream/index.ts"],"sourcesContent":["import { createWriteStream } from \"node:fs\";\nimport { decompressBody, pushToSpotlightBuffer } from \"../../sdk.ts\";\nimport { SENTRY_CONTENT_TYPE } from \"../../../shared/constants.ts\";\nimport { Hono } from \"hono\";\nimport { logger } from \"../../logger.ts\";\nimport type { HonoEnv } from \"../../types/env.ts\";\nimport { getBuffer } from \"../../utils/index.ts\";\nimport { logIncomingEvent, logOutgoingEvent } from \"./debugLogging.ts\";\nimport { streamSSE } from \"./streaming.ts\";\nimport { parseBrowserFromUserAgent } from \"./userAgent.ts\";\n\nconst router = new Hono<HonoEnv>()\n  .get(\"/stream\", ctx => {\n    const buffer = getBuffer();\n\n    const useBase64 = ctx.req.query(\"base64\") != null;\n    const base64Indicator = useBase64 ? \";base64\" : \"\";\n\n    // Capture client information for debug logging\n    let clientId = ctx.req.query(\"client\");\n    if (!clientId) {\n      // Fallback to parsing User-Agent if no client param\n      const userAgent = ctx.req.header(\"User-Agent\") || \"unknown\";\n      clientId = parseBrowserFromUserAgent(userAgent);\n    }\n    // Sanitize to prevent log injection - keep only safe printable characters\n    // Allow alphanumeric, spaces, dots, dashes, underscores, slashes, parentheses\n    clientId = clientId.replace(/[^\\w\\s.\\-/()]/g, \"\");\n    // Ensure we always have a non-empty clientId\n    if (!clientId) clientId = \"unknown\";\n\n    return streamSSE(ctx, async stream => {\n      // Check for Last-Event-ID header to support reconnection\n      const lastEventId = ctx.req.header(\"Last-Event-ID\");\n\n      // Subscribe to events, optionally starting from after the lastEventId\n      const sub = buffer.subscribe(container => {\n        logOutgoingEvent(container, clientId);\n\n        const parsedEnvelope = container.getParsedEnvelope();\n        if (parsedEnvelope) {\n          stream.writeSSE({\n            id: parsedEnvelope.envelope[0].__spotlight_envelope_id.toString(),\n            event: `${container.getContentType()}${base64Indicator}`,\n            data: JSON.stringify(parsedEnvelope.envelope),\n          });\n        }\n      }, lastEventId);\n\n      stream.onAbort(() => {\n        buffer.unsubscribe(sub);\n      });\n    });\n  })\n  .get(\"/envelope/:id\", ctx => {\n    const buffer = getBuffer();\n\n    const envelopeId = ctx.req.param(\"id\");\n    const container = buffer.read({ envelopeId });\n\n    if (container.length === 0) {\n      return ctx.notFound();\n    }\n\n    return ctx.body(new Uint8Array(container[0].getData()), 200, {\n      \"Content-Type\": container[0].getContentType(),\n      \"Cache-Control\": \"no-cache\",\n      \"Content-Disposition\": `attachment; filename=\"${envelopeId}.bin\"`,\n      Connection: \"keep-alive\",\n    });\n  })\n  .on(\"POST\", [\"/stream\", \"/api/:id/envelope\"], async ctx => {\n    let contentType = ctx.req.header(\"content-type\")?.split(\";\")[0].toLocaleLowerCase();\n    if (ctx.req.query(\"sentry_client\")?.startsWith(\"sentry.javascript.browser\") && ctx.req.header(\"Origin\")) {\n      // This is a correction we make as Sentry Browser SDK may send messages with text/plain to avoid CORS issues\n      contentType = SENTRY_CONTENT_TYPE;\n    }\n\n    // manually decompress body to use it below without another decompression\n    const body = decompressBody(Buffer.from(await ctx.req.arrayBuffer()), ctx.req.header(\"Content-Encoding\"));\n\n    const container = pushToSpotlightBuffer({\n      body,\n      spotlightBuffer: getBuffer(),\n      contentType,\n      userAgent: ctx.req.header(\"User-Agent\"),\n    });\n\n    if (container) {\n      // Log incoming event details when debug is enabled\n      logIncomingEvent(container);\n    } else {\n      logger.warn(\"No content type, skipping payload...\");\n    }\n\n    const incomingPayload = ctx.get(\"incomingPayload\");\n\n    if (process.env.SPOTLIGHT_CAPTURE || incomingPayload) {\n      const contentType = container?.getContentType();\n      const timestamp = BigInt(Date.now()) * 1_000_000n + (process.hrtime.bigint() % 1_000_000n);\n      const filename = `${contentType?.replace(/[^a-z0-9]/gi, \"_\") || \"no_content_type\"}-${timestamp}.txt`;\n\n      if (incomingPayload) {\n        incomingPayload(body.toString(\"binary\"));\n      } else {\n        const stream = createWriteStream(filename);\n        stream.on(\"error\", err => {\n          logger.error(`Failed to save data to ${filename}: ${err}`);\n          stream.destroy();\n        });\n        stream.end(body, () => {\n          logger.info(`🗃️ Saved data to ${filename}`);\n        });\n      }\n    }\n\n    // 204 would be more appropriate but returning 200 to match what /envelope returns\n    return ctx.body(null, 200, {\n      \"Cache-Control\": \"no-cache\",\n      Connection: \"keep-alive\",\n    });\n  });\n\nexport default router;\n"],"names":["contentType"],"mappings":"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"}

package/dist/server/routes/stream/streaming.d.ts

@@ -0,0 +1,3 @@
+import { Context } from 'hono';
+import { SSEStreamingApi } from 'hono/streaming';
+export declare const streamSSE: (c: Context, cb: (stream: SSEStreamingApi) => Promise<void>, onError?: (e: Error, stream: SSEStreamingApi) => Promise<void>) => Response;

package/dist/server/routes/stream/streaming.js

@@ -0,0 +1,35 @@
+;
+!function() {
+  try {
+    var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {}, n = new e.Error().stack;
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "fe8af0d5-27a9-4341-90d6-e57e107c3c7d", e._sentryDebugIdIdentifier = "sentry-dbid-fe8af0d5-27a9-4341-90d6-e57e107c3c7d");
+  } catch (e2) {
+  }
+}();
+import { captureException } from "@sentry/node";
+import { SSEStreamingApi } from "../../../node_modules/.pnpm/hono@4.10.3/node_modules/hono/dist/helper/streaming/sse.js";
+import "../../../_virtual/_sentry-release-injection-file.js";
+const run = async (stream, cb, onError) => {
+  try {
+    await cb(stream);
+  } catch (e) {
+    {
+      captureException(e, { extra: { context: "Unhandled error in SSE stream" } });
+    }
+  }
+};
+const streamSSE = (c, cb, onError) => {
+  const { readable, writable } = new TransformStream();
+  const stream = new SSEStreamingApi(writable, readable);
+  c.header("Transfer-Encoding", "chunked");
+  c.header("Content-Type", "text/event-stream");
+  c.header("Cache-Control", "no-cache");
+  c.header("Connection", "keep-alive");
+  stream.writeln("");
+  run(stream, cb);
+  return c.newResponse(stream.responseReadable);
+};
+export {
+  streamSSE
+};
+//# sourceMappingURL=streaming.js.map

package/dist/server/routes/stream/streaming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.js","sources":["../../../../src/server/routes/stream/streaming.ts"],"sourcesContent":["import { captureException } from \"@sentry/node\";\nimport type { Context } from \"hono\";\nimport { SSEStreamingApi } from \"hono/streaming\";\n\nconst run = async (\n  stream: SSEStreamingApi,\n  cb: (stream: SSEStreamingApi) => Promise<void>,\n  onError?: (e: Error, stream: SSEStreamingApi) => Promise<void>,\n): Promise<void> => {\n  try {\n    await cb(stream);\n  } catch (e) {\n    if (e instanceof Error && onError) {\n      await onError(e, stream);\n\n      await stream.writeSSE({\n        event: \"error\",\n        data: e.message,\n      });\n    } else {\n      captureException(e, { extra: { context: \"Unhandled error in SSE stream\" } });\n    }\n  }\n};\n\nexport const streamSSE = (\n  c: Context,\n  cb: (stream: SSEStreamingApi) => Promise<void>,\n  onError?: (e: Error, stream: SSEStreamingApi) => Promise<void>,\n): Response => {\n  const { readable, writable } = new TransformStream();\n  const stream = new SSEStreamingApi(writable, readable);\n\n  c.header(\"Transfer-Encoding\", \"chunked\");\n  c.header(\"Content-Type\", \"text/event-stream\");\n  c.header(\"Cache-Control\", \"no-cache\");\n  c.header(\"Connection\", \"keep-alive\");\n\n  // Send something in the body to trigger the `open` event\n  // This is mostly for Firefox -- see #376\n  stream.writeln(\"\");\n\n  run(stream, cb, onError);\n\n  return c.newResponse(stream.responseReadable);\n};\n"],"names":[],"mappings":";;;;;;;;;;;AAIA,MAAM,MAAM,OACV,QACA,IACA,YACkB;AAClB,MAAI;AACF,UAAM,GAAG,MAAM;AAAA,EACjB,SAAS,GAAG;AAQH;AACL,uBAAiB,GAAG,EAAE,OAAO,EAAE,SAAS,gCAAA,GAAmC;AAAA,IAC7E;AAAA,EACF;AACF;AAEO,MAAM,YAAY,CACvB,GACA,IACA,YACa;AACb,QAAM,EAAE,UAAU,SAAA,IAAa,IAAI,gBAAA;AACnC,QAAM,SAAS,IAAI,gBAAgB,UAAU,QAAQ;AAErD,IAAE,OAAO,qBAAqB,SAAS;AACvC,IAAE,OAAO,gBAAgB,mBAAmB;AAC5C,IAAE,OAAO,iBAAiB,UAAU;AACpC,IAAE,OAAO,cAAc,YAAY;AAInC,SAAO,QAAQ,EAAE;AAEjB,MAAI,QAAQ,EAAW;AAEvB,SAAO,EAAE,YAAY,OAAO,gBAAgB;AAC9C;"}

package/dist/server/routes/stream/userAgent.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Extracts browser name and major version from a User-Agent string
+ * Returns format like "Chrome/131" or "Firefox/122"
+ */
+export declare function parseBrowserFromUserAgent(userAgent: string): string;
+/**
+ * Builds a client identifier from browser info and optional hostname
+ * Format: clientName/version (metadata)
+ * Example: "ui/Chrome/131 (example.com)"
+ */
+export declare function buildClientIdentifier(clientName: string, userAgent?: string, hostname?: string): string;

package/dist/server/routes/stream/userAgent.js

@@ -0,0 +1,34 @@
+;
+!function() {
+  try {
+    var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {}, n = new e.Error().stack;
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "973355d8-c9ea-4dc7-b5bb-32f849e751bc", e._sentryDebugIdIdentifier = "sentry-dbid-973355d8-c9ea-4dc7-b5bb-32f849e751bc");
+  } catch (e2) {
+  }
+}();
+import "../../../_virtual/_sentry-release-injection-file.js";
+function parseBrowserFromUserAgent(userAgent) {
+  if (!userAgent) return "unknown";
+  if (userAgent.includes("Chrome/") && !userAgent.includes("Edg/")) {
+    const match2 = userAgent.match(/Chrome\/([\d]+)/);
+    return match2 ? `Chrome/${match2[1]}` : "Chrome";
+  }
+  if (userAgent.includes("Firefox/")) {
+    const match2 = userAgent.match(/Firefox\/([\d]+)/);
+    return match2 ? `Firefox/${match2[1]}` : "Firefox";
+  }
+  if (userAgent.includes("Safari/") && !userAgent.includes("Chrome")) {
+    const match2 = userAgent.match(/Version\/([\d]+)/);
+    return match2 ? `Safari/${match2[1]}` : "Safari";
+  }
+  if (userAgent.includes("Edg/")) {
+    const match2 = userAgent.match(/Edg\/([\d]+)/);
+    return match2 ? `Edge/${match2[1]}` : "Edge";
+  }
+  const match = userAgent.match(/^([^\/\s\(]+)/);
+  return match ? match[1] : "unknown";
+}
+export {
+  parseBrowserFromUserAgent
+};
+//# sourceMappingURL=userAgent.js.map

package/dist/server/routes/stream/userAgent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"userAgent.js","sources":["../../../../src/server/routes/stream/userAgent.ts"],"sourcesContent":["/**\n * Extracts browser name and major version from a User-Agent string\n * Returns format like \"Chrome/131\" or \"Firefox/122\"\n */\nexport function parseBrowserFromUserAgent(userAgent: string): string {\n  if (!userAgent) return \"unknown\";\n\n  // Check for Chrome (but not Edge which also contains Chrome)\n  if (userAgent.includes(\"Chrome/\") && !userAgent.includes(\"Edg/\")) {\n    const match = userAgent.match(/Chrome\\/([\\d]+)/);\n    return match ? `Chrome/${match[1]}` : \"Chrome\";\n  }\n\n  // Check for Firefox\n  if (userAgent.includes(\"Firefox/\")) {\n    const match = userAgent.match(/Firefox\\/([\\d]+)/);\n    return match ? `Firefox/${match[1]}` : \"Firefox\";\n  }\n\n  // Check for Safari (but not Chrome which also contains Safari)\n  if (userAgent.includes(\"Safari/\") && !userAgent.includes(\"Chrome\")) {\n    const match = userAgent.match(/Version\\/([\\d]+)/);\n    return match ? `Safari/${match[1]}` : \"Safari\";\n  }\n\n  // Check for Edge\n  if (userAgent.includes(\"Edg/\")) {\n    const match = userAgent.match(/Edg\\/([\\d]+)/);\n    return match ? `Edge/${match[1]}` : \"Edge\";\n  }\n\n  // Generic fallback - try to extract first meaningful part\n  const match = userAgent.match(/^([^\\/\\s\\(]+)/);\n  return match ? match[1] : \"unknown\";\n}\n\n/**\n * Builds a client identifier from browser info and optional hostname\n * Format: clientName/version (metadata)\n * Example: \"ui/Chrome/131 (example.com)\"\n */\nexport function buildClientIdentifier(clientName: string, userAgent?: string, hostname?: string): string {\n  let clientId = clientName;\n\n  if (userAgent) {\n    const browserInfo = parseBrowserFromUserAgent(userAgent);\n    if (browserInfo !== \"unknown\") {\n      clientId = `${clientName}/${browserInfo}`;\n    }\n  }\n\n  if (hostname && hostname !== \"localhost\") {\n    clientId += ` (${hostname})`;\n  }\n\n  return clientId;\n}\n"],"names":["match"],"mappings":";;;;;;;;;AAIO,SAAS,0BAA0B,WAA2B;AACnE,MAAI,CAAC,UAAW,QAAO;AAGvB,MAAI,UAAU,SAAS,SAAS,KAAK,CAAC,UAAU,SAAS,MAAM,GAAG;AAChE,UAAMA,SAAQ,UAAU,MAAM,iBAAiB;AAC/C,WAAOA,SAAQ,UAAUA,OAAM,CAAC,CAAC,KAAK;AAAA,EACxC;AAGA,MAAI,UAAU,SAAS,UAAU,GAAG;AAClC,UAAMA,SAAQ,UAAU,MAAM,kBAAkB;AAChD,WAAOA,SAAQ,WAAWA,OAAM,CAAC,CAAC,KAAK;AAAA,EACzC;AAGA,MAAI,UAAU,SAAS,SAAS,KAAK,CAAC,UAAU,SAAS,QAAQ,GAAG;AAClE,UAAMA,SAAQ,UAAU,MAAM,kBAAkB;AAChD,WAAOA,SAAQ,UAAUA,OAAM,CAAC,CAAC,KAAK;AAAA,EACxC;AAGA,MAAI,UAAU,SAAS,MAAM,GAAG;AAC9B,UAAMA,SAAQ,UAAU,MAAM,cAAc;AAC5C,WAAOA,SAAQ,QAAQA,OAAM,CAAC,CAAC,KAAK;AAAA,EACtC;AAGA,QAAM,QAAQ,UAAU,MAAM,eAAe;AAC7C,SAAO,QAAQ,MAAM,CAAC,IAAI;AAC5B;"}

package/dist/server/sdk.d.ts

@@ -0,0 +1,15 @@
+import { MessageBuffer } from './messageBuffer.ts';
+import { EventContainer } from './utils/eventContainer.ts';
+declare const decompressors: Record<"gzip" | "deflate" | "br", (buf: Buffer) => Buffer>;
+type ContentEncoding = keyof typeof decompressors;
+export declare function createSpotlightBuffer(): MessageBuffer<EventContainer>;
+type PushToSpotlightBufferOptions = {
+    spotlightBuffer: MessageBuffer<EventContainer>;
+    body: Buffer;
+    encoding?: ContentEncoding;
+    contentType?: string;
+    userAgent?: string;
+};
+export declare function pushToSpotlightBuffer(options: PushToSpotlightBufferOptions): EventContainer | undefined;
+export declare function decompressBody(body: Buffer, contentEncoding?: ContentEncoding): Buffer<ArrayBufferLike>;
+export {};

package/dist/server/sdk.js

@@ -0,0 +1,41 @@
+;
+!function() {
+  try {
+    var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {}, n = new e.Error().stack;
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "75ed20dd-d677-4ccd-a15b-af93d9a30db1", e._sentryDebugIdIdentifier = "sentry-dbid-75ed20dd-d677-4ccd-a15b-af93d9a30db1");
+  } catch (e2) {
+  }
+}();
+import { brotliDecompressSync, inflateSync, gunzipSync } from "node:zlib";
+import { MessageBuffer } from "./messageBuffer.js";
+import { EventContainer } from "./utils/eventContainer.js";
+import "../_virtual/_sentry-release-injection-file.js";
+const decompressors = {
+  gzip: gunzipSync,
+  deflate: inflateSync,
+  br: brotliDecompressSync
+};
+function createSpotlightBuffer() {
+  return new MessageBuffer();
+}
+function pushToSpotlightBuffer(options) {
+  const body = decompressBody(options.body, options.encoding);
+  const contentType = options.contentType?.split(";")[0].toLocaleLowerCase();
+  if (contentType) {
+    const container = new EventContainer(contentType, body, options.userAgent);
+    options.spotlightBuffer.put(container);
+    return container;
+  }
+}
+function decompressBody(body, contentEncoding) {
+  if (!contentEncoding) {
+    return body;
+  }
+  return decompressors[contentEncoding](body);
+}
+export {
+  createSpotlightBuffer,
+  decompressBody,
+  pushToSpotlightBuffer
+};
+//# sourceMappingURL=sdk.js.map

package/dist/server/sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.js","sources":["../../src/server/sdk.ts"],"sourcesContent":["import { brotliDecompressSync, gunzipSync, inflateSync } from \"node:zlib\";\nimport { MessageBuffer } from \"./messageBuffer.ts\";\nimport { EventContainer } from \"./utils/eventContainer.ts\";\n\nconst decompressors: Record<\"gzip\" | \"deflate\" | \"br\", (buf: Buffer) => Buffer> = {\n  gzip: gunzipSync,\n  deflate: inflateSync,\n  br: brotliDecompressSync,\n};\ntype ContentEncoding = keyof typeof decompressors;\n\nexport function createSpotlightBuffer() {\n  return new MessageBuffer<EventContainer>();\n}\n\ntype PushToSpotlightBufferOptions = {\n  spotlightBuffer: MessageBuffer<EventContainer>;\n  body: Buffer;\n  encoding?: ContentEncoding;\n  contentType?: string;\n  userAgent?: string;\n};\n\nexport function pushToSpotlightBuffer(options: PushToSpotlightBufferOptions) {\n  const body = decompressBody(options.body, options.encoding);\n\n  const contentType = options.contentType?.split(\";\")[0].toLocaleLowerCase();\n\n  if (contentType) {\n    // Create event container and add to buffer\n    const container = new EventContainer(contentType, body, options.userAgent);\n\n    // Add to buffer - this will automatically trigger all subscribers\n    // including the onEnvelope callback if one is registered\n    options.spotlightBuffer.put(container);\n\n    return container;\n  }\n}\n\nexport function decompressBody(body: Buffer, contentEncoding?: ContentEncoding) {\n  if (!contentEncoding) {\n    return body;\n  }\n  return decompressors[contentEncoding](body);\n}\n"],"names":[],"mappings":";;;;;;;;;;;;AAIA,MAAM,gBAA4E;AAAA,EAChF,MAAM;AAAA,EACN,SAAS;AAAA,EACT,IAAI;AACN;AAGO,SAAS,wBAAwB;AACtC,SAAO,IAAI,cAAA;AACb;AAUO,SAAS,sBAAsB,SAAuC;AAC3E,QAAM,OAAO,eAAe,QAAQ,MAAM,QAAQ,QAAQ;AAE1D,QAAM,cAAc,QAAQ,aAAa,MAAM,GAAG,EAAE,CAAC,EAAE,kBAAA;AAEvD,MAAI,aAAa;AAEf,UAAM,YAAY,IAAI,eAAe,aAAa,MAAM,QAAQ,SAAS;AAIzE,YAAQ,gBAAgB,IAAI,SAAS;AAErC,WAAO;AAAA,EACT;AACF;AAEO,SAAS,eAAe,MAAc,iBAAmC;AAC9E,MAAI,CAAC,iBAAiB;AACpB,WAAO;AAAA,EACT;AACA,SAAO,cAAc,eAAe,EAAE,IAAI;AAC5C;"}

package/dist/server/types/cli.d.ts

@@ -0,0 +1,15 @@
+import { FormatterType } from '../formatters/types.ts';
+import { SideCarOptions } from './utils.ts';
+export type CLIHandlerOptions = {
+    cmd?: string;
+    cmdArgs: string[];
+    port: SideCarOptions["port"];
+    help?: boolean;
+    debug?: boolean;
+    format?: FormatterType;
+    basePath?: SideCarOptions["basePath"];
+    filesToServe?: SideCarOptions["filesToServe"];
+    allowedOrigins?: SideCarOptions["allowedOrigins"];
+};
+export type CLIHandlerReturnType = Promise<any> | any;
+export type CLIHandler = ((options: CLIHandlerOptions) => CLIHandlerReturnType) | (() => CLIHandlerReturnType);

package/dist/server/types/env.d.ts

@@ -0,0 +1,10 @@
+import { HttpBindings } from '@hono/node-server';
+import { IncomingPayloadCallback } from './utils.ts';
+export type HonoEnv = {
+    Bindings: HttpBindings;
+    Variables: {
+        contextId: string;
+        basePath?: string;
+        incomingPayload?: IncomingPayloadCallback;
+    };
+};

package/dist/server/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './env.ts';
+export * from './utils.ts';

package/dist/server/types/utils.d.ts

@@ -0,0 +1,56 @@
+import { ParsedEnvelope } from '../parser/processEnvelope.ts';
+import { NormalizedAllowedOrigins } from '../utils/cors.ts';
+export type IncomingPayloadCallback = (body: string) => void;
+export type OnEnvelopeCallback = (envelope: ParsedEnvelope["envelope"]) => void;
+export type SidecarLogger = {
+    info: (message: any) => void;
+    warn: (message: any) => void;
+    error: (message: any) => void;
+    debug: (message: any) => void;
+};
+export type SideCarOptions = {
+    /**
+     * The port on which the sidecar should listen.
+     * Defaults to 8969.
+     */
+    port: number;
+    /**
+     * A logger that implements the SidecarLogger interface.
+     * Use this to inject your custom logger implementation.
+     *
+     * @default - a simple logger logging to the console.
+     */
+    logger?: SidecarLogger;
+    /**
+     * The base path from where the static files should be served.
+     */
+    basePath?: string;
+    filesToServe?: Record<string, Buffer>;
+    /**
+     * A callback that will be called with the incoming message.
+     * Helpful for debugging.
+     */
+    incomingPayload?: IncomingPayloadCallback;
+    /**
+     * A callback that will be called with the parsed envelope every
+     * time an envelope is received. This will me mainly used for the
+     * CLI for streaming data but can be used by other tools as well.
+     */
+    onEnvelope?: OnEnvelopeCallback;
+    isStandalone?: boolean;
+    stdioMCP?: boolean;
+    /**
+     * Additional origins to allow for CORS requests.
+     * Useful for custom local domains, tunnels, etc.
+     *
+     * Accepts two formats:
+     * - Full origins (e.g., "https://ngrok.io:443") for strict matching
+     * - Plain domains (e.g., "myapp.local") to allow any protocol/port
+     */
+    allowedOrigins?: string[];
+};
+export type StartServerOptions = Pick<SideCarOptions, "basePath" | "filesToServe" | "incomingPayload"> & {
+    port: number;
+    /** Pre-normalized allowed origins for CORS (use normalizeAllowedOrigins() to create) */
+    normalizedAllowedOrigins?: NormalizedAllowedOrigins;
+};

package/dist/server/utils/cors.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pre-normalized allowed origins for efficient matching.
+ * Call normalizeAllowedOrigins() once at server startup to create this structure.
+ */
+export interface NormalizedAllowedOrigins {
+    /** Full origins (lowercased, trailing slash removed) for exact matching */
+    fullOrigins: Set<string>;
+    /** Plain domains (lowercased) for permissive matching */
+    domains: Set<string>;
+}
+/**
+ * Normalize and classify allowed origins for efficient matching.
+ * Call this once at server startup, then pass the result to isAllowedOrigin().
+ *
+ * @param allowedOrigins - Raw list of allowed origins/domains from config
+ * @returns Pre-normalized structure for O(1) lookups
+ */
+export declare function normalizeAllowedOrigins(allowedOrigins: string[]): NormalizedAllowedOrigins;
+/**
+ * Clear the DNS cache, pending resolutions, and machine IPs cache. Useful for testing.
+ */
+export declare function clearDnsCache(): void;
+/**
+ * Get the current DNS cache size. Useful for testing.
+ */
+export declare function getDnsCacheSize(): number;
+/**
+ * Validates if an origin should be allowed to access the Sidecar.
+ *
+ * Allowed origins:
+ * - localhost (RFC 6761 reserved name, always trusted)
+ * - Any origin whose hostname resolves to this machine's IPs (with TTL >= 1h)
+ * - https://spotlightjs.com and subdomains (HTTPS only, default port)
+ * - Custom origins/domains from the normalizedAllowedOrigins list
+ *
+ * For DNS rebinding protection details, see the TTL Constants section above.
+ *
+ * @param origin - The origin to validate
+ * @param normalizedAllowedOrigins - Optional pre-normalized allowed origins (from normalizeAllowedOrigins())
+ * @returns Promise<boolean> - true if the origin is allowed, false otherwise
+ */
+export declare function isAllowedOrigin(origin: string, normalizedAllowedOrigins?: NormalizedAllowedOrigins): Promise<boolean>;