[turnipdabeets]

💡 Motivation and Context

Stacked on #673. We agreed that SDKs should drop events only when they can never be delivered (event too large, duplicate uuid) or when the buffer is full. A 404 usually means a misconfigured proxy, and a 429 now comes only from an overloaded Envoy. Both can recover, so dropping the batch loses data for no reason.

This ports PostHog/posthog-go#395 to the Dart desktop transport (Windows/Linux): 404 and 429 join 408/500/502/503/504 as retried statuses. Redirects (other than same-origin 307/308) are still terminal. Flutter on iOS and Android gets the same fix through the native SDKs.

It also brings desktop retry, timeout and flush behavior in line with posthog-android 4.0 (PostHog/posthog-android#897) and posthog-ios 4.0 (PostHog/posthog-ios#979), so capture v1 behaves the same on every 6.0 platform:

• Backoff (ed36592). A transient failure (network error or a retried status), or a 2xx whose per-event results ask to retry, no longer resends inside the flush (it used to try 3 times, 3 s apart, then pause 6/12/24/30 s). Each one now pauses the queue: 1 s, doubling up to 30 s, with ±25% jitter. Retry-After is a floor applied after the jitter, capped at 30 s. It no longer replaces the backoff, so Retry-After: 1 doesn't make the SDK resend every 3 s. A delivered or dropped batch resets the backoff. The jitter source is injectable for tests.
• Request timeout (1ae278f). The 10 s whole-request timeout could fail a large batch on a slow uplink on every attempt and keep it stuck at the head of the queue. A request now fails only after 10 s without progress: connecting (HttpClient.connectionTimeout), the socket taking a 64 KiB chunk of the body (addStream respects socket backpressure), the response headers, or a chunk of the response body. This is as close to OkHttp's and URLSession's idle timeouts as dart:io allows. Like those, it can't see bytes still in the kernel send buffer, so the wait for headers starts once the last chunk is handed to the socket.
• 413 (7c25cac). Halves flushAt along with the batch size, keeping flushAt ≤ the batch size, and ends the flush instead of resending at once. The smaller batches go out with the next flush (the next capture over flushAt, or the periodic flush). The natives differ here: Android pauses with backoff after a 413, while iOS ends the flush without one. Desktop follows iOS and adds no backoff.
• Byte flush trigger (b7cd99c). The queue now also flushes once 5 MiB of serialized events is queued (the captureV1MaxBatchBytes from feat!: capture v1 on every platform, with per-event options and captureAi #673), not only at flushAt. The file queue tracks each event's size: measured when the event is added, and read from the file sizes when a later process loads the queue.

Divergences from native: no backoff after a 413 (matches iOS, not Android), and the timeout limitation above.

💚 How did you test it?

• 404/429: moved from the terminal-status loop to the retried loop in queue_flush_test.dart, and 429 added to the Retry-After pause test. The capture v1 404 test checks that the batch stays queued and nothing falls back to /batch.
• Backoff: captureRetryDelay unit tests (doubling and cap, jitter bounds, an out-of-range jitter unit, Retry-After as a floor and its 30 s cap). Client tests with fixed jitter cover the 1/2/4/8/16/30 s schedule, ±25% jitter (first retry at 750 ms and 1250 ms), Retry-After 5 over a 1 s backoff and Retry-After: 1 under a 16 s backoff, and a partial-retry 2xx advancing the backoff while a full delivery resets it. testClient fixes the jitter at the midpoint, so the existing timing tests stay deterministic.
• Timeout: a fake request covers an upload that takes a chunk every 6 s (finishes past 10 s, no abort), an upload that stalls (aborted at exactly 10 s, events kept), and a response body that trickles in past 10 s. The existing connect, body-timeout and cancel-before-retry tests still pass. A local experiment confirmed that HttpClientRequest.addStream stops pulling chunks once a peer stops reading.
• 413: the batch size and flushAt both halve, each 413 ends its flush, the next capture over the new flushAt flushes, and the periodic flush sends the halved batches.
• Byte trigger: two 2.5 MiB events flush right away while far below flushAt, and FileEventQueue.byteCount is checked across add, remove and a reload from disk.
• flutter test in posthog_flutter (1324 passed), plus dart analyze . (no issues) and dart format --set-exit-if-changed . (no changes) from the repo root.

📝 Checklist

• All commits are signed (see Commit signing)
• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran pnpm changeset to generate a changeset file

No new changeset is needed because capture v1 on desktop hasn't shipped yet. The existing v6-desktop-capture-v1 changeset from #673 now says that a 404 or 429 is retried, that redirects still drop the batch, and that the queue backs off like iOS and Android.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Claude Code made the 404/429 change from a brief that named posthog-go#395 as the reference. A later brief asked it to match the posthog-android 4.0 and posthog-ios 4.0 retry, timeout and flush behavior, and it checked each gap against the native queue code. It left alone property order, options, process_person_profile, the AI endpoint and the per-path retry identity, which are being done separately. /flags keeps its own retry (502/504 only, once, after 300 ms).

🤖 Generated with Claude Code

[github-actions]

posthog-flutter Compliance Report

Date: 2026-10-28 20:19:59 UTC
Duration: 96508ms

✅ All Tests Passed!

45/45 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	127ms
Format Validation.Event Has Uuid	✅	112ms
Format Validation.Event Has Lib Properties	✅	111ms
Format Validation.Distinct Id Is String	✅	110ms
Format Validation.Token Is Present	✅	110ms
Format Validation.Custom Properties Preserved	✅	112ms
Format Validation.Event Has Timestamp	✅	112ms
Retry Behavior.Retries On 503	✅	5324ms
Retry Behavior.Does Not Retry On 400	✅	2113ms
Retry Behavior.Does Not Retry On 401	✅	2113ms
Retry Behavior.Respects Retry After Header	✅	8120ms
Retry Behavior.Implements Backoff	✅	15436ms
Retry Behavior.Retries On 500	✅	5221ms
Retry Behavior.Retries On 502	✅	5223ms
Retry Behavior.Retries On 504	✅	5223ms
Retry Behavior.Max Retries Respected	✅	15442ms
Deduplication.Generates Unique Uuids	✅	120ms
Deduplication.Preserves Uuid On Retry	✅	5221ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10330ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5226ms
Deduplication.No Duplicate Events In Batch	✅	116ms
Deduplication.Different Events Have Different Uuids	✅	112ms
Compression.Sends Gzip When Enabled	✅	113ms
Batch Format.Uses Proper Batch Structure	✅	110ms
Batch Format.Flush With No Events Sends Nothing	✅	107ms
Batch Format.Multiple Events Batched Together	✅	117ms
Error Handling.Does Not Retry On 403	✅	2113ms
Error Handling.Does Not Retry On 413	✅	2114ms
Error Handling.Retries On 408	✅	5223ms

Feature_Flags Tests

✅ 16/16 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	13ms
Request Payload.Flags Request Uses V2 Query Param	✅	8ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	7ms
Request Payload.Flags Request Omits Authorization Header	✅	7ms
Request Payload.Token In Flags Body Matches Init	✅	7ms
Request Payload.Groups Round Trip	✅	7ms
Request Payload.Groups Default To Empty Object	✅	6ms
Request Payload.Person Properties Distinct Id Auto Populated When Caller Omits It	✅	7ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	6ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	6ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	6ms
Request Lifecycle.No Flags Request On Init Alone	✅	3ms
Request Lifecycle.No Flags Request On Normal Capture	✅	109ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	14ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	7ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	110ms

[posthog]

PostHog Review · Standard · reviewed fef8375: 1 Should fix.

See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.

[marandaneto]

The code looks good; no qualifying findings. Verdict: correct.

[posthog]

PostHog Review · Standard · reviewed b7cd99c: 1 Should fix.