Allow MetaMTA adapters to indicate that a mail is permanently undeliverable

Summary: Currently, adapters can only fail mail temporarily. Allow them to indicate a permanent failure by throwing a special exception.

Test Plan: Added and ran unit tests.

Reviewers: wez, btrahan

Reviewed By: btrahan

CC: aran

Differential Revision: https://secure.phabricator.com/D6847

src/__phutil_library_map__.php

@@ -1302,6 +1302,7 @@ phutil_register_library_map(array(
     'PhabricatorMetaMTAMailBodyTestCase' => 'applications/metamta/view/__tests__/PhabricatorMetaMTAMailBodyTestCase.php',
     'PhabricatorMetaMTAMailTestCase' => 'applications/metamta/storage/__tests__/PhabricatorMetaMTAMailTestCase.php',
     'PhabricatorMetaMTAMailingList' => 'applications/mailinglists/storage/PhabricatorMetaMTAMailingList.php',
+    'PhabricatorMetaMTAPermanentFailureException' => 'applications/metamta/exception/PhabricatorMetaMTAPermanentFailureException.php',
     'PhabricatorMetaMTAReceivedMail' => 'applications/metamta/storage/PhabricatorMetaMTAReceivedMail.php',
     'PhabricatorMetaMTAReceivedMailProcessingException' => 'applications/metamta/exception/PhabricatorMetaMTAReceivedMailProcessingException.php',
     'PhabricatorMetaMTAReceivedMailTestCase' => 'applications/metamta/storage/__tests__/PhabricatorMetaMTAReceivedMailTestCase.php',
@@ -3387,6 +3388,7 @@ phutil_register_library_map(array(
       0 => 'PhabricatorMetaMTADAO',
       1 => 'PhabricatorPolicyInterface',
     ),
+    'PhabricatorMetaMTAPermanentFailureException' => 'Exception',
     'PhabricatorMetaMTAReceivedMail' => 'PhabricatorMetaMTADAO',
     'PhabricatorMetaMTAReceivedMailProcessingException' => 'Exception',
     'PhabricatorMetaMTAReceivedMailTestCase' => 'PhabricatorTestCase',

src/applications/metamta/adapter/PhabricatorMailImplementationAdapter.php

@@ -18,6 +18,18 @@ abstract class PhabricatorMailImplementationAdapter {
    */
   abstract public function supportsMessageIDHeader();
 
+
+  /**
+   * Send the message. Generally, this means connecting to some service and
+   * handing data to it.
+   *
+   * If the adapter determines that the mail will never be deliverable, it
+   * should throw a @{class:PhabricatorMetaMTAPermanentFailureException}.
+   *
+   * For temporary failures, throw some other exception or return `false`.
+   *
+   * @return bool True on success.
+   */
   abstract public function send();
 
 }

src/applications/metamta/adapter/PhabricatorMailImplementationTestAdapter.php

@@ -79,6 +79,16 @@ final class PhabricatorMailImplementationTestAdapter
   }
 
   public function send() {
+    if (!empty($this->guts['fail-permanently'])) {
+      throw new PhabricatorMetaMTAPermanentFailureException(
+        'Unit Test (Permanent)');
+    }
+
+    if (!empty($this->guts['fail-temporarily'])) {
+      throw new Exception(
+        'Unit Test (Temporary)');
+    }
+
     $this->guts['did-send'] = true;
     return true;
   }
@@ -87,4 +97,14 @@ final class PhabricatorMailImplementationTestAdapter
     return $this->guts;
   }
 
+  public function setFailPermanently($fail) {
+    $this->guts['fail-permanently'] = $fail;
+    return $this;
+  }
+
+  public function setFailTemporarily($fail) {
+    $this->guts['fail-temporarily'] = $fail;
+    return $this;
+  }
+
 }

src/applications/metamta/exception/PhabricatorMetaMTAPermanentFailureException.php

@@ -0,0 +1,6 @@
+<?php
+
+final class PhabricatorMetaMTAPermanentFailureException
+  extends Exception {
+
+}

src/applications/metamta/storage/PhabricatorMetaMTAMail.php

@@ -627,6 +627,10 @@ final class PhabricatorMetaMTAMail extends PhabricatorMetaMTADAO {
       try {
         $ok = $mailer->send();
         $error = null;
+      } catch (PhabricatorMetaMTAPermanentFailureException $ex) {
+        $this->setStatus(self::STATUS_FAIL);
+        $this->setMessage($ex->getMessage());
+        return $this->save();
       } catch (Exception $ex) {
         $ok = false;
         $error = $ex->getMessage()."\n".$ex->getTraceAsString();

src/applications/metamta/storage/__tests__/PhabricatorMetaMTAMailTestCase.php

@@ -8,6 +8,46 @@ final class PhabricatorMetaMTAMailTestCase extends PhabricatorTestCase {
     );
   }
 
+  public function testMailSendFailures() {
+    $user = $this->generateNewTestUser();
+    $phid = $user->getPHID();
+
+
+    // Normally, the send should succeed.
+    $mail = new PhabricatorMetaMTAMail();
+    $mail->addTos(array($phid));
+
+    $mailer = new PhabricatorMailImplementationTestAdapter();
+    $mail->sendNow($force = true, $mailer);
+    $this->assertEqual(
+      PhabricatorMetaMTAMail::STATUS_SENT,
+      $mail->getStatus());
+
+
+    // When the mailer fails temporarily, the mail should remain queued.
+    $mail = new PhabricatorMetaMTAMail();
+    $mail->addTos(array($phid));
+
+    $mailer = new PhabricatorMailImplementationTestAdapter();
+    $mailer->setFailTemporarily(true);
+    $mail->sendNow($force = true, $mailer);
+    $this->assertEqual(
+      PhabricatorMetaMTAMail::STATUS_QUEUE,
+      $mail->getStatus());
+
+
+    // When the mailer fails permanently, the mail should be failed.
+    $mail = new PhabricatorMetaMTAMail();
+    $mail->addTos(array($phid));
+
+    $mailer = new PhabricatorMailImplementationTestAdapter();
+    $mailer->setFailPermanently(true);
+    $mail->sendNow($force = true, $mailer);
+    $this->assertEqual(
+      PhabricatorMetaMTAMail::STATUS_FAIL,
+      $mail->getStatus());
+  }
+
   public function testRecipients() {
     $user = $this->generateNewTestUser();
     $phid = $user->getPHID();