midpoint-cli 1.6.0__py3-none-any.whl

midpoint_cli/client/rest.py

@@ -0,0 +1,490 @@
+"""REST transport: authenticated calls to the Midpoint REST API and their error handling."""
+
+import re
+from collections.abc import Sequence
+from typing import Any, NamedTuple
+from urllib.parse import urljoin, urlparse
+from xml.etree import ElementTree
+from xml.etree.ElementTree import Element
+
+import requests
+from urllib3.exceptions import MaxRetryError
+
+from midpoint_cli.client.configuration import MidpointClientConfiguration
+from midpoint_cli.client.errors import (
+    MidpointInvalidOid,
+    MidpointMissingPassword,
+    MidpointObjectNotFound,
+    MidpointServerError,
+    MidpointUnsupportedOperation,
+)
+from midpoint_cli.client.objects import MidpointObjectType, MidpointObjectTypes
+from midpoint_cli.client.observer import MidpointCommunicationObserver, NopMidpointCommunicationObserver
+from midpoint_cli.client.patch import patch_from_file
+from midpoint_cli.client.safe_xml import fromstring as safe_fromstring
+from midpoint_cli.client.session import (
+    READ_TIMEOUT_ENV_VAR,
+    RETRY_TIMEOUT_ENV_VAR,
+    CustomHTTPAdapter,
+    CustomRetryManager,
+    read_timeout_seconds,
+    retry_attempts_for,
+    retry_timeout_seconds,
+)
+
+# Connect timeout in seconds for every REST call; the read timeout is configurable
+# (MidpointClientConfiguration.read_timeout). Without them a server that accepts the
+# connection but never answers hangs the CLI forever. A connect timeout is retried like any
+# other connection failure, a read timeout is not (see session.py).
+CONNECT_TIMEOUT_SECONDS = 10
+
+# Header in which Midpoint 4.10+ answers a search sent with returnTotalCount=true.
+TOTAL_COUNT_HEADER = 'X-Total-Count'
+
+
+# Midpoint's native repository only accepts UUIDs, but the generic repository (H2 and
+# older setups) stores any string up to 36 characters, so OIDs such as 'my-role-01' exist.
+# Accept a conservative token: no '/', '?', '#', '%', whitespace, and no leading '.', so
+# urljoin cannot resolve '..' segments into another collection or out of the context path.
+_SAFE_PATH_SEGMENT = re.compile(r'[A-Za-z0-9][A-Za-z0-9._:-]*')
+
+
+def _check_path_segment(value: str, what: str = 'OID') -> str:
+    """Return value unchanged if it is safe as a single REST URL path segment, else raise MidpointInvalidOid."""
+    if not isinstance(value, str) or _SAFE_PATH_SEGMENT.fullmatch(value) is None:
+        raise MidpointInvalidOid(
+            f'Invalid {what} {value!r}: only letters, digits and ".", "_", ":", "-" are allowed, '
+            f'starting with a letter or digit'
+        )
+    return value
+
+
+def _search_options(options: Sequence[str]) -> dict[str, Any]:
+    """The ``options`` query parameters of a search: GetOperationOptions in their REST form (e.g. 'raw')."""
+    return {'options': [_check_path_segment(o, 'option') for o in options]} if options else {}
+
+
+class PutResult(NamedTuple):
+    """Outcome of an upload: the object type, its OID (None if the server did not report one) and
+    whether it was created by POST (True) or written to a known OID by PUT (False)."""
+
+    object_type: MidpointObjectType
+    oid: str | None
+    created: bool
+
+
+_ERROR_DETAIL_MAX_LEN = 500
+
+
+def _extract_error_detail(content: bytes) -> str | None:
+    """Pull the human-readable reason out of a Midpoint error body.
+
+    Midpoint answers a failed REST call with an OperationResultType document whose
+    <message> element carries the actual reason ("Object of type 'UserType' with oid
+    '...' was not found."). Without it the CLI could only report a bare status code.
+    Bodies that aren't XML (proxy error pages, plain text) are reported verbatim,
+    truncated.
+    """
+    if not content:
+        return None
+
+    try:
+        tree = safe_fromstring(content)
+    except ElementTree.ParseError:
+        text = ' '.join(content.decode('utf-8', errors='replace').split())
+        return text[:_ERROR_DETAIL_MAX_LEN] or None
+
+    # Document order, so a top-level <message> wins over a nested <partialResults> one.
+    for node in tree.iter():
+        if node.tag.rsplit('}', 1)[-1] == 'message' and node.text and node.text.strip():
+            return ' '.join(node.text.split())[:_ERROR_DETAIL_MAX_LEN]
+
+    return None
+
+
+def _describe_request_failure(
+    url: str,
+    error: requests.RequestException,
+    retry_timeout: float | None = None,
+    read_timeout: float | None = None,
+) -> str:
+    """Turn a transport-level requests failure into a one-line, actionable message."""
+    # requests wraps the urllib3 MaxRetryError whose reason is the actual cause; its own
+    # str() repeats the pool and URL details, so report the innermost reason instead.
+    reason: object = error
+    retried = bool(error.args) and isinstance(error.args[0], MaxRetryError)
+    if retried and error.args[0].reason is not None:
+        reason = error.args[0].reason
+
+    if isinstance(error, requests.exceptions.SSLError):
+        return (
+            f'TLS/SSL error on the REST call to {url}: {reason} — '
+            f'check the server certificate and that the URL scheme (http/https) is correct'
+        )
+    # A MaxRetryError means the retry budget of session.py was spent before giving up.
+    gave_up = (
+        f' (gave up after retrying for up to {retry_timeout:g} s; use --timeout or {RETRY_TIMEOUT_ENV_VAR} to wait longer)'
+        if retried and retry_timeout is not None
+        else ''
+    )
+    if isinstance(error, requests.exceptions.ConnectTimeout):
+        return f'Timed out connecting to the server for the REST call to {url}: {reason}{gave_up}'
+    if isinstance(error, requests.exceptions.Timeout):
+        within = f' within {read_timeout:g} seconds' if read_timeout is not None else ''
+        return (
+            f'Server did not answer the REST call to {url}{within} '
+            f'(use --read-timeout or {READ_TIMEOUT_ENV_VAR} to wait longer)'
+        )
+    if isinstance(error, requests.exceptions.ConnectionError):
+        return (
+            f'Cannot connect to the server for the REST call to {url}: {reason}{gave_up} '
+            f'— check the configured server URL'
+        )
+    return f'REST call to {url} failed: {reason}'
+
+
+class RestApiClient:
+    """Low-level client of the Midpoint REST API (``ws/rest/...``), one method per HTTP call.
+
+    The verbs return what the call needs, so their return types differ: a decoded ``str``
+    (get_element, delete, patch_element, get_endpoint, post_xml), raw ``bytes``
+    (execute_action), a parsed ``Element`` (get_elements, search_elements), an OID
+    (create_element) or a PutResult (put_element).
+
+    Every verb raises the same errors, all subclasses of MidpointServerError:
+
+    - MidpointInvalidOid before anything is sent, when an OID, endpoint or action is not a
+      safe URL path segment;
+    - MidpointMissingPassword before anything is sent, when the configuration has no password;
+    - MidpointObjectNotFound when the server answers 404;
+    - MidpointServerError for any other error status (with the server's message when it
+      gives one), a redirect or HTML page (a base URL without the Midpoint context path),
+      and transport failures (refused connection, timeout, TLS error, retries exhausted).
+
+    Methods that parse the answer also raise ``xml.etree.ElementTree.ParseError`` when it is
+    not XML or holds constructs refused by safe_xml.
+    """
+
+    def __init__(
+        self,
+        client_configuration: MidpointClientConfiguration,
+        observer: MidpointCommunicationObserver | None = None,
+    ):
+        self.configuration = client_configuration
+
+        if observer is None:
+            # No-op observer implementation
+            observer = NopMidpointCommunicationObserver()
+
+        session = requests.Session()
+
+        # Overall wall-clock budget for retrying a request that gets no answer (session.py).
+        timeout = client_configuration.timeout
+        self.retry_timeout_seconds = timeout if timeout is not None else retry_timeout_seconds()
+        attempts = retry_attempts_for(self.retry_timeout_seconds)
+        read_timeout = client_configuration.read_timeout
+        self.read_timeout_seconds = read_timeout if read_timeout is not None else read_timeout_seconds()
+        adapter = CustomHTTPAdapter(
+            max_retries=CustomRetryManager(
+                connect=attempts, total=attempts, timeout_seconds=self.retry_timeout_seconds, observer=observer
+            ),
+            observer=observer,
+        )
+        session.mount('http://', adapter)
+        session.mount('https://', adapter)
+
+        self.requests_session = session
+
+    def _url(self, path: str) -> str:
+        """Resolve a server-relative path against the configured base URL.
+
+        ``urljoin`` replaces the last path segment of a base without a trailing slash, so
+        'http://host/midpoint' + 'ws/rest/users' would lose the context path and target
+        'http://host/ws/rest/users'. The base is read at call time because the configuration
+        is filled in field by field after the client is built.
+        """
+        base = self.configuration.url
+        if not base.endswith('/'):
+            base += '/'
+        return urljoin(base, path)
+
+    def _collection_url(self, element_class: MidpointObjectType, *segments: str) -> str:
+        """Build the REST URL of a collection (``ws/rest/<endpoint>``), followed by already checked segments."""
+        if element_class.endpoint is None:
+            raise AssertionError(f'Element class {element_class} has no endpoint')
+        path = [_check_path_segment(element_class.endpoint, 'endpoint'), *segments]
+        return self._url('ws/rest/' + '/'.join(path))
+
+    def _object_url(self, element_class: MidpointObjectType, element_oid: str, action: str | None = None) -> str:
+        """Build the REST URL of one object (optionally of an action on it), validating every segment."""
+        if element_class.endpoint is None:
+            raise AssertionError(f'Element class {element_class} has no endpoint')
+        endpoint = _check_path_segment(element_class.endpoint, 'endpoint')
+        segments = [_check_path_segment(element_oid)]
+        if action is not None:
+            segments.append(_check_path_segment(action, 'action'))
+        return self._url('ws/rest/' + '/'.join([endpoint, *segments]))
+
+    def _rest_request(self, method: str, url: str, **kwargs: Any) -> requests.Response:
+        """Send an authenticated REST request, refusing redirects and HTML answers.
+
+        Midpoint REST endpoints answer directly with XML: a redirect or an HTML body
+        means the call landed on the web UI instead of the REST API — typically a base
+        URL missing the /midpoint/ context path (recent Midpoint container images serve
+        strictly under /midpoint, and the root URL answers with redirects ending at the
+        HTML login page). Silently following that redirect used to surface as a cryptic
+        ``xml.etree.ElementTree.ParseError: mismatched tag`` when the login page was
+        parsed as XML.
+        """
+        if not self.configuration.password:
+            raise MidpointMissingPassword(
+                f'No password configured for user {self.configuration.username}: '
+                f'refusing to send an unauthenticated REST call to {url}'
+            )
+        try:
+            response = self.requests_session.request(
+                method,
+                url,
+                auth=(self.configuration.username, self.configuration.password),
+                allow_redirects=False,
+                timeout=(CONNECT_TIMEOUT_SECONDS, self.read_timeout_seconds),
+                **kwargs,
+            )
+        except requests.RequestException as e:
+            # Transport failures (refused connection, timeout, TLS error, exhausted retries)
+            # are reported like server errors so command handlers print a clean message
+            # instead of a traceback.
+            raise MidpointServerError(
+                _describe_request_failure(url, e, self.retry_timeout_seconds, self.read_timeout_seconds)
+            ) from e
+
+        if 300 <= response.status_code < 400:
+            location = response.headers.get('Location', '(no Location header)')
+            raise MidpointServerError(
+                f'Server redirected the REST call on {url} to {location}. '
+                f'REST endpoints never redirect — check the configured server URL: '
+                f"it must include the Midpoint context path, e.g. 'http://localhost:8080/midpoint/'."
+            )
+
+        if 'text/html' in response.headers.get('Content-Type', ''):
+            raise MidpointServerError(
+                f'Server answered the REST call on {url} with an HTML page '
+                f'(HTTP {response.status_code}) instead of a REST response — '
+                f'check the configured server URL: '
+                f"it must include the Midpoint context path, e.g. 'http://localhost:8080/midpoint/'."
+            )
+
+        # Checked here rather than in each verb so no REST call can silently succeed on an
+        # error status. Reaching this point means the status is < 300 or >= 400: the redirect
+        # branch above already rejected 301-399.
+        if response.status_code >= 400:
+            message = f'Server responded with status code {response.status_code} on {url}'
+            if response.status_code in (401, 403):
+                message += ' — check the configured username and password'
+            detail = _extract_error_detail(response.content)
+            if detail:
+                message += f': {detail}'
+            error = MidpointObjectNotFound(message) if response.status_code == 404 else MidpointServerError(message)
+            error.status_code = response.status_code
+            raise error
+
+        return response
+
+    def get_element(self, element_class: MidpointObjectType, element_oid: str) -> str:
+        """GET one object (``ws/rest/<collection>/<oid>``) and return its XML, decoded to ``str``.
+
+        element_class gives the collection and element_oid the object. Errors as described in
+        the class docstring; a missing object raises MidpointObjectNotFound.
+        """
+        response = self._rest_request('get', self._object_url(element_class, element_oid))
+
+        return response.content.decode()
+
+    def delete(self, element_class: MidpointObjectType, element_oid: str) -> str:
+        """DELETE one object (``ws/rest/<collection>/<oid>``) and return the answer body, decoded to ``str``.
+
+        Midpoint answers a successful delete with no content, so the result is usually empty.
+        Errors as described in the class docstring; a missing object raises MidpointObjectNotFound.
+        """
+        response = self._rest_request('delete', self._object_url(element_class, element_oid))
+
+        return response.content.decode()
+
+    def patch_element(self, element_class: MidpointObjectType, element_oid: str, xml_body: str) -> str:
+        """PATCH one object with xml_body, an ``ObjectModificationType`` document of item deltas.
+
+        Returns the answer body decoded to ``str``, usually empty. Errors as described in the
+        class docstring; a server that refuses the modification answers an error status.
+        """
+        target_url = self._object_url(element_class, element_oid)
+        response = self._rest_request(
+            'patch',
+            target_url,
+            data=xml_body,
+            headers={'Content-Type': 'application/xml'},
+        )
+        return response.content.decode()
+
+    def get_elements(self, element_class: MidpointObjectType) -> Element:
+        """GET a whole collection (``ws/rest/<collection>``) and return the parsed ``<objects>`` ``Element``.
+
+        Every object of the type is downloaded: use search_elements to filter or page on the
+        server. Errors as described in the class docstring, including ParseError.
+        """
+        url = self._collection_url(element_class)
+        response = self._rest_request('get', url)
+        tree = safe_fromstring(response.content)
+        return tree
+
+    def search_elements(
+        self, element_class: MidpointObjectType, query_xml: str, options: Sequence[str] = ()
+    ) -> Element:
+        """POST a QueryType to the search endpoint of a collection and return the parsed object list.
+
+        options are GetOperationOptions in their REST form (e.g. ``raw``), sent as ``options``
+        query parameters, which the search endpoint of 4.4 to 4.11 reads.
+        """
+        response = self._search(element_class, query_xml, _search_options(options))
+        return safe_fromstring(response.content)
+
+    def count_elements(
+        self, element_class: MidpointObjectType, query_xml: str, options: Sequence[str] = ()
+    ) -> int | None:
+        """The number of objects matching a QueryType, ignoring its paging, or None if the server cannot tell.
+
+        Midpoint 4.10 added ``returnTotalCount`` to the search endpoint: the answer then carries
+        the count in an ``X-Total-Count`` header. Earlier versions ignore the parameter and send
+        no header. Give the query a small maxSize, as the matching objects are still returned.
+        options are sent as in search_elements.
+        """
+        params: dict[str, Any] = {'returnTotalCount': 'true', **_search_options(options)}
+        response = self._search(element_class, query_xml, params)
+        header = response.headers.get(TOTAL_COUNT_HEADER)
+        try:
+            return int(header) if header is not None else None
+        except ValueError:
+            return None
+
+    def _search(
+        self, element_class: MidpointObjectType, query_xml: str, params: dict[str, Any] | None
+    ) -> requests.Response:
+        url = self._collection_url(element_class, 'search')
+        kwargs: dict[str, Any] = {'params': params} if params else {}
+        return self._rest_request(
+            'post',
+            url,
+            data=query_xml.encode('utf-8'),
+            headers={'Content-Type': 'application/xml'},
+            **kwargs,
+        )
+
+    def create_element(self, element_class: MidpointObjectType, xml_body: str) -> str | None:
+        """POST a new object to its collection; return its OID from the Location header (None if not reported)."""
+        url = self._collection_url(element_class)
+        response = self._rest_request(
+            'post',
+            url,
+            data=xml_body.encode('utf-8'),
+            headers={'Content-Type': 'application/xml'},
+        )
+        return self._created_oid(response)
+
+    def execute_action(self, element_class: MidpointObjectType, element_oid: str, action: str) -> bytes:
+        """POST an action on one object (``ws/rest/<collection>/<oid>/<action>``) and return the raw answer.
+
+        Actions are e.g. ``run``, ``suspend`` and ``resume`` on tasks, or ``test`` on resources,
+        whose answer is an ``OperationResultType`` document. The body is returned as undecoded
+        ``bytes``, to be parsed by the caller. Errors as described in the class docstring.
+        """
+        response = self._rest_request('post', self._object_url(element_class, element_oid, action))
+
+        return response.content
+
+    def get_endpoint(self, path: str) -> str:
+        """GET any path under the configured base URL (e.g. ``actuator/info``, ``ws/rest/self``).
+
+        Returns the answer body decoded to ``str``, whatever its format (XML or JSON). path is
+        relative to the base URL and is not validated: callers pass fixed paths only. Errors as
+        described in the class docstring.
+        """
+        url = self._url(path)
+        response = self._rest_request('get', url)
+        return response.content.decode()
+
+    def post_xml(self, path: str, xml_body: str) -> str:
+        """POST an XML body to an arbitrary path under the configured base URL."""
+        url = self._url(path)
+        response = self._rest_request(
+            'post',
+            url,
+            data=xml_body,
+            headers={'Content-Type': 'application/xml'},
+        )
+        return response.content.decode()
+
+    def put_element(self, xml_filename: str, patch_file: str | None, patch_write: bool) -> PutResult:
+        """Upload an object from an XML file, creating or replacing it.
+
+        A root element with an ``oid`` attribute is PUT to the object URL, which creates or
+        overwrites the object at that OID. Without one, the document is POSTed to the type
+        collection and the server picks the OID, read back from the ``Location`` header.
+        The patch, if any, is applied first, so it may add, change or drop the OID.
+
+        xml_filename is the local file to upload. patch_file, if not None, is an XML patch file
+        applied to it first; with patch_write the patched document is also written next to the
+        patch file (``<patch_file>.xml``). Returns a PutResult with the object type, its OID
+        (None when the server created the object without reporting one) and whether it was
+        created by POST.
+
+        Raises OSError when a file cannot be read, ParseError when the document is not XML,
+        MidpointTypeNotFound when its root element is not a known object type,
+        MidpointUnsupportedOperation when the type has no REST collection, and the errors
+        described in the class docstring.
+        """
+        with open(xml_filename) as xml_file:
+            xml_body = xml_file.read()
+
+        if patch_file is not None:
+            xml_body = patch_from_file(xml_body, patch_file, patch_write)
+
+        # A local file, not server XML: parsed with the standard parser, as before, so the user's own
+        # files keep working whatever they declare (S314 targets untrusted input).
+        tree_root = ElementTree.fromstring(xml_body)  # noqa: S314
+
+        root_tag_name = tree_root.tag.split('}', 1)[1] if '}' in tree_root.tag else tree_root.tag  # strip namespace
+        object_type = MidpointObjectTypes.find_by_name(root_tag_name)
+
+        if not object_type.endpoint:
+            raise MidpointUnsupportedOperation(f'Upload of {object_type} is not supported through REST API')
+
+        object_oid = tree_root.attrib.get('oid')
+        headers = {'Content-Type': 'application/xml'}
+
+        if object_oid is None:
+            collection_url = self._collection_url(object_type)
+            response = self._rest_request('post', collection_url, data=xml_body, headers=headers)
+            return PutResult(object_type, self._created_oid(response), created=True)
+
+        # The OID comes from the uploaded file, so it is validated before anything is sent.
+        target_url = self._object_url(object_type, object_oid)
+        self._rest_request('put', target_url, data=xml_body, headers=headers)
+        return PutResult(object_type, object_oid, created=False)
+
+    @staticmethod
+    def _created_oid(response: requests.Response) -> str | None:
+        """Read the OID of a newly created object from the Location header of a POST answer.
+
+        Midpoint answers 201 Created (202 Accepted for tasks) with a Location ending in the
+        new OID. An answer without Location means the object was accepted but not created
+        yet, e.g. while it waits for an approval, so it has no OID to report.
+        """
+        location = response.headers.get('Location')
+        if not location:
+            return None
+        oid = urlparse(location).path.rstrip('/').rsplit('/', 1)[-1]
+        try:
+            return _check_path_segment(oid)
+        except MidpointInvalidOid as e:
+            raise MidpointServerError(
+                f'The object was created, but the Location header {location!r} does not end with a valid OID'
+            ) from e

midpoint_cli/client/safe_xml.py

@@ -0,0 +1,24 @@
+"""Parsing of XML received from the server, hardened with defusedxml.
+
+The stdlib parser expands internal entities, so a hostile or intercepted response
+(plain http://) could exhaust memory with a "billion laughs" document. defusedxml
+refuses entity declarations and external references instead.
+"""
+
+from xml.etree.ElementTree import Element, ParseError
+
+from defusedxml import DefusedXmlException
+from defusedxml.ElementTree import fromstring as _defused_fromstring
+
+
+def fromstring(text: str | bytes) -> Element:
+    """Parse server-supplied XML into an Element.
+
+    A refused construct is raised as ``ParseError`` so callers keep a single
+    error path for any response that cannot be used as XML.
+    """
+    try:
+        root: Element = _defused_fromstring(text)
+    except DefusedXmlException as e:
+        raise ParseError(f'Refused unsafe XML from the server: {e}') from e
+    return root

midpoint_cli/client/server_info.py

@@ -0,0 +1,130 @@
+"""What `info` shows about the server, and how it is read from each REST source.
+
+Midpoint has no single REST call for the "About" page of the web UI, so the information is
+gathered from calls that every supported release (4.4 to 4.11) answers the same way:
+
+* ``actuator/info``: version, build, branch, build timestamp and license (see server_version.py);
+* ``ws/rest/nodes``: the cluster nodes, each with its host, state, Midpoint build and last
+  check-in (NodeType, unchanged from 4.4.11 to 4.11.0);
+* ``ws/rest/systemConfigurations/<oid>``: the deployment name and whether a subscription
+  identifier is configured (SystemConfigurationType/deploymentInformation);
+* ``ws/rest/self``: the account the CLI is logged in as.
+
+The repository implementation is not exposed over REST. Midpoint 4.10 dropped the generic
+(SQL) repository, so from 4.10 on the repository is known to be the native PostgreSQL one;
+for earlier versions it is reported as unknown.
+"""
+
+from dataclasses import dataclass, field
+from xml.etree.ElementTree import Element
+
+from midpoint_cli.client.objects import namespaces
+from midpoint_cli.client.server_version import MidpointVersion
+
+# OID of the single SystemConfigurationType object, the same in every Midpoint release.
+SYSTEM_CONFIGURATION_OID = '00000000-0000-0000-0000-000000000001'
+
+# The 4.10.5 and 4.11.0 distributions no longer ship repo-sql-impl, the generic repository.
+NATIVE_REPOSITORY_ONLY_SINCE = (4, 10)
+
+# actuator/info fields and the label `info` shows them under, in display order.
+ACTUATOR_FIELDS = (
+    ('version', 'Midpoint Version'),
+    ('build', 'Build'),
+    ('branch', 'Branch'),
+    ('buildTimestamp', 'Build Timestamp'),
+    ('license', 'License'),
+)
+
+
+def _text(parent: Element | None, path: str) -> str | None:
+    """Stripped text of the element at path under parent, or None when missing or blank."""
+    node = parent.find(path, namespaces) if parent is not None else None
+    text = node.text.strip() if node is not None and node.text is not None else ''
+    return text or None
+
+
+@dataclass
+class ServerInformation:
+    """Server properties in display order, and the sources that could not be read, with the reason."""
+
+    properties: dict[str, str] = field(default_factory=dict)
+    unavailable: list[str] = field(default_factory=list)
+
+
+@dataclass
+class NodeInformation:
+    identifier: str
+    hostname: str | None = None
+    state: str | None = None
+    version: str | None = None
+    last_check_in: str | None = None
+
+    def describe(self) -> str:
+        """One line for the node, e.g. 'mp1.example.com, running, Midpoint 4.8.14, last check-in 2026-...'."""
+        parts = [
+            self.hostname,
+            self.state,
+            f'Midpoint {self.version}' if self.version else None,
+            f'last check-in {self.last_check_in}' if self.last_check_in else None,
+        ]
+        return ', '.join(part for part in parts if part) or '(no details)'
+
+
+def parse_nodes(objects: Element) -> list[NodeInformation]:
+    """The nodes of a ws/rest/nodes object list.
+
+    The execution state (running, paused, error, ...) is more telling than the operational
+    state (up, down, starting), so it is shown when the node has one.
+    """
+    nodes = []
+    for node in objects:
+        identifier = _text(node, 'c:nodeIdentifier') or _text(node, 'c:name')
+        if identifier is None:
+            continue
+        nodes.append(
+            NodeInformation(
+                identifier=identifier,
+                hostname=_text(node, 'c:hostname'),
+                state=_text(node, 'c:executionState') or _text(node, 'c:operationalState'),
+                version=_text(node, 'c:build/c:version'),
+                last_check_in=_text(node, 'c:lastCheckInTime'),
+            )
+        )
+    return nodes
+
+
+def parse_logged_in_user(user: Element) -> str | None:
+    """'name (full name)' of the ws/rest/self answer, or just the name."""
+    name = _text(user, 'c:name')
+    if name is None:
+        return None
+    full_name = _text(user, 'c:fullName')
+    return f'{name} ({full_name})' if full_name and full_name != name else name
+
+
+def parse_deployment(system_configuration: Element) -> dict[str, str]:
+    """Deployment name and subscription status from the system configuration.
+
+    Only the presence of a subscription identifier is reported: its validity (format, check
+    digit, expiry) is decided by the server, with rules that changed across releases.
+    """
+    deployment = system_configuration.find('c:deploymentInformation', namespaces)
+    properties: dict[str, str] = {}
+    name = _text(deployment, 'c:name')
+    if name:
+        properties['Deployment Name'] = name
+    subscription = _text(deployment, 'c:subscriptionIdentifier')
+    properties['Subscription'] = (
+        'identifier configured (validity is checked by the server)' if subscription else 'none configured'
+    )
+    return properties
+
+
+def describe_repository(version: MidpointVersion | None) -> str | None:
+    """The repository implementation as far as the version tells, or None when the version is unknown."""
+    if version is None:
+        return None
+    if version.at_least(*NATIVE_REPOSITORY_ONLY_SINCE):
+        return 'native (PostgreSQL)'
+    return 'not reported over REST before Midpoint 4.10 (see the About page of the web UI)'