mirror of
https://github.com/appwrite/appwrite.git
synced 2026-11-18 20:36:03 +00:00
Merge remote-tracking branch 'origin/main' into fix-migration-sentry-leak
# Conflicts: # src/Migration/Destinations/Appwrite.php
This commit is contained in:
commit
e325782f76
4 files changed
+1113
-59
No files matched your search
File diff suppressed because it is too large.
Load diff
@@ -2,20 +2,69 @@
|
||||
|
||||
namespace Utopia\Migration\Destinations;
|
||||
|
||||
/**
|
||||
* Behavior when a destination row with an existing ID is encountered.
|
||||
*/
|
||||
enum SchemaAction
|
||||
{
|
||||
case Create;
|
||||
case Skip;
|
||||
case Overwrite;
|
||||
}
|
||||
|
||||
enum OnDuplicate: string
|
||||
{
|
||||
case Fail = 'fail';
|
||||
case Skip = 'skip';
|
||||
case Upsert = 'upsert';
|
||||
case Overwrite = 'overwrite';
|
||||
|
||||
/**
|
||||
* @return array<string>
|
||||
* @return list<string>
|
||||
*/
|
||||
public static function values(): array
|
||||
{
|
||||
return \array_map(fn (self $case) => $case->value, self::cases());
|
||||
return \array_values(\array_map(fn (self $case) => $case->value, self::cases()));
|
||||
}
|
||||
|
||||
/**
|
||||
* Coarse routing for re-migration. The caller follows up with a spec-match
|
||||
* check that overrides Overwrite to Skip when source and dest
|
||||
* already have identical spec — see DestinationAppwrite for the full flow.
|
||||
*/
|
||||
public function resolveSchemaAction(
|
||||
bool $exists,
|
||||
?string $sourceUpdatedAt = null,
|
||||
?string $destUpdatedAt = null,
|
||||
): SchemaAction {
|
||||
if (!$exists) {
|
||||
return SchemaAction::Create;
|
||||
}
|
||||
return match ($this) {
|
||||
self::Fail => SchemaAction::Create,
|
||||
self::Skip => SchemaAction::Skip,
|
||||
self::Overwrite => $this->sourceIsNewer($sourceUpdatedAt, $destUpdatedAt)
|
||||
? SchemaAction::Overwrite
|
||||
: SchemaAction::Skip,
|
||||
};
|
||||
}
|
||||
|
||||
private function sourceIsNewer(?string $source, ?string $dest): bool
|
||||
{
|
||||
$src = $this->parseTimestamp($source);
|
||||
$dst = $this->parseTimestamp($dest);
|
||||
return $src !== null && $dst !== null && $src > $dst;
|
||||
}
|
||||
|
||||
/**
|
||||
* strtotime accepts '0000-00-00' leniently (returns a large negative epoch,
|
||||
* not false), so non-positive epochs are rejected too.
|
||||
*/
|
||||
private function parseTimestamp(?string $value): ?int
|
||||
{
|
||||
if ($value === null || $value === '') {
|
||||
return null;
|
||||
}
|
||||
$epoch = \strtotime($value);
|
||||
if ($epoch === false || $epoch <= 0) {
|
||||
return null;
|
||||
}
|
||||
return $epoch;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,96 @@
|
||||
<?php
|
||||
|
||||
namespace Migration\Unit\Destinations;
|
||||
|
||||
use Appwrite\Services\Databases;
|
||||
use Appwrite\Services\TablesDB;
|
||||
use PHPUnit\Framework\TestCase;
|
||||
use ReflectionClass;
|
||||
use ReflectionMethod;
|
||||
use Utopia\Migration\Destinations\Appwrite as AppwriteDestination;
|
||||
|
||||
/**
|
||||
* Lock-in for the SDK boundary that drives ATTRIBUTE_IMMUTABLE_FIELDS.
|
||||
*
|
||||
* Reflects on appwrite/appwrite's TablesDB + Databases services. If the SDK
|
||||
* ships a new updateXColumn / updateXAttribute endpoint that exposes a
|
||||
* previously-non-SDK field, this test fails so DestinationAppwrite's
|
||||
* ATTRIBUTE_IMMUTABLE_FIELDS constant can be synced. Catches drift in CI
|
||||
* rather than at runtime.
|
||||
*/
|
||||
class AppwriteAttributeSdkBoundaryTest extends TestCase
|
||||
{
|
||||
/** Routing/identity params that aren't mutable column state. */
|
||||
private const IGNORED_PARAMS = ['databaseId', 'tableId', 'collectionId', 'key', 'newKey'];
|
||||
|
||||
/**
|
||||
* SDK param name → meta-doc field name. Param names that don't appear on
|
||||
* the meta doc as a top-level key map to null (e.g. min/max/elements live
|
||||
* inside formatOptions; onDelete lives inside the relationship's options).
|
||||
*
|
||||
* @var array<string, string|null>
|
||||
*/
|
||||
private const PARAM_TO_META_FIELD = [
|
||||
'xdefault' => 'default',
|
||||
'min' => null,
|
||||
'max' => null,
|
||||
'elements' => null,
|
||||
'onDelete' => null,
|
||||
];
|
||||
|
||||
public function testSdkExposedFieldsAreNotInNonSdkConstant(): void
|
||||
{
|
||||
$sdkExposed = $this->collectSdkExposedMetaFields();
|
||||
$nonSdk = $this->readNonSdkConstant();
|
||||
|
||||
$overlap = \array_intersect($sdkExposed, $nonSdk);
|
||||
$this->assertSame(
|
||||
[],
|
||||
\array_values($overlap),
|
||||
'ATTRIBUTE_IMMUTABLE_FIELDS marks these fields as non-SDK, but the appwrite/appwrite '
|
||||
. 'SDK exposes them via updateXColumn/updateXAttribute: ' . \implode(', ', $overlap)
|
||||
. '. Either drop these from ATTRIBUTE_IMMUTABLE_FIELDS or update PARAM_TO_META_FIELD '
|
||||
. 'in this test if the SDK param doesn\'t correspond to a top-level meta-doc field.',
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* @return list<string> meta-doc field names the SDK can mutate
|
||||
*/
|
||||
private function collectSdkExposedMetaFields(): array
|
||||
{
|
||||
$fields = [];
|
||||
foreach ([TablesDB::class, Databases::class] as $service) {
|
||||
$service = new ReflectionClass($service);
|
||||
foreach ($service->getMethods(ReflectionMethod::IS_PUBLIC) as $method) {
|
||||
if (!\preg_match('/^update.+(Column|Attribute)$/', $method->getName())) {
|
||||
continue;
|
||||
}
|
||||
foreach ($method->getParameters() as $param) {
|
||||
$name = $param->getName();
|
||||
if (\in_array($name, self::IGNORED_PARAMS, true)) {
|
||||
continue;
|
||||
}
|
||||
$mapped = \array_key_exists($name, self::PARAM_TO_META_FIELD)
|
||||
? self::PARAM_TO_META_FIELD[$name]
|
||||
: $name;
|
||||
if ($mapped === null) {
|
||||
continue;
|
||||
}
|
||||
$fields[$mapped] = true;
|
||||
}
|
||||
}
|
||||
}
|
||||
return \array_keys($fields);
|
||||
}
|
||||
|
||||
/**
|
||||
* @return list<string>
|
||||
*/
|
||||
private function readNonSdkConstant(): array
|
||||
{
|
||||
/** @var list<string> $value */
|
||||
$value = (new ReflectionClass(AppwriteDestination::class))->getConstant('ATTRIBUTE_IMMUTABLE_FIELDS');
|
||||
return $value;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,155 @@
|
||||
<?php
|
||||
|
||||
namespace Migration\Unit\General;
|
||||
|
||||
use PHPUnit\Framework\Attributes\DataProvider;
|
||||
use PHPUnit\Framework\TestCase;
|
||||
use Utopia\Migration\Destinations\OnDuplicate;
|
||||
use Utopia\Migration\Destinations\SchemaAction;
|
||||
|
||||
/**
|
||||
* OnDuplicate::resolveSchemaAction is the load-bearing decision point for
|
||||
* re-migration tolerance. The destination then runs a spec-match guard that
|
||||
* overrides Overwrite to Skip when source and dest already have
|
||||
* identical spec — see DestinationAppwrite. These tests lock the
|
||||
* mode × existence × updatedAt matrix.
|
||||
*/
|
||||
class OnDuplicateTest extends TestCase
|
||||
{
|
||||
public function testNotExistsAlwaysCreates(): void
|
||||
{
|
||||
foreach (OnDuplicate::cases() as $mode) {
|
||||
$this->assertSame(
|
||||
SchemaAction::Create,
|
||||
$mode->resolveSchemaAction(exists: false),
|
||||
"{$mode->value} on non-existing resource must return Create",
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
public function testFailExistsReturnsCreateSoCallerDDLThrows(): void
|
||||
{
|
||||
// Fail is routed through Create (not Skip) so the caller's normal
|
||||
// create flow runs and the library surfaces DuplicateException as
|
||||
// designed. Returning Skip here would silently hide the error.
|
||||
$this->assertSame(
|
||||
SchemaAction::Create,
|
||||
OnDuplicate::Fail->resolveSchemaAction(exists: true),
|
||||
);
|
||||
}
|
||||
|
||||
public function testSkipAlwaysSkipsExisting(): void
|
||||
{
|
||||
// Skip must ignore updatedAt entirely — it's the "don't touch" contract.
|
||||
$this->assertSame(
|
||||
SchemaAction::Skip,
|
||||
OnDuplicate::Skip->resolveSchemaAction(
|
||||
exists: true,
|
||||
sourceUpdatedAt: '2026-01-01T00:00:00.000+00:00',
|
||||
destUpdatedAt: '2020-01-01T00:00:00.000+00:00',
|
||||
),
|
||||
);
|
||||
$this->assertSame(
|
||||
SchemaAction::Skip,
|
||||
OnDuplicate::Skip->resolveSchemaAction(
|
||||
exists: true,
|
||||
sourceUpdatedAt: '2020-01-01T00:00:00.000+00:00',
|
||||
destUpdatedAt: '2026-01-01T00:00:00.000+00:00',
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
public function testOverwriteSourceNewerUpdatesInPlace(): void
|
||||
{
|
||||
// Source updatedAt strictly newer than dest → Overwrite. The
|
||||
// caller (DestinationAppwrite) follows up with attribute/index spec
|
||||
// checks and falls through to drop+recreate when the SDK can't
|
||||
// express the change.
|
||||
$this->assertSame(
|
||||
SchemaAction::Overwrite,
|
||||
OnDuplicate::Overwrite->resolveSchemaAction(
|
||||
exists: true,
|
||||
sourceUpdatedAt: '2026-04-23T10:00:00.000+00:00',
|
||||
destUpdatedAt: '2026-04-23T09:59:59.000+00:00',
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
public function testOverwriteSourceEqualSkips(): void
|
||||
{
|
||||
$when = '2026-04-23T10:00:00.000+00:00';
|
||||
$this->assertSame(
|
||||
SchemaAction::Skip,
|
||||
OnDuplicate::Overwrite->resolveSchemaAction(
|
||||
exists: true,
|
||||
sourceUpdatedAt: $when,
|
||||
destUpdatedAt: $when,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
public function testOverwriteSourceOlderSkips(): void
|
||||
{
|
||||
// Dest is ahead — don't roll back. Avoids overwriting newer
|
||||
// destination edits with stale source data.
|
||||
$this->assertSame(
|
||||
SchemaAction::Skip,
|
||||
OnDuplicate::Overwrite->resolveSchemaAction(
|
||||
exists: true,
|
||||
sourceUpdatedAt: '2026-04-23T09:00:00.000+00:00',
|
||||
destUpdatedAt: '2026-04-23T10:00:00.000+00:00',
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
public function testOverwriteNoTimestampsSkips(): void
|
||||
{
|
||||
// No timestamps provided at all → no information to act on. Conservative:
|
||||
// Skip rather than risk a destructive update on uncertain input.
|
||||
$this->assertSame(
|
||||
SchemaAction::Skip,
|
||||
OnDuplicate::Overwrite->resolveSchemaAction(exists: true),
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* @return array<string, array{0: ?string, 1: ?string}>
|
||||
*/
|
||||
public static function unparseableTimestampPairs(): array
|
||||
{
|
||||
return [
|
||||
'both empty' => ['', ''],
|
||||
'both null' => [null, null],
|
||||
'source empty' => ['', '2026-04-23T10:00:00.000+00:00'],
|
||||
'dest empty' => ['2026-04-23T10:00:00.000+00:00', ''],
|
||||
'source null' => [null, '2026-04-23T10:00:00.000+00:00'],
|
||||
'dest null' => ['2026-04-23T10:00:00.000+00:00', null],
|
||||
'source zero-date' => ['0000-00-00 00:00:00', '2026-04-23T10:00:00.000+00:00'],
|
||||
'dest zero-date' => ['2026-04-23T10:00:00.000+00:00', '0000-00-00 00:00:00'],
|
||||
'source garbage' => ['not-a-date', '2026-04-23T10:00:00.000+00:00'],
|
||||
'dest garbage' => ['2026-04-23T10:00:00.000+00:00', 'not-a-date'],
|
||||
];
|
||||
}
|
||||
|
||||
#[DataProvider('unparseableTimestampPairs')]
|
||||
public function testOverwriteUnparseableUpdatedAtSkips(?string $source, ?string $dest): void
|
||||
{
|
||||
// Conservative: unparseable updatedAt preserves existing destination
|
||||
// rather than risk a destructive update on garbage input.
|
||||
$this->assertSame(
|
||||
SchemaAction::Skip,
|
||||
OnDuplicate::Overwrite->resolveSchemaAction(
|
||||
exists: true,
|
||||
sourceUpdatedAt: $source,
|
||||
destUpdatedAt: $dest,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
public function testValuesListsAllCasesInDeclarationOrder(): void
|
||||
{
|
||||
// The values() helper is consumed by API/SDK param validators; this
|
||||
// protects against an accidental case-rename or reorder.
|
||||
$this->assertSame(['fail', 'skip', 'overwrite'], OnDuplicate::values());
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user