@blueking/open-telemetry 0.0.1

package/src/browser.ts

@@ -0,0 +1,44 @@
+/*
+ * Tencent is pleased to support the open source community by making
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) available.
+ *
+ * Copyright (C) 2021 THL A29 Limited, a Tencent company.  All rights reserved.
+ *
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) is licensed under the MIT License.
+ *
+ * License for 蓝鲸智云PaaS平台 (BlueKing PaaS):
+ *
+ * ---------------------------------------------------
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+ * to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+ * the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+ * THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+ * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+import { createPlugin } from './core/plugin';
+import { createBkOT, initBkOT } from './core/sdk';
+
+export * from './index';
+
+const BkOpenTelemetry = {
+  createBkOT,
+  createPlugin,
+  initBkOT,
+};
+
+if (typeof window !== 'undefined') {
+  Object.assign(window, {
+    BkOpenTelemetry,
+  });
+}
+
+export { BkOpenTelemetry };

package/src/core/config.ts

@@ -0,0 +1,327 @@
+/*
+ * Tencent is pleased to support the open source community by making
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) available.
+ *
+ * Copyright (C) 2017-2025 Tencent.  All rights reserved.
+ *
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) is licensed under the MIT License.
+ *
+ * License for 蓝鲸智云PaaS平台 (BlueKing PaaS):
+ *
+ * ---------------------------------------------------
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+ * to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+ * the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+ * THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+ * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+import type { BkOTPlugin } from './plugin';
+import type { Attributes } from '@opentelemetry/api';
+
+export interface BkOTAttributesConfig {
+  custom?: () => Attributes;
+  error?: () => Attributes;
+  metric?: () => Attributes;
+  page?: () => Attributes;
+}
+
+export type BkOTAttributeValue = boolean | number | string;
+
+export interface BkOTBatchConfig {
+  exportTimeoutMillis?: number;
+  maxExportBatchSize?: number;
+  maxQueueSize?: number;
+  scheduledDelayMillis?: number;
+}
+
+export interface BkOTConfig {
+  attributes?: BkOTAttributesConfig;
+  autoStart?: boolean;
+  debug?: boolean;
+  enabled?: boolean;
+  endpoint?: string;
+  environment?: string;
+  headers?: Record<string, string>;
+  plugins?: BkOTPlugin[];
+  redact?: BkOTRedactConfig;
+  rum?: BkOTRumConfig;
+  sampleRate?: number;
+  spanBatch?: BkOTBatchConfig;
+  token?: string;
+}
+
+export interface BkOTCustomEventPayload {
+  attributes?: Attributes;
+  error?: Error;
+  name: string;
+}
+
+export interface BkOTHttpBodyConfig {
+  maxBodySize?: number;
+  redact?: (payload: BkOTHttpBodyRedactPayload) => string;
+}
+
+export interface BkOTHttpBodyRedactPayload {
+  body: string;
+  contentType?: string;
+  method: string;
+  status?: number;
+  truncated: boolean;
+  type: 'request' | 'response';
+  url: string;
+}
+
+export interface BkOTInstrumentationsConfig {
+  documentLoad?: boolean;
+  fetch?: boolean;
+  userInteraction?: boolean | { eventNames?: string[] };
+  xhr?: boolean;
+}
+
+export interface BkOTRedactConfig {
+  // 用于隐私脱敏：在所有 RUM 自定义插件 emit 之前过滤一次属性
+  attributes?: (attributes: Attributes) => Attributes;
+  // 用于隐私脱敏：所有上报到 attribute 的 URL 在写入前会经过此函数
+  url?: (url: string) => string;
+}
+
+export interface BkOTRumConfig extends BkOTInstrumentationsConfig {
+  cspViolation?: boolean;
+  device?: boolean | { storageKey?: string };
+  httpBody?: BkOTHttpBodyConfig | boolean;
+  pageView?: boolean;
+  routeTiming?: boolean;
+  websocket?: boolean;
+  webVitals?: boolean;
+  blankScreen?:
+    | {
+        checkDelay?: number;
+        // 自定义"页面已渲染"忽略选择器，命中即认为是 loading 占位、非空白
+        ignoreSelectors?: string[];
+        rootSelector?: string;
+        threshold?: number;
+      }
+    | boolean;
+  error?:
+    | {
+        // 同 hash 错误窗口内最多上报多少条，默认 5
+        maxPerWindow?: number;
+        // 节流窗口长度（ms），默认 60_000
+        windowMs?: number;
+      }
+    | boolean;
+  longTask?:
+    | {
+        // 任务时长阈值（ms），低于该值的 longtask 不上报，默认 50
+        threshold?: number;
+      }
+    | boolean;
+  session?:
+    | {
+        // 不活跃多久后视为新会话，默认 30 分钟
+        inactivityMs?: number;
+        storageKey?: string;
+      }
+    | boolean;
+}
+
+export interface NormalizedBkOTConfig extends Omit<
+  BkOTConfig,
+  'attributes' | 'autoStart' | 'debug' | 'enabled' | 'endpoint' | 'environment' | 'plugins' | 'redact' | 'token'
+> {
+  autoStart: boolean;
+  debug: boolean;
+  enabled: boolean;
+  endpoint: string;
+  environment: string;
+  logs: SignalExporterConfig;
+  metricIntervalMillis: number;
+  metrics: SignalExporterConfig;
+  plugins: BkOTPlugin[];
+  resourceAttributes: Attributes;
+  sampleRate: number;
+  traces: SignalExporterConfig;
+  getCustomAttributes: () => Attributes;
+  getErrorAttributes: () => Attributes;
+  getMetricAttributes: () => Attributes;
+  getPageAttributes: () => Attributes;
+  redactAttributes: (attributes: Attributes) => Attributes;
+  redactUrl: (url: string) => string;
+  instrumentations: Required<Pick<BkOTInstrumentationsConfig, 'documentLoad' | 'fetch' | 'xhr'>> & {
+    userInteraction: BkOTInstrumentationsConfig['userInteraction'];
+  };
+  rum: Omit<Required<BkOTRumConfig>, 'documentLoad' | 'fetch' | 'httpBody' | 'userInteraction' | 'xhr'> & {
+    httpBody: false | Required<BkOTHttpBodyConfig>;
+  };
+}
+
+export interface SignalExporterConfig {
+  concurrencyLimit?: number;
+  endpoint: string;
+  headers?: Record<string, string>;
+  timeoutMillis?: number;
+}
+
+const DEFAULT_OTLP_ENDPOINT = 'http://localhost:4318'; // 默认上报到本机 OTLP collector
+const DEFAULT_METRIC_INTERVAL_MILLIS = 10 * 1000; // 10s 上报一次
+
+const trimTrailingSlash = (value: string) => value.replace(/\/+$/, '');
+
+const resolveSignalEndpoint = (endpoint: string | undefined, signalPath: 'logs' | 'metrics' | 'traces') => {
+  const normalized = trimTrailingSlash(endpoint || DEFAULT_OTLP_ENDPOINT);
+  if (normalized.endsWith(`/v1/${signalPath}`)) {
+    return normalized;
+  }
+  if (normalized.endsWith('/v1')) {
+    return `${normalized}/${signalPath}`;
+  }
+  return `${normalized}/v1/${signalPath}`;
+};
+
+const resolveSignalConfig = (base: BkOTConfig, signalPath: 'logs' | 'metrics' | 'traces'): SignalExporterConfig => {
+  // token 只负责提供默认鉴权头；headers 保持显式配置优先，便于特殊场景覆盖。
+  const mergedHeaders =
+    base.token || base.headers
+      ? {
+          ...(base.token ? { Authorization: `Bearer ${base.token}` } : {}),
+          ...(base.headers ?? {}),
+        }
+      : undefined;
+
+  return {
+    endpoint: resolveSignalEndpoint(base.endpoint, signalPath),
+    headers: mergedHeaders,
+  };
+};
+
+const clampSampleRate = (sampleRate?: number) => {
+  if (typeof sampleRate !== 'number' || !Number.isFinite(sampleRate)) {
+    return 1;
+  }
+  return Math.max(0, Math.min(1, sampleRate));
+};
+
+const positiveNumber = (value: number | undefined, fallback: number) =>
+  typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+
+const nonNegativeNumber = (value: number | undefined, fallback: number) =>
+  typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : fallback;
+
+const boundedRatio = (value: number | undefined, fallback: number) => {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.max(0, Math.min(1, value));
+};
+
+const identityRedactHttpBody = (payload: BkOTHttpBodyRedactPayload) => payload.body;
+
+const normalizeHttpBodyConfig = (httpBody: BkOTRumConfig['httpBody']): false | Required<BkOTHttpBodyConfig> => {
+  if (!httpBody) {
+    return false;
+  }
+  if (typeof httpBody === 'boolean') {
+    return {
+      maxBodySize: 10 * 1024,
+      redact: identityRedactHttpBody,
+    };
+  }
+  return {
+    maxBodySize: positiveNumber(httpBody.maxBodySize, 10 * 1024),
+    redact: httpBody.redact ?? identityRedactHttpBody,
+  };
+};
+
+const normalizeRumConfig = (rum: BkOTConfig['rum']): NormalizedBkOTConfig['rum'] => ({
+  device: rum?.device ?? true,
+  httpBody: normalizeHttpBodyConfig(rum?.httpBody),
+  session:
+    typeof rum?.session === 'object'
+      ? {
+          ...rum.session,
+          inactivityMs: positiveNumber(rum.session.inactivityMs, 30 * 60 * 1000),
+        }
+      : (rum?.session ?? true),
+  pageView: rum?.pageView ?? true,
+  error:
+    typeof rum?.error === 'object'
+      ? {
+          ...rum.error,
+          maxPerWindow: positiveNumber(rum.error.maxPerWindow, 5),
+          windowMs: positiveNumber(rum.error.windowMs, 60_000),
+        }
+      : (rum?.error ?? true),
+  webVitals: rum?.webVitals ?? true,
+  blankScreen:
+    typeof rum?.blankScreen === 'object'
+      ? {
+          ...rum.blankScreen,
+          checkDelay: nonNegativeNumber(rum.blankScreen.checkDelay, 3000),
+          threshold: boundedRatio(rum.blankScreen.threshold, 0.8),
+        }
+      : (rum?.blankScreen ?? true),
+  websocket: rum?.websocket ?? true,
+  longTask:
+    typeof rum?.longTask === 'object'
+      ? {
+          ...rum.longTask,
+          threshold: nonNegativeNumber(rum.longTask.threshold, 50),
+        }
+      : (rum?.longTask ?? false),
+  cspViolation: rum?.cspViolation ?? false,
+  routeTiming: rum?.routeTiming ?? false,
+});
+
+const identityRedactAttributes = (attributes: Attributes) => attributes;
+const identityRedactUrl = (url: string) => url;
+
+export const normalizeConfig = (config: BkOTConfig): NormalizedBkOTConfig => {
+  const resourceAttributes: Attributes = {
+    'deployment.environment.name': config.environment ?? 'production',
+    'rum.provider': 'blueking',
+    'telemetry.sdk.language': 'webjs',
+  };
+
+  return {
+    ...config,
+    debug: config.debug ?? false,
+    enabled: config.enabled ?? true,
+    environment: config.environment ?? 'production',
+    endpoint: trimTrailingSlash(config.endpoint || DEFAULT_OTLP_ENDPOINT),
+    traces: resolveSignalConfig(config, 'traces'),
+    metrics: resolveSignalConfig(config, 'metrics'),
+    logs: resolveSignalConfig(config, 'logs'),
+    sampleRate: clampSampleRate(config.sampleRate),
+    resourceAttributes,
+    metricIntervalMillis: DEFAULT_METRIC_INTERVAL_MILLIS,
+    instrumentations: {
+      documentLoad: config.rum?.documentLoad ?? true,
+      fetch: config.rum?.fetch ?? true,
+      xhr: config.rum?.xhr ?? true,
+      userInteraction: config.rum?.userInteraction ?? true,
+    },
+    rum: normalizeRumConfig(config.rum),
+    plugins: config.plugins ?? [],
+    autoStart: config.autoStart ?? true,
+    getPageAttributes:
+      config.attributes?.page ??
+      (() => ({
+        'rum.page.host': typeof window === 'undefined' ? '' : window.location.host,
+        'rum.page.path': typeof window === 'undefined' ? '' : window.location.pathname,
+      })),
+    getMetricAttributes: config.attributes?.metric ?? (() => ({})),
+    getErrorAttributes: config.attributes?.error ?? (() => ({})),
+    getCustomAttributes: config.attributes?.custom ?? (() => ({})),
+    redactAttributes: config.redact?.attributes ?? identityRedactAttributes,
+    redactUrl: config.redact?.url ?? identityRedactUrl,
+  };
+};

package/src/core/plugin.ts

@@ -0,0 +1,97 @@
+/*
+ * Tencent is pleased to support the open source community by making
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) available.
+ *
+ * Copyright (C) 2017-2025 Tencent.  All rights reserved.
+ *
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) is licensed under the MIT License.
+ *
+ * License for 蓝鲸智云PaaS平台 (BlueKing PaaS):
+ *
+ * ---------------------------------------------------
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+ * to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+ * the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+ * THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+ * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+import type { NormalizedBkOTConfig } from './config';
+import type { Attributes, Meter, Span, Tracer } from '@opentelemetry/api';
+import type { Logger, LogRecord } from '@opentelemetry/api-logs';
+
+export interface BkOTPlugin {
+  enabled?: ((config: NormalizedBkOTConfig) => boolean) | boolean;
+  name: string;
+  flush?: () => Promise<void> | void;
+  init: (context: BkOTRuntimeContext) => Promise<void> | void;
+  shutdown?: () => Promise<void> | void;
+}
+
+export interface BkOTRuntimeContext {
+  config: NormalizedBkOTConfig;
+  logger: Logger;
+  meter: Meter;
+  tracer: Tracer;
+  /** 对外提供的属性脱敏入口，所有插件在 emit 前都应过一次 */
+  applyRedact: (attributes: Attributes) => Attributes;
+  /** 包装 logger.emit，自动应用 redact 与 runtime attributes */
+  emitLog: (record: LogRecord) => void;
+  getRuntimeAttributes: () => Attributes;
+  setRuntimeAttributes: (attributes: Attributes) => void;
+  startSpan: (name: string, attributes?: Attributes) => Span;
+}
+
+export const isPluginEnabled = (plugin: BkOTPlugin, config: NormalizedBkOTConfig) => {
+  if (typeof plugin.enabled === 'function') {
+    return plugin.enabled(config);
+  }
+  return plugin.enabled !== false;
+};
+
+export const createPlugin = (plugin: BkOTPlugin) => plugin;
+
+export class PluginManager {
+  private readonly plugins: BkOTPlugin[];
+  private startedPlugins: BkOTPlugin[] = [];
+
+  public constructor(plugins: BkOTPlugin[]) {
+    this.plugins = plugins;
+  }
+
+  public async flush() {
+    // 并行 flush，避免单个慢插件拖累整体
+    await Promise.all(this.startedPlugins.map(plugin => Promise.resolve().then(() => plugin.flush?.())));
+  }
+
+  public async shutdown() {
+    const plugins = [...this.startedPlugins].reverse();
+    for (const plugin of plugins) {
+      await plugin.shutdown?.();
+    }
+    this.startedPlugins = [];
+  }
+
+  public async start(context: BkOTRuntimeContext) {
+    try {
+      for (const plugin of this.plugins) {
+        if (!isPluginEnabled(plugin, context.config)) {
+          continue;
+        }
+        await plugin.init(context);
+        this.startedPlugins.push(plugin);
+      }
+    } catch (error) {
+      await this.shutdown();
+      throw error;
+    }
+  }
+}

package/src/core/processor.ts

@@ -0,0 +1,74 @@
+/*
+ * Tencent is pleased to support the open source community by making
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) available.
+ *
+ * Copyright (C) 2017-2025 Tencent.  All rights reserved.
+ *
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) is licensed under the MIT License.
+ *
+ * License for 蓝鲸智云PaaS平台 (BlueKing PaaS):
+ *
+ * ---------------------------------------------------
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+ * to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+ * the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+ * THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+ * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+import { isBkOTEndpoint } from './url';
+
+import type { NormalizedBkOTConfig } from './config';
+import type { Context } from '@opentelemetry/api';
+import type { ReadableSpan, Span, SpanProcessor } from '@opentelemetry/sdk-trace-base';
+
+const SELF_TELEMETRY_URL_KEYS = ['http.url', 'url.full'];
+
+const getSpanUrl = (span: ReadableSpan): string | undefined => {
+  for (const key of SELF_TELEMETRY_URL_KEYS) {
+    const value = span.attributes?.[key];
+    if (typeof value === 'string') {
+      return value;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * 包装 SpanProcessor，在 onEnd 阶段过滤指向自身上报 endpoint 的 span，
+ * 兜底防止 official fetch/xhr 拦截器对 OTel 自身请求产生回环 span。
+ */
+export class FilteringSpanProcessor implements SpanProcessor {
+  public constructor(
+    private readonly inner: SpanProcessor,
+    private readonly config: NormalizedBkOTConfig,
+  ) {}
+
+  public forceFlush(): Promise<void> {
+    return this.inner.forceFlush();
+  }
+
+  public onEnd(span: ReadableSpan): void {
+    const url = getSpanUrl(span);
+    if (url && isBkOTEndpoint(this.config, url)) {
+      return;
+    }
+    this.inner.onEnd(span);
+  }
+
+  public onStart(span: Span, parentContext: Context): void {
+    this.inner.onStart(span, parentContext);
+  }
+
+  public shutdown(): Promise<void> {
+    return this.inner.shutdown();
+  }
+}

package/src/core/route-observer.ts

@@ -0,0 +1,128 @@
+/*
+ * Tencent is pleased to support the open source community by making
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) available.
+ *
+ * Copyright (C) 2017-2025 Tencent.  All rights reserved.
+ *
+ * 蓝鲸智云PaaS平台 (BlueKing PaaS) is licensed under the MIT License.
+ *
+ * License for 蓝鲸智云PaaS平台 (BlueKing PaaS):
+ *
+ * ---------------------------------------------------
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+ * to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+ * the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+ * THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+ * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+export interface RouteChangeEvent {
+  fromUrl: string;
+  source: RouteChangeSource;
+  toUrl: string;
+}
+
+export type RouteChangeSource = 'hashchange' | 'popstate' | 'pushState' | 'replaceState';
+
+type RouteChangeHandler = (event: RouteChangeEvent) => void;
+
+const subscribers = new Set<RouteChangeHandler>();
+
+let lastUrl = '';
+let originalPushState: typeof history.pushState | undefined;
+let originalReplaceState: typeof history.replaceState | undefined;
+let patched = false;
+
+const getCurrentUrl = () => (typeof location === 'undefined' ? '' : location.href);
+
+const emitRouteChange = (source: RouteChangeSource, fromUrl: string) => {
+  const toUrl = getCurrentUrl();
+  lastUrl = toUrl;
+  const event: RouteChangeEvent = { fromUrl, source, toUrl };
+
+  for (const subscriber of Array.from(subscribers)) {
+    subscriber(event);
+  }
+};
+
+const onPopState = () => {
+  emitRouteChange('popstate', lastUrl || getCurrentUrl());
+};
+
+const onHashChange = () => {
+  emitRouteChange('hashchange', lastUrl || getCurrentUrl());
+};
+
+const patchHistory = () => {
+  if (patched || typeof window === 'undefined' || typeof history === 'undefined') {
+    return;
+  }
+
+  patched = true;
+  lastUrl = getCurrentUrl();
+  originalPushState = history.pushState;
+  originalReplaceState = history.replaceState;
+
+  history.pushState = function patchedPushState(this: History, data: any, title: string, url?: null | string | URL) {
+    const fromUrl = lastUrl || getCurrentUrl();
+    const result = originalPushState?.apply(this, [data, title, url]);
+    emitRouteChange('pushState', fromUrl);
+    return result;
+  };
+  history.replaceState = function patchedReplaceState(
+    this: History,
+    data: any,
+    title: string,
+    url?: null | string | URL,
+  ) {
+    const fromUrl = lastUrl || getCurrentUrl();
+    const result = originalReplaceState?.apply(this, [data, title, url]);
+    emitRouteChange('replaceState', fromUrl);
+    return result;
+  };
+  window.addEventListener('popstate', onPopState);
+  window.addEventListener('hashchange', onHashChange);
+};
+
+const restoreHistory = () => {
+  if (!patched || typeof window === 'undefined' || typeof history === 'undefined') {
+    return;
+  }
+
+  if (originalPushState) {
+    history.pushState = originalPushState;
+  }
+  if (originalReplaceState) {
+    history.replaceState = originalReplaceState;
+  }
+  window.removeEventListener('popstate', onPopState);
+  window.removeEventListener('hashchange', onHashChange);
+  originalPushState = undefined;
+  originalReplaceState = undefined;
+  patched = false;
+  lastUrl = '';
+};
+
+export const subscribeRouteChange = (handler: RouteChangeHandler) => {
+  if (typeof window === 'undefined' || typeof history === 'undefined') {
+    return () => {};
+  }
+
+  patchHistory();
+  subscribers.add(handler);
+
+  return () => {
+    subscribers.delete(handler);
+    if (subscribers.size === 0) {
+      restoreHistory();
+    }
+  };
+};