feat: add set-matrix-server action

Author: gsanchietti

Containerfile

@@ -21,7 +21,7 @@ COPY imageroot /imageroot
 # copy ui from ui_builder
 COPY --from=ui_builder /app/dist /ui
 ENTRYPOINT [ "/" ]
-LABEL org.nethserver.authorizations="traefik@any:fulladm node:fwadm,portsadm nethvoice-proxy@any:routeadm"
+LABEL org.nethserver.authorizations="traefik@any:fulladm node:fwadm,portsadm nethvoice-proxy@any:routeadm matrix@any:matrixadm"
 LABEL org.nethserver.tcp-ports-demand="36"
 LABEL org.nethserver.rootfull="0"
 LABEL org.nethserver.min-core="3.6.2-0"

README.md

@@ -65,6 +65,44 @@ It raises an event named `phonebook-settings-changed` with the following payload
 
 Consumers of the events must then run the `get-phonebook-credentials` action on `module_id` to get the updated phonebook credentials.
 
+## 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.
+
+A helper action `set-matrix-server` was added to manage this integration. The action performs the following steps:
+
+- 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).
+
+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):
+
+```
+{
+    "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.
+
+
 ## Uninstall
 
 To uninstall the instance:

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

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+
+#
+# Copyright (C) 2025 Nethesis S.r.l.
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+
+import json
+import sys
+import os
+
+import agent
+
+request = json.load(sys.stdin)
+
+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
+
+
+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)
+
+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)

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

@@ -0,0 +1,18 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Set Matrix server integration",
+    "$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"],
+    "properties": {
+        "module_uuid": {
+            "description": "Module UUID of the Matrix module to configure",
+            "type": "string"
+        },
+        "enable_integration": {
+            "description": "Enable integration with NethVoice",
+            "type": "boolean"
+        }
+    }
+}