Enhancement/1887/zos unarchive (#2020)

* async changes for unarchive

* test case to test the async functionality for zos_unarchive

* changelog addition

* Update test_zos_unarchive_func.py

---------

Co-authored-by: André Marcel Gutiérrez Benítez <[email protected]>

Author: Rohitcodes28

changelogs/fragments/2020-zos-unarchive_async_support.yml

@@ -0,0 +1,3 @@
+minor_changes:
+  - zos_unarchive - Adds support for unarchiving files in asynchronous mode inside playbooks.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/2020).

plugins/action/zos_unarchive.py

@@ -1,4 +1,4 @@
-# Copyright (c) IBM Corporation 2023, 2024
+# Copyright (c) IBM Corporation 2023, 2025
 # 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
@@ -34,11 +34,14 @@ def _process_boolean(arg, default=False):
 
 class ActionModule(ActionBase):
     def run(self, tmp=None, task_vars=None):
+        self._supports_async = True
         if task_vars is None:
             task_vars = dict()
 
         result = super(ActionModule, self).run(tmp, task_vars)
 
+        self._task_vars = task_vars
+
         if result.get("skipped"):
             return result
 
@@ -53,6 +56,7 @@ def run(self, tmp=None, task_vars=None):
                     module_name="ibm.ibm_zos_core.zos_unarchive",
                     module_args=module_args,
                     task_vars=task_vars,
+                    wrap_async=self._task.async_val
                 )
             )
         else:
@@ -102,6 +106,8 @@ def run(self, tmp=None, task_vars=None):
             )
             copy_task = self._task.copy()
             copy_task.args = copy_module_args
+            # Making the zos_copy task run synchronously every time.
+            copy_task.async_val = 0
             copy_action = self._shared_loader_obj.action_loader.get(
                 'ibm.ibm_zos_core.zos_copy',
                 task=copy_task,
@@ -120,6 +126,7 @@ def run(self, tmp=None, task_vars=None):
                         module_name="ibm.ibm_zos_core.zos_unarchive",
                         module_args=module_args,
                         task_vars=task_vars,
+                        wrap_async=self._task.async_val
                     )
                 )
             else:

plugins/modules/zos_unarchive.py

@@ -318,7 +318,7 @@
     support: full
     description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
   async:
-    support: none
+    support: full
     description: Supports being used with the ``async`` keyword.
   check_mode:
     support: full

tests/functional/modules/test_zos_unarchive_func.py

@@ -15,10 +15,14 @@
 
 from __future__ import absolute_import, division, print_function
 
+import os
 import pytest
 import tempfile
 from tempfile import mkstemp
 from ibm_zos_core.tests.helpers.dataset import get_tmp_ds_name
+import yaml
+from shellescape import quote
+import subprocess
 
 __metaclass__ = type
 
@@ -33,6 +37,51 @@
 
 USS_FORMATS = ['tar', 'gz', 'bz2', 'zip', 'pax']
 
+PLAYBOOK_ASYNC_TEST = """- hosts: zvm
+  collections:
+    - ibm.ibm_zos_core
+  gather_facts: False
+  environment:
+    _BPXK_AUTOCVT: "ON"
+    ZOAU_HOME: "{0}"
+    PYTHONPATH: "{0}/lib/{2}"
+    LIBPATH: "{0}/lib:{1}/lib:/lib:/usr/lib:."
+    PATH: "{0}/bin:/bin:/usr/lpp/rsusr/ported/bin:/var/bin:/usr/lpp/rsusr/ported/bin:/usr/lpp/java/java180/J8.0_64/bin:{1}/bin:"
+    _CEE_RUNOPTS: "FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)"
+    _TAG_REDIR_ERR: "txt"
+    _TAG_REDIR_IN: "txt"
+    _TAG_REDIR_OUT: "txt"
+    LANG: "C"
+    PYTHONSTDINENCODING: "cp1047"
+
+  tasks:
+    - name: Execute script in async mode.
+      ibm.ibm_zos_core.zos_unarchive:
+        src: {3}
+        format:
+          name: {4}
+        remote_src: True
+      async: 45
+      poll: 0
+      register: job_task
+
+    - name: Query async task.
+      async_status:
+        jid: "{{{{ job_task.ansible_job_id }}}}"
+      register: job_result
+      until: job_result.finished
+      retries: 20
+      delay: 5
+"""
+
+INVENTORY_ASYNC_TEST = """all:
+  hosts:
+    zvm:
+      ansible_host: {0}
+      ansible_ssh_private_key_file: {1}
+      ansible_user: {2}
+      ansible_python_interpreter: {3}"""
+
 def set_uss_test_env(ansible_zos_module, test_files):
     for key, value in test_files.items():
         ansible_zos_module.all.shell(
@@ -1185,3 +1234,80 @@ def test_gdg_unarchive(ansible_zos_module, dstype, format):
     finally:
         hosts.all.shell(cmd=f'drm "{HLQ}.*"')
 
+@pytest.mark.uss
+def test_zos_unarchive_async(ansible_zos_module, get_config):
+    try:
+        # Load environment details from the config file
+        with open(get_config, 'r') as file:
+            environment = yaml.safe_load(file)
+
+        ssh_key = environment["ssh_key"]
+        hosts = environment["host"].upper()
+        user = environment["user"].upper()
+        python_path = environment["python_path"]
+        cut_python_path = python_path[:python_path.find('/bin')].strip()
+        zoau = environment["environment"]["ZOAU_ROOT"]
+        python_version = cut_python_path.split('/')[2]
+        archive_format = USS_FORMATS[0]
+
+        # Create a temporary archive file for testing
+        hosts_zos = ansible_zos_module
+        hosts_zos.all.file(path=f"{USS_TEMP_DIR}", state="absent")
+        hosts_zos.all.file(path=USS_TEMP_DIR, state="directory")
+        set_uss_test_env(hosts_zos, USS_TEST_FILES)
+        dest = f"{USS_TEMP_DIR}/archive.{archive_format}"
+        archive_result = hosts_zos.all.zos_archive(src=list(USS_TEST_FILES.keys()),
+                                        dest=dest,
+                                        format=dict(
+                                            name=archive_format
+                                        ))
+        # remove files
+        for file in USS_TEST_FILES.keys():
+            hosts_zos.all.file(path=file, state="absent")
+
+        # Create temporary playbook and inventory files
+        playbook = tempfile.NamedTemporaryFile(delete=True)
+        inventory = tempfile.NamedTemporaryFile(delete=True)
+
+        os.system("echo {0} > {1}".format(
+            quote(PLAYBOOK_ASYNC_TEST.format(
+                zoau,
+                cut_python_path,
+                python_version,
+                dest,  
+                archive_format,  
+            )),
+            playbook.name
+        ))
+
+        os.system("echo {0} > {1}".format(
+            quote(INVENTORY_ASYNC_TEST.format(
+                hosts,
+                ssh_key,
+                user,
+                python_path
+            )),
+            inventory.name
+        ))
+
+        # Run the Ansible playbook
+        command = "ansible-playbook -i {0} {1}".format(
+            inventory.name,
+            playbook.name
+        )
+
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            shell=True,
+            timeout=120,
+            encoding='utf-8'
+        )
+
+        # Assertions to validate the result
+        assert result.returncode == 0
+        assert "ok=2" in result.stdout
+        assert "changed=2" in result.stdout
+        assert result.stderr == ""
+    finally:
+        hosts_zos.all.file(path=f"{USS_TEMP_DIR}", state="absent")