@push.rocks/smartmta 8.1.0 → 8.2.0

package/ts/mail/routing/classes.email.action.executor.ts

@@ -30,6 +30,22 @@ export interface IActionExecutorDeps {
   deliveryQueue: UnifiedDeliveryQueue;
 }
 
+export interface IActionExecutionOptions {
+  /**
+   * Queue the action with a deterministic durable id instead of performing
+   * direct delivery. Used when replaying an already-accepted envelope.
+   */
+  durableQueue?: {
+    idempotencyKey: string;
+    fingerprint: string;
+  };
+}
+
+export interface IActionExecutionResult {
+  outcome: 'completed' | 'queued';
+  queueId?: string;
+}
+
 /**
  * Executes email routing actions (forward, process, deliver, reject)
  */
@@ -61,30 +77,45 @@ export class EmailActionExecutor {
     }
   }
 
-  async executeAction(action: IEmailAction, email: Email, context: IEmailContext): Promise<void> {
+  async executeAction(
+    action: IEmailAction,
+    email: Email,
+    context: IEmailContext,
+  ): Promise<void> {
+    await this.executeActionWithResult(action, email, context);
+  }
+
+  async executeActionWithResult(
+    action: IEmailAction,
+    email: Email,
+    context: IEmailContext,
+    options: IActionExecutionOptions = {},
+  ): Promise<IActionExecutionResult> {
     switch (action.type) {
       case 'forward':
-        await this.handleForwardAction(action, email, context);
-        break;
+        return this.handleForwardAction(action, email, context, options);
       case 'process':
-        await this.handleProcessAction(action, email, context);
-        break;
+        return this.handleProcessAction(action, email, context, options);
       case 'deliver':
-        await this.handleDeliverAction(action, email, context);
-        break;
+        return this.handleDeliverAction(action, email, context, options);
       case 'store':
         throw new Error(
           'Store actions require raw SMTP context and an awaited hooks.onAcceptEnvelope handler',
         );
       case 'reject':
         await this.handleRejectAction(action, email, context);
-        break;
+        throw new Error('Reject action unexpectedly returned');
       default:
         throw new Error(`Unknown action type: ${(action as any).type}`);
     }
   }
 
-  private async handleForwardAction(action: IEmailAction, email: Email, context: IEmailContext): Promise<void> {
+  private async handleForwardAction(
+    action: IEmailAction,
+    email: Email,
+    context: IEmailContext,
+    options: IActionExecutionOptions,
+  ): Promise<IActionExecutionResult> {
     if (!action.forward) {
       throw new Error('Forward action requires forward configuration');
     }
@@ -105,6 +136,20 @@ export class EmailActionExecutor {
     email.headers['X-Forwarded-To'] = email.to.join(', ');
     email.headers['X-Forwarded-Date'] = new Date().toISOString();
 
+    if (options.durableQueue) {
+      const queueId = await this.deps.deliveryQueue.enqueue(
+        email,
+        'forward',
+        context.session.matchedRoute!,
+        {
+          idempotencyKey: options.durableQueue.idempotencyKey,
+          idempotencyFingerprint: options.durableQueue.fingerprint,
+          requireDurable: true,
+        },
+      );
+      return { outcome: 'queued', queueId };
+    }
+
     try {
       // Send email via Rust SMTP client
       const result = await this.deps.sendOutboundEmail(host, port, email, {
@@ -128,6 +173,7 @@ export class EmailActionExecutor {
         },
         success: true
       }));
+      return { outcome: 'completed' };
     } catch (error) {
       const errorMessage = getErrorMessage(error);
       logger.log('error', `Failed to forward email: ${errorMessage}`);
@@ -172,7 +218,12 @@ export class EmailActionExecutor {
     }
   }
 
-  private async handleProcessAction(action: IEmailAction, email: Email, context: IEmailContext): Promise<void> {
+  private async handleProcessAction(
+    action: IEmailAction,
+    email: Email,
+    context: IEmailContext,
+    options: IActionExecutionOptions,
+  ): Promise<IActionExecutionResult> {
     logger.log('info', `Processing email with action options`);
 
     // Apply scanning if requested
@@ -182,18 +233,47 @@ export class EmailActionExecutor {
 
     // Queue for delivery
     const queue = action.process?.queue || 'normal';
-    await this.deps.deliveryQueue.enqueue(email, 'process', context.session.matchedRoute!);
+    const queueId = await this.deps.deliveryQueue.enqueue(
+      email,
+      'process',
+      context.session.matchedRoute!,
+      options.durableQueue
+        ? {
+            idempotencyKey: options.durableQueue.idempotencyKey,
+            idempotencyFingerprint: options.durableQueue.fingerprint,
+            requireDurable: true,
+          }
+        : {},
+    );
 
     logger.log('info', `Email queued for delivery in ${queue} queue`);
+    return { outcome: 'queued', queueId };
   }
 
-  private async handleDeliverAction(_action: IEmailAction, email: Email, context: IEmailContext): Promise<void> {
+  private async handleDeliverAction(
+    _action: IEmailAction,
+    email: Email,
+    context: IEmailContext,
+    options: IActionExecutionOptions,
+  ): Promise<IActionExecutionResult> {
     logger.log('info', `Delivering email locally`);
 
     // Queue for local delivery
-    await this.deps.deliveryQueue.enqueue(email, 'mta', context.session.matchedRoute!);
+    const queueId = await this.deps.deliveryQueue.enqueue(
+      email,
+      'mta',
+      context.session.matchedRoute!,
+      options.durableQueue
+        ? {
+            idempotencyKey: options.durableQueue.idempotencyKey,
+            idempotencyFingerprint: options.durableQueue.fingerprint,
+            requireDurable: true,
+          }
+        : {},
+    );
 
     logger.log('info', 'Email queued for local delivery');
+    return { outcome: 'queued', queueId };
   }
 
   private async handleRejectAction(action: IEmailAction, _email: Email, context: IEmailContext): Promise<void> {