From d6a1694987a368aeb74cf137c88e152867596e9d Mon Sep 17 00:00:00 2001 From: Konstantin Zaytcev Date: Thu, 17 Sep 2026 09:25:25 +0300 Subject: [PATCH 1/2] fix(provider): mint an eventId the caller did not supply MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ingest deduplicates on eventId, but the field is optional: a payload that arrives without one gets a fresh id minted per request, so a retry stores the event twice. Client sets the id, so every integration that goes through the core — Monolog, Laravel, Symfony, PSR-15 — was covered, while calling DuckBugProvider::create($dsn)->captureEvent(...) directly was not. With the default maxRetries of 2, that means duplicates. preparePayload is the one place a payload cannot avoid, and the id goes in as its last act: after beforeSend and after stripNullValues, because a hook that drops the field would otherwise reopen the gap. There is a test for exactly that. The beforeSend-returned-null bail stays above it. An existing usable id is left alone; a missing, blank or non-string one is replaced, since ingest rejects those with 400 anyway. generateEventId becomes public rather than being duplicated in the provider: assembling a payload by hand is a legitimate scenario, and then the caller needs something to fill the field with. This mirrors core.NewEventID in the Go SDK, so the three read the same. The tests match the server's own uuid4 rule with preg_match rather than an assertion helper, because those diverged between PHPUnit 7.5 and 9.6 and both run in CI, and they pin that two consecutive events get different ids. --- packages/core/src/Core/Client.php | 29 ++- packages/core/src/HttpClient/HttpClient.php | 14 +- .../core/src/Providers/DuckBugProvider.php | 40 ++++ src/Core/Client.php | 29 ++- src/HttpClient/HttpClient.php | 14 +- src/Providers/DuckBugProvider.php | 40 ++++ tests/Unit/Providers/DuckBugProviderTest.php | 181 ++++++++++++++++++ 7 files changed, 315 insertions(+), 32 deletions(-) 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..4ad6a04 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 + * @return array + * @throws ReflectionException + */ + 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 */ From 52831bd3b0a789995fe66d653bd3bc35e043ba69 Mon Sep 17 00:00:00 2001 From: Konstantin Zaytcev Date: Thu, 17 Sep 2026 09:55:09 +0300 Subject: [PATCH 2/2] style(tests): order the docblock tags the way the fixer expects CI runs a newer php-cs-fixer than the local run did, and its phpdoc_order puts @throws before @return. The check failed on this file alone; every other finding in the job predates this branch. --- tests/Unit/Providers/DuckBugProviderTest.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/Unit/Providers/DuckBugProviderTest.php b/tests/Unit/Providers/DuckBugProviderTest.php index 4ad6a04..4dca184 100644 --- a/tests/Unit/Providers/DuckBugProviderTest.php +++ b/tests/Unit/Providers/DuckBugProviderTest.php @@ -324,8 +324,8 @@ public function testMintsDistinctEventIdsPerEvent(): void /** * @param array $payload - * @return array * @throws ReflectionException + * @return array */ private function captureSentLogPayload(array $payload, ?callable $beforeSend = null): array {