Additional backends

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## Version 0.8.1
+
+* **Multi-backend support added to VintaSend**:
+  * Added support for configuring one primary backend plus optional additional backends.
+  * Implemented primary-first write replication with best-effort propagation to additional backends.
+  * Added backend-targeted read operations with optional `backendIdentifier` parameters.
+  * Added backend management operations: `verifyNotificationSync`, `replicateNotification`, and `getBackendSyncStats`.
+  * Enhanced `migrateToBackend` with optional source backend selection.
+* **Documentation and examples**:
+  * Added multi-backend configuration section to README.
+  * Added `MULTI_BACKEND_MIGRATION.md` migration guide.
+  * Added `src/examples/multi-backend-example.ts` with setup, read-routing, and management operation examples.
+
 ## Version 0.7.1
 
 * Add `renderEmailTemplateFromContent` method to the VintaSend service, so users can preview older notifications by providing the template content at the time.

README.md

@@ -106,6 +106,59 @@ export function sendWelcomeEmail(userId: number) {
 } 
 ```
 
+## Multi-Backend Configuration
+
+VintaSend supports configuring multiple backends for redundancy, data distribution, and migration use cases.
+
+### Basic Setup
+
+```typescript
+import { VintaSendFactory } from 'vintasend';
+
+const vintasend = new VintaSendFactory<NotificationTypeConfig>().create({
+  adapters,
+  backend: primaryBackend,
+  additionalBackends: [replicaBackend],
+  logger,
+  contextGeneratorsMap,
+});
+```
+
+### How It Works
+
+- **Writes**: VintaSend writes to the primary backend first, then replicates to additional backends on a best-effort basis.
+- **Reads**: Read methods use the primary backend by default, but support optional backend targeting by identifier.
+
+```typescript
+// Read from primary backend (default)
+const notification = await vintasend.getNotification(notificationId);
+
+// Read from a specific backend
+const notificationFromReplica = await vintasend.getNotification(
+  notificationId,
+  false,
+  'replica-backend',
+);
+```
+
+### Backend Management Operations
+
+```typescript
+const report = await vintasend.verifyNotificationSync(notificationId);
+
+if (!report.synced) {
+  await vintasend.replicateNotification(notificationId);
+}
+
+const backendStats = await vintasend.getBackendSyncStats();
+```
+
+### Failure Handling
+
+- Primary backend failures fail the operation.
+- Additional backend replication failures are logged and do not fail the primary operation.
+- This keeps primary workflows available while still enabling redundancy.
+
 ## Attachment Support
 
 VintaSend supports file attachments for notifications with an extensible architecture that allows you to choose your preferred storage backend.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "vintasend",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "main": "dist/index.js",
   "files": [
     "dist"

src/services/__tests__/multi-backend-error-handling.test.ts

@@ -0,0 +1,219 @@
+import { VintaSendFactory } from '../../index';
+import type { DatabaseNotification, NotificationInput } from '../../types/notification';
+import type { BaseLogger } from '../loggers/base-logger';
+import type { BaseNotificationAdapter } from '../notification-adapters/base-notification-adapter';
+import type { BaseNotificationBackend } from '../notification-backends/base-notification-backend';
+import type { BaseEmailTemplateRenderer } from '../notification-template-renderers/base-email-template-renderer';
+
+type ContextGenerators = {
+  testContext: {
+    generate: (params: { userId: string }) => Promise<{ userId: string }>;
+  };
+};
+
+type Config = {
+  ContextMap: ContextGenerators;
+  NotificationIdType: string;
+  UserIdType: string;
+};
+
+type MockBackend = jest.Mocked<BaseNotificationBackend<Config>> & {
+  injectLogger: jest.Mock;
+  injectAttachmentManager: jest.Mock;
+  getBackendIdentifier: jest.Mock<string, []>;
+};
+
+const templateRenderer: jest.Mocked<BaseEmailTemplateRenderer<Config>> = {
+  render: jest.fn(),
+  renderFromTemplateContent: jest.fn(),
+};
+
+const logger: jest.Mocked<BaseLogger> = {
+  info: jest.fn(),
+  error: jest.fn(),
+  warn: jest.fn(),
+};
+
+// biome-ignore lint/suspicious/noExplicitAny: test adapter mock
+const adapter: jest.Mocked<BaseNotificationAdapter<any, Config>> = {
+  notificationType: 'EMAIL',
+  key: 'adapter-1',
+  enqueueNotifications: false,
+  send: jest.fn(),
+  injectBackend: jest.fn(),
+  injectLogger: jest.fn(),
+  backend: null,
+  templateRenderer,
+  logger,
+  supportsAttachments: false,
+  // biome-ignore lint/suspicious/noExplicitAny: test-only cast
+} as any;
+
+const contextGenerators: ContextGenerators = {
+  testContext: {
+    generate: jest.fn(),
+  },
+};
+
+function createMockBackend(identifier: string): MockBackend {
+  return {
+    persistNotification: jest.fn(),
+    persistNotificationUpdate: jest.fn(),
+    getAllFutureNotifications: jest.fn(),
+    getAllFutureNotificationsFromUser: jest.fn(),
+    getFutureNotificationsFromUser: jest.fn(),
+    getFutureNotifications: jest.fn(),
+    getAllPendingNotifications: jest.fn(),
+    getPendingNotifications: jest.fn(),
+    getNotification: jest.fn(),
+    markAsRead: jest.fn(),
+    filterAllInAppUnreadNotifications: jest.fn(),
+    cancelNotification: jest.fn(),
+    markAsSent: jest.fn(),
+    markAsFailed: jest.fn(),
+    storeAdapterAndContextUsed: jest.fn(),
+    getUserEmailFromNotification: jest.fn(),
+    filterInAppUnreadNotifications: jest.fn(),
+    filterNotifications: jest.fn(),
+    bulkPersistNotifications: jest.fn(),
+    getAllNotifications: jest.fn(),
+    getNotifications: jest.fn(),
+    persistOneOffNotification: jest.fn(),
+    persistOneOffNotificationUpdate: jest.fn(),
+    getOneOffNotification: jest.fn(),
+    getAllOneOffNotifications: jest.fn(),
+    getOneOffNotifications: jest.fn(),
+    storeAttachmentFileRecord: jest.fn(),
+    getAttachmentFileRecord: jest.fn(),
+    getAttachmentFile: jest.fn(),
+    findAttachmentFileByChecksum: jest.fn(),
+    deleteAttachmentFile: jest.fn(),
+    getOrphanedAttachmentFiles: jest.fn(),
+    getAttachments: jest.fn(),
+    deleteNotificationAttachment: jest.fn(),
+    injectLogger: jest.fn(),
+    injectAttachmentManager: jest.fn(),
+    getBackendIdentifier: jest.fn(() => identifier),
+  } as unknown as MockBackend;
+}
+
+describe('VintaSend multi-backend error handling (Phase 4)', () => {
+  const createNotificationInput: Omit<NotificationInput<Config>, 'id'> = {
+    userId: 'user-1',
+    notificationType: 'EMAIL',
+    title: 'Title',
+    bodyTemplate: 'body',
+    contextName: 'testContext',
+    contextParameters: { userId: 'user-1' },
+    sendAfter: new Date(Date.now() + 60_000),
+    subjectTemplate: 'subject',
+    extraParams: null,
+  };
+
+  const databaseNotification = {
+    ...createNotificationInput,
+    id: 'notif-1',
+    status: 'PENDING_SEND',
+    contextUsed: null,
+    adapterUsed: null,
+    sentAt: null,
+    readAt: null,
+    gitCommitSha: null,
+  } as DatabaseNotification<Config>;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    contextGenerators.testContext.generate = jest.fn().mockResolvedValue({ userId: 'user-1' });
+  });
+
+  it('continues when one additional backend replication fails', async () => {
+    const primaryBackend = createMockBackend('primary');
+    const failingReplica = createMockBackend('replica-a');
+    const healthyReplica = createMockBackend('replica-b');
+
+    primaryBackend.persistNotification.mockResolvedValue(databaseNotification);
+    failingReplica.persistNotification.mockRejectedValue(new Error('replication failed'));
+    healthyReplica.persistNotification.mockResolvedValue(databaseNotification);
+
+    const service = new VintaSendFactory<Config>().create({
+      adapters: [adapter],
+      backend: primaryBackend,
+      additionalBackends: [failingReplica, healthyReplica],
+      logger,
+      contextGeneratorsMap: contextGenerators,
+    });
+
+    const result = await service.createNotification(createNotificationInput);
+
+    expect(result.id).toBe('notif-1');
+    expect(healthyReplica.persistNotification).toHaveBeenCalledWith({
+      ...createNotificationInput,
+      id: 'notif-1',
+    });
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.stringContaining('Failed to replicate createNotification to backend replica-a'),
+    );
+  });
+
+  it('continues processing send path when additional backend markAsSent fails', async () => {
+    const primaryBackend = createMockBackend('primary');
+    const failingReplica = createMockBackend('replica-a');
+
+    adapter.send.mockResolvedValue();
+
+    primaryBackend.markAsSent.mockResolvedValue(databaseNotification);
+    failingReplica.markAsSent.mockRejectedValue(new Error('markAsSent failed'));
+
+    primaryBackend.storeAdapterAndContextUsed.mockResolvedValue();
+    failingReplica.storeAdapterAndContextUsed.mockResolvedValue();
+
+    const service = new VintaSendFactory<Config>().create({
+      adapters: [adapter],
+      backend: primaryBackend,
+      additionalBackends: [failingReplica],
+      logger,
+      contextGeneratorsMap: contextGenerators,
+    });
+
+    await expect(service.send(databaseNotification)).resolves.toBeUndefined();
+
+    expect(primaryBackend.markAsSent).toHaveBeenCalledWith('notif-1', true);
+    expect(failingReplica.markAsSent).toHaveBeenCalledWith('notif-1', true);
+    expect(primaryBackend.storeAdapterAndContextUsed).toHaveBeenCalled();
+    expect(failingReplica.storeAdapterAndContextUsed).toHaveBeenCalled();
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.stringContaining('Failed to replicate markAsSent to backend replica-a'),
+    );
+  });
+
+  it('logs all additional backend failures without failing operation', async () => {
+    const primaryBackend = createMockBackend('primary');
+    const replicaA = createMockBackend('replica-a');
+    const replicaB = createMockBackend('replica-b');
+
+    primaryBackend.markAsRead.mockResolvedValue({
+      ...databaseNotification,
+      status: 'SENT',
+      readAt: new Date(),
+    });
+    replicaA.markAsRead.mockRejectedValue(new Error('replica A fail'));
+    replicaB.markAsRead.mockRejectedValue(new Error('replica B fail'));
+
+    const service = new VintaSendFactory<Config>().create({
+      adapters: [adapter],
+      backend: primaryBackend,
+      additionalBackends: [replicaA, replicaB],
+      logger,
+      contextGeneratorsMap: contextGenerators,
+    });
+
+    await expect(service.markRead('notif-1')).resolves.toMatchObject({ id: 'notif-1' });
+
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.stringContaining('Failed to replicate markRead to backend replica-a'),
+    );
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.stringContaining('Failed to replicate markRead to backend replica-b'),
+    );
+  });
+});