update to provisioner code

This commit is contained in:
Mark Gregory
2026-09-30 12:55:32 +01:00
parent 6850a00e76
commit 58eec7da9a
2 changed files with 378 additions and 172 deletions
@@ -11,6 +11,8 @@ use App\Services\Payments\PurchaseProvisioner;
use Illuminate\Http\JsonResponse; use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request; use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB; use Illuminate\Support\Facades\DB;
use RuntimeException;
use Throwable;
final class PaymentWebhookController extends Controller final class PaymentWebhookController extends Controller
{ {
@@ -36,7 +38,7 @@ final class PaymentWebhookController extends Controller
try { try {
$verifier->verify($request, $raw); $verifier->verify($request, $raw);
} catch (\Throwable $e) { } catch (Throwable $e) {
report($e); report($e);
return response()->json([ return response()->json([
@@ -50,7 +52,7 @@ final class PaymentWebhookController extends Controller
true, true,
flags: JSON_THROW_ON_ERROR flags: JSON_THROW_ON_ERROR
); );
} catch (\Throwable) { } catch (Throwable) {
return response()->json([ return response()->json([
'message' => 'Invalid JSON.', 'message' => 'Invalid JSON.',
], 400); ], 400);
@@ -76,16 +78,16 @@ final class PaymentWebhookController extends Controller
], 400); ], 400);
} }
$payloadHash = hash('sha256', $raw);
try { try {
/* /*
* Paddle can deliver several related webhook events at almost * Paddle can deliver several related events concurrently.
* exactly the same time.
* *
* Laravel will automatically retry the entire transaction when * Laravel retries this complete transaction when MySQL reports
* MySQL reports a deadlock / serialization failure. * a deadlock. Five attempts gives short-lived lock contention
* * enough opportunity to resolve without acknowledging an event
* Five attempts gives short-lived webhook contention time to * that was not actually processed.
* resolve without weakening any database constraints.
*/ */
DB::transaction( DB::transaction(
function () use ( function () use (
@@ -93,15 +95,14 @@ final class PaymentWebhookController extends Controller
$externalID, $externalID,
$eventType, $eventType,
$payload, $payload,
$raw, $payloadHash,
$provisioner $provisioner
): void { ): void {
/* /*
* firstOrCreate protects against Paddle retrying the exact * Insert the event if this is its first delivery.
* same event ID.
* *
* lockForUpdate prevents two workers handling the same * Once present, lock the row so duplicate deliveries of
* webhook event concurrently after the row exists. * the same event cannot provision concurrently.
*/ */
LicenseWebhookEvent::firstOrCreate( LicenseWebhookEvent::firstOrCreate(
[ [
@@ -110,7 +111,7 @@ final class PaymentWebhookController extends Controller
], ],
[ [
'event_type' => $eventType, 'event_type' => $eventType,
'payload_sha256' => hash('sha256', $raw), 'payload_sha256' => $payloadHash,
'payload' => $payload, 'payload' => $payload,
] ]
); );
@@ -121,27 +122,15 @@ final class PaymentWebhookController extends Controller
->lockForUpdate() ->lockForUpdate()
->firstOrFail(); ->firstOrFail();
/* if ($event->processed_at) {
* Already successfully processed.
*
* Returning here makes duplicate delivery of the exact
* same Paddle event idempotent.
*/
if ($event->processed_at !== null) {
return; return;
} }
/*
* An external event ID must never be reused with different
* content.
*/
$incomingHash = hash('sha256', $raw);
if (! hash_equals( if (! hash_equals(
(string) $event->payload_sha256, (string) $event->payload_sha256,
$incomingHash $payloadHash
)) { )) {
throw new \RuntimeException( throw new RuntimeException(
'Webhook ID was reused with a different payload.' 'Webhook ID was reused with a different payload.'
); );
} }
@@ -152,31 +141,30 @@ final class PaymentWebhookController extends Controller
$payload $payload
); );
$event->update([ $event->processed_at = now();
'processed_at' => now(), $event->processing_error = null;
'processing_error' => null, $event->save();
]); } catch (Throwable $e) {
} catch (\Throwable $e) {
/* /*
* This update is part of the same transaction. * This assignment is useful when the surrounding
* * transaction eventually succeeds. If processing
* If processing fails and the transaction rolls back, * throws, the transaction itself is rolled back and
* Paddle can retry the webhook normally. * Paddle will retry the event.
*/ */
$event->update([ $event->processing_error = mb_substr(
'processing_error' => mb_substr( $e->getMessage(),
$e->getMessage(), 0,
0, 4000
4000 );
),
]); $event->save();
throw $e; throw $e;
} }
}, },
5 5
); );
} catch (\Throwable $e) { } catch (Throwable $e) {
report($e); report($e);
return response()->json([ return response()->json([
@@ -189,15 +177,15 @@ final class PaymentWebhookController extends Controller
} }
/* /*
* Delivery is intentionally outside the webhook transaction. * Delivery deliberately happens outside the webhook transaction.
* *
* A temporary mail outage must not roll back an otherwise valid * A temporary SMTP failure must not undo a successfully processed
* payment event. Pending outbox rows remain available for portal * payment event. The outbox retains anything that still needs
* resend or a later webhook delivery attempt. * delivery.
*/ */
try { try {
$delivery->deliverPending(10); $delivery->deliverPending(10);
} catch (\Throwable $e) { } catch (Throwable $e) {
report($e); report($e);
} }
+338 -120
View File
@@ -8,7 +8,9 @@ use App\Models\LicenseProduct;
use App\Services\Accounts\PurchasedAccountProvisioner; use App\Services\Accounts\PurchasedAccountProvisioner;
use App\Services\Licensing\LicenseIssuer; use App\Services\Licensing\LicenseIssuer;
use Illuminate\Support\Carbon; use Illuminate\Support\Carbon;
use Illuminate\Support\Facades\DB;
use RuntimeException; use RuntimeException;
use Throwable;
final class PurchaseProvisioner final class PurchaseProvisioner
{ {
@@ -32,16 +34,24 @@ final class PurchaseProvisioner
return; return;
} }
throw new RuntimeException('Unsupported payment provider.'); throw new RuntimeException(
'Unsupported payment provider.'
);
} }
private function provisionPaddle(array $event): void private function provisionPaddle(array $event): void
{ {
$type = (string) ($event['event_type'] ?? ''); $type = (string) ($event['event_type'] ?? '');
$data = $event['data'] ?? [];
$data = is_array($event['data'] ?? null)
? $event['data']
: [];
if (str_starts_with($type, 'subscription.')) { if (str_starts_with($type, 'subscription.')) {
$this->syncPaddleSubscription($type, $data); $this->syncPaddleSubscription(
$type,
$data
);
return; return;
} }
@@ -53,11 +63,17 @@ final class PurchaseProvisioner
} }
if ($type === 'transaction.refunded') { if ($type === 'transaction.refunded') {
$transactionID = (string) ($data['id'] ?? ''); $transactionID = $this->nullableString(
$data['id'] ?? null
);
if ($transactionID !== '') { if ($transactionID !== null) {
License::where('payment_provider', 'paddle') License::query()
->where('external_order_id', $transactionID) ->where('payment_provider', 'paddle')
->where(
'external_order_id',
$transactionID
)
->whereNull('external_subscription_id') ->whereNull('external_subscription_id')
->whereNull('revoked_at') ->whereNull('revoked_at')
->update([ ->update([
@@ -68,35 +84,67 @@ final class PurchaseProvisioner
} }
} }
private function syncPaddleSubscription(string $type, array $data): void private function syncPaddleSubscription(
{ string $type,
$subscriptionID = (string) ($data['id'] ?? ''); array $data
): void {
$subscriptionID = $this->nullableString(
$data['id'] ?? null
);
if ($subscriptionID === '') { if ($subscriptionID === null) {
throw new RuntimeException( throw new RuntimeException(
'Paddle subscription webhook has no subscription ID.' 'Paddle subscription webhook has no subscription ID.'
); );
} }
/* /*
* Paddle webhook delivery order is not guaranteed. * Multiple Paddle events for the same subscription can arrive
* simultaneously.
* *
* A transaction.completed event can arrive before the corresponding * The unique index protects database integrity, but by itself it
* subscription event has created our local licence. Capture the * cannot stop two workers from both observing "no licence" before
* transaction ID from the subscription payload as well whenever * either worker inserts the subscription ID.
* Paddle provides one. *
* A MySQL advisory lock serialises provisioning for one Paddle
* subscription while still allowing unrelated subscriptions to be
* processed concurrently.
*/ */
$lockName = 'sonardesk:paddle:subscription:'
.$subscriptionID;
$this->withMysqlLock(
$lockName,
function () use (
$type,
$data,
$subscriptionID
): void {
$this->syncLockedPaddleSubscription(
$type,
$data,
$subscriptionID
);
}
);
}
private function syncLockedPaddleSubscription(
string $type,
array $data,
string $subscriptionID
): void {
$transactionID = $this->nullableString( $transactionID = $this->nullableString(
$data['transaction_id'] ?? null $data['transaction_id'] ?? null
); );
$status = (string) ($data['status'] ?? ''); $status = (string) ($data['status'] ?? '');
$item = $this->firstRecurringItem( $items = is_array($data['items'] ?? null)
is_array($data['items'] ?? null) ? $data['items']
? $data['items'] : [];
: []
); $item = $this->firstRecurringItem($items);
$price = is_array($item['price'] ?? null) $price = is_array($item['price'] ?? null)
? $item['price'] ? $item['price']
@@ -115,11 +163,20 @@ final class PurchaseProvisioner
); );
/* /*
* Subscription ID is the authoritative identity for recurring * The Paddle subscription ID is the authoritative identity for a
* Paddle licences. * recurring licence.
*
* lockForUpdate protects an existing licence while we mutate it.
* Creation of a missing licence is serialised by the advisory lock
* acquired by syncPaddleSubscription().
*/ */
$license = License::where('payment_provider', 'paddle') $license = License::query()
->where('external_subscription_id', $subscriptionID) ->where('payment_provider', 'paddle')
->where(
'external_subscription_id',
$subscriptionID
)
->lockForUpdate()
->first(); ->first();
if (! $license) { if (! $license) {
@@ -137,13 +194,10 @@ final class PurchaseProvisioner
$data['customer_id'] ?? null $data['customer_id'] ?? null
); );
$customer = $this->paddle->customer($customerID) ?? []; $customer = $this->paddle->customer(
$customerID
) ?? [];
/*
* Use the transaction ID as the initial external order ID where
* available. If it is absent, transaction.completed can backfill
* it later.
*/
[$license] = $this->issuer->issue( [$license] = $this->issuer->issue(
$product, $product,
$this->nullableString( $this->nullableString(
@@ -164,19 +218,42 @@ final class PurchaseProvisioner
true, true,
); );
$this->accounts->ensure( /*
$license->customer_email, * LicenseIssuer may return an existing licence if the
$license->customer_name * transaction ID has already been seen.
); *
* Re-read it with a row lock before attaching the Paddle
* subscription.
*/
$license = License::query()
->whereKey($license->getKey())
->lockForUpdate()
->firstOrFail();
$license->external_subscription_id = $subscriptionID; /*
* Do not attach this subscription to a licence already owned
* by a different subscription.
*/
if (
$license->external_subscription_id !== null
&& $license->external_subscription_id
!== $subscriptionID
) {
throw new RuntimeException(
'Paddle transaction resolved to a licence '
.'belonging to another subscription.'
);
}
$license->external_subscription_id =
$subscriptionID;
} elseif ( } elseif (
$priceID !== '' $priceID !== ''
&& $priceID !== $license->external_price_id && $priceID !== $license->external_price_id
) { ) {
/* /*
* Upgrades/downgrades change the entitlement attached to the * Upgrades and downgrades modify the entitlement attached to
* existing licence key. * the existing licence key rather than issuing another key.
*/ */
$product = $this->mappedProduct( $product = $this->mappedProduct(
'paddle', 'paddle',
@@ -186,11 +263,15 @@ final class PurchaseProvisioner
$license->license_product_id = $product->id; $license->license_product_id = $product->id;
$license->edition = $product->edition; $license->edition = $product->edition;
$license->activation_limit = $product->activation_limit; $license->activation_limit =
$license->max_major_version = $product->max_major_version; $product->activation_limit;
$license->max_major_version =
$product->max_major_version;
} }
$periodEnd = $data['current_billing_period']['ends_at'] ?? null; $periodEnd =
$data['current_billing_period']['ends_at']
?? null;
$scheduled = $data['scheduled_change'] ?? null; $scheduled = $data['scheduled_change'] ?? null;
@@ -200,14 +281,18 @@ final class PurchaseProvisioner
: null; : null;
$license->external_customer_id = $license->external_customer_id =
$this->nullableString($data['customer_id'] ?? null) $this->nullableString(
$data['customer_id'] ?? null
)
?? $license->external_customer_id; ?? $license->external_customer_id;
$this->backfillPaddleCustomer($license, $data); $this->backfillPaddleCustomer(
$license,
$data
);
/* /*
* ensure() must be idempotent. Existing users must simply be * Account provisioning is expected to be idempotent.
* returned rather than created again.
*/ */
$this->accounts->ensure( $this->accounts->ensure(
$license->customer_email, $license->customer_email,
@@ -218,8 +303,12 @@ final class PurchaseProvisioner
$license->external_price_id = $priceID; $license->external_price_id = $priceID;
} }
if ($transactionID && ! $license->external_order_id) { if (
$license->external_order_id = $transactionID; $transactionID !== null
&& ! $license->external_order_id
) {
$license->external_order_id =
$transactionID;
} }
if ($status !== '') { if ($status !== '') {
@@ -227,7 +316,8 @@ final class PurchaseProvisioner
} }
if ($periodEnd) { if ($periodEnd) {
$license->current_period_ends_at = Carbon::parse($periodEnd); $license->current_period_ends_at =
Carbon::parse($periodEnd);
} }
$license->cancel_scheduled_at = $cancelAt $license->cancel_scheduled_at = $cancelAt
@@ -235,41 +325,51 @@ final class PurchaseProvisioner
: null; : null;
/* /*
* Entitlement handling. * Subscription entitlement.
*/ */
if (in_array($status, ['active', 'trialing'], true)) { if (in_array(
$status,
['active', 'trialing'],
true
)) {
$license->revoked_at = null; $license->revoked_at = null;
$license->revoke_reason = null; $license->revoke_reason = null;
/*
* Active/trialing subscriptions remain valid through the
* current Paddle billing period.
*/
$license->expires_at = $periodEnd $license->expires_at = $periodEnd
? Carbon::parse($periodEnd) ? Carbon::parse($periodEnd)
: null; : null;
} elseif ($status === 'past_due') { } elseif ($status === 'past_due') {
/* /*
* Do not revoke immediately after the first failed renewal. * A failed renewal does not immediately destroy the
* Preserve Paddle's current billing period where possible. * entitlement. Preserve Paddle's current billing period when
* available and otherwise provide the existing grace period.
*/ */
$license->expires_at = $periodEnd $license->expires_at = $periodEnd
? Carbon::parse($periodEnd) ? Carbon::parse($periodEnd)
: ($license->expires_at ?? now()->addDays(7)); : (
} elseif (in_array($status, ['canceled', 'paused'], true)) { $license->expires_at
?? now()->addDays(7)
);
} elseif (in_array(
$status,
['canceled', 'paused'],
true
)) {
$license->expires_at = now(); $license->expires_at = now();
$license->revoked_at = now(); $license->revoked_at = now();
$license->revoke_reason = $status === 'paused' $license->revoke_reason =
? 'Subscription paused' $status === 'paused'
: 'Subscription canceled'; ? 'Subscription paused'
: 'Subscription canceled';
} }
$license->save(); $license->save();
} }
private function syncPaddleTransaction(array $data): void private function syncPaddleTransaction(
{ array $data
): void {
$subscriptionID = $this->nullableString( $subscriptionID = $this->nullableString(
$data['subscription_id'] ?? null $data['subscription_id'] ?? null
); );
@@ -279,28 +379,58 @@ final class PurchaseProvisioner
); );
/* /*
* Recurring transactions belong to an existing subscription. * A recurring transaction belongs to its subscription.
* *
* The subscription event normally creates the licence. If the * Serialise this operation using the same lock as subscription
* transaction event arrives afterwards we simply backfill the * provisioning. This prevents transaction.completed from updating
* transaction/order ID. * the licence while a subscription event is still creating or
* * modifying it.
* If transaction.completed arrives first, it does nothing here.
* The subsequent subscription event will obtain transaction_id
* directly from its payload where Paddle supplies it.
*/ */
if ($subscriptionID) { if ($subscriptionID !== null) {
if ($transactionID) { $lockName = 'sonardesk:paddle:subscription:'
License::where('payment_provider', 'paddle') .$subscriptionID;
->where(
'external_subscription_id', $this->withMysqlLock(
$subscriptionID $lockName,
) function () use (
->whereNull('external_order_id') $subscriptionID,
->update([ $transactionID
'external_order_id' => $transactionID, ): void {
]); if ($transactionID === null) {
} return;
}
$license = License::query()
->where(
'payment_provider',
'paddle'
)
->where(
'external_subscription_id',
$subscriptionID
)
->lockForUpdate()
->first();
/*
* transaction.completed may legitimately arrive before
* subscription.created. In that case there is nothing
* to update yet. The subscription event will create the
* licence and Paddle's transaction_id can populate the
* order ID.
*/
if (! $license) {
return;
}
if (! $license->external_order_id) {
$license->external_order_id =
$transactionID;
$license->save();
}
}
);
return; return;
} }
@@ -344,7 +474,9 @@ final class PurchaseProvisioner
$data['customer_id'] ?? null $data['customer_id'] ?? null
); );
$customer = $this->paddle->customer($customerID) ?? []; $customer = $this->paddle->customer(
$customerID
) ?? [];
[$license] = $this->issuer->issue( [$license] = $this->issuer->issue(
$product, $product,
@@ -372,8 +504,9 @@ final class PurchaseProvisioner
); );
} }
private function provisionLemonSqueezy(array $event): void private function provisionLemonSqueezy(
{ array $event
): void {
$type = (string) ( $type = (string) (
$event['meta']['event_name'] $event['meta']['event_name']
?? '' ?? ''
@@ -393,13 +526,17 @@ final class PurchaseProvisioner
if (in_array( if (in_array(
$type, $type,
['order_refunded', 'subscription_expired'], [
'order_refunded',
'subscription_expired',
],
true true
)) { )) {
License::where( License::query()
'payment_provider', ->where(
'lemon-squeezy' 'payment_provider',
) 'lemon-squeezy'
)
->where('external_order_id', $order) ->where('external_order_id', $order)
->whereNull('revoked_at') ->whereNull('revoked_at')
->update([ ->update([
@@ -413,7 +550,10 @@ final class PurchaseProvisioner
if (! in_array( if (! in_array(
$type, $type,
['order_created', 'subscription_created'], [
'order_created',
'subscription_created',
],
true true
)) { )) {
return; return;
@@ -421,8 +561,14 @@ final class PurchaseProvisioner
$product = $this->mappedProduct( $product = $this->mappedProduct(
'lemon-squeezy', 'lemon-squeezy',
(string) ($attributes['variant_id'] ?? ''), (string) (
(string) ($attributes['product_id'] ?? ''), $attributes['variant_id']
?? ''
),
(string) (
$attributes['product_id']
?? ''
),
); );
[$license] = $this->issuer->issue( [$license] = $this->issuer->issue(
@@ -451,7 +597,9 @@ final class PurchaseProvisioner
License $license, License $license,
array $data array $data
): void { ): void {
$custom = is_array($data['custom_data'] ?? null) $custom = is_array(
$data['custom_data'] ?? null
)
? $data['custom_data'] ? $data['custom_data']
: []; : [];
@@ -460,7 +608,9 @@ final class PurchaseProvisioner
?? $license->external_customer_id ?? $license->external_customer_id
); );
$customer = $this->paddle->customer($customerID) ?? []; $customer = $this->paddle->customer(
$customerID
) ?? [];
$name = $this->nullableString( $name = $this->nullableString(
$custom['customer_name'] $custom['customer_name']
@@ -485,10 +635,11 @@ final class PurchaseProvisioner
$license->customer_email = $email; $license->customer_email = $email;
LicenseDeliveryOutbox::where( LicenseDeliveryOutbox::query()
'license_id', ->where(
$license->id 'license_id',
) $license->id
)
->whereNull('delivered_at') ->whereNull('delivered_at')
->update([ ->update([
'recipient_email' => $email, 'recipient_email' => $email,
@@ -502,26 +653,31 @@ final class PurchaseProvisioner
string $productID string $productID
): LicenseProduct { ): LicenseProduct {
/* /*
* Price IDs are authoritative. * Price IDs are authoritative because multiple billing intervals
* * can belong to the same Paddle product.
* Monthly and annual Paddle prices can intentionally belong to the
* same Paddle product, therefore product ID alone cannot reliably
* identify the licence plan.
*/ */
if ($priceID !== '') { if ($priceID !== '') {
$product = LicenseProduct::where( $product = LicenseProduct::query()
'payment_provider', ->where(
$provider 'payment_provider',
) $provider
->where('external_price_id', $priceID) )
->where(
'external_price_id',
$priceID
)
->where('active', true) ->where('active', true)
->first(); ->first();
} else { } else {
$product = LicenseProduct::where( $product = LicenseProduct::query()
'payment_provider', ->where(
$provider 'payment_provider',
) $provider
->where('external_product_id', $productID) )
->where(
'external_product_id',
$productID
)
->where('active', true) ->where('active', true)
->first(); ->first();
} }
@@ -536,8 +692,9 @@ final class PurchaseProvisioner
return $product; return $product;
} }
private function firstRecurringItem(array $items): array private function firstRecurringItem(
{ array $items
): array {
foreach ($items as $item) { foreach ($items as $item) {
if (! is_array($item)) { if (! is_array($item)) {
continue; continue;
@@ -550,11 +707,14 @@ final class PurchaseProvisioner
$first = $items[0] ?? []; $first = $items[0] ?? [];
return is_array($first) ? $first : []; return is_array($first)
? $first
: [];
} }
private function nullableString(mixed $value): ?string private function nullableString(
{ mixed $value
): ?string {
if (! is_scalar($value)) { if (! is_scalar($value)) {
return null; return null;
} }
@@ -565,4 +725,62 @@ final class PurchaseProvisioner
? null ? null
: $value; : $value;
} }
/**
* Execute a callback while holding a MySQL advisory lock.
*
* The lock is connection-scoped, so it must always be explicitly
* released in finally. A short timeout is sufficient because Paddle
* will retry failed webhook deliveries and the controller also retries
* database deadlocks.
*/
private function withMysqlLock(
string $name,
callable $callback
): mixed {
/*
* MySQL advisory lock names have a finite length. Hashing also
* prevents provider supplied identifiers from creating unusual
* lock names.
*/
$lockName = 'sd:'.hash('sha256', $name);
$row = DB::selectOne(
'SELECT GET_LOCK(?, ?) AS acquired',
[
$lockName,
10,
]
);
$acquired = (int) (
$row->acquired
?? 0
);
if ($acquired !== 1) {
throw new RuntimeException(
'Could not acquire Paddle subscription lock.'
);
}
try {
return $callback();
} finally {
try {
DB::selectOne(
'SELECT RELEASE_LOCK(?) AS released',
[$lockName]
);
} catch (Throwable $e) {
/*
* Do not hide the original processing exception merely
* because releasing an advisory lock failed. MySQL also
* releases connection-owned locks when the connection
* closes.
*/
report($e);
}
}
}
} }