diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index f8bd9f5..448e3db 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -201,8 +201,23 @@ It may contain: Infrastructure may depend on Laravel and external libraries. Examples: +```text +src/Ingestion/Infrastructure/Laravel/Middleware/ValidateWebhook.php +src/Audit/Infrastructure/Laravel/Http/Controllers/WebhookLogController.php +src/Audit/Infrastructure/Laravel/Persistence/Models/WebhookLog.php +src/Shared/Infrastructure/Laravel/Providers/LarawebhookServiceProvider.php +``` + + +### Concurrency + +`processed_webhook_events` owns a database unique constraint on `service + idempotency_key`. + +The application first checks duplicates through `WebhookDuplicateDetector`, then records successful processing through `ProcessedWebhookRecorder`. + +If two identical webhooks are received concurrently, both requests may pass the initial duplicate check. The database unique constraint remains the final guard. -text src/Ingestion/Infrastructure/Laravel/Middleware/ValidateWebhook.php src/Audit/Infrastructure/Laravel/Http/Controllers/WebhookLogController.php src/Audit/Infrastructure/Laravel/Persistence/Models/WebhookLog.php src/Shared/Infrastructure/Laravel/Providers/LarawebhookServiceProvider.php +Duplicate insert collisions are converted into an `already_processed` result instead of surfacing as an infrastructure error. ## CQRS diff --git a/docs/architecture.md b/docs/architecture.md index 89d1831..3c91ded 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -64,6 +64,16 @@ Deduplication is backed by the `processed_webhook_events` projection. `webhook_logs` does not own any deduplication constraint. It is an audit trail and may contain multiple rows for the same webhook across receive, retry, replay or manual audit writes. +### Concurrency + +`processed_webhook_events` owns a database unique constraint on `service + idempotency_key`. + +The application first checks duplicates through `WebhookDuplicateDetector`, then records successful processing through `ProcessedWebhookRecorder`. + +If two identical webhooks are received concurrently, both requests may pass the initial duplicate check. The database unique constraint remains the final guard. + +Duplicate insert collisions are converted into an `already_processed` result instead of surfacing as an infrastructure error. + ### Historical migration `idempotency_key` was introduced after `external_id`. Older installations may contain webhook logs where `external_id` was used as the deduplication key. diff --git a/src/Ingestion/Application/UseCases/ReceiveWebhook.php b/src/Ingestion/Application/UseCases/ReceiveWebhook.php index fb8a597..e851c6d 100644 --- a/src/Ingestion/Application/UseCases/ReceiveWebhook.php +++ b/src/Ingestion/Application/UseCases/ReceiveWebhook.php @@ -127,12 +127,19 @@ public function handle(ReceiveWebhookCommand $command): ReceiveWebhookResult $webhookEvent->markProcessed(); if ($idempotencyKey !== null) { - $this->processedWebhookRecorder->recordProcessed( + $recordResult = $this->processedWebhookRecorder->recordProcessed( service: $provider->value(), idempotencyKey: $idempotencyKey->value(), externalId: $externalId, event: $validation->event, ); + + if ($recordResult->alreadyRecorded) { + return ReceiveWebhookResult::alreadyProcessed( + externalId: $externalId, + idempotencyKey: $idempotencyKey->value(), + ); + } } return ReceiveWebhookResult::success($log, [ diff --git a/src/Processing/Application/Ports/ProcessedWebhookRecorder.php b/src/Processing/Application/Ports/ProcessedWebhookRecorder.php index 1a7887d..20728ca 100644 --- a/src/Processing/Application/Ports/ProcessedWebhookRecorder.php +++ b/src/Processing/Application/Ports/ProcessedWebhookRecorder.php @@ -4,6 +4,8 @@ namespace Proxynth\Larawebhook\Processing\Application\Ports; +use Proxynth\Larawebhook\Processing\Application\Results\ProcessedWebhookRecordResult; + interface ProcessedWebhookRecorder { public function recordProcessed( @@ -11,5 +13,5 @@ public function recordProcessed( string $idempotencyKey, ?string $externalId, ?string $event, - ): void; + ): ProcessedWebhookRecordResult; } diff --git a/src/Processing/Application/Results/ProcessedWebhookRecordResult.php b/src/Processing/Application/Results/ProcessedWebhookRecordResult.php new file mode 100644 index 0000000..dd4f357 --- /dev/null +++ b/src/Processing/Application/Results/ProcessedWebhookRecordResult.php @@ -0,0 +1,23 @@ +firstOrCreate([ - 'service' => $service, - 'idempotency_key' => $idempotencyKey, - ], [ - 'external_id' => $externalId, - 'event' => $event, - 'processed_at' => now(), - ]); + ): ProcessedWebhookRecordResult { + try { + ProcessedWebhookEvent::query()->create([ + 'service' => $service, + 'idempotency_key' => $idempotencyKey, + 'external_id' => $externalId, + 'event' => $event, + 'processed_at' => now(), + ]); + + return ProcessedWebhookRecordResult::recorded(); + } catch (QueryException $exception) { + if ($this->isUniqueConstraintViolation($exception)) { + return ProcessedWebhookRecordResult::alreadyRecorded(); + } + + throw $exception; + } + } + + private function isUniqueConstraintViolation(QueryException $exception): bool + { + $sqlState = $exception->errorInfo[0] ?? null; + $driverCode = $exception->errorInfo[1] ?? null; + + return $sqlState === '23000' + || $sqlState === '23505' + || $driverCode === 1062 + || $driverCode === 19; } } diff --git a/tests/Fakes/Processing/FakeProcessedWebhookRecorder.php b/tests/Fakes/Processing/FakeProcessedWebhookRecorder.php index 2c7ed42..c3b4526 100644 --- a/tests/Fakes/Processing/FakeProcessedWebhookRecorder.php +++ b/tests/Fakes/Processing/FakeProcessedWebhookRecorder.php @@ -3,22 +3,33 @@ namespace Proxynth\Larawebhook\Tests\Fakes\Processing; use Proxynth\Larawebhook\Processing\Application\Ports\ProcessedWebhookRecorder; +use Proxynth\Larawebhook\Processing\Application\Results\ProcessedWebhookRecordResult; class FakeProcessedWebhookRecorder implements ProcessedWebhookRecorder { public array $records = []; + public function __construct( + private bool $alreadyRecorded = false, + ) {} + public function recordProcessed( string $service, string $idempotencyKey, ?string $externalId, ?string $event, - ): void { + ): ProcessedWebhookRecordResult { + if ($this->alreadyRecorded) { + return ProcessedWebhookRecordResult::alreadyRecorded(); + } + $this->records[] = [ 'service' => $service, 'idempotencyKey' => $idempotencyKey, 'externalId' => $externalId, 'event' => $event, ]; + + return ProcessedWebhookRecordResult::recorded(); } } diff --git a/tests/Unit/Ingestion/Application/UseCases/ReceiveWebhookTest.php b/tests/Unit/Ingestion/Application/UseCases/ReceiveWebhookTest.php index 0894292..2a41ed5 100644 --- a/tests/Unit/Ingestion/Application/UseCases/ReceiveWebhookTest.php +++ b/tests/Unit/Ingestion/Application/UseCases/ReceiveWebhookTest.php @@ -362,3 +362,35 @@ function githubPayload(string $deliveryId = 'delivery_123'): string expect($result->isSuccess())->toBeFalse() ->and($processedRecorder->records)->toBeEmpty(); }); + +it('returns already processed when processed event was recorded concurrently', function () { + $processedRecorder = new FakeProcessedWebhookRecorder( + alreadyRecorded: true, + ); + + app()->instance(ProcessedWebhookRecorder::class, $processedRecorder); + + app()->instance(WebhookSecretResolver::class, new FakeWebhookSecretResolver([ + 'github' => 'github_secret', + ])); + + $payload = json_encode([ + 'type' => 'custom.event', + 'data' => [ + 'foo' => 'bar', + ], + ], JSON_THROW_ON_ERROR); + + $signature = githubSignature($payload); + + $result = app(ReceiveWebhook::class)->handle(new ReceiveWebhookCommand( + service: WebhookService::Github, + payload: $payload, + signature: $signature, + externalIdHeaderValue: 'delivery_123', + )); + + expect($result->isAlreadyProcessed())->toBeTrue() + ->and($result->externalId)->toBe('delivery_123') + ->and($result->idempotencyKey)->toBe('delivery_123'); +}); diff --git a/tests/Unit/Processing/Application/Results/ProcessedWebhookRecordResultTest.php b/tests/Unit/Processing/Application/Results/ProcessedWebhookRecordResultTest.php new file mode 100644 index 0000000..14a99dc --- /dev/null +++ b/tests/Unit/Processing/Application/Results/ProcessedWebhookRecordResultTest.php @@ -0,0 +1,19 @@ +recorded)->toBeTrue() + ->and($result->alreadyRecorded)->toBeFalse(); +}); + +it('represents already recorded processed webhook event', function () { + $result = ProcessedWebhookRecordResult::alreadyRecorded(); + + expect($result->recorded)->toBeFalse() + ->and($result->alreadyRecorded)->toBeTrue(); +}); diff --git a/tests/Unit/Processing/Infrastructure/Persistence/EloquentProcessedWebhookRecorderTest.php b/tests/Unit/Processing/Infrastructure/Persistence/EloquentProcessedWebhookRecorderTest.php index 608e4ac..3f9a9a5 100644 --- a/tests/Unit/Processing/Infrastructure/Persistence/EloquentProcessedWebhookRecorderTest.php +++ b/tests/Unit/Processing/Infrastructure/Persistence/EloquentProcessedWebhookRecorderTest.php @@ -25,15 +25,6 @@ ->and($processed->processed_at)->not->toBeNull(); }); -it('does not create duplicate processed event for same service and idempotency key', function () { - $recorder = app(EloquentProcessedWebhookRecorder::class); - - $recorder->recordProcessed('github', 'delivery_123', 'delivery_123', 'push'); - $recorder->recordProcessed('github', 'delivery_123', 'delivery_123', 'push'); - - expect(ProcessedWebhookEvent::query()->count())->toBe(1); -}); - it('enforces unique constraint on processed webhook events service and idempotency key', function () { ProcessedWebhookEvent::query()->create([ 'service' => 'stripe', @@ -51,3 +42,27 @@ 'processed_at' => now(), ]))->toThrow(QueryException::class); }); + +it('returns already recorded when processed webhook already exists', function () { + $recorder = app(EloquentProcessedWebhookRecorder::class); + + $first = $recorder->recordProcessed( + service: 'github', + idempotencyKey: 'delivery_123', + externalId: 'delivery_123', + event: 'push', + ); + + $second = $recorder->recordProcessed( + service: 'github', + idempotencyKey: 'delivery_123', + externalId: 'delivery_123', + event: 'push', + ); + + expect($first->recorded)->toBeTrue() + ->and($first->alreadyRecorded)->toBeFalse() + ->and($second->recorded)->toBeFalse() + ->and($second->alreadyRecorded)->toBeTrue() + ->and(ProcessedWebhookEvent::query()->count())->toBe(1); +});