feat: introduce AttachmentErrorHandler for custom error handling in attachment sync operations

- Added AttachmentErrorHandler interface to manage download, upload, and delete errors for attachments.
- Updated AttachmentQueue and SyncingService to utilize the new error handler.
- Enhanced tests to verify error handling behavior during attachment sync processes.

Author: Amine

…ages/attachments/src/SyncErrorHandler.ts …ttachments/src/AttachmentErrorHandler.tspackages/attachments/src/SyncErrorHandler.ts renamed to packages/attachments/src/AttachmentErrorHandler.ts packages/attachments/src/SyncErrorHandler.ts renamed to packages/attachments/src/AttachmentErrorHandler.ts

@@ -4,7 +4,7 @@ import { AttachmentRecord } from './Schema.js';
  * SyncErrorHandler provides custom error handling for attachment sync operations.
  * Implementations determine whether failed operations should be retried or archived.
  */
-export interface SyncErrorHandler {
+export interface AttachmentErrorHandler {
   /**
    * Handles a download error for a specific attachment.
    * @param attachment The attachment that failed to download

packages/attachments/src/AttachmentQueue.ts

@@ -6,6 +6,7 @@ import { ATTACHMENT_TABLE, AttachmentRecord, AttachmentState } from './Schema.js
 import { SyncingService } from './SyncingService.js';
 import { WatchedAttachmentItem } from './WatchedAttachmentItem.js';
 import { AttachmentService } from './AttachmentService.js';
+import { AttachmentErrorHandler } from './AttachmentErrorHandler.js';
 
 /**
  * AttachmentQueue manages the lifecycle and synchronization of attachments
@@ -81,7 +82,8 @@ export class AttachmentQueue {
     syncIntervalMs = 30 * 1000,
     syncThrottleDuration = DEFAULT_WATCH_THROTTLE_MS,
     downloadAttachments = true,
-    archivedCacheLimit = 100
+    archivedCacheLimit = 100,
+    errorHandler
   }: {
     db: AbstractPowerSyncDatabase;
     remoteStorage: RemoteStorageAdapter;
@@ -93,13 +95,14 @@ export class AttachmentQueue {
     syncThrottleDuration?: number;
     downloadAttachments?: boolean;
     archivedCacheLimit?: number;
+    errorHandler?: AttachmentErrorHandler;
   }) {
     this.context = new AttachmentContext(db, tableName, logger ?? db.logger);
     this.remoteStorage = remoteStorage;
     this.localStorage = localStorage;
     this.watchAttachments = watchAttachments;
     this.tableName = tableName;
-    this.syncingService = new SyncingService(this.context, localStorage, remoteStorage, logger ?? db.logger);
+    this.syncingService = new SyncingService(this.context, localStorage, remoteStorage, logger ?? db.logger, errorHandler);
     this.attachmentService = new AttachmentService(tableName, db);
     this.syncIntervalMs = syncIntervalMs;
     this.syncThrottleDuration = syncThrottleDuration;

packages/attachments/src/AttachmentService.ts

@@ -1,4 +1,4 @@
-import { AbstractPowerSyncDatabase, DEFAULT_WATCH_THROTTLE_MS, DifferentialWatchedQuery } from '@powersync/common';
+import { AbstractPowerSyncDatabase, DifferentialWatchedQuery } from '@powersync/common';
 import { AttachmentRecord, AttachmentState } from './Schema.js';
 
 /**

packages/attachments/src/SyncingService.ts

@@ -3,7 +3,7 @@ import { AttachmentContext } from './AttachmentContext.js';
 import { LocalStorageAdapter } from './LocalStorageAdapter.js';
 import { RemoteStorageAdapter } from './RemoteStorageAdapter.js';
 import { AttachmentRecord, AttachmentState } from './Schema.js';
-import { SyncErrorHandler } from './SyncErrorHandler.js';
+import { AttachmentErrorHandler } from './AttachmentErrorHandler.js';
 
 /**
  * Orchestrates attachment synchronization between local and remote storage.
@@ -14,14 +14,14 @@ export class SyncingService {
   localStorage: LocalStorageAdapter;
   remoteStorage: RemoteStorageAdapter;
   logger: ILogger;
-  errorHandler?: SyncErrorHandler;
+  errorHandler?: AttachmentErrorHandler;
 
   constructor(
     context: AttachmentContext,
     localStorage: LocalStorageAdapter,
     remoteStorage: RemoteStorageAdapter,
     logger: ILogger,
-    errorHandler?: SyncErrorHandler
+    errorHandler?: AttachmentErrorHandler
   ) {
     this.context = context;
     this.localStorage = localStorage;

packages/attachments/tests/attachments.test.ts

@@ -7,6 +7,7 @@ import { attachmentFromSql, AttachmentRecord, AttachmentState, AttachmentTable }
 import { RemoteStorageAdapter } from '../src/RemoteStorageAdapter.js';
 import { WatchedAttachmentItem } from '../src/WatchedAttachmentItem.js';
 import { NodeFileSystemAdapter } from '../src/storageAdapters/NodeFileSystemAdapter.js';
+import { AttachmentErrorHandler } from '../src/AttachmentErrorHandler.js';
 
 const MOCK_JPEG_U8A = [
   0xFF, 0xD8, 0xFF, 0xE0,
@@ -438,14 +439,50 @@ describe('attachment queue', () => {
     await queue.stopSync();
   })
 
-  it.todo('should skip failed download and retry it in the next sync', async () => {
+  it('should skip failed download and retry it in the next sync', async () => {
+    const mockErrorHandler = vi.fn().mockRejectedValue(false);
+    const errorHandler: AttachmentErrorHandler = {
+      onDeleteError: mockErrorHandler,
+      onDownloadError: mockErrorHandler,
+      onUploadError: mockErrorHandler,
+    }
+    const mockDownloadFile = vi.fn()
+    .mockRejectedValueOnce(new Error('Download failed'))
+    .mockResolvedValueOnce(createMockJpegBuffer());
+
+    const mockRemoteStorage: RemoteStorageAdapter = {
+      downloadFile: mockDownloadFile,
+      uploadFile: mockUploadFile,
+      deleteFile: mockDeleteFile
+    };
+
     // no error handling yet expose error handling
     const localeQueue = new AttachmentQueue({
       db: db,
       watchAttachments,
       remoteStorage: mockRemoteStorage,
       localStorage: mockLocalStorage,
       syncIntervalMs: INTERVAL_MILLISECONDS,
+      errorHandler,
     });
+
+    const id = await localeQueue.generateAttachmentId();
+
+    await localeQueue.startSync()
+
+    await db.execute(
+      'INSERT INTO users (id, name, email, photo_id) VALUES (uuid(), ?, ?, ?)',
+      ['testuser', 'testuser@journeyapps.com', id],
+    );
+
+    await waitForMatchCondition(
+      () => watchAttachmentsTable(),
+      (results) => results.some((r) => r.id === id && r.state === AttachmentState.SYNCED),
+      5
+    );
+
+    expect(mockErrorHandler).toHaveBeenCalledOnce();
+    expect(mockDownloadFile).toHaveBeenCalledTimes(2);
+
   })
 });