diff --git a/packages/core/src/Core/Client.php b/packages/core/src/Core/Client.php index 164d066..cc90f1f 100644 --- a/packages/core/src/Core/Client.php +++ b/packages/core/src/Core/Client.php @@ -294,6 +294,24 @@ public function captureTransaction(Transaction $transaction): void } } + /** + * Mints an event id in the only shape ingest accepts: the server validates + * the field as uuid4, so a random UUID with the version and variant bits + * set is what makes an event deduplicable rather than rejected with 400. + * + * It is public because the id is not optional for anyone assembling an + * ingest payload by hand instead of going through this client - see + * DuckBugProvider::ensureEventId(). + */ + public static function generateEventId(): string + { + $bytes = random_bytes(16); + $bytes[6] = \chr((\ord($bytes[6]) & 0x0F) | 0x40); + $bytes[8] = \chr((\ord($bytes[8]) & 0x3F) | 0x80); + + return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($bytes), 4)); + } + /** * @param array $context * @return array @@ -344,7 +362,7 @@ private function buildBasePayload(array $context): array $requestContext = $this->pond->getContext(); return [ - 'eventId' => $this->generateEventId(), + 'eventId' => self::generateEventId(), 'platform' => $metadata['platform'], 'release' => $metadata['release'], 'environment' => $metadata['environment'], @@ -593,15 +611,6 @@ private function isLevelEnabled(ProviderSetup $setup, string $rawLevel): bool } } - private function generateEventId(): string - { - $bytes = random_bytes(16); - $bytes[6] = \chr((\ord($bytes[6]) & 0x0F) | 0x40); - $bytes[8] = \chr((\ord($bytes[8]) & 0x3F) | 0x80); - - return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($bytes), 4)); - } - private function generateTraceId(): string { return bin2hex(random_bytes(16)); diff --git a/packages/core/src/HttpClient/HttpClient.php b/packages/core/src/HttpClient/HttpClient.php index a8a003c..1d95de2 100644 --- a/packages/core/src/HttpClient/HttpClient.php +++ b/packages/core/src/HttpClient/HttpClient.php @@ -125,12 +125,14 @@ private function execute(string $url, string $body, int $attempts): TransportRes * deduplicates on the event id with a Postgres primary key and ON CONFLICT * DO NOTHING, with no expiry, on the single and the batch route alike. * - * That guarantee is only as strong as the id. It has to be supplied by the - * caller: when a payload reaches ingest without an "eventId", the server - * mints a fresh one per request and a retry does store the event twice. - * Client::generateEventId() sets a UUIDv4 on every event it builds, so the - * normal path is safe. The server validates it as uuid4, so a non-UUID - * idempotency key is rejected with 400 rather than honoured. + * That guarantee is only as strong as the id, and the id is optional to + * ingest: a payload that arrives without an "eventId" gets a fresh one + * minted per request, and a retry then stores the event twice. Nothing + * reaches this client in that state - Client sets a UUIDv4 on every event + * it builds, and DuckBugProvider::ensureEventId() fills the field for + * anything else, including a caller driving captureEvent() directly. The + * server validates it as uuid4, so a non-UUID idempotency key is rejected + * with 400 rather than honoured. * * 408 is retried because it is the edge timing out the request body * (nginx client_body_timeout and friends), never a verdict on the payload; diff --git a/packages/core/src/Providers/DuckBugProvider.php b/packages/core/src/Providers/DuckBugProvider.php index 77c713d..4294b77 100644 --- a/packages/core/src/Providers/DuckBugProvider.php +++ b/packages/core/src/Providers/DuckBugProvider.php @@ -4,6 +4,7 @@ namespace DuckBug\Providers; +use DuckBug\Core\Client; use DuckBug\Core\Event; use DuckBug\Core\FlushableProvider; use DuckBug\Core\Provider; @@ -222,6 +223,45 @@ private function preparePayload(array $payload): ?array $payload = $this->stripNullValues($processed); } + return $this->ensureEventId($payload); + } + + /** + * Guarantees that every payload leaving this provider carries an + * idempotency key. Ingest deduplicates on "eventId" - a Postgres primary + * key with ON CONFLICT DO NOTHING, no expiry, on the single and the batch + * route alike - but only for a payload that has one: the field is optional + * there, and without it the server mints a fresh id per request, so the + * retries in HttpClient would store the same event once per attempt. + * + * preparePayload() is the last point every payload passes through before + * the transport, and this runs as its final act: after beforeSend and after + * the null strip, because a hook that dropped or blanked the field would + * otherwise reopen the gap. The "nothing to send" check stays above, so no + * event is born out of an eventId alone. + * + * Client sets the id on everything it builds, so this is a no-op on the + * normal path; it is a caller driving the provider straight through + * captureEvent() that would otherwise reach ingest unidentified. + * + * A usable id the caller supplied always wins. Anything else - absent, + * blank, or not a string - is not an id ingest would honour (it validates + * uuid4 and answers 400 otherwise), so it is replaced rather than passed + * through to be rejected. + * + * @param array $payload + * @return array + */ + private function ensureEventId(array $payload): array + { + /** @var mixed $existing */ + $existing = $payload['eventId'] ?? null; + if (\is_string($existing) && trim($existing) !== '') { + return $payload; + } + + $payload['eventId'] = Client::generateEventId(); + return $payload; } diff --git a/src/Core/Client.php b/src/Core/Client.php index 164d066..cc90f1f 100644 --- a/src/Core/Client.php +++ b/src/Core/Client.php @@ -294,6 +294,24 @@ public function captureTransaction(Transaction $transaction): void } } + /** + * Mints an event id in the only shape ingest accepts: the server validates + * the field as uuid4, so a random UUID with the version and variant bits + * set is what makes an event deduplicable rather than rejected with 400. + * + * It is public because the id is not optional for anyone assembling an + * ingest payload by hand instead of going through this client - see + * DuckBugProvider::ensureEventId(). + */ + public static function generateEventId(): string + { + $bytes = random_bytes(16); + $bytes[6] = \chr((\ord($bytes[6]) & 0x0F) | 0x40); + $bytes[8] = \chr((\ord($bytes[8]) & 0x3F) | 0x80); + + return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($bytes), 4)); + } + /** * @param array $context * @return array @@ -344,7 +362,7 @@ private function buildBasePayload(array $context): array $requestContext = $this->pond->getContext(); return [ - 'eventId' => $this->generateEventId(), + 'eventId' => self::generateEventId(), 'platform' => $metadata['platform'], 'release' => $metadata['release'], 'environment' => $metadata['environment'], @@ -593,15 +611,6 @@ private function isLevelEnabled(ProviderSetup $setup, string $rawLevel): bool } } - private function generateEventId(): string - { - $bytes = random_bytes(16); - $bytes[6] = \chr((\ord($bytes[6]) & 0x0F) | 0x40); - $bytes[8] = \chr((\ord($bytes[8]) & 0x3F) | 0x80); - - return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($bytes), 4)); - } - private function generateTraceId(): string { return bin2hex(random_bytes(16)); diff --git a/src/HttpClient/HttpClient.php b/src/HttpClient/HttpClient.php index a8a003c..1d95de2 100644 --- a/src/HttpClient/HttpClient.php +++ b/src/HttpClient/HttpClient.php @@ -125,12 +125,14 @@ private function execute(string $url, string $body, int $attempts): TransportRes * deduplicates on the event id with a Postgres primary key and ON CONFLICT * DO NOTHING, with no expiry, on the single and the batch route alike. * - * That guarantee is only as strong as the id. It has to be supplied by the - * caller: when a payload reaches ingest without an "eventId", the server - * mints a fresh one per request and a retry does store the event twice. - * Client::generateEventId() sets a UUIDv4 on every event it builds, so the - * normal path is safe. The server validates it as uuid4, so a non-UUID - * idempotency key is rejected with 400 rather than honoured. + * That guarantee is only as strong as the id, and the id is optional to + * ingest: a payload that arrives without an "eventId" gets a fresh one + * minted per request, and a retry then stores the event twice. Nothing + * reaches this client in that state - Client sets a UUIDv4 on every event + * it builds, and DuckBugProvider::ensureEventId() fills the field for + * anything else, including a caller driving captureEvent() directly. The + * server validates it as uuid4, so a non-UUID idempotency key is rejected + * with 400 rather than honoured. * * 408 is retried because it is the edge timing out the request body * (nginx client_body_timeout and friends), never a verdict on the payload; diff --git a/src/Providers/DuckBugProvider.php b/src/Providers/DuckBugProvider.php index 77c713d..4294b77 100644 --- a/src/Providers/DuckBugProvider.php +++ b/src/Providers/DuckBugProvider.php @@ -4,6 +4,7 @@ namespace DuckBug\Providers; +use DuckBug\Core\Client; use DuckBug\Core\Event; use DuckBug\Core\FlushableProvider; use DuckBug\Core\Provider; @@ -222,6 +223,45 @@ private function preparePayload(array $payload): ?array $payload = $this->stripNullValues($processed); } + return $this->ensureEventId($payload); + } + + /** + * Guarantees that every payload leaving this provider carries an + * idempotency key. Ingest deduplicates on "eventId" - a Postgres primary + * key with ON CONFLICT DO NOTHING, no expiry, on the single and the batch + * route alike - but only for a payload that has one: the field is optional + * there, and without it the server mints a fresh id per request, so the + * retries in HttpClient would store the same event once per attempt. + * + * preparePayload() is the last point every payload passes through before + * the transport, and this runs as its final act: after beforeSend and after + * the null strip, because a hook that dropped or blanked the field would + * otherwise reopen the gap. The "nothing to send" check stays above, so no + * event is born out of an eventId alone. + * + * Client sets the id on everything it builds, so this is a no-op on the + * normal path; it is a caller driving the provider straight through + * captureEvent() that would otherwise reach ingest unidentified. + * + * A usable id the caller supplied always wins. Anything else - absent, + * blank, or not a string - is not an id ingest would honour (it validates + * uuid4 and answers 400 otherwise), so it is replaced rather than passed + * through to be rejected. + * + * @param array $payload + * @return array + */ + private function ensureEventId(array $payload): array + { + /** @var mixed $existing */ + $existing = $payload['eventId'] ?? null; + if (\is_string($existing) && trim($existing) !== '') { + return $payload; + } + + $payload['eventId'] = Client::generateEventId(); + return $payload; } diff --git a/tests/Unit/Providers/DuckBugProviderTest.php b/tests/Unit/Providers/DuckBugProviderTest.php index f518505..4dca184 100644 --- a/tests/Unit/Providers/DuckBugProviderTest.php +++ b/tests/Unit/Providers/DuckBugProviderTest.php @@ -20,6 +20,13 @@ final class DuckBugProviderTest extends TestCase { private const TEST_DSN = 'https://duckbug.io'; + /** + * The server's own `omitempty,uuid4` rule spelled out. Ingest answers 400 to + * anything else, so an id minted here has to match it or the event is dropped + * instead of deduplicated. + */ + private const UUID4_PATTERN = '/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/'; + /** * @throws ReflectionException */ @@ -169,6 +176,180 @@ public function testTransactionBypassesBatchBufferAndUsesSingleIngest(): void ])); } + /** + * @throws ReflectionException + */ + public function testMintsEventIdWhenCallerOmitsIt(): void + { + $sent = $this->captureSentLogPayload([ + 'time' => 1704067200000, + 'level' => 'WARN', + 'message' => 'no id from the caller', + 'context' => [], + ]); + + self::assertArrayHasKey('eventId', $sent); + self::assertSame(1, preg_match(self::UUID4_PATTERN, (string)$sent['eventId'])); + } + + /** + * @throws ReflectionException + */ + public function testReplacesEventIdIngestWouldReject(): void + { + /** @var array $unusable */ + $unusable = [ + 'empty string' => '', + 'whitespace only' => " \t ", + 'not a string' => 12345, + 'boolean' => true, + ]; + + /** @var mixed $value */ + foreach ($unusable as $label => $value) { + $sent = $this->captureSentLogPayload([ + 'eventId' => $value, + 'time' => 1704067200000, + 'level' => 'WARN', + 'message' => 'unusable id from the caller', + 'context' => [], + ]); + + self::assertArrayHasKey('eventId', $sent, $label); + self::assertSame(1, preg_match(self::UUID4_PATTERN, (string)$sent['eventId']), $label); + } + } + + /** + * @throws ReflectionException + */ + public function testKeepsEventIdSuppliedByTheCaller(): void + { + $sent = $this->captureSentLogPayload([ + 'eventId' => '550e8400-e29b-41d4-a716-446655440020', + 'time' => 1704067200000, + 'level' => 'WARN', + 'message' => 'caller owns the id', + 'context' => [], + ]); + + self::assertSame('550e8400-e29b-41d4-a716-446655440020', $sent['eventId']); + } + + /** + * A beforeSend hook runs before the id is filled in, so one that drops the + * field would reopen the gap if the provider trusted the hook's output. + * + * @throws ReflectionException + */ + public function testRestoresEventIdDroppedByBeforeSend(): void + { + $sent = $this->captureSentLogPayload( + [ + 'eventId' => '550e8400-e29b-41d4-a716-446655440021', + 'time' => 1704067200000, + 'level' => 'WARN', + 'message' => 'beforeSend dropped the id', + 'context' => [], + ], + static function (array $payload): array { + unset($payload['eventId']); + return $payload; + } + ); + + self::assertArrayHasKey('eventId', $sent); + self::assertSame(1, preg_match(self::UUID4_PATTERN, (string)$sent['eventId'])); + self::assertNotSame('550e8400-e29b-41d4-a716-446655440021', $sent['eventId']); + } + + /** + * Filling the id must not resurrect an event a beforeSend hook dropped, nor + * turn one into a payload whose only field is the id. + * + * @throws ReflectionException + */ + public function testBeforeSendDiscardingTheEventStillSendsNothing(): void + { + /** @var HttpClientInterface|MockObject $client */ + $client = $this->createMock(HttpClientInterface::class); + $client->expects(self::never())->method('send'); + $client->expects(self::never())->method('sendBatch'); + + $provider = $this->createProviderWithClient($client); + $provider->setBeforeSend(static function (array $payload) { + return null; + }); + + $provider->captureEvent(Event::log([ + 'time' => 1704067200000, + 'level' => 'WARN', + 'message' => 'dropped by the hook', + 'context' => [], + ])); + } + + /** + * @throws ReflectionException + */ + public function testMintsDistinctEventIdsPerEvent(): void + { + /** @var HttpClientInterface|MockObject $client */ + $client = $this->createMock(HttpClientInterface::class); + + $batch = []; + $client->expects(self::once()) + ->method('sendBatch') + ->willReturnCallback(static function (string $dsn, string $type, array $items) use (&$batch) { + $batch = $items; + return new TransportResult(202); + }); + + $provider = $this->createProviderWithClient($client, 2); + + for ($i = 0; $i < 2; ++$i) { + $provider->captureEvent(Event::log([ + 'time' => 1704067200000 + $i, + 'level' => 'WARN', + 'message' => 'batched without an id', + 'context' => [], + ])); + } + + self::assertCount(2, $batch); + self::assertSame(1, preg_match(self::UUID4_PATTERN, (string)$batch[0]['eventId'])); + self::assertSame(1, preg_match(self::UUID4_PATTERN, (string)$batch[1]['eventId'])); + self::assertNotSame($batch[0]['eventId'], $batch[1]['eventId']); + } + + /** + * @param array $payload + * @throws ReflectionException + * @return array + */ + private function captureSentLogPayload(array $payload, ?callable $beforeSend = null): array + { + /** @var HttpClientInterface|MockObject $client */ + $client = $this->createMock(HttpClientInterface::class); + + $sent = []; + $client->expects(self::once()) + ->method('send') + ->willReturnCallback(static function (string $dsn, string $type, array $data) use (&$sent) { + $sent = $data; + return new TransportResult(202); + }); + + $provider = $this->createProviderWithClient($client); + if ($beforeSend !== null) { + $provider->setBeforeSend($beforeSend); + } + + $provider->captureEvent(Event::log($payload)); + + return $sent; + } + /** * @throws ReflectionException */