Added option to use re2j for CSS query regexes

Re2j is a linear-time regex engine. This enables jsoup users to now safely accept arbitrary CSS regex-based queries.

Author: jhy

CHANGES.md

@@ -3,6 +3,16 @@
 ## 1.22.1 (PENDING)
 
 ### Improvements
+* Added support for using the re2j regular expression engine for CSS selectors, which ensures linear-time performance for regex evaluation. This enables safe handling of arbitrary user-supplied query regexes. To enable, add the `com.google.re2j` dependency to your classpath, e.g.:
+```xml
+  <dependency>
+    <groupId>com.google.re2j</groupId>
+    <artifactId>re2j</artifactId>
+    <version>1.8</version>
+  </dependency>
+ ```
+  (If you already have that dependency in your classpath, but you want to keep using the Java regex engine, you can disable re2j via `System.setProperty("jsoup.useRe2j", "false")`.)
+
 * Added an instance method `Parser#unescape(String, boolean)` that unescapes HTML entities using the parser’s configuration (e.g. to support error tracking), complementing the existing static utility `Parser.unescapeEntities(String, boolean)`. [#2396](https://github.com/jhy/jsoup/pull/2396)
 * Build: added CI coverage for JDK 25 [#2403](https://github.com/jhy/jsoup/pull/2403)
 * Build: added a CI fuzzer for contextual fragment parsing (in addition to existing full body HTML and XML fuzzers). [oss-fuzz #14041](https://github.com/google/oss-fuzz/pull/14041)

pom.xml

@@ -544,6 +544,15 @@
       <version>1.0.0</version>
       <scope>provided</scope>
     </dependency>
+
+    <dependency>
+      <!-- re2j; linear time regex, with 3-clause BSD license -->
+      <groupId>com.google.re2j</groupId>
+      <artifactId>re2j</artifactId>
+      <version>1.8</version>
+      <optional>true</optional>
+      <scope>compile</scope>
+    </dependency>
   </dependencies>
 
   <dependencyManagement>

src/main/java/org/jsoup/helper/Re2jRegex.java

@@ -0,0 +1,46 @@
+package org.jsoup.helper;
+
+/**
+ re2j-backed Regex implementation; must only be touched when re2j is on the classpath.
+ */
+final class Re2jRegex extends Regex {
+    private static final java.util.regex.Pattern unused = java.util.regex.Pattern.compile("");
+
+    private final com.google.re2j.Pattern re2jPattern;
+
+    private Re2jRegex(com.google.re2j.Pattern re2jPattern) {
+        super(unused);
+        this.re2jPattern = re2jPattern;
+    }
+
+    public static Regex compile(String regex) {
+        try {
+            return new Re2jRegex(com.google.re2j.Pattern.compile(regex));
+        } catch (RuntimeException e) {
+            throw new ValidationException("Pattern syntax error: " + e.getMessage());
+        }
+    }
+
+    @Override
+    public Matcher matcher(CharSequence input) {
+        return new Re2jMatcher(re2jPattern.matcher(input));
+    }
+
+    @Override
+    public String toString() {
+        return re2jPattern.toString();
+    }
+
+    private static final class Re2jMatcher implements Matcher {
+        private final com.google.re2j.Matcher delegate;
+
+        Re2jMatcher(com.google.re2j.Matcher delegate) {
+            this.delegate = delegate;
+        }
+
+        @Override
+        public boolean find() {
+            return delegate.find();
+        }
+    }
+}

src/main/java/org/jsoup/helper/Regex.java

@@ -0,0 +1,92 @@
+package org.jsoup.helper;
+
+import org.jsoup.internal.SharedConstants;
+
+import java.util.regex.Pattern;
+import java.util.regex.PatternSyntaxException;
+
+/**
+ A regular expression abstraction. Allows jsoup to optionally use the re2j regular expression engine (linear time)
+ instead of the JDK's backtracking regex implementation.
+
+ <p>If the {@code com.google.re2j} library is found on the classpath, by default it will be used. You can override this
+ by setting {@code -Djsoup.useRe2j=false} to explicitly disable, and use the JDK regex engine.</p>
+
+ <p>(Currently this a simplified implementation for jsoup's specific use; can extend as required.)</p>
+ */
+public class Regex {
+    private static final boolean hasRe2j = hasRe2j();
+
+    private final Pattern jdkPattern;
+
+    Regex(Pattern jdkPattern) {
+        this.jdkPattern = jdkPattern;
+    }
+
+    /**
+     Compile a regex, using re2j if enabled and available; otherwise JDK regex.
+
+     @param regex the regex to compile
+     @return the compiled regex
+     @throws ValidationException if the regex is invalid
+     */
+    public static Regex compile(String regex) {
+        if (hasRe2j && wantsRe2j()) {
+            return Re2jRegex.compile(regex);
+        }
+
+        try {
+            return new Regex(Pattern.compile(regex));
+        } catch (PatternSyntaxException e) {
+            throw new ValidationException("Pattern syntax error: " + e.getMessage());
+        }
+    }
+
+    /** Wraps an existing JDK Pattern (for API compat); doesn't switch */
+    public static Regex fromPattern(Pattern pattern) {
+        return new Regex(pattern);
+    }
+
+    static boolean wantsRe2j() {
+        return Boolean.parseBoolean(System.getProperty(SharedConstants.UseRe2j, "true"));
+    }
+
+    static void wantsRe2j(boolean use) {
+        System.setProperty(SharedConstants.UseRe2j, Boolean.toString(use));
+    }
+
+    static boolean hasRe2j() {
+        try {
+            Class.forName("com.google.re2j.Pattern", false, Regex.class.getClassLoader());
+            return true;
+        } catch (ClassNotFoundException e) {
+            return false;
+        }
+    }
+
+    public Matcher matcher(CharSequence input) {
+        return new JdkMatcher(jdkPattern.matcher(input));
+    }
+
+    @Override
+    public String toString() {
+        return jdkPattern.toString();
+    }
+
+    public interface Matcher {
+        boolean find();
+    }
+
+    private static final class JdkMatcher implements Matcher {
+        private final java.util.regex.Matcher delegate;
+
+        JdkMatcher(java.util.regex.Matcher delegate) {
+            this.delegate = delegate;
+        }
+
+        @Override
+        public boolean find() {
+            return delegate.find();
+        }
+    }
+}

src/main/java/org/jsoup/internal/SharedConstants.java

@@ -21,5 +21,7 @@ public final class SharedConstants {
 
     public static final String UseHttpClient = "jsoup.useHttpClient";
 
+    public static final String UseRe2j = "jsoup.useRe2j"; // enables use of the re2j regular expression engine when true and it's on the classpath
+
     private SharedConstants() {}
 }

src/main/java/org/jsoup/nodes/Element.java

@@ -3,6 +3,7 @@
 import org.jsoup.helper.Validate;
 import org.jsoup.internal.Normalizer;
 import org.jsoup.internal.QuietAppendable;
+import org.jsoup.helper.Regex;
 import org.jsoup.internal.StringUtil;
 import org.jsoup.parser.ParseSettings;
 import org.jsoup.parser.Parser;
@@ -1404,7 +1405,6 @@ public Elements getElementsByAttributeValueContaining(String key, String match)
      */
     public Elements getElementsByAttributeValueMatching(String key, Pattern pattern) {
         return Collector.collect(new Evaluator.AttributeWithValueMatching(key, pattern), this);
-
     }
 
     /**
@@ -1414,13 +1414,13 @@ public Elements getElementsByAttributeValueMatching(String key, Pattern pattern)
      * @return elements that have attributes matching this regular expression
      */
     public Elements getElementsByAttributeValueMatching(String key, String regex) {
-        Pattern pattern;
+        Regex pattern;
         try {
-            pattern = Pattern.compile(regex);
+            pattern = Regex.compile(regex);
         } catch (PatternSyntaxException e) {
             throw new IllegalArgumentException("Pattern syntax error: " + regex, e);
         }
-        return getElementsByAttributeValueMatching(key, pattern);
+        return Collector.collect(new Evaluator.AttributeWithValueMatching(key, pattern), this);
     }
 
     /**
@@ -1489,13 +1489,13 @@ public Elements getElementsMatchingText(Pattern pattern) {
      * @see Element#text()
      */
     public Elements getElementsMatchingText(String regex) {
-        Pattern pattern;
+        Regex pattern;
         try {
-            pattern = Pattern.compile(regex);
+            pattern = Regex.compile(regex);
         } catch (PatternSyntaxException e) {
             throw new IllegalArgumentException("Pattern syntax error: " + regex, e);
         }
-        return getElementsMatchingText(pattern);
+        return Collector.collect(new Evaluator.Matches(pattern), this);
     }
 
     /**
@@ -1515,13 +1515,13 @@ public Elements getElementsMatchingOwnText(Pattern pattern) {
      * @see Element#ownText()
      */
     public Elements getElementsMatchingOwnText(String regex) {
-        Pattern pattern;
+        Regex pattern;
         try {
-            pattern = Pattern.compile(regex);
+            pattern = Regex.compile(regex);
         } catch (PatternSyntaxException e) {
             throw new IllegalArgumentException("Pattern syntax error: " + regex, e);
         }
-        return getElementsMatchingOwnText(pattern);
+        return Collector.collect(new Evaluator.MatchesOwn(pattern), this);
     }
 
     /**

src/main/java/org/jsoup/select/Evaluator.java

@@ -11,10 +11,10 @@
 import org.jsoup.nodes.TextNode;
 import org.jsoup.nodes.XmlDeclaration;
 import org.jsoup.parser.ParseSettings;
+import org.jsoup.helper.Regex;
 
 import java.util.List;
 import java.util.function.Predicate;
-import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
 import static org.jsoup.internal.Normalizer.lowerCase;
@@ -385,13 +385,17 @@ public String toString() {
      */
     public static final class AttributeWithValueMatching extends Evaluator {
         final String key;
-        final Pattern pattern;
+        final Regex pattern;
 
-        public AttributeWithValueMatching(String key, Pattern pattern) {
+        public AttributeWithValueMatching(String key, Regex pattern) {
             this.key = normalize(key);
             this.pattern = pattern;
         }
 
+        public AttributeWithValueMatching(String key, Pattern pattern) {
+            this(key, Regex.fromPattern(pattern)); // api compat
+        }
+
         @Override
         public boolean matches(Element root, Element element) {
             return element.hasAttr(key) && pattern.matcher(element.attr(key)).find();
@@ -924,16 +928,19 @@ public String toString() {
      * Evaluator for matching Element (and its descendants) text with regex
      */
     public static final class Matches extends Evaluator {
-        private final Pattern pattern;
+        private final Regex pattern;
 
-        public Matches(Pattern pattern) {
+        public Matches(Regex pattern) {
             this.pattern = pattern;
         }
 
+        public Matches(Pattern pattern) {
+            this(Regex.fromPattern(pattern));
+        }
+
         @Override
         public boolean matches(Element root, Element element) {
-            Matcher m = pattern.matcher(element.text());
-            return m.find();
+            return pattern.matcher(element.text()).find();
         }
 
         @Override protected int cost() {
@@ -950,16 +957,19 @@ public String toString() {
      * Evaluator for matching Element's own text with regex
      */
     public static final class MatchesOwn extends Evaluator {
-        private final Pattern pattern;
+        private final Regex pattern;
 
-        public MatchesOwn(Pattern pattern) {
+        public MatchesOwn(Regex pattern) {
             this.pattern = pattern;
         }
 
+        public MatchesOwn(Pattern pattern) {
+            this(Regex.fromPattern(pattern));
+        }
+
         @Override
         public boolean matches(Element root, Element element) {
-            Matcher m = pattern.matcher(element.ownText());
-            return m.find();
+            return pattern.matcher(element.ownText()).find();
         }
 
         @Override protected int cost() {
@@ -977,16 +987,19 @@ public String toString() {
      * @since 1.15.1.
      */
     public static final class MatchesWholeText extends Evaluator {
-        private final Pattern pattern;
+        private final Regex pattern;
 
-        public MatchesWholeText(Pattern pattern) {
+        public MatchesWholeText(Regex pattern) {
             this.pattern = pattern;
         }
 
+        public MatchesWholeText(Pattern pattern) {
+            this.pattern = Regex.fromPattern(pattern);
+        }
+
         @Override
         public boolean matches(Element root, Element element) {
-            Matcher m = pattern.matcher(element.wholeText());
-            return m.find();
+            return pattern.matcher(element.wholeText()).find();
         }
 
         @Override protected int cost() {
@@ -1004,15 +1017,19 @@ public String toString() {
      * @since 1.15.1.
      */
     public static final class MatchesWholeOwnText extends Evaluator {
-        private final Pattern pattern;
+        private final Regex pattern;
 
-        public MatchesWholeOwnText(Pattern pattern) {
+        public MatchesWholeOwnText(Regex pattern) {
             this.pattern = pattern;
         }
 
+        public MatchesWholeOwnText(Pattern pattern) {
+            this(Regex.fromPattern(pattern));
+        }
+
         @Override
         public boolean matches(Element root, Element element) {
-            Matcher m = pattern.matcher(element.wholeOwnText());
+            Regex.Matcher m = pattern.matcher(element.wholeOwnText());
             return m.find();
         }
 

src/main/java/org/jsoup/select/NodeEvaluator.java

@@ -4,8 +4,7 @@
 import org.jsoup.nodes.Element;
 import org.jsoup.nodes.LeafNode;
 import org.jsoup.nodes.Node;
-
-import java.util.regex.Pattern;
+import org.jsoup.helper.Regex;
 
 import static org.jsoup.internal.Normalizer.lowerCase;
 import static org.jsoup.internal.StringUtil.normaliseWhitespace;
@@ -98,9 +97,9 @@ public String toString() {
     }
 
     static class MatchesValue extends NodeEvaluator {
-        private final Pattern pattern;
+        private final Regex pattern;
 
-        protected MatchesValue(Pattern pattern) {
+        protected MatchesValue(Regex pattern) {
             this.pattern = pattern;
         }