feat(regex-validation): add new plugin regex-validation

Zorin95670 · Zorin95670 · commit dadb8ceb9022 · 2025-08-22T16:31:25.000+02:00
diff --git a/.github/workflows/regex-validation-pull-request.yml b/.github/workflows/regex-validation-pull-request.yml
@@ -0,0 +1,45 @@
+name: 'Check Pull Request for plugin: regex-validation'
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - 'regex-validation/**'
+
+jobs:
+  tests:
+    name: Unit tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up JDK 21 for x64
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+          architecture: x64
+
+      - name: Install Pandoc
+        run: sudo apt-get update && sudo apt-get install -y pandoc
+
+      - name: Execute unit tests
+        run: mvn -ntp -pl regex-validation test
+
+      - name: Execute mutation tests
+        run: mvn -ntp -pl regex-validation org.pitest:pitest-maven:mutationCoverage
+
+      - name: Extract summary from pitest
+        run: |
+          echo "<html><head></head><body><h1>Pit Test Coverage Report: regex-validation</h1><h3>Project Summary</h3>" > pitest.html
+          perl -0777 -ne 'print "$1\n" if /(<table>.*?<\/table>)/s' regex-validation/target/pit-reports/index.html >> pitest.html
+          echo "</body></html>" >> pitest.html
+
+      - name: Convert pitest report to markdown
+        run: pandoc --from html --to markdown_github --no-highlight pitest.html
+
+      - name: Post comment
+        uses: luukkemp/pr-comment@2024.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          path: pitest.html
diff --git a/pom.xml b/pom.xml
@@ -13,6 +13,7 @@
     <modules>
         <module>template-plugin</module>
         <module>context-mapper-task</module>
+        <module>regex-validation</module>
     </modules>
 
     <licenses>
diff --git a/regex-validation/README.md b/regex-validation/README.md
@@ -0,0 +1,54 @@
+# 🧪 RegexValidationPlugin
+
+The `RegexValidationPlugin` is a validation plugin used to ensure that a value matches a specified regular expression pattern.
+
+## ✅ Use Case
+
+Use this plugin when:
+
+* You need to validate that a value matches a specific regex pattern
+* You want the validation to optionally ignore case sensitivity
+* You want to easily enforce custom format rules in your flows
+
+## 🔧 Configuration
+
+### Minimal Example
+
+```yaml
+- type: regex
+  name: myRegexValidator
+  pattern: ^[a-z0-9_-]{3,16}$
+```
+
+This will validate that the value contains 3 to 16 characters consisting of lowercase letters, digits, hyphens, or underscores.
+
+### Full Example
+
+```yaml
+- type: regex
+  name: myRegexValidator
+  pattern: ^hello.*world$
+  insensitive: true
+```
+
+This will validate values against the regex `^hello.*world$`, ignoring case (e.g., `Hello my World`, `hello WORLD`, etc.).
+
+### Configuration Fields
+
+| Key           | Required | Description                                                                  |
+| ------------- | -------- | ---------------------------------------------------------------------------- |
+| `pattern`     | ✅        | The regular expression used to validate the value.                           |
+| `insensitive` | ❌        | Boolean flag to enable case-insensitive matching (`true`). Default: `false`. |
+
+## 🛠 Behavior
+
+* The plugin retrieves the value to validate from the context (as defined by the hosting engine).
+* It applies the provided `pattern` to the value.
+* If `insensitive` is set to `true`, case is ignored during validation.
+* If the value does not match the pattern, a validation error is raised.
+
+## 🧷 Notes
+
+* The plugin uses Java regular expressions (`java.util.regex`).
+* If the `pattern` is invalid, a configuration error will be raised at startup.
+* The `insensitive` field is optional and defaults to `false`.
diff --git a/regex-validation/pom.xml b/regex-validation/pom.xml
@@ -0,0 +1,27 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>io.github.linagora.linid.im</groupId>
+        <artifactId>linid-im-api-community-plugins</artifactId>
+        <version>0.1.0</version>
+        <relativePath>../pom.xml</relativePath>
+    </parent>
+
+    <properties>
+        <sonar.projectBaseDir>regex-validation</sonar.projectBaseDir>
+    </properties>
+
+    <artifactId>regex-validation-plugin</artifactId>
+    <version>0.1.0</version>
+    <name>regex-validation-plugin</name>
+    <description>Plugin to validate field with regex</description>
+
+    <dependencies>
+        <!-- Add here dependencies specific to this plugin if needed -->
+    </dependencies>
+
+</project>
diff --git a/regex-validation/src/main/java/io/github/linagora/linid/im/rvp/RegexValidationPlugin.java b/regex-validation/src/main/java/io/github/linagora/linid/im/rvp/RegexValidationPlugin.java
@@ -0,0 +1,90 @@
+/*
+ * Copyright (C) 2020-2025 Linagora
+ *
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General
+ * Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option)
+ * any later version, provided you comply with the Additional Terms applicable for LinID Directory Manager software by
+ * LINAGORA pursuant to Section 7 of the GNU Affero General Public License, subsections (b), (c), and (e), pursuant to
+ * which these Appropriate Legal Notices must notably (i) retain the display of the "LinID™" trademark/logo at the top
+ * of the interface window, the display of the “You are using the Open Source and free version of LinID™, powered by
+ * Linagora © 2009–2013. Contribute to LinID R&D by subscribing to an Enterprise offer!” infobox and in the e-mails
+ * sent with the Program, notice appended to any type of outbound messages (e.g. e-mail and meeting requests) as well
+ * as in the LinID Directory Manager user interface, (ii) retain all hypertext links between LinID Directory Manager
+ * and https://linid.org/, as well as between LINAGORA and LINAGORA.com, and (iii) refrain from infringing LINAGORA
+ * intellectual property rights over its trademarks and commercial brands. Other Additional Terms apply, see
+ * <http://www.linagora.com/licenses/> for more details.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
+ * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Affero General Public License and its applicable Additional Terms for
+ * LinID Directory Manager along with this program. If not, see <http://www.gnu.org/licenses/> for the GNU Affero
+ * General Public License version 3 and <http://www.linagora.com/licenses/> for the Additional Terms applicable to the
+ * LinID Directory Manager software.
+ */
+
+package io.github.linagora.linid.im.rvp;
+
+import java.util.Map;
+import java.util.Optional;
+import java.util.regex.Pattern;
+import java.util.regex.PatternSyntaxException;
+import io.github.linagora.linid.im.corelib.exception.ApiException;
+import io.github.linagora.linid.im.corelib.i18n.I18nMessage;
+import io.github.linagora.linid.im.corelib.plugin.config.dto.ValidationConfiguration;
+import io.github.linagora.linid.im.corelib.plugin.validation.ValidationPlugin;
+import org.springframework.lang.NonNull;
+import org.springframework.stereotype.Component;
+
+
+/**
+ * A {@link ValidationPlugin} implementation that validates a value using a regular expression.
+ */
+@Component
+public class RegexValidationPlugin implements ValidationPlugin {
+
+  @Override
+  public boolean supports(@NonNull String type) {
+    return "regex".equals(type);
+  }
+
+  @Override
+  public Optional<I18nMessage> validate(ValidationConfiguration configuration, Object value) {
+    var regex = configuration.getOption("pattern")
+        .orElseThrow(() -> new ApiException(
+            500,
+            I18nMessage.of("error.plugin.default.missing.option", Map.of("option", "pattern"))
+        ));
+    boolean insensitive = configuration.getOption("insensitive", Boolean.class)
+        .orElse(false);
+
+    Pattern pattern;
+
+    try {
+      if (insensitive) {
+        pattern = Pattern.compile(regex, Pattern.CASE_INSENSITIVE);
+      } else {
+        pattern = Pattern.compile(regex);
+      }
+
+    } catch (PatternSyntaxException exception) {
+      throw new ApiException(
+          500,
+          I18nMessage.of("error.plugin.default.invalid.option", Map.of(
+              "option", "pattern",
+              "value", regex
+          ))
+      );
+    }
+
+    if (pattern.matcher(value.toString()).matches()) {
+      return Optional.empty();
+    }
+
+    return Optional.of(I18nMessage.of(
+        "error.plugin.regexValidation.invalid.value",
+        Map.of("pattern", regex,  "value", value)
+    ));
+  }
+}
diff --git a/regex-validation/src/main/resources/i18n/en.json b/regex-validation/src/main/resources/i18n/en.json
@@ -0,0 +1 @@
+{}
diff --git a/regex-validation/src/main/resources/i18n/fr.json b/regex-validation/src/main/resources/i18n/fr.json
@@ -0,0 +1 @@
+{}
diff --git a/regex-validation/src/test/java/io/github/linagora/linid/im/rvp/RegexValidationPluginTest.java b/regex-validation/src/test/java/io/github/linagora/linid/im/rvp/RegexValidationPluginTest.java
@@ -0,0 +1,136 @@
+/*
+ * Copyright (C) 2020-2025 Linagora
+ *
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General
+ * Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option)
+ * any later version, provided you comply with the Additional Terms applicable for LinID Directory Manager software by
+ * LINAGORA pursuant to Section 7 of the GNU Affero General Public License, subsections (b), (c), and (e), pursuant to
+ * which these Appropriate Legal Notices must notably (i) retain the display of the "LinID™" trademark/logo at the top
+ * of the interface window, the display of the “You are using the Open Source and free version of LinID™, powered by
+ * Linagora © 2009–2013. Contribute to LinID R&D by subscribing to an Enterprise offer!” infobox and in the e-mails
+ * sent with the Program, notice appended to any type of outbound messages (e.g. e-mail and meeting requests) as well
+ * as in the LinID Directory Manager user interface, (ii) retain all hypertext links between LinID Directory Manager
+ * and https://linid.org/, as well as between LINAGORA and LINAGORA.com, and (iii) refrain from infringing LINAGORA
+ * intellectual property rights over its trademarks and commercial brands. Other Additional Terms apply, see
+ * <http://www.linagora.com/licenses/> for more details.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
+ * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Affero General Public License and its applicable Additional Terms for
+ * LinID Directory Manager along with this program. If not, see <http://www.gnu.org/licenses/> for the GNU Affero
+ * General Public License version 3 and <http://www.linagora.com/licenses/> for the Additional Terms applicable to the
+ * LinID Directory Manager software.
+ */
+
+package io.github.linagora.linid.im.rvp;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.Map;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import io.github.linagora.linid.im.corelib.exception.ApiException;
+import io.github.linagora.linid.im.corelib.plugin.config.dto.ValidationConfiguration;
+
+@DisplayName("Test class: RegexValidationPlugin")
+public class RegexValidationPluginTest {
+
+  @Test
+  @DisplayName("test supports: should return true on valid type")
+  void testSupports() {
+    var plugin = new RegexValidationPlugin();
+
+    assertTrue(plugin.supports("regex"));
+    assertFalse(plugin.supports("other"));
+  }
+
+  @Test
+  @DisplayName("test validate: should thrown an exception on missing pattern option")
+  void testValidateMissingPatternOption() {
+    var plugin = new RegexValidationPlugin();
+    var configuration = new ValidationConfiguration();
+
+    ApiException exception = assertThrows(ApiException.class, () -> plugin.validate(configuration, ""));
+
+    assertEquals(500, exception.getStatusCode());
+    assertEquals("error.plugin.default.missing.option", exception.getError().key());
+    assertEquals(Map.of("option", "pattern"), exception.getError().context());
+  }
+
+  @Test
+  @DisplayName("test validate: should thrown an exception on invalid pattern option")
+  void testValidateInvalidPatternOption() {
+    var plugin = new RegexValidationPlugin();
+    var configuration = new ValidationConfiguration();
+    configuration.addOption("pattern", "[a-z");
+
+    ApiException exception = assertThrows(ApiException.class, () -> plugin.validate(configuration, ""));
+
+    assertEquals(500, exception.getStatusCode());
+    assertEquals("error.plugin.default.invalid.option", exception.getError().key());
+    assertEquals(Map.of("option", "pattern", "value", "[a-z"), exception.getError().context());
+  }
+
+  @Test
+  @DisplayName("test validate: should thrown an exception on invalid insensitive pattern option")
+  void testValidateInvalidInsensitivePatternOption() {
+    var plugin = new RegexValidationPlugin();
+    var configuration = new ValidationConfiguration();
+    configuration.addOption("pattern", "[a-z");
+    configuration.addOption("insensitive", true);
+
+    ApiException exception = assertThrows(ApiException.class, () -> plugin.validate(configuration, ""));
+
+    assertEquals(500, exception.getStatusCode());
+    assertEquals("error.plugin.default.invalid.option", exception.getError().key());
+    assertEquals(Map.of("option", "pattern", "value", "[a-z"), exception.getError().context());
+  }
+
+  @Test
+  @DisplayName("test validate: should return message on invalid value")
+  void testValidateInvalidValue() {
+    var plugin = new RegexValidationPlugin();
+    var configuration = new ValidationConfiguration();
+    configuration.addOption("pattern", "[a-z]{1}");
+
+    var error = plugin.validate(configuration, "A");
+
+    assertNotNull(error);
+    assertTrue(error.isPresent());
+    assertEquals("error.plugin.regexValidation.invalid.value", error.get().key());
+    assertEquals(Map.of("pattern", "[a-z]{1}", "value", "A"), error.get().context());
+  }
+
+  @Test
+  @DisplayName("test validate: should not return message on valid value")
+  void testValidateValidValue() {
+    var plugin = new RegexValidationPlugin();
+    var configuration = new ValidationConfiguration();
+    configuration.addOption("pattern", "[a-z]{1}");
+
+    var error = plugin.validate(configuration, "a");
+
+    assertNotNull(error);
+    assertTrue(error.isEmpty());
+  }
+
+  @Test
+  @DisplayName("test validate: should not return message on insensitive valid value")
+  void testValidateInsensitiveValidValue() {
+    var plugin = new RegexValidationPlugin();
+    var configuration = new ValidationConfiguration();
+    configuration.addOption("pattern", "[a-z]{1}");
+    configuration.addOption("insensitive", true);
+
+    var error = plugin.validate(configuration, "A");
+
+    assertNotNull(error);
+    assertTrue(error.isEmpty());
+  }
+}
