Migrate MongoDB GUIDs from subtype 3 to 4 (#4179)

Author: Copilot

.gitignore

@@ -35,6 +35,7 @@ scripts/*.js
 !scripts/frontendScripts.js
 !scripts/jestTest.js
 !scripts/setupMongo.js
+database/*.js
 *.log
 *-debug.log*
 *-error.log*

Backend/Models/Sense.cs

@@ -16,7 +16,7 @@ public class Sense
         /// </summary>
         [Required]
         [BsonElement("guid")]
-        [BsonGuidRepresentation(GuidRepresentation.CSharpLegacy)]
+        [BsonGuidRepresentation(GuidRepresentation.Standard)]
 #pragma warning disable CA1720
         public Guid Guid { get; set; }
 #pragma warning restore CA1720

Backend/Models/UserEdit.cs

@@ -35,7 +35,7 @@ public UserEdit Clone()
     public class UserEditStepWrapper
     {
         [Required]
-        [BsonGuidRepresentation(GuidRepresentation.CSharpLegacy)]
+        [BsonGuidRepresentation(GuidRepresentation.Standard)]
         public Guid EditGuid { get; set; }
 
         [Required]
@@ -57,7 +57,7 @@ public class Edit
     {
         [Required]
         [BsonElement("guid")]
-        [BsonGuidRepresentation(GuidRepresentation.CSharpLegacy)]
+        [BsonGuidRepresentation(GuidRepresentation.Standard)]
 #pragma warning disable CA1720
         public Guid Guid { get; set; } = Guid.NewGuid();
 #pragma warning restore CA1720

Backend/Models/Word.cs

@@ -20,7 +20,7 @@ public class Word
         /// </summary>
         [Required]
         [BsonElement("guid")]
-        [BsonGuidRepresentation(GuidRepresentation.CSharpLegacy)]
+        [BsonGuidRepresentation(GuidRepresentation.Standard)]
 #pragma warning disable CA1720
         public Guid Guid { get; set; }
 #pragma warning restore CA1720

database/migrate-guids-to-subtype4.ts

@@ -0,0 +1,214 @@
+// Migration script: convert MongoDB GUID fields from BinData subtype 3 (CSharpLegacy)
+// to BinData subtype 4 (Standard/RFC 4122).
+//
+// Usage:
+//   npx tsc database/migrate-guids-to-subtype4.ts
+//   mongosh CombineDatabase database/migrate-guids-to-subtype4.js
+//
+// Type-check only (no output):
+//   npx tsc --project database/tsconfig.json --noEmit
+//
+// Background:
+//   The C# MongoDB driver previously encoded System.Guid values using BinData subtype 3
+//   with a CSharpLegacy byte order (little-endian for the first three components).
+//   BinData subtype 4 uses a stable RFC 4122 byte order across all drivers, making
+//   it easier to search by GUID in mongosh and other tools.
+//
+//   CSharpLegacy byte order for UUID aabbccdd-eeff-gghh-iijj-kkllmmnnoopp:
+//     stored as [dd,cc,bb,aa, ff,ee, hh,gg, ii,jj,kk,ll,mm,nn,oo,pp]
+//   Standard (subtype 4) byte order for the same UUID:
+//     stored as [aa,bb,cc,dd, ee,ff, gg,hh, ii,jj,kk,ll,mm,nn,oo,pp]
+
+// Type declarations for mongosh globals.
+// All `declare` statements are erased by tsc and produce no JS output.
+//
+// The inline BsonBinary interface matches the bson@^7 Binary API:
+//   sub_type is a number property; toString("hex") returns the hex string.
+interface BsonBinary {
+  sub_type: number;
+  toString(encoding: "hex" | "base64" | "utf8" | "utf-8"): string;
+}
+declare function UUID(hexstr?: string): BsonBinary;
+declare function print(msg: string): void;
+declare const db: MongoDB;
+
+type MongoDoc = Record<string, unknown>;
+
+interface MongoCursor {
+  forEach(callback: (doc: MongoDoc) => void): void;
+}
+
+interface MongoCollection {
+  find(query: MongoDoc): MongoCursor;
+  updateOne(filter: MongoDoc, update: MongoDoc): void;
+}
+
+interface MongoDB {
+  getCollection(name: string): MongoCollection;
+  getCollectionNames(): string[];
+}
+
+/**
+ * Convert a BinData subtype 3 (CSharpLegacy) GUID to BinData subtype 4 (Standard).
+ * Returns null if the input is not a subtype-3 binary value.
+ */
+function csharpGuidToStandard(bin: unknown): ReturnType<typeof UUID> | null {
+  if (bin === null || typeof bin !== "object") {
+    return null;
+  }
+  const binary = bin as Partial<BsonBinary>;
+  if (binary.sub_type !== 3 || typeof binary.toString !== "function") {
+    return null;
+  }
+  // Split the 32-character hex string into 16 byte pairs.
+  const hexBytes = binary.toString("hex").match(/../g);
+  if (hexBytes === null || hexBytes.length !== 16) {
+    return null;
+  }
+
+  // Rearrange the first 8 bytes (4+2+2) from little-endian to big-endian;
+  // the remaining 8 bytes are already in big-endian order.
+  const rev1 = hexBytes[3] + hexBytes[2] + hexBytes[1] + hexBytes[0];
+  const rev2 = hexBytes[5] + hexBytes[4];
+  const rev3 = hexBytes[7] + hexBytes[6];
+  const keep1 = hexBytes[8] + hexBytes[9];
+  const keep2 = hexBytes.slice(10).join("");
+  const uuidStr = rev1 + "-" + rev2 + "-" + rev3 + "-" + keep1 + "-" + keep2;
+  return UUID(uuidStr);
+}
+
+let totalGuidsConverted = 0;
+let totalDocumentsUpdated = 0;
+
+// ── WordsCollection and FrontierCollection ──────────────────────────────────
+//
+// Each Word document has:
+//   - guid           (BinData, top-level)
+//   - senses[].guid  (BinData, per-element in the senses array)
+
+for (const collName of ["WordsCollection", "FrontierCollection"]) {
+  const coll = db.getCollection(collName);
+
+  // Find all words that have binData guid fields (the conversion function handles subtype checking).
+  coll.find({ guid: { $type: "binData" } }).forEach((doc) => {
+    const update: Record<string, ReturnType<typeof UUID>> = {};
+
+    // Convert top-level guid.
+    const newGuid = csharpGuidToStandard(doc["guid"]);
+    if (newGuid !== null) {
+      update["guid"] = newGuid;
+      totalGuidsConverted++;
+    }
+
+    // Convert each sense's guid.
+    if (Array.isArray(doc["senses"])) {
+      doc["senses"].forEach((sense, i) => {
+        if (sense === null || typeof sense !== "object") {
+          return;
+        }
+        const newSenseGuid = csharpGuidToStandard(sense["guid"]);
+        if (newSenseGuid !== null) {
+          update[`senses.${i}.guid`] = newSenseGuid;
+          totalGuidsConverted++;
+        }
+      });
+    }
+
+    if (Object.keys(update).length > 0) {
+      try {
+        coll.updateOne({ _id: doc["_id"] }, { $set: update });
+        totalDocumentsUpdated++;
+      } catch (e) {
+        print(`Error updating document ${doc["_id"]}: ${e}`);
+      }
+    }
+  });
+
+  print(`${collName}: done`);
+}
+
+// ── UserEditsCollection ──────────────────────────────────────────────────────
+//
+// Each UserEdit document has:
+//   - edits[].guid  (BinData, per-element in the edits array)
+
+const userEditsColl = db.getCollection("UserEditsCollection");
+
+// Find all UserEdits that have binData guid fields (the conversion function handles subtype checking).
+userEditsColl.find({ "edits.guid": { $type: "binData" } }).forEach((doc) => {
+  const update: Record<string, ReturnType<typeof UUID>> = {};
+
+  if (Array.isArray(doc["edits"])) {
+    doc["edits"].forEach((edit, i) => {
+      if (edit === null || typeof edit !== "object") {
+        return;
+      }
+      const newEditGuid = csharpGuidToStandard(edit["guid"]);
+      if (newEditGuid !== null) {
+        update[`edits.${i}.guid`] = newEditGuid;
+        totalGuidsConverted++;
+      }
+    });
+  }
+
+  if (Object.keys(update).length > 0) {
+    try {
+      userEditsColl.updateOne({ _id: doc["_id"] }, { $set: update });
+      totalDocumentsUpdated++;
+    } catch (e) {
+      print(`Error updating document ${doc["_id"]}: ${e}`);
+    }
+  }
+});
+
+print("UserEditsCollection: done");
+
+print(
+  `Migration complete. ${totalGuidsConverted} GUID(s) converted in ${totalDocumentsUpdated} document(s).`
+);
+
+// ── Final verification scan ─────────────────────────────────────────────────
+//
+// Recursively scan every collection/document/field and count objects with a
+// sub_type property that is not 4.
+
+function countObjectsWithSubtypeNot4(root: unknown): number {
+  if (root === null || root === undefined || typeof root !== "object") {
+    return 0;
+  }
+
+  if (Array.isArray(root)) {
+    return root.reduce<number>(
+      (sum, item) => sum + countObjectsWithSubtypeNot4(item),
+      0
+    );
+  }
+
+  if ("sub_type" in root && root.sub_type !== 4) {
+    return 1;
+  }
+
+  return Object.values(root as Record<string, unknown>).reduce<number>(
+    (sum, child) => sum + countObjectsWithSubtypeNot4(child),
+    0
+  );
+}
+
+let totalNonSubtype4Objects = 0;
+
+for (const collName of db.getCollectionNames()) {
+  print(
+    `Scanning collection ${collName} for objects found with sub_type !== 4...`
+  );
+  db.getCollection(collName)
+    .find({})
+    .forEach((doc) => {
+      const subcount = countObjectsWithSubtypeNot4(doc);
+      if (subcount > 0) {
+        print(`* doc ${doc["_id"]}: ${subcount} objects with sub_type !== 4`);
+      }
+      totalNonSubtype4Objects += subcount;
+    });
+}
+
+print(`Final scan: ${totalNonSubtype4Objects} objects found.`);

database/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "lib": ["esnext"],
+    "isolatedModules": false,
+    "noEmit": true
+  },
+  "include": ["."]
+}

package-lock.json

@@ -109,6 +109,7 @@
     "@types/validator": "~13.15.10",
     "babel-jest": "~30.2.0",
     "babel-plugin-transform-import-meta": "~2.3.3",
+    "bson": "^7.2.0",
     "buffer": "~6.0.3",
     "css-mediaquery": "~0.1.2",
     "dotenv": "~16.6.1",