Add support for compensating writes

CHANGELOG.md

@@ -4,6 +4,8 @@
 * None
 
 ### Enhancements
+* Added new error class `CompensatingWriteError`, that that indicates that one or more object changes have been reverted by the server. 
+This can happen when the client creates/updates objects that do not match any subscription, or performs writes on an object it didn't have permission to ([#5599](https://github.com/realm/realm-js/pull/5599)).
 * Added configuration option `SyncConfiguration.cancelWaitsOnNonFatalError`. Set to true, all async operations (such as opening the Realm with `Realm.open`) will fail when a non-fatal error, such as a timeout, occurs.  
 * Added an overload to `Object.linkingObjects` method that takes type of the linking object as an input instead of its string name ([#5326](https://github.com/realm/realm-js/issues/5326))  
 Example usage:

integration-tests/tests/src/tests/sync/flexible.ts

@@ -33,14 +33,17 @@ import {
   BSON,
   ClientResetMode,
   ConfigurationWithSync,
+  ErrorCallback,
   FlexibleSyncConfiguration,
   Realm,
   SessionStopPolicy,
+  CompensatingWriteError,
+  CompensatingWriteErrorInfo,
   SyncConfiguration,
 } from "realm";
 
 import { authenticateUserBefore, importAppBefore, openRealmBeforeEach } from "../../hooks";
-import { DogSchema, IPerson, PersonSchema } from "../../schemas/person-and-dog-with-object-ids";
+import { DogSchema, IPerson, PersonSchema, IDog } from "../../schemas/person-and-dog-with-object-ids";
 import { closeRealm } from "../../utils/close-realm";
 import { expectClientResetError } from "../../utils/expect-sync-error";
 import { createSyncConfig } from "../../utils/open-realm";
@@ -396,6 +399,88 @@ describe.skipIf(environment.missingServer, "Flexible sync", function () {
     });
   });
 
+  describe("Errors", () => {
+    it("raises compensating writes errors", async function () {
+      const person1Id = new BSON.ObjectId("0000002a9a7969d24bea4cf5");
+      const person2Id = new BSON.ObjectId("0000002a9a7969d24bea4cf6");
+      const dogId = new BSON.ObjectId("0000002a9a7969d24bea4cf7");
+
+      const promise = new Promise<void>((resolve, _) => {
+        (async () => {
+          const errorCallback: ErrorCallback = (_, error) => {
+            expect(error.code).to.equal(231);
+            expect(error.isFatal).to.be.false;
+            expect(error.message).to.contain(
+              "Client attempted a write that is outside of permissions or query filters; it has been reverted",
+            );
+
+            if (!(error instanceof CompensatingWriteError)) {
+              throw new Error("Expected a CompensatingWriteError");
+            }
+
+            expect(error.compensatingWrites.length).to.equal(3);
+
+            const compensatingWrites = error.compensatingWrites.sort((a, b) =>
+              (a.primaryKey as BSON.ObjectId).toString().localeCompare((b.primaryKey as BSON.ObjectId).toString()),
+            );
+
+            expect((compensatingWrites[0].primaryKey as BSON.ObjectId).equals(person1Id)).to.be.true;
+            expect((compensatingWrites[1].primaryKey as BSON.ObjectId).equals(person2Id)).to.be.true;
+            expect((compensatingWrites[2].primaryKey as BSON.ObjectId).equals(dogId)).to.be.true;
+
+            expect(compensatingWrites[0].objectName).to.equal(FlexiblePersonSchema.name);
+            expect(compensatingWrites[1].objectName).to.equal(FlexiblePersonSchema.name);
+            expect(compensatingWrites[2].objectName).to.equal(DogSchema.name);
+
+            expect(compensatingWrites[0].reason).to.contain("object is outside of the current query view");
+            expect(compensatingWrites[1].reason).to.contain("object is outside of the current query view");
+            expect(compensatingWrites[2].reason).to.contain("object is outside of the current query view");
+
+            resolve();
+          };
+
+          const realm = await Realm.open({
+            schema: [FlexiblePersonSchema, DogSchema],
+            sync: {
+              flexible: true,
+              user: this.user,
+              onError: errorCallback,
+            },
+          });
+
+          await realm.subscriptions.update((mutableSubs) => {
+            mutableSubs.add(realm.objects(FlexiblePersonSchema.name).filtered("age < 30"));
+            mutableSubs.add(realm.objects(DogSchema.name).filtered("age > 5"));
+          });
+
+          realm.write(() => {
+            //Outside subscriptions
+            const tom = realm.create<IPerson>(FlexiblePersonSchema.name, {
+              _id: person1Id,
+              name: "Tom",
+              age: 36,
+            });
+            realm.create<IPerson>(FlexiblePersonSchema.name, { _id: person2Id, name: "Maria", age: 44 });
+            realm.create<IDog>(DogSchema.name, { _id: dogId, name: "Puppy", age: 1, owner: tom });
+
+            //Inside subscriptions
+            const luigi = realm.create<IPerson>(FlexiblePersonSchema.name, {
+              _id: new BSON.ObjectId(),
+              name: "Luigi",
+              age: 20,
+            });
+            realm.create<IPerson>(FlexiblePersonSchema.name, { _id: new BSON.ObjectId(), name: "Mario", age: 22 });
+            realm.create<IDog>(DogSchema.name, { _id: new BSON.ObjectId(), name: "Oldy", age: 6, owner: luigi });
+          });
+
+          await realm?.syncSession?.uploadAllLocalChanges();
+        })();
+      });
+
+      await promise;
+    });
+  });
+
   describe("With realm opened before", function () {
     openRealmBeforeEach({
       schema: [FlexiblePersonSchema, DogSchema],

packages/bindgen/spec.yml

@@ -546,8 +546,7 @@ records:
      # server_requests_action:
      #   type: sync::ProtocolErrorInfo::Action
      #   default: sync::ProtocolErrorInfo::Action::NoAction
-     # compensating_writes_info: std::vector<sync::CompensatingWriteErrorInfo>
-
+     compensating_writes_info: std::vector<CompensatingWriteErrorInfo>
 
   Request:
     cppName: app::Request
@@ -591,6 +590,13 @@ records:
       default_request_timeout_ms: util::Optional<uint64_t>
       device_info: DeviceInfo
 
+  CompensatingWriteErrorInfo:
+   cppName: sync::CompensatingWriteErrorInfo
+   fields:
+     object_name: std::string
+     reason: std::string
+     primary_key: Mixed
+
 opaqueTypes:
   - Schema
   - Group

packages/realm/src/Types.ts

@@ -18,6 +18,8 @@
 
 import { BSON, Dictionary, List, RealmSet, Results } from "./internal";
 
+export type Mixed = unknown;
+
 const RealmDictionary = Dictionary;
 type RealmDictionary<T> = Dictionary<T>;
 

packages/realm/src/errors.ts

@@ -20,6 +20,7 @@ import {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars -- Used by TS docs
   ClientResetMode,
   Configuration,
+  Mixed,
   binding,
 } from "./internal";
 
@@ -92,7 +93,9 @@ export class TimeoutError extends Error {
 
 /** @internal */
 export function fromBindingSyncError(error: binding.SyncError) {
-  if (error.isClientResetRequested) {
+  if (error.systemError.code == 231) {
+    return new CompensatingWriteError(error);
+  } else if (error.isClientResetRequested) {
     return new ClientResetError(error);
   } else {
     return new SyncError(error);
@@ -117,7 +120,6 @@ export class SyncError extends Error {
   }
 }
 
-const ORIGINAL_FILE_PATH_KEY = "ORIGINAL_FILE_PATH";
 const RECOVERY_FILE_PATH_KEY = "RECOVERY_FILE_PATH";
 
 /**
@@ -138,3 +140,45 @@ export class ClientResetError extends SyncError {
     };
   }
 }
+
+/**
+ * An error class that indicates that one or more object changes have been reverted by the server.
+ * This can happen when the client creates/updates objects that do not match any subscription, or performs writes on
+ * an object it didn't have permission to.
+ */
+export class CompensatingWriteError extends SyncError {
+  /**
+   * The array of compensating writes performed by the server.
+   */
+  public infos: CompensatingWriteInfo[] = [];
+
+  /** @internal */
+  constructor(error: binding.SyncError) {
+    super(error);
+    if (error.compensatingWritesInfo) {
+      error.compensatingWritesInfo.forEach((element) => {
+        this.infos.push({ objectName: element.objectName, reason: element.reason, primaryKey: element.primaryKey });
+      });
+    }
+  }
+}
+
+/**
+ * The details of a compensating write performed by the server.
+ */
+export type CompensatingWriteInfo = {
+  /**
+   * The type of the object affected by the compensating write.
+   */
+  objectName: string;
+
+  /**
+   * The reason for the compensating write.
+   */
+  reason: string;
+
+  /**
+   * The primary key of the object affected by the compensating write.
+   */
+  primaryKey: Mixed;
+};

packages/realm/src/index.ts

@@ -51,6 +51,8 @@ export {
   CollectionChangeCallback,
   CollectionChangeSet,
   CollectionPropertyTypeName,
+  CompensatingWriteError,
+  CompensatingWriteInfo,
   Configuration,
   ConfigurationWithoutSync,
   ConfigurationWithSync,