feat: Require scopeId cascade FK relation to crdt_scopes for synced tables (#79)

Co-authored-by: Marcelo Soares <marcelo.me.soares@gmail.com>

docs/sync-non-sync-relations.md

@@ -24,7 +24,7 @@ The ownership link is:
 fields:
   id: UuidValue?, defaultPersist=random_v7
   ### Owner scope of this row. Maintained by the CRDT sync layer.
-  scopeId: int?, relation(optional, parent=crdt_scopes, onDelete=Cascade)
+  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)
 ```
 
 `scopeId == null` remains valid persisted state, but it means the row is
@@ -262,7 +262,7 @@ The error message should explain the allowed alternatives:
 
 The implementation issue should add schema/initialize tests for:
 
-- accepting `scopeId: int?, relation(optional, parent=crdt_scopes,
+- accepting `scopeId: int?, relation(parent=crdt_scopes,
   onDelete=Cascade)` on every synced table;
 - rejecting `sync -> non-sync` restricted reference-table FKs with
   `onDelete=Restrict` while the reference-data sync phase is absent;

packages/serverpod_offline_sync_client/lib/src/database/schema.dart

@@ -32,14 +32,8 @@ class CrdtSchemaRegistry {
         'CRDT can only synchronize tables with a nullable int scopeId column, '
         'but ${tablesWithoutScopeId.length} table(s) are missing it or declare '
         'it with the wrong type: '
-        '${tablesWithoutScopeId.map((t) => '"${t.tableName}"').join(', ')}\n\n'
+        '${tablesWithoutScopeId.map((t) => '"${t.tableName}"').join(', ')}'
-        'Add this field to every synced model:\n'
+        '$_scopeIdFieldHelp',
-        'fields:\n'
-        '  id: UuidValue?, defaultPersist=random_v7\n'
-        '  ### Owner scope of this row. Maintained by the CRDT sync layer.\n'
-        '  scopeId: int?\n\n'
-        'If the column is declared with scope=serverOnly, remove the scope; '
-        'the column must exist on every database.',
       );
     }
 
@@ -63,8 +57,34 @@ class CrdtSchemaRegistry {
         'whose target tables are also synchronized.',
       );
     }
+
+    final tablesMissingScopeIdRelation = _missingCrdtScopeRelations(
+      syncTables,
+      tableDefinitionsByName,
+    );
+    if (tablesMissingScopeIdRelation.isNotEmpty) {
+      throw StateError(
+        'CRDT synced tables must declare scopeId as a cascade relation to '
+        'crdt_scopes, but ${tablesMissingScopeIdRelation.length} table(s) are '
+        'missing this relation: '
+        '${tablesMissingScopeIdRelation.map((t) => '"$t"').join(', ')}'
+        '$_scopeIdFieldHelp',
+      );
+    }
   }
 
+  /// Help text appended to schema validation errors that describes the required
+  /// `scopeId` ownership field on every synced model.
+  static const _scopeIdFieldHelp =
+      '\n\n'
+      'Add this field to every synced model:\n'
+      'fields:\n'
+      '  id: UuidValue?, defaultPersist=random_v7\n'
+      '  ### Owner scope of this row. Maintained by the CRDT sync layer.\n'
+      '  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)\n\n'
+      'If the column is declared with scope=serverOnly, remove the scope; '
+      'the column must exist on every database.';
+
   final DatabaseSession _session;
 
   /// The list of tables to sync with CRDT.
@@ -210,3 +230,27 @@ bool _isForbiddenGlobalUniqueIndex(
     syncTableNames,
   );
 }
+
+List<String> _missingCrdtScopeRelations(
+  List<Table> syncTables,
+  Map<String, TableDefinition> tableDefinitionsByName,
+) {
+  return [
+    for (final table in syncTables)
+      if (tableDefinitionsByName.containsKey(table.tableName) &&
+          !_hasCrdtScopeRelation(tableDefinitionsByName[table.tableName]!))
+        table.tableName,
+  ];
+}
+
+bool _hasCrdtScopeRelation(TableDefinition tableDefinition) {
+  return tableDefinition.foreignKeys.any(
+    (fk) =>
+        fk.columns.length == 1 &&
+        fk.columns.single == 'scopeId' &&
+        fk.referenceTable == 'crdt_scopes' &&
+        fk.referenceColumns.length == 1 &&
+        fk.referenceColumns.single == 'id' &&
+        fk.onDelete == ForeignKeyAction.cascade,
+  );
+}

test/serverpod_offline_sync_test_server/lib/src/models/address.spy.yaml

@@ -4,7 +4,7 @@ database: all
 fields:
   id: UuidValue?, defaultPersist=random_v7
   ### Owner scope of this row. Maintained by the CRDT sync layer.
-  scopeId: int?
+  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)
   street: String
   inhabitantId: UuidValue?, unique
   inhabitant: Person?, relation(name=person_address, field=inhabitantId, onDelete=Restrict)

test/serverpod_offline_sync_test_server/lib/src/models/city.spy.yaml

@@ -4,7 +4,7 @@ database: all
 fields:
   id: UuidValue?, defaultPersist=random_v7
   ### Owner scope of this row. Maintained by the CRDT sync layer.
-  scopeId: int?
+  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)
   name: String
   citizens: List<Person>?, relation
   organizations: List<Organization>?, relation(name=city_org)

test/serverpod_offline_sync_test_server/lib/src/models/company.spy.yaml

@@ -4,7 +4,7 @@ database: all
 fields:
   id: UuidValue?, defaultPersist=random_v7
   ### Owner scope of this row. Maintained by the CRDT sync layer.
-  scopeId: int?
+  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)
   name: String
   town: Town?, relation(field=townId, onDelete=SetDefault)
   townId: UuidValue, default='550e8400-e29b-41d4-a716-446655440000'

test/serverpod_offline_sync_test_server/lib/src/models/fk_chain/cascade_middle.spy.yaml

@@ -4,7 +4,7 @@ database: all
 fields:
   id: UuidValue?, defaultPersist=random_v7
   ### Owner scope of this row. Maintained by the CRDT sync layer.
-  scopeId: int?
+  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)
   name: String
   root: FkChainRoot?, relation(field=rootId, onDelete=Cascade)
   rootId: UuidValue?

test/serverpod_offline_sync_test_server/lib/src/models/fk_chain/middle_cascade_child.spy.yaml

@@ -4,7 +4,7 @@ database: all
 fields:
   id: UuidValue?, defaultPersist=random_v7
   ### Owner scope of this row. Maintained by the CRDT sync layer.
-  scopeId: int?
+  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)
   name: String
   restrictBlocker: FkChainRestrictBlocker?, relation(field=restrictBlockerId, onDelete=Cascade)
   restrictBlockerId: UuidValue?

test/serverpod_offline_sync_test_server/lib/src/models/fk_chain/middle_set_null_child.spy.yaml

@@ -4,7 +4,7 @@ database: all
 fields:
   id: UuidValue?, defaultPersist=random_v7
   ### Owner scope of this row. Maintained by the CRDT sync layer.
-  scopeId: int?
+  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)
   name: String
   restrictBlocker: FkChainRestrictBlocker?, relation(field=restrictBlockerId, onDelete=SetNull)
   restrictBlockerId: UuidValue?

test/serverpod_offline_sync_test_server/lib/src/models/fk_chain/restrict_blocker.spy.yaml

@@ -4,7 +4,7 @@ database: all
 fields:
   id: UuidValue?, defaultPersist=random_v7
   ### Owner scope of this row. Maintained by the CRDT sync layer.
-  scopeId: int?
+  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)
   name: String
   cascadeMiddle: FkChainCascadeMiddle?, relation(field=cascadeMiddleId, onDelete=Restrict)
   cascadeMiddleId: UuidValue?

test/serverpod_offline_sync_test_server/lib/src/models/fk_chain/root.spy.yaml

@@ -4,5 +4,5 @@ database: all
 fields:
   id: UuidValue?, defaultPersist=random_v7
   ### Owner scope of this row. Maintained by the CRDT sync layer.
-  scopeId: int?
+  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)
   name: String

test/serverpod_offline_sync_test_server/lib/src/models/fk_chain/set_null_cascade_child.spy.yaml

@@ -4,7 +4,7 @@ database: all
 fields:
   id: UuidValue?, defaultPersist=random_v7
   ### Owner scope of this row. Maintained by the CRDT sync layer.
-  scopeId: int?
+  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)
   name: String
   setNullMiddle: FkChainSetNullMiddle?, relation(field=setNullMiddleId, onDelete=Cascade)
   setNullMiddleId: UuidValue?

test/serverpod_offline_sync_test_server/lib/src/models/fk_chain/set_null_middle.spy.yaml

@@ -4,7 +4,7 @@ database: all
 fields:
   id: UuidValue?, defaultPersist=random_v7
   ### Owner scope of this row. Maintained by the CRDT sync layer.
-  scopeId: int?
+  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)
   name: String
   cascadeMiddle: FkChainCascadeMiddle?, relation(field=cascadeMiddleId, onDelete=SetNull)
   cascadeMiddleId: UuidValue?

test/serverpod_offline_sync_test_server/lib/src/models/fk_chain/set_null_restrict_child.spy.yaml

@@ -4,7 +4,7 @@ database: all
 fields:
   id: UuidValue?, defaultPersist=random_v7
   ### Owner scope of this row. Maintained by the CRDT sync layer.
-  scopeId: int?
+  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)
   name: String
   setNullMiddle: FkChainSetNullMiddle?, relation(field=setNullMiddleId, onDelete=Restrict)
   setNullMiddleId: UuidValue?

test/serverpod_offline_sync_test_server/lib/src/models/fk_chain/set_null_set_null_child.spy.yaml

@@ -4,7 +4,7 @@ database: all
 fields:
   id: UuidValue?, defaultPersist=random_v7
   ### Owner scope of this row. Maintained by the CRDT sync layer.
-  scopeId: int?
+  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)
   name: String
   setNullMiddle: FkChainSetNullMiddle?, relation(field=setNullMiddleId, onDelete=SetNull)
   setNullMiddleId: UuidValue?

test/serverpod_offline_sync_test_server/lib/src/models/organization.spy.yaml

@@ -4,7 +4,7 @@ database: all
 fields:
   id: UuidValue?, defaultPersist=random_v7
   ### Owner scope of this row. Maintained by the CRDT sync layer.
-  scopeId: int?
+  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)
   name: String
   people: List<Person>?, relation(name=org_person)
   city: City?, relation(name=city_org, optional, onDelete=Cascade)

test/serverpod_offline_sync_test_server/lib/src/models/person.spy.yaml

@@ -4,7 +4,7 @@ database: all
 fields:
   id: UuidValue?, defaultPersist=random_v7
   ### Owner scope of this row. Maintained by the CRDT sync layer.
-  scopeId: int?
+  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)
   name: String
   surname: String?
   address: Address?, relation(name=person_address)

test/serverpod_offline_sync_test_server/lib/src/models/required_set_null_child.spy.yaml

@@ -4,7 +4,7 @@ database: all
 fields:
   id: UuidValue?, defaultPersist=random_v7
   ### Owner scope of this row. Maintained by the CRDT sync layer.
-  scopeId: int?
+  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)
   name: String
   parent: Person?, relation(field=parentId, onDelete=SetNull)
   parentId: UuidValue

test/serverpod_offline_sync_test_server/lib/src/models/restrict_child.spy.yaml

@@ -4,7 +4,7 @@ database: all
 fields:
   id: UuidValue?, defaultPersist=random_v7
   ### Owner scope of this row. Maintained by the CRDT sync layer.
-  scopeId: int?
+  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)
   name: String
   parent: Person?, relation(field=parentId, onDelete=Restrict)
   parentId: UuidValue?

test/serverpod_offline_sync_test_server/lib/src/models/town.spy.yaml

@@ -4,7 +4,7 @@ database: all
 fields:
   id: UuidValue?, defaultPersist=random_v7
   ### Owner scope of this row. Maintained by the CRDT sync layer.
-  scopeId: int?
+  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)
   name: String
   city: City?, relation(optional, onDelete=Cascade)
   mayor: Person?, relation(optional, onDelete=SetNull)

test/serverpod_offline_sync_test_server/lib/src/models/types.spy.yaml

@@ -5,7 +5,7 @@ database: all
 fields:
   id: UuidValue?, defaultPersist=random_v7
   ### Owner scope of this row. Maintained by the CRDT sync layer.
-  scopeId: int?
+  scopeId: int?, relation(parent=crdt_scopes, onDelete=Cascade)
   aBool: bool
   aDateTime: DateTime
   aText: String