feat(db): add emailBounces table

Add a table to record all hard and soft bounces, and complaints, to a
given email address. Also add `POST /emailBounces` and `GET
/emailBounces/:email` to query for them.

Author: seanmonstar

docs/API.md

@@ -45,6 +45,7 @@ There are a number of methods that a DB storage backend should implement:
     * .createVerificationReminder(body)
     * .fetchReminders(body, query)
     * .deleteReminder(body)
+* Email Bounces
 * General
     * .ping()
     * .close()
@@ -493,4 +494,16 @@ Parameters:
   * uid : user id
   * type : type of reminder
 
+## .createEmailBounce(body) ##
+
+Record when an email bounce has occurred.
+
+Parameters:
+
+* body: (object)
+  * email: A string of the email address that bounced
+  * bounceType: The bounce type ([`'Permanent'`, `'Transient'`, `'Complaint'`])
+  * bounceSubType: The bounce sub type string
+
 (Ends)
+

fxa-auth-db-server/index.js

@@ -107,6 +107,9 @@ function createServer(db) {
   api.get('/securityEvents/:id/ip/:ipAddr', withParams(db.securityEvents))
   api.post('/securityEvents', withBodyAndQuery(db.createSecurityEvent))
 
+  api.get('/emailBounces/:email', op(req => db.fetchEmailBounces(req.params.email)))
+  api.post('/emailBounces', withBodyAndQuery(db.createEmailBounce))
+
   api.get('/emailRecord/:id', withIdAndBody(db.emailRecord))
   api.head('/emailRecord/:id', withIdAndBody(db.accountExists))
 

fxa-auth-db-server/test/backend/db_tests.js

@@ -6,8 +6,8 @@ var crypto = require('crypto')
 var base64url = require('base64url')
 var P = require('bluebird')
 
-var zeroBuffer16 = Buffer('00000000000000000000000000000000', 'hex')
-var zeroBuffer32 = Buffer('0000000000000000000000000000000000000000000000000000000000000000', 'hex')
+var zeroBuffer16 = Buffer.from('00000000000000000000000000000000', 'hex')
+var zeroBuffer32 = Buffer.from('0000000000000000000000000000000000000000000000000000000000000000', 'hex')
 var now = Date.now()
 
 function newUuid() {
@@ -1898,6 +1898,36 @@ module.exports = function(config, DB) {
           }
         )
 
+        test(
+          'emailBounces',
+          t => {
+            t.plan(4)
+            const data = {
+              email: ('' + Math.random()).substr(2) + '@email.bounces',
+              bounceType: 'Permanent',
+              bounceSubType: 'NoEmail'
+            }
+            db.createEmailBounce(data)
+              .then(() => {
+                return db.fetchEmailBounces(data.email)
+              })
+              .then(bounces => {
+                t.equal(bounces.length, 1)
+                t.equal(bounces[0].email, data.email)
+                t.equal(bounces[0].bounceType, 1)
+                t.equal(bounces[0].bounceSubType, 3)
+
+              })
+              .done(
+                () => {
+                  t.end()
+                },
+                (err) => {
+                  t.fail(err)
+                }
+              )
+          }
+        )
 
         test(
           'teardown',

fxa-auth-db-server/test/backend/remote.js

@@ -1090,6 +1090,33 @@ module.exports = function(cfg, server) {
     }
   )
 
+  test(
+    'email bounces',
+    function (t) {
+      t.plan(8)
+      var email = Math.random() + '@email.bounces'
+      return client.postThen('/emailBounces', {
+        email: email,
+        bounceType: 'Permanent',
+        bounceSubType: 'NoEmail'
+      })
+        .then(
+          function (r) {
+            respOkEmpty(t, r)
+            return client.getThen('/emailBounces/' + email)
+          }
+        )
+        .then(
+          function (r) {
+            respOk(t, r)
+            t.equal(r.obj.length, 1)
+            t.equal(r.obj[0].email, email)
+            t.ok(r.obj[0].createdAt <= Date.now(), 'returns { createdAt: Number }')
+          }
+        )
+    }
+  )
+
   test(
     'GET an unknown path',
     function (t) {

lib/db/mem.js

@@ -2,9 +2,12 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
-var P = require('bluebird')
-var extend = require('util')._extend
-var ip = require('ip')
+'use strict'
+
+const P = require('bluebird')
+const extend = require('util')._extend
+const ip = require('ip')
+const dbUtil = require('./util')
 
 // our data stores
 var accounts = {}
@@ -18,6 +21,7 @@ var passwordForgotTokens = {}
 var reminders = {}
 var securityEvents = {}
 var unblockCodes = {}
+var emailBounces = {}
 
 var DEVICE_FIELDS = [
   'sessionTokenId',
@@ -891,6 +895,21 @@ module.exports = function (log, error) {
     return P.resolve({ createdAt: timestamp })
   }
 
+
+  Memory.prototype.createEmailBounce = function (data) {
+    let row = emailBounces[data.email] || (emailBounces[data.email] = [])
+    let bounce = extend({}, data)
+    bounce.createdAt = Date.now()
+    bounce.bounceType = dbUtil.mapEmailBounceType(bounce.bounceType)
+    bounce.bounceSubType = dbUtil.mapEmailBounceSubType(bounce.bounceSubType)
+    row.push(bounce)
+    return P.resolve({})
+  }
+
+  Memory.prototype.fetchEmailBounces = function(email) {
+    return P.resolve(emailBounces[email] || [])
+  }
+
   // UTILITY FUNCTIONS
 
   Memory.prototype.ping = function () {

lib/db/mysql.js

@@ -2,12 +2,15 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
-var crypto = require('crypto')
-var ip = require('ip')
-var mysql = require('mysql')
-var P = require('../promise')
+'use strict'
 
-var patch = require('./patch')
+const crypto = require('crypto')
+const ip = require('ip')
+const mysql = require('mysql')
+const P = require('../promise')
+
+const patch = require('./patch')
+const dbUtil = require('./util')
 
 // http://dev.mysql.com/doc/refman/5.5/en/error-messages-server.html
 const ER_TOO_MANY_CONNECTIONS = 1040
@@ -1072,5 +1075,22 @@ module.exports = function (log, error) {
       )
   }
 
+  const CREATE_EMAIL_BOUNCE = 'CALL createEmailBounce_1(?, ?, ?, ?)'
+  MySql.prototype.createEmailBounce = function (data) {
+    const args = [
+      data.email,
+      dbUtil.mapEmailBounceType(data.bounceType),
+      dbUtil.mapEmailBounceSubType(data.bounceSubType),
+      Date.now()
+    ]
+    return this.write(CREATE_EMAIL_BOUNCE, args)
+  }
+
+  const FETCH_EMAIL_BOUNCES = 'CALL fetchEmailBounces_1(?)'
+  MySql.prototype.fetchEmailBounces = function (email) {
+    return this.read(FETCH_EMAIL_BOUNCES, [email])
+      .then(result => result[0])
+  }
+
   return MySql
 }

lib/db/patch.js

@@ -4,4 +4,4 @@
 
 // The expected patch level of the database. Update if you add a new
 // patch in the ./schema/ directory.
-module.exports.level = 40
+module.exports.level = 41

lib/db/schema/patch-040-041.sql

@@ -0,0 +1,45 @@
+CREATE TABLE IF NOT EXISTS emailBounces (
+  email VARCHAR(255) NOT NULL,
+  bounceType TINYINT UNSIGNED NOT NULL,
+  bounceSubType TINYINT UNSIGNED NOT NULL,
+  createdAt BIGINT UNSIGNED NOT NULL,
+  PRIMARY KEY(email, createdAt)
+) ENGINE=InnoDB;
+
+CREATE PROCEDURE `createEmailBounce_1` (
+  IN inEmail VARCHAR(255),
+  IN inBounceType TINYINT UNSIGNED,
+  IN inBounceSubType TINYINT UNSIGNED,
+  IN inCreatedAt BIGINT UNSIGNED
+)
+BEGIN
+  INSERT INTO emailBounces(
+    email,
+    bounceType,
+    bounceSubType,
+    createdAt
+  )
+  VALUES(
+    inEmail,
+    inBounceType,
+    inBounceSubType,
+    inCreatedAt
+  );
+END;
+
+CREATE PROCEDURE `fetchEmailBounces_1` (
+  IN `inEmail` VARCHAR(255)
+)
+BEGIN
+  SELECT
+      email,
+      bounceType,
+      bounceSubType,
+      createdAt
+  FROM emailBounces
+  WHERE email = inEmail
+  ORDER BY createdAt DESC
+  LIMIT 20;
+END;
+
+UPDATE dbMetadata SET value = '41' WHERE name = 'schema-patch-level';

lib/db/schema/patch-041-040.sql

@@ -0,0 +1,8 @@
+-- Rollback; commented out to prevent accidental running
+-- in production.
+
+-- DROP TABLE `emailBounces`;
+-- DROP PROCEDURE `createEmailBounce_1`;
+-- DROP PROCEDURE `fetchEmailBounces_1`;
+
+-- UPDATE dbMetadata SET value = '40' WHERE name = 'schema-patch-level';

lib/db/util.js

@@ -0,0 +1,51 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+'use strict'
+
+
+const BOUNCE_TYPES = new Map([
+  ['__fxa__unmapped', 0], // a bounce type we don't yet recognize
+  ['Permanent', 1], // Hard
+  ['Transient', 2], // Soft
+  ['Complaint', 3]  // Complaint
+])
+
+const BOUNCE_SUB_TYPES = new Map([
+  ['__fxa__unmapped', 0], // a bounce type we don't yet recognize
+  ['Undetermined', 1],
+  ['General', 2],
+  ['NoEmail', 3],
+  ['Suppressed', 4],
+  ['MailboxFull', 5],
+  ['MessageTooLarge', 6],
+  ['ContentRejected', 7],
+  ['AttachmentRejected', 8],
+  ['abuse', 9],
+  ['auth-failure', 10],
+  ['fraud', 11],
+  ['not-spam', 12],
+  ['other', 13],
+  ['virus', 14]
+])
+
+module.exports = {
+
+  mapEmailBounceType(val) {
+    if (typeof val === 'number') {
+      return val
+    } else {
+      return BOUNCE_TYPES.get(val) || 0
+    }
+  },
+
+  mapEmailBounceSubType(val) {
+    if (typeof val === 'number') {
+      return val
+    } else {
+      return BOUNCE_SUB_TYPES.get(val) || 0
+    }
+  }
+
+}