Cancel Plan Preview Command RFC

Signed-off-by: Harshit Gupta <[email protected]>

Author: atpugtihsrah

docs/rfcs/0020-cancel-plan-preview.md

@@ -0,0 +1,36 @@
+- Start Date: 2025-09-17
+- Target Version: 0.x
+
+# Summary
+
+Cancel Plan Preview Command is a command to cancel plan preview commands that have not been picked up by a piped agent.
+
+# Motivation
+
+Currently, users can start plan preview commands but cannot cancel them. Therefore, we have the following two motivations to introduce a cancel plan preview command:
+
+- Plan preview commands, especially terraform related plan preview commands, can be long running. This becomes a bottleneck specially when there are large number of commands but only a few number of piped agents to execute them. Cancelling the plan preview commands will shorten the queue of commands.
+- In the future we would like to have a generic way to cancel all types of commands. Exploring how to cancel plan preview command helps us developers to explore how to build a cancel command feature which could be extended to other commands.
+
+# Detailed design
+
+In this iteration of the cancel plan preview command, we limit ourselves to only trigger the cancel plan preview comman using a github action. The following points describe how each component will handle the cancel plan preview command:
+
+- Github Action: A new cancel-plan-preview github action will call pipecdctl to cancel a plan preview command. This will contain the detail necessary to find the plan preview command to cancel.
+
+- PipecdCtl: Makes a blocking call the control plane to cancel the plan preview command.
+
+- Control Plane: 
+    - Finds all the commands generated by the plan preview command to cancel.
+    - If no commandds have been picked up by the piped agents yet, the control plan cancels the commands by setting the status to cancel and update the database/filestore. Rreturn message that plan preview command was cancelled
+    - If at least one command has been picked up by piped agent then control plane return a message that the command cannot be cancelled because a piped agent has already started executing the command.
+
+# Alternatives
+
+- We rejected an idea to have a UI page to list all the currently running plan preview commands and let the users cancel the plan preview commands from there. The main motivation behind this idea was to address the difficulty in finding the PRs which are currently running the plan preview commands. This idea is not completely rejected, we want to first address how the plan preview is mostly used. We would possibly revisit this idea in the future in the context of a generic cancel command.
+
+- We rejected an idea where the user would have to manually specificy details of the plan preview comman so that the cancel plan preview command could find the plan preview command to cancel it. We rejected this idea in favour of using github actions because github actions already provide us with this detail making it the most efficient method for users to trigger a cancel plan preview command.
+
+# Unresolved questions
+
+In this iteration, we do not cancel commands that have already been picked up by a piped agent. In a future iteration we would explore how to cancel commands that have been already picked up by a piped agent.