email-bounce-parser 1.0.22 → 1.1.1

package/README.md

@@ -10,7 +10,7 @@ Parses bounce emails and extracts details.
 
 <table>
 <tr>
-<td align="center"><a href="https://crisp.chat/"><img src="https://crisp.chat/favicon-256x256.png" height="64" /></a></td>
+<td align="center"><a href="https://crisp.chat/"><img src="https://crisp.chat/favicons/favicon-256x256.png" height="64" /></a></td>
 </tr>
 <tr>
 <td align="center">Crisp</td>
@@ -24,6 +24,22 @@ _👋 You use this library and you want to be listed there? [Contact us](https:/
 This library is used at [Crisp](https://crisp.chat/) everyday to parse bounce emails.
 It supports most variations of bounce emails (Postfix, Dovecat, Gmail, Outlook).
 
+## RE2 Support
+
+This library uses the [RE2](https://github.com/uhop/node-re2) regex engine when available for better performance and [ReDoS](https://en.wikipedia.org/wiki/ReDoS) protection. It automatically falls back to native JavaScript `RegExp` if RE2 is unavailable or fails to load.
+
+RE2 is an optional dependency. To use it, install it alongside this library:
+
+```bash
+npm install re2
+```
+
+After a Node.js upgrade, you may need to rebuild RE2:
+
+```bash
+npm rebuild re2
+```
+
 ## Usage
 
 ```js

package/lib/parser.js

@@ -1,8 +1,7 @@
 "use strict";
 
 
-var RE2                         = require("re2");
-var { loopRegexes, trimString } = require("./utils");
+var { buildSafeRegExp, loopRegexes, trimString } = require("./utils");
 
 var ERROR_CODES_TYPES = {
   "421"        : "service_not_available",
@@ -265,13 +264,13 @@ class Parser {
 
         for (var _i = 0; _i < _entry.length; _i++) {
           _regexes[_key].push(
-            new RE2(_entry[_i])
+            buildSafeRegExp(_entry[_i])
           );
         }
       } else if (typeof _entry === "object" && Object.keys(_entry).length > 0) {
         _regexes[_key] = this.__initRegexes(_entry);
       } else {
-        _regexes[_key] = new RE2(_entry);
+        _regexes[_key] = buildSafeRegExp(_entry);
       }
     }
 
@@ -316,7 +315,7 @@ class Parser {
     // In cases where the bounce is detected as permanent, or the \
     //   temporary / permanent status is still unclear, run additional detection
     if (_permanent === true || (_temporary === false && _permanent === false)) {
-      var _match = this.__regexes.temporary_safe.match(str);
+      var _match = str.match(this.__regexes.temporary_safe);
 
       if (_match && _match.length > 1) {
         _temporary = true;
@@ -415,14 +414,14 @@ class Parser {
     }
 
     // Check if blocked
-    var _blocked_match = this.__regexes.blocked.match(str);
+    var _blocked_match = str.match(this.__regexes.blocked);
 
     if (_blocked_match && _blocked_match.length > 1) {
       _blocked = true;
     }
 
     // Check if spam
-    var _spam_match = this.__regexes.spam.match(str);
+    var _spam_match = str.match(this.__regexes.spam);
 
     if (_spam_match && _spam_match.length > 1) {
       _spam = true;

package/lib/utils.js

@@ -4,12 +4,45 @@
  * IMPORTS
  ***************************************************************************/
 
-var RE2 = require("re2");
+/**************************************************************************
+ * INSTANCES
+ ***************************************************************************/
+
+var RE2Engine = detectRE2();
 
 /**************************************************************************
  * FUNCTIONS
  ***************************************************************************/
 
+/**
+ * Detects whether the RE2 engine is available
+ * @private
+ * @return {function|null} The RE2 engine, or null if unavailable
+ */
+function detectRE2() {
+  // Notice: RE2 can be explicitly disabled, to test the RegExp fallback
+  if (process.env.EMAIL_BOUNCE_PARSER_DISABLE_RE2) {
+    return null;
+  }
+
+  try {
+    return require("re2");
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Builds a safe regular expression (RE2 when available, RegExp otherwise)
+ * @public
+ * @param  {string|RegExp} source
+ * @return {RegExp}        The regular expression
+ */
+var buildSafeRegExp = function(source) {
+  return (RE2Engine !== null) ? new RE2Engine(source) : new RegExp(source);
+}
+
+
 /**
  * Executes multiple regular expressions until one succeeds
  * @public
@@ -31,12 +64,19 @@ var loopRegexes = function(
 
     if (typeof regexes[_i] === "string") {
       // Build the regex
-      _regex = new RE2(regexes[_i]);
+      _regex = buildSafeRegExp(regexes[_i]);
     }
 
-    var _currentMatch = (
-      _regex[mode](str || "", mode === "replace" ? "" : undefined)
-    );
+    // Notice: call String methods, as they support both RE2 and RegExp
+    var _currentMatch;
+
+    if (mode === "replace") {
+      _currentMatch = (str || "").replace(_regex, "");
+    } else if (mode === "split") {
+      _currentMatch = (str || "").split(_regex);
+    } else {
+      _currentMatch = (str || "").match(_regex);
+    }
 
     if (mode === "replace") {
       _match = _currentMatch;
@@ -98,10 +138,12 @@ var trimString = function(str) {
  * EXPORTS
  ***************************************************************************/
 
-exports.loopRegexes = loopRegexes;
-exports.trimString  = trimString;
+exports.buildSafeRegExp = buildSafeRegExp;
+exports.loopRegexes     = loopRegexes;
+exports.trimString      = trimString;
 
 exports.default = {
-  loopRegexes : loopRegexes,
-  trimString  : trimString
+  buildSafeRegExp : buildSafeRegExp,
+  loopRegexes     : loopRegexes,
+  trimString      : trimString
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "email-bounce-parser",
-  "version": "1.0.22",
+  "version": "1.1.1",
   "description": "Parses bounce emails and extract errors",
   "author": "Eliott Vincent <eliott@crisp.chat>",
   "main": "lib/index.js",
@@ -14,16 +14,27 @@
   },
   "engineStrict": true,
   "engines": {
-    "node": ">=14.18.0"
+    "node": ">= 22.0.0"
   },
   "scripts": {
-    "test": "nodeunit ./test/index.js"
+    "unit": "nodeunit ./test/index.js",
+    "unit:regexp": "EMAIL_BOUNCE_PARSER_DISABLE_RE2=1 npm run unit",
+    "test": "npm run unit && npm run unit:regexp"
   },
   "devDependencies": {
-    "nodeunit-x": "0.15.0"
+    "nodeunit-x": "0.15.0",
+    "re2": "1.27.0"
   },
-  "dependencies": {
-    "re2": "1.20.7"
+  "peerDependencies": {
+    "re2": "1.x"
+  },
+  "peerDependenciesMeta": {
+    "re2": {
+      "optional": true
+    }
+  },
+  "allowScripts": {
+    "re2@1.27.0": true
   },
   "keywords": [
     "parser",