Add allowGmailDots to EmailValidator

Author: RohanNagar

CHANGELOG.md

@@ -131,6 +131,23 @@ the `Email` object (similar to the `normalize()` method).
     "[email protected]" => "te*****@gm*****"
   ```
 
+
+### Support for Leading and Trailing Dots in the Local-Part (GMail Allowed)
+
+While technically disallowed under published RFCs, GMail considers email addresses that have
+local-parts that start with or end with a dot `.` character as valid. For example, GMail
+considers `[email protected]` valid, even though it is not actually valid according to RFC.
+
+JMail now gives you the option to consider these addresses valid as well. You must use an
+`EmailValidator` with the `allowGmailDots` rule added to it to allow these addresses to pass validation.
+
+```java
+EmailValidator validator = JMail.strictValidator()
+        .allowGmailDots();
+
+validator.isValid("[email protected]"); // returns true
+```
+
 ---
 ## 1.6.3
 

src/main/java/com/sanctionco/jmail/EmailValidator.java

@@ -48,13 +48,16 @@ public final class EmailValidator {
       = ValidationRules::requireAscii;
 
   private final Map<Predicate<Email>, FailureReason> validationPredicates;
+  private final boolean allowGmailDots;
 
-  EmailValidator(Map<Predicate<Email>, FailureReason> validationPredicates) {
+  EmailValidator(Map<Predicate<Email>, FailureReason> validationPredicates,
+                 boolean allowGmailDots) {
     this.validationPredicates = Collections.unmodifiableMap(validationPredicates);
+    this.allowGmailDots = allowGmailDots;
   }
 
   EmailValidator() {
-    this(new HashMap<>());
+    this(new HashMap<>(), false);
   }
 
   /**
@@ -77,7 +80,7 @@ public EmailValidator withRules(Map<Predicate<Email>, FailureReason> rules) {
     Map<Predicate<Email>, FailureReason> ruleMap = new HashMap<>(validationPredicates);
     ruleMap.putAll(rules);
 
-    return new EmailValidator(ruleMap);
+    return new EmailValidator(ruleMap, allowGmailDots);
   }
 
   /**
@@ -161,6 +164,23 @@ public EmailValidator withRule(Predicate<Email> rule, String failureReason) {
     return withRules(Collections.singletonMap(rule, new FailureReason(failureReason)));
   }
 
+  /**
+   * <p>Create a new {@code EmailValidator} (with all rules from the current instance) that
+   * allows email addresses to have a local-part that either starts with or ends with a dot
+   * {@code .} character.</p>
+   *
+   * <p>While not allowed according to RFC, a leading or trailing dot character in the local-part
+   * <strong>is allowed</strong> by GMail, hence the naming of this method.</p>
+   *
+   * <p>For example, {@code "[email protected]"} would be considered valid if you use the
+   * {@code EmailValidator} returned by this method.</p>
+   *
+   * @return the new {@code EmailValidator} instance
+   */
+  public EmailValidator allowGmailDots() {
+    return new EmailValidator(this.validationPredicates, true);
+  }
+
   /**
    * <p>Create a new {@code EmailValidator} with all rules from the current instance and the
    * {@link ValidationRules#disallowIpDomain(Email)} rule.
@@ -341,7 +361,8 @@ public EmailValidator requireAscii() {
    * @return the result of the validation
    */
   public boolean isValid(String email) {
-    return JMail.tryParse(email)
+    return JMail.validate(email, allowGmailDots)
+        .getEmail()
         .filter(e -> !testPredicates(e).isPresent())
         .isPresent();
   }
@@ -383,7 +404,7 @@ public void enforceValid(String email) throws InvalidEmailException {
    *         {@link Email} object if successful, or the {@link FailureReason} if not
    */
   public EmailValidationResult validate(String email) {
-    EmailValidationResult result = JMail.validate(email);
+    EmailValidationResult result = JMail.validate(email, allowGmailDots);
 
     // If failed basic validation, just return it
     if (!result.getEmail().isPresent()) return result;
@@ -404,14 +425,16 @@ public EmailValidationResult validate(String email) {
    *         is invalid according to all registered validation rules
    */
   public Optional<Email> tryParse(String email) {
-    return JMail.tryParse(email).filter(e -> !testPredicates(e).isPresent());
+    return JMail.validate(email, allowGmailDots).getEmail()
+        .filter(e -> !testPredicates(e).isPresent());
   }
 
   /**
    * Test the given email address against all configured validation predicates.
    *
    * @param email the email address to test
-   * @return true if it passes the predicates, false otherwise
+   * @return an Optional that is either empty if all predicates passed or filled with the proper
+   *         FailureReason if one failed
    */
   private Optional<FailureReason> testPredicates(Email email) {
     return validationPredicates.entrySet().stream()

src/main/java/com/sanctionco/jmail/JMail.java

@@ -93,20 +93,6 @@ public static void enforceValid(String email) throws InvalidEmailException {
     }
   }
 
-  /**
-   * Determine if the given email address is valid, returning a new {@link EmailValidationResult}
-   * object that contains details on the result of the validation. Use this method if you need to
-   * see the {@link FailureReason} upon validation failure. See {@link #tryParse(String)}
-   * for details on what is required of an email address within basic validation.
-   *
-   * @param email the email address to validate
-   * @return a {@link EmailValidationResult} containing success or failure, along with the parsed
-   *         {@link Email} object if successful, or the {@link FailureReason} if not
-   */
-  public static EmailValidationResult validate(String email) {
-    return validateInternal(email);
-  }
-
   /**
    * Parse the given email address into a new {@link Email} object. This method does basic
    * validation on the input email address. This method does not claim to be 100%
@@ -123,18 +109,44 @@ public static EmailValidationResult validate(String email) {
    *         is invalid
    */
   public static Optional<Email> tryParse(String email) {
-    EmailValidationResult result = validateInternal(email);
+    EmailValidationResult result = validate(email);
 
     return result.getEmail();
   }
 
+  /**
+   * Determine if the given email address is valid, returning a new {@link EmailValidationResult}
+   * object that contains details on the result of the validation. Use this method if you need to
+   * see the {@link FailureReason} upon validation failure. See {@link #tryParse(String)}
+   * for details on what is required of an email address within basic validation.
+   *
+   * @param email the email address to validate
+   * @return a {@link EmailValidationResult} containing success or failure, along with the parsed
+   *         {@link Email} object if successful, or the {@link FailureReason} if not
+   */
+  public static EmailValidationResult validate(String email) {
+    return validateInternal(email, false);
+  }
+
+  /**
+   * Package-private validate method that exposes an additional option {@code allowGmailDots}.
+   *
+   * @param email the email address to parse and validate
+   * @param allowGmailDots true if a leading or trailing dot in the local-part should be allowed
+   * @return a {@link EmailValidationResult} containing success or failure, along with the parsed
+   *         {@link Email} object if successful, or the {@link FailureReason} if not
+   */
+  static EmailValidationResult validate(String email, boolean allowGmailDots) {
+    return validateInternal(email, allowGmailDots);
+  }
+
   /**
    * Internal parsing method.
    *
    * @param email the email address to parse
    * @return a new {@link Email} instance if valid, empty if invalid
    */
-  private static EmailValidationResult validateInternal(String email) {
+  private static EmailValidationResult validateInternal(String email, boolean allowGmailDots) {
     // email cannot be null
     if (email == null) return EmailValidationResult.failure(FailureReason.NULL_ADDRESS);
 
@@ -168,7 +180,11 @@ private static EmailValidationResult validateInternal(String email) {
     if (size > 320) return EmailValidationResult.failure(FailureReason.ADDRESS_TOO_LONG);
 
     // email cannot start with '.'
-    if (email.charAt(0) == '.') return EmailValidationResult.failure(FailureReason.STARTS_WITH_DOT);
+    // email cannot start with '.'
+    // unless we are configured to allow it (GMail doesn't care about a starting dot)
+    if (email.charAt(0) == '.' && !allowGmailDots) {
+      return EmailValidationResult.failure(FailureReason.STARTS_WITH_DOT);
+    }
 
     // email cannot end with '.'
     if (email.charAt(size - 1) == '.') {
@@ -223,7 +239,8 @@ private static EmailValidationResult validateInternal(String email) {
           return EmailValidationResult.failure(FailureReason.UNQUOTED_ANGLED_BRACKET);
         }
 
-        EmailValidationResult innerResult = validateInternal(email.substring(i + 1, size - 1));
+        EmailValidationResult innerResult
+            = validateInternal(email.substring(i + 1, size - 1), allowGmailDots);
 
         // If the address passed validation, return success with the identifier included.
         // Otherwise, just return the failed internal result
@@ -512,7 +529,15 @@ private static EmailValidationResult validateInternal(String email) {
 
     // Check that local-part does not end with '.'
     if (localPart.charAt(localPart.length() - 1) == '.') {
-      return EmailValidationResult.failure(FailureReason.LOCAL_PART_ENDS_WITH_DOT);
+      // unless we are configured to allow it (GMail doesn't care about a trailing dot)
+      if (!allowGmailDots) {
+        return EmailValidationResult.failure(FailureReason.LOCAL_PART_ENDS_WITH_DOT);
+      }
+
+      // if we allow a trailing dot, just make sure it's not the only thing in the local-part
+      if (localPartLen <= 1) {
+        return EmailValidationResult.failure(FailureReason.LOCAL_PART_MISSING);
+      }
     }
 
     // Ensure the TLD is not empty or greater than 63 chars

src/test/java/com/sanctionco/jmail/EmailValidatorTest.java

@@ -307,6 +307,42 @@ void invalidatesCorrectlyWithMap(String email) {
     }
   }
 
+  @Nested
+  class AllowGmailDots {
+    @ParameterizedTest(name = "{0}")
+    @ValueSource(strings = {
+        "[email protected]", "[email protected]", "[email protected]"})
+    void rejectsInvalidDots(String email) {
+      runInvalidTest(JMail.validator().allowGmailDots(),
+          email, FailureReason.MULTIPLE_DOT_SEPARATORS);
+    }
+
+    @ParameterizedTest(name = "{0}")
+    @ValueSource(strings = {
+        "[email protected]", "[email protected]", "[email protected]"})
+    void allowsGmailDots(String email) {
+      runValidTest(JMail.validator().allowGmailDots(), email);
+    }
+  }
+
+  @Nested
+  class DisallowIpDomainAllowGmailDotsCombination {
+    @ParameterizedTest(name = "{0}")
+    @ValueSource(strings = {
+        "test@[1.2.3.4]", "test@[5.6.7.8]"})
+    void rejects(String email) {
+      runInvalidTest(JMail.validator().allowGmailDots().disallowIpDomain(),
+          email, FailureReason.CONTAINS_IP_DOMAIN);
+    }
+
+    @ParameterizedTest(name = "{0}")
+    @ValueSource(strings = {
+        "[email protected]", "[email protected]", "[email protected]"})
+    void allows(String email) {
+      runValidTest(JMail.validator().allowGmailDots().disallowIpDomain(), email);
+    }
+  }
+
   private static void runValidTest(EmailValidator validator, String email) {
     Condition<String> valid = new Condition<>(validator::isValid, "valid");
 

src/test/java/com/sanctionco/jmail/JMailTest.java

@@ -8,6 +8,7 @@
 import net.andreinc.mockneat.MockNeat;
 
 import org.assertj.core.api.Condition;
+import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.CsvFileSource;
@@ -17,6 +18,7 @@
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
 import static org.assertj.core.api.Assertions.assertThatNoException;
+import static org.junit.jupiter.api.Assumptions.assumeTrue;
 
 class JMailTest {
   private final Condition<String> valid = new Condition<>(JMail::isValid, "valid");
@@ -207,4 +209,36 @@ void ensureIdentifiersAreParsed() {
   void isInvalidCanValidate() {
     assertThat(JMail.isInvalid("[email protected]")).isFalse();
   }
+
+  @Nested
+  class AllowGmailDots {
+    @ParameterizedTest(name = "{0}")
+    @MethodSource({
+        "com.sanctionco.jmail.helpers.AdditionalEmailProvider#provideInvalidEmails",
+        "com.sanctionco.jmail.helpers.AdditionalEmailProvider#provideInvalidWhitespaceEmails",
+        "com.sanctionco.jmail.helpers.AdditionalEmailProvider#provideInvalidControlEmails"})
+    @CsvFileSource(resources = "/invalid-addresses.csv", delimiterString = " ;", numLinesToSkip = 1)
+    void ensureFailuresWhenAllowGmailDotsIsTrue(String email) {
+      // This test only works for addresses that will fail
+      // even when we allow a starting or trailing dot in the local-part
+      assumeTrue(email.charAt(0) != '.' && !email.contains(".@"));
+
+      assertThat(JMail.validate(email, true))
+          .returns(true, EmailValidationResult::isFailure);
+    }
+
+    @Test
+    void ensureOnlyDotFailsWhenAllowGmailDotsIsTrue() {
+      assertThat(JMail.validate("[email protected]", true))
+          .returns(true, EmailValidationResult::isFailure)
+          .returns(FailureReason.LOCAL_PART_MISSING, EmailValidationResult::getFailureReason);;
+    }
+
+    @ParameterizedTest(name = "{0}")
+    @ValueSource(strings = {"[email protected]", "[email protected]"})
+    void ensureStartingAndTrailingDotsPass(String address) {
+      assertThat(JMail.validate(address, true).getEmail())
+          .isPresent().get().hasToString(address);
+    }
+  }
 }