ScriptTrigger.java

package io.kestra.plugin.scripts.python;

import io.kestra.core.models.annotations.Example;
import io.kestra.core.models.annotations.Plugin;
import io.kestra.core.models.conditions.ConditionContext;
import io.kestra.core.models.executions.Execution;
import io.kestra.core.models.property.Property;
import io.kestra.core.models.tasks.RunnableTaskException;
import io.kestra.core.models.tasks.runners.TaskException;
import io.kestra.core.models.triggers.*;
import io.kestra.core.runners.RunContext;
import io.kestra.plugin.core.runner.Process;
import io.kestra.plugin.scripts.exec.scripts.models.ScriptOutput;
import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.NotNull;
import lombok.*;
import lombok.experimental.SuperBuilder;

import java.time.Duration;
import java.time.Instant;
import java.util.Map;
import java.util.Optional;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

@SuperBuilder
@ToString
@EqualsAndHashCode
@Getter
@NoArgsConstructor
@Schema(title = "Trigger a flow when a Python script matches a condition.")
@Plugin(
    examples = {
        @Example(
            title = "Trigger when the script fails with an implicit error (exit 1).",
            full = true,
            code = """
                id: script_trigger
                namespace: company.team

                triggers:
                  - id: script_failure
                    type: io.kestra.plugin.scripts.python.ScriptTrigger
                    interval: PT10S
                    exitCondition: "exit 1"
                    edge: true
                    containerImage: ubuntu
                    script: |
                      # This command fails because the file doesn't exist, resulting in a non-zero exit code.
                      import os
                      os.listdir("/path/that/does/not/exist")

                tasks:
                  - id: log
                    type: io.kestra.plugin.core.log.Log
                    message: "Triggered with exitCode={{ trigger.exitCode }} (condition={{ trigger.condition }})"
                """
        )
    }
)
public class ScriptTrigger extends AbstractTrigger
    implements PollingTriggerInterface, TriggerOutput<ScriptTrigger.Output> {

    private static final String DEFAULT_IMAGE = "ubuntu";

    @Schema(
        title = "Docker image used to execute the script.",
        description = """
            Container image used by the underlying Script task to run the inline shell script.
            Defaults to 'ubuntu'.
            """
    )
    @Builder.Default
    protected Property<String> containerImage = Property.ofValue(DEFAULT_IMAGE);

    @Schema(
        title = "Inline python script to execute.",
        description = """
            Inline script content (multi-line string). This is the same 'script' concept as the Python Script task.
            The script is executed on each poll.
            """
    )
    @NotNull
    protected Property<String> script;

    @Schema(
        title = "Condition to match.",
        description = """
            Condition evaluated after each script execution. The trigger emits an event only when this condition matches.

            Supported forms:
            - 'exit N' (example: 'exit 1'): matches when the script exit code equals N.
            - Any other string: treated as a regex (or substring if regex is invalid) matched against:
              - the task 'vars' (when the script emits ::{"outputs":...}::),
              - and error logs when the task fails (TaskException).
            """
    )
    @NotNull
    protected Property<String> exitCondition;

    @Schema(
        title = "Check interval",
        description = """
            Interval between polling evaluations. The scheduler uses this interval to compute the next evaluation date.
            """
    )
    @Builder.Default
    private final Duration interval = Duration.ofSeconds(60);

    @Schema(
        title = "Edge trigger mode.",
        description = """
            If true, the trigger emits only on a transition from 'not matching' to 'matching' (anti-spam).
            If false, the trigger emits on every poll where the condition matches.
            """
    )
    @Builder.Default
    protected Property<Boolean> edge = Property.ofValue(true);

    @Builder.Default
    @Getter(AccessLevel.NONE)
    private final AtomicBoolean lastMatched = new AtomicBoolean(false);

    /**
     * Evaluate the trigger by executing the configured script and decide whether to emit an execution
     * based on the rendered exit condition and the `edge` setting.
     *
     * If emission criteria are met, produces an Execution populated with the evaluated Output.
     *
     * @param conditionContext the condition evaluation context containing the RunContext
     * @param context the trigger invocation context used when generating an Execution
     * @return an Optional containing an Execution when the trigger should emit, or an empty Optional otherwise
     */
    @Override
    public Optional<Execution> evaluate(ConditionContext conditionContext, TriggerContext context) throws Exception {
        RunContext runContext = conditionContext.getRunContext();
        boolean rEdge = runContext.render(this.edge).as(Boolean.class).orElse(true);

        Output out = runOnce(runContext);

        // USE exitCondition to decide whether to emit
        boolean matched = matchesCondition(out);

        boolean emit = rEdge
            ? (!lastMatched.getAndSet(matched) && matched)
            : matched;

        if (!emit) {
            return Optional.empty();
        }

        return Optional.of(TriggerService.generateExecution(this, conditionContext, context, out));
    }

    /**
     * Execute the configured script once and produce an Output snapshot for this poll.
     *
     * Renders the trigger's exitCondition using the provided RunContext, runs the script task,
     * and returns an Output containing the poll timestamp, rendered condition, script exit code,
     * any produced vars (on successful execution) or captured failure logs (on execution failure).
     *
     * @param runContext the execution context used to render properties and run the script
     * @return an Output with timestamp, rendered condition, exitCode, vars (when available), and logs (on failure)
     * @throws Exception if rendering or task execution fails unexpectedly
     */
    private Output runOnce(RunContext runContext) throws Exception {
        Script task = Script.builder()
            .taskRunner(Process.instance())
            .containerImage(this.containerImage)
            .script(this.script)
            .build();

        String rExitCondition = runContext.render(this.exitCondition).as(String.class).orElse("");

        try {
            ScriptOutput taskOutput = task.run(runContext);
            Integer exitCode = safeExitCode(taskOutput);

            // vars are the only reliable structured "result" we can read on success
            Map<String, Object> vars = safeVars(taskOutput);

            return new Output(Instant.now(), rExitCondition, exitCode, vars, null);
        } catch (RunnableTaskException e) {
            ExtractedFailure failure = extractFailure(e);
            return new Output(Instant.now(), rExitCondition, failure.exitCode, null, failure.logs);
        }
    }

    /**
     * Determines whether the given output satisfies the trigger's exitCondition.
     *
     * Supports the special form "exit N" which matches when the output's exit code equals N.
     * For other conditions, the condition is treated as a regular expression applied to the concatenation of the task's vars and logs; if the regex is invalid, falls back to a plain substring containment check. If either the rendered condition or the haystack is empty, the result is `false`.
     *
     * @param out the trigger execution output to evaluate
     * @return `true` if the output matches the configured condition, `false` otherwise
     */
    private boolean matchesCondition(Output out) {
        String cond = out.getCondition() == null ? "" : out.getCondition().trim();

        // 1) exit N
        Matcher exitMatcher = Pattern.compile("^\\s*exit\\s+(\\d+)\\s*$", Pattern.CASE_INSENSITIVE).matcher(cond);
        if (exitMatcher.matches()) {
            int expected = Integer.parseInt(exitMatcher.group(1));
            return out.getExitCode() != null && out.getExitCode() == expected;
        }

        // 2) otherwise: regex (fallback contains) on vars + logs
        String haystack = buildHaystack(out);
        if (haystack.isEmpty() || cond.isEmpty()) {
            return false;
        }

        try {
            return Pattern.compile(cond).matcher(haystack).find();
        } catch (Exception invalidRegex) {
            return haystack.contains(cond);
        }
    }

    /**
     * Concatenates the trigger output's vars and logs into a single newline-separated string.
     *
     * @param out the trigger output containing optional vars and logs
     * @return a string containing the vars (if present) followed by the logs (if present), each terminated by a newline; empty string if neither is present
     */
    private String buildHaystack(Output out) {
        StringBuilder sb = new StringBuilder();

        if (out.getVars() != null && !out.getVars().isEmpty()) {
            sb.append(out.getVars()).append("\n");
        }
        if (out.getLogs() != null && !out.getLogs().isBlank()) {
            sb.append(out.getLogs()).append("\n");
        }

        return sb.toString();
    }

    /**
     * Extracts the exit code from the given ScriptOutput, or returns null if it cannot be read.
     *
     * @param taskOutput the script task output to read the exit code from
     * @return the exit code, or `null` if the exit code is unavailable or an error occurs while reading it
     */
    private Integer safeExitCode(ScriptOutput taskOutput) {
        try {
            return taskOutput.getExitCode();
        } catch (Exception ignored) {
            return null;
        }
    }

    /**
     * Retrieve the task's `vars` map, returning null if it cannot be read.
     *
     * @param taskOutput the script task output to extract variables from
     * @return the `vars` map produced by the task, or `null` if unavailable or an error occurs
     */
    private Map<String, Object> safeVars(ScriptOutput taskOutput) {
        try {
            return taskOutput.getVars();
        } catch (Exception ignored) {
            return null;
        }
    }

    private record ExtractedFailure(Integer exitCode, String logs) {}

    /**
     * Extracts the task exit code and available logs from a RunnableTaskException by locating an underlying TaskException.
     *
     * @param e the RunnableTaskException thrown during task execution
     * @return an ExtractedFailure containing the extracted exit code (may be null) and captured logs (may be null)
     */
    private ExtractedFailure extractFailure(RunnableTaskException e) {
        Integer exitCode = null;
        String logs = null;

        Throwable cur = e.getCause();
        while (cur != null) {
            if (cur instanceof TaskException te) {
                exitCode = te.getExitCode();
                // Best-effort: TaskException carries a log consumer; toString() usually contains aggregated logs.
                try {
                    logs = te.getLogConsumer() != null ? te.getLogConsumer().toString() : null;
                } catch (Exception ignored) {}
                break;
            }
            cur = cur.getCause();
        }

        return new ExtractedFailure(exitCode, logs);
    }

    @Data
    @AllArgsConstructor
    public static class Output implements io.kestra.core.models.tasks.Output {
        private Instant timestamp;

        @Schema(
            title = "Rendered condition.",
            description = "Rendered value of the exitCondition property for this poll."
        )
        private String condition;

        @Schema(
            title = "Script exit code.",
            description = "Exit code returned by the shell process (may be null if not available)."
        )
        private Integer exitCode;

        @Schema(
            title = "Script vars.",
            description = """
                Vars produced by the task (e.g. via ::{"outputs":{...}}:: convention). This is the main structured
                way to evaluate non-exit conditions on successful runs.
                """
        )
        private Map<String, Object> vars;

        @Schema(
            title = "Captured logs (best effort).",
            description = "Captured error logs when the script fails (best effort, depends on the runner)."
        )
        private String logs;
    }
}