Merge pull request #31 from Quad9DNS/feature/regex-rule

esensar · web-flow · commit 19e9f10df22e · 2026-03-19T18:12:34.000+01:00
Add regex rule
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -28,6 +28,7 @@ lazy_static = { version = "1.5.0" }
 metrics = { version = "0.24.2" }
 metrics-exporter-prometheus = { version = "0.17.0" }
 metrics-util = { version = "0.19.1" }
+regex = { version = "1.12.3" }
 rdkafka = { version = "0.37.0" }
 rphonetic = { version = "3.0.3" }
 serde = { version = "1.0.219" }
diff --git a/README.md b/README.md
@@ -46,6 +46,7 @@ Stringsimile supports different inputs, outputs and rules to use when comparing
 - NYSIIS
 - Match Rating
 - Bitflip
+- Regex
 
 Check out the [example rules file](./distribution/rules/example.json) to see how they can be defined. You can also check out the included man pages (`man 5 stringsimile-rule-config`).
 
diff --git a/bin/stringsimile-service/tests/basic_file_test.rs b/bin/stringsimile-service/tests/basic_file_test.rs
@@ -23,7 +23,7 @@ const INPUT_DATA: &[u8] =
 "#;
 
 const RULES_DATA: &[u8] = br#"
-{ "name": "Example string group", "rule_sets": [ { "name": "Test rule set", "string_match": "test", "preprocessors": [ { "preprocessor_type": "split_target", "ignore_tld": true } ], "match_rules": [ { "rule_type": "levenshtein", "values": { "maximum_distance": 3 } }, { "rule_type": "hamming", "values": { "maximum_distance": 3 } }, { "rule_type": "soundex", "values": { "minimum_similarity": 3 } }, { "rule_type": "metaphone", "values": { "max_code_length": 3 } }, { "rule_type": "nysiis", "values": { "strict": true } }, { "rule_type": "jaro", "values": { "match_percent_threshold": 0.85 } }, { "rule_type": "jaro_winkler", "values": { "match_percent_threshold": 0.85 } }, { "rule_type": "confusables" }, { "rule_type": "match_rating" }, { "rule_type": "damerau_levenshtein", "values": { "maximum_distance": 3 } } ] }, { "name": "Example rule set", "split_target": true, "ignore_tld": true, "string_match": "example", "match_rules": [ { "rule_type": "levenshtein", "values": { "maximum_distance": 3 } }, { "rule_type": "jaro", "values": { "match_percent_threshold": 0.85 } }, { "rule_type": "bitflip" } ] } ] }
+{ "name": "Example string group", "rule_sets": [ { "name": "Test rule set", "string_match": "test", "preprocessors": [ { "preprocessor_type": "split_target", "ignore_tld": true } ], "match_rules": [ { "rule_type": "levenshtein", "values": { "maximum_distance": 3 } }, { "rule_type": "hamming", "values": { "maximum_distance": 3 } }, { "rule_type": "soundex", "values": { "minimum_similarity": 3 } }, { "rule_type": "metaphone", "values": { "max_code_length": 3 } }, { "rule_type": "nysiis", "values": { "strict": true } }, { "rule_type": "jaro", "values": { "match_percent_threshold": 0.85 } }, { "rule_type": "jaro_winkler", "values": { "match_percent_threshold": 0.85 } }, { "rule_type": "confusables" }, { "rule_type": "match_rating" }, { "rule_type": "damerau_levenshtein", "values": { "maximum_distance": 3 } } ] }, { "name": "Example rule set", "split_target": true, "ignore_tld": true, "string_match": "example", "match_rules": [ { "rule_type": "levenshtein", "values": { "maximum_distance": 3 } }, { "rule_type": "jaro", "values": { "match_percent_threshold": 0.85 } }, { "rule_type": "bitflip" }, { "rule_type": "regex", "values": { "pattern": "test" } } ] } ] }
 "#;
 
 #[test]
diff --git a/crates/stringsimile-config/Cargo.toml b/crates/stringsimile-config/Cargo.toml
@@ -9,6 +9,7 @@ version.workspace = true
 stringsimile-matcher.workspace = true
 
 hashbrown.workspace = true
+regex.workspace = true
 serde = { workspace = true, features = ["derive"] }
 serde_json.workspace = true
 snafu.workspace = true
diff --git a/crates/stringsimile-config/src/rules.rs b/crates/stringsimile-config/src/rules.rs
@@ -1,6 +1,7 @@
 //! Configuration for rules
+use regex::Regex;
 use serde::{Deserialize, Serialize};
-use snafu::Snafu;
+use snafu::{ResultExt, Snafu};
 use stringsimile_matcher::{
     Error,
     rule::{GenericMatcherRule, IntoGenericMatcherRule},
@@ -15,6 +16,7 @@ use stringsimile_matcher::{
         match_rating::MatchRatingRule,
         metaphone::{MetaphoneRule, MetaphoneRuleType},
         nysiis::NysiisRule,
+        regex::RegexRule,
         soundex::{SoundexRule, SoundexRuleType},
     },
 };
@@ -45,6 +47,8 @@ pub enum RuleConfig {
     MatchRating,
     /// Configuration for Bitflip rule
     Bitflip(Option<BitflipConfig>),
+    /// Configuration for Regex rule
+    Regex(RegexConfig),
 }
 
 /// Errors for rule configuration
@@ -98,6 +102,13 @@ pub enum RuleConfigError {
         /// Position at which non-ASCII char was found.
         index: usize,
     },
+
+    /// Regex rule configuration error
+    #[snafu(display("Invalid pattern for Regex rule: {}", source))]
+    RegexInvalidPattern {
+        /// Regex error.
+        source: regex::Error,
+    },
 }
 
 impl RuleConfig {
@@ -146,6 +157,9 @@ impl RuleConfig {
                     .build(target_str)?
                     .into_generic_matcher(),
             ),
+            RuleConfig::Regex(regex_config) => {
+                Box::new(regex_config.build()?.into_generic_matcher())
+            }
         })
     }
 }
@@ -421,6 +435,21 @@ impl Default for BitflipConfig {
     }
 }
 
+/// Configuration for Regex rule
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RegexConfig {
+    /// Regex pattern to match against.
+    pub pattern: String,
+}
+
+impl RegexConfig {
+    fn build(&self) -> Result<RegexRule, Error> {
+        Ok(RegexRule::new(
+            Regex::new(&self.pattern).context(RegexInvalidPatternSnafu)?,
+        ))
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -802,4 +831,44 @@ mod tests {
         assert_eq!(input_str, "abcčćddžđ");
         assert_eq!(*index, 3);
     }
+
+    #[test]
+    fn test_parse_regex() {
+        let json = r#"
+        {
+            "rule_type": "regex",
+            "values": {
+                "pattern": "test"
+            }
+        }
+            "#;
+
+        let RuleConfig::Regex(config) = serde_json::from_str(json).unwrap() else {
+            panic!("Expected Regex config");
+        };
+        assert_eq!(config.pattern, "test");
+
+        let res = config.build();
+        assert!(res.is_ok());
+    }
+
+    #[test]
+    fn test_parse_regex_invalid_pattern() {
+        let json = r#"
+        {
+            "rule_type": "regex",
+            "values": {
+                "pattern": "["
+            }
+        }
+            "#;
+
+        let RuleConfig::Regex(config) = serde_json::from_str(json).unwrap() else {
+            panic!("Expected Regex config");
+        };
+        assert_eq!(config.pattern, "[");
+
+        let res = config.build();
+        assert!(res.is_err());
+    }
 }
diff --git a/crates/stringsimile-matcher/Cargo.toml b/crates/stringsimile-matcher/Cargo.toml
@@ -7,24 +7,26 @@ version.workspace = true
 
 [features]
 default = ["all"]
-all = ["rules-levenshtein", "rules-hamming", "rules-jaro", "rules-jaro-winkler", "rules-confusables", "rules-damerau-levenshtein", "rules-soundex", "rules-metaphone", "rules-nysiis", "rules-match-rating", "rules-bitflip"]
-rules-levenshtein = ["dep:triple_accel"]
+all = ["rules-levenshtein", "rules-hamming", "rules-jaro", "rules-jaro-winkler", "rules-confusables", "rules-damerau-levenshtein", "rules-soundex", "rules-metaphone", "rules-nysiis", "rules-match-rating", "rules-bitflip", "rules-regex"]
+rules-bitflip = ["dep:lazy_static"]
+rules-confusables = ["dep:confusables"]
+rules-damerau-levenshtein = ["dep:triple_accel"]
 rules-hamming = ["dep:triple_accel"]
 rules-jaro = ["dep:strsim"]
 rules-jaro-winkler = ["dep:strsim"]
-rules-confusables = ["dep:confusables"]
-rules-damerau-levenshtein = ["dep:triple_accel"]
-rules-soundex = ["dep:rphonetic"]
+rules-levenshtein = ["dep:triple_accel"]
+rules-match-rating = ["dep:rphonetic"]
 rules-metaphone = ["dep:rphonetic"]
 rules-nysiis = ["dep:rphonetic"]
-rules-match-rating = ["dep:rphonetic"]
-rules-bitflip = ["dep:lazy_static"]
+rules-regex = ["dep:regex"]
+rules-soundex = ["dep:rphonetic"]
 
 [dependencies]
 confusables = { workspace = true, optional = true }
+hashbrown.workspace = true
 lazy_static = { workspace = true, optional = true }
 metrics.workspace = true
-hashbrown.workspace = true
+regex = { workspace = true, optional = true }
 rphonetic = { workspace = true, optional = true }
 serde = { workspace = true, features = ["derive"] }
 serde_json.workspace = true
diff --git a/crates/stringsimile-matcher/benches/rules.rs b/crates/stringsimile-matcher/benches/rules.rs
@@ -1,4 +1,5 @@
 use criterion::{Criterion, criterion_group, criterion_main};
+use regex::Regex;
 use stringsimile_matcher::{
     rule::MatcherRule,
     rules::{
@@ -12,6 +13,7 @@ use stringsimile_matcher::{
         match_rating::MatchRatingRule,
         metaphone::{MetaphoneRule, MetaphoneRuleType},
         nysiis::NysiisRule,
+        regex::RegexRule,
         soundex::{SoundexRule, SoundexRuleType},
     },
 };
@@ -330,6 +332,24 @@ bench_rule! {
     }
 }
 
+bench_rule! {
+    name = regex_exact_match;
+    single_match = "randomWstring_to_find";
+    single_mismatch = "some different string";
+    builder {
+        RegexRule::new(Regex::new("randomWstring_to_find").unwrap())
+    }
+}
+
+bench_rule! {
+    name = regex_complex_pattern;
+    single_match = "randomWstring_to_find";
+    single_mismatch = "some different string";
+    builder {
+        RegexRule::new(Regex::new(r#"\w*_.*"#).unwrap())
+    }
+}
+
 criterion_group!(
     benches,
     confusables,
@@ -351,5 +371,7 @@ criterion_group!(
     bitflip_case_insensitive,
     bitflip_ascii_printable,
     bitflip_ascii_printable_case_insensitive,
+    regex_exact_match,
+    regex_complex_pattern,
 );
 criterion_main!(benches);
diff --git a/crates/stringsimile-matcher/benches/rulesets.rs b/crates/stringsimile-matcher/benches/rulesets.rs
@@ -1,4 +1,5 @@
 use criterion::{Criterion, criterion_group, criterion_main};
+use regex::Regex;
 use stringsimile_matcher::{
     preprocessors::{Preprocessor, SplitTargetConfig},
     rule::IntoGenericMatcherRule,
@@ -13,6 +14,7 @@ use stringsimile_matcher::{
         match_rating::MatchRatingRule,
         metaphone::{MetaphoneRule, MetaphoneRuleType},
         nysiis::NysiisRule,
+        regex::RegexRule,
         soundex::{SoundexRule, SoundexRuleType},
     },
     ruleset::{RuleSet, StringGroup, StringGroupContext},
@@ -201,6 +203,7 @@ bench_ruleset! {
                     Box::new(SoundexRule::new(SoundexRuleType::Normal, 5, target_str).into_generic_matcher()),
                     Box::new(SoundexRule::new(SoundexRuleType::Refined, 5, target_str).into_generic_matcher()),
                     Box::new(BitflipRule::new_dns(target_str, true)),
+                    Box::new(RegexRule::new(Regex::new(target_str).unwrap())),
                 ]
             }])
         }
@@ -233,6 +236,7 @@ bench_ruleset! {
                     Box::new(SoundexRule::new(SoundexRuleType::Normal, 5, target_str).into_generic_matcher()),
                     Box::new(SoundexRule::new(SoundexRuleType::Refined, 5, target_str).into_generic_matcher()),
                     Box::new(BitflipRule::new_dns(target_str, true)),
+                    Box::new(RegexRule::new(Regex::new(target_str).unwrap())),
                 ]
             }])
         }
@@ -265,6 +269,7 @@ bench_ruleset! {
                     Box::new(SoundexRule::new(SoundexRuleType::Normal, 5, target_str).into_generic_matcher()),
                     Box::new(SoundexRule::new(SoundexRuleType::Refined, 5, target_str).into_generic_matcher()),
                     Box::new(BitflipRule::new_dns(target_str, true)),
+                    Box::new(RegexRule::new(Regex::new(target_str).unwrap())),
                 ]
             }])
         }
diff --git a/crates/stringsimile-matcher/src/rules/mod.rs b/crates/stringsimile-matcher/src/rules/mod.rs
@@ -20,5 +20,7 @@ pub mod match_rating;
 pub mod metaphone;
 #[cfg(feature = "rules-nysiis")]
 pub mod nysiis;
+#[cfg(feature = "rules-regex")]
+pub mod regex;
 #[cfg(feature = "rules-soundex")]
 pub mod soundex;
diff --git a/crates/stringsimile-matcher/src/rules/regex.rs b/crates/stringsimile-matcher/src/rules/regex.rs
@@ -0,0 +1,80 @@
+//! Regex rule implementation
+
+use std::{fmt::Debug, io::Error};
+
+use regex::Regex;
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    MatcherResult,
+    rule::{MatcherResultRuleMetadataExt, MatcherRule, RuleMetadata},
+};
+
+/// Rule
+#[derive(Debug, Clone)]
+pub struct RegexRule {
+    pattern: Regex,
+}
+
+impl RegexRule {
+    /// Creates a new instance of [`RegexRule`], with compiled pattern.
+    pub fn new(pattern: Regex) -> Self {
+        Self { pattern }
+    }
+}
+
+/// metadata
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RegexMetadata;
+
+impl MatcherRule for RegexRule {
+    type OutputMetadata = RegexMetadata;
+    type Error = Error;
+
+    fn match_rule(
+        &self,
+        input_str: &str,
+        _target_str: &str,
+    ) -> MatcherResult<Self::OutputMetadata, Self::Error> {
+        if self.pattern.is_match(input_str) {
+            MatcherResult::new_match(RegexMetadata)
+        } else {
+            MatcherResult::new_no_match(RegexMetadata)
+        }
+    }
+}
+
+impl RuleMetadata for RegexMetadata {
+    const RULE_NAME: &str = "regex";
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::rule::MatcherResultExt;
+
+    use super::*;
+
+    #[test]
+    fn simple_example() {
+        let rule = RegexRule::new(Regex::new(r#"netflix\.com\.$"#).unwrap());
+
+        let result = rule.match_rule("netflix.com.", "netflix.com.");
+        assert!(result.is_match());
+        let result = rule.match_rule("netflix.com", "netflix.com.");
+        assert!(!result.is_match());
+        let result = rule.match_rule("neftlix.com.", "netflix.com.");
+        assert!(!result.is_match());
+    }
+
+    #[test]
+    fn complex_pattern_example() {
+        let rule = RegexRule::new(Regex::new(r#".*n.*t.*f.*"#).unwrap());
+
+        let result = rule.match_rule("netflix.com.", "netflix.com.");
+        assert!(result.is_match());
+        let result = rule.match_rule("netflix.com", "netflix.com.");
+        assert!(result.is_match());
+        let result = rule.match_rule("neftlix.com.", "netflix.com.");
+        assert!(!result.is_match());
+    }
+}
diff --git a/distribution/rules/example.json b/distribution/rules/example.json
diff --git a/distribution/rules/example.jsonl b/distribution/rules/example.jsonl
diff --git a/doc/stringsimile-rule-config.5.scd b/doc/stringsimile-rule-config.5.scd

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`use criterion::{Criterion, criterion_group, criterion_main};`
	`2`	`+use regex::Regex;`
`2`	`3`	`use stringsimile_matcher::{`
`3`	`4`	`preprocessors::{Preprocessor, SplitTargetConfig},`
`4`	`5`	`rule::IntoGenericMatcherRule,`
`@@ -13,6 +14,7 @@ use stringsimile_matcher::{`
`13`	`14`	`match_rating::MatchRatingRule,`
`14`	`15`	`metaphone::{MetaphoneRule, MetaphoneRuleType},`
`15`	`16`	`nysiis::NysiisRule,`
	`17`	`+ regex::RegexRule,`
`16`	`18`	`soundex::{SoundexRule, SoundexRuleType},`
`17`	`19`	`},`
`18`	`20`	`ruleset::{RuleSet, StringGroup, StringGroupContext},`
`@@ -201,6 +203,7 @@ bench_ruleset! {`
`201`	`203`	`Box::new(SoundexRule::new(SoundexRuleType::Normal, 5, target_str).into_generic_matcher()),`
`202`	`204`	`Box::new(SoundexRule::new(SoundexRuleType::Refined, 5, target_str).into_generic_matcher()),`
`203`	`205`	`Box::new(BitflipRule::new_dns(target_str, true)),`
	`206`	`+ Box::new(RegexRule::new(Regex::new(target_str).unwrap())),`
`204`	`207`	`]`
`205`	`208`	`}])`
`206`	`209`	`}`
`@@ -233,6 +236,7 @@ bench_ruleset! {`
`233`	`236`	`Box::new(SoundexRule::new(SoundexRuleType::Normal, 5, target_str).into_generic_matcher()),`
`234`	`237`	`Box::new(SoundexRule::new(SoundexRuleType::Refined, 5, target_str).into_generic_matcher()),`
`235`	`238`	`Box::new(BitflipRule::new_dns(target_str, true)),`
	`239`	`+ Box::new(RegexRule::new(Regex::new(target_str).unwrap())),`
`236`	`240`	`]`
`237`	`241`	`}])`
`238`	`242`	`}`
`@@ -265,6 +269,7 @@ bench_ruleset! {`
`265`	`269`	`Box::new(SoundexRule::new(SoundexRuleType::Normal, 5, target_str).into_generic_matcher()),`
`266`	`270`	`Box::new(SoundexRule::new(SoundexRuleType::Refined, 5, target_str).into_generic_matcher()),`
`267`	`271`	`Box::new(BitflipRule::new_dns(target_str, true)),`
	`272`	`+ Box::new(RegexRule::new(Regex::new(target_str).unwrap())),`
`268`	`273`	`]`
`269`	`274`	`}])`
`270`	`275`	`}`