feat(engine): script preprocessing feature addition to fluxnova engine (#184)

Author: HarishMalavade

engine/pom.xml

@@ -116,6 +116,12 @@
       <artifactId>gson</artifactId>
     </dependency>
 
+    <dependency>
+      <groupId>commons-codec</groupId>
+      <artifactId>commons-codec</artifactId>
+      <version>1.15</version>
+    </dependency>
+
     <!-- provided dependencies -->
 
     <dependency>

engine/src/main/java/org/finos/fluxnova/bpm/engine/impl/cfg/ProcessEngineConfigurationImpl.java

@@ -347,6 +347,8 @@
 import org.finos.fluxnova.bpm.engine.impl.scripting.engine.VariableScopeResolverFactory;
 import org.finos.fluxnova.bpm.engine.impl.scripting.env.ScriptEnvResolver;
 import org.finos.fluxnova.bpm.engine.impl.scripting.env.ScriptingEnvironment;
+import org.finos.fluxnova.bpm.engine.impl.scripting.preprocessor.CompositeScriptPreprocessor;
+import org.finos.fluxnova.bpm.engine.impl.scripting.preprocessor.ScriptPreprocessor;
 import org.finos.fluxnova.bpm.engine.impl.telemetry.dto.DatabaseImpl;
 import org.finos.fluxnova.bpm.engine.impl.telemetry.dto.InternalsImpl;
 import org.finos.fluxnova.bpm.engine.impl.telemetry.dto.JdkImpl;
@@ -608,6 +610,10 @@ public abstract class ProcessEngineConfigurationImpl extends ProcessEngineConfig
   protected boolean enableScriptEngineNashornCompatibility = false;
   protected boolean configureScriptEngineHostAccess = true;
   protected boolean skipIsolationLevelCheck = false;
+  private volatile boolean enableScriptPreprocessing = false;
+  private volatile List<ScriptPreprocessor> scriptPreprocessors;
+  private volatile ScriptPreprocessor effectiveScriptPreprocessor;
+  private final Object scriptPreprocessorLock = new Object();
 
   /**
    * When set to false, the following behavior changes:
@@ -4266,6 +4272,50 @@ public void setScriptFactory(ScriptFactory scriptFactory) {
     this.scriptFactory = scriptFactory;
   }
 
+  /**
+   * @return whether script preprocessing is enabled for script execution.
+   */
+  public boolean isEnableScriptPreprocessing() {
+    return enableScriptPreprocessing;
+  }
+
+  /**
+   * Enables/disables script preprocessing and resets the cached effective preprocessor.
+   */
+  public void setEnableScriptPreprocessing(boolean enableScriptPreprocessing) {
+    synchronized (scriptPreprocessorLock) {
+      this.enableScriptPreprocessing = enableScriptPreprocessing;
+      this.effectiveScriptPreprocessor = null;
+    }
+  }
+
+  /**
+   * @return a copy of configured preprocessors, or {@code null} when none are configured.
+   */
+  public List<ScriptPreprocessor> getScriptPreprocessors() {
+    synchronized (scriptPreprocessorLock) {
+      if (scriptPreprocessors == null) {
+        return null;
+      }
+      return new ArrayList<>(scriptPreprocessors);
+    }
+  }
+
+  /**
+   * Replaces configured preprocessors and resets the cached effective preprocessor.
+   */
+  public void setScriptPreprocessors(List<ScriptPreprocessor> scriptPreprocessors) {
+    synchronized (scriptPreprocessorLock) {
+      if (scriptPreprocessors == null) {
+        this.scriptPreprocessors = null;
+      } else {
+        this.scriptPreprocessors = new ArrayList<>(scriptPreprocessors);
+      }
+      this.effectiveScriptPreprocessor = null;
+    }
+  }
+
+
   public ScriptEngineResolver getScriptEngineResolver() {
     return scriptEngineResolver;
   }
@@ -5330,4 +5380,56 @@ public ProcessEngineConfiguration setLegacyJobRetryBehaviorEnabled(boolean legac
     this.legacyJobRetryBehaviorEnabled = legacyJobRetryBehaviorEnabled;
     return this;
   }
+
+  /**
+   * Adds a preprocessor to the configured chain and invalidates the cached effective preprocessor.
+   */
+  public void addScriptPreprocessor(ScriptPreprocessor scriptPreprocessor) {
+    if (scriptPreprocessor == null) {
+      return;
+    }
+    synchronized (scriptPreprocessorLock) {
+      List<ScriptPreprocessor> updatedScriptPreprocessors = this.scriptPreprocessors == null
+          ? new ArrayList<>()
+          : new ArrayList<>(this.scriptPreprocessors);
+      updatedScriptPreprocessors.add(scriptPreprocessor);
+      this.scriptPreprocessors = updatedScriptPreprocessors;
+      this.effectiveScriptPreprocessor = null;
+    }
+  }
+
+  /**
+   * Returns the effective preprocessor for runtime use.
+   *
+   * @return {@code null} when preprocessing is disabled or no preprocessors are configured.
+   */
+  public ScriptPreprocessor getEffectiveScriptPreprocessor() {
+    if (!enableScriptPreprocessing) {
+      return null;
+    }
+    ScriptPreprocessor cached = effectiveScriptPreprocessor;
+    if (cached != null) {
+      return cached;
+    }
+
+    synchronized (scriptPreprocessorLock) {
+      if (!enableScriptPreprocessing) {
+        return null;
+      }
+
+      if (effectiveScriptPreprocessor == null) {
+        List<ScriptPreprocessor> configuredScriptPreprocessors = scriptPreprocessors;
+        if (configuredScriptPreprocessors == null || configuredScriptPreprocessors.isEmpty()) {
+          return null;
+        }
+
+        if (configuredScriptPreprocessors.size() == 1) {
+          effectiveScriptPreprocessor = configuredScriptPreprocessors.get(0);
+        } else {
+          effectiveScriptPreprocessor = new CompositeScriptPreprocessor(new ArrayList<>(configuredScriptPreprocessors));
+        }
+      }
+      return effectiveScriptPreprocessor;
+    }
+  }
 }

engine/src/main/java/org/finos/fluxnova/bpm/engine/impl/scripting/CompiledExecutableScript.java

@@ -30,7 +30,7 @@ public class CompiledExecutableScript extends ExecutableScript {
 
   private final static ScriptLogger LOG = ProcessEngineLogger.SCRIPT_LOGGER;
 
-  protected CompiledScript compiledScript;
+  protected volatile CompiledScript compiledScript;
 
   protected CompiledExecutableScript(String language) {
     this(language, null);
@@ -50,9 +50,13 @@ public void setCompiledScript(CompiledScript compiledScript) {
   }
 
   public Object evaluate(ScriptEngine scriptEngine, VariableScope variableScope, Bindings bindings) {
+    return evaluateCompiledScript(getCompiledScript(), variableScope, bindings);
+  }
+
+  protected Object evaluateCompiledScript(CompiledScript compiledScript, VariableScope variableScope, Bindings bindings) {
     try {
       LOG.debugEvaluatingCompiledScript(language);
-      return getCompiledScript().eval(bindings);
+      return compiledScript.eval(bindings);
     } catch (ScriptException e) {
       if (e.getCause() instanceof BpmnError) {
         throw (BpmnError) e.getCause();

engine/src/main/java/org/finos/fluxnova/bpm/engine/impl/scripting/DynamicExecutableScript.java

@@ -41,6 +41,7 @@ protected DynamicExecutableScript(Expression scriptExpression, String language)
 
   public Object evaluate(ScriptEngine scriptEngine, VariableScope variableScope, Bindings bindings) {
     String source = getScriptSource(variableScope);
+    source = preprocessScript(source, variableScope);
     try {
       return scriptEngine.eval(source, bindings);
     }

engine/src/main/java/org/finos/fluxnova/bpm/engine/impl/scripting/ExecutableScript.java

@@ -23,7 +23,12 @@
 import org.finos.fluxnova.bpm.engine.delegate.DelegateCaseExecution;
 import org.finos.fluxnova.bpm.engine.delegate.DelegateExecution;
 import org.finos.fluxnova.bpm.engine.delegate.VariableScope;
+import org.finos.fluxnova.bpm.engine.impl.ProcessEngineLogger;
+import org.finos.fluxnova.bpm.engine.impl.cfg.ProcessEngineConfigurationImpl;
+import org.finos.fluxnova.bpm.engine.impl.context.Context;
 import org.finos.fluxnova.bpm.engine.impl.persistence.entity.TaskEntity;
+import org.finos.fluxnova.bpm.engine.impl.scripting.preprocessor.ScriptPreprocessor;
+import org.finos.fluxnova.bpm.engine.impl.scripting.preprocessor.ScriptPreprocessorRequest;
 
 /**
  * <p>Represents an executable script.</p>
@@ -34,6 +39,8 @@
  */
 public abstract class ExecutableScript {
 
+  private static final ScriptLogger LOG = ProcessEngineLogger.SCRIPT_LOGGER;
+
   /** The language of the script. Used to resolve the
    * {@link ScriptEngine}. */
   protected final String language;
@@ -94,4 +101,60 @@ protected String getActivityIdExceptionMessage(VariableScope variableScope) {
 
   protected abstract Object evaluate(ScriptEngine scriptEngine, VariableScope variableScope, Bindings bindings);
 
+  /**
+   * Preprocesses a script before execution.
+   *
+   * <p>If script preprocessing is disabled, no preprocessor is configured, or the preprocessor
+   * returns {@code null}, the original script is returned unchanged.</p>
+   *
+   * <p>If preprocessing fails with an exception, a warning is logged and the original script is
+   * returned as a safe fallback to ensure scripts continue to execute.</p>
+   *
+   * @param script the script text to preprocess; may be {@code null}
+   * @param variableScope the current execution context; may be {@code null}
+   * @return the preprocessed script, or the original script if preprocessing is disabled,
+   *         not configured, returns {@code null}, or fails with an exception
+   */
+  protected String preprocessScript(String script, VariableScope variableScope) {
+    if (script == null) {
+      return script;
+    }
+
+    ProcessEngineConfigurationImpl processEngineConfiguration = Context.getProcessEngineConfiguration();
+    if (processEngineConfiguration == null
+        || !processEngineConfiguration.isEnableScriptPreprocessing()) {
+      return script;
+    }
+
+    ScriptPreprocessor scriptPreprocessor = processEngineConfiguration.getEffectiveScriptPreprocessor();
+    if (scriptPreprocessor == null) {
+      return script;
+    }
+
+    String preprocessorName = getPreprocessorName(scriptPreprocessor);
+
+    ScriptPreprocessorRequest request = new ScriptPreprocessorRequest(script, language, variableScope);
+    String processedScript;
+    try {
+      processedScript = scriptPreprocessor.process(request);
+    } catch (Throwable e) {
+      LOG.warnScriptPreprocessingFailed(language, preprocessorName, e);
+      return script;
+    }
+
+    if (processedScript == null) {
+      return script;
+    }
+
+    return processedScript;
+  }
+
+  private String getPreprocessorName(ScriptPreprocessor scriptPreprocessor) {
+    try {
+      String name = scriptPreprocessor.getName();
+      return name != null ? name : "<unknown>";
+    } catch (Exception e) {
+      return "<unknown>";
+    }
+  }
 }

engine/src/main/java/org/finos/fluxnova/bpm/engine/impl/scripting/ScriptFactory.java

@@ -19,10 +19,16 @@
 import org.finos.fluxnova.bpm.engine.delegate.Expression;
 
 /**
- * <p>A script factory is responsible for creating a {@link ExecutableScript}
- * instance. Users may customize (subclass) this class in order to customize script
- * creation. For instance, some users may choose to pre-process scripts before
- * they are created.</p>
+ * <p>A script factory is responsible for creating {@link ExecutableScript}
+ * instances. Users may customize (subclass) this class in order to customize script
+ * creation.</p>
+ *
+ * <p>The default executable script implementations created by this factory preserve
+ * configured script preprocessing behavior automatically. Custom subclasses that
+ * return their own {@link ExecutableScript} implementations should ensure that
+ * configured script preprocessors are still applied before evaluation if they
+ * want those custom implementations to participate in the script preprocessing
+ * feature.</p>
  *
  * @author Daniel Meyer
  *

engine/src/main/java/org/finos/fluxnova/bpm/engine/impl/scripting/ScriptLogger.java

@@ -39,4 +39,24 @@ public void debugEvaluatingNonCompiledScript(String scriptSource) {
         "001", "Evaluating non-compiled script {}", scriptSource);
   }
 
+  public void warnScriptPreprocessorRequestNull(String preprocessorName) {
+    logWarn(
+        "004",
+        "ScriptPreprocessorRequest is null in preprocessor {}; returning null (no preprocessing will be done).",
+        preprocessorName);
+  }
+
+  public void warnScriptPreprocessingFailed(
+      String language,
+      String preprocessorName,
+      Throwable throwable) {
+    logWarn(
+        "005",
+        "Script preprocessing failed for language {} using preprocessor {}. Error: {}. Falling back to the original script.",
+        language,
+        preprocessorName,
+        throwable.getMessage(),
+        throwable);
+  }
+
 }