From e18e848a68671fdfd2dd2cb81ab769d8cbbc4b62 Mon Sep 17 00:00:00 2001 From: eldadfux Date: Sat, 11 Apr 2026 18:50:26 +0200 Subject: [PATCH 01/18] feat(projects): add onboarding stages tracking and stages API Add configurable onboarding stages keyed by SDK method, persist completion in project onboarding JSON on successful API responses, and expose listStages and updateStage routes with stages.read/write scopes and stage/stageList models. Made-with: Cursor --- app/config/collections/platform.php | 11 ++ app/config/onboarding.php | 30 ++++ app/config/roles.php | 2 + app/config/scopes/project.php | 6 + app/controllers/shared/api.php | 47 +++++- app/init/configs.php | 1 + app/init/constants.php | 6 + app/init/models.php | 3 + .../Modules/Projects/Http/Stages/Update.php | 150 ++++++++++++++++++ .../Modules/Projects/Http/Stages/XList.php | 97 +++++++++++ .../Modules/Projects/Services/Http.php | 5 + src/Appwrite/Utopia/Response.php | 2 + .../Utopia/Response/Model/Project.php | 6 + src/Appwrite/Utopia/Response/Model/Stage.php | 61 +++++++ 14 files changed, 426 insertions(+), 1 deletion(-) create mode 100644 app/config/onboarding.php create mode 100644 src/Appwrite/Platform/Modules/Projects/Http/Stages/Update.php create mode 100644 src/Appwrite/Platform/Modules/Projects/Http/Stages/XList.php create mode 100644 src/Appwrite/Utopia/Response/Model/Stage.php diff --git a/app/config/collections/platform.php b/app/config/collections/platform.php index 6195c11724..4775fd174f 100644 --- a/app/config/collections/platform.php +++ b/app/config/collections/platform.php @@ -342,6 +342,17 @@ $platformCollections = [ 'array' => true, 'filters' => [], ], + [ + '$id' => ID::custom('onboarding'), + 'type' => Database::VAR_STRING, + 'format' => '', + 'size' => 65536, + 'signed' => true, + 'required' => false, + 'default' => [], + 'array' => false, + 'filters' => ['json'], + ], [ '$id' => 'status', 'type' => Database::VAR_STRING, diff --git a/app/config/onboarding.php b/app/config/onboarding.php new file mode 100644 index 0000000000..626ddd91ca --- /dev/null +++ b/app/config/onboarding.php @@ -0,0 +1,30 @@ + '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, +]; diff --git a/app/config/roles.php b/app/config/roles.php index 116e8ac932..0e9d391418 100644 --- a/app/config/roles.php +++ b/app/config/roles.php @@ -95,6 +95,8 @@ $admins = [ 'tokens.write', 'schedules.read', 'schedules.write', + 'stages.read', + 'stages.write', ]; return [ diff --git a/app/config/scopes/project.php b/app/config/scopes/project.php index 6c7f75c08e..c195f1e9cb 100644 --- a/app/config/scopes/project.php +++ b/app/config/scopes/project.php @@ -151,6 +151,12 @@ return [ // List of publicly visible scopes 'schedules.write' => [ 'description' => 'Access to create, update, and delete your project\'s schedules', ], + 'stages.read' => [ + 'description' => 'Access to read your project\'s stages', + ], + 'stages.write' => [ + 'description' => 'Access to update your project\'s stages', + ], 'migrations.read' => [ 'description' => 'Access to read your project\'s migrations', ], diff --git a/app/controllers/shared/api.php b/app/controllers/shared/api.php index fa96d2ae80..bb8b118c46 100644 --- a/app/controllers/shared/api.php +++ b/app/controllers/shared/api.php @@ -800,16 +800,61 @@ Http::shutdown() ->inject('queueForWebhooks') ->inject('queueForRealtime') ->inject('dbForProject') + ->inject('dbForPlatform') ->inject('authorization') ->inject('timelimit') ->inject('eventProcessor') ->inject('bus') ->inject('apiKey') ->inject('mode') - ->action(function (Http $utopia, Request $request, Response $response, Document $project, User $user, Event $queueForEvents, Audit $queueForAudits, Context $usage, UsagePublisher $publisherForUsage, Delete $queueForDeletes, EventDatabase $queueForDatabase, Build $queueForBuilds, Messaging $queueForMessaging, Func $queueForFunctions, Event $queueForWebhooks, Realtime $queueForRealtime, Database $dbForProject, Authorization $authorization, callable $timelimit, EventProcessor $eventProcessor, Bus $bus, ?Key $apiKey, string $mode) use ($parseLabel) { + ->action(function (Http $utopia, Request $request, Response $response, Document $project, User $user, Event $queueForEvents, Audit $queueForAudits, Context $usage, UsagePublisher $publisherForUsage, Delete $queueForDeletes, EventDatabase $queueForDatabase, Build $queueForBuilds, Messaging $queueForMessaging, Func $queueForFunctions, Event $queueForWebhooks, Realtime $queueForRealtime, Database $dbForProject, Database $dbForPlatform, Authorization $authorization, callable $timelimit, EventProcessor $eventProcessor, Bus $bus, ?Key $apiKey, string $mode) use ($parseLabel) { $responsePayload = $response->getPayload(); + /** + * Persist completed stage when the route matches a configured SDK method (stored on project as `onboarding`: stageId → row). + */ + if ($response->getStatusCode() >= 200 && $response->getStatusCode() < 300 && $project->getId() !== 'console') { + $sdkLabel = $utopia->getRoute()?->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, + ]))); + } + } + } + if (! empty($queueForEvents->getEvent())) { if (empty($queueForEvents->getPayload())) { $queueForEvents->setPayload($responsePayload); diff --git a/app/init/configs.php b/app/init/configs.php index 35c8e3899d..1eba1d5dcd 100644 --- a/app/init/configs.php +++ b/app/init/configs.php @@ -26,6 +26,7 @@ Config::load('projectScopes', __DIR__ . '/../config/scopes/project.php', $config Config::load('organizationScopes', __DIR__ . '/../config/scopes/organization.php', $configAdapter); Config::load('accountScopes', __DIR__ . '/../config/scopes/account.php', $configAdapter); Config::load('services', __DIR__ . '/../config/services.php', $configAdapter); // List of services +Config::load('onboarding', __DIR__ . '/../config/onboarding.php', $configAdapter); // Project onboarding stages → routes Config::load('variables', __DIR__ . '/../config/variables.php', $configAdapter); // List of env variables Config::load('regions', __DIR__ . '/../config/regions.php', $configAdapter); // List of available regions Config::load('avatar-browsers', __DIR__ . '/../config/avatars/browsers.php', $configAdapter); diff --git a/app/init/constants.php b/app/init/constants.php index 3b907572ab..6e842a74a0 100644 --- a/app/init/constants.php +++ b/app/init/constants.php @@ -163,6 +163,12 @@ const ACTIVITY_TYPE_KEY_PROJECT = 'keyProject'; const ACTIVITY_TYPE_KEY_ACCOUNT = 'keyAccount'; const ACTIVITY_TYPE_KEY_ORGANIZATION = 'keyOrganization'; +/** + * Project onboarding stage status (stored per stage id under project.onboarding JSON). + */ +const ONBOARDING_STATUS_COMPLETED = 'completed'; +const ONBOARDING_STATUS_SKIPPED = 'skipped'; + /** * MFA */ diff --git a/app/init/models.php b/app/init/models.php index dd97b03652..646ff45af9 100644 --- a/app/init/models.php +++ b/app/init/models.php @@ -126,6 +126,7 @@ use Appwrite\Utopia\Response\Model\Schedule; use Appwrite\Utopia\Response\Model\Session; use Appwrite\Utopia\Response\Model\Site; use Appwrite\Utopia\Response\Model\Specification; +use Appwrite\Utopia\Response\Model\Stage; use Appwrite\Utopia\Response\Model\Subscriber; use Appwrite\Utopia\Response\Model\Table; use Appwrite\Utopia\Response\Model\Target; @@ -212,6 +213,7 @@ Response::setModel(new BaseList('Variables List', Response::MODEL_VARIABLE_LIST, Response::setModel(new BaseList('Status List', Response::MODEL_HEALTH_STATUS_LIST, 'statuses', Response::MODEL_HEALTH_STATUS)); Response::setModel(new BaseList('Rule List', Response::MODEL_PROXY_RULE_LIST, 'rules', Response::MODEL_PROXY_RULE)); Response::setModel(new BaseList('Schedules List', Response::MODEL_SCHEDULE_LIST, 'schedules', Response::MODEL_SCHEDULE)); +Response::setModel(new BaseList('Stages List', Response::MODEL_STAGE_LIST, 'stages', Response::MODEL_STAGE, false, false)); Response::setModel(new BaseList('Locale codes list', Response::MODEL_LOCALE_CODE_LIST, 'localeCodes', Response::MODEL_LOCALE_CODE)); Response::setModel(new BaseList('Provider list', Response::MODEL_PROVIDER_LIST, 'providers', Response::MODEL_PROVIDER)); Response::setModel(new BaseList('Message list', Response::MODEL_MESSAGE_LIST, 'messages', Response::MODEL_MESSAGE)); @@ -373,6 +375,7 @@ Response::setModel(new Headers()); Response::setModel(new Specification()); Response::setModel(new Rule()); Response::setModel(new Schedule()); +Response::setModel(new Stage()); Response::setModel(new TemplateSMS()); Response::setModel(new TemplateEmail()); Response::setModel(new ConsoleVariables()); diff --git a/src/Appwrite/Platform/Modules/Projects/Http/Stages/Update.php b/src/Appwrite/Platform/Modules/Projects/Http/Stages/Update.php new file mode 100644 index 0000000000..a489dd2b3f --- /dev/null +++ b/src/Appwrite/Platform/Modules/Projects/Http/Stages/Update.php @@ -0,0 +1,150 @@ +setHttpMethod(Action::HTTP_REQUEST_METHOD_PATCH) + ->setHttpPath('/v1/projects/:projectId/stages/:stageId') + ->desc('Update stage') + ->groups(['api', 'projects']) + ->label('scope', 'stages.write') + ->label('audits.event', 'stages.update') + ->label('audits.resource', 'project/{request.projectId}') + ->label('sdk', new Method( + namespace: 'projects', + group: 'stages', + name: 'updateStage', + description: '/docs/references/projects/update-stage.md', + auth: [AuthType::ADMIN], + responses: [ + new SDKResponse( + code: Response::STATUS_CODE_OK, + model: Response::MODEL_STAGE, + ) + ], + )) + ->param('projectId', '', new UID(), 'Project unique ID.') + ->param('stageId', '', new Text(64), 'Stage ID.') + ->param('skip', true, new Boolean(), 'Mark the stage as skipped.', true) + ->inject('response') + ->inject('dbForPlatform') + ->inject('apiKey') + ->inject('user') + ->inject('mode') + ->callback($this->action(...)); + } + + public function action(string $projectId, string $stageId, bool $skip, Response $response, Database $dbForPlatform, ?Key $apiKey, User $user, string $mode): void + { + $project = $dbForPlatform->getDocument('projects', $projectId); + + if ($project->isEmpty()) { + throw new Exception(Exception::PROJECT_NOT_FOUND); + } + + $definition = $this->getStageDefinition($stageId); + + $byStageId = $project->getAttribute('onboarding', []); + if (! \is_array($byStageId)) { + $byStageId = []; + } + + $row = \is_array($byStageId[$stageId] ?? null) ? $byStageId[$stageId] : null; + + if ($skip) { + $prev = \is_array($row) ? ($row['status'] ?? '') : ''; + if ($prev !== ONBOARDING_STATUS_COMPLETED) { + $byStageId[$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; + } + } + + $response->dynamic(new Document($this->formatStageRow($definition, $row)), Response::MODEL_STAGE); + } + + /** + * @return array{id: string, sdk: string} + */ + private function getStageDefinition(string $stageId): array + { + foreach (Config::getParam('onboarding', [])['stages'] ?? [] as $definition) { + if (($definition['id'] ?? '') === $stageId) { + return $definition; + } + } + + 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 + { + $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'] ?? '', + 'status' => $status ?? 'pending', + 'at' => $at, + 'actorType' => $actorType, + ]; + } + + private function resolveActorType(?Key $apiKey, User $user, string $mode): string + { + 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, + }; + } + + if (! $user->isEmpty()) { + return $mode === APP_MODE_ADMIN ? ACTIVITY_TYPE_ADMIN : ACTIVITY_TYPE_USER; + } + + return ACTIVITY_TYPE_GUEST; + } +} diff --git a/src/Appwrite/Platform/Modules/Projects/Http/Stages/XList.php b/src/Appwrite/Platform/Modules/Projects/Http/Stages/XList.php new file mode 100644 index 0000000000..e0f4f4074b --- /dev/null +++ b/src/Appwrite/Platform/Modules/Projects/Http/Stages/XList.php @@ -0,0 +1,97 @@ +setHttpMethod(Action::HTTP_REQUEST_METHOD_GET) + ->setHttpPath('/v1/projects/:projectId/stages') + ->desc('List stages') + ->groups(['api', 'projects']) + ->label('scope', 'stages.read') + ->label('sdk', new Method( + namespace: 'projects', + group: 'stages', + name: 'listStages', + description: '/docs/references/projects/list-stages.md', + auth: [AuthType::ADMIN], + responses: [ + new SDKResponse( + code: Response::STATUS_CODE_OK, + model: Response::MODEL_STAGE_LIST, + ) + ], + )) + ->param('projectId', '', new UID(), 'Project unique ID.') + ->inject('response') + ->inject('dbForPlatform') + ->callback($this->action(...)); + } + + public function action(string $projectId, Response $response, Database $dbForPlatform): void + { + $project = $dbForPlatform->getDocument('projects', $projectId); + + if ($project->isEmpty()) { + throw new Exception(Exception::PROJECT_NOT_FOUND); + } + + $response->dynamic(new Document([ + 'stages' => $this->buildStagesList($project), + ]), Response::MODEL_STAGE_LIST); + } + + /** + * @return array> + */ + private function buildStagesList(Document $project): array + { + $definitions = Config::getParam('onboarding', [])['stages'] ?? []; + $byStageId = $project->getAttribute('onboarding', []); + if (! \is_array($byStageId)) { + $byStageId = []; + } + + $out = []; + foreach ($definitions as $definition) { + $stageId = $definition['id']; + $row = $byStageId[$stageId] ?? 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'] ?? '', + 'status' => $status ?? 'pending', + 'at' => $at, + 'actorType' => $actorType, + ]; + } + + return $out; + } +} diff --git a/src/Appwrite/Platform/Modules/Projects/Services/Http.php b/src/Appwrite/Platform/Modules/Projects/Services/Http.php index 8275e664d5..56e8c26d73 100644 --- a/src/Appwrite/Platform/Modules/Projects/Services/Http.php +++ b/src/Appwrite/Platform/Modules/Projects/Services/Http.php @@ -14,6 +14,8 @@ use Appwrite\Platform\Modules\Projects\Http\Projects\XList as ListProjects; use Appwrite\Platform\Modules\Projects\Http\Schedules\Create as CreateSchedule; use Appwrite\Platform\Modules\Projects\Http\Schedules\Get as GetSchedule; use Appwrite\Platform\Modules\Projects\Http\Schedules\XList as ListSchedules; +use Appwrite\Platform\Modules\Projects\Http\Stages\Update as UpdateStages; +use Appwrite\Platform\Modules\Projects\Http\Stages\XList as ListStages; use Utopia\Platform\Service; class Http extends Service @@ -35,5 +37,8 @@ class Http extends Service $this->addAction(CreateSchedule::getName(), new CreateSchedule()); $this->addAction(GetSchedule::getName(), new GetSchedule()); $this->addAction(ListSchedules::getName(), new ListSchedules()); + + $this->addAction(ListStages::getName(), new ListStages()); + $this->addAction(UpdateStages::getName(), new UpdateStages()); } } diff --git a/src/Appwrite/Utopia/Response.php b/src/Appwrite/Utopia/Response.php index 295348c665..c4a272f5bf 100644 --- a/src/Appwrite/Utopia/Response.php +++ b/src/Appwrite/Utopia/Response.php @@ -247,6 +247,8 @@ class Response extends SwooleResponse // Project public const MODEL_PROJECT = 'project'; public const MODEL_PROJECT_LIST = 'projectList'; + public const MODEL_STAGE = 'stage'; + public const MODEL_STAGE_LIST = 'stageList'; public const MODEL_WEBHOOK = 'webhook'; public const MODEL_WEBHOOK_LIST = 'webhookList'; public const MODEL_KEY = 'key'; diff --git a/src/Appwrite/Utopia/Response/Model/Project.php b/src/Appwrite/Utopia/Response/Model/Project.php index 1ef73aa769..2c46d51243 100644 --- a/src/Appwrite/Utopia/Response/Model/Project.php +++ b/src/Appwrite/Utopia/Response/Model/Project.php @@ -308,6 +308,12 @@ class Project extends Model 'default' => 'active', 'example' => 'active', ]) + ->addRule('onboarding', [ + 'type' => self::TYPE_JSON, + 'description' => 'Stage progress (completed or skipped) with timestamps and actor types, keyed by stage id.', + 'default' => [], + 'example' => [], + ]) ; $services = Config::getParam('services', []); diff --git a/src/Appwrite/Utopia/Response/Model/Stage.php b/src/Appwrite/Utopia/Response/Model/Stage.php new file mode 100644 index 0000000000..8adaaaae47 --- /dev/null +++ b/src/Appwrite/Utopia/Response/Model/Stage.php @@ -0,0 +1,61 @@ +addRule('id', [ + 'type' => self::TYPE_STRING, + 'description' => 'Stage ID.', + 'default' => '', + 'example' => 'create_database', + ]) + ->addRule('sdk', [ + 'type' => self::TYPE_STRING, + 'description' => 'SDK method key (namespace.name) for this stage.', + 'default' => '', + 'example' => 'databases.create', + ]) + ->addRule('status', [ + 'type' => self::TYPE_STRING, + 'description' => 'Stage status.', + 'default' => 'pending', + 'example' => 'completed', + ]) + ->addRule('at', [ + 'type' => self::TYPE_DATETIME, + 'description' => 'When the stage was completed or skipped, in ISO 8601 format.', + 'default' => '', + 'example' => self::TYPE_DATETIME_EXAMPLE, + ]) + ->addRule('actorType', [ + 'type' => self::TYPE_STRING, + 'description' => 'Actor type when the stage was recorded.', + 'default' => '', + 'example' => 'user', + ]) + ; + } + + public function getName(): string + { + return 'Stage'; + } + + public function getType(): string + { + return Response::MODEL_STAGE; + } + + public function filter(Document $document): Document + { + return $document; + } +} From f1c24a0b24ba37811cd85980df99e2d9eb821c38 Mon Sep 17 00:00:00 2001 From: eldadfux Date: Sat, 11 Apr 2026 19:14:57 +0200 Subject: [PATCH 02/18] feat(projects): realtime on stage completion; add stages E2E tests Emit console realtime when onboarding stages complete in API shutdown. Add Project/StagesBase + StagesConsoleClientTest following Platforms pattern. Made-with: Cursor --- app/controllers/shared/api.php | 15 ++ tests/e2e/Services/Project/StagesBase.php | 179 ++++++++++++++++++ .../Project/StagesConsoleClientTest.php | 14 ++ 3 files changed, 208 insertions(+) create mode 100644 tests/e2e/Services/Project/StagesBase.php create mode 100644 tests/e2e/Services/Project/StagesConsoleClientTest.php diff --git a/app/controllers/shared/api.php b/app/controllers/shared/api.php index bb8b118c46..6f13250405 100644 --- a/app/controllers/shared/api.php +++ b/app/controllers/shared/api.php @@ -851,6 +851,21 @@ Http::shutdown() $authorization->skip(fn () => $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ 'onboarding' => $byStageId, ]))); + + $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(); } } } diff --git a/tests/e2e/Services/Project/StagesBase.php b/tests/e2e/Services/Project/StagesBase.php new file mode 100644 index 0000000000..9bf3f21f4b --- /dev/null +++ b/tests/e2e/Services/Project/StagesBase.php @@ -0,0 +1,179 @@ +createTeamAndProject(); + + $response = $this->listStages($projectId); + + $this->assertSame(200, $response['headers']['status-code']); + $this->assertIsArray($response['body']['stages']); + $this->assertCount(3, $response['body']['stages']); + + $ids = array_column($response['body']['stages'], 'id'); + $this->assertSame(['create_database', 'create_bucket', 'create_function'], $ids); + + foreach ($response['body']['stages'] as $stage) { + $this->assertArrayHasKey('sdk', $stage); + $this->assertArrayHasKey('status', $stage); + $this->assertArrayHasKey('at', $stage); + $this->assertArrayHasKey('actorType', $stage); + $this->assertSame('pending', $stage['status']); + } + + // Verify via GET for unknown project + $response = $this->listStages(ID::unique()); + $this->assertSame(404, $response['headers']['status-code']); + $this->assertSame(Exception::PROJECT_NOT_FOUND, $response['body']['type']); + } + + public function testListProjectStagesWithoutAuthentication(): void + { + $projectId = $this->createTeamAndProject(); + + $response = $this->listStages($projectId, false); + + $this->assertSame(401, $response['headers']['status-code']); + } + + // ========================================================================= + // Update stage (skip) tests + // ========================================================================= + + public function testUpdateProjectStageSkip(): void + { + $projectId = $this->createTeamAndProject(); + + $response = $this->updateStage($projectId, 'create_database', true); + + $this->assertSame(200, $response['headers']['status-code']); + $this->assertSame('create_database', $response['body']['id']); + $this->assertSame('databases.create', $response['body']['sdk']); + $this->assertSame(ONBOARDING_STATUS_SKIPPED, $response['body']['status']); + $this->assertNotEmpty($response['body']['at']); + $this->assertSame(ACTIVITY_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']); + + $response = $this->updateStage($projectId, 'unknown_stage_xyz', 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); + $this->assertSame(404, $response['headers']['status-code']); + $this->assertSame(Exception::PROJECT_NOT_FOUND, $response['body']['type']); + } + + public function testUpdateProjectStageSkipFalseLeavesPending(): void + { + $projectId = $this->createTeamAndProject(); + + $response = $this->updateStage($projectId, 'create_bucket', false); + + $this->assertSame(200, $response['headers']['status-code']); + $this->assertSame('create_bucket', $response['body']['id']); + $this->assertSame('pending', $response['body']['status']); + } + + public function testUpdateProjectStageWithoutAuthentication(): void + { + $projectId = $this->createTeamAndProject(); + + $response = $this->updateStage($projectId, 'create_database', true, false); + + $this->assertSame(401, $response['headers']['status-code']); + } + + // ========================================================================= + // Helpers + // ========================================================================= + + protected function listStages(string $projectId, bool $authenticated = true): mixed + { + $headers = [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + ]; + + if ($authenticated) { + $headers = array_merge($headers, $this->getHeaders()); + } + + return $this->client->call(Client::METHOD_GET, '/projects/' . $projectId . '/stages', $headers, []); + } + + protected function updateStage(string $projectId, string $stageId, bool $skip, bool $authenticated = true): mixed + { + $headers = [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + ]; + + if ($authenticated) { + $headers = array_merge($headers, $this->getHeaders()); + } + + return $this->client->call(Client::METHOD_PATCH, '/projects/' . $projectId . '/stages/' . $stageId, $headers, [ + 'skip' => $skip, + ]); + } + + /** + * Creates a new team and child project under the console session (isolated from cached getProject()). + */ + protected function createTeamAndProject(): string + { + $teamId = ID::unique(); + $team = $this->client->call(Client::METHOD_POST, '/teams', array_merge([ + 'content-type' => 'application/json', + 'x-appwrite-project' => 'console', + ], $this->getHeaders()), [ + 'teamId' => $teamId, + 'name' => 'Stages E2E Team', + ]); + + $this->assertContains($team['headers']['status-code'], [201, 409]); + if ($team['headers']['status-code'] === 201) { + $teamId = $team['body']['$id']; + } + + $project = $this->client->call(Client::METHOD_POST, '/projects', array_merge([ + 'content-type' => 'application/json', + 'x-appwrite-project' => 'console', + ], $this->getHeaders()), [ + 'projectId' => ID::unique(), + 'name' => 'Stages E2E Project', + 'teamId' => $teamId, + 'region' => System::getEnv('_APP_REGION', 'default'), + ]); + + $this->assertSame(201, $project['headers']['status-code']); + + return $project['body']['$id']; + } +} diff --git a/tests/e2e/Services/Project/StagesConsoleClientTest.php b/tests/e2e/Services/Project/StagesConsoleClientTest.php new file mode 100644 index 0000000000..cde4f4ab79 --- /dev/null +++ b/tests/e2e/Services/Project/StagesConsoleClientTest.php @@ -0,0 +1,14 @@ + Date: Sat, 11 Apr 2026 21:44:14 +0100 Subject: [PATCH 03/18] docs: add projects stages API reference markdown for spec generation Made-with: Cursor --- docs/references/projects/list-stages.md | 1 + docs/references/projects/update-stage.md | 1 + 2 files changed, 2 insertions(+) create mode 100644 docs/references/projects/list-stages.md create mode 100644 docs/references/projects/update-stage.md diff --git a/docs/references/projects/list-stages.md b/docs/references/projects/list-stages.md new file mode 100644 index 0000000000..3a2f6cc401 --- /dev/null +++ b/docs/references/projects/list-stages.md @@ -0,0 +1 @@ +Get the onboarding stages for the current project, including each stage’s SDK method key and status (for example pending, completed, or skipped). diff --git a/docs/references/projects/update-stage.md b/docs/references/projects/update-stage.md new file mode 100644 index 0000000000..9e6f43919e --- /dev/null +++ b/docs/references/projects/update-stage.md @@ -0,0 +1 @@ +Update an onboarding stage for the current project. Use this endpoint to skip a stage or leave it unchanged without performing the related API action. From 4bb5dfb6ffd4e66b6bb721cc9b7ef236f93953db Mon Sep 17 00:00:00 2001 From: eldadfux Date: Thu, 25 Jun 2026 15:37:07 -0400 Subject: [PATCH 04/18] 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']); } From 7b24acb5b6d477a0515bdd2709e6d851d572d74a Mon Sep 17 00:00:00 2001 From: eldadfux Date: Thu, 25 Jun 2026 15:53:58 -0400 Subject: [PATCH 05/18] Enhance API shutdown logic to persist onboarding stage completion after usage metrics are recorded. Introduce error handling for database updates to ensure reliability in onboarding status updates. --- app/controllers/shared/api.php | 206 +++++++++++++++++---------------- 1 file changed, 106 insertions(+), 100 deletions(-) diff --git a/app/controllers/shared/api.php b/app/controllers/shared/api.php index 8123be05e1..c16e590f4a 100644 --- a/app/controllers/shared/api.php +++ b/app/controllers/shared/api.php @@ -42,6 +42,7 @@ use Utopia\Span\Span; use Utopia\System\System; use Utopia\Telemetry\Adapter as Telemetry; use Utopia\Validator\WhiteList; +use Throwable; $parseLabel = function (string $label, array $responsePayload, array $requestParams, User $user, Document $project) { preg_match_all('/{(.*?)}/', $label, $matches); @@ -878,106 +879,6 @@ Http::shutdown() } }); -Http::shutdown() - ->groups(['api']) - ->inject('route') - ->inject('response') - ->inject('project') - ->inject('user') - ->inject('queueForRealtime') - ->inject('dbForPlatform') - ->inject('authorization') - ->inject('apiKey') - ->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`: method → row). - * Hot path: fail fast on status/console, O(1) onboarding key lookup, O(1) project state check — no work on unrelated routes. - */ - $statusCode = $response->getStatusCode(); - if ($statusCode < 200 || $statusCode >= 300 || $project->getId() === 'console') { - return; - } - - $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() ->groups(['api']) ->inject('route') @@ -1212,6 +1113,111 @@ Http::shutdown() } }); +Http::shutdown() + ->groups(['api']) + ->inject('route') + ->inject('response') + ->inject('project') + ->inject('user') + ->inject('queueForRealtime') + ->inject('dbForPlatform') + ->inject('authorization') + ->inject('apiKey') + ->inject('mode') + ->action(function (Route $route, Response $response, Document $project, User $user, Realtime $queueForRealtime, Database $dbForPlatform, Authorization $authorization, ?Key $apiKey, string $mode) { + /** + * Persist completed onboarding stage after usage shutdown so a schema/write failure here + * cannot suppress RequestCompleted or usage metrics on the same request. + */ + $statusCode = $response->getStatusCode(); + if ($statusCode < 200 || $statusCode >= 300 || $project->getId() === 'console') { + return; + } + + $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, + ]; + + try { + $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(); + } catch (Throwable) { + // Missing `onboarding` attribute on upgraded installs must not break the request lifecycle. + } + }); + Http::init() ->groups(['usage']) ->action(function () { From c1a03613928052606fbe97a22cbadd53695ac901 Mon Sep 17 00:00:00 2001 From: eldadfux Date: Thu, 25 Jun 2026 16:31:24 -0400 Subject: [PATCH 06/18] Update onboarding configuration to include account creation permissions and adjust API role checks. Modify migration versioning for consistency and refactor project stage tests to streamline project ID retrieval. --- app/config/onboarding.php | 2 + app/controllers/shared/api.php | 2 +- src/Appwrite/Migration/Migration.php | 1 + .../Modules/Projects/Http/Stages/Update.php | 2 +- tests/e2e/Services/Project/StagesBase.php | 76 ++++--------------- .../Project/StagesConsoleClientTest.php | 4 +- 6 files changed, 21 insertions(+), 66 deletions(-) diff --git a/app/config/onboarding.php b/app/config/onboarding.php index 72f2861206..38f2bb8ec5 100644 --- a/app/config/onboarding.php +++ b/app/config/onboarding.php @@ -17,6 +17,8 @@ return [ // Auth 'users.create' => true, + 'account.create' => true, + 'account.createAnonymousSession' => true, 'teams.create' => true, // Databases — tablesDB diff --git a/app/controllers/shared/api.php b/app/controllers/shared/api.php index c16e590f4a..9a894c4587 100644 --- a/app/controllers/shared/api.php +++ b/app/controllers/shared/api.php @@ -1178,7 +1178,7 @@ Http::shutdown() $byMethod = []; } - $actorType = ($apiKey !== null && $apiKey->getRole() === User::ROLE_APPS) + $actorType = ($apiKey !== null && $apiKey->getRole() === User::ROLE_KEYS) ? match ($apiKey->getType()) { API_KEY_ACCOUNT => ACTOR_TYPE_KEY_ACCOUNT, API_KEY_ORGANIZATION => ACTOR_TYPE_KEY_ORGANIZATION, diff --git a/src/Appwrite/Migration/Migration.php b/src/Appwrite/Migration/Migration.php index 77c62bce96..93d8994d7c 100644 --- a/src/Appwrite/Migration/Migration.php +++ b/src/Appwrite/Migration/Migration.php @@ -98,6 +98,7 @@ abstract class Migration '1.9.3' => 'V24', '1.9.4' => 'V24', '1.9.5' => 'V24', + '1.9.6' => 'V25', ]; /** diff --git a/src/Appwrite/Platform/Modules/Projects/Http/Stages/Update.php b/src/Appwrite/Platform/Modules/Projects/Http/Stages/Update.php index 910b2dcf63..c345712bc8 100644 --- a/src/Appwrite/Platform/Modules/Projects/Http/Stages/Update.php +++ b/src/Appwrite/Platform/Modules/Projects/Http/Stages/Update.php @@ -126,7 +126,7 @@ class Update extends Action private function resolveActorType(?Key $apiKey, User $user, string $mode): string { - if ($apiKey !== null && $apiKey->getRole() === User::ROLE_APPS) { + if ($apiKey !== null && $apiKey->getRole() === User::ROLE_KEYS) { return match ($apiKey->getType()) { API_KEY_ACCOUNT => ACTOR_TYPE_KEY_ACCOUNT, API_KEY_ORGANIZATION => ACTOR_TYPE_KEY_ORGANIZATION, diff --git a/tests/e2e/Services/Project/StagesBase.php b/tests/e2e/Services/Project/StagesBase.php index ff7a56359d..471fdd9acb 100644 --- a/tests/e2e/Services/Project/StagesBase.php +++ b/tests/e2e/Services/Project/StagesBase.php @@ -3,24 +3,19 @@ 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; trait StagesBase { - use Async; - // ========================================================================= // List stages tests // ========================================================================= public function testListProjectStages(): void { - $projectId = $this->createTeamAndProject(); + $projectId = $this->getProject()['$id']; $response = $this->listStages($projectId); @@ -38,20 +33,12 @@ trait StagesBase $this->assertArrayHasKey('status', $stage); $this->assertArrayHasKey('at', $stage); $this->assertArrayHasKey('actorType', $stage); - $this->assertSame('pending', $stage['status']); } - - // Verify via GET for unknown project - $response = $this->listStages(ID::unique()); - $this->assertSame(404, $response['headers']['status-code']); - $this->assertSame(Exception::PROJECT_NOT_FOUND, $response['body']['type']); } public function testListProjectStagesWithoutAuthentication(): void { - $projectId = $this->createTeamAndProject(); - - $response = $this->listStages($projectId, false); + $response = $this->listStages($this->getProject()['$id'], false); $this->assertSame(401, $response['headers']['status-code']); } @@ -62,7 +49,7 @@ trait StagesBase public function testUpdateProjectStageSkip(): void { - $projectId = $this->createTeamAndProject(); + $projectId = $this->getProject()['$id']; $method = 'tablesDB.create'; $response = $this->updateStage($projectId, $method, true); @@ -93,15 +80,11 @@ trait StagesBase $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(), 'storage.createBucket', true); - $this->assertSame(404, $response['headers']['status-code']); - $this->assertSame(Exception::PROJECT_NOT_FOUND, $response['body']['type']); } public function testUpdateProjectStageSkipFalseLeavesPending(): void { - $projectId = $this->createTeamAndProject(); + $projectId = $this->getProject()['$id']; $method = 'storage.createBucket'; $response = $this->updateStage($projectId, $method, false); @@ -113,9 +96,7 @@ trait StagesBase public function testUpdateProjectStageWithoutAuthentication(): void { - $projectId = $this->createTeamAndProject(); - - $response = $this->updateStage($projectId, 'tablesDB.create', true, false); + $response = $this->updateStage($this->getProject()['$id'], 'tablesDB.create', true, false); $this->assertSame(401, $response['headers']['status-code']); } @@ -126,13 +107,15 @@ trait StagesBase protected function listStages(string $projectId, bool $authenticated = true): mixed { + // Stages live under /projects (console scope); use the root console session. $headers = [ 'content-type' => 'application/json', - 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-project' => 'console', ]; if ($authenticated) { - $headers = array_merge($headers, $this->getHeaders()); + $headers['origin'] = 'http://localhost'; + $headers['cookie'] = 'a_session_console=' . $this->getRoot()['session']; } return $this->client->call(Client::METHOD_GET, '/projects/' . $projectId . '/stages', $headers, []); @@ -142,49 +125,16 @@ trait StagesBase { $headers = [ 'content-type' => 'application/json', - 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-project' => 'console', ]; if ($authenticated) { - $headers = array_merge($headers, $this->getHeaders()); + $headers['origin'] = 'http://localhost'; + $headers['cookie'] = 'a_session_console=' . $this->getRoot()['session']; } - return $this->client->call(Client::METHOD_PATCH, '/projects/' . $projectId . '/stages/' . $stageId, $headers, [ + return $this->client->call(Client::METHOD_PATCH, '/projects/' . $projectId . '/stages/' . rawurlencode($stageId), $headers, [ 'skip' => $skip, ]); } - - /** - * Creates a new team and child project under the console session (isolated from cached getProject()). - */ - protected function createTeamAndProject(): string - { - $teamId = ID::unique(); - $team = $this->client->call(Client::METHOD_POST, '/teams', array_merge([ - 'content-type' => 'application/json', - 'x-appwrite-project' => 'console', - ], $this->getHeaders()), [ - 'teamId' => $teamId, - 'name' => 'Stages E2E Team', - ]); - - $this->assertContains($team['headers']['status-code'], [201, 409]); - if ($team['headers']['status-code'] === 201) { - $teamId = $team['body']['$id']; - } - - $project = $this->client->call(Client::METHOD_POST, '/projects', array_merge([ - 'content-type' => 'application/json', - 'x-appwrite-project' => 'console', - ], $this->getHeaders()), [ - 'projectId' => ID::unique(), - 'name' => 'Stages E2E Project', - 'teamId' => $teamId, - 'region' => System::getEnv('_APP_REGION', 'default'), - ]); - - $this->assertSame(201, $project['headers']['status-code']); - - return $project['body']['$id']; - } } diff --git a/tests/e2e/Services/Project/StagesConsoleClientTest.php b/tests/e2e/Services/Project/StagesConsoleClientTest.php index cde4f4ab79..51ba5fa3e4 100644 --- a/tests/e2e/Services/Project/StagesConsoleClientTest.php +++ b/tests/e2e/Services/Project/StagesConsoleClientTest.php @@ -1,12 +1,14 @@ Date: Thu, 25 Jun 2026 16:40:14 -0400 Subject: [PATCH 07/18] Remove migration version mapping for '1.9.6' to maintain consistency in versioning. --- src/Appwrite/Migration/Migration.php | 1 - 1 file changed, 1 deletion(-) diff --git a/src/Appwrite/Migration/Migration.php b/src/Appwrite/Migration/Migration.php index 93d8994d7c..77c62bce96 100644 --- a/src/Appwrite/Migration/Migration.php +++ b/src/Appwrite/Migration/Migration.php @@ -98,7 +98,6 @@ abstract class Migration '1.9.3' => 'V24', '1.9.4' => 'V24', '1.9.5' => 'V24', - '1.9.6' => 'V25', ]; /** From 67fd6226a90dd5d2448c45d202d75988f7b79161 Mon Sep 17 00:00:00 2001 From: eldadfux Date: Thu, 25 Jun 2026 16:41:14 -0400 Subject: [PATCH 08/18] Refactor API role determination logic for improved readability and maintainability. Remove unused Throwable import and adjust formatting for consistency. --- app/controllers/shared/api.php | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/app/controllers/shared/api.php b/app/controllers/shared/api.php index 9a894c4587..150a2bcd6b 100644 --- a/app/controllers/shared/api.php +++ b/app/controllers/shared/api.php @@ -23,6 +23,7 @@ use Appwrite\Usage\Context; use Appwrite\Utopia\Database\Documents\User; use Appwrite\Utopia\Request; use Appwrite\Utopia\Response; +use Throwable; use Utopia\Abuse\Abuse; use Utopia\Bus\Bus; use Utopia\Cache\Adapter\Filesystem; @@ -42,7 +43,6 @@ use Utopia\Span\Span; use Utopia\System\System; use Utopia\Telemetry\Adapter as Telemetry; use Utopia\Validator\WhiteList; -use Throwable; $parseLabel = function (string $label, array $responsePayload, array $requestParams, User $user, Document $project) { preg_match_all('/{(.*?)}/', $label, $matches); @@ -1185,9 +1185,9 @@ Http::shutdown() 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); + : (! $user->isEmpty() + ? ($mode === APP_MODE_ADMIN ? ACTOR_TYPE_ADMIN : ACTOR_TYPE_USER) + : ACTOR_TYPE_GUEST); $byMethod[$method] = [ 'status' => ONBOARDING_STATUS_COMPLETED, 'at' => DateTime::now(), From 5ee82afc8c3eeb99306bbc3397a399513acf7730 Mon Sep 17 00:00:00 2001 From: eldadfux Date: Thu, 25 Jun 2026 17:41:30 -0400 Subject: [PATCH 09/18] Remove unused queueForRealtime injection from API shutdown logic to streamline onboarding process. Adjust related action parameters for improved clarity and maintainability. --- app/controllers/shared/api.php | 18 +----------------- 1 file changed, 1 insertion(+), 17 deletions(-) diff --git a/app/controllers/shared/api.php b/app/controllers/shared/api.php index 150a2bcd6b..e30305e55b 100644 --- a/app/controllers/shared/api.php +++ b/app/controllers/shared/api.php @@ -1119,12 +1119,11 @@ Http::shutdown() ->inject('response') ->inject('project') ->inject('user') - ->inject('queueForRealtime') ->inject('dbForPlatform') ->inject('authorization') ->inject('apiKey') ->inject('mode') - ->action(function (Route $route, Response $response, Document $project, User $user, Realtime $queueForRealtime, Database $dbForPlatform, Authorization $authorization, ?Key $apiKey, string $mode) { + ->action(function (Route $route, Response $response, Document $project, User $user, Database $dbForPlatform, Authorization $authorization, ?Key $apiKey, string $mode) { /** * Persist completed onboarding stage after usage shutdown so a schema/write failure here * cannot suppress RequestCompleted or usage metrics on the same request. @@ -1198,21 +1197,6 @@ Http::shutdown() $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(); } catch (Throwable) { // Missing `onboarding` attribute on upgraded installs must not break the request lifecycle. } From 696b266fc50e394a9d2d26b15a910787238ae6ec Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 28 Jun 2026 04:31:31 +0000 Subject: [PATCH 10/18] fix(projects): mark deployment onboarding stages from the build lifecycle The deployment onboarding stages (functions.createDeployment, functions.updateFunctionDeployment, sites.createDeployment, sites.updateSiteDeployment) never marked on a normal deploy because the shutdown hook keys onboarding off the request's SDK method: - deployments are created via several paths (manual upload, template, duplicate, and VCS webhooks) whose SDK methods differ from createDeployment, and VCS creates the deployment server-side with no labelled request; - activation is performed by the builds worker via the activate flag, not the updateFunctionDeployment/updateSiteDeployment routes, so those stages were effectively unreachable. Mark these stages at the build-lifecycle choke point instead, where every creation path and the worker-driven activation converge. Extract the read-modify-write into a reusable Appwrite\Onboarding\Onboarding helper that persists multiple stages in a single update (so create + activate cannot clobber each other), and have the API shutdown hook reuse it. The builds worker writes onboarding via dbForPlatform - the same platform (console) database it already updates for the rules collection during activation - so the write reaches the central console store. --- app/controllers/shared/api.php | 25 +----- app/init/constants.php | 1 + src/Appwrite/Onboarding/Onboarding.php | 70 +++++++++++++++ .../Modules/Functions/Workers/Builds.php | 19 ++++ tests/unit/Onboarding/OnboardingTest.php | 89 +++++++++++++++++++ 5 files changed, 181 insertions(+), 23 deletions(-) create mode 100644 src/Appwrite/Onboarding/Onboarding.php create mode 100644 tests/unit/Onboarding/OnboardingTest.php diff --git a/app/controllers/shared/api.php b/app/controllers/shared/api.php index e30305e55b..6f040fc4b5 100644 --- a/app/controllers/shared/api.php +++ b/app/controllers/shared/api.php @@ -16,6 +16,7 @@ use Appwrite\Event\Webhook; use Appwrite\Extend\Exception; use Appwrite\Extend\Exception as AppwriteException; use Appwrite\Functions\EventProcessor; +use Appwrite\Onboarding\Onboarding; use Appwrite\Platform\Modules\Storage\Config\CacheControl; use Appwrite\Platform\Modules\Storage\Config\StorageCacheControl; use Appwrite\SDK\Method; @@ -23,7 +24,6 @@ use Appwrite\Usage\Context; use Appwrite\Utopia\Database\Documents\User; use Appwrite\Utopia\Request; use Appwrite\Utopia\Response; -use Throwable; use Utopia\Abuse\Abuse; use Utopia\Bus\Bus; use Utopia\Cache\Adapter\Filesystem; @@ -1167,16 +1167,6 @@ Http::shutdown() 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_KEYS) ? match ($apiKey->getType()) { API_KEY_ACCOUNT => ACTOR_TYPE_KEY_ACCOUNT, @@ -1187,19 +1177,8 @@ Http::shutdown() : (! $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, - ]; - try { - $authorization->skip(fn () => $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ - 'onboarding' => $byMethod, - ]))); - } catch (Throwable) { - // Missing `onboarding` attribute on upgraded installs must not break the request lifecycle. - } + $authorization->skip(fn () => Onboarding::complete($dbForPlatform, $project, [$method], $actorType)); }); Http::init() diff --git a/app/init/constants.php b/app/init/constants.php index 9efb6e3222..62819d601b 100644 --- a/app/init/constants.php +++ b/app/init/constants.php @@ -171,6 +171,7 @@ const ACTOR_TYPE_GUEST = 'guest'; const ACTOR_TYPE_KEY_PROJECT = 'keyProject'; const ACTOR_TYPE_KEY_ACCOUNT = 'keyAccount'; const ACTOR_TYPE_KEY_ORGANIZATION = 'keyOrganization'; +const ACTOR_TYPE_SYSTEM = 'system'; /** * Project onboarding stage status (stored per SDK method key under project.onboarding JSON). diff --git a/src/Appwrite/Onboarding/Onboarding.php b/src/Appwrite/Onboarding/Onboarding.php new file mode 100644 index 0000000000..555c3a10be --- /dev/null +++ b/src/Appwrite/Onboarding/Onboarding.php @@ -0,0 +1,70 @@ + $methods + */ + public static function complete(Database $dbForPlatform, Document $project, array $methods, string $actorType): void + { + if ($project->getId() === 'console' || $methods === []) { + return; + } + + $onboarding = Config::getParam('onboarding', []); + + $byMethod = $project->getAttribute('onboarding', []); + if (! \is_array($byMethod)) { + $byMethod = []; + } + + $changed = false; + foreach ($methods as $method) { + if (! isset($onboarding[$method])) { + continue; + } + + $status = $byMethod[$method]['status'] ?? null; + if ($status === ONBOARDING_STATUS_COMPLETED || $status === ONBOARDING_STATUS_SKIPPED) { + continue; + } + + $byMethod[$method] = [ + 'status' => ONBOARDING_STATUS_COMPLETED, + 'at' => DateTime::now(), + 'actorType' => $actorType, + ]; + $changed = true; + } + + if (! $changed) { + return; + } + + try { + $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ + 'onboarding' => $byMethod, + ])); + } catch (Throwable) { + // Missing `onboarding` attribute on upgraded installs must not break the caller. + } + } +} diff --git a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php index d0806ccadf..2128dd610a 100644 --- a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php +++ b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php @@ -13,6 +13,7 @@ use Appwrite\Event\Realtime; use Appwrite\Event\Webhook; use Appwrite\Extend\Exception as AppwriteException; use Appwrite\Filter\BranchDomain as BranchDomainFilter; +use Appwrite\Onboarding\Onboarding; use Appwrite\Usage\Context; use Appwrite\Utopia\Response\Model\Deployment; use Appwrite\Vcs\Comment; @@ -1039,6 +1040,24 @@ class Builds extends Action Span::add('build.activated', true); } + /** + * Mark deployment onboarding stages. Done here (not via the HTTP sdk + * label) so every creation path - manual upload, template, duplicate + * and VCS - and the worker-driven activation are all covered. + */ + $onboardingMethods = match ($resource->getCollection()) { + 'functions' => ['create' => 'functions.createDeployment', 'activate' => 'functions.updateFunctionDeployment'], + 'sites' => ['create' => 'sites.createDeployment', 'activate' => 'sites.updateSiteDeployment'], + default => null, + }; + if ($onboardingMethods !== null) { + $stages = [$onboardingMethods['create']]; + if ($activateBuild) { + $stages[] = $onboardingMethods['activate']; + } + Onboarding::complete($dbForPlatform, $project, $stages, ACTOR_TYPE_SYSTEM); + } + $resource = $this->updateLatestDeployment($dbForProject, $resource); $this->afterDeploymentSuccess( diff --git a/tests/unit/Onboarding/OnboardingTest.php b/tests/unit/Onboarding/OnboardingTest.php new file mode 100644 index 0000000000..97ac84e9e0 --- /dev/null +++ b/tests/unit/Onboarding/OnboardingTest.php @@ -0,0 +1,89 @@ + true, + 'functions.updateFunctionDeployment' => true, + 'sites.createDeployment' => true, + ]); + } + + public function testCompletesMultipleStagesInASingleWrite(): void + { + $project = new Document(['$id' => 'project1', 'onboarding' => []]); + + $dbForPlatform = $this->createMock(Database::class); + $dbForPlatform->expects($this->once()) + ->method('updateDocument') + ->with( + 'projects', + 'project1', + $this->callback(function (Document $document): bool { + $onboarding = $document->getAttribute('onboarding'); + + return isset($onboarding['functions.createDeployment'], $onboarding['functions.updateFunctionDeployment']) + && $onboarding['functions.createDeployment']['status'] === ONBOARDING_STATUS_COMPLETED + && $onboarding['functions.createDeployment']['actorType'] === ACTOR_TYPE_SYSTEM + && ! empty($onboarding['functions.createDeployment']['at']); + }) + ); + + Onboarding::complete($dbForPlatform, $project, [ + 'functions.createDeployment', + 'functions.updateFunctionDeployment', + ], ACTOR_TYPE_SYSTEM); + } + + public function testIgnoresConsoleProject(): void + { + $project = new Document(['$id' => 'console', 'onboarding' => []]); + + $dbForPlatform = $this->createMock(Database::class); + $dbForPlatform->expects($this->never())->method('updateDocument'); + + Onboarding::complete($dbForPlatform, $project, ['functions.createDeployment'], ACTOR_TYPE_SYSTEM); + } + + public function testIgnoresUnknownAndAlreadyCompletedMethods(): void + { + $project = new Document(['$id' => 'project1', 'onboarding' => [ + 'functions.createDeployment' => [ + 'status' => ONBOARDING_STATUS_COMPLETED, + 'at' => '2026-01-01 00:00:00.000', + 'actorType' => ACTOR_TYPE_USER, + ], + ]]); + + $dbForPlatform = $this->createMock(Database::class); + $dbForPlatform->expects($this->never())->method('updateDocument'); + + Onboarding::complete($dbForPlatform, $project, ['functions.createDeployment', 'unknown.method'], ACTOR_TYPE_SYSTEM); + } + + public function testDoesNotOverwriteSkippedStage(): void + { + $project = new Document(['$id' => 'project1', 'onboarding' => [ + 'sites.createDeployment' => [ + 'status' => ONBOARDING_STATUS_SKIPPED, + 'at' => '2026-01-01 00:00:00.000', + 'actorType' => ACTOR_TYPE_USER, + ], + ]]); + + $dbForPlatform = $this->createMock(Database::class); + $dbForPlatform->expects($this->never())->method('updateDocument'); + + Onboarding::complete($dbForPlatform, $project, ['sites.createDeployment'], ACTOR_TYPE_SYSTEM); + } +} From 6d52a695a22db66f742d4e4f52a039e104860b69 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 28 Jun 2026 04:44:23 +0000 Subject: [PATCH 11/18] feat(projects): per-type deployment onboarding stages Replace the single createDeployment stage with one key per deployment type (manual, cli, vcs) for functions and sites, keyed off the deployment `type` attribute. Every creation path maps to a type - manual upload -> manual, CLI -> cli, template + VCS/GitHub -> vcs - and the build worker marks the matching stage. Activation still marks updateFunctionDeployment/updateSiteDeployment. The UI can OR the per-type stages for a single "created a deployment" milestone while still tracking which deployment methods a project has used. --- app/config/onboarding.php | 12 +++++- .../Modules/Functions/Workers/Builds.php | 42 ++++++++++++++----- tests/unit/Onboarding/OnboardingTest.php | 26 ++++++------ 3 files changed, 56 insertions(+), 24 deletions(-) diff --git a/app/config/onboarding.php b/app/config/onboarding.php index 38f2bb8ec5..5b73328e25 100644 --- a/app/config/onboarding.php +++ b/app/config/onboarding.php @@ -40,7 +40,11 @@ return [ // Functions 'functions.create' => true, - 'functions.createDeployment' => true, + // One key per deployment creation type (deployment `type` attribute); + // OR them in the UI for a single "created a deployment" milestone. + 'functions.createManualDeployment' => true, + 'functions.createCliDeployment' => true, + 'functions.createVcsDeployment' => true, 'functions.updateFunctionDeployment' => true, // Messaging @@ -63,6 +67,10 @@ return [ // Sites 'sites.create' => true, - 'sites.createDeployment' => true, + // One key per deployment creation type (deployment `type` attribute); + // OR them in the UI for a single "created a deployment" milestone. + 'sites.createManualDeployment' => true, + 'sites.createCliDeployment' => true, + 'sites.createVcsDeployment' => true, 'sites.updateSiteDeployment' => true, ]; diff --git a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php index 2128dd610a..35ae9948d8 100644 --- a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php +++ b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php @@ -1042,19 +1042,41 @@ class Builds extends Action /** * Mark deployment onboarding stages. Done here (not via the HTTP sdk - * label) so every creation path - manual upload, template, duplicate - * and VCS - and the worker-driven activation are all covered. + * label) so every creation path - manual upload, CLI, template, + * duplicate and VCS - and the worker-driven activation are covered. + * The create stage is keyed by the deployment `type` so each type + * has its own stage (OR them in the UI for a single milestone). */ - $onboardingMethods = match ($resource->getCollection()) { - 'functions' => ['create' => 'functions.createDeployment', 'activate' => 'functions.updateFunctionDeployment'], - 'sites' => ['create' => 'sites.createDeployment', 'activate' => 'sites.updateSiteDeployment'], + $collection = $resource->getCollection(); + $createStage = match ($collection) { + 'functions' => match ($deployment->getAttribute('type')) { + 'manual' => 'functions.createManualDeployment', + 'cli' => 'functions.createCliDeployment', + 'vcs' => 'functions.createVcsDeployment', + default => null, + }, + 'sites' => match ($deployment->getAttribute('type')) { + 'manual' => 'sites.createManualDeployment', + 'cli' => 'sites.createCliDeployment', + 'vcs' => 'sites.createVcsDeployment', + default => null, + }, default => null, }; - if ($onboardingMethods !== null) { - $stages = [$onboardingMethods['create']]; - if ($activateBuild) { - $stages[] = $onboardingMethods['activate']; - } + $activateStage = match ($collection) { + 'functions' => 'functions.updateFunctionDeployment', + 'sites' => 'sites.updateSiteDeployment', + default => null, + }; + + $stages = []; + if ($createStage !== null) { + $stages[] = $createStage; + } + if ($activateBuild && $activateStage !== null) { + $stages[] = $activateStage; + } + if ($stages !== []) { Onboarding::complete($dbForPlatform, $project, $stages, ACTOR_TYPE_SYSTEM); } diff --git a/tests/unit/Onboarding/OnboardingTest.php b/tests/unit/Onboarding/OnboardingTest.php index 97ac84e9e0..2ce7d2635d 100644 --- a/tests/unit/Onboarding/OnboardingTest.php +++ b/tests/unit/Onboarding/OnboardingTest.php @@ -13,9 +13,11 @@ final class OnboardingTest extends TestCase protected function setUp(): void { Config::setParam('onboarding', [ - 'functions.createDeployment' => true, + 'functions.createManualDeployment' => true, + 'functions.createCliDeployment' => true, + 'functions.createVcsDeployment' => true, 'functions.updateFunctionDeployment' => true, - 'sites.createDeployment' => true, + 'sites.createVcsDeployment' => true, ]); } @@ -32,15 +34,15 @@ final class OnboardingTest extends TestCase $this->callback(function (Document $document): bool { $onboarding = $document->getAttribute('onboarding'); - return isset($onboarding['functions.createDeployment'], $onboarding['functions.updateFunctionDeployment']) - && $onboarding['functions.createDeployment']['status'] === ONBOARDING_STATUS_COMPLETED - && $onboarding['functions.createDeployment']['actorType'] === ACTOR_TYPE_SYSTEM - && ! empty($onboarding['functions.createDeployment']['at']); + return isset($onboarding['functions.createCliDeployment'], $onboarding['functions.updateFunctionDeployment']) + && $onboarding['functions.createCliDeployment']['status'] === ONBOARDING_STATUS_COMPLETED + && $onboarding['functions.createCliDeployment']['actorType'] === ACTOR_TYPE_SYSTEM + && ! empty($onboarding['functions.createCliDeployment']['at']); }) ); Onboarding::complete($dbForPlatform, $project, [ - 'functions.createDeployment', + 'functions.createCliDeployment', 'functions.updateFunctionDeployment', ], ACTOR_TYPE_SYSTEM); } @@ -52,13 +54,13 @@ final class OnboardingTest extends TestCase $dbForPlatform = $this->createMock(Database::class); $dbForPlatform->expects($this->never())->method('updateDocument'); - Onboarding::complete($dbForPlatform, $project, ['functions.createDeployment'], ACTOR_TYPE_SYSTEM); + Onboarding::complete($dbForPlatform, $project, ['functions.createCliDeployment'], ACTOR_TYPE_SYSTEM); } public function testIgnoresUnknownAndAlreadyCompletedMethods(): void { $project = new Document(['$id' => 'project1', 'onboarding' => [ - 'functions.createDeployment' => [ + 'functions.createCliDeployment' => [ 'status' => ONBOARDING_STATUS_COMPLETED, 'at' => '2026-01-01 00:00:00.000', 'actorType' => ACTOR_TYPE_USER, @@ -68,13 +70,13 @@ final class OnboardingTest extends TestCase $dbForPlatform = $this->createMock(Database::class); $dbForPlatform->expects($this->never())->method('updateDocument'); - Onboarding::complete($dbForPlatform, $project, ['functions.createDeployment', 'unknown.method'], ACTOR_TYPE_SYSTEM); + Onboarding::complete($dbForPlatform, $project, ['functions.createCliDeployment', 'unknown.method'], ACTOR_TYPE_SYSTEM); } public function testDoesNotOverwriteSkippedStage(): void { $project = new Document(['$id' => 'project1', 'onboarding' => [ - 'sites.createDeployment' => [ + 'sites.createVcsDeployment' => [ 'status' => ONBOARDING_STATUS_SKIPPED, 'at' => '2026-01-01 00:00:00.000', 'actorType' => ACTOR_TYPE_USER, @@ -84,6 +86,6 @@ final class OnboardingTest extends TestCase $dbForPlatform = $this->createMock(Database::class); $dbForPlatform->expects($this->never())->method('updateDocument'); - Onboarding::complete($dbForPlatform, $project, ['sites.createDeployment'], ACTOR_TYPE_SYSTEM); + Onboarding::complete($dbForPlatform, $project, ['sites.createVcsDeployment'], ACTOR_TYPE_SYSTEM); } } From d67b9c9326bd1ecf97bc6dd5abece02a88bf3820 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 28 Jun 2026 05:15:07 +0000 Subject: [PATCH 12/18] test: add declare(strict_types=1) to OnboardingTest (Rector) --- tests/unit/Onboarding/OnboardingTest.php | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tests/unit/Onboarding/OnboardingTest.php b/tests/unit/Onboarding/OnboardingTest.php index 2ce7d2635d..e138e8e4ed 100644 --- a/tests/unit/Onboarding/OnboardingTest.php +++ b/tests/unit/Onboarding/OnboardingTest.php @@ -1,5 +1,7 @@ Date: Sun, 28 Jun 2026 05:30:27 +0000 Subject: [PATCH 13/18] refactor: inline deployment onboarding write, drop Onboarding helper Keep the existing inline read-modify-write pattern instead of a shared helper class. The builds worker writes the per-type deployment stages (and activation) directly via dbForPlatform; the API shutdown hook is unchanged from the base branch. Removes the Onboarding helper and its unit test. --- app/controllers/shared/api.php | 25 ++++- src/Appwrite/Onboarding/Onboarding.php | 70 -------------- .../Modules/Functions/Workers/Builds.php | 31 ++++++- tests/unit/Onboarding/OnboardingTest.php | 93 ------------------- 4 files changed, 52 insertions(+), 167 deletions(-) delete mode 100644 src/Appwrite/Onboarding/Onboarding.php delete mode 100644 tests/unit/Onboarding/OnboardingTest.php diff --git a/app/controllers/shared/api.php b/app/controllers/shared/api.php index 6f040fc4b5..e30305e55b 100644 --- a/app/controllers/shared/api.php +++ b/app/controllers/shared/api.php @@ -16,7 +16,6 @@ use Appwrite\Event\Webhook; use Appwrite\Extend\Exception; use Appwrite\Extend\Exception as AppwriteException; use Appwrite\Functions\EventProcessor; -use Appwrite\Onboarding\Onboarding; use Appwrite\Platform\Modules\Storage\Config\CacheControl; use Appwrite\Platform\Modules\Storage\Config\StorageCacheControl; use Appwrite\SDK\Method; @@ -24,6 +23,7 @@ use Appwrite\Usage\Context; use Appwrite\Utopia\Database\Documents\User; use Appwrite\Utopia\Request; use Appwrite\Utopia\Response; +use Throwable; use Utopia\Abuse\Abuse; use Utopia\Bus\Bus; use Utopia\Cache\Adapter\Filesystem; @@ -1167,6 +1167,16 @@ Http::shutdown() 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_KEYS) ? match ($apiKey->getType()) { API_KEY_ACCOUNT => ACTOR_TYPE_KEY_ACCOUNT, @@ -1177,8 +1187,19 @@ Http::shutdown() : (! $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 () => Onboarding::complete($dbForPlatform, $project, [$method], $actorType)); + try { + $authorization->skip(fn () => $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ + 'onboarding' => $byMethod, + ]))); + } catch (Throwable) { + // Missing `onboarding` attribute on upgraded installs must not break the request lifecycle. + } }); Http::init() diff --git a/src/Appwrite/Onboarding/Onboarding.php b/src/Appwrite/Onboarding/Onboarding.php deleted file mode 100644 index 555c3a10be..0000000000 --- a/src/Appwrite/Onboarding/Onboarding.php +++ /dev/null @@ -1,70 +0,0 @@ - $methods - */ - public static function complete(Database $dbForPlatform, Document $project, array $methods, string $actorType): void - { - if ($project->getId() === 'console' || $methods === []) { - return; - } - - $onboarding = Config::getParam('onboarding', []); - - $byMethod = $project->getAttribute('onboarding', []); - if (! \is_array($byMethod)) { - $byMethod = []; - } - - $changed = false; - foreach ($methods as $method) { - if (! isset($onboarding[$method])) { - continue; - } - - $status = $byMethod[$method]['status'] ?? null; - if ($status === ONBOARDING_STATUS_COMPLETED || $status === ONBOARDING_STATUS_SKIPPED) { - continue; - } - - $byMethod[$method] = [ - 'status' => ONBOARDING_STATUS_COMPLETED, - 'at' => DateTime::now(), - 'actorType' => $actorType, - ]; - $changed = true; - } - - if (! $changed) { - return; - } - - try { - $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ - 'onboarding' => $byMethod, - ])); - } catch (Throwable) { - // Missing `onboarding` attribute on upgraded installs must not break the caller. - } - } -} diff --git a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php index 35ae9948d8..1a64ce235e 100644 --- a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php +++ b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php @@ -13,7 +13,6 @@ use Appwrite\Event\Realtime; use Appwrite\Event\Webhook; use Appwrite\Extend\Exception as AppwriteException; use Appwrite\Filter\BranchDomain as BranchDomainFilter; -use Appwrite\Onboarding\Onboarding; use Appwrite\Usage\Context; use Appwrite\Utopia\Response\Model\Deployment; use Appwrite\Vcs\Comment; @@ -1076,8 +1075,36 @@ class Builds extends Action if ($activateBuild && $activateStage !== null) { $stages[] = $activateStage; } + if ($stages !== []) { - Onboarding::complete($dbForPlatform, $project, $stages, ACTOR_TYPE_SYSTEM); + $onboarding = $project->getAttribute('onboarding', []); + if (! \is_array($onboarding)) { + $onboarding = []; + } + + $onboardingChanged = false; + foreach ($stages as $stage) { + $stageStatus = $onboarding[$stage]['status'] ?? null; + if ($stageStatus === ONBOARDING_STATUS_COMPLETED || $stageStatus === ONBOARDING_STATUS_SKIPPED) { + continue; + } + $onboarding[$stage] = [ + 'status' => ONBOARDING_STATUS_COMPLETED, + 'at' => DateTime::now(), + 'actorType' => ACTOR_TYPE_SYSTEM, + ]; + $onboardingChanged = true; + } + + if ($onboardingChanged) { + try { + $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ + 'onboarding' => $onboarding, + ])); + } catch (\Throwable) { + // Missing `onboarding` attribute on upgraded installs must not break the build lifecycle. + } + } } $resource = $this->updateLatestDeployment($dbForProject, $resource); diff --git a/tests/unit/Onboarding/OnboardingTest.php b/tests/unit/Onboarding/OnboardingTest.php deleted file mode 100644 index e138e8e4ed..0000000000 --- a/tests/unit/Onboarding/OnboardingTest.php +++ /dev/null @@ -1,93 +0,0 @@ - true, - 'functions.createCliDeployment' => true, - 'functions.createVcsDeployment' => true, - 'functions.updateFunctionDeployment' => true, - 'sites.createVcsDeployment' => true, - ]); - } - - public function testCompletesMultipleStagesInASingleWrite(): void - { - $project = new Document(['$id' => 'project1', 'onboarding' => []]); - - $dbForPlatform = $this->createMock(Database::class); - $dbForPlatform->expects($this->once()) - ->method('updateDocument') - ->with( - 'projects', - 'project1', - $this->callback(function (Document $document): bool { - $onboarding = $document->getAttribute('onboarding'); - - return isset($onboarding['functions.createCliDeployment'], $onboarding['functions.updateFunctionDeployment']) - && $onboarding['functions.createCliDeployment']['status'] === ONBOARDING_STATUS_COMPLETED - && $onboarding['functions.createCliDeployment']['actorType'] === ACTOR_TYPE_SYSTEM - && ! empty($onboarding['functions.createCliDeployment']['at']); - }) - ); - - Onboarding::complete($dbForPlatform, $project, [ - 'functions.createCliDeployment', - 'functions.updateFunctionDeployment', - ], ACTOR_TYPE_SYSTEM); - } - - public function testIgnoresConsoleProject(): void - { - $project = new Document(['$id' => 'console', 'onboarding' => []]); - - $dbForPlatform = $this->createMock(Database::class); - $dbForPlatform->expects($this->never())->method('updateDocument'); - - Onboarding::complete($dbForPlatform, $project, ['functions.createCliDeployment'], ACTOR_TYPE_SYSTEM); - } - - public function testIgnoresUnknownAndAlreadyCompletedMethods(): void - { - $project = new Document(['$id' => 'project1', 'onboarding' => [ - 'functions.createCliDeployment' => [ - 'status' => ONBOARDING_STATUS_COMPLETED, - 'at' => '2026-01-01 00:00:00.000', - 'actorType' => ACTOR_TYPE_USER, - ], - ]]); - - $dbForPlatform = $this->createMock(Database::class); - $dbForPlatform->expects($this->never())->method('updateDocument'); - - Onboarding::complete($dbForPlatform, $project, ['functions.createCliDeployment', 'unknown.method'], ACTOR_TYPE_SYSTEM); - } - - public function testDoesNotOverwriteSkippedStage(): void - { - $project = new Document(['$id' => 'project1', 'onboarding' => [ - 'sites.createVcsDeployment' => [ - 'status' => ONBOARDING_STATUS_SKIPPED, - 'at' => '2026-01-01 00:00:00.000', - 'actorType' => ACTOR_TYPE_USER, - ], - ]]); - - $dbForPlatform = $this->createMock(Database::class); - $dbForPlatform->expects($this->never())->method('updateDocument'); - - Onboarding::complete($dbForPlatform, $project, ['sites.createVcsDeployment'], ACTOR_TYPE_SYSTEM); - } -} From 4fc1f737b6a527545761187cd8691bdf91893131 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 28 Jun 2026 05:37:20 +0000 Subject: [PATCH 14/18] fix(builds): re-read project before marking deployment onboarding The injected $project is a job-dispatch-time snapshot and a build can run for minutes. Read the current onboarding map from dbForPlatform before writing so a stage skipped or completed via the API during the build is not overwritten. --- .../Platform/Modules/Functions/Workers/Builds.php | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php index 1a64ce235e..7de85fbb91 100644 --- a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php +++ b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php @@ -1077,7 +1077,12 @@ class Builds extends Action } if ($stages !== []) { - $onboarding = $project->getAttribute('onboarding', []); + // Re-read the project: the injected $project is a snapshot from + // job-dispatch time, and a build can run for minutes. Reading the + // current onboarding map avoids overwriting a stage that was + // skipped (or completed) via the API while the build was running. + $onboardingProject = $dbForPlatform->getDocument('projects', $project->getId()); + $onboarding = $onboardingProject->getAttribute('onboarding', []); if (! \is_array($onboarding)) { $onboarding = []; } @@ -1096,7 +1101,7 @@ class Builds extends Action $onboardingChanged = true; } - if ($onboardingChanged) { + if ($onboardingChanged && ! $onboardingProject->isEmpty()) { try { $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ 'onboarding' => $onboarding, From 0fe49223b773556d82b2380bd33f10f19442f664 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 28 Jun 2026 05:48:26 +0000 Subject: [PATCH 15/18] refactor(builds): simplify onboarding write to fetch + set + update Use null-coalescing assignment so only stages not already recorded are set, which inherently leaves a skipped/completed stage untouched. Drops the explicit status guard, changed flag, and isEmpty check. --- .../Modules/Functions/Workers/Builds.php | 31 ++++++------------- 1 file changed, 10 insertions(+), 21 deletions(-) diff --git a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php index 7de85fbb91..0ddb14aef1 100644 --- a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php +++ b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php @@ -1077,38 +1077,27 @@ class Builds extends Action } if ($stages !== []) { - // Re-read the project: the injected $project is a snapshot from - // job-dispatch time, and a build can run for minutes. Reading the - // current onboarding map avoids overwriting a stage that was - // skipped (or completed) via the API while the build was running. - $onboardingProject = $dbForPlatform->getDocument('projects', $project->getId()); - $onboarding = $onboardingProject->getAttribute('onboarding', []); + // Fetch the project fresh and only set stages that aren't already + // recorded, so a stage skipped or completed via the API while the + // build was running is left untouched (??= respects it). + $onboarding = $dbForPlatform->getDocument('projects', $project->getId())->getAttribute('onboarding', []); if (! \is_array($onboarding)) { $onboarding = []; } - $onboardingChanged = false; foreach ($stages as $stage) { - $stageStatus = $onboarding[$stage]['status'] ?? null; - if ($stageStatus === ONBOARDING_STATUS_COMPLETED || $stageStatus === ONBOARDING_STATUS_SKIPPED) { - continue; - } - $onboarding[$stage] = [ + $onboarding[$stage] ??= [ 'status' => ONBOARDING_STATUS_COMPLETED, 'at' => DateTime::now(), 'actorType' => ACTOR_TYPE_SYSTEM, ]; - $onboardingChanged = true; } - if ($onboardingChanged && ! $onboardingProject->isEmpty()) { - try { - $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ - 'onboarding' => $onboarding, - ])); - } catch (\Throwable) { - // Missing `onboarding` attribute on upgraded installs must not break the build lifecycle. - } + try { + $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ + 'onboarding' => $onboarding, + ])); + } catch (\Throwable) { } } From aacab8fcf107e72c4491be14f66502f943984ced Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 28 Jun 2026 06:27:02 +0000 Subject: [PATCH 16/18] feat(projects): track template & duplicate deployment onboarding via the API hook Add functions/sites createTemplateDeployment and createDuplicateDeployment to the onboarding config so the existing api.php shutdown hook marks them in the API request context (which reaches the central console DB), instead of the regional build worker. Reverts the build-worker write and the Onboarding helper. --- app/config/onboarding.php | 20 +++--- app/init/constants.php | 1 - .../Modules/Functions/Workers/Builds.php | 62 ------------------- 3 files changed, 10 insertions(+), 73 deletions(-) diff --git a/app/config/onboarding.php b/app/config/onboarding.php index 5b73328e25..6ac29b25ee 100644 --- a/app/config/onboarding.php +++ b/app/config/onboarding.php @@ -40,11 +40,11 @@ return [ // Functions 'functions.create' => true, - // One key per deployment creation type (deployment `type` attribute); - // OR them in the UI for a single "created a deployment" milestone. - 'functions.createManualDeployment' => true, - 'functions.createCliDeployment' => true, - 'functions.createVcsDeployment' => true, + // One key per deployment-creation SDK method; OR them in the UI for a + // single "created a deployment" milestone. + 'functions.createDeployment' => true, + 'functions.createTemplateDeployment' => true, + 'functions.createDuplicateDeployment' => true, 'functions.updateFunctionDeployment' => true, // Messaging @@ -67,10 +67,10 @@ return [ // Sites 'sites.create' => true, - // One key per deployment creation type (deployment `type` attribute); - // OR them in the UI for a single "created a deployment" milestone. - 'sites.createManualDeployment' => true, - 'sites.createCliDeployment' => true, - 'sites.createVcsDeployment' => true, + // One key per deployment-creation SDK method; OR them in the UI for a + // single "created a deployment" milestone. + 'sites.createDeployment' => true, + 'sites.createTemplateDeployment' => true, + 'sites.createDuplicateDeployment' => true, 'sites.updateSiteDeployment' => true, ]; diff --git a/app/init/constants.php b/app/init/constants.php index 62819d601b..9efb6e3222 100644 --- a/app/init/constants.php +++ b/app/init/constants.php @@ -171,7 +171,6 @@ const ACTOR_TYPE_GUEST = 'guest'; const ACTOR_TYPE_KEY_PROJECT = 'keyProject'; const ACTOR_TYPE_KEY_ACCOUNT = 'keyAccount'; const ACTOR_TYPE_KEY_ORGANIZATION = 'keyOrganization'; -const ACTOR_TYPE_SYSTEM = 'system'; /** * Project onboarding stage status (stored per SDK method key under project.onboarding JSON). diff --git a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php index 0ddb14aef1..d0806ccadf 100644 --- a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php +++ b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php @@ -1039,68 +1039,6 @@ class Builds extends Action Span::add('build.activated', true); } - /** - * Mark deployment onboarding stages. Done here (not via the HTTP sdk - * label) so every creation path - manual upload, CLI, template, - * duplicate and VCS - and the worker-driven activation are covered. - * The create stage is keyed by the deployment `type` so each type - * has its own stage (OR them in the UI for a single milestone). - */ - $collection = $resource->getCollection(); - $createStage = match ($collection) { - 'functions' => match ($deployment->getAttribute('type')) { - 'manual' => 'functions.createManualDeployment', - 'cli' => 'functions.createCliDeployment', - 'vcs' => 'functions.createVcsDeployment', - default => null, - }, - 'sites' => match ($deployment->getAttribute('type')) { - 'manual' => 'sites.createManualDeployment', - 'cli' => 'sites.createCliDeployment', - 'vcs' => 'sites.createVcsDeployment', - default => null, - }, - default => null, - }; - $activateStage = match ($collection) { - 'functions' => 'functions.updateFunctionDeployment', - 'sites' => 'sites.updateSiteDeployment', - default => null, - }; - - $stages = []; - if ($createStage !== null) { - $stages[] = $createStage; - } - if ($activateBuild && $activateStage !== null) { - $stages[] = $activateStage; - } - - if ($stages !== []) { - // Fetch the project fresh and only set stages that aren't already - // recorded, so a stage skipped or completed via the API while the - // build was running is left untouched (??= respects it). - $onboarding = $dbForPlatform->getDocument('projects', $project->getId())->getAttribute('onboarding', []); - if (! \is_array($onboarding)) { - $onboarding = []; - } - - foreach ($stages as $stage) { - $onboarding[$stage] ??= [ - 'status' => ONBOARDING_STATUS_COMPLETED, - 'at' => DateTime::now(), - 'actorType' => ACTOR_TYPE_SYSTEM, - ]; - } - - try { - $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ - 'onboarding' => $onboarding, - ])); - } catch (\Throwable) { - } - } - $resource = $this->updateLatestDeployment($dbForProject, $resource); $this->afterDeploymentSuccess( From 808a5f53dfb5a8b834331c2c31565f9bc6351f02 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 28 Jun 2026 06:30:36 +0000 Subject: [PATCH 17/18] feat(projects): drop createDuplicateDeployment from onboarding Duplicating an existing deployment is a redeploy/rollback action that presupposes a prior deployment, so it is not an onboarding milestone. Keeps createDeployment + createTemplateDeployment for functions and sites. --- app/config/onboarding.php | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/app/config/onboarding.php b/app/config/onboarding.php index 6ac29b25ee..4f51d95e02 100644 --- a/app/config/onboarding.php +++ b/app/config/onboarding.php @@ -40,11 +40,10 @@ return [ // Functions 'functions.create' => true, - // One key per deployment-creation SDK method; OR them in the UI for a - // single "created a deployment" milestone. + // Deployment-creation SDK methods; OR them in the UI for a single + // "created a deployment" milestone. 'functions.createDeployment' => true, 'functions.createTemplateDeployment' => true, - 'functions.createDuplicateDeployment' => true, 'functions.updateFunctionDeployment' => true, // Messaging @@ -67,10 +66,9 @@ return [ // Sites 'sites.create' => true, - // One key per deployment-creation SDK method; OR them in the UI for a - // single "created a deployment" milestone. + // Deployment-creation SDK methods; OR them in the UI for a single + // "created a deployment" milestone. 'sites.createDeployment' => true, 'sites.createTemplateDeployment' => true, - 'sites.createDuplicateDeployment' => true, 'sites.updateSiteDeployment' => true, ]; From 971c74bddec6b32efa83252a6cf2dbeace74d41e Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 28 Jun 2026 06:32:53 +0000 Subject: [PATCH 18/18] feat(projects): track VCS deployment onboarding (repo-connected deploy) Add functions/sites createVcsDeployment - the explicit 'deploy from connected repo' endpoint - so connecting a repo to ship a first function/site marks an onboarding stage. Caught by the api hook (API context), like the other methods. --- app/config/onboarding.php | 2 ++ 1 file changed, 2 insertions(+) diff --git a/app/config/onboarding.php b/app/config/onboarding.php index 4f51d95e02..014301a72e 100644 --- a/app/config/onboarding.php +++ b/app/config/onboarding.php @@ -44,6 +44,7 @@ return [ // "created a deployment" milestone. 'functions.createDeployment' => true, 'functions.createTemplateDeployment' => true, + 'functions.createVcsDeployment' => true, 'functions.updateFunctionDeployment' => true, // Messaging @@ -70,5 +71,6 @@ return [ // "created a deployment" milestone. 'sites.createDeployment' => true, 'sites.createTemplateDeployment' => true, + 'sites.createVcsDeployment' => true, 'sites.updateSiteDeployment' => true, ];