feat(templates): add TemplatePayloadInfo and restrict tx validation to apply payloads (#857)

dieppa · claude · web-flow · commit 8cb45bd38035 · 2026-03-08T11:48:49.000+08:00
- Add **TemplatePayloadInfo** class with `supportsTransactions` field so payloads can
  declare transaction compatibility via `TemplatePayload.getInfo()`
- Implement `getInfo()` in **TemplateString**, **TemplateVoid**, and test payload stubs
- Add `checkPayloadTransactionSupport()` and `getExplicitTransactionSupport()` helpers
  to **AbstractTemplateLoadedChange** for centralized transaction-support checking
- Restrict transaction-support validation to **apply payloads only** — configuration
  is shared state and rollback is a compensating action, neither represents an actual
  operation against a target system
- `warnIfAllPayloadsSupportTransactions()` now inspects only apply payloads in both
  **SimpleTemplateLoadedChange** and **MultiStepTemplateLoadedChange**
- Add **PayloadTransactionSupportValidationTest** with 10 cases covering error, warning,
  and not-checked paths for both simple and multi-step templates

Co-authored-by: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/core/flamingock-core-api/src/main/java/io/flamingock/api/template/TemplatePayload.java b/core/flamingock-core-api/src/main/java/io/flamingock/api/template/TemplatePayload.java
@@ -33,4 +33,12 @@ public interface TemplatePayload {
      * @return list of validation errors, empty if payload is valid
      */
     List<TemplatePayloadValidationError> validate(TemplateValidationContext context);
+
+    /**
+     * Returns metadata about this payload so the framework can make
+     * centralized decisions based on payload characteristics.
+     *
+     * @return payload info; never {@code null}
+     */
+    TemplatePayloadInfo getInfo();
 }
diff --git a/core/flamingock-core-api/src/main/java/io/flamingock/api/template/TemplatePayloadInfo.java b/core/flamingock-core-api/src/main/java/io/flamingock/api/template/TemplatePayloadInfo.java
@@ -0,0 +1,71 @@
+/*
+ * Copyright 2026 Flamingock (https://www.flamingock.io)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.flamingock.api.template;
+
+import java.util.Optional;
+
+/**
+ * Metadata that a {@link TemplatePayload} exposes to the framework so
+ * centralized decisions can be made based on payload characteristics.
+ *
+ * <p><b>Binary-compatibility contract:</b> new fields are added as
+ * getter/setter pairs.  A {@code null} value means "not specified" —
+ * the payload makes no claim and the framework applies its own policy.
+ * Older implementations that return a default-constructed instance
+ * continue to work unchanged as new fields are introduced.
+ *
+ * <p>Current fields:
+ * <ul>
+ *   <li>{@code supportsTransactions} — whether the payload's target
+ *       system supports transactional execution.  {@code null} (default)
+ *       means the payload makes no claim.</li>
+ * </ul>
+ */
+public class TemplatePayloadInfo {
+
+    private Boolean supportsTransactions;
+
+    /**
+     * Creates an info instance with all fields set to {@code null}
+     * (no claims made).
+     */
+    public TemplatePayloadInfo() {
+    }
+
+    /**
+     * Returns whether the payload's target system supports transactional
+     * execution.
+     *
+     * @return an {@link Optional} containing {@code true} or {@code false}
+     *         if the payload explicitly declares support; empty if the
+     *         payload makes no claim
+     */
+    public Optional<Boolean> getSupportsTransactions() {
+        return Optional.ofNullable(supportsTransactions);
+    }
+
+    /**
+     * Sets whether the payload's target system supports transactional
+     * execution.
+     *
+     * @param supportsTransactions {@code true} if transactions are supported,
+     *                             {@code false} if not, or {@code null} to
+     *                             make no claim
+     */
+    public void setSupportsTransactions(Boolean supportsTransactions) {
+        this.supportsTransactions = supportsTransactions;
+    }
+}
diff --git a/core/flamingock-core-api/src/main/java/io/flamingock/api/template/wrappers/TemplateString.java b/core/flamingock-core-api/src/main/java/io/flamingock/api/template/wrappers/TemplateString.java
@@ -16,6 +16,7 @@
 package io.flamingock.api.template.wrappers;
 
 import io.flamingock.api.template.TemplatePayload;
+import io.flamingock.api.template.TemplatePayloadInfo;
 import io.flamingock.api.template.TemplatePayloadValidationError;
 import io.flamingock.api.template.TemplateValidationContext;
 
@@ -67,6 +68,11 @@ public List<TemplatePayloadValidationError> validate(TemplateValidationContext c
         return Collections.emptyList();
     }
 
+    @Override
+    public TemplatePayloadInfo getInfo() {
+        return new TemplatePayloadInfo();
+    }
+
     @Override
     public String toString() {
         return value;
diff --git a/core/flamingock-core-api/src/main/java/io/flamingock/api/template/wrappers/TemplateVoid.java b/core/flamingock-core-api/src/main/java/io/flamingock/api/template/wrappers/TemplateVoid.java
@@ -16,6 +16,7 @@
 package io.flamingock.api.template.wrappers;
 
 import io.flamingock.api.template.TemplatePayload;
+import io.flamingock.api.template.TemplatePayloadInfo;
 import io.flamingock.api.template.TemplatePayloadValidationError;
 import io.flamingock.api.template.TemplateValidationContext;
 
@@ -36,4 +37,9 @@ public class TemplateVoid implements TemplatePayload {
     public List<TemplatePayloadValidationError> validate(TemplateValidationContext context) {
         return Collections.emptyList();
     }
+
+    @Override
+    public TemplatePayloadInfo getInfo() {
+        return new TemplatePayloadInfo();
+    }
 }
diff --git a/core/flamingock-core-api/src/test/java/io/flamingock/api/template/AbstractChangeTemplateReflectiveClassesTest.java b/core/flamingock-core-api/src/test/java/io/flamingock/api/template/AbstractChangeTemplateReflectiveClassesTest.java
@@ -39,6 +39,11 @@ public static class TestConfig implements TemplatePayload {
         public List<TemplatePayloadValidationError> validate(TemplateValidationContext context) {
             return Collections.emptyList();
         }
+
+        @Override
+        public TemplatePayloadInfo getInfo() {
+            return new TemplatePayloadInfo();
+        }
     }
 
     // Simple test apply payload class
@@ -49,6 +54,11 @@ public static class TestApplyPayload implements TemplatePayload {
         public List<TemplatePayloadValidationError> validate(TemplateValidationContext context) {
             return Collections.emptyList();
         }
+
+        @Override
+        public TemplatePayloadInfo getInfo() {
+            return new TemplatePayloadInfo();
+        }
     }
 
     // Simple test rollback payload class
@@ -59,6 +69,11 @@ public static class TestRollbackPayload implements TemplatePayload {
         public List<TemplatePayloadValidationError> validate(TemplateValidationContext context) {
             return Collections.emptyList();
         }
+
+        @Override
+        public TemplatePayloadInfo getInfo() {
+            return new TemplatePayloadInfo();
+        }
     }
 
     // Additional class for reflection
diff --git a/core/flamingock-core/src/main/java/io/flamingock/internal/core/task/loaded/AbstractTemplateLoadedChange.java b/core/flamingock-core/src/main/java/io/flamingock/internal/core/task/loaded/AbstractTemplateLoadedChange.java
@@ -25,9 +25,12 @@
 import io.flamingock.internal.common.core.task.TargetSystemDescriptor;
 import io.flamingock.internal.core.pipeline.loaded.stage.StageValidationContext;
 import io.flamingock.internal.util.ReflectionUtil;
+import io.flamingock.internal.util.log.FlamingockLoggerFactory;
+import org.slf4j.Logger;
 
 import java.lang.reflect.Constructor;
 import java.lang.reflect.Method;
+import java.util.Collections;
 import java.util.List;
 import java.util.Optional;
 
@@ -42,6 +45,8 @@
  */
 public abstract class AbstractTemplateLoadedChange<CONFIG extends TemplatePayload, APPLY extends TemplatePayload, ROLLBACK extends TemplatePayload> extends AbstractLoadedChange {
 
+    protected static final Logger logger = FlamingockLoggerFactory.getLogger(AbstractTemplateLoadedChange.class);
+
     private final List<String> profiles;
     private final CONFIG configurationPayload;
     protected final boolean rollbackPayloadRequired;
@@ -101,6 +106,7 @@ public List<ValidationError> getValidationErrors(StageValidationContext context)
         errors.addAll(validateConfigurationPayload());
         errors.addAll(validateApplyPayload());
         errors.addAll(validateRollbackPayload());
+        warnIfAllPayloadsSupportTransactions();
         return errors;
     }
 
@@ -110,9 +116,32 @@ protected TemplateValidationContext buildValidationContext() {
         return ctx;
     }
 
+    protected List<ValidationError> checkPayloadTransactionSupport(TemplatePayload payload, String payloadLabel) {
+        if (payload == null) {
+            return Collections.emptyList();
+        }
+        Optional<Boolean> supports = payload.getInfo().getSupportsTransactions();
+        if (isTransactional() && supports.isPresent() && !supports.get()) {
+            return Collections.singletonList(new ValidationError(
+                    String.format("Template '%s' is transactional but %s payload does not support transactions",
+                            getSource(), payloadLabel),
+                    getId(), "change"));
+        }
+        return Collections.emptyList();
+    }
+
+    protected static Boolean getExplicitTransactionSupport(TemplatePayload payload) {
+        if (payload == null) {
+            return null;
+        }
+        return payload.getInfo().getSupportsTransactions().orElse(null);
+    }
+
     abstract protected List<ValidationError> validateConfigurationPayload();
 
     abstract protected List<ValidationError> validateApplyPayload();
 
     abstract protected List<ValidationError> validateRollbackPayload();
+
+    abstract protected void warnIfAllPayloadsSupportTransactions();
 }
diff --git a/core/flamingock-core/src/main/java/io/flamingock/internal/core/task/loaded/MultiStepTemplateLoadedChange.java b/core/flamingock-core/src/main/java/io/flamingock/internal/core/task/loaded/MultiStepTemplateLoadedChange.java
@@ -105,6 +105,7 @@ protected List<ValidationError> validateApplyPayload() {
                                 String.format("Template '%s', step %d apply payload: %s", getSource(), i + 1, e.getFormattedMessage()),
                                 getId(), "change"));
                     }
+                    errors.addAll(checkPayloadTransactionSupport(applyPayload, "step " + (i + 1) + " apply"));
                 }
             }
         }
@@ -134,4 +135,29 @@ protected List<ValidationError> validateRollbackPayload() {
         }
         return errors;
     }
+
+    @Override
+    protected void warnIfAllPayloadsSupportTransactions() {
+        if (isTransactional()) {
+            return;
+        }
+        if (steps == null || steps.isEmpty()) {
+            return;
+        }
+        boolean atLeastOneExplicit = false;
+        for (TemplateStep<APPLY, ROLLBACK> step : steps) {
+            Boolean supports = getExplicitTransactionSupport(step.getApplyPayload());
+            if (supports == null) {
+                continue;
+            }
+            if (!supports) {
+                return;
+            }
+            atLeastOneExplicit = true;
+        }
+        if (atLeastOneExplicit) {
+            logger.warn("Template '{}': all apply payloads support transactions but change is not transactional. " +
+                    "Consider setting transactional=true", getSource());
+        }
+    }
 }
diff --git a/core/flamingock-core/src/main/java/io/flamingock/internal/core/task/loaded/SimpleTemplateLoadedChange.java b/core/flamingock-core/src/main/java/io/flamingock/internal/core/task/loaded/SimpleTemplateLoadedChange.java
@@ -105,22 +105,21 @@ protected List<ValidationError> validateApplyPayload() {
                     String.format("Template '%s' requires 'apply' payload", getSource()),
                     getId(), "change"));
         }
+        List<ValidationError> errors = new ArrayList<>();
         TemplateValidationContext context = buildValidationContext();
         List<TemplatePayloadValidationError> payloadErrors = applyPayload.validate(context);
-        if (!payloadErrors.isEmpty()) {
-            List<ValidationError> errors = new ArrayList<>();
-            for (TemplatePayloadValidationError e : payloadErrors) {
-                errors.add(new ValidationError(
-                        String.format("Template '%s' apply payload: %s", getSource(), e.getFormattedMessage()),
-                        getId(), "change"));
-            }
-            return errors;
+        for (TemplatePayloadValidationError e : payloadErrors) {
+            errors.add(new ValidationError(
+                    String.format("Template '%s' apply payload: %s", getSource(), e.getFormattedMessage()),
+                    getId(), "change"));
         }
-        return Collections.emptyList();
+        errors.addAll(checkPayloadTransactionSupport(applyPayload, "apply"));
+        return errors;
     }
 
     @Override
     protected List<ValidationError> validateRollbackPayload() {
+        List<ValidationError> errors = new ArrayList<>();
         if (rollbackPayloadRequired && rollbackPayload == null) {
             return Collections.singletonList(new ValidationError(
                     String.format("Template '%s' requires 'rollback' payload (rollbackPayloadRequired=true)", getSource()),
@@ -129,16 +128,24 @@ protected List<ValidationError> validateRollbackPayload() {
         if (rollbackPayload != null) {
             TemplateValidationContext context = buildValidationContext();
             List<TemplatePayloadValidationError> payloadErrors = rollbackPayload.validate(context);
-            if (!payloadErrors.isEmpty()) {
-                List<ValidationError> errors = new ArrayList<>();
-                for (TemplatePayloadValidationError e : payloadErrors) {
-                    errors.add(new ValidationError(
-                            String.format("Template '%s' rollback payload: %s", getSource(), e.getFormattedMessage()),
-                            getId(), "change"));
-                }
-                return errors;
+            for (TemplatePayloadValidationError e : payloadErrors) {
+                errors.add(new ValidationError(
+                        String.format("Template '%s' rollback payload: %s", getSource(), e.getFormattedMessage()),
+                        getId(), "change"));
             }
         }
-        return Collections.emptyList();
+        return errors;
+    }
+
+    @Override
+    protected void warnIfAllPayloadsSupportTransactions() {
+        if (isTransactional()) {
+            return;
+        }
+        Boolean supports = getExplicitTransactionSupport(applyPayload);
+        if (Boolean.TRUE.equals(supports)) {
+            logger.warn("Template '{}': apply payload supports transactions but change is not transactional. " +
+                    "Consider setting transactional=true", getSource());
+        }
     }
 }
diff --git a/core/flamingock-core/src/test/java/io/flamingock/internal/core/task/loaded/PayloadTransactionSupportValidationTest.java b/core/flamingock-core/src/test/java/io/flamingock/internal/core/task/loaded/PayloadTransactionSupportValidationTest.java

Original file line number	Diff line number	Diff line change
`@@ -39,6 +39,11 @@ public static class TestConfig implements TemplatePayload {`
`39`	`39`	`public List<TemplatePayloadValidationError> validate(TemplateValidationContext context) {`
`40`	`40`	`return Collections.emptyList();`
`41`	`41`	`}`
	`42`	`+`
	`43`	`+ @Override`
	`44`	`+ public TemplatePayloadInfo getInfo() {`
	`45`	`+ return new TemplatePayloadInfo();`
	`46`	`+ }`
`42`	`47`	`}`
`43`	`48`
`44`	`49`	`// Simple test apply payload class`
`@@ -49,6 +54,11 @@ public static class TestApplyPayload implements TemplatePayload {`
`49`	`54`	`public List<TemplatePayloadValidationError> validate(TemplateValidationContext context) {`
`50`	`55`	`return Collections.emptyList();`
`51`	`56`	`}`
	`57`	`+`
	`58`	`+ @Override`
	`59`	`+ public TemplatePayloadInfo getInfo() {`
	`60`	`+ return new TemplatePayloadInfo();`
	`61`	`+ }`
`52`	`62`	`}`
`53`	`63`
`54`	`64`	`// Simple test rollback payload class`
`@@ -59,6 +69,11 @@ public static class TestRollbackPayload implements TemplatePayload {`
`59`	`69`	`public List<TemplatePayloadValidationError> validate(TemplateValidationContext context) {`
`60`	`70`	`return Collections.emptyList();`
`61`	`71`	`}`
	`72`	`+`
	`73`	`+ @Override`
	`74`	`+ public TemplatePayloadInfo getInfo() {`
	`75`	`+ return new TemplatePayloadInfo();`
	`76`	`+ }`
`62`	`77`	`}`
`63`	`78`
`64`	`79`	`// Additional class for reflection`
Original file line number	Diff line number	Diff line change
`@@ -105,6 +105,7 @@ protected List<ValidationError> validateApplyPayload() {`
`105`	`105`	`String.format("Template '%s', step %d apply payload: %s", getSource(), i + 1, e.getFormattedMessage()),`
`106`	`106`	`getId(), "change"));`
`107`	`107`	`}`
	`108`	`+ errors.addAll(checkPayloadTransactionSupport(applyPayload, "step " + (i + 1) + " apply"));`
`108`	`109`	`}`
`109`	`110`	`}`
`110`	`111`	`}`
`@@ -134,4 +135,29 @@ protected List<ValidationError> validateRollbackPayload() {`
`134`	`135`	`}`
`135`	`136`	`return errors;`
`136`	`137`	`}`
	`138`	`+`
	`139`	`+ @Override`
	`140`	`+ protected void warnIfAllPayloadsSupportTransactions() {`
	`141`	`+ if (isTransactional()) {`
	`142`	`+ return;`
	`143`	`+ }`
	`144`	`+ if (steps == null \|\| steps.isEmpty()) {`
	`145`	`+ return;`
	`146`	`+ }`
	`147`	`+ boolean atLeastOneExplicit = false;`
	`148`	`+ for (TemplateStep<APPLY, ROLLBACK> step : steps) {`
	`149`	`+ Boolean supports = getExplicitTransactionSupport(step.getApplyPayload());`
	`150`	`+ if (supports == null) {`
	`151`	`+ continue;`
	`152`	`+ }`
	`153`	`+ if (!supports) {`
	`154`	`+ return;`
	`155`	`+ }`
	`156`	`+ atLeastOneExplicit = true;`
	`157`	`+ }`
	`158`	`+ if (atLeastOneExplicit) {`
	`159`	`+ logger.warn("Template '{}': all apply payloads support transactions but change is not transactional. " +`
	`160`	`+ "Consider setting transactional=true", getSource());`
	`161`	`+ }`
	`162`	`+ }`
`137`	`163`	`}`