From 8ca32ef63b834b6d28c30e2281097404bbc14dda Mon Sep 17 00:00:00 2001
From: Abdul Munif Hanafi <amunifhanafi@gmail.com>
Date: Thu, 26 Dec 2024 23:59:24 +0700
Subject: [PATCH] Update readme and add more tests

---
 README.md                       | 74 +++++++++++++++++++++++++++++++++
 tests/komando_parallel_hosts.rs | 47 +++++++++++++++++++++
 tests/komando_parallel_tasks.rs | 48 +++++++++++++++++++++
 3 files changed, 169 insertions(+)
 create mode 100644 tests/komando_parallel_hosts.rs
 create mode 100644 tests/komando_parallel_tasks.rs

diff --git a/README.md b/README.md
index 4e9a37b..79a634f 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,8 @@ Komandan is a server automation tool that simplifies remote server management by
 - [`komando` function](#komando-function)
 - [Modules](#modules)
 - [Built-in functions](#built-in-functions)
+- [Default Values](#default-values)
+- [Parallel Execution](#parallel-execution)
 - [Error Handling](#error-handling)
 - [Contributing](#contributing)
 - [License](#license)
@@ -167,6 +169,78 @@ local env = komandan.defaults:get_env("ENV_VAR")
 local env_all = komandan.defaults:get_all_env()
 ```
 
+## Parallel Execution
+
+Komandan supports parallel execution of tasks on multiple hosts using the `komando_parallel_hosts` function, and `komando_parallel_tasks` function for parallel execution of tasks on the same host.
+
+```lua
+-- parallel execution of a task on multiple hosts
+local hosts = {
+    {
+        name = "server1",
+        address = "localhost",
+        user = "usertest",
+        private_key_file = os.getenv("HOME") .. "/.ssh/id_ed25519",
+    },
+    {
+        name = "server2",
+        address = "localhost",
+        user = "usertest",
+        private_key_file = os.getenv("HOME") .. "/.ssh/id_ed25519",
+    },
+    {
+        name = "server3",
+        address = "localhost",
+        user = "usertest",
+        private_key_file = os.getenv("HOME") .. "/.ssh/id_ed25519",
+    }
+}
+
+local task = {
+    name = "Ping Google",
+    komandan.modules.cmd({
+        cmd = "ping google.com -c 5",
+    }),
+}
+
+komandan.komando_parallel_hosts(hosts, task)
+```
+
+```lua
+-- parallel execution of a task on the same host
+local host = {
+    name = "My Server",
+    address = "localhost",
+    user = "usertest",
+    private_key_file = os.getenv("HOME") .. "/.ssh/id_ed25519",
+}
+
+local tasks = {
+    {
+        name = "Task 1",
+        komandan.modules.cmd({
+            cmd = "uname -a",
+        }),
+    },
+    {
+        name = "Task 2",
+        komandan.modules.cmd({
+            cmd = "ping google.com -c 7",
+        }),
+    },
+    {
+        name = "Task 3",
+        komandan.modules.apt({
+            package = "neovim",
+            update_cache = true
+        }),
+        elevate = true,
+    }
+}
+
+komandan.komando_parallel_tasks(host, tasks)
+```
+
 ## Error Handling
 
 Komandan provides error information through the return values of the `komando` function. If a task fails, the `exit_code` will be non-zero, and `stderr` may contain error messages. You can use the `ignore_exit_code` option in a task to continue execution even if a task fails.
diff --git a/tests/komando_parallel_hosts.rs b/tests/komando_parallel_hosts.rs
new file mode 100644
index 0000000..b761b47
--- /dev/null
+++ b/tests/komando_parallel_hosts.rs
@@ -0,0 +1,47 @@
+use komandan::create_lua;
+use mlua::{chunk, Integer, Table, Value};
+
+#[test]
+fn test_komando_parallel_hosts() {
+    let lua = create_lua().unwrap();
+
+    let results = lua
+        .load(chunk! {
+            local hosts = {
+                {
+                    name = "server1",
+                    address = "localhost",
+                    user = "usertest",
+                    private_key_file = os.getenv("HOME") .. "/.ssh/id_ed25519",
+                },
+                {
+                    name = "server2",
+                    address = "localhost",
+                    user = "usertest",
+                    private_key_file = os.getenv("HOME") .. "/.ssh/id_ed25519",
+                },
+                {
+                    name = "server3",
+                    address = "localhost",
+                    user = "usertest",
+                    private_key_file = os.getenv("HOME") .. "/.ssh/id_ed25519",
+                }
+            }
+
+            local task = {
+                name = "Echo 1",
+                komandan.modules.cmd({
+                    cmd = "echo 1",
+                }),
+            }
+
+            return komandan.komando_parallel_hosts(hosts, task)
+        })
+        .eval::<Table>()
+        .unwrap();
+
+    for pair in results.pairs::<Value, Table>() {
+        let (_, table) = pair.unwrap();
+        assert!(table.get::<Integer>("exit_code").unwrap() == 0);
+    }
+}
diff --git a/tests/komando_parallel_tasks.rs b/tests/komando_parallel_tasks.rs
new file mode 100644
index 0000000..20fa72d
--- /dev/null
+++ b/tests/komando_parallel_tasks.rs
@@ -0,0 +1,48 @@
+use komandan::create_lua;
+use mlua::{chunk, Integer, Table, Value};
+
+#[test]
+fn test_komando_parallel_tasks() {
+    let lua = create_lua().unwrap();
+
+    let results = lua
+        .load(chunk! {
+            local host = {
+                name = "My Server",
+                address = "localhost",
+                user = "usertest",
+                private_key_file = os.getenv("HOME") .. "/.ssh/id_ed25519",
+            }
+
+            local tasks = {
+                {
+                    name = "Task 1",
+                    komandan.modules.cmd({
+                        cmd = "uname -a",
+                    }),
+                },
+                {
+                    name = "Echo 1",
+                    komandan.modules.cmd({
+                        cmd = "echo 1",
+                    }),
+                },
+                {
+                    name = "Echo 2",
+                    komandan.modules.cmd({
+                        cmd = "echo 2"
+                    }),
+                    elevate = true,
+                }
+            }
+
+            return komandan.komando_parallel_tasks(host, tasks)
+        })
+        .eval::<Table>()
+        .unwrap();
+
+    for pair in results.pairs::<Value, Table>() {
+        let (_, table) = pair.unwrap();
+        assert!(table.get::<Integer>("exit_code").unwrap() == 0);
+    }
+}