From 4bb5dfb6ffd4e66b6bb721cc9b7ef236f93953db Mon Sep 17 00:00:00 2001 From: eldadfux Date: Thu, 25 Jun 2026 15:37:07 -0400 Subject: [PATCH] Refactor onboarding stages to use SDK method keys instead of stage IDs. Update related logic in API handling, constants, and response models to reflect this change. Adjust tests to validate new onboarding structure and ensure proper functionality. --- app/config/onboarding.php | 84 +++++++---- app/controllers/shared/api.php | 132 +++++++++++------- app/init/constants.php | 2 +- .../Modules/Projects/Http/Stages/Update.php | 56 ++++---- .../Modules/Projects/Http/Stages/XList.php | 17 ++- src/Appwrite/Utopia/Response/Model/Stage.php | 4 +- tests/e2e/Services/Project/StagesBase.php | 43 +++--- 7 files changed, 203 insertions(+), 135 deletions(-) diff --git a/app/config/onboarding.php b/app/config/onboarding.php index 626ddd91ca..72f2861206 100644 --- a/app/config/onboarding.php +++ b/app/config/onboarding.php @@ -1,30 +1,66 @@ 'create_database', - 'sdk' => 'databases.create', - ], - [ - 'id' => 'create_bucket', - 'sdk' => 'storage.createBucket', - ], - [ - 'id' => 'create_function', - 'sdk' => 'functions.create', - ], -]; - -$sdkIndex = []; -foreach ($stages as $stage) { - $sdkIndex[$stage['sdk']] = $stage['id']; -} - return [ - 'stages' => $stages, - 'sdkIndex' => $sdkIndex, + // Connect — register platform + 'project.createWebPlatform' => true, + 'project.createAndroidPlatform' => true, + 'project.createApplePlatform' => true, + 'project.createWindowsPlatform' => true, + 'project.createLinuxPlatform' => true, + // Connect — API key + 'project.createKey' => true, + + // Auth + 'users.create' => true, + 'teams.create' => true, + + // Databases — tablesDB + 'tablesDB.create' => true, + 'tablesDB.createTable' => true, + 'tablesDB.createRow' => true, + // Databases — documentsDB + 'documentsDB.create' => true, + 'documentsDB.createCollection' => true, + 'documentsDB.createDocument' => true, + // Databases — legacy + 'databases.create' => true, + 'databases.createCollection' => true, + 'databases.createDocument' => true, + + // Storage + 'storage.createBucket' => true, + 'storage.createFile' => true, + + // Functions + 'functions.create' => true, + 'functions.createDeployment' => true, + 'functions.updateFunctionDeployment' => true, + + // Messaging + 'messaging.createTopic' => true, + 'messaging.createMailgunProvider' => true, + 'messaging.createSendgridProvider' => true, + 'messaging.createSesProvider' => true, + 'messaging.createResendProvider' => true, + 'messaging.createSmtpProvider' => true, + 'messaging.createSMTPProvider' => true, + 'messaging.createMsg91Provider' => true, + 'messaging.createTelesignProvider' => true, + 'messaging.createTextmagicProvider' => true, + 'messaging.createTwilioProvider' => true, + 'messaging.createVonageProvider' => true, + 'messaging.createFcmProvider' => true, + 'messaging.createFCMProvider' => true, + 'messaging.createApnsProvider' => true, + 'messaging.createAPNSProvider' => true, + + // Sites + 'sites.create' => true, + 'sites.createDeployment' => true, + 'sites.updateSiteDeployment' => true, ]; diff --git a/app/controllers/shared/api.php b/app/controllers/shared/api.php index dae41d4f4b..8123be05e1 100644 --- a/app/controllers/shared/api.php +++ b/app/controllers/shared/api.php @@ -891,63 +891,91 @@ Http::shutdown() ->inject('mode') ->action(function (Route $route, Response $response, Document $project, User $user, Realtime $queueForRealtime, Database $dbForPlatform, Authorization $authorization, ?Key $apiKey, string $mode) { /** - * Persist completed stage when the route matches a configured SDK method (stored on project as `onboarding`: stageId → row). + * Persist completed stage when the route matches a configured SDK method (stored on project as `onboarding`: method → row). + * Hot path: fail fast on status/console, O(1) onboarding key lookup, O(1) project state check — no work on unrelated routes. */ - if ($response->getStatusCode() >= 200 && $response->getStatusCode() < 300 && $project->getId() !== 'console') { - $sdkLabel = $route->getLabel('sdk', false); - $stageId = null; - if ($sdkLabel !== false && $sdkLabel !== null) { - $sdkIndex = Config::getParam('onboarding', [])['sdkIndex'] ?? []; - foreach ($sdkLabel instanceof Method ? [$sdkLabel] : (\is_array($sdkLabel) ? $sdkLabel : []) as $sdkMethod) { - if ($sdkMethod instanceof Method && isset($sdkIndex[$k = $sdkMethod->getNamespace() . '.' . $sdkMethod->getMethodName()])) { - $stageId = $sdkIndex[$k]; - break; - } - } - } - if ($stageId !== null) { - $byStageId = $project->getAttribute('onboarding', []); - if (! \is_array($byStageId)) { - $byStageId = []; - } - $done = \is_array($byStageId[$stageId] ?? null) ? ($byStageId[$stageId]['status'] ?? '') : ''; - if ($done !== ONBOARDING_STATUS_COMPLETED && $done !== ONBOARDING_STATUS_SKIPPED) { - $actorType = ($apiKey !== null && $apiKey->getRole() === User::ROLE_APPS) - ? match ($apiKey->getType()) { - API_KEY_ACCOUNT => ACTIVITY_TYPE_KEY_ACCOUNT, - API_KEY_ORGANIZATION => ACTIVITY_TYPE_KEY_ORGANIZATION, - API_KEY_STANDARD, API_KEY_DYNAMIC => ACTIVITY_TYPE_KEY_PROJECT, - default => ACTIVITY_TYPE_KEY_PROJECT, - } - : (! $user->isEmpty() - ? ($mode === APP_MODE_ADMIN ? ACTIVITY_TYPE_ADMIN : ACTIVITY_TYPE_USER) - : ACTIVITY_TYPE_GUEST); - $byStageId[$stageId] = [ - 'status' => ONBOARDING_STATUS_COMPLETED, - 'at' => DateTime::now(), - 'actorType' => $actorType, - ]; - $authorization->skip(fn () => $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ - 'onboarding' => $byStageId, - ]))); + $statusCode = $response->getStatusCode(); + if ($statusCode < 200 || $statusCode >= 300 || $project->getId() === 'console') { + return; + } - $queueForRealtime->reset(); - $queueForRealtime - ->setProject($project) - ->setSubscribers(['console']) - ->setEvent('projects.[projectId].stages.[stageId].complete') - ->setParam('projectId', $project->getId()) - ->setParam('stageId', $stageId) - ->setPayload([ - 'stageId' => $stageId, - 'status' => ONBOARDING_STATUS_COMPLETED, - 'at' => $byStageId[$stageId]['at'], - 'actorType' => $actorType, - ]) - ->trigger(); + $sdkLabel = $route->getLabel('sdk', false); + if ($sdkLabel === false || $sdkLabel === null) { + return; + } + + /** @var array $onboarding */ + $onboarding = Config::getParam('onboarding', []); + if ($onboarding === []) { + return; + } + + $method = null; + if ($sdkLabel instanceof Method) { + $key = $sdkLabel->getNamespace() . '.' . $sdkLabel->getMethodName(); + if (isset($onboarding[$key])) { + $method = $key; + } + } elseif (\is_array($sdkLabel)) { + foreach ($sdkLabel as $sdkMethod) { + if (! $sdkMethod instanceof Method) { + continue; + } + $key = $sdkMethod->getNamespace() . '.' . $sdkMethod->getMethodName(); + if (isset($onboarding[$key])) { + $method = $key; + break; } } } + + if ($method === null) { + return; + } + + $byMethod = $project->getAttribute('onboarding', []); + $status = \is_array($byMethod) ? ($byMethod[$method]['status'] ?? null) : null; + if ($status === ONBOARDING_STATUS_COMPLETED || $status === ONBOARDING_STATUS_SKIPPED) { + return; + } + + if (! \is_array($byMethod)) { + $byMethod = []; + } + + $actorType = ($apiKey !== null && $apiKey->getRole() === User::ROLE_APPS) + ? match ($apiKey->getType()) { + API_KEY_ACCOUNT => ACTOR_TYPE_KEY_ACCOUNT, + API_KEY_ORGANIZATION => ACTOR_TYPE_KEY_ORGANIZATION, + API_KEY_STANDARD, API_KEY_EPHEMERAL => ACTOR_TYPE_KEY_PROJECT, + default => ACTOR_TYPE_KEY_PROJECT, + } + : (! $user->isEmpty() + ? ($mode === APP_MODE_ADMIN ? ACTOR_TYPE_ADMIN : ACTOR_TYPE_USER) + : ACTOR_TYPE_GUEST); + $byMethod[$method] = [ + 'status' => ONBOARDING_STATUS_COMPLETED, + 'at' => DateTime::now(), + 'actorType' => $actorType, + ]; + $authorization->skip(fn () => $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ + 'onboarding' => $byMethod, + ]))); + + $queueForRealtime->reset(); + $queueForRealtime + ->setProject($project) + ->setSubscribers(['console']) + ->setEvent('projects.[projectId].stages.[stageId].complete') + ->setParam('projectId', $project->getId()) + ->setParam('stageId', $method) + ->setPayload([ + 'stageId' => $method, + 'status' => ONBOARDING_STATUS_COMPLETED, + 'at' => $byMethod[$method]['at'], + 'actorType' => $actorType, + ]) + ->trigger(); }); Http::shutdown() diff --git a/app/init/constants.php b/app/init/constants.php index 44d3b5110b..9efb6e3222 100644 --- a/app/init/constants.php +++ b/app/init/constants.php @@ -173,7 +173,7 @@ const ACTOR_TYPE_KEY_ACCOUNT = 'keyAccount'; const ACTOR_TYPE_KEY_ORGANIZATION = 'keyOrganization'; /** - * Project onboarding stage status (stored per stage id under project.onboarding JSON). + * Project onboarding stage status (stored per SDK method key under project.onboarding JSON). */ const ONBOARDING_STATUS_COMPLETED = 'completed'; const ONBOARDING_STATUS_SKIPPED = 'skipped'; diff --git a/src/Appwrite/Platform/Modules/Projects/Http/Stages/Update.php b/src/Appwrite/Platform/Modules/Projects/Http/Stages/Update.php index a489dd2b3f..910b2dcf63 100644 --- a/src/Appwrite/Platform/Modules/Projects/Http/Stages/Update.php +++ b/src/Appwrite/Platform/Modules/Projects/Http/Stages/Update.php @@ -52,7 +52,7 @@ class Update extends Action ], )) ->param('projectId', '', new UID(), 'Project unique ID.') - ->param('stageId', '', new Text(64), 'Stage ID.') + ->param('stageId', '', new Text(128), 'SDK method key (namespace.method).') ->param('skip', true, new Boolean(), 'Mark the stage as skipped.', true) ->inject('response') ->inject('dbForPlatform') @@ -70,60 +70,54 @@ class Update extends Action throw new Exception(Exception::PROJECT_NOT_FOUND); } - $definition = $this->getStageDefinition($stageId); + $this->assertOnboardingMethod($stageId); - $byStageId = $project->getAttribute('onboarding', []); - if (! \is_array($byStageId)) { - $byStageId = []; + $byMethod = $project->getAttribute('onboarding', []); + if (! \is_array($byMethod)) { + $byMethod = []; } - $row = \is_array($byStageId[$stageId] ?? null) ? $byStageId[$stageId] : null; + $row = \is_array($byMethod[$stageId] ?? null) ? $byMethod[$stageId] : null; if ($skip) { $prev = \is_array($row) ? ($row['status'] ?? '') : ''; if ($prev !== ONBOARDING_STATUS_COMPLETED) { - $byStageId[$stageId] = [ + $byMethod[$stageId] = [ 'status' => ONBOARDING_STATUS_SKIPPED, 'at' => DateTime::now(), 'actorType' => $this->resolveActorType($apiKey, $user, $mode), ]; - $project = $dbForPlatform->updateDocument('projects', $project->getId(), $project->setAttribute('onboarding', $byStageId)); - $byStageId = $project->getAttribute('onboarding', []); - $row = \is_array($byStageId[$stageId] ?? null) ? $byStageId[$stageId] : null; + $project = $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ + 'onboarding' => $byMethod, + ])); + $byMethod = $project->getAttribute('onboarding', []); + $row = \is_array($byMethod[$stageId] ?? null) ? $byMethod[$stageId] : null; } } - $response->dynamic(new Document($this->formatStageRow($definition, $row)), Response::MODEL_STAGE); + $response->dynamic(new Document($this->formatStageRow($stageId, $row)), Response::MODEL_STAGE); } - /** - * @return array{id: string, sdk: string} - */ - private function getStageDefinition(string $stageId): array + private function assertOnboardingMethod(string $method): void { - foreach (Config::getParam('onboarding', [])['stages'] ?? [] as $definition) { - if (($definition['id'] ?? '') === $stageId) { - return $definition; - } + if (! \array_key_exists($method, Config::getParam('onboarding', []))) { + throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'Unknown SDK method: ' . $method); } - - throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'Unknown stage ID: ' . $stageId); } /** * @param array|null $row * @return array */ - private function formatStageRow(array $definition, ?array $row): array + private function formatStageRow(string $method, ?array $row): array { - $stageId = $definition['id']; $status = \is_array($row) ? ($row['status'] ?? null) : null; $at = \is_array($row) ? ($row['at'] ?? '') : ''; $actorType = \is_array($row) ? ($row['actorType'] ?? '') : ''; return [ - 'id' => $stageId, - 'sdk' => $definition['sdk'] ?? '', + 'id' => $method, + 'sdk' => $method, 'status' => $status ?? 'pending', 'at' => $at, 'actorType' => $actorType, @@ -134,17 +128,17 @@ class Update extends Action { if ($apiKey !== null && $apiKey->getRole() === User::ROLE_APPS) { return match ($apiKey->getType()) { - API_KEY_ACCOUNT => ACTIVITY_TYPE_KEY_ACCOUNT, - API_KEY_ORGANIZATION => ACTIVITY_TYPE_KEY_ORGANIZATION, - API_KEY_STANDARD, API_KEY_DYNAMIC => ACTIVITY_TYPE_KEY_PROJECT, - default => ACTIVITY_TYPE_KEY_PROJECT, + API_KEY_ACCOUNT => ACTOR_TYPE_KEY_ACCOUNT, + API_KEY_ORGANIZATION => ACTOR_TYPE_KEY_ORGANIZATION, + API_KEY_STANDARD, API_KEY_EPHEMERAL => ACTOR_TYPE_KEY_PROJECT, + default => ACTOR_TYPE_KEY_PROJECT, }; } if (! $user->isEmpty()) { - return $mode === APP_MODE_ADMIN ? ACTIVITY_TYPE_ADMIN : ACTIVITY_TYPE_USER; + return $mode === APP_MODE_ADMIN ? ACTOR_TYPE_ADMIN : ACTOR_TYPE_USER; } - return ACTIVITY_TYPE_GUEST; + return ACTOR_TYPE_GUEST; } } diff --git a/src/Appwrite/Platform/Modules/Projects/Http/Stages/XList.php b/src/Appwrite/Platform/Modules/Projects/Http/Stages/XList.php index e0f4f4074b..7fa6537152 100644 --- a/src/Appwrite/Platform/Modules/Projects/Http/Stages/XList.php +++ b/src/Appwrite/Platform/Modules/Projects/Http/Stages/XList.php @@ -68,24 +68,23 @@ class XList extends Action */ private function buildStagesList(Document $project): array { - $definitions = Config::getParam('onboarding', [])['stages'] ?? []; - $byStageId = $project->getAttribute('onboarding', []); - if (! \is_array($byStageId)) { - $byStageId = []; + $methods = \array_keys(Config::getParam('onboarding', [])); + $byMethod = $project->getAttribute('onboarding', []); + if (! \is_array($byMethod)) { + $byMethod = []; } $out = []; - foreach ($definitions as $definition) { - $stageId = $definition['id']; - $row = $byStageId[$stageId] ?? null; + foreach ($methods as $method) { + $row = $byMethod[$method] ?? null; $status = \is_array($row) ? ($row['status'] ?? null) : null; $at = \is_array($row) ? ($row['at'] ?? '') : ''; $actorType = \is_array($row) ? ($row['actorType'] ?? '') : ''; $out[] = [ - 'id' => $stageId, - 'sdk' => $definition['sdk'] ?? '', + 'id' => $method, + 'sdk' => $method, 'status' => $status ?? 'pending', 'at' => $at, 'actorType' => $actorType, diff --git a/src/Appwrite/Utopia/Response/Model/Stage.php b/src/Appwrite/Utopia/Response/Model/Stage.php index 8adaaaae47..2b39499f8f 100644 --- a/src/Appwrite/Utopia/Response/Model/Stage.php +++ b/src/Appwrite/Utopia/Response/Model/Stage.php @@ -15,13 +15,13 @@ class Stage extends Model 'type' => self::TYPE_STRING, 'description' => 'Stage ID.', 'default' => '', - 'example' => 'create_database', + 'example' => 'tablesDB.create', ]) ->addRule('sdk', [ 'type' => self::TYPE_STRING, 'description' => 'SDK method key (namespace.name) for this stage.', 'default' => '', - 'example' => 'databases.create', + 'example' => 'tablesDB.create', ]) ->addRule('status', [ 'type' => self::TYPE_STRING, diff --git a/tests/e2e/Services/Project/StagesBase.php b/tests/e2e/Services/Project/StagesBase.php index 9bf3f21f4b..ff7a56359d 100644 --- a/tests/e2e/Services/Project/StagesBase.php +++ b/tests/e2e/Services/Project/StagesBase.php @@ -5,6 +5,7 @@ namespace Tests\E2E\Services\Project; use Appwrite\Extend\Exception; use Appwrite\Tests\Async; use Tests\E2E\Client; +use Utopia\Config\Config; use Utopia\Database\Helpers\ID; use Utopia\Database\Validator\Datetime as DatetimeValidator; use Utopia\System\System; @@ -25,13 +26,15 @@ trait StagesBase $this->assertSame(200, $response['headers']['status-code']); $this->assertIsArray($response['body']['stages']); - $this->assertCount(3, $response['body']['stages']); + $this->assertCount(\count(Config::getParam('onboarding', [])), $response['body']['stages']); $ids = array_column($response['body']['stages'], 'id'); - $this->assertSame(['create_database', 'create_bucket', 'create_function'], $ids); + $this->assertContains('tablesDB.create', $ids); + $this->assertContains('storage.createBucket', $ids); + $this->assertContains('functions.create', $ids); foreach ($response['body']['stages'] as $stage) { - $this->assertArrayHasKey('sdk', $stage); + $this->assertSame($stage['id'], $stage['sdk']); $this->assertArrayHasKey('status', $stage); $this->assertArrayHasKey('at', $stage); $this->assertArrayHasKey('actorType', $stage); @@ -60,31 +63,38 @@ trait StagesBase public function testUpdateProjectStageSkip(): void { $projectId = $this->createTeamAndProject(); + $method = 'tablesDB.create'; - $response = $this->updateStage($projectId, 'create_database', true); + $response = $this->updateStage($projectId, $method, true); $this->assertSame(200, $response['headers']['status-code']); - $this->assertSame('create_database', $response['body']['id']); - $this->assertSame('databases.create', $response['body']['sdk']); + $this->assertSame($method, $response['body']['id']); + $this->assertSame($method, $response['body']['sdk']); $this->assertSame(ONBOARDING_STATUS_SKIPPED, $response['body']['status']); $this->assertNotEmpty($response['body']['at']); - $this->assertSame(ACTIVITY_TYPE_USER, $response['body']['actorType']); + $this->assertSame(ACTOR_TYPE_USER, $response['body']['actorType']); $dateValidator = new DatetimeValidator(); $this->assertSame(true, $dateValidator->isValid($response['body']['at'])); $list = $this->listStages($projectId); $this->assertSame(200, $list['headers']['status-code']); - $first = $list['body']['stages'][0]; - $this->assertSame('create_database', $first['id']); - $this->assertSame(ONBOARDING_STATUS_SKIPPED, $first['status']); - $this->assertSame(ACTIVITY_TYPE_USER, $first['actorType']); + $databaseStage = null; + foreach ($list['body']['stages'] as $stage) { + if ($stage['id'] === $method) { + $databaseStage = $stage; + break; + } + } + $this->assertNotNull($databaseStage); + $this->assertSame(ONBOARDING_STATUS_SKIPPED, $databaseStage['status']); + $this->assertSame(ACTOR_TYPE_USER, $databaseStage['actorType']); - $response = $this->updateStage($projectId, 'unknown_stage_xyz', true); + $response = $this->updateStage($projectId, 'unknown.method', true); $this->assertSame(400, $response['headers']['status-code']); $this->assertSame(Exception::GENERAL_ARGUMENT_INVALID, $response['body']['type']); - $response = $this->updateStage(ID::unique(), 'create_bucket', true); + $response = $this->updateStage(ID::unique(), 'storage.createBucket', true); $this->assertSame(404, $response['headers']['status-code']); $this->assertSame(Exception::PROJECT_NOT_FOUND, $response['body']['type']); } @@ -92,11 +102,12 @@ trait StagesBase public function testUpdateProjectStageSkipFalseLeavesPending(): void { $projectId = $this->createTeamAndProject(); + $method = 'storage.createBucket'; - $response = $this->updateStage($projectId, 'create_bucket', false); + $response = $this->updateStage($projectId, $method, false); $this->assertSame(200, $response['headers']['status-code']); - $this->assertSame('create_bucket', $response['body']['id']); + $this->assertSame($method, $response['body']['id']); $this->assertSame('pending', $response['body']['status']); } @@ -104,7 +115,7 @@ trait StagesBase { $projectId = $this->createTeamAndProject(); - $response = $this->updateStage($projectId, 'create_database', true, false); + $response = $this->updateStage($projectId, 'tablesDB.create', true, false); $this->assertSame(401, $response['headers']['status-code']); }