Add infrastructure for sending SMS via AWS SNS

Summary:
Ref T920. Ref T13235. This adds a `Future`, similar to `TwilioFuture`, for interacting with Amazon's SNS service.

Also updates the documentation.

Also makes the code consistent with the documentation by accepting a `media` argument.

Test Plan: Clicked the "send test message" button from the Settings UI.

Reviewers: epriestley

Reviewed By: epriestley

Subscribers: Korvin

Maniphest Tasks: T13235, T920

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

src/__phutil_library_map__.php

@@ -2083,6 +2083,7 @@ phutil_register_library_map(array(
     'PhabricatorAjaxRequestExceptionHandler' => 'aphront/handler/PhabricatorAjaxRequestExceptionHandler.php',
     'PhabricatorAlmanacApplication' => 'applications/almanac/application/PhabricatorAlmanacApplication.php',
     'PhabricatorAmazonAuthProvider' => 'applications/auth/provider/PhabricatorAmazonAuthProvider.php',
+    'PhabricatorAmazonSNSFuture' => 'applications/metamta/future/PhabricatorAmazonSNSFuture.php',
     'PhabricatorAnchorView' => 'view/layout/PhabricatorAnchorView.php',
     'PhabricatorAphlictManagementDebugWorkflow' => 'applications/aphlict/management/PhabricatorAphlictManagementDebugWorkflow.php',
     'PhabricatorAphlictManagementNotifyWorkflow' => 'applications/aphlict/management/PhabricatorAphlictManagementNotifyWorkflow.php',
@@ -3425,6 +3426,7 @@ phutil_register_library_map(array(
     'PhabricatorMacroViewController' => 'applications/macro/controller/PhabricatorMacroViewController.php',
     'PhabricatorMailAdapter' => 'applications/metamta/adapter/PhabricatorMailAdapter.php',
     'PhabricatorMailAmazonSESAdapter' => 'applications/metamta/adapter/PhabricatorMailAmazonSESAdapter.php',
+    'PhabricatorMailAmazonSNSAdapter' => 'applications/metamta/adapter/PhabricatorMailAmazonSNSAdapter.php',
     'PhabricatorMailAttachment' => 'applications/metamta/message/PhabricatorMailAttachment.php',
     'PhabricatorMailConfigTestCase' => 'applications/metamta/storage/__tests__/PhabricatorMailConfigTestCase.php',
     'PhabricatorMailEmailEngine' => 'applications/metamta/engine/PhabricatorMailEmailEngine.php',
@@ -7773,6 +7775,7 @@ phutil_register_library_map(array(
     'PhabricatorAjaxRequestExceptionHandler' => 'PhabricatorRequestExceptionHandler',
     'PhabricatorAlmanacApplication' => 'PhabricatorApplication',
     'PhabricatorAmazonAuthProvider' => 'PhabricatorOAuth2AuthProvider',
+    'PhabricatorAmazonSNSFuture' => 'PhutilAWSFuture',
     'PhabricatorAnchorView' => 'AphrontView',
     'PhabricatorAphlictManagementDebugWorkflow' => 'PhabricatorAphlictManagementWorkflow',
     'PhabricatorAphlictManagementNotifyWorkflow' => 'PhabricatorAphlictManagementWorkflow',
@@ -9318,6 +9321,7 @@ phutil_register_library_map(array(
     'PhabricatorMacroViewController' => 'PhabricatorMacroController',
     'PhabricatorMailAdapter' => 'Phobject',
     'PhabricatorMailAmazonSESAdapter' => 'PhabricatorMailAdapter',
+    'PhabricatorMailAmazonSNSAdapter' => 'PhabricatorMailAdapter',
     'PhabricatorMailAttachment' => 'Phobject',
     'PhabricatorMailConfigTestCase' => 'PhabricatorTestCase',
     'PhabricatorMailEmailEngine' => 'PhabricatorMailMessageEngine',

src/applications/metamta/adapter/PhabricatorMailAmazonSNSAdapter.php

@@ -0,0 +1,63 @@
+<?php
+
+final class PhabricatorMailAmazonSNSAdapter
+  extends PhabricatorMailAdapter {
+
+  const ADAPTERTYPE = 'sns';
+
+  public function getSupportedMessageTypes() {
+    return array(
+      PhabricatorMailSMSMessage::MESSAGETYPE,
+    );
+  }
+
+  protected function validateOptions(array $options) {
+    PhutilTypeSpec::checkMap(
+      $options,
+      array(
+        'access-key' => 'string',
+        'secret-key' => 'string',
+        'endpoint' => 'string',
+        'region' => 'string',
+      ));
+  }
+
+  public function newDefaultOptions() {
+    return array(
+      'access-key' => null,
+      'secret-key' => null,
+      'endpoint' => null,
+      'region' => null,
+    );
+  }
+
+  public function sendMessage(PhabricatorMailExternalMessage $message) {
+    $access_key = $this->getOption('access-key');
+
+    $secret_key = $this->getOption('secret-key');
+    $secret_key = new PhutilOpaqueEnvelope($secret_key);
+
+    $endpoint = $this->getOption('endpoint');
+    $region = $this->getOption('region');
+
+    $to_number = $message->getToNumber();
+    $text_body = $message->getTextBody();
+
+    $params = array(
+      'Version' => '2010-03-31',
+      'Action' => 'Publish',
+      'PhoneNumber' => $to_number->toE164(),
+      'Message' => $text_body,
+    );
+
+    return id(new PhabricatorAmazonSNSFuture())
+      ->setParameters($params)
+      ->setEndpoint($endpoint)
+      ->setAccessKey($access_key)
+      ->setSecretKey($secret_key)
+      ->setRegion($region)
+      ->setTimeout(60)
+      ->resolve();
+  }
+
+}

src/applications/metamta/future/PhabricatorAmazonSNSFuture.php

@@ -0,0 +1,41 @@
+<?php
+
+final class PhabricatorAmazonSNSFuture extends PhutilAWSFuture {
+  private $parameters = array();
+  private $timeout;
+
+  public function setParameters($parameters) {
+    $this->parameters = $parameters;
+    return $this;
+  }
+
+  protected function getParameters() {
+    return $this->parameters;
+  }
+
+  public function getServiceName() {
+    return 'sns';
+  }
+
+  public function setTimeout($timeout) {
+    $this->timeout = $timeout;
+    return $this;
+  }
+
+  public function getTimeout() {
+    return $this->timeout;
+  }
+
+  protected function getProxiedFuture() {
+    $future = parent::getProxiedFuture();
+
+    $timeout = $this->getTimeout();
+    if ($timeout) {
+      $future->setTimeout($timeout);
+    }
+
+    return $future;
+
+  }
+
+}

src/docs/user/configuration/configuring_outbound_email.diviner

@@ -97,6 +97,7 @@ The `type` field can be used to select these third-party mailers:
   - `ses`: Use Amazon SES.
   - `sendgrid`: Use SendGrid.
   - `postmark`: Use Postmark.
+  - `sns`: Use Amazon SNS (only for sending SMS messages).
 
 It also supports these local mailers:
 
@@ -208,6 +209,15 @@ which "From" address to use by setting `metamta.default-address` in your
 config, then follow the Amazon SES verification process to verify it. You
 won't be able to send email until you do this!
 
+Mailer: Amazon SNS
+==================
+
+Amazon SNS is Amazon's cloud notification service. You can learn more at
+<http://aws.amazon.com/sns/>. Note that this mailer is only able to send
+SMS messages, not emails.
+
+To use this mailer, set `type` to `sns`, then configure the options similarly
+to the SES configuration above.
 
 Mailer: SendGrid
 ================

src/infrastructure/cluster/config/PhabricatorClusterMailersConfigType.php

@@ -45,6 +45,7 @@ final class PhabricatorClusterMailersConfigType
             'options' => 'optional wild',
             'inbound' => 'optional bool',
             'outbound' => 'optional bool',
+            'media' => 'optional list<string>',
           ));
       } catch (Exception $ex) {
         throw $this->newException(