Gestionar Errores de Sincronización - Swift SDK

Automatic vs. Manual Client Reset

Los SDK de Realm ofrecen modos de restablecimiento de cliente que gestionan automáticamente la mayoría de los errores de restablecimiento. Los modos de restablecimiento automático de cliente restauran el archivo local de Realm a un estado sincronizable sin cerrarlo ni perder notificaciones.

Todos los modos de reinicio del cliente excepto .manual Realizar un restablecimiento automático del cliente. Las diferencias entre los modos se basan en cómo gestionan los cambios en el dispositivo que aún no se han sincronizado con el backend.

Elige .recoverUnsyncedChanges para gestionar automáticamente la mayoría de los escenarios de restablecimiento del cliente. Esto intenta recuperar los cambios no sincronizados cuando ocurre un restablecimiento del cliente.

In some cases, you may want or need to set a manual client reset handler. You may want to do this if your app requires specific client reset logic that can't be handled automatically.

Specify a Client Reset Mode

El SDK de Swift ofrece la opción de especificar un modo de restablecimiento de cliente en SyncConfiguration.Esta es la propiedad `.clientResetMode`.

// Specify the clientResetMode when you create the SyncConfiguration.
// If you do not specify, this defaults to `.recoverUnsyncedChanges` mode.
var configuration = user.flexibleSyncConfiguration(clientResetMode: .recoverUnsyncedChanges())

Esta propiedad toma una enumeración que representa los diferentes modos de reinicio del cliente:

• .recoverUnsyncedChanges

• .recoverOrDiscardUnsyncedChanges

• .discardUnsyncedChanges

• .manual

Si no se especifica .clientResetMode en la configuración, el modo de restablecimiento del cliente predeterminado es a .recoverUnsyncedChanges.

You can specify a before and after block to execute during the automatic client reset process. You might use this to perform recovery logic that is important to your application.

// A block called after a client reset error is detected, but before the
// client recovery process is executed.
// This block could be used for any custom logic, reporting, debugging etc.
// This is one example, but your usage may vary.
let beforeClientResetBlock: (Realm) -> Void = { before in
    var recoveryConfig = Realm.Configuration()
    recoveryConfig.fileURL = myRecoveryPath
    do {
       try before.writeCopy(configuration: recoveryConfig)
        // The copied realm could be used later for recovery, debugging, reporting, etc.
     } catch {
            // handle error
     }
}
// A block called after the client recovery process has executed.
// This block could be used for custom recovery, reporting, debugging etc.
// This is one example, but your usage may vary.
let afterClientResetBlock: (Realm, Realm) -> Void = { before, after in
    //     let res = after.objects(myClass.self)
    //     if (res.filter("primaryKey == %@", object.primaryKey).first != nil) {
    //         // ...custom recovery logic...
    //     } else {
    //         // ...custom recovery logic...
    //     }
    // }
}
do {
    let app = App(id: YOUR_APP_SERVICES_APP_ID)
    let user = try await app.login(credentials: Credentials.anonymous)
    var configuration = user.flexibleSyncConfiguration(clientResetMode:
                                                        .recoverOrDiscardUnsyncedChanges(
                                                            beforeReset: beforeClientResetBlock,
                                                            afterReset: afterClientResetBlock))
} catch {
    print("Error logging in user: \(error.localizedDescription)")
}

Si su aplicación tiene necesidades específicas de recuperación de clientes, puede especificar el .manual modo de restablecimiento de cliente y configurar un controlador manual de restablecimiento de cliente. Puede hacerlo si su aplicación debe ejecutar una lógica personalizada específica durante un restablecimiento de cliente o si las reglas de recuperación de cliente no funcionan.

Handle Schema Changes

Client Recovery is a feature that is enabled by default when you configure Device Sync. When Client Recovery is enabled, Realm can automatically manage the client reset process in most cases. When you make schema changes:

• The client can recover unsynced changes when there are no schema changes, or non-breaking schema changes.

• Al realizar cambios de esquema disruptivos, los modos de restablecimiento automático del cliente recurren a un gestor de errores manual. Puede configurar un gestor de errores de restablecimiento manual del cliente para este caso. La recuperación automática del cliente no puede ocurrir cuando su aplicación realiza cambios de esquema disruptivos.

For information on breaking vs. non-breaking schema changes, see Breaking vs. Non-Breaking Change Quick Reference.

Recuperar cambios no sincronizados

Durante un restablecimiento de cliente, las aplicaciones cliente pueden intentar recuperar datos del dominio local que aún no se hayan sincronizado con el backend. Para recuperar los cambios no sincronizados, laRecuperación de Cliente debe estar habilitada en la aplicación de Servicios de Aplicaciones, como está predeterminado.

Si quieres que tu aplicación recupere cambios que aún no se han sincronizado, establece el .clientResetMode en la SyncConfiguration a uno de:

• .recoverUnsyncedChanges: When you choose this mode, the client attempts to recover unsynced changes. Choose this mode when you do not want to fall through to discard unsynced changes.

• .recoverOrDiscardUnsyncedChangesEl cliente primero intenta recuperar los cambios que aún no se han sincronizado. Si no puede recuperar los datos no sincronizados, 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.

// Specify the clientResetMode when you create the SyncConfiguration.
// If you do not specify, this defaults to `.recoverUnsyncedChanges` mode.
var configuration = user.flexibleSyncConfiguration(clientResetMode: .recoverUnsyncedChanges())

Es posible que, en ocasiones, la operación de restablecimiento del cliente no pueda completarse en el modo de recuperación de cambios no sincronizados, como cuando hay cambios de esquema importantes o la recuperación del cliente está deshabilitada en la configuración de sincronización de dispositivos. Para solucionar este problema, la aplicación puede implementar una alternativa de restablecimiento manual del cliente.

Descartar cambios no sincronizados

The discard unsynced changes client reset mode permanently deletes all local unsynced changes made since the last successful sync. You might use this mode when your app requires client recovery logic that is not consistent with the Device Sync Client Recovery Rules, or when you don't want to recover unsynced data.

Do not use discard unsynced changes mode if your application cannot lose local data that has not yet synced to the backend.

Para realizar un restablecimiento automático del cliente que descarte cambios no sincronizados, establece el .clientResetMode en el SyncConfiguration a .discardUnsyncedChanges.

do {
    let app = App(id: APP_ID)
    let user = try await app.login(credentials: Credentials.anonymous)
    var config = user.flexibleSyncConfiguration(clientResetMode: .discardUnsyncedChanges())
} catch {
    print("Error logging in user: \(error.localizedDescription)")
}

Puede haber ocasiones en las que la operación de restablecimiento del cliente no se pueda completar en modo de descartar cambios no sincronizados, como cuando hay cambios de esquema incompatibles. Para manejar este caso, tu aplicación puede implementar un restablecimiento del cliente manual como alternativa.

Modo de restablecimiento manual del cliente

Cuando especifique .manual para .clientResetMode, se debe implementar un gestor de restablecimiento manual del cliente.

En modo .manual, defines tu propio gestor de restablecimiento del cliente. El controlador puede aceptar un ErrorReportingBlock. Se recomienda usar los modos automáticos de recuperación de clientes cuando sea posible, y elegir el modo .manual solo si la lógica de recuperación automática no es adecuada para tu aplicación.

do {
    let app = App(id: APP_ID)
    let user = try await app.login(credentials: Credentials.anonymous)
    var config = user.flexibleSyncConfiguration(clientResetMode: .manual())
} catch {
    print("Error logging in user: \(error.localizedDescription)")
}

Manual Client Reset Fallback

Si la operación de restablecimiento del cliente no puede completarse automáticamente, como cuando se producen cambios drásticos en el esquema, el proceso de restablecimiento del cliente pasa a un manejador de errores manual. Esto puede ocurrir en cualquiera de estos modos automáticos de restablecimiento del cliente:

• .recoverUnsyncedChanges

• .recoverOrDiscardUnsyncedChanges

• .discardUnsyncedChanges

RLMApp *app = [RLMApp appWithId:YOUR_APP_ID];
[[app syncManager] setErrorHandler:^(NSError *error, RLMSyncSession *session) {
    if (error.code == RLMSyncErrorClientResetError) {
        // TODO: Invalidate all open realm instances
        // TODO: Restore the local changes backed up at [error rlmSync_clientResetBackedUpRealmPath]
        [RLMSyncSession immediatelyHandleError:[error rlmSync_errorActionToken] syncManager:[app syncManager]];
        return;
    }
    // Handle other errors...
}];

func handleClientReset() {
    // Report the client reset error to the user, or do some custom logic.
}
do {
    let app = App(id: APP_ID)
    let user = try await app.login(credentials: Credentials.anonymous)
    var config = user.flexibleSyncConfiguration(clientResetMode: .recoverOrDiscardUnsyncedChanges())
    // If client recovery fails,
    app.syncManager.errorHandler = { error, session in
        guard let syncError = error as? SyncError else {
            fatalError("Unexpected error type passed to sync error handler! \(error)")
        }
        switch syncError.code {
        case .clientResetError:
            if let (path, clientResetToken) = syncError.clientResetInfo() {
                handleClientReset()
                SyncSession.immediatelyHandleError(clientResetToken, syncManager: app.syncManager)
            }
        default:
            // Handle other errors...
            ()
        }
    }
} catch {
    print("Error: \(error.localizedDescription)")
}

Test Client Reset Handling

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

When you terminate and re-enable Sync, clients that have previously connected with Sync are unable to connect until after they perform a client reset. Terminating Sync deletes the metadata from the server that allows the client to synchronize. The client must download a new copy of the realm from the server. The server sends a client reset error to these clients. So, when you terminate Sync, you trigger the client reset condition.

To test client reset handling:

1. Write data from a client application and wait for it to synchronize.

2. Termina y vuelve a habilitar Device Sync.

3. Ejecuta la aplicación cliente nuevamente. La aplicación debería obtener un error de restablecimiento del cliente cuando intente conectarse al servidor.