Skip to content

fix: align durable queue retries with SDK specs - #134

Open
dustinbyrne wants to merge 2 commits into
mainfrom
fix/durable-retry-queue
Open

fix: align durable queue retries with SDK specs#134
dustinbyrne wants to merge 2 commits into
mainfrom
fix/durable-retry-queue

Conversation

@dustinbyrne

@dustinbyrne dustinbyrne commented Sep 1, 2026

Copy link
Copy Markdown
Contributor

💡 Motivation and Context

Unity's analytics and session replay queues can currently delete events after retryable HTTP 408 and 429 responses. Queue entries can also be acknowledged incorrectly when replay capacity changes during an in-flight request, while oversized singleton payloads can block later records indefinitely.

This aligns Unity with the durable retry-queue contract in PostHog/sdk-specs#53, alongside PostHog/posthog-ios#788 and PostHog/posthog-android#740.

Changes

  • Retain analytics and replay records after transport failures, 408, 429, and 5xx responses while preserving terminal endpoint classifications.
  • Give persisted analytics records queue-owned UUID-v7 identities, independent of mutable event payload UUIDs.
  • Enforce FIFO capacity after restart and when MaxQueueSize is lowered.
  • Acknowledge only the exact analytics storage IDs or replay objects included in an in-flight request.
  • Halve batches after 413 and remove only a singleton record that remains oversized.

The change adds no public API or configuration, and does not change defaults, event payloads, endpoints, or persisted storage layout. Existing payload-UUID storage keys and new queue-owned keys remain mutually readable across upgrades and downgrades. Session replay remains in memory.

💚 How did you test it?

  • DOTNET_ROOT=/opt/homebrew/opt/dotnet/libexec bin/fmt --check
  • bin/test — 477 passed, 2 skipped, 0 failed
  • bin/build — netstandard2.1 build, 0 warnings and 0 errors
  • git diff --check
  • Two complete SDK review passes; final verdict: pass with no findings

📝 Checklist

  • 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 (a patch changeset was added directly)

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Implemented with the Pi coding agent in a local session; no public session link is available. The human directed alignment with the shared durable retry-queue contract and requested this draft PR. Fresh SDK-focused reviewer passes checked retry classification, queue identity, capacity, lifecycle behavior, compatibility, and regression coverage. The implementation preserves Unity's existing public surface, payloads, storage layout, defaults, and capped linear backoff.

@dustinbyrne dustinbyrne self-assigned this Sep 1, 2026
@github-actions

github-actions Bot commented Sep 1, 2026

Copy link
Copy Markdown
Contributor

posthog-unity Compliance Report

Date: 2026-09-04 20:05:44 UTC
Duration: 105698ms

✅ All Tests Passed!

46/46 tests passed


Capture Tests

29/29 tests passed

View Details
Test Status Duration
Format Validation.Event Has Required Fields 63ms
Format Validation.Event Has Uuid 8ms
Format Validation.Event Has Lib Properties 5ms
Format Validation.Distinct Id Is String 6ms
Format Validation.Token Is Present 6ms
Format Validation.Custom Properties Preserved 10ms
Format Validation.Event Has Timestamp 6ms
Retry Behavior.Retries On 503 6518ms
Retry Behavior.Does Not Retry On 400 2014ms
Retry Behavior.Does Not Retry On 401 2010ms
Retry Behavior.Respects Retry After Header 8015ms
Retry Behavior.Implements Backoff 18531ms
Retry Behavior.Retries On 500 5515ms
Retry Behavior.Retries On 502 5514ms
Retry Behavior.Retries On 504 5513ms
Retry Behavior.Max Retries Respected 18531ms
Deduplication.Generates Unique Uuids 11ms
Deduplication.Preserves Uuid On Retry 5513ms
Deduplication.Preserves Uuid And Timestamp On Retry 11512ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry 5519ms
Deduplication.No Duplicate Events In Batch 11ms
Deduplication.Different Events Have Different Uuids 7ms
Compression.Sends Gzip When Enabled 7ms
Batch Format.Uses Proper Batch Structure 5ms
Batch Format.Flush With No Events Sends Nothing 3ms
Batch Format.Multiple Events Batched Together 10ms
Error Handling.Does Not Retry On 403 2007ms
Error Handling.Does Not Retry On 413 2010ms
Error Handling.Retries On 408 5513ms

Feature_Flags Tests

17/17 tests passed

View Details
Test Status Duration
Request Payload.Request With Person Properties Device Id 16ms
Request Payload.Flags Request Uses V2 Query Param 7ms
Request Payload.Flags Request Hits Flags Path Not Decide 4ms
Request Payload.Flags Request Omits Authorization Header 4ms
Request Payload.Token In Flags Body Matches Init 4ms
Request Payload.Groups Round Trip 5ms
Request Payload.Groups Default To Empty Object 4ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False 4ms
Request Payload.Disable Geoip Omitted Defaults To False 4ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key 4ms
Request Lifecycle.No Flags Request On Init Alone 3ms
Request Lifecycle.No Flags Request On Normal Capture 5ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests 6ms
Request Lifecycle.Mock Response Value Is Returned To Caller 5ms
Retry Behavior.Retries Flags On 502 507ms
Retry Behavior.Retries Flags On 504 507ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event 7ms

@dustinbyrne
dustinbyrne force-pushed the fix/durable-retry-queue branch from 303a0c1 to d5498e0 Compare September 4, 2026 20:03
@dustinbyrne
dustinbyrne marked this pull request as ready for review September 4, 2026 20:17
@dustinbyrne
dustinbyrne requested a review from a team as a code owner September 4, 2026 20:17
@greptile-apps

greptile-apps Bot commented Sep 4, 2026

Copy link
Copy Markdown
Prompt To Fix All With AI
### Issue 1
tests/PostHog.Unity.Tests/EventQueueTests.cs:107-118
**Retry flow coverage is incomplete**

These tests stop after the first failed request and only confirm that the record stays queued. The replay tests at `tests/PostHog.Unity.Tests/ReplayQueueTests.cs:61-77` do the same. They do not advance through multiple retries to a successful delivery or verify that retry state resets. This violates the repository directive requiring comprehensive tests of the complete retry flow with multiple attempts, so the requirement must be satisfied before merging.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Reviews (1): Last reviewed commit: "refactor: defer retry-after handling to ..." | Re-trigger Greptile

Comment on lines +107 to +118
public void RetryableFailuresRetainEntries(int statusCode)
{
var harness = CreateHarness();
harness.Queue.Enqueue(Event("retained"));
var id = Assert.Single(harness.Storage.GetEventIds());
harness.Results.Enqueue((false, statusCode));

RunCoroutine(harness.Queue.FlushCoroutine());

Assert.Equal(id, Assert.Single(harness.Storage.GetEventIds()));
Assert.Single(harness.Attempts);
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Retry flow coverage is incomplete

These tests stop after the first failed request and only confirm that the record stays queued. The replay tests at tests/PostHog.Unity.Tests/ReplayQueueTests.cs:61-77 do the same. They do not advance through multiple retries to a successful delivery or verify that retry state resets. This violates the repository directive requiring comprehensive tests of the complete retry flow with multiple attempts, so the requirement must be satisfied before merging.

Rule Used: When implementing retry logic, include comprehensi... (source)

Learned From
PostHog/posthog#32651

Knowledge Base Used: SDK validation and release automation

Prompt To Fix With AI
This is a comment left during a code review.
Path: tests/PostHog.Unity.Tests/EventQueueTests.cs
Line: 107-118

Comment:
**Retry flow coverage is incomplete**

These tests stop after the first failed request and only confirm that the record stays queued. The replay tests at `tests/PostHog.Unity.Tests/ReplayQueueTests.cs:61-77` do the same. They do not advance through multiple retries to a successful delivery or verify that retry state resets. This violates the repository directive requiring comprehensive tests of the complete retry flow with multiple attempts, so the requirement must be satisfied before merging.

**Rule Used:** When implementing retry logic, include comprehensi... ([source](https://app.greptile.com/posthog-org-19734/-/custom-context?memory=24d1be3f-07fb-465d-b1a7-60dff301aed8))

**Learned From**
[PostHog/posthog#32651](https://github.com/PostHog/posthog/pull/32651)

**Knowledge Base Used:** [SDK validation and release automation](https://app.greptile.com/posthog-org-19734/-/custom-context/knowledge-base/posthog/posthog-unity/-/docs/sdk-validation-and-release.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants