fix(replay): Set worker Blob MIME type and clarify load-failure errors

The compression worker is created from a Blob URL. The Blob was constructed
without a MIME type, so it defaulted to an empty type. Safari (especially on
iOS) validates the MIME type before executing a Blob as a classic Worker and
silently rejects it, firing a bare `error` event with no message — which the
SDK surfaced as the misleading "Unknown error ... CSP policy restrictions"
message. Tagging the Blob `text/javascript` fixes the Safari load failure.

The same "Unknown error" was also captured across Chrome/Edge/Firefox, where
the MIME type is irrelevant: those come from the worker fetch being aborted
during page navigation/teardown. `WorkerHandler` now distinguishes an aborted
load (document hidden/unloading) from a genuine failure, so the captured
signal is accurate instead of always blaming CSP/network.

Author: billyvg

packages/replay-internal/src/eventBuffer/WorkerHandler.ts

@@ -1,7 +1,37 @@
+import { WINDOW } from '../constants';
 import { DEBUG_BUILD } from '../debug-build';
 import type { WorkerRequest, WorkerResponse } from '../types';
 import { debug } from '../util/logger';
 
+/**
+ * Build the error thrown when the compression worker fails to load.
+ *
+ * The worker's `error` event is a bare `Event` (not an `ErrorEvent`) when the
+ * script fails to *load* — it carries no `message`, so we can't read a cause
+ * off it. Rather than always blaming CSP/network, we check whether the document
+ * is no longer visible: when the page is navigating away or backgrounded, an
+ * in-flight worker fetch is aborted and this error is expected teardown noise,
+ * not a real load failure. Distinguishing the two keeps the captured signal
+ * accurate across browsers (this fires on Safari, Chrome, Firefox alike).
+ */
+function _getWorkerLoadError(error: unknown): Error {
+  if (error instanceof ErrorEvent && error.message) {
+    return new Error(`Failed to load Replay compression worker: ${error.message}`);
+  }
+
+  // `document` may be undefined in non-browser worker/SSR contexts.
+  const isDocumentHidden = WINDOW.document && WINDOW.document.visibilityState !== 'visible';
+  if (isDocumentHidden) {
+    return new Error(
+      'Failed to load Replay compression worker: the page was hidden or unloaded before the worker loaded.',
+    );
+  }
+
+  return new Error(
+    'Failed to load Replay compression worker: Unknown error. This can happen due to CSP policy restrictions, network issues, or the worker script failing to load.',
+  );
+}
+
 interface PendingRequest {
   method: WorkerRequest['method'];
   resolve: (value: unknown) => void;
@@ -56,11 +86,7 @@ export class WorkerHandler {
         'error',
         error => {
           DEBUG_BUILD && debug.warn('Failed to load Replay compression worker', error);
-          reject(
-            new Error(
-              `Failed to load Replay compression worker: ${error instanceof ErrorEvent && error.message ? error.message : 'Unknown error. This can happen due to CSP policy restrictions, network issues, or the worker script failing to load.'}`,
-            ),
-          );
+          reject(_getWorkerLoadError(error));
         },
         { once: true },
       );

packages/replay-internal/test/unit/eventBuffer/WorkerHandler.test.ts

@@ -2,7 +2,7 @@
  * @vitest-environment jsdom
  */
 
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it } from 'vitest';
 import { WorkerHandler } from '../../../src/eventBuffer/WorkerHandler';
 import type { WorkerResponse } from '../../../src/types';
 
@@ -62,6 +62,16 @@ class MockWorker implements Pick<Worker, 'addEventListener' | 'removeEventListen
     this._dispatch('message', { data: response } as MessageEvent);
   }
 
+  /** Dispatch the worker's readiness message (consumed by `ensureReady`). */
+  public dispatchReady(success = true): void {
+    this._dispatch('message', { data: { success } } as MessageEvent);
+  }
+
+  /** Dispatch an `error` event, as fired when the worker script fails to load. */
+  public dispatchError(event: Event): void {
+    this._dispatch('error', event as MessageEvent);
+  }
+
   public get pendingCount(): number {
     return this._pendingRequests.length;
   }
@@ -171,4 +181,56 @@ describe('Unit | eventBuffer | WorkerHandler', () => {
     expect(worker.terminated).toBe(true);
     expect(worker.listenerCount).toBe(0);
   });
+
+  describe('ensureReady', () => {
+    const originalVisibility = Object.getOwnPropertyDescriptor(Document.prototype, 'visibilityState');
+
+    const setVisibility = (state: DocumentVisibilityState): void => {
+      Object.defineProperty(document, 'visibilityState', { configurable: true, get: () => state });
+    };
+
+    afterEach(() => {
+      if (originalVisibility) {
+        Object.defineProperty(Document.prototype, 'visibilityState', originalVisibility);
+      }
+    });
+
+    it('resolves once the worker reports readiness', async () => {
+      const { worker, handler } = makeHandler();
+      const ready = handler.ensureReady();
+      worker.dispatchReady();
+      await expect(ready).resolves.toBeUndefined();
+    });
+
+    it('caches the ready promise so listeners are only attached once', () => {
+      const { handler } = makeHandler();
+      expect(handler.ensureReady()).toBe(handler.ensureReady());
+    });
+
+    it("uses an ErrorEvent's message when one is present", async () => {
+      const { worker, handler } = makeHandler();
+      const ready = handler.ensureReady();
+      worker.dispatchError(new ErrorEvent('error', { message: 'CSP blocked worker-src' }));
+      await expect(ready).rejects.toThrow('Failed to load Replay compression worker: CSP blocked worker-src');
+    });
+
+    it('attributes a bare error event to teardown when the document is hidden', async () => {
+      setVisibility('hidden');
+      const { worker, handler } = makeHandler();
+      const ready = handler.ensureReady();
+      // A load failure fires a plain Event with no message (Safari/Chrome/Firefox alike).
+      worker.dispatchError(new Event('error'));
+      await expect(ready).rejects.toThrow(
+        'Failed to load Replay compression worker: the page was hidden or unloaded before the worker loaded.',
+      );
+    });
+
+    it('falls back to the generic message for a bare error event while visible', async () => {
+      setVisibility('visible');
+      const { worker, handler } = makeHandler();
+      const ready = handler.ensureReady();
+      worker.dispatchError(new Event('error'));
+      await expect(ready).rejects.toThrow(/Unknown error\. This can happen due to CSP policy restrictions/);
+    });
+  });
 });

packages/replay-worker/src/index.ts

@@ -4,6 +4,12 @@ import workerString from './worker';
  * Get the URL for a web worker.
  */
 export function getWorkerURL(): string {
-  const workerBlob = new Blob([workerString]);
+  // Safari (particularly on iOS) validates the MIME type of a Blob before it
+  // will execute it as a classic Worker script. A Blob created without an
+  // explicit `type` defaults to an empty string, which WebKit may reject,
+  // firing a bare `error` event with no message. Blink/Gecko are lenient here,
+  // so this only manifests on Safari. Set an explicit JavaScript MIME type so
+  // the worker loads across browsers.
+  const workerBlob = new Blob([workerString], { type: 'text/javascript' });
   return URL.createObjectURL(workerBlob);
 }

packages/replay-worker/test/unit/getWorkerURL.test.ts

@@ -0,0 +1,25 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { getWorkerURL } from '../../src';
+
+describe('getWorkerURL', () => {
+  // Safari (esp. iOS) rejects executing a Blob worker without a JavaScript MIME
+  // type, firing a bare `error` event. The Blob must be tagged `text/javascript`
+  // so the worker loads across browsers. See WorkerHandler for the load-error path.
+  it('creates the worker Blob with a JavaScript MIME type', () => {
+    // jsdom does not implement `URL.createObjectURL`, so stub it and capture the Blob.
+    const createObjectURL = vi.fn<(blob: Blob) => string>().mockReturnValue('blob:mock');
+    URL.createObjectURL = createObjectURL as unknown as typeof URL.createObjectURL;
+
+    const url = getWorkerURL();
+
+    expect(url).toBe('blob:mock');
+    expect(createObjectURL).toHaveBeenCalledTimes(1);
+    const blob = createObjectURL.mock.calls[0]![0];
+    expect(blob).toBeInstanceOf(Blob);
+    expect(blob.type).toBe('text/javascript');
+  });
+});