Merge pull request #412 from nextcloud/feature/PSR-4/apps-info-and-config

add hability to read appInfos and settings exposed to the PSR-4 autoloader

Author: aalaesar

plugins/module_utils/app.py

@@ -23,18 +23,25 @@
 # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+from __future__ import annotations
 import json
 from typing import Union
 from ansible_collections.nextcloud.admin.plugins.module_utils.exceptions import (
     OccExceptions,
     AppExceptions,
+    PhpInlineExceptions,
+    PhpResultJsonException,
+    AppPSR4InfosNotReadable,
+    AppPSR4InfosUnavailable,
 )
-from ansible_collections.nextcloud.admin.plugins.module_utils.nc_tools import run_occ  # type: ignore
+from ansible_collections.nextcloud.admin.plugins.module_utils.nc_tools import run_occ, run_php_inline  # type: ignore
 
 
 class app:
-    _update_version_available = "unchecked"
+    _update_version_available = ""
     _path = None
+    _autoloaded_infos = None
+    _current_settings = None
 
     def __init__(self, module, app_name: str):
         self.module = module
@@ -62,14 +69,14 @@ def __init__(self, module, app_name: str):
 
     @property
     def update_version_available(self) -> Union[str, None]:
-        if self._update_version_available == "unchecked":
+        if self._update_version_available == "":
             _check_app_update = run_occ(
                 self.module, ["app:update", "--showonly", self.app_name]
             )[1]
-            if _check_app_update != "":
-                result = _check_app_update.split()[-1]
-            else:
+            if _check_app_update == "" or "up-to-date" in _check_app_update:
                 result = None
+            else:
+                result = _check_app_update.split()[-1]
             self._update_version_available = result
         return self._update_version_available
 
@@ -84,18 +91,105 @@ def path(self) -> str:
         self._path = result
         return self._path
 
-    def infos(self):
-        result = dict(
-            name=self.app_name,
+    def get_facts(self) -> dict[str, any]:
+        facts = dict(
             state=self.state,
             is_shipped=self.shipped,
         )
         if self.state != "absent":
-            result.update(update_available=self.update_available)
-            result.update(version=self.version)
-            result.update(version_available=self.update_version_available)
-            result.update(app_path=self.path)
-        return result
+            facts.update(update_available=self.update_available)
+            facts.update(version=self.version)
+            facts.update(version_available=self.update_version_available)
+            facts.update(app_path=self.path)
+        return facts
+
+    @property
+    def autoloaded_infos(self) -> dict:
+        if self._autoloaded_infos is None:
+            self._autoloaded_infos = self._get_autoloaded_infos()
+        return self._autoloaded_infos
+
+    @property
+    def infos(self) -> dict:
+        return self.autoloaded_infos.get("appInfo")
+
+    @property
+    def default_settings(self) -> dict:
+        return self.autoloaded_infos["settings"]
+
+    def _get_autoloaded_infos(self) -> dict:
+        """
+        Run inline php script that use the server autoloading system to inspect the app.
+        return a dict that contains keys: appInfo, settings.
+        setting can contain admin and personal default settings if any is available.
+        """
+        php_script = f"""
+        $appId = '{self.app_name}';
+        // Get App PSR-4 infos
+        $appManager = \\OC::$server->getAppManager();
+        $appInfo = $appManager->getAppInfo($appId);
+        $result = array(
+        'appInfo' => $appInfo,
+        'settings' => array()
+        );
+        foreach (['admin', 'personal'] as $section) {{
+            if (!empty($appInfo['settings'][$section])) {{
+                $className = $appInfo['settings'][$section][0];
+                if (class_exists($className)) {{
+                    $settingsInstance = \\OC::$server->get($className);
+                    $form = $settingsInstance->getForm();
+
+                    if (method_exists($form, 'getParams')) {{
+                        $result['settings'][$section] = $form->getParams();
+                    }} else {{
+                        $result['settings'][$section] = 'Unavailable';
+                        }}
+                }} else {{
+                    $result['settings'][$section] = 'Settings not currently loaded';
+                }}
+            }}
+        }}
+        """
+        try:
+            result = run_php_inline(self.module, php_script)
+            # force the 'settings' key to be dict if it is empty
+            if isinstance(result["settings"], list) and not result["settings"]:
+                result["settings"] = {}
+            return result
+        except PhpResultJsonException as e:
+            raise AppPSR4InfosNotReadable(app_name=self.app_name, **e.__dict__)
+        except PhpInlineExceptions as e:
+            raise AppPSR4InfosUnavailable(app_name=self.app_name, **e.__dict__)
+
+    @property
+    def current_settings(self) -> dict[str, any]:
+        if self._current_settings is None:
+            self._current_settings = self._get_current_settings()
+        return self._current_settings
+
+    def _get_current_settings(self) -> dict[str, any]:
+        """
+        Returns the current configured settings for the app, using `occ config:list <app>`.
+        """
+        non_informative = ["installed_version", "enabled", "types"]
+        try:
+            raw_config = run_occ(self.module, ["config:list", self.app_name])[1]
+            occ_config = json.loads(raw_config).get("apps", {}).get(self.app_name, {})
+            if isinstance(occ_config, list) and not occ_config:
+                return {}
+            else:
+                return {k: v for k, v in occ_config.items() if k not in non_informative}
+        except OccExceptions as e:
+            self.module.warn(
+                f"Failed to get current config for {self.app_name}: {e.stderr}"
+            )
+            return {}
+        except Exception as e:
+            raise AppExceptions(
+                msg=f"Unexpected error in reading configured values. {str(e)}",
+                app_name=self.app_name,
+                **e.__dict__,
+            )
 
     def install(self, enable: bool = True):
         occ_args = ["app:install", self.app_name]

plugins/module_utils/exceptions.py

@@ -111,6 +111,24 @@ class OccAuthenticationException(OccExceptions):
     pass
 
 
+class PhpInlineExceptions(NextcloudException):
+    """Base exception for php run in the nextcloud server."""
+
+    pass
+
+
+class PhpScriptException(PhpInlineExceptions):
+    """Raised when a php script return an error."""
+
+    pass
+
+
+class PhpResultJsonException(PhpInlineExceptions):
+    """Exception raised for php script results failing python's json deserialization."""
+
+    pass
+
+
 class AppExceptions(NextcloudException):
     """
     Base exception for app-related errors in Nextcloud.
@@ -134,15 +152,15 @@ def __init__(self, **kwargs):
             super().__init__(**kwargs)
 
 
-class AppFormNotAvailable(AppExceptions):
-    """Raised when an app does not expose an admin form via its Settings API."""
+class AppPSR4InfosUnavailable(AppExceptions):
+    """Raised when an app does not expose proper PSR4 Infos"""
 
     def __init__(self, **kwargs):
-        super().__init__(dft_msg="Admin form not available", **kwargs)
+        super().__init__(dft_msg="PSR-4 infos not available", **kwargs)
 
 
-class AppFormInvalidJson(AppExceptions):
+class AppPSR4InfosNotReadable(AppExceptions):
     """Raised when an app's getForm() method returns invalid JSON."""
 
     def __init__(self, **kwargs):
-        super().__init__(dft_msg="Invalid JSON returned by getForm()", **kwargs)
+        super().__init__(dft_msg="PSR-4 infos are invalid JSON", **kwargs)

plugins/module_utils/nc_tools.py

@@ -25,6 +25,8 @@
 
 import os
 from multiprocessing import Process, Pipe
+import json
+from textwrap import dedent
 from ansible_collections.nextcloud.admin.plugins.module_utils.exceptions import (
     OccExceptions,
     OccAuthenticationException,
@@ -33,6 +35,9 @@
     OccNotEnoughArguments,
     OccOptionRequiresValue,
     OccOptionNotDefined,
+    PhpInlineExceptions,
+    PhpScriptException,
+    PhpResultJsonException,
 )
 from shlex import shlex
 import copy
@@ -164,3 +169,52 @@ def run_occ(
         raise OccExceptions(full_command, **result)
 
     return result["rc"], result["stdout"], result["stderr"], maintenanceMode
+
+
+def run_php_inline(module, php_code: str) -> dict:
+    """
+    Interface with Nextcloud server through ad-hoc php scripts.
+    The script must define the var $result that will be exported into a python dict
+    """
+    if isinstance(php_code, list):
+        php_code = "\n".join(php_code)
+    elif isinstance(php_code, str):
+        php_code = dedent(php_code).strip()
+    else:
+        raise Exception("php_code must be a list or a string")
+
+    full_code = f"""
+    require_once 'lib/base.php';
+    {php_code}
+    if (!isset($result)) {{
+        $result = null;
+    }}
+    echo json_encode($result, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
+    """
+    rc, stdout, stderr = module.run_command(
+        [module.params.get("php_runtime"), "-r", full_code],
+        cwd=module.params.get("nextcloud_path"),
+    )
+    if rc != 0:
+        raise PhpScriptException(
+            msg="Failed to run the given php script.",
+            stderr=stderr,
+            stdout=stdout,
+            rc=rc,
+            php_script=full_code,
+        )
+
+    stdout = stdout.strip()
+    try:
+        result = json.loads(stdout) if stdout and stdout != "null" else None
+        return result
+    except json.JSONDecodeError as e:
+        raise PhpResultJsonException(
+            msg="Failed to decode JSON from php script stdout",
+            stderr=stderr,
+            stdout=stdout,
+            rc=rc,
+            JSONDecodeError=str(e),
+        )
+    except Exception:
+        raise PhpInlineExceptions(stderr=stderr, stdout=stdout, rc=rc)

plugins/modules/app.py

@@ -47,6 +47,8 @@
       - Attention! Use the application `technical` name (available at the end of the app's page url).
     type: str
     required: true
+    aliases:
+      - "id"
 
   state:
     description:
@@ -74,7 +76,7 @@
 EXAMPLES = r"""
 - name: Enable preinstalled contact application
   nextcloud.admin.app:
-    name: contacts
+    id: contacts
     state: present
     nextcloud_path: /var/lib/www/nextcloud
 
@@ -97,9 +99,17 @@
       returned: always
       type: str
 version:
-  description: App version present of updated on the server.
+  description: App version present or updated on the server.
   returned: always
   type: str
+miscellaneous:
+  description: Informative messages sent by the server during app operation.
+  returned: when not empty
+  type: list
+  contains:
+    misc:
+      description: Something reported by the server.
+      type: str
 """
 
 from ansible.module_utils.basic import AnsibleModule
@@ -112,7 +122,7 @@
 )
 
 module_args_spec = dict(
-    name=dict(type="str", required=True),
+    name=dict(type="str", aliases=["id"], required=True),
     state=dict(
         type="str",
         required=False,