@push.rocks/smartmta 8.0.1 → 8.1.1

package/ts/mail/delivery/classes.delivery.queue.ts

@@ -40,7 +40,8 @@ export interface IRecipientPermanentFailure {
 
 export interface IBounceOperation {
   operationId: string;
-  kind: 'smtpFailure';
+  kind: 'smtpFailure' | 'deliveryFailure';
+  failureClass?: 'localTopology' | 'transport';
   recipient: string;
   normalizedRecipient: string;
   smtpCode: number;
@@ -57,8 +58,14 @@ export interface IBounceOperation {
  */
 export interface IQueueItem {
   id: string;
+  /** Stable caller-supplied key used to make enqueue replay-safe. */
+  idempotencyKey?: string;
+  /** Fingerprint of the exact work associated with the idempotency key. */
+  idempotencyFingerprint?: string;
   processingMode: EmailProcessingMode;
   processingResult: Email;
+  /** Materialized attachment count for queue/detail consumers. */
+  attachmentCount?: number;
   route?: IEmailRoute;
   status: QueueItemStatus;
   attempts: number;
@@ -83,9 +90,12 @@ interface IStoredEmail {
 interface IStoredQueueItemV1 {
   schemaVersion: 1;
   id: string;
+  idempotencyKey?: string;
+  idempotencyFingerprint?: string;
   processingMode: EmailProcessingMode;
   processingResult: IStoredEmail;
   route?: IEmailRoute;
+  attachmentCount?: number;
   status: QueueItemStatus;
   attempts: number;
   nextAttempt: number;
@@ -117,9 +127,25 @@ type IStoredQueueItem = IStoredQueueItemV1 | IStoredQueueItemV2;
 
 type TQueueLifecycleState = 'new' | 'initialized' | 'shutting-down' | 'closed';
 
+interface IStoredQueueIdempotencyTombstone {
+  schemaVersion: 1;
+  id: string;
+  idempotencyKey: string;
+  idempotencyFingerprint: string;
+  expiresAt: number;
+}
+
+export const ACCEPTED_ENVELOPE_IDEMPOTENCY_RETENTION_MS = 31 * 24 * 60 * 60 * 1000;
+const QUEUE_IDEMPOTENCY_TOMBSTONE_CLEANUP_LIMIT = 256;
+
 export interface IQueueFailureOptions {
   /** Unknown failures default to retryable so temporary internal faults do not lose mail. */
   retryable?: boolean;
+  /** Durable work created atomically when unresolved recipients become terminal. */
+  terminalFailure?: {
+    failureClass: 'localTopology' | 'transport';
+    smtpCode?: number;
+  };
 }
 
 export interface IQueueFailureTransition {
@@ -150,6 +176,15 @@ export interface IQueueOptions {
   maxRetryDelay?: number;
 }
 
+export interface IQueueEnqueueOptions {
+  /** Stable key that resolves to one deterministic queue item id. */
+  idempotencyKey?: string;
+  /** Required with idempotencyKey to reject reuse for different work. */
+  idempotencyFingerprint?: string;
+  /** Fail closed unless the queue is backed by managed blob storage. */
+  requireDurable?: boolean;
+}
+
 /**
  * Queue statistics interface
  */
@@ -216,6 +251,11 @@ export class UnifiedDeliveryQueue extends EventEmitter {
   private totalProcessed: number = 0;
   private ownsManagedPrefix = false;
   private lifecycleState: TQueueLifecycleState = 'new';
+  private readonly idempotentEnqueueFlights = new Map<string, {
+    fingerprint: string;
+    promise: Promise<string>;
+  }>();
+  private idempotencyTombstoneCleanupCursor?: string;
   
   /**
    * Create a new unified delivery queue
@@ -270,6 +310,143 @@ export class UnifiedDeliveryQueue extends EventEmitter {
     }
   }
 
+  /** Whether queue entries are committed through caller-managed blob storage. */
+  public hasManagedStorage(): boolean {
+    return !!this.options.storageManager;
+  }
+
+  /** Whether managed storage can list a backend-bounded page of keys. */
+  public hasPaginatedManagedStorage(): boolean {
+    return typeof this.options.storageManager?.listPage === 'function';
+  }
+
+  private idempotentQueueId(idempotencyKey: string): string {
+    return `idempotent-${createHash('sha256')
+      .update('smartmta-queue-v1\0')
+      .update(idempotencyKey)
+      .digest('hex')}`;
+  }
+
+  private idempotencyTombstonePrefix(): string {
+    return `${this.options.storagePrefix.slice(0, -1)}.idempotency/`;
+  }
+
+  private idempotencyTombstoneKey(id: string): string {
+    return `${this.idempotencyTombstonePrefix()}${id}.json`;
+  }
+
+  private async readIdempotencyTombstone(
+    id: string,
+  ): Promise<IStoredQueueIdempotencyTombstone | null> {
+    const storageManager = this.options.storageManager;
+    if (!storageManager) return null;
+    const key = this.idempotencyTombstoneKey(id);
+    const value = await storageManager.get(key);
+    if (!value) return null;
+    const tombstone = this.parseIdempotencyTombstone(value, key, id);
+    if (tombstone.expiresAt <= Date.now()) {
+      await storageManager.delete(key);
+      return null;
+    }
+    return tombstone;
+  }
+
+  private parseIdempotencyTombstone(
+    value: Buffer,
+    key: string,
+    expectedId: string,
+  ): IStoredQueueIdempotencyTombstone {
+    let tombstone: IStoredQueueIdempotencyTombstone;
+    try {
+      tombstone = JSON.parse(value.toString('utf8')) as IStoredQueueIdempotencyTombstone;
+    } catch {
+      throw new Error(`Invalid queue idempotency tombstone at ${key}`);
+    }
+    if (
+      tombstone?.schemaVersion !== 1
+      || tombstone.id !== expectedId
+      || typeof tombstone.idempotencyKey !== 'string'
+      || !tombstone.idempotencyKey
+      || tombstone.idempotencyKey.length > 512
+      || this.idempotentQueueId(tombstone.idempotencyKey) !== expectedId
+      || typeof tombstone.idempotencyFingerprint !== 'string'
+      || !/^[a-f0-9]{64}$/.test(tombstone.idempotencyFingerprint)
+      || !Number.isFinite(tombstone.expiresAt)
+    ) {
+      throw new Error(`Invalid queue idempotency tombstone at ${key}`);
+    }
+    return tombstone;
+  }
+
+  private async persistIdempotencyTombstone(
+    id: string,
+    idempotencyKey: string,
+    idempotencyFingerprint: string,
+  ): Promise<void> {
+    const storageManager = this.options.storageManager;
+    if (!storageManager) return;
+    const tombstone: IStoredQueueIdempotencyTombstone = {
+      schemaVersion: 1,
+      id,
+      idempotencyKey,
+      idempotencyFingerprint,
+      expiresAt: Date.now() + ACCEPTED_ENVELOPE_IDEMPOTENCY_RETENTION_MS,
+    };
+    await storageManager.set(
+      this.idempotencyTombstoneKey(id),
+      Buffer.from(JSON.stringify(tombstone)),
+    );
+  }
+
+  private async cleanupExpiredIdempotencyTombstones(
+    limit = QUEUE_IDEMPOTENCY_TOMBSTONE_CLEANUP_LIMIT,
+  ): Promise<void> {
+    const storageManager = this.options.storageManager;
+    if (!storageManager?.listPage || limit < 1) return;
+    const prefix = this.idempotencyTombstonePrefix();
+    const page = await storageManager.listPage(prefix, {
+      limit,
+      ...(this.idempotencyTombstoneCleanupCursor
+        ? { continuationToken: this.idempotencyTombstoneCleanupCursor }
+        : {}),
+    });
+    if (
+      !page
+      || !Array.isArray(page.keys)
+      || page.keys.length > limit
+      || page.keys.some((key) => typeof key !== 'string' || !key.startsWith(prefix))
+      || new Set(page.keys).size !== page.keys.length
+      || (
+        page.continuationToken !== undefined
+        && (
+          typeof page.continuationToken !== 'string'
+          || page.continuationToken.length === 0
+          || page.continuationToken === this.idempotencyTombstoneCleanupCursor
+        )
+      )
+    ) {
+      throw new Error('Invalid paginated queue idempotency tombstone listing');
+    }
+    this.idempotencyTombstoneCleanupCursor = page.continuationToken;
+    const now = Date.now();
+    for (const key of page.keys) {
+      const value = await storageManager.get(key);
+      if (!value) continue;
+      try {
+        if (!key.endsWith('.json')) {
+          throw new Error(`Invalid queue idempotency tombstone key: ${key}`);
+        }
+        const id = key.slice(prefix.length, -'.json'.length);
+        const tombstone = this.parseIdempotencyTombstone(value, key, id);
+        if (tombstone.expiresAt <= now) {
+          await storageManager.delete(key);
+        }
+      } catch {
+        await storageManager.delete(key);
+      }
+    }
+  }
+
   private createInitialRecipientStates(email: Email): IRecipientDeliveryState[] {
     const byRecipient = new Map<string, IRecipientDeliveryState>();
     const now = new Date();
@@ -286,12 +463,16 @@ export class UnifiedDeliveryQueue extends EventEmitter {
     return [...byRecipient.values()];
   }
 
-  private createBounceOperationId(itemId: string, normalizedRecipient: string): string {
+  private createBounceOperationId(
+    itemId: string,
+    normalizedRecipient: string,
+    kind: IBounceOperation['kind'] = 'smtpFailure',
+  ): string {
     return createHash('sha256')
       .update(itemId)
       .update('\0')
       .update(normalizedRecipient)
-      .update('\0smtpFailure')
+      .update(`\0${kind}`)
       .digest('hex');
   }
   
@@ -448,25 +629,116 @@ export class UnifiedDeliveryQueue extends EventEmitter {
     processingResult: Email,
     mode: EmailProcessingMode,
     route?: IEmailRoute,
+    enqueueOptions: IQueueEnqueueOptions = {},
   ): Promise<string> {
     this.assertMutable();
     if (!(processingResult instanceof Email)) {
       throw new Error('Queue processingResult must be an Email instance');
     }
 
+    if (enqueueOptions.requireDurable && !this.options.storageManager) {
+      throw new Error('Durable idempotent enqueue requires managed queue storage');
+    }
+    if (
+      (enqueueOptions.idempotencyKey === undefined)
+      !== (enqueueOptions.idempotencyFingerprint === undefined)
+    ) {
+      throw new Error('Queue idempotencyKey and idempotencyFingerprint must be provided together');
+    }
+    if (enqueueOptions.idempotencyKey !== undefined) {
+      if (this.options.storageManager && !this.options.storageManager.listPage) {
+        throw new Error(
+          'Managed idempotent enqueue requires paginated managed queue storage',
+        );
+      }
+      if (!enqueueOptions.idempotencyKey || enqueueOptions.idempotencyKey.length > 512) {
+        throw new Error('Queue idempotencyKey must contain 1 to 512 characters');
+      }
+      if (!/^[a-f0-9]{64}$/.test(enqueueOptions.idempotencyFingerprint!)) {
+        throw new Error('Queue idempotencyFingerprint must be a lowercase SHA-256 digest');
+      }
+
+      const id = this.idempotentQueueId(enqueueOptions.idempotencyKey);
+      const existing = this.queue.get(id);
+      if (existing) {
+        if (
+          existing.idempotencyKey !== enqueueOptions.idempotencyKey
+          || existing.idempotencyFingerprint !== enqueueOptions.idempotencyFingerprint
+        ) {
+          throw new Error(`Queue idempotency key collision for ${id}`);
+        }
+        return id;
+      }
+
+      const activeFlight = this.idempotentEnqueueFlights.get(id);
+      if (activeFlight) {
+        if (activeFlight.fingerprint !== enqueueOptions.idempotencyFingerprint) {
+          throw new Error(`Queue idempotency key collision for ${id}`);
+        }
+        return activeFlight.promise;
+      }
+      const flight = (async () => {
+        const tombstone = await this.readIdempotencyTombstone(id);
+        if (tombstone) {
+          if (
+            tombstone.idempotencyKey !== enqueueOptions.idempotencyKey
+            || tombstone.idempotencyFingerprint !== enqueueOptions.idempotencyFingerprint
+          ) {
+            throw new Error(`Queue idempotency key collision for ${id}`);
+          }
+          return id;
+        }
+        return this.enqueueNew(processingResult, mode, route, {
+          id,
+          idempotencyKey: enqueueOptions.idempotencyKey!,
+          idempotencyFingerprint: enqueueOptions.idempotencyFingerprint!,
+        });
+      })();
+      this.idempotentEnqueueFlights.set(id, {
+        fingerprint: enqueueOptions.idempotencyFingerprint!,
+        promise: flight,
+      });
+      try {
+        return await flight;
+      } finally {
+        if (this.idempotentEnqueueFlights.get(id)?.promise === flight) {
+          this.idempotentEnqueueFlights.delete(id);
+        }
+      }
+    }
+
+    return this.enqueueNew(processingResult, mode, route);
+  }
+
+  private async enqueueNew(
+    processingResult: Email,
+    mode: EmailProcessingMode,
+    route?: IEmailRoute,
+    idempotency?: {
+      id: string;
+      idempotencyKey: string;
+      idempotencyFingerprint: string;
+    },
+  ): Promise<string> {
     // Check if queue is full
     if (this.queue.size >= this.options.maxQueueSize) {
       throw new Error('Queue is full');
     }
     
     // Generate a unique ID
-    const id = `${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;
+    const id = idempotency?.id
+      || `${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;
     
     // Create queue item
     const item: IQueueItem = {
       id,
+      ...(idempotency ? {
+        idempotencyKey: idempotency.idempotencyKey,
+        idempotencyFingerprint: idempotency.idempotencyFingerprint,
+      } : {}),
       processingMode: mode,
       processingResult,
+      attachmentCount: processingResult.attachments.length,
       route,
       status: 'pending',
       attempts: 0,
@@ -482,6 +754,13 @@ export class UnifiedDeliveryQueue extends EventEmitter {
     
     // Commit durable state before exposing the item in memory or emitting acceptance.
     await this.persistItem(item);
+    if (idempotency) {
+      await this.persistIdempotencyTombstone(
+        id,
+        idempotency.idempotencyKey,
+        idempotency.idempotencyFingerprint,
+      );
+    }
     this.queue.set(id, item);
     
     // Update statistics
@@ -638,9 +917,55 @@ export class UnifiedDeliveryQueue extends EventEmitter {
     } else {
       // Mark as permanently failed
       await this.applyPersistedMutation(item, (updatedItem) => {
+        const now = new Date();
         updatedItem.status = 'failed';
         updatedItem.lastError = error;
-        updatedItem.updatedAt = new Date();
+        updatedItem.updatedAt = now;
+
+        if (optionsArg.terminalFailure) {
+          const states = updatedItem.recipientStates || this.createInitialRecipientStates(
+            updatedItem.processingResult,
+          );
+          const terminal = new Set(updatedItem.terminalRecipients || []);
+          const operations = updatedItem.bounceOperations || [];
+          const operationIds = new Set(operations.map((operation) => operation.operationId));
+          const requestedCode = optionsArg.terminalFailure.smtpCode;
+          const smtpCode = Number.isInteger(requestedCode) && requestedCode! >= 500
+            ? requestedCode!
+            : 554;
+
+          for (const state of states) {
+            if (state.state !== 'unresolved') continue;
+            state.state = 'permanentFailure';
+            state.smtpCode = smtpCode;
+            state.smtpResponse = error;
+            state.updatedAt = now;
+            terminal.add(state.normalizedRecipient);
+
+            const operationId = this.createBounceOperationId(
+              updatedItem.id,
+              state.normalizedRecipient,
+              'deliveryFailure',
+            );
+            if (operationIds.has(operationId)) continue;
+            operations.push({
+              operationId,
+              kind: 'deliveryFailure',
+              failureClass: optionsArg.terminalFailure.failureClass,
+              recipient: state.recipient,
+              normalizedRecipient: state.normalizedRecipient,
+              smtpCode,
+              smtpResponse: error,
+              state: 'pending',
+              attempts: 0,
+              nextAttempt: now,
+            });
+            operationIds.add(operationId);
+          }
+          updatedItem.recipientStates = states;
+          updatedItem.terminalRecipients = [...terminal];
+          updatedItem.bounceOperations = operations;
+        }
       });
       
       // Update statistics
@@ -811,12 +1136,46 @@ export class UnifiedDeliveryQueue extends EventEmitter {
   /** Includes terminal queue items because bounce work outlives delivery status. */
   public listPendingBounceOperations(
     now: Date = new Date(),
+    limitArg = 100,
   ): Array<{ itemId: string; operation: IBounceOperation }> {
     const result: Array<{ itemId: string; operation: IBounceOperation }> = [];
+    const limit = Math.max(0, Math.min(Math.trunc(limitArg), 100));
+    if (limit === 0) return result;
+    for (const item of this.queue.values()) {
+      for (const operation of item.bounceOperations || []) {
+        if (
+          operation.kind === 'smtpFailure'
+          && operation.state === 'pending'
+          && operation.nextAttempt <= now
+        ) {
+          result.push({ itemId: item.id, operation: { ...operation } });
+          if (result.length >= limit) return result;
+        }
+      }
+    }
+    return result;
+  }
+
+  /** Durable terminal-delivery notices. These never enter SMTP recipient suppression. */
+  public listPendingDeliveryFailureOperations(
+    now: Date = new Date(),
+    limitArg = 100,
+  ): Array<{
+    itemId: string;
+    operation: IBounceOperation;
+  }> {
+    const result: Array<{ itemId: string; operation: IBounceOperation }> = [];
+    const limit = Math.max(0, Math.min(Math.trunc(limitArg), 100));
+    if (limit === 0) return result;
     for (const item of this.queue.values()) {
       for (const operation of item.bounceOperations || []) {
-        if (operation.state === 'pending' && operation.nextAttempt <= now) {
+        if (
+          operation.kind === 'deliveryFailure'
+          && operation.state === 'pending'
+          && operation.nextAttempt <= now
+        ) {
           result.push({ itemId: item.id, operation: { ...operation } });
+          if (result.length >= limit) return result;
         }
       }
     }
@@ -884,6 +1243,13 @@ export class UnifiedDeliveryQueue extends EventEmitter {
       return false;
     }
     
+    if (item.idempotencyKey && item.idempotencyFingerprint) {
+      await this.persistIdempotencyTombstone(
+        item.id,
+        item.idempotencyKey,
+        item.idempotencyFingerprint,
+      );
+    }
     // Delete durable state before making the removal visible in memory.
     await this.removeItemFromStorage(id);
     this.queue.delete(id);
@@ -914,12 +1280,17 @@ export class UnifiedDeliveryQueue extends EventEmitter {
     return {
       schemaVersion: 2,
       id: item.id,
+      ...(item.idempotencyKey !== undefined ? {
+        idempotencyKey: item.idempotencyKey,
+        idempotencyFingerprint: item.idempotencyFingerprint,
+      } : {}),
       processingMode: item.processingMode,
       processingResult: {
         options: item.processingResult.toEmailOptions(),
         messageId: item.processingResult.getMessageId(),
         envelopeFrom: item.processingResult.getEnvelopeFrom(),
       },
+      attachmentCount: item.attachmentCount ?? item.processingResult.attachments.length,
       ...(item.route ? { route: item.route } : {}),
       status: item.status,
       attempts: item.attempts,
@@ -986,6 +1357,27 @@ export class UnifiedDeliveryQueue extends EventEmitter {
     if (!parsed || typeof parsed !== 'object' || typeof parsed.id !== 'string' || !parsed.id) {
       throw new Error(`Invalid managed queue item at ${key}: missing id`);
     }
+    if (
+      parsed.idempotencyKey !== undefined
+      && (
+        typeof parsed.idempotencyKey !== 'string'
+        || !parsed.idempotencyKey
+        || parsed.idempotencyKey.length > 512
+        || typeof parsed.idempotencyFingerprint !== 'string'
+        || !/^[a-f0-9]{64}$/.test(parsed.idempotencyFingerprint)
+      )
+    ) {
+      throw new Error(`Invalid managed queue item at ${key}: invalid idempotency metadata`);
+    }
+    if (parsed.idempotencyKey === undefined && parsed.idempotencyFingerprint !== undefined) {
+      throw new Error(`Invalid managed queue item at ${key}: orphaned idempotency fingerprint`);
+    }
+    if (parsed.idempotencyKey !== undefined) {
+      const expectedId = this.idempotentQueueId(parsed.idempotencyKey);
+      if (parsed.id !== expectedId) {
+        throw new Error(`Invalid managed queue item at ${key}: idempotency id mismatch`);
+      }
+    }
     if (parsed.schemaVersion !== 1 && parsed.schemaVersion !== 2) {
       throw new Error(`Invalid managed queue item at ${key}: unsupported schema version`);
     }
@@ -1048,7 +1440,11 @@ export class UnifiedDeliveryQueue extends EventEmitter {
           return !(
             typeof operation.operationId === 'string'
             && operation.operationId.length > 0
-            && operation.kind === 'smtpFailure'
+            && ['smtpFailure', 'deliveryFailure'].includes(operation.kind as string)
+            && (
+              operation.failureClass === undefined
+              || ['localTopology', 'transport'].includes(operation.failureClass as string)
+            )
             && typeof operation.recipient === 'string'
             && typeof operation.normalizedRecipient === 'string'
             && operation.normalizedRecipient === operation.recipient.trim().toLowerCase()
@@ -1102,6 +1498,19 @@ export class UnifiedDeliveryQueue extends EventEmitter {
           entry.responseCode === undefined
           || (Number.isInteger(entry.responseCode) && (entry.responseCode as number) >= 100)
         )
+        && (
+          entry.transferStats === undefined
+          || (
+            Boolean(entry.transferStats)
+            && typeof entry.transferStats === 'object'
+            && Number.isSafeInteger((entry.transferStats as Record<string, unknown>).bytes)
+            && ((entry.transferStats as Record<string, number>).bytes >= 0)
+            && Number.isSafeInteger((entry.transferStats as Record<string, unknown>).chunks)
+            && ((entry.transferStats as Record<string, number>).chunks >= 0)
+            && Number.isSafeInteger((entry.transferStats as Record<string, unknown>).durationMs)
+            && ((entry.transferStats as Record<string, number>).durationMs >= 0)
+          )
+        )
       );
     };
     const isValidTransaction = (value: unknown): boolean => {
@@ -1189,6 +1598,13 @@ export class UnifiedDeliveryQueue extends EventEmitter {
       throw new Error(`Invalid managed queue item at ${key}: invalid email payload`);
     }
 
+    if (
+      parsed.attachmentCount !== undefined
+      && (!Number.isSafeInteger(parsed.attachmentCount) || parsed.attachmentCount < 0)
+    ) {
+      throw new Error(`Invalid managed queue item at ${key}: invalid attachment count`);
+    }
+
     const storedOptions = parsed.processingResult.options as IEmailOptions;
     if (storedOptions.attachments !== undefined) {
       if (!Array.isArray(storedOptions.attachments)) {
@@ -1243,8 +1659,13 @@ export class UnifiedDeliveryQueue extends EventEmitter {
 
     return {
       id: parsed.id,
+      ...(parsed.idempotencyKey !== undefined ? {
+        idempotencyKey: parsed.idempotencyKey,
+        idempotencyFingerprint: parsed.idempotencyFingerprint,
+      } : {}),
       processingMode: parsed.processingMode,
       processingResult,
+      attachmentCount: parsed.attachmentCount ?? processingResult.attachments.length,
       ...(parsed.route ? { route: parsed.route as IEmailRoute } : {}),
       status: parsed.status,
       attempts: parsed.attempts,
@@ -1431,6 +1852,7 @@ export class UnifiedDeliveryQueue extends EventEmitter {
     for (const id of idsToRemove) {
       await this.removeItem(id);
     }
+    await this.cleanupExpiredIdempotencyTombstones();
 
     if (idsToRemove.length > 0) {
       logger.log('info', `Cleaned up ${idsToRemove.length} old items from delivery queue`);