@dash0/sdk-web 0.13.4 → 0.14.0

package/src/attributes/url_test.ts

@@ -0,0 +1,417 @@
+import { expect, describe, it, beforeEach, afterEach } from "vitest";
+import { addUrlAttributes, UrlAttributeScrubber } from "./url";
+import { KeyValue } from "../types/otlp";
+import { vars } from "../vars";
+import { identity } from "../utils/fn";
+import { URL_DOMAIN, URL_FRAGMENT, URL_FULL, URL_PATH, URL_QUERY, URL_SCHEME } from "../semantic-conventions";
+
+describe("addUrlAttributes", () => {
+  let attributes: KeyValue[];
+  let originalScrubber: UrlAttributeScrubber;
+
+  beforeEach(() => {
+    attributes = [];
+    originalScrubber = vars.urlAttributeScrubber;
+    vars.urlAttributeScrubber = identity;
+  });
+
+  afterEach(() => {
+    vars.urlAttributeScrubber = originalScrubber;
+  });
+
+  describe("URL parsing and attribute extraction", () => {
+    it("extracts all URL components for complete URL", () => {
+      const url = "https://example.com:8080/path/to/resource?param1=value1&param2=value2#section1";
+
+      addUrlAttributes(attributes, url);
+
+      expect(attributes).toEqual([
+        {
+          key: URL_FULL,
+          value: { stringValue: "https://example.com:8080/path/to/resource?param1=value1&param2=value2#section1" },
+        },
+        { key: URL_PATH, value: { stringValue: "/path/to/resource" } },
+        { key: URL_DOMAIN, value: { stringValue: "example.com" } },
+        { key: URL_SCHEME, value: { stringValue: "https" } },
+        { key: URL_FRAGMENT, value: { stringValue: "section1" } },
+        { key: URL_QUERY, value: { stringValue: "param1=value1&param2=value2" } },
+      ]);
+    });
+
+    it("handles URL with only required components", () => {
+      const url = "https://example.com";
+
+      addUrlAttributes(attributes, url);
+
+      expect(attributes).toEqual([
+        { key: URL_FULL, value: { stringValue: "https://example.com/" } },
+        { key: URL_PATH, value: { stringValue: "/" } },
+        { key: URL_DOMAIN, value: { stringValue: "example.com" } },
+        { key: URL_SCHEME, value: { stringValue: "https" } },
+      ]);
+    });
+
+    it("handles URL with path but no query or fragment", () => {
+      const url = "http://example.com/some/path";
+
+      addUrlAttributes(attributes, url);
+
+      expect(attributes).toEqual([
+        { key: URL_FULL, value: { stringValue: "http://example.com/some/path" } },
+        { key: URL_PATH, value: { stringValue: "/some/path" } },
+        { key: URL_DOMAIN, value: { stringValue: "example.com" } },
+        { key: URL_SCHEME, value: { stringValue: "http" } },
+      ]);
+    });
+
+    it("handles URL with query but no fragment", () => {
+      const url = "https://example.com/path?query=test";
+
+      addUrlAttributes(attributes, url);
+
+      expect(attributes).toEqual([
+        { key: URL_FULL, value: { stringValue: "https://example.com/path?query=test" } },
+        { key: URL_PATH, value: { stringValue: "/path" } },
+        { key: URL_DOMAIN, value: { stringValue: "example.com" } },
+        { key: URL_SCHEME, value: { stringValue: "https" } },
+        { key: URL_QUERY, value: { stringValue: "query=test" } },
+      ]);
+    });
+
+    it("handles URL with fragment but no query", () => {
+      const url = "https://example.com/path#section";
+
+      addUrlAttributes(attributes, url);
+
+      expect(attributes).toEqual([
+        { key: URL_FULL, value: { stringValue: "https://example.com/path#section" } },
+        { key: URL_PATH, value: { stringValue: "/path" } },
+        { key: URL_DOMAIN, value: { stringValue: "example.com" } },
+        { key: URL_SCHEME, value: { stringValue: "https" } },
+        { key: URL_FRAGMENT, value: { stringValue: "section" } },
+      ]);
+    });
+
+    it("accepts URL object as input", () => {
+      const urlObject = new URL("https://example.com/path?query=test#fragment");
+
+      addUrlAttributes(attributes, urlObject);
+
+      expect(attributes).toEqual([
+        { key: URL_FULL, value: { stringValue: "https://example.com/path?query=test#fragment" } },
+        { key: URL_PATH, value: { stringValue: "/path" } },
+        { key: URL_DOMAIN, value: { stringValue: "example.com" } },
+        { key: URL_SCHEME, value: { stringValue: "https" } },
+        { key: URL_FRAGMENT, value: { stringValue: "fragment" } },
+        { key: URL_QUERY, value: { stringValue: "query=test" } },
+      ]);
+    });
+  });
+
+  describe("credential redaction functionality", () => {
+    it("redacts username and password from URL", () => {
+      const url = "https://user:pass@example.com/path";
+
+      addUrlAttributes(attributes, url);
+
+      expect(attributes).toEqual([
+        { key: URL_FULL, value: { stringValue: "https://REDACTED:REDACTED@example.com/path" } },
+        { key: URL_PATH, value: { stringValue: "/path" } },
+        { key: URL_DOMAIN, value: { stringValue: "example.com" } },
+        { key: URL_SCHEME, value: { stringValue: "https" } },
+      ]);
+    });
+
+    it("redacts username when password is not present", () => {
+      const url = "https://user@example.com/path";
+
+      addUrlAttributes(attributes, url);
+
+      expect(attributes).toEqual([
+        { key: URL_FULL, value: { stringValue: "https://REDACTED@example.com/path" } },
+        { key: URL_PATH, value: { stringValue: "/path" } },
+        { key: URL_DOMAIN, value: { stringValue: "example.com" } },
+        { key: URL_SCHEME, value: { stringValue: "https" } },
+      ]);
+    });
+
+    it("handles special characters in credentials", () => {
+      const url = "https://user%40domain:p%40ssw0rd@example.com/path";
+
+      addUrlAttributes(attributes, url);
+
+      expect(attributes).toEqual([
+        { key: URL_FULL, value: { stringValue: "https://REDACTED:REDACTED@example.com/path" } },
+        { key: URL_PATH, value: { stringValue: "/path" } },
+        { key: URL_DOMAIN, value: { stringValue: "example.com" } },
+        { key: URL_SCHEME, value: { stringValue: "https" } },
+      ]);
+    });
+  });
+
+  describe("URL attribute scrubber integration", () => {
+    it("applies custom scrubber to URL attributes", () => {
+      const customScrubber: UrlAttributeScrubber = (attrs) => ({
+        ...attrs,
+        [URL_PATH]: "REDACTED",
+        [URL_QUERY]: undefined,
+      });
+      vars.urlAttributeScrubber = customScrubber;
+
+      const url = "https://example.com/sensitive/path?secret=value#fragment";
+
+      addUrlAttributes(attributes, url);
+
+      expect(attributes).toEqual([
+        { key: URL_FULL, value: { stringValue: "https://example.com/sensitive/path?secret=value#fragment" } },
+        { key: URL_PATH, value: { stringValue: "REDACTED" } },
+        { key: URL_DOMAIN, value: { stringValue: "example.com" } },
+        { key: URL_SCHEME, value: { stringValue: "https" } },
+        { key: URL_FRAGMENT, value: { stringValue: "fragment" } },
+      ]);
+    });
+
+    it("applies scrubber that removes all optional attributes", () => {
+      const restrictiveScrubber: UrlAttributeScrubber = (attrs) => ({
+        [URL_FULL]: attrs[URL_FULL],
+      });
+      vars.urlAttributeScrubber = restrictiveScrubber;
+
+      const url = "https://example.com/path?query=test#fragment";
+
+      addUrlAttributes(attributes, url);
+
+      expect(attributes).toEqual([
+        { key: URL_FULL, value: { stringValue: "https://example.com/path?query=test#fragment" } },
+      ]);
+    });
+
+    it("handles scrubber that throws an error", () => {
+      const errorScrubber: UrlAttributeScrubber = () => {
+        throw new Error("Scrubber error");
+      };
+      vars.urlAttributeScrubber = errorScrubber;
+
+      const url = "https://example.com/path";
+
+      addUrlAttributes(attributes, url);
+
+      expect(attributes).toHaveLength(0);
+    });
+
+    it("applies identity scrubber correctly", () => {
+      vars.urlAttributeScrubber = identity;
+
+      const url = "https://example.com/path?query=test";
+
+      addUrlAttributes(attributes, url);
+
+      expect(attributes).toHaveLength(5);
+      expect(attributes.find((attr) => attr.key === URL_FULL)?.value).toEqual({
+        stringValue: "https://example.com/path?query=test",
+      });
+      expect(attributes.find((attr) => attr.key === URL_PATH)?.value).toEqual({ stringValue: "/path" });
+      expect(attributes.find((attr) => attr.key === URL_DOMAIN)?.value).toEqual({ stringValue: "example.com" });
+      expect(attributes.find((attr) => attr.key === URL_SCHEME)?.value).toEqual({ stringValue: "https" });
+      expect(attributes.find((attr) => attr.key === URL_QUERY)?.value).toEqual({ stringValue: "query=test" });
+    });
+  });
+
+  describe("error handling for invalid URLs", () => {
+    it("handles invalid URL with identity scrubber by adding full URL", () => {
+      vars.urlAttributeScrubber = identity;
+      const invalidUrl = "not-a-valid-url";
+
+      addUrlAttributes(attributes, invalidUrl);
+
+      // Invalid URLs still parse but create fallback attributes
+      expect(attributes.length).toBeGreaterThan(0);
+      // The actual behavior might be different based on the parsing logic
+      const fullAttr = attributes.find((attr) => attr.key === URL_FULL);
+      expect(fullAttr).toBeDefined();
+    });
+
+    it("handles invalid URL with custom scrubber by dropping attributes", () => {
+      const customScrubber: UrlAttributeScrubber = (attrs) => attrs;
+      vars.urlAttributeScrubber = customScrubber;
+      const invalidUrl = "not-a-valid-url";
+
+      addUrlAttributes(attributes, invalidUrl);
+
+      // With custom scrubber, invalid URLs still get parsed with fallback
+      expect(attributes.length).toBeGreaterThan(0);
+    });
+
+    it("handles empty string URL with identity scrubber", () => {
+      vars.urlAttributeScrubber = identity;
+      const emptyUrl = "";
+
+      addUrlAttributes(attributes, emptyUrl);
+
+      // Empty URLs still parse but create fallback attributes
+      expect(attributes.length).toBeGreaterThan(0);
+      expect(attributes.find((attr) => attr.key === URL_FULL)?.value).toEqual({
+        stringValue: "http://localhost:3000/",
+      });
+    });
+
+    it("handles relative URL that can be parsed with base", () => {
+      // This should work if there's a document.baseURI or location.href available
+      const relativeUrl = "/relative/path?query=test";
+
+      // This might throw or might work depending on environment
+      addUrlAttributes(attributes, relativeUrl);
+
+      // We expect either parsed attributes or fallback behavior
+      expect(attributes.length).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  describe("prefix functionality for attributes", () => {
+    it("applies string prefix to attribute keys", () => {
+      const url = "https://example.com/path";
+      const prefix = "page";
+
+      addUrlAttributes(attributes, url, prefix);
+
+      expect(attributes).toEqual([
+        { key: "page.url.full", value: { stringValue: "https://example.com/path" } },
+        { key: "page.url.path", value: { stringValue: "/path" } },
+        { key: "page.url.domain", value: { stringValue: "example.com" } },
+        { key: "page.url.scheme", value: { stringValue: "https" } },
+      ]);
+    });
+
+    it("applies array prefix to attribute keys", () => {
+      const url = "https://example.com/path?query=test";
+      const prefix = ["http", "request"];
+
+      addUrlAttributes(attributes, url, prefix);
+
+      expect(attributes).toEqual([
+        { key: "http.request.url.full", value: { stringValue: "https://example.com/path?query=test" } },
+        { key: "http.request.url.path", value: { stringValue: "/path" } },
+        { key: "http.request.url.domain", value: { stringValue: "example.com" } },
+        { key: "http.request.url.scheme", value: { stringValue: "https" } },
+        { key: "http.request.url.query", value: { stringValue: "query=test" } },
+      ]);
+    });
+
+    it("handles empty string prefix", () => {
+      const url = "https://example.com/path";
+      const prefix = "";
+
+      addUrlAttributes(attributes, url, prefix);
+
+      expect(attributes).toEqual([
+        { key: "url.full", value: { stringValue: "https://example.com/path" } },
+        { key: "url.path", value: { stringValue: "/path" } },
+        { key: "url.domain", value: { stringValue: "example.com" } },
+        { key: "url.scheme", value: { stringValue: "https" } },
+      ]);
+    });
+
+    it("handles undefined prefix", () => {
+      const url = "https://example.com/path";
+
+      addUrlAttributes(attributes, url, undefined);
+
+      expect(attributes).toEqual([
+        { key: URL_FULL, value: { stringValue: "https://example.com/path" } },
+        { key: URL_PATH, value: { stringValue: "/path" } },
+        { key: URL_DOMAIN, value: { stringValue: "example.com" } },
+        { key: URL_SCHEME, value: { stringValue: "https" } },
+      ]);
+    });
+
+    it("applies prefix with error handling fallback", () => {
+      vars.urlAttributeScrubber = identity;
+      const invalidUrl = "invalid-url";
+      const prefix = "page";
+
+      addUrlAttributes(attributes, invalidUrl, prefix);
+
+      // With prefix and identity scrubber, fallback should include prefix
+      expect(attributes.length).toBeGreaterThan(0);
+      // The actual behavior might be different based on the parsing logic
+      const fullAttr = attributes.find((attr) => attr.key === "page.url.full");
+      expect(fullAttr).toBeDefined();
+    });
+  });
+
+  describe("edge cases and corner cases", () => {
+    it("handles URL with port number", () => {
+      const url = "https://example.com:8080/path";
+
+      addUrlAttributes(attributes, url);
+
+      expect(attributes).toEqual([
+        { key: URL_FULL, value: { stringValue: "https://example.com:8080/path" } },
+        { key: URL_PATH, value: { stringValue: "/path" } },
+        { key: URL_DOMAIN, value: { stringValue: "example.com" } },
+        { key: URL_SCHEME, value: { stringValue: "https" } },
+      ]);
+    });
+
+    it("handles URL with IP address", () => {
+      const url = "http://192.168.1.1:8080/api";
+
+      addUrlAttributes(attributes, url);
+
+      expect(attributes).toEqual([
+        { key: URL_FULL, value: { stringValue: "http://192.168.1.1:8080/api" } },
+        { key: URL_PATH, value: { stringValue: "/api" } },
+        { key: URL_DOMAIN, value: { stringValue: "192.168.1.1" } },
+        { key: URL_SCHEME, value: { stringValue: "http" } },
+      ]);
+    });
+
+    it("handles URL with IPv6 address", () => {
+      const url = "http://[::1]:8080/path";
+
+      addUrlAttributes(attributes, url);
+
+      expect(attributes).toEqual([
+        { key: URL_FULL, value: { stringValue: "http://[::1]:8080/path" } },
+        { key: URL_PATH, value: { stringValue: "/path" } },
+        { key: URL_DOMAIN, value: { stringValue: "[::1]" } },
+        { key: URL_SCHEME, value: { stringValue: "http" } },
+      ]);
+    });
+
+    it("handles URL with encoded characters", () => {
+      const url = "https://example.com/path%20with%20spaces?query=value%20with%20spaces#fragment%20with%20spaces";
+
+      addUrlAttributes(attributes, url);
+
+      expect(attributes).toEqual([
+        {
+          key: URL_FULL,
+          value: {
+            stringValue:
+              "https://example.com/path%20with%20spaces?query=value%20with%20spaces#fragment%20with%20spaces",
+          },
+        },
+        { key: URL_PATH, value: { stringValue: "/path%20with%20spaces" } },
+        { key: URL_DOMAIN, value: { stringValue: "example.com" } },
+        { key: URL_SCHEME, value: { stringValue: "https" } },
+        { key: URL_FRAGMENT, value: { stringValue: "fragment%20with%20spaces" } },
+        { key: URL_QUERY, value: { stringValue: "query=value%20with%20spaces" } },
+      ]);
+    });
+
+    it("handles different protocol schemes", () => {
+      const protocols = ["ftp", "ws", "wss", "file"];
+
+      protocols.forEach((protocol) => {
+        attributes = []; // Reset attributes for each test
+        const url = `${protocol}://example.com/path`;
+
+        addUrlAttributes(attributes, url);
+
+        const schemeAttr = attributes.find((attr) => attr.key === URL_SCHEME);
+        expect(schemeAttr?.value).toEqual({ stringValue: protocol });
+      });
+    });
+  });
+});

package/src/entrypoint/npm-package.ts

@@ -1,5 +1,6 @@
 import { debug, INIT_MESSAGE } from "../utils";
-import { init as initApi, InitOptions } from "../api/init";
+import { init as initApi } from "../api/init";
+import { InitOptions } from "../types/options";
 
 export * from "../api/identify";
 export * from "../api/debug";

package/src/instrumentations/errors/unhandled-error.ts

@@ -1,6 +1,4 @@
-import { KeyValue, LogRecord } from "../../../types/otlp";
 import { hasOwnProperty, nowNanos, win } from "../../utils";
-import { ErrorLike, ReportErrorOpts } from "../../../types/errors";
 import { isErrorMessageIgnored } from "../../utils/ignore-rules";
 import { sendLog } from "../../transport";
 import {
@@ -14,6 +12,8 @@ import {
 } from "../../semantic-conventions";
 import { addAttribute } from "../../utils/otel";
 import { addCommonAttributes } from "../../attributes";
+import { KeyValue, LogRecord } from "../../types/otlp";
+import { ReportErrorOpts, ErrorLike } from "../../types/errors";
 
 type TrackedError = {
   seenCount: number;

package/src/instrumentations/navigation/event.ts

@@ -1,4 +1,3 @@
-import { KeyValue, LogRecord } from "../../../types/otlp";
 import { addAttribute, getTraceContextForPageLoad } from "../../utils/otel";
 import {
   EVENT_NAME,
@@ -13,6 +12,7 @@ import { doc, NO_VALUE_FALLBACK } from "../../utils";
 import { addCommonAttributes } from "../../attributes";
 import { sendLog } from "../../transport";
 import { PageViewMeta, vars } from "../../vars";
+import { KeyValue, LogRecord } from "../../types/otlp";
 
 function getPageViewMeta(url?: URL): PageViewMeta {
   if (!url) return {};

package/src/instrumentations/navigation/page-load.ts

@@ -1,10 +1,10 @@
 import { addEventListener, debug, doc, win, roundToTwoDecimals, error, toNanosTs, getTimeOrigin } from "../../utils";
-import { KeyValue, LogRecord } from "../../../types/otlp";
 import { EVENT_NAME, EVENT_NAMES, LOG_SEVERITIES } from "../../semantic-conventions";
 import { sendLog } from "../../transport";
 import { getTraceContextForPageLoad, addAttribute } from "../../utils/otel";
 import { addCommonAttributes } from "../../attributes";
 import { transmitPageViewEvent } from "./event";
+import { KeyValue, LogRecord } from "../../types/otlp";
 
 /**
  * Tracks page loads as per this OTel spec:

package/src/instrumentations/web-vitals.ts

@@ -1,5 +1,5 @@
 import { onLCP, onINP, onCLS, Metric } from "web-vitals";
-import { KeyValue, LogRecord } from "../../types/otlp";
+import { KeyValue, LogRecord } from "../types/otlp";
 import { EVENT_NAME, EVENT_NAMES, LOG_SEVERITIES } from "../semantic-conventions";
 import { nowNanos, roundToTwoDecimals } from "../utils";
 import { sendLog } from "../transport";

package/src/transport/index.ts

@@ -1,9 +1,9 @@
-import { ExportLogsServiceRequest, ExportTraceServiceRequest, LogRecord, Span } from "../../types/otlp";
 import { newBatcher } from "./batcher";
 import { send } from "./fetch";
 import { vars } from "../vars";
 import { createRateLimiter } from "../utils/rate-limit";
 import { debug, error } from "../utils";
+import { ExportLogsServiceRequest, ExportTraceServiceRequest, LogRecord, Span } from "../types/otlp";
 
 const logBatcher = newBatcher<LogRecord>(sendLogs);
 const spanBatcher = newBatcher<Span>(sendSpans);

package/src/types/errors.ts

@@ -0,0 +1,9 @@
+export type ErrorLike = {
+  message: string;
+  name?: string;
+  stack?: string;
+};
+
+export type ReportErrorOpts = {
+  componentStack: string | null | undefined;
+};

package/src/types/globals.ts

@@ -0,0 +1,19 @@
+// Ensure this is treated as a module.
+export {};
+
+declare global {
+  interface Window {
+    Zone?: any;
+  }
+
+  type ErrorLike = {
+    message: string;
+    stack?: string;
+
+    // to permit ['foo'] based access that doesn't break
+    // when pushed through the Closure compiler
+    [key: string]: number | string | null | undefined;
+  };
+
+  let __sdkVersion: string;
+}

package/src/types/options.ts

@@ -0,0 +1,56 @@
+import { AttributeValueType } from "../utils/otel";
+import { AnyValue } from "./otlp";
+import { Endpoint, Vars } from "../vars";
+
+export type InstrumentationName = "@dash0/navigation" | "@dash0/web-vitals" | "@dash0/error" | "@dash0/fetch";
+
+export type InitOptions = {
+  serviceName: string;
+  serviceVersion?: string;
+  environment?: string;
+  deploymentName?: string;
+  deploymentId?: string;
+
+  /**
+   * Additional attributes to include with transmitted signals
+   */
+  additionalSignalAttributes?: Record<string, AttributeValueType | AnyValue>;
+
+  /**
+   * OTLP endpoints to which the generated telemetry should be sent to.
+   */
+  endpoint: Endpoint | Endpoint[];
+
+  /**
+   * Which instrumentations to enable. Defaults to undefined, which means all instrumentations.
+   */
+  enabledInstrumentations?: InstrumentationName[];
+
+  /**
+   * The  session inactivity timeout. Session inactivity is the maximum
+   * allowed time to pass between two page loads before the session is considered
+   * to be expired. Also think of cache time-to-idle configuration options.
+   */
+  sessionInactivityTimeoutMillis?: number;
+
+  /**
+   * The default session termination timeout. Session termination is the maximum
+   * allowed time to pass since session start before the session is considered
+   * to be expired. Also think of cache time-to-live configuration options.
+   */
+  sessionTerminationTimeoutMillis?: number;
+} & Partial<
+  Pick<
+    Vars,
+    | "ignoreUrls"
+    | "ignoreErrorMessages"
+    | "wrapEventHandlers"
+    | "wrapTimers"
+    | "propagateTraceHeadersCorsURLs"
+    | "maxWaitForResourceTimingsMillis"
+    | "maxToleranceForResourceTimingsMillis"
+    | "headersToCapture"
+    | "urlAttributeScrubber"
+    | "pageViewInstrumentation"
+  >
+>;