fix(transport): track cumulative inflight keepalive bytes and count

overbalance · overbalance · commit 04bb42037bc0 · 2026-02-25T19:25:04.000-06:00
diff --git a/packages/web-sdk/src/transport/FetchTransport/FetchTransport.test.ts b/packages/web-sdk/src/transport/FetchTransport/FetchTransport.test.ts
@@ -0,0 +1,217 @@
+import * as chai from 'chai';
+import sinonChai from 'sinon-chai';
+import {
+  fakeFetchGetKeepalive,
+  fakeFetchInstall,
+  fakeFetchRespondWith,
+  fakeFetchRestore,
+} from '../../../tests/utils/index.ts';
+import { _resetKeepaliveTracking, FetchTransport } from './FetchTransport.ts';
+
+chai.use(sinonChai);
+const { expect } = chai;
+
+const makeTransport = (
+  overrides?: Partial<ConstructorParameters<typeof FetchTransport>[0]>,
+) =>
+  new FetchTransport({
+    url: 'http://example.com',
+    headers: {},
+    compression: 'none',
+    ...overrides,
+  });
+
+const smallPayload = new TextEncoder().encode('{"small": true}');
+const largePayload = new Uint8Array(49153); // 1 byte over the 48KiB budget
+
+interface Deferred {
+  promise: Promise<Response>;
+  resolve: (value: Response) => void;
+  reject: (reason: Error) => void;
+}
+
+function createDeferred(): Deferred {
+  let resolve!: (value: Response) => void;
+  let reject!: (reason: Error) => void;
+  const promise = new Promise<Response>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+describe('FetchTransport', () => {
+  beforeEach(() => {
+    _resetKeepaliveTracking();
+    fakeFetchInstall();
+  });
+
+  afterEach(() => {
+    fakeFetchRestore();
+  });
+
+  describe('keepalive budget', () => {
+    it('should set keepalive to true for payloads within the budget', async () => {
+      fakeFetchRespondWith('ok', { status: 200 });
+      const transport = makeTransport();
+
+      await transport.send(smallPayload, 1000);
+
+      expect(fakeFetchGetKeepalive()).to.equal(true);
+    });
+
+    it('should set keepalive to false for payloads exceeding the budget', async () => {
+      fakeFetchRespondWith('ok', { status: 200 });
+      const transport = makeTransport();
+
+      await transport.send(largePayload, 1000);
+
+      expect(fakeFetchGetKeepalive()).to.equal(false);
+    });
+  });
+
+  describe('keepalive cumulative tracking', () => {
+    it('should disable keepalive when cumulative bytes exceed the budget', async () => {
+      const deferred = createDeferred();
+      fakeFetchRestore();
+      const stub = fakeFetchInstall();
+      stub.onCall(0).returns(deferred.promise);
+      stub.onCall(1).resolves(new Response('ok', { status: 200 }));
+
+      const transport = makeTransport();
+
+      // 30KiB payload — fits individually but two exceed the 48KiB budget
+      const payload30k = new Uint8Array(30 * 1024);
+
+      // Start first request (stays inflight)
+      const first = transport.send(payload30k, 5000);
+      // Allow microtask to run so fetch is called
+      await Promise.resolve();
+
+      expect(fakeFetchGetKeepalive(0)).to.equal(true);
+
+      // Second request should exceed cumulative budget
+      await transport.send(payload30k, 5000);
+
+      expect(fakeFetchGetKeepalive(1)).to.equal(false);
+
+      // Clean up
+      deferred.resolve(new Response('ok', { status: 200 }));
+      await first;
+    });
+
+    it('should disable keepalive when concurrent count reaches 9', async () => {
+      const deferreds: Deferred[] = [];
+      fakeFetchRestore();
+      const stub = fakeFetchInstall();
+
+      for (let i = 0; i < 9; i++) {
+        const d = createDeferred();
+        deferreds.push(d);
+        stub.onCall(i).returns(d.promise);
+      }
+      stub.onCall(9).resolves(new Response('ok', { status: 200 }));
+
+      const transport = makeTransport();
+      const tinyPayload = new Uint8Array(1);
+
+      // Start 9 concurrent requests
+      const pending = [];
+      for (let i = 0; i < 9; i++) {
+        pending.push(transport.send(tinyPayload, 5000));
+        await Promise.resolve();
+      }
+
+      for (let i = 0; i < 9; i++) {
+        expect(fakeFetchGetKeepalive(i)).to.equal(true);
+      }
+
+      // 10th request should exceed concurrent limit
+      await transport.send(tinyPayload, 5000);
+
+      expect(fakeFetchGetKeepalive(9)).to.equal(false);
+
+      // Clean up
+      for (const d of deferreds) {
+        d.resolve(new Response('ok', { status: 200 }));
+      }
+      await Promise.all(pending);
+    });
+
+    it('should decrement counters after request completes', async () => {
+      const deferred = createDeferred();
+      fakeFetchRestore();
+      const stub = fakeFetchInstall();
+      stub.onCall(0).returns(deferred.promise);
+      stub.onCall(1).resolves(new Response('ok', { status: 200 }));
+      stub.onCall(2).resolves(new Response('ok', { status: 200 }));
+
+      const transport = makeTransport();
+      const payload30k = new Uint8Array(30 * 1024);
+
+      // First request stays inflight
+      const first = transport.send(payload30k, 5000);
+      await Promise.resolve();
+
+      // Second request exceeds cumulative budget
+      await transport.send(payload30k, 5000);
+
+      expect(fakeFetchGetKeepalive(1)).to.equal(false);
+
+      // Resolve first request to free up budget
+      deferred.resolve(new Response('ok', { status: 200 }));
+      await first;
+
+      // Third request should fit now
+      await transport.send(payload30k, 5000);
+
+      expect(fakeFetchGetKeepalive(2)).to.equal(true);
+    });
+
+    it('should decrement counters after request fails', async () => {
+      const deferred = createDeferred();
+      fakeFetchRestore();
+      const stub = fakeFetchInstall();
+      stub.onCall(0).returns(deferred.promise);
+      stub.onCall(1).resolves(new Response('ok', { status: 200 }));
+      stub.onCall(2).resolves(new Response('ok', { status: 200 }));
+
+      const transport = makeTransport();
+      const payload30k = new Uint8Array(30 * 1024);
+
+      // First request stays inflight
+      const first = transport.send(payload30k, 5000);
+      await Promise.resolve();
+
+      // Second request exceeds cumulative budget
+      await transport.send(payload30k, 5000);
+
+      expect(fakeFetchGetKeepalive(1)).to.equal(false);
+
+      // Reject first request to free up budget
+      deferred.reject(new TypeError('Failed to fetch'));
+      await first;
+
+      // Third request should fit now
+      await transport.send(payload30k, 5000);
+
+      expect(fakeFetchGetKeepalive(2)).to.equal(true);
+    });
+  });
+
+  describe('network errors', () => {
+    it('should return failure when fetch throws', async () => {
+      // Restore then re-install to reconfigure the stub to reject
+      fakeFetchRestore();
+      fakeFetchInstall().rejects(new TypeError('Failed to fetch'));
+
+      const transport = makeTransport();
+      const result = await transport.send(smallPayload, 1000);
+
+      expect(result).to.deep.equal({
+        status: 'failure',
+        error: new TypeError('Failed to fetch'),
+      });
+    });
+  });
+});
diff --git a/packages/web-sdk/src/transport/FetchTransport/FetchTransport.ts b/packages/web-sdk/src/transport/FetchTransport/FetchTransport.ts
@@ -4,11 +4,28 @@ import type {
 } from '@opentelemetry/otlp-exporter-base';
 import type { FetchRequestParameters } from './types.ts';
 
+// The fetch spec enforces a 64KiB limit on the sum of all inflight keepalive
+// request bodies per fetch group. We use a conservative budget to leave room
+// for third-party scripts that may also be using keepalive or sendBeacon.
+// https://github.com/whatwg/fetch/issues/679
+const KEEPALIVE_BYTE_BUDGET = 49152; // 48KiB
+
+// Chrome enforces a 9-request concurrent keepalive limit per renderer process.
+const MAX_KEEPALIVE_REQUESTS = 9;
+
+let inflightKeepaliveBytes = 0;
+let inflightKeepaliveCount = 0;
+
+/** @internal for testing only */
+export function _resetKeepaliveTracking(): void {
+  inflightKeepaliveBytes = 0;
+  inflightKeepaliveCount = 0;
+}
+
 export class FetchTransport implements IExporterTransport {
   public constructor(private readonly _config: FetchRequestParameters) {}
 
-  // _compressRequest compresses the data using the gzip algorithm.
-  // Embrace Data endpoints require the data to be compressed.
+  // Embrace endpoints require data to be encoded with gzip
   private static async _compressRequest(
     data: Uint8Array<ArrayBuffer>,
   ): Promise<Uint8Array<ArrayBuffer>> {
@@ -69,7 +86,6 @@ export class FetchTransport implements IExporterTransport {
 
     if (this._config.compression === 'gzip') {
       request = await FetchTransport._compressRequest(data);
-
       headers['Content-Encoding'] = 'gzip';
       headers['Content-Length'] = request.length.toString();
     }
@@ -89,10 +105,20 @@ export class FetchTransport implements IExporterTransport {
       }, timeoutMillis);
     }
 
+    const wouldExceedBytes =
+      inflightKeepaliveBytes + request.byteLength > KEEPALIVE_BYTE_BUDGET;
+    const wouldExceedCount = inflightKeepaliveCount >= MAX_KEEPALIVE_REQUESTS;
+    const keepalive = !wouldExceedBytes && !wouldExceedCount;
+
+    if (keepalive) {
+      inflightKeepaliveBytes += request.byteLength;
+      inflightKeepaliveCount++;
+    }
+
     try {
       const response = await fetch(this._config.url, {
         method: 'POST',
-        keepalive: true,
+        keepalive,
         headers,
         body: request,
         signal,
@@ -115,6 +141,10 @@ export class FetchTransport implements IExporterTransport {
       if (timeoutId !== undefined) {
         clearTimeout(timeoutId);
       }
+      if (keepalive) {
+        inflightKeepaliveBytes -= request.byteLength;
+        inflightKeepaliveCount--;
+      }
     }
   }
 }
diff --git a/packages/web-sdk/tests/utils/fakeFetch.ts b/packages/web-sdk/tests/utils/fakeFetch.ts
@@ -73,5 +73,8 @@ export const fakeFetchRespondWith = (
   options?: ResponseInit,
 ) => fetchStub?.callsFake(() => Promise.resolve(new Response(data, options)));
 
+export const fakeFetchGetKeepalive = (callNumber = 0) =>
+  fakeFetchGetOptions(callNumber)?.keepalive;
+
 export const fakeFetchWasCalled = (callNumber = 0) =>
   !!fetchStub?.getCall(callNumber);
diff --git a/packages/web-sdk/tests/utils/index.ts b/packages/web-sdk/tests/utils/index.ts
@@ -9,6 +9,7 @@ export { FakeLogRecordProcessor } from './FakeLogRecordProcessor.ts';
 export { FakeSpanProcessor } from './FakeSpanProcessor.ts';
 export {
   fakeFetchGetBody,
+  fakeFetchGetKeepalive,
   fakeFetchGetMethod,
   fakeFetchGetOptions,
   fakeFetchGetRequestHeaders,
