Replay integration's public stop() has no way to skip force-flush after consent withdrawal (GDPR)

[trinitiwowka]

Problem Statement

@sentry-internal/replay's public ReplayIntegration.stop() has no way to stop recording without force-flushing the pending replay once recordingMode === 'session':

// packages/replay-internal/src/integration.ts
stop() {
  if (!this._replay) {
    return Promise.resolve();
  }

  return this._replay.stop({ forceFlush: this._replay.recordingMode === 'session', reason: 'manual' });
}

The internal Replay.stop({ forceFlush }) method does support disabling the flush, but that option isn't exposed through the public integration API.

This matters for GDPR/consent-gated setups (CookieYes, OneTrust, Usercentrics, custom CMPs, etc.): a common pattern is to keep Sentry.init() running always (so other instrumentation like browser tracing integrations wire up correctly) but gate actual sending behind beforeSend/beforeSendTransaction, and call replay.stop() when the user withdraws consent for session replay / performance monitoring.

beforeSend/beforeSendTransaction don't apply to Replay envelopes, so today the only gate is stop() — and if the user withdraws consent while an errored session has already been promoted to 'session' recording mode, calling stop() immediately force-flushes and sends the pending replay to Sentry after the user revoked consent. There's no public way to just stop recording and discard the buffered segment instead.

The only workaround right now is reaching into the integration's private _replay field to call the internal stop({ forceFlush: false }) directly, which isn't something we want to depend on in production code since it's not part of the public API surface and could change without notice.

Solution Brainstorm

Expose the existing internal forceFlush control on the public integration API, e.g.:

stop(options?: { forceFlush?: boolean }): Promise<void> {
  if (!this._replay) {
    return Promise.resolve();
  }

  return this._replay.stop({
    forceFlush: options?.forceFlush ?? this._replay.recordingMode === 'session',
    reason: 'manual',
  });
}

Defaulting to the current behavior (forceFlush: recordingMode === 'session') keeps this fully backwards compatible, while letting consent-driven integrations opt into stop({ forceFlush: false }) to guarantee nothing is sent after withdrawal.

Happy to open a PR for this if the approach looks reasonable — it looks like a small, additive change to packages/replay-internal/src/integration.ts.

Additional Context

Found while implementing consent-mode gating for @sentry/react + @sentry-internal/replay in a web app (browser SDK, @sentry/react@10.53.1). Verified the same limitation is still present as of 10.65.0 (latest at time of writing) — no public API changed in that range.

[linear-code]

JS-3019

[isaacs]

Thanks! Yes, this is a valid feature request.

The problem is real, and the proposed solution solves the problem, and is minimal and backwards-compatible. PR welcome.

It should default to the current behavior (so that we can land it in v10), and include a test. Also, be sure to note the "already-sent segments aren't retracted" caveat in the option's doc comment. That is, stop({ forceFlush: false }) would prevent the pending/final segment from being sent, but it does not retract segments already sent earlier during 'session' recording. That is, it's "don't send the buffered segment on stop", not "unsend everything". The docs for this option should say so.

The main concern I'd see with this (which doesn't have to gate a PR, but might be worth considering before landing) is the API shape bikeshed. forceFlush leaks an internal term into the public API. We might want to consider whether another option reads better for the consent use case (e.g. stop({ flush: false }), or a dedicated discard-style path). Not a blocker (matching the internal name is the least surprising for anyone who already knows it) but worth a moment since this becomes public surface.