From 4bc585c4a88b593ff8e9b0d6a39b2142fc97b0af Mon Sep 17 00:00:00 2001 From: Proxynth Date: Tue, 7 Jul 2026 12:45:19 +0200 Subject: [PATCH] refactor: clarify larawebhook facade responsibilities --- docs/facade-api.md | 33 +++++++++++---- src/Shared/Application/Larawebhook.php | 42 ++++++++++++------- .../Laravel/Facades/Larawebhook.php | 7 ++-- 3 files changed, 56 insertions(+), 26 deletions(-) diff --git a/docs/facade-api.md b/docs/facade-api.md index b495a40..9353f6d 100644 --- a/docs/facade-api.md +++ b/docs/facade-api.md @@ -3,10 +3,28 @@ LaraWebhook provides a powerful Facade and an Enum for type-safe service handling. For the inbound request flow, see [Architecture](/architecture). For manual validation, always wrap raw signature headers with `Signature::fromString()`. -## Larawebhook Facade +## Role of the facade -The `Larawebhook` facade provides a fluent API for all webhook operations. -Prefer `validate()`, `validateAndLog()`, `validateWithRetries()`, and the read/query helpers for new code. +The `Larawebhook` facade is a Laravel-friendly public API. + +It is intentionally a DX adapter over application use cases, repositories and Laravel infrastructure services. It should not be treated as the place where core webhook workflows are implemented. + +Critical behavior belongs to dedicated use cases: + +- `ReceiveWebhook` for inbound middleware processing; +- `ValidateWebhook` for signature validation; +- `RecordWebhookLog` for audit persistence; +- `RetryWebhook` for retry attempts; +- `ReplayWebhook` for replay attempts. + +For new code, prefer the high-level helpers: + +- `validate()` +- `validateAndLog()` +- `validateWithRetries()` +- query/read helpers + +Manual logging helpers remain available for compatibility, but are deprecated. ### Validation @@ -20,13 +38,14 @@ Larawebhook::validate($payload, $signature, 'stripe'); $log = Larawebhook::validateAndLog($payload, $signature, 'github', 'push'); ``` -### Logging +#### Logging + +Manual logging helpers remain available for compatibility, but they are deprecated. -The manual logging helpers remain available for compatibility, but they are deprecated. -Prefer `validateAndLog()` or the corresponding application use case when you need to persist an audit log. +Prefer `validateAndLog()` when a webhook should be validated and persisted, or use `RecordWebhookLog` directly when writing internal package code. ```php -// Log webhooks manually +// Deprecated manual audit helpers Larawebhook::logSuccess('stripe', 'payment.succeeded', $payload); Larawebhook::logFailure('stripe', 'payment.failed', $payload, 'Card declined'); ``` diff --git a/src/Shared/Application/Larawebhook.php b/src/Shared/Application/Larawebhook.php index 564ce1b..345ee4f 100644 --- a/src/Shared/Application/Larawebhook.php +++ b/src/Shared/Application/Larawebhook.php @@ -23,10 +23,14 @@ use Proxynth\Larawebhook\Shared\Domain\Enums\WebhookService; /** - * Main entry point for the Larawebhook package. + * Laravel-friendly public API for LaraWebhook. * - * Provides a fluent API for webhook validation, logging, and querying. - * Prefer validate(), validateAndLog(), validateWithRetries(), and the read helpers. + * This class intentionally acts as a DX adapter around application use cases, + * repositories, and Laravel infrastructure services. + * + * It is not a pure application use case. + * Critical workflows should remain implemented in dedicated use cases such as + * ValidateWebhook, ReceiveWebhook, RetryWebhook, ReplayWebhook, and RecordWebhookLog. */ class Larawebhook { @@ -55,7 +59,7 @@ public function validate(string $payload, Signature $signature, string|WebhookSe $webhookService = $this->resolveService($service); $rawPayload = RawPayload::fromString($payload); - $secret = $this->getSecretResolver()->resolve($webhookService); + $secret = $this->getSecret($webhookService); if ($secret === null || $secret === '') { throw new WebhookException("No secret configured for service: {$webhookService->value}"); @@ -98,7 +102,10 @@ public function validateAndLog( } /** - * Validate a webhook with automatic retries. + * Validate a webhook with synchronous automatic retries. + * + * This is a Laravel-friendly facade helper kept for DX and backward compatibility. + * For asynchronous retry processing, prefer the ReceiveWebhook / RetryWebhook flow. * * @throws InvalidSignatureException * @throws WebhookException @@ -110,31 +117,33 @@ public function validateWithRetries( string $event ): WebhookLog { $webhookService = $this->resolveService($service); - $maxAttempts = $this->getRetryPolicyResolver()->resolve()->maxAttempts; + $retryPolicy = $this->getRetryPolicyResolver()->resolve(); - if ($maxAttempts <= 0) { + if ($retryPolicy->maxAttempts <= 0) { throw new WebhookException('Validation failed with no recorded exception.'); } - $delays = $this->getRetryPolicyResolver()->resolve()->delays; + $rawPayload = RawPayload::fromString($payload); + $externalId = $this->extractExternalId($webhookService, $rawPayload); + $lastLog = null; - for ($attempt = 0; $attempt < $maxAttempts; $attempt++) { + for ($attempt = 0; $attempt < $retryPolicy->maxAttempts; $attempt++) { $lastLog = $this->validateAndRecord( payload: $payload, signature: $signature, service: $webhookService, event: $event, attempt: $attempt, - externalId: $this->extractExternalId($webhookService, RawPayload::fromString($payload)), + externalId: $externalId, ); if ($lastLog->status !== 'failed') { return $lastLog; } - if ($attempt < $maxAttempts - 1) { - $delay = $delays[$attempt] ?? 0; + if ($retryPolicy->shouldRetryAfter($attempt)) { + $delay = $retryPolicy->delayForAttempt($attempt) ?? 0; if ($delay > 0) { sleep($delay); @@ -150,7 +159,7 @@ public function validateWithRetries( /** * Log a successful webhook. * - * @deprecated Use validateAndLog() or the corresponding application use case. + * @deprecated Prefer validateAndLog() for validated webhooks or RecordWebhookLog for explicit audit writes. */ public function logSuccess( string $service, @@ -165,14 +174,16 @@ public function logSuccess( valid: true, payload: $payload, attempt: $attempt, + externalId: null, idempotencyKey: $idempotencyKey, + errorMessage: null, )); } /** * Log a failed webhook. * - * @deprecated Use validateAndLog() or the corresponding application use case. + * @deprecated Prefer validateAndLog() for validated webhooks or RecordWebhookLog for explicit audit writes. */ public function logFailure( string $service, @@ -188,6 +199,7 @@ public function logFailure( valid: false, payload: $payload, attempt: $attempt, + externalId: null, idempotencyKey: $idempotencyKey, errorMessage: $errorMessage, )); @@ -453,7 +465,7 @@ private function validateAndRecord( ): WebhookLog { $webhookService = $this->resolveService($service); $rawPayload = RawPayload::fromString($payload); - $secret = $this->getSecretResolver()->resolve($webhookService); + $secret = $this->getSecret($webhookService); if ($secret === null || $secret === '') { throw new WebhookException("No secret configured for service: {$webhookService->value}"); diff --git a/src/Shared/Infrastructure/Laravel/Facades/Larawebhook.php b/src/Shared/Infrastructure/Laravel/Facades/Larawebhook.php index c64f493..a842b18 100644 --- a/src/Shared/Infrastructure/Laravel/Facades/Larawebhook.php +++ b/src/Shared/Infrastructure/Laravel/Facades/Larawebhook.php @@ -14,7 +14,6 @@ * @method static bool validate(string $payload, Signature $signature, string|WebhookService $service) * @method static WebhookLog validateAndLog(string $payload, Signature $signature, string|WebhookService $service, string $event) * @method static WebhookLog validateWithRetries(string $payload, Signature $signature, string|WebhookService $service, string $event) - * Legacy helpers logSuccess() and logFailure() are deprecated; prefer validateAndLog() and application use cases. * @method static WebhookLog logSuccess(string $service, string $event, array $payload, int $attempt = 0, ?string $idempotencyKey = null) * @method static WebhookLog logFailure(string $service, string $event, array $payload, string $errorMessage, int $attempt = 0, ?string $idempotencyKey = null) * @method static Collection logs() @@ -25,12 +24,12 @@ * @method static bool canSendNotification(string $service, string $event) * @method static bool sendNotificationIfNeeded(string $service, string $event) * @method static bool notificationsEnabled() - * @method static array getNotificationChannels() + * @method static array getNotificationChannels() * @method static void clearCooldown(string $service, string $event) * @method static ?string getSecret(string|WebhookService $service) * @method static bool isServiceSupported(string $service) - * @method static array supportedServices() - * @method static array services() + * @method static array supportedServices() + * @method static array services() * @method static ?WebhookService service(string $service) * * @see \Proxynth\Larawebhook\Shared\Application\Larawebhook