feat: add set-matrix-server action

Author: gsanchietti

README.md

@@ -67,40 +67,21 @@ Consumers of the events must then run the `get-phonebook-credentials` action on
 
 ## Matrix integration
 
-This module provides optional integration with a Matrix server module (for example `matrix5`). Integration is implemented so the Matrix module can call into FreePBX to authenticate or validate users.
+Provides optional integration with a Matrix server module (e.g. `matrix5`). Use the included helper action `set-matrix-server` to enable or disable the NethVoice authentication endpoint on a Matrix instance.
 
-A helper action `set-matrix-server` was added to manage this integration. The action performs the following steps:
+The action sets or clears the `nethvoice_auth_url` used by the Matrix module to call FreePBX for external authentication.
 
-- Resolve the target Matrix module using the module UUID stored in Redis under `module/<module_id>/environment` as the `MODULE_UUID` field. The action only uses this method for resolution and will fail if the UUID is not found.
-- Calls `get-configuration` on the local NethVoice module to obtain `nethvoice_host`.
-- Calls `get-configuration` on the target Matrix module to obtain its current configuration.
-- Sets the `nethvoice_auth_url` field to either `https://<nethvoice_host>/freepbx/rest/testextauth` when integration is enabled, or to the empty string when disabled.
-- Calls `configure-module` on the Matrix module with the merged configuration (the Matrix module's existing `get-configuration` response with `nethvoice_auth_url` overridden).
+Parameters:
+  - `module_uuid`: string, required - the UUID of the Matrix module instance to update, find it using ` redis-cli hget module/matrix1/environment MODULE_UUID`
+  - `enable_integration`: boolean, required
 
-This approach ensures the Matrix module receives a full, consistent payload suitable for its `configure-module` handler while only changing the authentication endpoint field required for NethVoice integration.
-
-### Action: `set-matrix-server`
-
-- Location: `imageroot/actions/set-matrix-server/10setenvs`
-- Input schema: `imageroot/actions/set-matrix-server/validate-input.json`
-- Parameters:
-    - `module_uuid` (string, required): the UUID of the Matrix module instance to configure. The action will locate the module id by scanning `module/*/environment` for the `MODULE_UUID` value.
-    - `enable_integration` (boolean, required): `true` to enable integration (sets the `nethvoice_auth_url`), `false` to disable it (clears the field).
-
-### Example usage
-
-Run the action as a cluster task (example JSON payload):
+Example payload:
 
 ```
-{
-    "module_uuid": "cf50b191-95d5-435b-bf34-0905bf7dba55",
-    "enable_integration": true
-}
+{ "module_uuid": "cf50b191-95d5-435b-bf34-0905bf7dba55", "enable_integration": true }
 ```
 
-The action will find the module id (for example `matrix5`) by scanning Redis, fetch both configurations, set `nethvoice_auth_url` to `https://<nethvoice_host>/freepbx/rest/testextauth` and call `configure-module` on the `module/matrix5` agent.
-
-If you prefer to run this manually for testing, use the `agent.tasks.run` equivalent on the cluster admin node or invoke the module task from your management tooling.
+When enabling integration the `nethvoice_auth_url` is set to `https://<nethvoice_host>/freepbx/rest/testextauth` (using the configured NethVoice host); disabling the integration clears the field.
 
 
 ## Uninstall

imageroot/actions/restore-module/20copyenv

@@ -113,6 +113,7 @@ restore_envs = [
     'TIMEZONE',
     'TRAEFIK_HTTP2HTTPS',
     'USER_DOMAIN',
+    'NETHVOICE_MATRIX_UUID'
 ]
 
 for env in restore_envs:

imageroot/actions/restore-module/73set_matrix_service

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+
+#
+# Copyright (C) 2025 Nethesis S.r.l.
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+
+import sys
+import os
+import agent
+
+def resolve_module_id_from_uuid(uuid):
+    # Redis stores module info under module/{id}/uuid -> value
+    # We need to search for the module id that has this uuid
+    with agent.redis_connect() as rdb:
+        # Only method: check environment hashes where MODULE_UUID is stored (user-provided format)
+        for key in rdb.scan_iter(match='module/*/environment'):
+            try:
+                k = key.decode() if isinstance(key, bytes) else key
+                module_uuid_val = rdb.hget(k, 'MODULE_UUID')
+                if module_uuid_val and module_uuid_val.decode() == uuid:
+                    parts = k.split('/')
+                    if len(parts) >= 2:
+                        return parts[1]
+            except Exception:
+                continue
+    return None
+
+def get_configuration(module_id):
+    matrix_agent_id = f'module/{module_id}'
+    response = agent.tasks.run(agent_id=matrix_agent_id, action='get-configuration', data={})
+    agent.assert_exp(response['exit_code'] == 0)
+    return response
+
+def set_configuration(module_id, config):
+    matrix_agent_id = f'module/{module_id}'
+    response = agent.tasks.run(agent_id=matrix_agent_id, action='configure-module', data=config)
+    agent.assert_exp(response['exit_code'] == 0)
+    return response
+
+module_uuid = os.getenv('NETHVOICE_MATRIX_UUID', '')
+if module_uuid == '':
+    # No matrix integration to restore
+    sys.exit(0)
+
+# Resolve module uuid to module id
+module_id = resolve_module_id_from_uuid(module_uuid)
+if module_id is None:
+    # Matrix not found, nothing to restore
+    print(agent.SD_WARNING + f"Module UUID {module_uuid} not found: cannot restore Matrix integration")
+    sys.exit(0)
+
+config = get_configuration(module_id)
+nethvoice_host = os.environ.get('NETHVOICE_HOST', '')
+if nethvoice_host:
+    config['nethvoice_auth_url'] = f'https://{nethvoice_host}/freepbx/rest/testextauth'
+    set_configuration(module_id, config)
+else:
+    print(agent.SD_WARNING + "NETHVOICE_HOST not set: cannot restore Matrix integration")

imageroot/actions/set-matrix-server/10setenvs

@@ -8,7 +8,6 @@
 import json
 import sys
 import os
-
 import agent
 
 request = json.load(sys.stdin)
@@ -30,44 +29,44 @@ def resolve_module_id_from_uuid(uuid):
                 continue
     return None
 
+def get_configuration(module_id):
+    matrix_agent_id = f'module/{module_id}'
+    response = agent.tasks.run(agent_id=matrix_agent_id, action='get-configuration', data={})
+    agent.assert_exp(response['exit_code'] == 0)
+    return response
 
-module_uuid = request.get('module_uuid')
-enable_integration = request.get('enable_integration', False)
-
-if not module_uuid:
-    print(json.dumps({'exit_code': 2, 'message': 'module_uuid is required'}))
-    sys.exit(2)
-
-# Resolve module uuid to module id
-module_id = resolve_module_id_from_uuid(module_uuid)
-if module_id is None:
-    print(json.dumps({'exit_code': 2, 'message': f'module_uuid {module_uuid} not found via module/*/environment'}))
-    sys.exit(2)
-
-# Build agent id for module
-matrix_agent_id = f'module/{module_id}'
-
-# Call get-configuration on current nethvoice module to obtain hostname
-response = agent.tasks.run(agent_id=os.environ['AGENT_ID'], action='get-configuration', data={})
-agent.assert_exp(response['exit_code'] == 0)
+def set_configuration(module_id, config):
+    matrix_agent_id = f'module/{module_id}'
+    response = agent.tasks.run(agent_id=matrix_agent_id, action='configure-module', data=config)
+    agent.assert_exp(response['exit_code'] == 0)
+    return response
 
-nconfig = response.get('result', {})
-nethvoice_host = nconfig.get('nethvoice_host', os.environ.get('NETHVOICE_HOST', ''))
-
-# Call get-configuration on the matrix module and use its response for configure-module
-response = agent.tasks.run(agent_id=matrix_agent_id, action='get-configuration', data={})
-agent.assert_exp(response['exit_code'] == 0)
-
-matrix_config = response.get('result', {}) or {}
-
-if enable_integration:
-    nethvoice_auth_url = f'https://{nethvoice_host}/freepbx/rest/testextauth' if nethvoice_host else '/freepbx/rest/testextauth'
-else:
-    nethvoice_auth_url = ''
-
-# Merge/override nethvoice_auth_url into matrix configuration
-matrix_config['nethvoice_auth_url'] = nethvoice_auth_url
-
-# Call configure-module on matrix module with merged configuration
-response = agent.tasks.run(agent_id=matrix_agent_id, action='configure-module', data=matrix_config)
-agent.assert_exp(response['exit_code'] == 0)
+module_uuid = request.get('module_uuid')
+current_module_uuid = os.getenv('NETHVOICE_MATRIX_UUID', '')
+
+if current_module_uuid == module_uuid:
+    # No change, nothing to do
+    sys.exit(0)
+
+if current_module_uuid != '' and module_uuid == '':
+    # Disable integration on old module
+    module_id = resolve_module_id_from_uuid(current_module_uuid)
+    if module_id is not None:
+        config = get_configuration(module_id)
+        config['nethvoice_auth_url'] = ''
+        set_configuration(module_id, config)
+    else:
+        print(agent.SD_WARNING + f"Module UUID {current_module_uuid} not found: cannot disable Matrix integration")
+if current_module_uuid == '' and module_uuid != '':
+    # Enable integration on new module
+    module_id = resolve_module_id_from_uuid(module_uuid)
+    if module_id is not None:
+        nethvoice_host = os.environ.get('NETHVOICE_HOST', '')
+        if nethvoice_host:
+            config = get_configuration(module_id)
+            config['nethvoice_auth_url'] = f'https://{nethvoice_host}/freepbx/rest/testextaut'
+            set_configuration(module_id, config)
+        else:
+            print(agent.SD_WARNING + "NETHVOICE_HOST is not set, cannot enable Matrix integration")
+    else:
+        print(agent.SD_WARNING + f"Module UUID {module_uuid} not found: cannot enable Matrix integration")

imageroot/actions/set-matrix-server/validate-input.json

@@ -4,15 +4,11 @@
     "$id": "http://nethserver.org/json-schema/task/input/nethvoice/set-matrix-server",
     "description": "Enable or disable NethVoice integration on Matrix server",
     "type": "object",
-    "required": ["module_uuid", "enable_integration"],
+    "required": ["module_uuid"],
     "properties": {
         "module_uuid": {
             "description": "Module UUID of the Matrix module to configure",
             "type": "string"
-        },
-        "enable_integration": {
-            "description": "Enable integration with NethVoice",
-            "type": "boolean"
         }
     }
 }