From e1e79074596bf2d685d89420f98482b7e29f493c Mon Sep 17 00:00:00 2001
From: AnsibleGuy <guy@ansibleguy.net>
Date: Wed, 20 Dec 2023 12:08:33 +0100
Subject: [PATCH] added information-output to system-upgrade & -reboot, updated
 info regarding version-support

---
 README.md                             | 12 +++++++++++-
 docs/source/usage/4_develop.rst       |  2 ++
 plugins/module_utils/helper/system.py | 27 +++++++++++++++++++++------
 plugins/modules/system.py             |  1 +
 tests/README.md                       |  4 ++--
 5 files changed, 37 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index c6a6fdca..76b9999e 100644
--- a/README.md
+++ b/README.md
@@ -35,7 +35,6 @@ ansible-galaxy collection install ansibleguy.opnsense
 
 See: [Docs](https://opnsense.ansibleguy.net)
 
-
 ----
 
 ## Contribute
@@ -46,6 +45,17 @@ See also: [Contributing](https://github.com/ansibleguy/collection_opnsense/blob/
 
 ----
 
+## Version Support
+
+The `ansibleguy.opnsense` modules always support the latest version of OPNSense.
+
+If an API changed, the current module-implementation might fail for firewalls running an older firmware.
+
+See also: [Firmware-Upgrade using ansibleguy.opnsense.system](https://opnsense.ansibleguy.net/en/latest/modules/system.html#examples)
+
+----
+
+
 ## Modules
 
 **Development States**:
diff --git a/docs/source/usage/4_develop.rst b/docs/source/usage/4_develop.rst
index 6d02b3c7..876db591 100644
--- a/docs/source/usage/4_develop.rst
+++ b/docs/source/usage/4_develop.rst
@@ -173,6 +173,8 @@ Verbose output
 
 If you want to output something to ansible's runtime - use 'module.warn':
 
+NOTE: This output is buffered by Ansible until the task has finished.
+
 .. code-block:: python3
 
     module.warn(f"{before} != {after}")
diff --git a/plugins/module_utils/helper/system.py b/plugins/module_utils/helper/system.py
index 77dfa7b3..57343bd9 100644
--- a/plugins/module_utils/helper/system.py
+++ b/plugins/module_utils/helper/system.py
@@ -1,13 +1,14 @@
-from socket import socket, AF_INET, SOCK_STREAM
+from socket import socket, AF_INET, AF_INET6, SOCK_STREAM, gaierror
 from time import time, sleep
+from datetime import datetime
 
 from ansible.module_utils.basic import AnsibleModule
 
 from ansible_collections.ansibleguy.opnsense.plugins.module_utils.defaults.main import CONNECTION_TEST_TIMEOUT
 
 
-def opn_reachable(module: AnsibleModule) -> bool:
-    with socket(AF_INET, SOCK_STREAM) as s:
+def _opn_reachable_ipv(module: AnsibleModule, address_family: int) -> bool:
+    with socket(address_family, SOCK_STREAM) as s:
         s.settimeout(CONNECTION_TEST_TIMEOUT)
         return s.connect_ex((
             module.params['firewall'],
@@ -15,21 +16,35 @@ def opn_reachable(module: AnsibleModule) -> bool:
         )) == 0
 
 
+def _opn_reachable(module: AnsibleModule) -> bool:
+    try:
+        return _opn_reachable_ipv(module, AF_INET)
+
+    except gaierror:
+        return _opn_reachable_ipv(module, AF_INET6)
+
+
+def _wait_msg(module: AnsibleModule, msg: str):
+    module.warn(f"{datetime.now().strftime('%Y-%m-%d %H:%M:%S')} | {msg}")
+
+
 def wait_for_response(module: AnsibleModule) -> bool:
     timeout = time() + module.params['wait_timeout']
 
     if module.params['action'] == 'upgrade':
-        # waiting longer for download/install to finish
+        _wait_msg(module, 'Waiting download & upgrade to finish..')
         sleep(int(module.params['wait_timeout'] / 2))
 
     else:
-        # waiting for services to stop
+        _wait_msg(module, 'Waiting for service to stop..')
         sleep(10)
 
     while time() < timeout:
-        if opn_reachable(module=module):
+        if _opn_reachable(module=module):
+            _wait_msg(module, 'Got response!')
             return True
 
+        _wait_msg(module, 'Waiting for response..')
         sleep(module.params['poll_interval'])
 
     return False
diff --git a/plugins/modules/system.py b/plugins/modules/system.py
index 73dd8062..d13d3193 100644
--- a/plugins/modules/system.py
+++ b/plugins/modules/system.py
@@ -59,6 +59,7 @@ def run_module():
             if module.params['debug']:
                 module.warn(f"Waiting for firewall to complete '{module.params['action']}'!")
 
+            # todo: cleaner way of handling if no upgrade is needed
             result['failed'] = not wait_for_response(module=module)
 
             if result['failed']:
diff --git a/tests/README.md b/tests/README.md
index 63945ea9..61f9b03c 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -31,9 +31,9 @@ You need to add a `opt1` dummy-interface named `TEST`. The assigned IPs do not m
 
 ### Internet access
 
-To perform some tests (package/firmware, ids) the test firewall needs to reach some public service:
+To perform some tests (system, ids) the test firewall needs to reach some public service:
 
-* package/firmware - `pkg.opnsense.org`
+* system - `pkg.opnsense.org`
 * ids - `rules.emergingthreats.net`
 
 ----