동기화 오류 처리 - Swift SDK

자동 및 수동 클라이언트 재설정

Realm SDK는 대부분의 클라이언트 재설정 오류를 자동으로 처리하는 클라이언트 재설정 모드 를 제공합니다. 자동 클라이언트 재설정 모드는 Realm을 닫거나 알림을 누락하지 않고 로컬 Realm 파일을 동기화 가능한 상태로 복원합니다.

.manual 를 제외한 모든 클라이언트 재설정 모드는 자동 클라이언트 재설정을 수행합니다. 모드 간의 차이점은 아직 백엔드에 동기화되지 않은 기기의 변경 사항을 처리하는 방법에 따라 달라집니다.

대부분의 클라이언트 재설정 시나리오를 자동으로 처리하려면 .recoverUnsyncedChanges 를 선택합니다. 이렇게 하면 클라이언트 재설정이 발생할 때 동기화되지 않은 변경 사항을 복구하려고 시도합니다.

경우에 따라 수동 클라이언트 재설정 처리기를 설정 해야 하거나 설정해야 할 수 있습니다. 앱에 자동으로 처리할 수 없는 특정 클라이언트 재설정 로직이 필요한 경우 이 작업을 수행할 수 있습니다.

클라이언트 재설정 모드 지정

Swift SDK 는 SyncConfiguration 에서 클라이언트 재설정 모드 를 지정하는 옵션을 제공합니다. .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())

이 속성 은 다양한 클라이언트 재설정 모드를 나타내는 열거형 을 사용합니다.

• .recoverUnsyncedChanges

• .recoverOrDiscardUnsyncedChanges

• .discardUnsyncedChanges

• .manual

구성에서 .clientResetMode 을 지정하지 않으면 클라이언트 재설정 모드는 기본적으로 .recoverUnsyncedChanges 으로 설정됩니다.

자동 클라이언트 재설정 프로세스 중에 실행할 before 및 after 차단을 지정할 수 있습니다. 이를 사용하여 애플리케이션에 중요한 복구 로직을 수행할 수 있습니다.

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

앱에 특정 클라이언트 복구가 필요한 경우 .manual 클라이언트 재설정 모드를 지정하고 수동 클라이언트 재설정 핸들러 를 설정할 수 있습니다. 클라이언트 재설정 중에 앱이 수행해야 하는 특정 사용자 지정 로직이 있거나 클라이언트 복구 규칙 이 앱에서 작동하지 않는 경우 이 작업을 수행할 수 있습니다.

스키마 변경 처리

클라이언트 복구 는 Device Sync를 구성 할 때 기본적으로 활성화되는 기능입니다. 클라이언트 복구가 활성화되면 Realm은 대부분의 경우 클라이언트 재설정 프로세스를 자동으로 관리할 수 있습니다. 스키마를 변경하는 경우:

• 클라이언트는 스키마 변경이 없거나 손상적이지 않은 스키마 변경이 없는 경우 동기화되지 않은 변경 사항을 복구 할 수 있습니다.

• 손상적인 스키마 변경이 발생하면 자동 클라이언트 재설정 모드는 수동 오류 처리기로 되돌아갑니다. 이 경우 수동 클라이언트 재설정 오류 처리기 를 설정할 수 있습니다. 앱에서 호환성이 손상되는 스키마 변경이 있을 때는 자동 클라이언트 복구를 수행할 수 없습니다.

단절적 스키마 변경과 단절적이지 않은 변경에 대한 자세한 내용은 단절적 변경과 단절적이지 않은 변경 비교를 참조하세요.

동기화되지 않은 변경 내용 복구

클라이언트 재설정 중에 클라이언트 애플리케이션은 아직 백엔드 와 동기화되지 않은 로컬 영역 의 데이터 복구를 시도할 수 있습니다. 동기화되지 않은 변경 사항을 복구하려면 기본값 으로 App Services App 에서 클라이언트 복구 를 활성화해야 합니다.

앱 에서 아직 동기화되지 않은 변경 사항을 복구하려면 SyncConfiguration 에서 .clientResetMode 를 다음 중 하나로 설정하다 합니다.

• .recoverUnsyncedChanges: 이 모드를 선택하면 클라이언트는 동기화되지 않은 변경 사항을 복구하려고 시도합니다. 동기화되지 않은 변경 사항을 삭제하고 싶지 않을 때 이 모드를 선택하세요.

• .recoverOrDiscardUnsyncedChanges: 클라이언트는 먼저 아직 동기화되지 않은 변경 사항을 복구하려고 시도합니다. 클라이언트가 동기화되지 않은 데이터를 복구할 수 없는 경우 동기화 되지 않은 변경 사항을 삭제 하지만 계속 자동으로 클라이언트 재설정을 수행합니다. 동기화되지 않은 변경 사항을 삭제하도록 자동 클라이언트 복구를 활성화하려면 이 모드를 선택합니다.

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

손상적인 스키마 변경이 있거나 Device Sync 구성에서 클라이언트 복구 가 비활성화된 경우와 같이 동기화되지 않은 변경 사항 복구 모드에서 클라이언트 재설정 작업을 완료할 수 없는 경우가 있을 수 있습니다. 이 경우를 처리하기 위해 앱에서 수동 클라이언트 재설정 폴백을 구현할 수 있습니다.

동기화되지 않은 변경 내용 삭제

동기화되지 않은 변경 사항 삭제 클라이언트 재설정 모드 는 마지막 동기화 에 성공적인 이후 이루어진 모든 동기화되지 않은 로컬 변경 사항을 영구적으로 삭제합니다. 앱 에 Device Sync 클라이언트 복구 규칙 과 일관적인 하지 않는 클라이언트 복구 로직이 필요한 경우 또는 동기화되지 않은 데이터를 복구하지 않으려는 경우 이 모드 를 사용할 수 있습니다.

애플리케이션에서 아직 백엔드에 동기화되지 않은 로컬 데이터를 잃을 수 없는 경우 동기화되지 않은 변경 사항 삭제 모드를 사용하지 마세요.

동기화되지 않은 변경 사항을 삭제하는 자동 클라이언트 재설정을 수행하려면 SyncConfiguration 에서 .clientResetMode 를 .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)")
}

손상적인 스키마 변경이 있는 경우와 같이 동기화되지 않은 변경 사항 삭제 모드에서 클라이언트 재설정 작업을 완료할 수 없는 경우가 있을 수 있습니다. 이 경우를 처리하기 위해 앱에서 수동 클라이언트 재설정 폴백을 구현할 수 있습니다.

수동 클라이언트 재설정 모드

.clientResetMode 에 .manual 를 지정하는 경우 수동 클라이언트 재설정 핸들러를 구현해야 합니다.

.manual 모드 에서는 자체 클라이언트 재설정 핸들러를 정의합니다. 핸들러는 ErrorReportingBlock 을 취할 수 있습니다. 가능하면 자동 클라이언트 복구 모드 를 사용하고, 자동 복구 로직이 앱 에 적합하지 않은 경우에만 .manual 모드 를 선택하는 것이 좋습니다.

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

수동 클라이언트 재설정 폴백

손상적인 스키마 변경이 있는 경우와 같이 클라이언트 재설정 작업을 자동으로 완료할 수 없는 경우 클라이언트 재설정 프로세스는 수동 오류 처리기에게로 넘어갑니다. 이는 다음과 같은 자동 클라이언트 재설정 모드에서 발생할 수 있습니다.

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

클라이언트 재설정 처리 테스트

Device Sync를 종료했다가 다시 활성화하여 애플리케이션의 클라이언트 재설정 처리를 수동으로 테스트할 수 있습니다.

동기화를 종료했다가 다시 허용하면 이전에 동기화로 연결한 클라이언트는 클라이언트 재설정을 수행할 때까지 연결할 수 없습니다. 동기화를 종료하면 클라이언트의 동기화를 허용하는 메타데이터가 서버에서 삭제됩니다. 클라이언트는 서버에서 영역의 새 복사본을 다운로드해야 합니다. 서버는 이러한 클라이언트에 클라이언트 재설정 오류를 보냅니다. 따라서 동기화를 종료하면 trigger 클라이언트 재설정 조건이 됩니다.

클라이언트 재설정 처리를 테스트하려면 다음을 수행합니다.

1. 클라이언트 애플리케이션에서 데이터를 쓰고 동기화될 때까지 기다립니다.

2. Realm Mobile Sync를 종료했다가 다시 활성화합니다.

3. 클라이언트 앱을 다시 실행합니다. 앱이 서버에 연결하려고 할 때 클라이언트 재설정 오류가 발생해야 합니다.