Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-12
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
## Context

The capture v1 response shape lives in the backend
(`rust/capture/src/v1/analytics/response.rs`): a 2xx carries a `results` map
whose keys are canonical uuids. The request side is lenient, so the SDK can send
a form the server never echoes back. The mismatch is invisible — the batch is
accepted, the per-event verdicts are simply never matched — which is why both
SDKs found it only when they started acting on verdicts.

## Decisions

**The requirement is about the wire value, not the input format.** SDKs keep
accepting whatever uuid forms they accept today (and typed-uuid SDKs keep their
type). What the spec pins down is that the serialized value, and the uuid handed
back to the caller, are canonical.

**Normalization runs after the before-send hook.** Both SDKs normalize at the
last moment for the same reason: the hook can replace the uuid with any accepted
form, and the returned uuid must match what was sent. Specifying it earlier in
the pipeline would leave the hook as a hole.

**An unparseable override does not fail capture.** go's `makeUUID` falls back to
a generated UUIDv7 (v4 if the clock-based path fails); python logs the invalid
value and falls back to a generated UUIDv7. Dropping or throwing would make a
typo in an optional field lose an event, which neither SDK does. The spec
requires the fallback and a log, and leaves the log's wording open.

**Scenarios are tagged `@server`.** Both shipped implementations are server
SDKs, and the capture return value the scenarios check is the server shape.
Client SDKs that accept a uuid override are expected to behave the same way, but
this change does not assert it without evidence.

## Open questions

Both implementations sit on unreleased `v1` branches. The behavior is a bug fix
rather than a new surface, and it matches what the backend already does, so the
contract is recorded now; if the series changes shape before release this
requirement should be re-checked.
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
## Why

Capture v1 answers a 2xx with a per-event `results` map keyed by the **canonical
lowercase hyphenated** uuid, while the endpoint itself parses an incoming event
uuid leniently (uppercase, unhyphenated, brace-wrapped, `urn:uuid:`-prefixed).
An SDK that sends a caller-supplied uuid unchanged therefore cannot find its own
events in the response: a `retry` verdict is never retried, a `drop` verdict
never reaches the error callback, and the event is silently treated as accepted.

Two server SDKs have now fixed this the same way:

- posthog-go [#358](https://github.com/PostHog/posthog-go/pull/358) — `makeUUID`
returns the canonical form of a valid caller-supplied uuid, and
`prepareForSend` canonicalizes the correlation key again after `BeforeSend`.
- posthog-python [#1022's series, #1020](https://github.com/PostHog/posthog-python/pull/1020)
— `_stringify_event_uuid` stores the canonical form ("because capture keys
per-event results by it"), re-run after `before_send` "so the returned uuid
always matches the wire event".

Both also fall back to a freshly generated UUIDv7 when the caller's value does
not parse, rather than failing the capture call.

The `capture` spec says only that `uuid` is a "caller override or a freshly
generated UUIDv7". It does not say the value on the wire is canonical, that the
returned uuid matches it, or what happens to an unparseable override — so a new
SDK (or the next one to move to Capture v1) can reintroduce exactly the
correlation bug both SDKs just fixed.

## What Changes

- Add a `capture` requirement: the event uuid is sent in canonical lowercase
hyphenated form, a caller-supplied uuid in another accepted form is normalized
before enqueue, the returned uuid is the normalized value, normalization runs
after the before-send hook, and an unparseable override is replaced with a
generated UUIDv7 instead of failing the call.
- Note in the narrative (Behavior step 5, step 8, Error handling) why the
canonical form matters: Capture v1 keys its per-event results by it.

## Capabilities

### New Capabilities

_None._

### Modified Capabilities

- `capture`: require a canonical event uuid on the wire and define how a
non-canonical or unparseable caller override is handled.

## Impact

Only SDKs that accept a caller-supplied event uuid are affected, and the change
is observable only in the serialized uuid and the capture return value — no
public signature changes. SDKs that type the uuid (posthog-rs uses a typed
`Uuid`, which always serializes canonically) already conform. SDKs still on the
legacy `/batch/` wire are unaffected in practice, since the canonical form is
accepted everywhere; they conform once they normalize.
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
## Narrative alignment

When syncing this delta, note in Behavior step 5 that a caller-supplied `uuid`
is normalized to canonical lowercase hyphenated form, in step 6 that the
normalization is re-applied after the `before_send` hook, and in step 8 that the
uuid returned to the caller is the normalized value that was sent. Add to Error
handling that an unparseable caller-supplied uuid is logged and replaced with a
generated UUIDv7 rather than failing the call. Leave the existing capture
scenarios and unrelated sections unchanged.

## ADDED Requirements

### Requirement: Event uuid is sent in canonical form

A server SDK SHALL serialize the event `uuid` in canonical lowercase hyphenated form
(`8-4-4-4-12`, no braces, no `urn:uuid:` prefix). A caller-supplied uuid in
another form the SDK accepts — uppercase, unhyphenated, brace-wrapped, or
`urn:uuid:`-prefixed — SHALL be normalized to that form before the event is
enqueued, and the uuid the capture call returns SHALL be the normalized value
that was sent. The normalization SHALL be applied after the `before_send` hook,
so a uuid the hook sets is normalized too.

A caller-supplied value the SDK cannot parse as a uuid SHALL NOT fail or drop
the capture call: the SDK SHALL replace it with a freshly generated UUIDv7 and SHOULD log a
warning. The warning SHOULD NOT include the discarded value, because callers
can put their own data in the uuid field.

Capture v1 keys the per-event `results` map in a 2xx response by the canonical
uuid while parsing the request's uuid leniently, so an event sent under a
non-canonical uuid cannot be correlated with its own verdict: a retryable
verdict is never retried and a drop verdict never reaches the SDK's error
reporting.

#### Scenario: Non-canonical caller uuid is normalized before send (@server)
- **GIVEN** a fresh SDK acceptance test harness
- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z"
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token"
- **WHEN** capture is called with distinct id "user-123", event "Signed Up", and uuid "0199C3E8-4C7B-7E2E-9F21-2B6D5A1C9E04"
- **THEN** one event named "Signed Up" should be enqueued
- **AND** the enqueued event uuid should be "0199c3e8-4c7b-7e2e-9f21-2b6d5a1c9e04"
- **AND** the call should return the enqueued event's uuid

#### Scenario: Unparseable caller uuid falls back to a generated uuid (@server)
- **GIVEN** a fresh SDK acceptance test harness
- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z"
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token"
- **WHEN** capture is called with distinct id "user-123", event "Signed Up", and uuid "not-a-uuid"
- **THEN** the capture call should not throw
- **AND** one event named "Signed Up" should be enqueued
- **AND** the enqueued event uuid should not equal "not-a-uuid"
- **AND** the enqueued event should include an event uuid
- **AND** the call should return the enqueued event's uuid
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
## 1. Contract update

- [x] 1.1 Confirm the shipped normalization in posthog-go (`message.go`:
`makeUUID`, `canonicalUUID`, `prepareForSend`) and posthog-python
(`client.py`: `_stringify_event_uuid`, `_normalize_event_uuid` re-run
after `before_send`), including the unparseable-override fallback.
- [x] 1.2 Draft the canonical event uuid requirement and its scenarios.
- [x] 1.3 Sync the requirement and the narrative notes into the canonical
`capture` spec.

## 2. Validation and archive

- [x] 2.1 Check the diff against the canonical spec.
- [x] 2.2 Archive the completed change on this branch.

Validation: read the shipped source on both `v1` branches. `openspec validate
capture --type spec --strict` reports the same long-requirement warnings as the
rest of the spec, and `openspec validate --specs --strict` totals are unchanged
from `main` (32 passed, 32 failed, all pre-existing warnings). These are
specification checks, not executed SDK conformance tests.
39 changes: 36 additions & 3 deletions openspec/specs/capture/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,12 +103,12 @@ The following steps are the canonical flow for a single capture call. Client and
4. Person-processing state (`$process_person_profile`, `$is_identified`) based on current identity state. The SDK sets these after the caller's properties, so a caller can't override them.
5. SDK-owned per-event keys that the SDK MAY set after the caller's properties: session properties (`$session_id`, `$window_id`) on client SDKs that support session replay, the session replay debug properties, and `$geoip_disable` when GeoIP is disabled.
- **Server:** request-context properties, then caller-supplied `properties`, then SDK-stamped properties. Most server SDKs stamp `$lib` and `$lib_version` over the caller's values, and SDKs with SDK-level default properties (python `super_properties`, go `DefaultEventProperties`, dotnet `SuperProperties`, elixir `global_properties`) apply them after the caller's properties too. `$groups` comes from the `groups` option.
5. **Attach envelope fields.** Assign `timestamp` (caller override or `now()`, serialized in ISO 8601 and normalized to its equivalent UTC instant regardless of the input's original timezone/offset, preserving sub-second precision when the input carries it), `uuid` (caller override or a freshly generated UUIDv7), `distinct_id`, and `event` to the message. Server SDKs additionally stamp `$lib` / `$lib_version` onto properties here if not already present.
6. **Run `before_send` hook.** If the SDK has been configured with a `before_send` callback (Python, Go, posthog-js, .NET), invoke it with the fully-assembled message. The callback may return a modified message, or return `null`/`None` to drop the event. If the callback throws, log a warning, stop the hook chain, and drop the event. Never enqueue the original or partially processed message after a hook failure.
5. **Attach envelope fields.** Assign `timestamp` (caller override or `now()`, serialized in ISO 8601 and normalized to its equivalent UTC instant regardless of the input's original timezone/offset, preserving sub-second precision when the input carries it), `uuid` (caller override or a freshly generated UUIDv7; server SDKs normalize it to canonical lowercase hyphenated form), `distinct_id`, and `event` to the message. Server SDKs additionally stamp `$lib` / `$lib_version` onto properties here if not already present.
6. **Run `before_send` hook.** If the SDK has been configured with a `before_send` callback (Python, Go, posthog-js, .NET), invoke it with the fully-assembled message. The callback may return a modified message, or return `null`/`None` to drop the event. If the callback throws, log a warning, stop the hook chain, and drop the event. Never enqueue the original or partially processed message after a hook failure. Server SDKs re-normalize the message `uuid` after the hook returns, because the hook may have replaced it with another accepted form.
7. **Deliver.**
- **Server (and `posthog-node`, `posthog-js/core` stateless):** push onto an in-memory queue (`max_queue_size` default 10,000). If the queue is full, drop the oldest element and log a warning (posthog-js core; `posthog-python` drops the new element). If queue size ≥ `flush_at` (default 20 client/core, 100 python-server), kick off a background flush. A periodic timer (`flush_interval`, typically 10s client / 10s–30s server) also triggers flushes.
- **Client (browser):** forward to the request queue (`_requestQueue.enqueue`) unless `send_instantly` is set or batching is disabled, in which case send directly via `_send_retriable_request`. Flushes are opportunistic and aligned with network availability / page lifecycle (e.g. `sendBeacon` on `pagehide`).
8. **Return.** Client SDKs return a `CaptureResult` object containing the event data (or `undefined` if dropped). Server SDKs return the generated UUID string (or `null`/`None` if dropped).
8. **Return.** Client SDKs return a `CaptureResult` object containing the event data (or `undefined` if dropped). Server SDKs return the UUID string that was sent — the normalized, canonical form (or `null`/`None` if dropped).

## State & lifecycle

Expand All @@ -123,6 +123,7 @@ The following steps are the canonical flow for a single capture call. Client and
- **Log and drop** when `before_send` throws. The SDK must not enqueue a fallback event because the failed hook may have been responsible for removing sensitive data.
- **Log and swallow** other internal exceptions such as property enrichment or feature-flag-fetch failures. A failure to enqueue must not surface as an exception to the caller — the contract is that `capture` is fire-and-forget.
- **Return sentinel** (`null`/`None`/`undefined`) when a drop occurs and the SDK's signature lets it express that. Some SDKs (Go, Java) lack a return value and communicate failure only via logging.
- **Log and replace** (server SDKs) a caller-supplied `uuid` that cannot be parsed as a uuid, substituting a freshly generated UUIDv7. An unusable uuid override must not cost the caller the event.
- **Never throw** to the caller under normal operation. Capture is latency-sensitive and lives on the hot path of application code; SDKs are expected to absorb all I/O and serialization errors internally.

## Concurrency & ordering
Expand Down Expand Up @@ -435,3 +436,35 @@ This requirement does not apply to server SDKs. Most server SDKs set `$lib` and
| property | value |
| $process_person_profile | false |
| $is_identified | false |

### Requirement: Event uuid is sent in canonical form

A server SDK SHALL serialize the event `uuid` in canonical lowercase hyphenated form (`8-4-4-4-12`, no braces, no `urn:uuid:` prefix). A caller-supplied uuid in another form the SDK accepts — uppercase, unhyphenated, brace-wrapped, or `urn:uuid:`-prefixed — SHALL be normalized to that form before the event is enqueued, and the uuid the capture call returns SHALL be the normalized value that was sent. The normalization SHALL be applied after the `before_send` hook, so a uuid the hook sets is normalized too.

A caller-supplied value the SDK cannot parse as a uuid SHALL NOT fail or drop the capture call: the SDK SHALL replace it with a freshly generated UUIDv7 and SHOULD log a warning. The warning SHOULD NOT include the discarded value, because callers can put their own data in the uuid field.

Capture v1 keys the per-event `results` map in a 2xx response by the canonical uuid while parsing the request's uuid leniently, so an event sent under a non-canonical uuid cannot be correlated with its own verdict: a retryable verdict is never retried and a drop verdict never reaches the SDK's error reporting.

#### Scenario: Non-canonical caller uuid is normalized before send (@server)
- **GIVEN** a fresh SDK acceptance test harness
- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z"
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token"
- **WHEN** capture is called with distinct id "user-123", event "Signed Up", and uuid "0199C3E8-4C7B-7E2E-9F21-2B6D5A1C9E04"
- **THEN** one event named "Signed Up" should be enqueued
- **AND** the enqueued event uuid should be "0199c3e8-4c7b-7e2e-9f21-2b6d5a1c9e04"
- **AND** the call should return the enqueued event's uuid

#### Scenario: Unparseable caller uuid falls back to a generated uuid (@server)
- **GIVEN** a fresh SDK acceptance test harness
- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z"
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token"
- **WHEN** capture is called with distinct id "user-123", event "Signed Up", and uuid "not-a-uuid"
- **THEN** the capture call should not throw
- **AND** one event named "Signed Up" should be enqueued
- **AND** the enqueued event uuid should not equal "not-a-uuid"
- **AND** the enqueued event should include an event uuid
- **AND** the call should return the enqueued event's uuid
Loading