Gestionar errores de sincronización - SDK de Node.js

Controlador de errores de sincronización

Debe configurar un controlador de errores para las aplicaciones que usan Atlas Device Sync. Un controlador de errores genérico detectará y responderá a las llamadas a la API relacionadas con la sincronización fallida en su backend de Atlas.

const handleSyncError = async (session, error) => {
  // ... handle the error using session and error information.
  console.log(session);
  console.log(error);
};
const config = {
  schema: [DogSchema],
  sync: {
    flexible: true,
    user: app.currentUser,
    onError: handleSyncError,
  },
};
// Open realm with config that contains error handler.
const realm = await Realm.open(config);

const handleSyncError = (
  session: Realm.App.Sync.Session,
  error: Realm.SyncError | Realm.ClientResetError
) => {
  // ... handle the error using session and error information.
  console.log(session);
  console.log(error);
};
const config: Realm.Configuration = {
  schema: [DogSchema],
  sync: {
    flexible: true,
    user: app.currentUser!,
    onError: handleSyncError,
  },
};
// Open realm with config that contains error handler.
const realm = await Realm.open(config);

const errorCallback = (session, error) => {
  // Check if error type matches CompensatingWriteError.
  if (error instanceof CompensatingWriteError) {
    // Handle the compensating write error as needed.
    console.debug({
      name: error.name,
      code: error.code,
      message: error.message,
      atlasLogUrl: error.logUrl,
    });
    const compensatingWrites = error.writes.sort((a, b) =>
      a.primaryKey.toString().localeCompare(b.primaryKey.toString())
    );
    console.debug(compensatingWrites);
  }
};
const app = new Realm.App({
  id: APP_ID,
});
const credentials = Credentials.anonymous();
await app.logIn(credentials);
const realm = await Realm.open({
  schema: [Person, Turtle],
  sync: {
    flexible: true,
    user: app.currentUser,
    onError: errorCallback,
  },
});

const errorCallback: ErrorCallback = (session, error) => {
  // Check if error type matches CompensatingWriteError.
  if (error instanceof CompensatingWriteError) {
    // Handle the compensating write error as needed.
    console.debug({
      name: error.name,
      code: error.code,
      message: error.message,
      atlasLogUrl: error.logUrl,
    });
    const compensatingWrites = error.writes.sort((a, b) =>
      (a.primaryKey as BSON.ObjectId)
        .toString()
        .localeCompare((b.primaryKey as BSON.ObjectId).toString())
    );
    console.debug(compensatingWrites);
  }
};
const app = new Realm.App({
  id: APP_ID,
});
const credentials = Credentials.anonymous();
await app.logIn(credentials);
const realm = await Realm.open({
  schema: [Person, Turtle],
  sync: {
    flexible: true,
    user: app.currentUser!,
    onError: errorCallback,
  },
});

Manejar errores de restablecimiento del cliente

Un error de restablecimiento de cliente es un escenario en el que un dominio de cliente no puede sincronizar datos con el backend de Atlas App Services. Los clientes en este estado pueden seguir ejecutándose y guardando datos localmente, pero no pueden enviar ni recibir conjuntos de cambios de sincronización hasta que realicen un restablecimiento de cliente.

Para obtener más información sobre las causas y los modos de manejo de los restablecimientos de clientes, consulte Restablecimientos de clientes de sincronización de dispositivos en la documentación de Servicios de aplicaciones.

Modos de reinicio del cliente

Puede especificar qué modo de restablecimiento de cliente debe usar su aplicación para restaurar el reino a un estado sincronizable:

• Modo de recuperación de cambios no sincronizados: Al seleccionar este modo, el cliente intenta recuperar los cambios no sincronizados. Elija este modo si no desea descartar los cambios no sincronizados.

• Modo de recuperación o descarte de cambios no sincronizados: El cliente primero intenta recuperar los cambios que aún no se han sincronizado. Si no puede recuperar los datos no sincronizados, no descarta los cambios no sincronizados, pero continúa reiniciando el cliente automáticamente. Seleccione este modo si desea habilitar la recuperación automática del cliente para descartar los cambios no sincronizados.

• Modo descartar cambios no sincronizados: restaura el reino a un estado sincronizable descartando los cambios realizados desde la última sincronización.

• Modo de recuperación manual: Descarga una nueva copia del dominio y mueve el dominio no sincronizable a una copia de seguridad. Migra los datos no sincronizados de la copia de seguridad del dominio a la nueva copia sincronizable.

Reinicio automático vs. manual del cliente

Los SDK de Realm proporcionan modos de restablecimiento de cliente que manejan automáticamente la mayoría de los errores de restablecimiento de cliente.

Los modos de restablecimiento automático del cliente restauran el archivo de dominio local a un estado sincronizable sin cerrar el dominio ni perder notificaciones. Los siguientes modos de restablecimiento del cliente admiten restablecimientos automáticos:

• Recuperar el modo de cambios no sincronizados

• Recuperar o descartar el modo de cambios no sincronizados

• Descartar el modo de cambios no sincronizados

Las diferencias entre estos modos se basan en cómo gestionan los cambios en el dispositivo que aún no se han sincronizado con el backend. Solo el modo de recuperación manual no realiza un restablecimiento automático del cliente.

Seleccione el modo de recuperación de cambios no sincronizados para gestionar automáticamente la mayoría de los casos de restablecimiento del cliente. Este modo intenta recuperar los cambios no sincronizados al restablecer el cliente.

Si su aplicación requiere una lógica de reinicio de cliente específica que no se puede manejar automáticamente, es posible que desee o necesite agregar un controlador de reinicio de cliente manual al modo de reinicio de cliente automático.

Restablecimiento del cliente con recuperación

La Recuperación de Cliente es una función que se habilita de forma predeterminada al configurar la Sincronización de Dispositivos. Cuando está habilitada, Realm gestiona automáticamente el proceso de restablecimiento del cliente en la mayoría de los casos. El cliente puede recuperar cambios no sincronizados cuando no hay cambios de esquema o cambios de esquema permanentes.

Para utilizar la recuperación de cliente, configure su reino con uno de los siguientes modos de restablecimiento de cliente:

• Recuperar el modo de cambios no sincronizados

• Recuperar o descartar cambios no sincronizados

Cuando la Recuperación de Cliente está habilitada, estas reglas determinan cómo se integran los objetos, incluyendo la resolución de conflictos cuando tanto el backend como el cliente realizan cambios en el mismo objeto:

• Se sincronizan los objetos creados localmente que no se sincronizaron antes del reinicio del cliente.

• Si se elimina un objeto en el servidor, pero se modifica en el cliente en recuperación, la eliminación tiene prioridad y el cliente descarta la actualización.

• Si se elimina un objeto en el cliente en recuperación, pero no en el servidor, el cliente aplica la instrucción de eliminación del servidor.

• En el caso de actualizaciones conflictivas en el mismo campo, se aplica la actualización del cliente.

Para obtener más información sobre cómo configurar la Recuperación de cliente, consulte Recuperación de cliente en la documentación de Servicios de aplicaciones.

La recuperación del cliente no puede realizarse correctamente si la aplicación realiza cambios importantes en el esquema. Un cambio importante es un cambio que se puede realizar en el esquema del servidor y que requiere una acción adicional para su gestión. En este caso, el restablecimiento del cliente recurre a un restablecimiento manual por error.

Para obtener información sobre cambios de esquema disruptivos y no disruptivos, consulte Referencia rápida sobre cambios disruptivos y no disruptivos en la documentación de App Services.

const config = {
  schema: [DogSchema],
  sync: {
    user: app.currentUser,
    flexible: true,
    clientReset: {
      mode: "recoverUnsyncedChanges",
      onBefore: (realm) => {
        // This block could be used for custom recovery, reporting, debugging etc.
      },
      onAfter: (beforeRealm, afterRealm) => {
        // This block could be used for custom recovery, reporting, debugging etc.
      },
      onFallback: (session, path) => {
        // See below "Manual Client Reset Fallback" section for example
      },
    },
  },
};

const config = {
  schema: [DogSchema],
  sync: {
    user: app.currentUser,
    flexible: true,
    clientReset: {
      mode: "recoverOrDiscardUnsyncedChanges",
      onBefore: (realm) => {
        // This block could be used for custom recovery, reporting, debugging etc.
      },
      onAfter: (beforeRealm, afterRealm) => {
        // This block could be used for custom recovery, reporting, debugging etc.
      },
      onFallback: (session, path) => {
        // See below "Manual Client Reset Fallback" section for example
      },
    },
  },
};

// Must define `realm` at higher scope than `config` so it's accessible
// from the `onFallback` callback
let realm;
const config = {
  schema: [DogSchema],
  sync: {
    user: app.currentUser,
    flexible: true,
    clientReset: {
      mode: "recoverOrDiscardUnsyncedChanges", // or "recoverUnsyncedChanges"
      // can also include `onBefore` and `onAfter` callbacks
      onFallback: (_session, path) => {
        try {
          // Prompt user to perform a client reset immediately. If they don't,
          // they won't receive any data from the server until they restart the app
          // and all changes they make will be discarded when the app restarts.
          const didUserConfirmReset = showUserAConfirmationDialog();
          if (didUserConfirmReset) {
            // Close and delete old realm from device
            realm.close();
            Realm.deleteFile(path);
            // Perform client reset
            Realm.App.Sync.initiateClientReset(app, path);
            // Navigate the user back to the main page or reopen the
            // the Realm and reinitialize the current page
          }
        } catch (err) {
          // Reset failed. Notify user that they'll need to
          // update the app
        }
      },
    },
  },
};
realm = await Realm.open(config);

Modo Descartar cambios no sincronizados

El modo Descartar cambios no sincronizados borra permanentemente todos los cambios locales no sincronizados realizados desde la última sincronización exitosa. Puedes usar esta moda cuando tu aplicación requiera una lógica de recuperación de cliente que no sea coherente con Recuperación automática del cliente, o cuando no quieras recuperar datos no sincronizados.

No utilice el modo de descartar cambios no sincronizados si su aplicación no puede perder datos locales que aún no se han sincronizado con el backend.

Para gestionar los restablecimientos de clientes con el modo de descartar cambios no sincronizados, pase un ClientResetConfig al clientReset campo de su SyncConfiguration. Incluya estas propiedades en ClientResetConfiguration el:

• mode:Establecer en "discardUnsyncedChanges".

• onBefore: Opcional. Función de devolución de llamada que se invoca antes de que el SDK ejecute este modo cuando recibe un error de restablecimiento del cliente desde el backend. Proporciona una copia del dominio.

• onAfter: Opcional. Función de devolución de llamada que se invoca después de que el SDK ejecute correctamente este modo. Proporciona instancias del dominio antes y después del reinicio del cliente.

El siguiente ejemplo implementa el modo de descartar cambios no sincronizados:

const config = {
  schema: [DogSchema],
  sync: {
    user: app.currentUser,
    flexible: true,
    clientReset: {
      mode: "discardUnsyncedChanges",
      onBefore: (realm) => {
        console.log("Beginning client reset for ", realm.path);
      },
      onAfter: (beforeRealm, afterRealm) => {
        console.log("Finished client reset for", beforeRealm.path);
        console.log("New realm path", afterRealm.path);
      },
    },
  },
};

// Once you have opened your Realm, you will have to keep a reference to it.
// In the error handler, this reference is called `realm`
async function handleSyncError(session, syncError) {
  if (syncError.name == "ClientReset") {
    console.log(syncError);
    try {
      console.log("error type is ClientReset....");
      const path = realm.path; // realm.path will not be accessible after realm.close()
      realm.close();
      Realm.App.Sync.initiateClientReset(app, path);
      // Download Realm from the server.
      // Ensure that the backend state is fully downloaded before proceeding,
      // which is the default behavior.
      realm = await Realm.open(config);
      realm.close();
    } catch (err) {
      console.error(err);
    }
  } else {
    // ...handle other error types
  }
}
const config = {
  schema: [DogSchema],
  sync: {
    user: app.currentUser,
    flexible: true,
    clientReset: {
      mode: "discardUnsyncedChanges",
      onBefore: (realm) => {
        // NOT used with destructive schema changes
        console.log("Beginning client reset for ", realm.path);
      },
      onAfter: (beforeRealm, afterRealm) => {
        // Destructive schema changes do not hit this function.
        // Instead, they go through the error handler.
        console.log("Finished client reset for", beforeRealm.path);
        console.log("New realm path", afterRealm.path);
      },
    },
    onError: handleSyncError, // invoked with destructive schema changes
  },
};

Modo manual

En el modo manual, defines tu propio controlador de restablecimiento de cliente. Te recomendamos usar un controlador de restablecimiento de cliente manual si la lógica de recuperación automática no funciona en tu aplicación y no puedes descartar los datos locales no sincronizados.

Para gestionar los restablecimientos de clientes en modo manual, pase un ClientResetConfig al clientReset campo de su SyncConfiguration. Incluya estas propiedades en ClientResetConfiguration el:

• mode:Establecer en "manual".

• onManual: Opcional. Función de devolución de llamada que se invoca al reiniciar el cliente. Proporciona información sobre la sesión de sincronización y la ruta al dominio actual. Si no se configura el controlador de errores onManual, el error de reinicio del cliente se revierte al controlador de errores de sincronización general.

const config = {
  schema: [DogSchema],
  sync: {
    user: app.currentUser,
    flexible: true,
    clientReset: {
      mode: "manual",
      onManual: (session, path) => {
        // handle manual client reset here
      },
    },
  },
};

Manejo del restablecimiento del cliente de prueba

Puede probar manualmente el manejo de restablecimiento del cliente de su aplicación finalizando y volviendo a habilitar la sincronización del dispositivo.

Al finalizar y reactivar Sync, los clientes que se conectaron previamente con Sync no podrán hacerlo hasta que restablezcan el cliente. Al finalizar Sync, se eliminan los metadatos del servidor que permiten la sincronización. El cliente debe descargar una nueva copia del dominio desde el servidor. El servidor envía un error de restablecimiento de cliente a estos clientes. Por lo tanto, al finalizar Sync, se activa la condición de restablecimiento de cliente.

Para probar el manejo del restablecimiento del cliente:

1. Escriba datos desde una aplicación cliente y espere a que se sincronicen.

2. Termina y vuelve a habilitar Device Sync.

3. Ejecute la aplicación cliente nuevamente. La aplicación debería mostrar un error de restablecimiento de cliente al intentar conectarse al servidor.