Add workload version to juju status

metadata.yaml

@@ -8,11 +8,11 @@ description: |
   A charm for the matrix synapse chat server.
   Synapse is a drop in replacement for other chat servers like Mattermost and Slack.
   This charm is useful if you want to spin up your own chat instance.
-docs: ""
 issues: https://github.com/canonical/synapse-operator/issues
 maintainers:
   - launchpad.net/~canonical-is-devops
 source: https://github.com/canonical/synapse-operator
+docs: "https://discourse.charmhub.io/t/synapse-documentation-overview/11358"
 assumes:
   - k8s-api
 

src/charm.py

@@ -15,6 +15,7 @@
 from ops.main import main
 
 import actions
+import synapse
 from charm_state import CharmConfigInvalidError, CharmState
 from constants import SYNAPSE_CONTAINER_NAME, SYNAPSE_PORT
 from database_observer import DatabaseObserver
@@ -79,13 +80,27 @@ def change_config(self, _: ops.HookEvent) -> None:
             return
         self.model.unit.status = ops.ActiveStatus()
 
+    def _set_workload_version(self) -> None:
+        """Set workload version with Synapse version."""
+        container = self.unit.get_container(SYNAPSE_CONTAINER_NAME)
+        if not container.can_connect():
+            self.unit.status = ops.MaintenanceStatus("Waiting for pebble")
+            return
+        try:
+            synapse_version = synapse.get_version()
+            self.unit.set_workload_version(synapse_version)
+        except synapse.APIError as exc:
+            logger.debug("Cannot set workload version at this time: %s", exc)
+
     def _on_config_changed(self, event: ops.HookEvent) -> None:
         """Handle changed configuration.
 
         Args:
             event: Event triggering after config is changed.
         """
         self.change_config(event)
+        logger.debug("Setting workload in config-changed event")
+        self._set_workload_version()
 
     def _on_pebble_ready(self, event: ops.HookEvent) -> None:
         """Handle pebble ready event.

src/constants.py

@@ -4,6 +4,7 @@
 """This module defines constants used throughout the Synapse application."""
 
 CHECK_READY_NAME = "synapse-ready"
+CHECK_ALIVE_NAME = "synapse-alive"
 COMMAND_MIGRATE_CONFIG = "migrate_config"
 PROMETHEUS_TARGET_PORT = "9000"
 SYNAPSE_CONFIG_DIR = "/data"

src/database_client.py

@@ -85,7 +85,7 @@ def prepare(self) -> None:
                     ).format(sql.Literal(self._database_name))
                 )
         except psycopg2.Error as exc:
-            logger.error("Failed to prepare database: %s", str(exc))
+            logger.exception("Failed to prepare database: %r", exc)
             raise
         finally:
             self._close()
@@ -111,7 +111,7 @@ def erase(self) -> None:
                     ).format(sql.Identifier(self._database_name))
                 )
         except psycopg2.Error as exc:
-            logger.error("Failed to erase database: %s", str(exc))
+            logger.exception("Failed to erase database: %r", exc)
             raise
         finally:
             self._close()

src/pebble.py

@@ -13,6 +13,7 @@
 import synapse
 from charm_state import CharmState
 from constants import (
+    CHECK_ALIVE_NAME,
     CHECK_READY_NAME,
     SYNAPSE_COMMAND_PATH,
     SYNAPSE_CONTAINER_NAME,
@@ -115,6 +116,7 @@ def _pebble_layer(self) -> ops.pebble.LayerDict:
             },
             "checks": {
                 CHECK_READY_NAME: synapse.check_ready(),
+                CHECK_ALIVE_NAME: synapse.check_alive(),
             },
         }
         return typing.cast(ops.pebble.LayerDict, layer)

src/synapse/__init__.py

@@ -4,10 +4,11 @@
 """Synapse package is used to interact with Synapse instance."""
 
 # Exporting methods to be used for another modules
-from .api import APIError, register_user  # noqa: F401
+from .api import APIError, get_version, register_user  # noqa: F401
 from .workload import (  # noqa: F401
     ExecResult,
     WorkloadError,
+    check_alive,
     check_ready,
     enable_metrics,
     execute_migrate_config,

src/synapse/api.py

@@ -10,16 +10,22 @@
 import hashlib
 import hmac
 import logging
+import re
 import typing
 
 import requests
+from requests import Session
+from requests.adapters import HTTPAdapter
+from urllib3.util import Retry
 
 from user import User
 
 logger = logging.getLogger(__name__)
 
 SYNAPSE_URL = "http://localhost:8008"
 REGISTER_URL = f"{SYNAPSE_URL}/_synapse/admin/v1/register"
+VERSION_URL = f"{SYNAPSE_URL}/_synapse/admin/v1/server_version"
+SYNAPSE_VERSION_REGEX = r"(\d+\.\d+\.\d+(?:\w+)?)\s?"
 
 
 class APIError(Exception):
@@ -30,22 +36,38 @@ class APIError(Exception):
     """
 
     def __init__(self, msg: str):
-        """Initialize a new instance of the RegisterUserError exception.
+        """Initialize a new instance of the APIError exception.
 
         Args:
             msg (str): Explanation of the error.
         """
         self.msg = msg
 
 
-class RegisterUserError(APIError):
-    """Exception raised when registering user via API fails."""
-
-
 class NetworkError(APIError):
     """Exception raised when requesting API fails due network issues."""
 
 
+class GetNonceError(APIError):
+    """Exception raised when getting nonce via API fails."""
+
+
+class NonceNotFoundError(GetNonceError):
+    """Exception raised when nonce is not found."""
+
+
+class GetVersionError(APIError):
+    """Exception raised when getting version via API fails."""
+
+
+class VersionNotFoundError(GetVersionError):
+    """Exception raised when version is not found."""
+
+
+class VersionUnexpectedContentError(GetVersionError):
+    """Exception raised when output of getting version is unexpected."""
+
+
 def register_user(registration_shared_secret: str, user: User) -> None:
     """Register user.
 
@@ -55,36 +77,39 @@ def register_user(registration_shared_secret: str, user: User) -> None:
 
     Raises:
         NetworkError: if there was an error registering the user.
+        GetNonceError: if there was an error while getting nonce.
     """
-    # get nonce
-    nonce = _get_nonce()
-
-    # generate mac
-    hex_mac = _generate_mac(
-        shared_secret=registration_shared_secret,
-        nonce=nonce,
-        user=user.username,
-        password=user.password,
-        admin=user.admin,
-    )
-    data = {
-        "nonce": nonce,
-        "username": user.username,
-        "password": user.password,
-        "mac": hex_mac,
-        "admin": user.admin,
-    }
-    # finally register user
     try:
+        # get nonce
+        nonce = _get_nonce()
+
+        # generate mac
+        hex_mac = _generate_mac(
+            shared_secret=registration_shared_secret,
+            nonce=nonce,
+            user=user.username,
+            password=user.password,
+            admin=user.admin,
+        )
+        data = {
+            "nonce": nonce,
+            "username": user.username,
+            "password": user.password,
+            "mac": hex_mac,
+            "admin": user.admin,
+        }
+        # finally register user
         res = requests.post(REGISTER_URL, json=data, timeout=5)
         res.raise_for_status()
-    except (
-        requests.exceptions.ConnectionError,
-        requests.exceptions.Timeout,
-        requests.exceptions.HTTPError,
-    ) as exc:
-        logger.error("Failed to request %s : %s", REGISTER_URL, exc)
-        raise NetworkError(f"Failed to request {REGISTER_URL}.") from exc
+    except (requests.exceptions.ConnectionError, requests.exceptions.Timeout) as exc:
+        logger.exception("Failed to connect to %s: %r", REGISTER_URL, exc)
+        raise NetworkError(f"Failed to connect to {REGISTER_URL}.") from exc
+    except requests.exceptions.HTTPError as exc:
+        logger.exception("HTTP error from %s: %r", REGISTER_URL, exc)
+        raise NetworkError(f"HTTP error from {REGISTER_URL}.") from exc
+    except GetNonceError as exc:
+        logger.exception("Failed to get nonce: %r", exc)
+        raise GetNonceError(str(exc)) from exc
 
 
 def _generate_mac(
@@ -137,15 +162,85 @@ def _get_nonce() -> str:
 
     Raises:
         NetworkError: if there was an error fetching the nonce.
+        GetNonceError: if there was an error while getting nonce.
     """
     try:
         res = requests.get(REGISTER_URL, timeout=5)
         res.raise_for_status()
-        return res.json()["nonce"]
-    except (
-        requests.exceptions.ConnectionError,
-        requests.exceptions.Timeout,
-        requests.exceptions.HTTPError,
-    ) as exc:
-        logger.error("Failed to request %s : %s", REGISTER_URL, exc)
-        raise NetworkError(f"Failed to request {REGISTER_URL}.") from exc
+        res_json = res.json()
+        if not isinstance(res_json, dict):
+            # Exception not in docstring because is captured.
+            raise GetNonceError(f"Response has unexpected encode: {res_json}")  # noqa: DCO053
+        nonce = res_json.get("nonce", None)
+        if nonce is None:
+            # Exception not in docstring because is captured.
+            raise NonceNotFoundError(  # noqa: DCO053
+                f"There is no nonce in JSON output: {res_json}"
+            )
+        return nonce
+    except (requests.exceptions.ConnectionError, requests.exceptions.Timeout) as exc:
+        logger.exception("Failed to connect to %s: %r", REGISTER_URL, exc)
+        raise NetworkError(f"Failed to connect to {REGISTER_URL}.") from exc
+    except requests.exceptions.HTTPError as exc:
+        logger.exception("HTTP error from %s: %r", REGISTER_URL, exc)
+        raise NetworkError(f"HTTP error from {REGISTER_URL}.") from exc
+    except (GetNonceError, requests.exceptions.JSONDecodeError) as exc:
+        logger.exception("Failed to get nonce: %r", exc)
+        raise GetNonceError(str(exc)) from exc
+
+
+def get_version() -> str:
+    """Get version.
+
+    Expected API output:
+    {
+        "server_version": "0.99.2rc1 (b=develop, abcdef123)",
+        "python_version": "3.7.8"
+    }
+
+    We're using retry here because after the config change, Synapse is restarted.
+
+    Returns:
+        The version returned by Synapse API.
+
+    Raises:
+        NetworkError: if there was an error fetching the version.
+        GetVersionError: if there was an error while reading version.
+    """
+    try:
+        session = Session()
+        retries = Retry(
+            total=3,
+            backoff_factor=3,
+        )
+        session.mount("http://", HTTPAdapter(max_retries=retries))
+        res = session.get(VERSION_URL, timeout=10)
+        res.raise_for_status()
+        res_json = res.json()
+        if not isinstance(res_json, dict):
+            # Exception not in docstring because is captured.
+            raise VersionUnexpectedContentError(  # noqa: DCO053
+                f"Response has unexpected encode: {res_json}"
+            )
+        server_version = res_json.get("server_version", None)
+        if server_version is None:
+            # Exception not in docstring because is captured.
+            raise VersionNotFoundError(  # noqa: DCO053
+                f"There is no server_version in JSON output: {res_json}"
+            )
+        version_match = re.search(SYNAPSE_VERSION_REGEX, server_version)
+        if not version_match:
+            # Exception not in docstring because is captured.
+            raise VersionUnexpectedContentError(  # noqa: DCO053
+                f"server_version has unexpected content: {server_version}"
+            )
+        return version_match.group(1)
+    except (requests.exceptions.ConnectionError, requests.exceptions.Timeout) as exc:
+        logger.exception("Failed to connect to %s: %r", VERSION_URL, exc)
+        raise NetworkError(f"Failed to connect to {VERSION_URL}.") from exc
+    except requests.exceptions.HTTPError as exc:
+        logger.exception("HTTP error from %s: %r", VERSION_URL, exc)
+        raise NetworkError(f"HTTP error from {VERSION_URL}.") from exc
+    except (GetVersionError, requests.exceptions.JSONDecodeError) as exc:
+        logger.exception("Failed to get version: %r", exc)
+        raise GetVersionError(str(exc)) from exc

src/synapse/workload.py

@@ -23,6 +23,8 @@
     SYNAPSE_PORT,
 )
 
+from .api import VERSION_URL
+
 logger = logging.getLogger(__name__)
 
 
@@ -68,18 +70,30 @@ class ExecResult(typing.NamedTuple):
     stderr: str
 
 
-def check_ready() -> typing.Dict:
-    """Return the Synapse container check.
+def check_ready() -> ops.pebble.CheckDict:
+    """Return the Synapse container ready check.
 
     Returns:
         Dict: check object converted to its dict representation.
     """
     check = Check(CHECK_READY_NAME)
     check.override = "replace"
     check.level = "ready"
+    check.http = {"url": VERSION_URL}
+    return check.to_dict()
+
+
+def check_alive() -> ops.pebble.CheckDict:
+    """Return the Synapse container alive check.
+
+    Returns:
+        Dict: check object converted to its dict representation.
+    """
+    check = Check(CHECK_READY_NAME)
+    check.override = "replace"
+    check.level = "alive"
     check.tcp = {"port": SYNAPSE_PORT}
-    # _CheckDict cannot be imported
-    return check.to_dict()  # type: ignore
+    return check.to_dict()
 
 
 def execute_migrate_config(container: ops.Container, charm_state: CharmState) -> None:
@@ -167,8 +181,8 @@ def reset_instance(container: ops.Container) -> None:
         if "device or resource busy" in str(path_error):
             pass
         else:
-            logger.error(
-                "exception while erasing directory %s: %s", SYNAPSE_CONFIG_DIR, path_error
+            logger.exception(
+                "exception while erasing directory %s: %r", SYNAPSE_CONFIG_DIR, path_error
             )
             raise
 
@@ -275,8 +289,8 @@ def _get_configuration_field(container: ops.Container, fieldname: str) -> typing
                 SYNAPSE_CONFIG_PATH,
             )
             return None
-        logger.error(
-            "exception while reading configuration file %s: %s",
+        logger.exception(
+            "exception while reading configuration file %s: %r",
             SYNAPSE_CONFIG_PATH,
             path_error,
         )