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.

This commit is contained in:
eldadfux committed 2026-06-25 15:37:07 -04:00
1 parent c7f8605483
commit 4bb5dfb6ff
7 files changed
+203 -135

No files matched your search

+60 -24
View File
@@ -1,30 +1,66 @@
<?php
/**
* Project onboarding: each stage maps to an SDK method key (namespace + method name, same as Appwrite\SDK\Method).
* The sdk index is built once for O(1) lookup in the API shutdown hook.
* Project onboarding stages keyed by SDK method (namespace + method name, same as Appwrite\SDK\Method).
* Values are `true` for O(1) isset() lookup in the API shutdown hook. Each key is persisted under
* project.onboarding when the matching API call succeeds.
*/
$stages = [
[
'id' => '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,
];
+80 -52
View File
@@ -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<string, true> $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()
+1 -1
View File
@@ -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';
@@ -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<string, mixed>|null $row
* @return array<string, mixed>
*/
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;
}
}
@@ -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,
+2 -2
View File
@@ -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,
+27 -16
View File
@@ -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']);
}