Close #487 improve backup exception handler & test (#489)

Author: theachoem

docs/backup_exception_handling.md

@@ -0,0 +1,210 @@
+# Backup Exception Handling Implementation Summary
+
+## Overview
+
+This implementation provides comprehensive exception handling for the StoryPad backup sync system, following MVVM architecture principles and ensuring robust error management across all layers.
+
+## Architecture
+
+### Exception Flow
+
+```
+Google Drive Client → Backup Sync Service → Repository → Backup Provider
+     (Throws)      →    (Catches/Wraps)  → (Safe Types) → (UI States)
+```
+
+## Key Components
+
+### 1. Exception Types (`lib/core/exceptions/backup_exceptions.dart`)
+
+**Base Exception:**
+
+- `BackupException` - Abstract base class with message, context, and retry information
+
+**Specific Exception Types:**
+
+- `NetworkException` - Network connectivity issues (retryable by default)
+- `AuthException` - Authentication/authorization failures with specific types:
+  - `tokenExpired` - Requires reauthentication
+  - `tokenRevoked` - Requires sign out and new login
+  - `insufficientScopes` - Requires scope request
+  - `signInRequired` - User needs to sign in
+  - `signInFailed` - Sign-in process failed
+- `QuotaException` - Google Drive quota and rate limiting
+- `FileOperationException` - File upload/download/delete failures (retryable)
+- `ServiceException` - Business logic and data processing errors
+- `ConfigurationException` - Setup and configuration errors
+
+### 2. Result Types (`lib/core/types/backup_result.dart`)
+
+**BackupResult<T>** - Sealed class with three variants:
+
+- `BackupSuccess<T>` - Operation completed successfully
+- `BackupFailure<T>` - Operation failed completely
+- `BackupPartialSuccess<T>` - Some operations succeeded, some failed
+
+**BackupError** - Standardized error representation:
+
+- Type classification (network, auth, quota, etc.)
+- User-friendly messages
+- Retry capability flags
+- Contextual metadata
+
+### 3. Retry Policy (`lib/core/utils/retry_policy.dart`)
+
+**RetryPolicy:**
+
+- Configurable retry attempts, delays, and backoff strategies
+- Exception type filtering
+- Predefined policies for common scenarios:
+  - `RetryPolicy.network` - For network operations
+  - `RetryPolicy.quota` - For quota-limited operations
+  - `RetryPolicy.none` - No retry
+
+**RetryExecutor:**
+
+- Automatic retry logic with exponential backoff
+- Timeout support
+- Safe result wrapping
+
+### 4. Enhanced Google Drive Client (`lib/core/services/google_drive_client.dart`)
+
+**Authentication Enhancements:**
+
+- Proper token expiration detection and handling
+- Token revocation detection
+- Scope insufficiency handling
+- User-friendly error messages
+
+**API Operation Safety:**
+
+- HTTP status code to exception mapping
+- Network error detection and classification
+- File operation context preservation
+- Automatic retry for transient failures
+
+### 5. Updated Backup Services
+
+**Service Layer Changes:**
+
+- `BackupImagesUploaderService` - Enhanced with retry logic and auth handling
+- `BackupUploaderService` - Improved error reporting and file handling
+- `BackupLatestCheckerService` - Better content validation and download retry
+- All services now throw specific exceptions instead of generic errors
+
+### 6. Repository Layer (`lib/core/repositories/backup_repository.dart`)
+
+**Safe Result Wrapping:**
+
+- All public methods return `BackupResult<T>` instead of throwing
+- Authentication error detection and user sign-out handling
+- Connection status mapping from exceptions
+- Comprehensive error context preservation
+
+### 7. Provider Layer (`lib/providers/backup_provider.dart`)
+
+**UI State Management:**
+
+- Proper handling of `BackupResult` types
+- User-friendly error message display
+- Automatic sign-out on token revocation
+- Graceful fallback for partial failures
+
+## Error Handling Scenarios
+
+### 1. Token Expiration
+
+- **Detection:** 401 HTTP responses, token validation failures
+- **Handling:** Automatic reauthentication attempt
+- **UI:** "Your session has expired. Please sign in again."
+
+### 2. Token Revocation
+
+- **Detection:** 403 responses, scope validation failures
+- **Handling:** Automatic sign-out, clear stored credentials
+- **UI:** "Access has been revoked. Please sign in again to continue using backup."
+
+### 3. Network Issues
+
+- **Detection:** SocketException, TimeoutException
+- **Handling:** Automatic retry with exponential backoff
+- **UI:** "Network connection error. Please check your internet connection and try again."
+
+### 4. Storage Quota Exceeded
+
+- **Detection:** Specific Google Drive API error messages
+- **Handling:** No retry, immediate user notification
+- **UI:** "Google Drive storage is full. Please free up space or upgrade your storage plan."
+
+### 5. Rate Limiting
+
+- **Detection:** 429 HTTP responses
+- **Handling:** Retry with rate limit aware delays
+- **UI:** "Too many requests. Please wait a moment before trying again."
+
+## Testing
+
+### Test Coverage
+
+- **Exception Types:** Comprehensive unit tests for all exception scenarios
+- **Result Types:** Complete testing of success, failure, and partial success cases
+- **Retry Logic:** Various retry scenarios and policy configurations
+- **Integration:** End-to-end error handling scenarios
+
+### Test Files
+
+- `test/core/exceptions/backup_exceptions_test.dart` - Exception type tests
+- `test/core/types/backup_result_test.dart` - Result type functionality
+- `test/core/utils/retry_policy_test.dart` - Retry logic and policies
+- `test/core/services/google_drive_client_test.dart` - Client error scenarios
+
+## Benefits
+
+### For Users
+
+- Clear, actionable error messages
+- Automatic recovery from transient issues
+- Graceful handling of authentication problems
+- Continued functionality during partial failures
+
+### For Developers
+
+- Type-safe error handling
+- Centralized error classification
+- Comprehensive logging and debugging context
+- Easy testing of error scenarios
+
+### For Maintenance
+
+- Consistent error handling patterns
+- Clear separation of concerns
+- Extensible exception hierarchy
+- Robust retry and recovery mechanisms
+
+## Key Features
+
+### 🔐 Authentication Handling
+
+- Automatic token refresh
+- Graceful handling of revoked access
+- Smart sign-out on permanent auth failures
+
+### 🔄 Retry Logic
+
+- Exponential backoff with jitter
+- Configurable retry policies
+- Rate limit aware delays
+
+### 📱 User Experience
+
+- User-friendly error messages
+- Progress indication during retries
+- Offline mode support
+
+### 🧪 Testing
+
+- Comprehensive test coverage
+- Mock-friendly architecture
+- Error scenario validation
+
+This implementation ensures robust, user-friendly backup functionality that gracefully handles all common failure scenarios while maintaining the UI's functional integrity.

lib/core/objects/backup_exceptions/auth_exception.dart

@@ -0,0 +1,41 @@
+part of 'backup_exception.dart';
+
+enum AuthExceptionType {
+  tokenExpired,
+  tokenRevoked,
+  insufficientScopes,
+  signInRequired,
+  signInFailed,
+}
+
+/// Google authentication and authorization exceptions
+class AuthException extends BackupException {
+  final AuthExceptionType type;
+
+  const AuthException(
+    super.message,
+    this.type, {
+    super.context,
+    super.isRetryable = false,
+  });
+
+  @override
+  String get userFriendlyMessage {
+    switch (type) {
+      case AuthExceptionType.tokenExpired:
+        return 'Your session has expired. Please sign in again.';
+      case AuthExceptionType.tokenRevoked:
+        return 'Access has been revoked. Please sign in again to continue using backup.';
+      case AuthExceptionType.insufficientScopes:
+        return 'Additional permissions are required for backup functionality.';
+      case AuthExceptionType.signInRequired:
+        return 'Please sign in to Google Drive to use backup features.';
+      case AuthExceptionType.signInFailed:
+        return 'Failed to sign in to Google Drive. Please try again.';
+    }
+  }
+
+  bool get requiresSignOut => type == AuthExceptionType.tokenRevoked;
+  bool get requiresReauth => type == AuthExceptionType.tokenExpired || type == AuthExceptionType.signInRequired;
+  bool get requiresScopeRequest => type == AuthExceptionType.insufficientScopes;
+}

lib/core/objects/backup_exceptions/backup_exception.dart

@@ -0,0 +1,25 @@
+part 'auth_exception.dart';
+part 'configuration_exception.dart';
+part 'file_operation_exception.dart';
+part 'network_exception.dart';
+part 'quota_exception.dart';
+part 'service_exception.dart';
+
+/// Base exception for all backup-related errors
+abstract class BackupException implements Exception {
+  final String message;
+  final String? context;
+  final bool isRetryable;
+
+  const BackupException(
+    this.message, {
+    this.context,
+    this.isRetryable = false,
+  });
+
+  @override
+  String toString() => 'BackupException: $message${context != null ? ' ($context)' : ''}';
+
+  /// Creates user-friendly error message for UI display
+  String get userFriendlyMessage => message;
+}

lib/core/objects/backup_exceptions/configuration_exception.dart

@@ -0,0 +1,9 @@
+part of 'backup_exception.dart';
+
+/// Configuration or setup related exceptions
+class ConfigurationException extends BackupException {
+  const ConfigurationException(super.message, {super.context, super.isRetryable = false});
+
+  @override
+  String get userFriendlyMessage => 'Configuration error. Please restart the app or contact support.';
+}

lib/core/objects/backup_exceptions/file_operation_exception.dart

@@ -0,0 +1,34 @@
+part of 'backup_exception.dart';
+
+enum FileOperationType {
+  upload,
+  download,
+  delete,
+  list,
+}
+
+/// File operation exceptions
+class FileOperationException extends BackupException {
+  final FileOperationType operation;
+
+  const FileOperationException(
+    super.message,
+    this.operation, {
+    super.context,
+    super.isRetryable = true,
+  });
+
+  @override
+  String get userFriendlyMessage {
+    switch (operation) {
+      case FileOperationType.upload:
+        return 'Failed to upload backup. Please try again.';
+      case FileOperationType.download:
+        return 'Failed to download backup. Please check your connection and try again.';
+      case FileOperationType.delete:
+        return 'Failed to delete backup file. Please try again.';
+      case FileOperationType.list:
+        return 'Failed to load backup files. Please check your connection and try again.';
+    }
+  }
+}

lib/core/objects/backup_exceptions/network_exception.dart

@@ -0,0 +1,9 @@
+part of 'backup_exception.dart';
+
+/// Network-related exceptions
+class NetworkException extends BackupException {
+  const NetworkException(super.message, {super.context, super.isRetryable = true});
+
+  @override
+  String get userFriendlyMessage => 'Network connection error. Please check your internet connection and try again.';
+}

lib/core/objects/backup_exceptions/quota_exception.dart

@@ -0,0 +1,31 @@
+part of 'backup_exception.dart';
+
+enum QuotaExceptionType {
+  storageQuotaExceeded,
+  rateLimitExceeded,
+  dailyLimitExceeded,
+}
+
+/// Google Drive API quota and storage exceptions
+class QuotaException extends BackupException {
+  final QuotaExceptionType type;
+
+  const QuotaException(
+    super.message,
+    this.type, {
+    super.context,
+    super.isRetryable = false,
+  });
+
+  @override
+  String get userFriendlyMessage {
+    switch (type) {
+      case QuotaExceptionType.storageQuotaExceeded:
+        return 'Google Drive storage is full. Please free up space or upgrade your storage plan.';
+      case QuotaExceptionType.rateLimitExceeded:
+        return 'Too many requests. Please wait a moment before trying again.';
+      case QuotaExceptionType.dailyLimitExceeded:
+        return 'Daily API limit reached. Please try again tomorrow.';
+    }
+  }
+}