feat: Intelligent error management with Dead Letter Queue

[matthieup240]

⚠️ Dependencies

This PR is built on top of PR #7 (Adaptive sync improvements). Please review and merge #7 first, or review this PR with the understanding that it includes those changes.

Base branch for review: feat/adaptive-sync-and-realtime-improvements from PR #7
Changes in this PR: Only the commits related to error management (1 commit after PR #7)

---

Summary

This PR introduces a comprehensive error management system that prevents queue blocking and ensures data integrity in offline-first scenarios.

Key Features

🎯 Error Classification

• New SyncErrorClassifier distinguishes network errors from application errors
• Network errors (SocketException, TimeoutException, PostgrestException without code): Unlimited retries, never lose data
• Application errors (validation, constraint violations): Move to Dead Letter Queue after 3 attempts

🔄 Circuit Breaker Pattern

• Prevents network spam with automatic circuit breaking after 5 consecutive network errors
• Auto-resets after 2 minutes to allow retry when network recovers
• Per-table circuit breaker state for granular control
• Does not lose data - items stay in queue during circuit breaker open state

📦 Dead Letter Queue (DLQ)

• New SyncDeadLetterQueue helper class for persistent error tracking
• Saves complete item JSON for data recovery
• Captures full stack traces for debugging
• Stores error context (type, message, timestamps, retry count)
• Provides full traceability for administrators
• Enables manual resolution and recovery of application errors

🚦 Queue Management Improvements

• Non-blocking processing: Replaced all break statements with continue for independent item processing
• New _errorQueues Map tracks items with application errors (removed from outQueue after 3 retries)
• New _permanentErrorItemIds Set prevents re-injection of failed items after cleanup
• Periodic cleanup every 100 sync loops to prevent memory leaks
• "Second chance" logic: If user modifies a failed item locally, it automatically gets retried with fresh start

🔒 Data Loss Prevention Guarantees

• Network errors: Items stay in outQueue indefinitely with unlimited retries
• Application errors: Complete data preserved in DLQ (JSON + stack trace + context)
• Retry counters capped at 10,000 to prevent integer overflow
• Clean state management prevents data leakage between users
• clearSyncState() properly cleans all error management structures

Implementation Details

New Files

• lib/src/sync_error_classifier.dart: Error classification logic with SyncErrorType enum
• lib/src/sync_dead_letter_queue.dart: DLQ persistence helper with saveFailedItem() method

Modified Files

• lib/src/sync_manager.dart:
  • Added error management data structures (_errorQueues, _permanentErrorItemIds, _retryCounters, _circuitBreakers)
  • Modified _processOutgoing() to handle errors individually with classification
  • Updated _pushLocalChangesToOutQueue() to check permanent error tracking
  • Enhanced _cleanupErrorQueues() with periodic cleanup
  • Fixed clearSyncState() to clean all error structures
  • Fixed dispose() to properly clean up
• lib/syncable.dart: Export new classes

Database Schema Requirements

Consuming applications must implement a sync_dead_letter_queue table. Example schema:

@DataClassName('SyncDeadLetterEntry')
class SyncDeadLetterQueueTable extends Table {
  TextColumn get id => text()();
  TextColumn get syncTableName => text().named('table_name')();
  TextColumn get itemJson => text().named('item_json')();
  TextColumn get errorType => text().named('error_type')();
  TextColumn get errorMessage => text().named('error_message')();
  IntColumn get retryCount => integer().named('retry_count')();
  IntColumn get firstErrorAt => integer().named('first_error_at')();
  IntColumn get lastErrorAt => integer().named('last_error_at')();
  TextColumn get lastStackTrace => text().named('last_stack_trace').nullable()();
  TextColumn get status => text().withDefault(const Constant('pending'))();
  
  @override
  Set<Column> get primaryKey => {id};
}

Use Case Example

Scenario 1: User Offline for Days

// User creates item while offline
final item = await database.createCompetition(...);

// SyncManager detects network error (no internet)
// ✅ Item stays in outQueue
// ✅ Retries indefinitely with circuit breaker protection
// ✅ When network returns after 3 days, item syncs successfully
// ✅ NO DATA LOSS

Scenario 2: Application Error (e.g., Constraint Violation)

// Item fails to sync due to application error
// Attempt 1: Error logged, retry counter = 1
// Attempt 2: Error logged, retry counter = 2
// Attempt 3: Error logged, retry counter = 3
// ✅ Item moved to errorQueue and removed from outQueue
// ✅ Full details saved to DLQ:
//    - Complete item JSON (admin can recover data)
//    - Full stack trace (developer can debug)
//    - Error type, message, timestamps
// ✅ Other items continue processing (non-blocking)
// ✅ If user modifies item locally → gets "second chance" automatically

Breaking Changes

None - This is fully backward compatible:

• DLQ is optional (nullable _deadLetterQueue?)
• Only initialized if enableSync() receives a database with SyncDeadLetterQueueTable
• Existing code continues to work without changes
• New features are opt-in via DLQ table implementation

Bug Fixes During Implementation

During implementation and testing, 5 bugs were identified and fixed:

1. DLQ initialization: Made nullable with proper null-safety checks
2. Memory leak: Added periodic cleanup of errorQueues
3. Integer overflow: Capped retry counters at 10,000
4. Incomplete cleanup: Fixed clearSyncState() to clean all structures
5. Item re-injection: Added permanent tracking to prevent failed items from re-entering queue

Testing

• ✅ Verified with 0 compilation errors
• ✅ All 5 identified bugs have been fixed
• ✅ Tested scenarios:
  • Network errors with unlimited retries
  • Application errors moving to DLQ after 3 attempts
  • Circuit breaker opening and auto-reset
  • Cleanup preventing memory leaks
  • User switching with clean state
  • "Second chance" logic when user modifies failed items

Migration Guide

To use the DLQ feature in your consuming app:

1. Add the table to your database:

@DriftDatabase(tables: [
  // ... your existing tables ...
  SyncDeadLetterQueueTable,
])

2. Increment schema version and add migration:

@override
int get schemaVersion => 2;

@override
MigrationStrategy get migration => MigrationStrategy(
  onUpgrade: (Migrator m, int from, int to) async {
    if (from == 1 && to == 2) {
      await m.createTable(syncDeadLetterQueueTable);
    }
  },
);

3. That's it! The SyncManager will automatically detect and use the DLQ table.

Documentation

This PR includes:

• Inline code documentation with emoji markers (🔴 NEW:)
• Detailed commit message with implementation notes
• Usage examples in this PR description
• Database schema requirements