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
17 changes: 16 additions & 1 deletion ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
10 changes: 10 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
9 changes: 8 additions & 1 deletion src/Ingestion/Application/UseCases/ReceiveWebhook.php
Original file line number Diff line number Diff line change
Expand Up @@ -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, [
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,14 @@

namespace Proxynth\Larawebhook\Processing\Application\Ports;

use Proxynth\Larawebhook\Processing\Application\Results\ProcessedWebhookRecordResult;

interface ProcessedWebhookRecorder
{
public function recordProcessed(
string $service,
string $idempotencyKey,
?string $externalId,
?string $event,
): void;
): ProcessedWebhookRecordResult;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
<?php

declare(strict_types=1);

namespace Proxynth\Larawebhook\Processing\Application\Results;

final readonly class ProcessedWebhookRecordResult
{
private function __construct(
public bool $recorded,
public bool $alreadyRecorded,
) {}

public static function recorded(): self
{
return new self(true, false);
}

public static function alreadyRecorded(): self
{
return new self(false, true);
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -4,24 +4,46 @@

namespace Proxynth\Larawebhook\Processing\Infrastructure\Persistence;

use Illuminate\Database\QueryException;
use Proxynth\Larawebhook\Processing\Application\Ports\ProcessedWebhookRecorder;
use Proxynth\Larawebhook\Processing\Application\Results\ProcessedWebhookRecordResult;
use Proxynth\Larawebhook\Processing\Infrastructure\Persistence\Models\ProcessedWebhookEvent;

class EloquentProcessedWebhookRecorder implements ProcessedWebhookRecorder
final readonly class EloquentProcessedWebhookRecorder implements ProcessedWebhookRecorder
{
public function recordProcessed(
string $service,
string $idempotencyKey,
?string $externalId,
?string $event,
): void {
ProcessedWebhookEvent::query()->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;
}
}
13 changes: 12 additions & 1 deletion tests/Fakes/Processing/FakeProcessedWebhookRecorder.php
Original file line number Diff line number Diff line change
Expand Up @@ -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();
}
}
32 changes: 32 additions & 0 deletions tests/Unit/Ingestion/Application/UseCases/ReceiveWebhookTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -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');
});
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<?php

declare(strict_types=1);

use Proxynth\Larawebhook\Processing\Application\Results\ProcessedWebhookRecordResult;

it('represents recorded processed webhook event', function () {
$result = ProcessedWebhookRecordResult::recorded();

expect($result->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();
});
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand All @@ -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);
});