feat(analytics-browser): enable fetch keepalive by default to survive page navigation

[Mercy811]

Summary

Linear: SDKW-14

This PR adds a new capability to the browser SDK: the default fetch transport now sends uploads with keepalive: true, so in-flight event requests can complete even when the page is navigating away (redirects, link clicks, tab close).

Previously, delivering events at navigation time meant opting into transport: 'beacon' (navigator.sendBeacon). That works, but sendBeacon is limited: POST-only, no custom headers, no gzip (Content-Encoding), no access to the server response, and a hard 64 KiB cap. fetch with keepalive gives the same "survives navigation" behavior on the default transport while keeping everything we already rely on — gzip compression, custom headers, response handling, and the existing retry path. In short, customers no longer have to trade away those features to get navigation-time delivery.

What changed

• packages/analytics-browser/src/transports/fetch.ts
  • New exported constant KEEPALIVE_MAX_BODY_SIZE_BYTES = 16 * 1024.
  • Set keepalive when the outgoing body is within the cap. Size is measured with ArrayBuffer.byteLength for the gzip-compressed body, and the cheap JSON string length as a rough estimate for the uncompressed body (no per-request Blob/TextEncoder allocation).
• Tests added/updated for the enabled (small body) and disabled (oversized body) paths, including the compressed-body path.

Why a 16 KB cap?

keepalive comes with a hard, browser-enforced budget, and opting an oversized request into it is worse than leaving it off — the browser rejects the request outright instead of sending it. The cap is a graceful fallback: bodies within it get navigation survival; bodies above it send as a normal fetch (no size limit, just no survival).

The limit is normative in the Fetch spec. WHATWG Fetch Standard, "HTTP-network-or-cache fetch":

If the sum of contentLength and inflightKeepaliveBytes is greater than 64 kibibytes, then return a network error.

Source: https://fetch.spec.whatwg.org/#http-network-or-cache-fetch

Three things drive the 16 KB choice:

1. It's a network error, not a silent downgrade. A plain fetch() has no body-size limit; the moment you add keepalive: true, a body over budget makes the browser reject the request entirely. So we only opt a request into keepalive when its body fits.

2. The 64 KiB budget is shared, not per-request. inflightKeepaliveBytes is the combined total of all in-flight keepalive requests in the document — our analytics flushes, session-replay uploads (which already use keepalive), and any keepalive/sendBeacon traffic from the customer's own code. Headers count toward it too. A cap well below the full budget leaves headroom and reduces contention-induced rejections.

3. We gate on string length, which can undercount UTF-8 bytes. To avoid allocating a Blob/TextEncoder on every send, the uncompressed path uses body.length (UTF-16 code units) as a rough proxy for byte size — mirroring the existing gzip threshold (bodyString.length >= MIN_GZIP_UPLOAD_BODY_SIZE_BYTES). A code unit expands to at most 3 UTF-8 bytes (a surrogate pair is 2 units → 4 bytes, i.e. 2/unit), so using 64 KiB / 4 = 16 KB conservatively keeps even a fully multi-byte payload within the real budget.

For reference, Sentry adopted keepalive-by-default and added in-flight queue accounting after early issues with >64 KB requests (sentry-javascript#7553, #2548), and session-replay-browser already uses keepalive in this repo (commit fa5f84a).

Real-world payload sizes

In practice, event upload payloads are tiny relative to the 16 KB cap because the body is gzip-compressed. Observed request payload size is ~0.2 KB whether the batch contains a few events (e.g. 3–4) or many (e.g. 30) — so virtually all real traffic stays well under the cap and benefits from keepalive.

Behavior & blast radius

• Bodies within the cap (effectively all real, gzipped traffic) now survive page navigation.
• Bodies over the cap send exactly as they do today: a plain fetch with no size limit, no navigation survival.
• In-session, if a keepalive request is ever rejected on the shared budget, it falls into the destination retry path (catch → handleOtherResponse → re-schedule), bounded by flushMaxRetries — so the outcome is delay, not loss.
• Browser coverage: keepalive is Baseline Newly available (Firefox 133, Nov 2024; Chromium/Safari since ~2019). On browsers without support the option is silently ignored — no error, the request just behaves as a normal fetch.

Test plan

• pnpm --filter @amplitude/analytics-browser test -- test/transport/fetch.test.ts → 10/10 pass.
  • keepalive enabled for bodies ≤ cap; disabled for oversized uncompressed and oversized compressed bodies.
  • Existing header/gzip assertions updated to include keepalive.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes default upload behavior on every browser fetch and interacts with the shared 64 KiB keepalive budget; oversized keepalive requests fail at the network layer, though in-session retries should limit data loss.

Overview
Browser FetchTransport now sets keepalive: true on POST uploads when the outgoing body is within a 32 KiB cap (KEEPALIVE_MAX_BODY_SIZE_BYTES), so typical event batches can finish after redirects or navigation instead of being cancelled.

Sizing uses ArrayBuffer.byteLength for gzip bodies and JSON string length as a cheap upper bound for uncompressed payloads (no per-request Blob). Bodies above the cap omit keepalive and behave like today’s plain fetch.

Tests assert keepalive on small/uncompressed and small/compressed requests, and keepalive: false for oversized JSON and mocked oversized gzip output.

^{Reviewed by Cursor Bugbot for commit c18000f. Configure here.}

[linear-code]

SDKW-14

[github-actions]

size-limit report 📦

Path	Size
packages/analytics-browser/lib/scripts/amplitude-min.js.gz	58.34 KB (+0.06% 🔺)
packages/session-replay-browser/lib/scripts/session-replay-browser-min.js.gz	131.96 KB (0%)
packages/unified/lib/scripts/amplitude-min.umd.js.gz	208.98 KB (+0.02% 🔺)

[Mercy811]

Addressed review round 2:

• S1 (decouple compressed-body test): done — the over-budget compressed test now mocks compressToGzipArrayBuffer/isCompressionStreamAvailable directly rather than intercepting Response, so it no longer couples to the helper's internals.

Not changing, with reasoning:

• S2 (try/finally around global cleanup): leaving as-is. The manual set/delete of CompressionStream/Response/Blob.prototype.stream mirrors the existing gzip tests in this file; converting to beforeEach/afterEach or try/finally would be a broader refactor of pre-existing tests, out of scope for this PR. (The new S1 test no longer touches those globals at all.)
• N1 (under-budget keepalive test is redundant): keeping it as an explicit, self-documenting assertion of the enabled path. It's cheap and the intent is clearer than relying on the header/gzip tests to incidentally cover keepalive.
• N2 (Blob sizing is browser-scoped): acknowledged; the MAX_KEEPALIVE_BYTES comment already scopes this transport to the browser, and jsdom returns the correct UTF-8 byte count.

[Copilot]

Pull request overview

This PR updates the @amplitude/analytics-browser Fetch transport to opt requests into fetch(..., { keepalive: true }) by default so uploads are more likely to complete during page navigation/redirects, while avoiding browser keepalive budget rejections by gating keepalive based on the actual request body size.

Changes:

• Added a MAX_KEEPALIVE_BYTES budget constant (32 KiB) and set keepalive based on the measured outgoing body size (string UTF-8 bytes or compressed ArrayBuffer.byteLength).
• Updated and added Jest tests to assert keepalive behavior for small, oversized, and oversized-after-gzip payloads.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
packages/analytics-browser/src/transports/fetch.ts	Enables keepalive by default with a body-size gate to avoid Fetch keepalive budget network errors.
packages/analytics-browser/test/transport/fetch.test.ts	Adds/updates transport tests to verify keepalive is enabled/disabled appropriately (including compressed-body cases).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Mercy811]

@bug Bot

[Mercy811]

bugbot run

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit ecea5e8. Configure here.}

[Mercy811]

bugbot run

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 0410353. Configure here.}

[Mercy811]

bugbot run

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit c18000f. Configure here.}

[daniel-graham-amplitude]

My concern about this is that we're potentially competing with the combined keep-alive budget of other requests so we should only use this when necessary.

I think we should add another condition to this:

let isPageExiting = false;
function beforeUnloadHandler() {
  isPageExiting = true;
}
globalScope?.addEventListener('beforeunload', beforeUnloadHandler);
//...
keepalive: bodySize <= KEEPALIVE_MAX_BODY_SIZE_BYTES && isPageExiting

[Mercy811]

The request is canceled if the user closes the tab at any point between when the request is initiated and the tab is closed. Listening to a page exit flag isn't helpful here.

The risk is small here because the payload size is less than 1 KB. See the screenshot in the PR description. The size is released as long as the request succeeds.

[daniel-graham-amplitude]

I'm going to need to research how keepalive works better. It sounds like there's some tradeoffs between using keepalive and not using keepalive meaning there's a risk of nasty surprises. I feel like this implementation does make sense and I'll probably approve it, but I need to know what it is we're shipping first.

[Mercy811]

No problem, take your time 🙏