From ce15eeb7229dff70114951c5c5bf9594b82e042f Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Wed, 29 Apr 2026 07:17:04 +0100 Subject: [PATCH] refactor: introduce Lock facade for platform-DB lock sites MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extracts the lock-key format and the lock+auth-skip+sparse-update pattern into Appwrite\Locking\Lock with three methods: - set(collection, id, attribute=accessedAt, value=null) — throttled single-attribute write - run(collection, id, fn) — generic skip-on-contention - runOrFail(collection, id, fn) — block-then-409 for the deferred lost-update follow-up Migrates the 4 call sites (router projects accessedAt + 3 in shared/api) off the raw $distributedLock callable. Raw factories stay as escape hatches for non-platform key shapes. --- app/controllers/general.php | 33 ++++++++---------- app/controllers/shared/api.php | 19 ++++------ app/init/resources/request.php | 10 ++++++ src/Appwrite/Locking/Lock.php | 63 ++++++++++++++++++++++++++++++++++ 4 files changed, 94 insertions(+), 31 deletions(-) create mode 100644 src/Appwrite/Locking/Lock.php diff --git a/app/controllers/general.php b/app/controllers/general.php index 0fde400b89..9381843b64 100644 --- a/app/controllers/general.php +++ b/app/controllers/general.php @@ -11,6 +11,7 @@ use Appwrite\Event\Delete as DeleteEvent; use Appwrite\Event\Event; use Appwrite\Event\Publisher\Certificate; use Appwrite\Extend\Exception as AppwriteException; +use Appwrite\Locking\Lock; use Appwrite\Network\Cors; use Appwrite\Platform\Appwrite; use Appwrite\SDK\Method; @@ -67,7 +68,7 @@ use Utopia\Validator\Text; Config::setParam('cookieSamesite', Response::COOKIE_SAMESITE_NONE); -function router(Http $utopia, Database $dbForPlatform, callable $getProjectDB, SwooleRequest $swooleRequest, Request $request, Response $response, Log $log, Event $queueForEvents, Bus $bus, Executor $executor, Reader $geodb, callable $isResourceBlocked, array $platform, string $previewHostname, Authorization $authorization, ?Key $apiKey, DeleteEvent $queueForDeletes, int $executionsRetentionCount, callable $distributedLock) +function router(Http $utopia, Database $dbForPlatform, callable $getProjectDB, SwooleRequest $swooleRequest, Request $request, Response $response, Log $log, Event $queueForEvents, Bus $bus, Executor $executor, Reader $geodb, callable $isResourceBlocked, array $platform, string $previewHostname, Authorization $authorization, ?Key $apiKey, DeleteEvent $queueForDeletes, int $executionsRetentionCount, Lock $lock) { $host = $request->getHostname(); if (!empty($previewHostname)) { @@ -136,11 +137,7 @@ function router(Http $utopia, Database $dbForPlatform, callable $getProjectDB, S if (!$project->isEmpty() && $project->getId() !== 'console') { $accessedAt = $project->getAttribute('accessedAt', 0); if (DateTime::formatTz(DateTime::addSeconds(new \DateTime(), -APP_PROJECT_ACCESS)) > $accessedAt) { - $distributedLock('lock:platform:projects:' . $project->getId(), function () use ($dbForPlatform, $project, $authorization) { - $authorization->skip(fn () => $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ - 'accessedAt' => DateTime::now() - ]))); - }); + $lock->set('projects', $project->getId()); } /** @@ -849,8 +846,8 @@ Http::init() ->inject('authorization') ->inject('queueForDeletes') ->inject('executionsRetentionCount') - ->inject('distributedLock') - ->action(function (Http $utopia, SwooleRequest $swooleRequest, Request $request, Response $response, Log $log, Document $project, Database $dbForPlatform, callable $getProjectDB, Locale $locale, array $localeCodes, Reader $geodb, Event $queueForEvents, Bus $bus, Executor $executor, array $platform, callable $isResourceBlocked, string $previewHostname, Document $devKey, ?Key $apiKey, Cors $cors, Authorization $authorization, DeleteEvent $queueForDeletes, int $executionsRetentionCount, callable $distributedLock) { + ->inject('lock') + ->action(function (Http $utopia, SwooleRequest $swooleRequest, Request $request, Response $response, Log $log, Document $project, Database $dbForPlatform, callable $getProjectDB, Locale $locale, array $localeCodes, Reader $geodb, Event $queueForEvents, Bus $bus, Executor $executor, array $platform, callable $isResourceBlocked, string $previewHostname, Document $devKey, ?Key $apiKey, Cors $cors, Authorization $authorization, DeleteEvent $queueForDeletes, int $executionsRetentionCount, Lock $lock) { /* * Appwrite Router */ @@ -858,7 +855,7 @@ Http::init() $platformHostnames = $platform['hostnames'] ?? []; // Only run Router when external domain if (!\in_array($hostname, $platformHostnames) || !empty($previewHostname)) { - if (router($utopia, $dbForPlatform, $getProjectDB, $swooleRequest, $request, $response, $log, $queueForEvents, $bus, $executor, $geodb, $isResourceBlocked, $platform, $previewHostname, $authorization, $apiKey, $queueForDeletes, $executionsRetentionCount, $distributedLock)) { + if (router($utopia, $dbForPlatform, $getProjectDB, $swooleRequest, $request, $response, $log, $queueForEvents, $bus, $executor, $geodb, $isResourceBlocked, $platform, $previewHostname, $authorization, $apiKey, $queueForDeletes, $executionsRetentionCount, $lock)) { $utopia->getRoute()?->label('router', true); } } @@ -1143,15 +1140,15 @@ Http::options() ->inject('authorization') ->inject('queueForDeletes') ->inject('executionsRetentionCount') - ->inject('distributedLock') - ->action(function (Http $utopia, SwooleRequest $swooleRequest, Request $request, Response $response, Log $log, Database $dbForPlatform, callable $getProjectDB, Event $queueForEvents, Bus $bus, Executor $executor, Reader $geodb, callable $isResourceBlocked, array $platform, string $previewHostname, Document $project, Document $devKey, ?Key $apiKey, Cors $cors, Authorization $authorization, DeleteEvent $queueForDeletes, int $executionsRetentionCount, callable $distributedLock) { + ->inject('lock') + ->action(function (Http $utopia, SwooleRequest $swooleRequest, Request $request, Response $response, Log $log, Database $dbForPlatform, callable $getProjectDB, Event $queueForEvents, Bus $bus, Executor $executor, Reader $geodb, callable $isResourceBlocked, array $platform, string $previewHostname, Document $project, Document $devKey, ?Key $apiKey, Cors $cors, Authorization $authorization, DeleteEvent $queueForDeletes, int $executionsRetentionCount, Lock $lock) { /* * Appwrite Router */ $platformHostnames = $platform['hostnames'] ?? []; // Only run Router when external domain if (!in_array($request->getHostname(), $platformHostnames) || !empty($previewHostname)) { - if (router($utopia, $dbForPlatform, $getProjectDB, $swooleRequest, $request, $response, $log, $queueForEvents, $bus, $executor, $geodb, $isResourceBlocked, $platform, $previewHostname, $authorization, $apiKey, $queueForDeletes, $executionsRetentionCount, $distributedLock)) { + if (router($utopia, $dbForPlatform, $getProjectDB, $swooleRequest, $request, $response, $log, $queueForEvents, $bus, $executor, $geodb, $isResourceBlocked, $platform, $previewHostname, $authorization, $apiKey, $queueForDeletes, $executionsRetentionCount, $lock)) { $utopia->getRoute()?->label('router', true); } } @@ -1546,14 +1543,14 @@ Http::get('/robots.txt') ->inject('authorization') ->inject('queueForDeletes') ->inject('executionsRetentionCount') - ->inject('distributedLock') - ->action(function (Http $utopia, SwooleRequest $swooleRequest, Request $request, Response $response, Log $log, Database $dbForPlatform, callable $getProjectDB, Event $queueForEvents, Bus $bus, Executor $executor, Reader $geodb, callable $isResourceBlocked, array $platform, string $previewHostname, ?Key $apiKey, Authorization $authorization, DeleteEvent $queueForDeletes, int $executionsRetentionCount, callable $distributedLock) { + ->inject('lock') + ->action(function (Http $utopia, SwooleRequest $swooleRequest, Request $request, Response $response, Log $log, Database $dbForPlatform, callable $getProjectDB, Event $queueForEvents, Bus $bus, Executor $executor, Reader $geodb, callable $isResourceBlocked, array $platform, string $previewHostname, ?Key $apiKey, Authorization $authorization, DeleteEvent $queueForDeletes, int $executionsRetentionCount, Lock $lock) { $platformHostnames = $platform['hostnames'] ?? []; if (in_array($request->getHostname(), $platformHostnames) || !empty($previewHostname)) { $template = new View(__DIR__ . '/../views/general/robots.phtml'); $response->text($template->render(false)); } else { - if (router($utopia, $dbForPlatform, $getProjectDB, $swooleRequest, $request, $response, $log, $queueForEvents, $bus, $executor, $geodb, $isResourceBlocked, $platform, $previewHostname, $authorization, $apiKey, $queueForDeletes, $executionsRetentionCount, $distributedLock)) { + if (router($utopia, $dbForPlatform, $getProjectDB, $swooleRequest, $request, $response, $log, $queueForEvents, $bus, $executor, $geodb, $isResourceBlocked, $platform, $previewHostname, $authorization, $apiKey, $queueForDeletes, $executionsRetentionCount, $lock)) { $utopia->getRoute()?->label('router', true); } } @@ -1581,14 +1578,14 @@ Http::get('/humans.txt') ->inject('authorization') ->inject('queueForDeletes') ->inject('executionsRetentionCount') - ->inject('distributedLock') - ->action(function (Http $utopia, SwooleRequest $swooleRequest, Request $request, Response $response, Log $log, Database $dbForPlatform, callable $getProjectDB, Event $queueForEvents, Bus $bus, Executor $executor, Reader $geodb, callable $isResourceBlocked, array $platform, string $previewHostname, ?Key $apiKey, Authorization $authorization, DeleteEvent $queueForDeletes, int $executionsRetentionCount, callable $distributedLock) { + ->inject('lock') + ->action(function (Http $utopia, SwooleRequest $swooleRequest, Request $request, Response $response, Log $log, Database $dbForPlatform, callable $getProjectDB, Event $queueForEvents, Bus $bus, Executor $executor, Reader $geodb, callable $isResourceBlocked, array $platform, string $previewHostname, ?Key $apiKey, Authorization $authorization, DeleteEvent $queueForDeletes, int $executionsRetentionCount, Lock $lock) { $platformHostnames = $platform['hostnames'] ?? []; if (in_array($request->getHostname(), $platformHostnames) || !empty($previewHostname)) { $template = new View(__DIR__ . '/../views/general/humans.phtml'); $response->text($template->render(false)); } else { - if (router($utopia, $dbForPlatform, $getProjectDB, $swooleRequest, $request, $response, $log, $queueForEvents, $bus, $executor, $geodb, $isResourceBlocked, $platform, $previewHostname, $authorization, $apiKey, $queueForDeletes, $executionsRetentionCount, $distributedLock)) { + if (router($utopia, $dbForPlatform, $getProjectDB, $swooleRequest, $request, $response, $log, $queueForEvents, $bus, $executor, $geodb, $isResourceBlocked, $platform, $previewHostname, $authorization, $apiKey, $queueForDeletes, $executionsRetentionCount, $lock)) { $utopia->getRoute()?->label('router', true); } } diff --git a/app/controllers/shared/api.php b/app/controllers/shared/api.php index 0ce1b6ca33..3c679ce6ec 100644 --- a/app/controllers/shared/api.php +++ b/app/controllers/shared/api.php @@ -20,6 +20,7 @@ use Appwrite\Event\Webhook; use Appwrite\Extend\Exception; use Appwrite\Extend\Exception as AppwriteException; use Appwrite\Functions\EventProcessor; +use Appwrite\Locking\Lock; use Appwrite\SDK\Method; use Appwrite\Usage\Context; use Appwrite\Utopia\Database\Documents\User; @@ -100,8 +101,8 @@ Http::init() ->inject('team') ->inject('apiKey') ->inject('authorization') - ->inject('distributedLock') - ->action(function (Http $utopia, Request $request, Database $dbForPlatform, Database $dbForProject, AuditContext $auditContext, Document $project, User $user, ?Document $session, array $servers, string $mode, Document $team, ?Key $apiKey, Authorization $authorization, callable $distributedLock) { + ->inject('lock') + ->action(function (Http $utopia, Request $request, Database $dbForPlatform, Database $dbForProject, AuditContext $auditContext, Document $project, User $user, ?Document $session, array $servers, string $mode, Document $team, ?Key $apiKey, Authorization $authorization, Lock $lock) { $route = $utopia->getRoute(); if ($route === null) { throw new AppwriteException(AppwriteException::GENERAL_ROUTE_NOT_FOUND); @@ -250,7 +251,7 @@ Http::init() } if (! $updates->isEmpty()) { - $distributedLock('lock:platform:keys:' . $dbKey->getId(), function () use ($dbForPlatform, $dbKey, $updates, $apiKey, $project, $user, $team) { + $lock->run('keys', $dbKey->getId(), function () use ($dbForPlatform, $dbKey, $updates, $apiKey, $project, $user, $team) { $dbForPlatform->getAuthorization()->skip(fn () => $dbForPlatform->updateDocument('keys', $dbKey->getId(), $updates)); if (! empty($apiKey->getProjectId())) { @@ -391,11 +392,7 @@ Http::init() if ($project->getId() !== 'console') { $accessedAt = $project->getAttribute('accessedAt', 0); if (DateTime::formatTz(DateTime::addSeconds(new \DateTime(), -APP_PROJECT_ACCESS)) > $accessedAt) { - $distributedLock('lock:platform:projects:' . $project->getId(), function () use ($authorization, $dbForPlatform, $project) { - $authorization->skip(fn () => $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ - 'accessedAt' => DateTime::now() - ]))); - }); + $lock->set('projects', $project->getId()); } } @@ -412,11 +409,7 @@ Http::init() 'accessedAt' => $user->getAttribute('accessedAt') ])); } else { - $distributedLock('lock:platform:users:' . $user->getId(), function () use ($authorization, $dbForPlatform, $user) { - $authorization->skip(fn () => $dbForPlatform->updateDocument('users', $user->getId(), new Document([ - 'accessedAt' => $user->getAttribute('accessedAt') - ]))); - }); + $lock->set('users', $user->getId(), 'accessedAt', $user->getAttribute('accessedAt')); } } } diff --git a/app/init/resources/request.php b/app/init/resources/request.php index 71af68b4b2..c5fafbef47 100644 --- a/app/init/resources/request.php +++ b/app/init/resources/request.php @@ -17,6 +17,7 @@ use Appwrite\Event\Webhook; use Appwrite\Extend\Exception; use Appwrite\Functions\EventProcessor; use Appwrite\GraphQL\Schema; +use Appwrite\Locking\Lock; use Appwrite\Network\Cors; use Appwrite\Network\Platform; use Appwrite\Network\Validator\Origin; @@ -216,6 +217,15 @@ return function (Container $container): void { }; }, ['redis', 'telemetry', 'log', 'logger']); + $container->set('lock', function (callable $distributedLock, callable $distributedLockOrFail, Database $dbForPlatform, Authorization $authorization): Lock { + return new Lock( + \Closure::fromCallable($distributedLock), + \Closure::fromCallable($distributedLockOrFail), + $dbForPlatform, + $authorization, + ); + }, ['distributedLock', 'distributedLockOrFail', 'dbForPlatform', 'authorization']); + $container->set('authorization', function () { return new Authorization(); }, []); diff --git a/src/Appwrite/Locking/Lock.php b/src/Appwrite/Locking/Lock.php new file mode 100644 index 0000000000..ec85fe0fa6 --- /dev/null +++ b/src/Appwrite/Locking/Lock.php @@ -0,0 +1,63 @@ +skipLock)(self::key($collection, $id), function () use ($collection, $id, $attribute, $value) { + $this->authorization->skip(fn () => $this->dbForPlatform->updateDocument( + $collection, + $id, + new Document([$attribute => $value ?? DateTime::now()]) + )); + }); + } + + /** + * Skip-on-contention lock around an arbitrary callback. For idempotent + * writes that don't fit the set shape (e.g., updates with cache purge). + */ + public function run(string $collection, string $id, Closure $fn): void + { + ($this->skipLock)(self::key($collection, $id), $fn); + } + + /** + * Block-then-409 lock around an arbitrary callback. For read-modify-write + * endpoints where silently dropping a concurrent request would lose data. + */ + public function runOrFail(string $collection, string $id, Closure $fn): mixed + { + return ($this->failLock)(self::key($collection, $id), $fn); + } + + private static function key(string $collection, string $id): string + { + return "lock:platform:{$collection}:{$id}"; + } +}