fix(core): honor Retry-After on the OTLP export queues

.changeset/logs-backoff-cap.md

@@ -0,0 +1,7 @@
+---
+'posthog-js': patch
+'posthog-react-native': patch
+'@posthog/core': patch
+---
+
+Cap the retry delay for log exports at 30 seconds, the ceiling the logs contract states. It previously doubled to 64 times the flush interval — 192s on web, 640s on React Native — so a log export now resumes within 30 seconds of a failing endpoint recovering, at the cost of more retry requests while that endpoint is down.

.changeset/logs-backoff-survives-captures.md

@@ -0,0 +1,7 @@
+---
+'posthog-js': patch
+'posthog-react-native': patch
+'@posthog/core': patch
+---
+
+Keep backing off a failing log flush while new records arrive, instead of the next record resetting the retry to the flush interval.

.changeset/otlp-honor-retry-after.md

@@ -0,0 +1,7 @@
+---
+'posthog-node': patch
+'posthog-react-native': patch
+'@posthog/core': patch
+---
+
+Honor `Retry-After` when the ingestion endpoint refuses a logs or metrics batch, instead of retrying on the SDK's own schedule alone. A refusal naming a longer wait extends the one being served, up to five minutes from when it started. Retry delays now carry jitter so clients refused together do not return together, and metrics backs off exponentially across consecutive failures rather than retrying on a fixed interval.

.changeset/otlp-skip-oversized-bodies.md

@@ -0,0 +1,7 @@
+---
+'posthog-node': patch
+'posthog-react-native': patch
+'@posthog/core': patch
+---
+
+Stop sending logs and metrics batches over 10 MiB, or too large to serialize at all, instead of spending a request to discover the endpoint refuses them.

packages/browser/terser-mangled-names.json

@@ -113,7 +113,6 @@
         "_clearDebouncer",
         "_clearFlushBufferTimer",
         "_clearFlushTimeout",
-        "_clearFlushTimer",
         "_clearMouseSelection",
         "_clearPointer",
         "_clearSessionRegisteredProps",
@@ -235,6 +234,7 @@
         "_finishQueuedCompressionEvent",
         "_finishSetup",
         "_fireFeatureFlagsCallbacks",
+        "_firesAt",
         "_flagListenerCleanup",
         "_flagToExperiments",
         "_flagsLoadedFromRemote",
@@ -247,6 +247,7 @@
         "_flushInner",
         "_flushInterval",
         "_flushIntervalMs",
+        "_flushJitter",
         "_flushPendingActivityTimestamp",
         "_flushPromise",
         "_flushTimeout",
@@ -382,6 +383,7 @@
         "_initializeWidgetPromise",
         "_initialized",
         "_initializingClient",
+        "_installedAt",
         "_internalEventEmitter",
         "_internalFlagCheckSatisfied",
         "_intervalLogCount",
@@ -549,6 +551,7 @@
         "_onClick",
         "_onClickHandler",
         "_onDeadClick",
+        "_onFire",
         "_onFocusChange",
         "_onIdentityChanged",
         "_onIdentityCleared",
@@ -747,6 +750,7 @@
         "_resumeSavedTour",
         "_resyncIntervalMs",
         "_resyncTimer",
+        "_retryAfter",
         "_retryQueue",
         "_rrwebError",
         "_rrwebStartAttempted",
@@ -887,6 +891,7 @@
         "_teardown",
         "_throttledMutationsDropped",
         "_tickets",
+        "_timer",
         "_timestamp",
         "_totalBytes",
         "_touchStart",
@@ -916,6 +921,7 @@
         "_unsubscribeFeatureFlags",
         "_unsubscribeIdentifyListener",
         "_unsubscribeSessionId",
+        "_until",
         "_unwrapConsoleError",
         "_unwrapOnError",
         "_unwrapUnhandledRejection",

packages/core/src/__tests__/flush-timer.spec.ts

@@ -0,0 +1,100 @@
+import { FlushTimer } from '../utils/flush-timer'
+
+describe('FlushTimer', () => {
+  it('fires once, after the delay', async () => {
+    const onFire = vi.fn()
+    const timer = new FlushTimer(onFire)
+    timer.arm(1000)
+
+    await vi.advanceTimersByTimeAsync(999)
+    expect(onFire).not.toHaveBeenCalled()
+    await vi.advanceTimersByTimeAsync(1)
+    expect(onFire).toHaveBeenCalledTimes(1)
+
+    await vi.advanceTimersByTimeAsync(10_000)
+    expect(onFire).toHaveBeenCalledTimes(1)
+  })
+
+  it('releases the handle before firing, so the callback can arm again', async () => {
+    const timer: FlushTimer = new FlushTimer(() => {
+      pendingInsideCallback = timer.pending
+    })
+    let pendingInsideCallback: boolean | undefined
+    timer.arm(1000)
+    expect(timer.pending).toBe(true)
+
+    await vi.advanceTimersByTimeAsync(1000)
+    expect(pendingInsideCallback).toBe(false)
+    expect(timer.pending).toBe(false)
+  })
+
+  it('arm replaces a pending timer outright, in either direction', async () => {
+    const onFire = vi.fn()
+    const timer = new FlushTimer(onFire)
+    timer.arm(10_000)
+    timer.arm(1000)
+
+    await vi.advanceTimersByTimeAsync(1000)
+    expect(onFire).toHaveBeenCalledTimes(1)
+  })
+
+  // The reason the deadline lives next to the handle: every capture reaches the
+  // arming path, and none of them may pull a flush in front of a longer wait.
+  it('armNoEarlierThan does not shorten a pending timer', async () => {
+    const onFire = vi.fn()
+    const timer = new FlushTimer(onFire)
+    timer.arm(10_000)
+    timer.armNoEarlierThan(1000)
+
+    await vi.advanceTimersByTimeAsync(9999)
+    expect(onFire).not.toHaveBeenCalled()
+    await vi.advanceTimersByTimeAsync(1)
+    expect(onFire).toHaveBeenCalledTimes(1)
+  })
+
+  it('armNoEarlierThan lengthens a pending timer', async () => {
+    const onFire = vi.fn()
+    const timer = new FlushTimer(onFire)
+    timer.arm(1000)
+    timer.armNoEarlierThan(10_000)
+
+    await vi.advanceTimersByTimeAsync(1000)
+    expect(onFire).not.toHaveBeenCalled()
+    await vi.advanceTimersByTimeAsync(9000)
+    expect(onFire).toHaveBeenCalledTimes(1)
+  })
+
+  it('armNoEarlierThan counts down the remainder, not the whole delay', async () => {
+    const onFire = vi.fn()
+    const timer = new FlushTimer(onFire)
+    timer.arm(10_000)
+    await vi.advanceTimersByTimeAsync(6000)
+    // 4s left, so a 4s request is not longer and must not restart the wait.
+    timer.armNoEarlierThan(4000)
+
+    await vi.advanceTimersByTimeAsync(4000)
+    expect(onFire).toHaveBeenCalledTimes(1)
+  })
+
+  it('armNoEarlierThan arms when nothing is pending', async () => {
+    const onFire = vi.fn()
+    const timer = new FlushTimer(onFire)
+    timer.armNoEarlierThan(1000)
+    expect(timer.pending).toBe(true)
+
+    await vi.advanceTimersByTimeAsync(1000)
+    expect(onFire).toHaveBeenCalledTimes(1)
+  })
+
+  it('clear stops a pending timer and is safe to repeat', async () => {
+    const onFire = vi.fn()
+    const timer = new FlushTimer(onFire)
+    timer.arm(1000)
+    timer.clear()
+    timer.clear()
+    expect(timer.pending).toBe(false)
+
+    await vi.advanceTimersByTimeAsync(10_000)
+    expect(onFire).not.toHaveBeenCalled()
+  })
+})

packages/core/src/__tests__/posthog.otlp-retry-after.spec.ts

@@ -0,0 +1,108 @@
+import { createTestClient, PostHogCoreTestClient, PostHogCoreTestClientMocks } from '@/testing'
+
+// The header has to survive the whole path: response → PostHogFetchHttpError →
+// the retry-later outcome each queue reads. A unit test of the parser alone
+// would still pass if the plumbing were missing.
+describe('OTLP Retry-After', () => {
+  let posthog: PostHogCoreTestClient
+  let mocks: PostHogCoreTestClientMocks
+
+  const respondWith = (status: number, retryAfter?: string): void => {
+    mocks.fetch.mockResolvedValue({
+      status,
+      text: () => Promise.resolve(''),
+      json: () => Promise.resolve({}),
+      headers: { get: (name: string) => (name.toLowerCase() === 'retry-after' && retryAfter ? retryAfter : null) },
+    })
+  }
+
+  beforeEach(() => {
+    ;[posthog, mocks] = createTestClient('TEST_API_KEY', {
+      host: 'http://example.com',
+      preloadFeatureFlags: false,
+      disableCompression: true,
+      fetchRetryCount: 0,
+    })
+  })
+
+  it.each([
+    ['logs', () => posthog._sendLogsBatch({ resourceLogs: [] } as any)],
+    ['metrics', () => posthog._sendMetricsBatch({ resourceMetrics: [] } as any)],
+    ['traces', () => posthog._sendTracesBatch({ resourceSpans: [] } as any)],
+  ])("surfaces the endpoint's Retry-After to the %s queue", async (_signal, send) => {
+    respondWith(429, '120')
+
+    const outcome = await send()
+
+    expect(outcome).toMatchObject({ kind: 'retry-later', retryAfterMs: 120_000 })
+  })
+
+  it('sends once, not once per inner retry, when the endpoint names a wait', async () => {
+    // The inner retriable loop retries on a short fixed delay. Spending its
+    // attempts here would put three extra requests inside the very window the
+    // queue is about to back off for.
+    const [client, clientMocks] = createTestClient('TEST_API_KEY', {
+      host: 'http://example.com',
+      preloadFeatureFlags: false,
+      disableCompression: true,
+    })
+    clientMocks.fetch.mockResolvedValue({
+      status: 429,
+      text: () => Promise.resolve(''),
+      json: () => Promise.resolve({}),
+      headers: { get: (name: string) => (name.toLowerCase() === 'retry-after' ? '120' : null) },
+    })
+
+    const pending = client._sendTracesBatch({ resourceSpans: [] } as any)
+    await vi.advanceTimersByTimeAsync(60_000)
+
+    expect(await pending).toMatchObject({ kind: 'retry-later', retryAfterMs: 120_000 })
+    expect(clientMocks.fetch).toHaveBeenCalledTimes(1)
+  })
+
+  it('still retries internally when the response names no wait', async () => {
+    const [client, clientMocks] = createTestClient('TEST_API_KEY', {
+      host: 'http://example.com',
+      preloadFeatureFlags: false,
+      disableCompression: true,
+    })
+    clientMocks.fetch.mockResolvedValue({
+      status: 503,
+      text: () => Promise.resolve(''),
+      json: () => Promise.resolve({}),
+      headers: { get: () => null },
+    })
+
+    const pending = client._sendTracesBatch({ resourceSpans: [] } as any)
+    await vi.advanceTimersByTimeAsync(60_000)
+
+    expect((await pending).kind).toBe('retry-later')
+    expect(clientMocks.fetch.mock.calls.length).toBeGreaterThan(1)
+  })
+
+  it('leaves retryAfterMs unset when the response sends no header', async () => {
+    respondWith(503)
+
+    const outcome = await posthog._sendTracesBatch({ resourceSpans: [] } as any)
+
+    expect(outcome.kind).toBe('retry-later')
+    expect((outcome as { retryAfterMs?: number }).retryAfterMs).toBeUndefined()
+  })
+
+  it('survives a transport whose headers accessor throws', async () => {
+    mocks.fetch.mockResolvedValue({
+      status: 503,
+      text: () => Promise.resolve(''),
+      json: () => Promise.resolve({}),
+      headers: {
+        get: () => {
+          throw new Error('hostile transport')
+        },
+      },
+    })
+
+    const outcome = await posthog._sendTracesBatch({ resourceSpans: [] } as any)
+
+    expect(outcome.kind).toBe('retry-later')
+  })
+})