Repository navigation
fix(capture): send the event uuid in canonical form - #119
Merged
Merged
Conversation
Capture v1 keys its per-event results map by the canonical lowercase hyphenated uuid while parsing request uuids leniently, so an event sent under a non-canonical caller-supplied uuid cannot be correlated with its own verdict. posthog-go and posthog-python both now normalize the uuid before send, after before_send, and fall back to a generated UUIDv7 for an unparseable override. Record that in the capture spec. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Generated-By: PostHog Desktop Task-Id: 1b508480-1639-4fda-8a0f-13880afee91c
This was referenced Oct 14, 2026
…ng to shipped code posthog-js passes a valid caller uuid through unchanged, so the rule is scoped to server SDKs (matching the @server scenarios). posthog-go v1 does not log the fallback and posthog-python v1 deliberately omits the value from its warning, so the warning is a SHOULD and SHOULD NOT include the value. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
turnipdabeets
marked this pull request as ready for review
October 20, 2026 19:47
marandaneto
approved these changes
Oct 21, 2026
marandaneto
left a comment
marandaneto
left a comment
Member
There was a problem hiding this comment.
The code looks good; no qualifying findings. Verdict: correct.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Capture v1 answers a 2xx with a per-event
resultsmap keyed by the canonical lowercase hyphenated uuid, while the request side parses an event uuid leniently (uppercase, unhyphenated, braced,urn:uuid:). An SDK that forwards a caller-supplied uuid unchanged cannot find its own events in the response: aretryverdict is never retried, adropverdict never reaches the error callback, and the event is silently treated as accepted. Thecapturespec said only thatuuidis a "caller override or a freshly generated UUIDv7", so nothing stopped the next SDK from reintroducing the bug.Source changes
v1).makeUUIDreturns the canonical form of a valid caller-supplied uuid;prepareForSendcanonicalizes the correlation key again afterBeforeSend; an unparseable value falls back to a generated UUIDv7.v1)._stringify_event_uuidstores the canonical form "because capture keys per-event results by it", and_normalize_event_uuidruns again afterbefore_send"so the returned uuid always matches the wire event"; an invalid override is logged and replaced with a generated UUIDv7.What changed in the spec
capturerequirement Event uuid is sent in canonical form: canonical on the wire, a caller override in another accepted form normalized before enqueue, the returned uuid equal to the value sent, normalization re-applied after the before-send hook, and an unparseable override logged and replaced with a generated UUIDv7 rather than failing the call. Two@serverscenarios cover normalization and the fallback.Proposed, applied and archived on this branch per AGENTS.md.
openspec validate --specs --stricttotals are unchanged frommain(the remaining warnings are the pre-existing long-requirement ones across the repo).Uncertain / worth a look
v1branches. This is a bug fix against behavior the backend already has, so it is recorded now, but it is worth re-checking if the capture v1 series changes shape before release.@server(applicability only, not the opt-in@sdk:server) because both shipped fixes are server SDKs. Client SDKs that accept a uuid override are presumably the same, but this PR does not assert it.CaptureError,CaptureEventResult, aggregate loss logging, 100ms×2^attempt backoff capped at 30s,Consumerretries default 3) aligned with posthog-go'sv1. That is a larger new contract area with no spec home today, so it needs a deliberate call rather than an inferred spec edit.Created with PostHog Desktop
🤖 Generated with Claude Code