Lidar com erros de sincronização - Swift SDK

reinício do cliente automático versus manual

Os SDKs do Realm oferecem modos de reinício do cliente que gerenciam automaticamente a maioria dos erros de reinício do cliente. Os modos automáticos de reinício do cliente restauram seu arquivo de domínio local para um estado sincronizável sem fechar o domínio ou perder notificações.

Todos os modos de reinício do cliente, exceto .manual , executam um reinício do cliente automático. As diferenças entre os modos são baseadas em como eles lidam com alterações no dispositivo que ainda não foram sincronizadas com o backend.

Escolha .recoverUnsyncedChanges para lidar com a maioria dos cenários de reinício do cliente automaticamente. Isso tenta recuperar alterações não sincronizadas quando ocorre um reinício do cliente.

Em alguns casos, você pode desejar ou precisar definir um manipulador manual de redefinição do cliente. Talvez você queira fazer isso se o seu aplicativo exigir lógica de redefinição de cliente específica que não possa ser tratada automaticamente.

Especificar um modo de reinício do cliente

O Swift SDK oferece a opção de especificar um modo de reinício do cliente em seu SyncConfiguration. Este é o .clientResetMode propriedade.

// 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 propriedade usa um enumeração que representa os diferentes modos de reinício do cliente :

• .recoverUnsyncedChanges

• .recoverOrDiscardUnsyncedChanges

• .discardUnsyncedChanges

• .manual

Se você não especificar .clientResetMode em sua configuração, o modo de reinício do cliente será padronizado como .recoverUnsyncedChanges.

Você pode especificar um bloco before e after para ser executado durante o processo automático de reinício do cliente. Você pode usar isso para executar a lógica de recuperação que é importante para seu aplicativo.

// 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)")
}

Se seu aplicativo tiver necessidades específicas de recuperação do cliente, você poderá especificar o modo de reinício do cliente .manual e definir um manipulador manual de reinício do cliente. Você pode fazer isso se tiver uma lógica personalizada específica que seu aplicativo deve executar durante a redefinição de um cliente ou se as regras de recuperação do cliente não funcionarem para seu aplicativo.

Lidar com alterações no esquema

A recuperação de cliente é um recurso que é habilitado por padrão quando você configura o Device Sync. Quando a Recuperação de Cliente está ativada, o Realm pode gerenciar automaticamente o processo de redefinição do cliente na maioria dos casos. Quando você faz alterações no esquema:

• O cliente pode recuperar alterações não sincronizadas quando não houver alterações no esquema ou alterações no esquema não significativas.

• Quando você faz alterações significativas no esquema, os modos automáticos de reinício do cliente voltam para um manipulador manual de erros. Você pode definir um manipulador de erro de redefinição manual do cliente para esse caso. A recuperação automática do cliente não pode ocorrer quando seu aplicativo faz alterações significativas no esquema.

Para obter informações sobre alterações de esquema significativas e não significativas, consulte Referência rápida de alterações significativas versus não significativas.

Recuperar alterações não sincronizadas

Durante um reinício do cliente do cliente , os aplicativos do cliente podem tentar recuperar dados no Realm local que ainda não foram sincronizados com o backend. Para recuperar alterações não sincronizadas, a Recuperação de cliente deve estar ativada em seu App Services App, como é por padrão.

Se você quiser que seu aplicativo recupere as alterações que ainda não foram sincronizadas, defina .clientResetMode em SyncConfiguration como um dos seguintes:

• .recoverUnsyncedChanges: ao escolher esse modo, o cliente tenta recuperar alterações não sincronizadas. Escolha este modo se não quiser descartar alterações não sincronizadas.

• .recoverOrDiscardUnsyncedChanges: o cliente primeiro tenta recuperar as alterações que ainda não foram sincronizadas. Se o cliente não conseguir recuperar dados não sincronizados, ele falhará no descarte das alterações não sincronizadas, mas continuará executando automaticamente o reinício do cliente. Escolha este modo quando quiser ativar a recuperação automática do cliente para voltar a descartar alterações não sincronizadas.

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

Pode haver momentos em que a operação de redefinição do cliente não pode ser concluída no modo de recuperação de alterações não sincronizadas, como quando há alterações de esquema de quebra ou a Recuperação de Cliente está desabilitada na configuração do Device Sync. Para lidar com esse caso, seu aplicativo pode implementar um fallback manual de redefinição do cliente.

Descartar alterações não sincronizadas

O modo de reinício do cliente de descarte de alterações não sincronizadas exclui permanentemente todas as alterações não sincronizadas locais feitas desde a última sincronização bem-sucedida. Você pode usar esse modo quando seu aplicativo exigir uma lógica de recuperação de cliente que não seja consistente com as Regras de recuperação de cliente do Device Sync ou quando você não quiser recuperar dados não sincronizados.

Não use o modo de descarte de alterações não sincronizadas se o aplicativo não puder perder dados locais que ainda não foram sincronizados com o backend.

Para executar um reinício do cliente automático que descarta alterações não sincronizadas, defina o .clientResetMode em SyncConfiguration como .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)")
}

Pode haver momentos em que a operação de reinício do cliente não pode ser concluída no modo de descarte de alterações não sincronizadas, como quando há alterações de esquema significativas. Para lidar com esse caso, seu aplicativo pode implementar um fallback manual de redefinição do cliente.

Modo de reinício do cliente

Ao especificar .manual para .clientResetMode, você deve implementar um manipulador manual de reinício do cliente.

No modo .manual , você define seu próprio manipulador de reinício do cliente . O manipulador pode receber um ErrorReportingBlock. Recomendamos usar os modos de recuperação automática de cliente quando possível e escolher o modo .manual somente se a lógica de recuperação automática não for adequada para seu aplicativo.

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)")
}

fallback de reinício do cliente

Se a operação de reinício do cliente não puder ser concluída automaticamente, como quando há alterações de esquema de quebra, o processo de reinício do cliente passará para um manipulador de erros manual. Isso pode ocorrer em qualquer um destes modos automáticos de reinício do 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)")
}

Tratamento de reinício do cliente de teste

Você pode testar manualmente o tratamento de redefinição do cliente do seu aplicativo encerrando e reativando o Device Sync.

Quando você encerra e reativa a sincronização, os clientes que se conectaram anteriormente à sincronização não conseguem se conectar até depois de fazerem um reinício do cliente. O encerramento da sincronização exclui os metadados do servidor que permitem ao cliente sincronizar. O cliente deve baixar uma nova cópia do Realm do servidor. O servidor envia um erro de reinício do cliente para esses clientes. Então, ao encerrar a sincronização, você trigger a condição de reinício do cliente.

Para testar o tratamento de reinício do cliente:

1. Escreva dados de um aplicativo cliente e aguarde a sincronização.

2. Encerre e reative o Realm Mobile Sync.

3. Run the client app again. O aplicativo deve receber um erro de reinício do cliente ao tentar se conectar ao servidor.