From 2d59f039bae10476a356c5da7dc66989b29f01f6 Mon Sep 17 00:00:00 2001
From: Charles d'Avernas <charles.davernas@neuroglia.io>
Date: Wed, 8 Jan 2025 15:08:18 +0100
Subject: [PATCH] Add a new `return` property to the `run` task, used to
 configure the output of the process to execute Closes #1051

Signed-off-by: Charles d'Avernas <charles.davernas@neuroglia.io>
---
 dsl-reference.md                | 53 +++++++++++++++++++++++++++++++++
 examples/run-return-all.yaml    | 11 +++++++
 examples/run-return-code.yaml   | 11 +++++++
 examples/run-return-none.yaml   | 11 +++++++
 examples/run-return-stderr.yaml | 11 +++++++
 5 files changed, 97 insertions(+)
 create mode 100644 examples/run-return-all.yaml
 create mode 100644 examples/run-return-code.yaml
 create mode 100644 examples/run-return-none.yaml
 create mode 100644 examples/run-return-stderr.yaml

diff --git a/dsl-reference.md b/dsl-reference.md
index 92b02d60..4f3fd799 100644
--- a/dsl-reference.md
+++ b/dsl-reference.md
@@ -55,6 +55,7 @@
   + [HTTP Response](#http-response)
   + [HTTP Request](#http-request)
   + [URI Template](#uri-template)
+  + [Process Result](#process-result)
 
 ## Abstract
 
@@ -723,6 +724,7 @@ Provides the capability to execute external [containers](#container-process), [s
 | run.shell | [`shell`](#shell-process) | `no` | The definition of the shell command to run.<br>*Required if `container`, `script` and `workflow` have not been set.* |
 | run.workflow | [`workflow`](#workflow-process) | `no` | The definition of the workflow to run.<br>*Required if `container`, `script` and `shell` have not been set.* |
 | await | `boolean` | `no` | Determines whether or not the process to run should be awaited for.<br>*Defaults to `true`.* |
+| return | `string` | `no` | Configures the output of the process.<br>*Supported values are:*<br>*- `stdout`: Outputs the content of the process **STDOUT**.*<br>*- `stderr`: Outputs the content of the process **STDERR**.*<br>*- `code`:  Outputs the process's **exit code**.*<br>*- `all`: Outputs the **exit code**, the **STDOUT** content and the **STDERR** content, wrapped into a new [processResult](#process-result) object.*<br>*- `none`: Does not output anything.*<br>*Defaults to `stdout`.* |
 
 ##### Examples
 
@@ -1888,3 +1890,54 @@ This has the following limitations compared to runtime expressions:
 ```yaml
 uri: https://petstore.swagger.io/v2/pet/{petId}
 ```
+
+### Process Result
+
+Describes the result of a process.
+
+#### Properties
+
+| Name | Type | Required | Description|
+|:--|:---:|:---:|:---|
+| code | `integer` | `yes` | The process's exit code. |
+| stdout | `string` | `yes` | The process's **STDOUT** output. |
+| stderr | `string` | `yes` | The process's **STDERR** output. |
+
+#### Examples
+
+```yaml
+document:
+  dsl: '1.0.0-alpha5'
+  namespace: test
+  name: run-example
+  version: '0.1.0'
+do:
+  - runContainer:
+      run:
+        container:
+          image: fake-image
+      return: stderr
+
+  - runScript:
+      run:
+        script:
+          language: js
+          code: >
+            Some cool multiline script
+      return: code
+
+  - runShell:
+      run:
+        shell:
+          command: 'echo "Hello, ${ .user.name }"'
+      return: all
+
+  - runWorkflow:
+      run:
+        workflow:
+          namespace: another-one
+          name: do-stuff
+          version: '0.1.0'
+          input: {}
+      return: none
+```
\ No newline at end of file
diff --git a/examples/run-return-all.yaml b/examples/run-return-all.yaml
new file mode 100644
index 00000000..966d2215
--- /dev/null
+++ b/examples/run-return-all.yaml
@@ -0,0 +1,11 @@
+document:
+  dsl: '1.0.0-alpha5'
+  namespace: test
+  name: run-container
+  version: '0.1.0'
+do:
+  - runContainer:
+      run:
+        container:
+          image: hello-world
+      return: all
\ No newline at end of file
diff --git a/examples/run-return-code.yaml b/examples/run-return-code.yaml
new file mode 100644
index 00000000..bdde3ef5
--- /dev/null
+++ b/examples/run-return-code.yaml
@@ -0,0 +1,11 @@
+document:
+  dsl: '1.0.0-alpha5'
+  namespace: test
+  name: run-container
+  version: '0.1.0'
+do:
+  - runContainer:
+      run:
+        container:
+          image: hello-world
+      return: code
\ No newline at end of file
diff --git a/examples/run-return-none.yaml b/examples/run-return-none.yaml
new file mode 100644
index 00000000..e0ea1159
--- /dev/null
+++ b/examples/run-return-none.yaml
@@ -0,0 +1,11 @@
+document:
+  dsl: '1.0.0-alpha5'
+  namespace: test
+  name: run-container
+  version: '0.1.0'
+do:
+  - runContainer:
+      run:
+        container:
+          image: hello-world
+      return: none
\ No newline at end of file
diff --git a/examples/run-return-stderr.yaml b/examples/run-return-stderr.yaml
new file mode 100644
index 00000000..73d07242
--- /dev/null
+++ b/examples/run-return-stderr.yaml
@@ -0,0 +1,11 @@
+document:
+  dsl: '1.0.0-alpha5'
+  namespace: test
+  name: run-container
+  version: '0.1.0'
+do:
+  - runContainer:
+      run:
+        container:
+          image: hello-world
+      return: stderr
\ No newline at end of file