midpoint-cli 1.6.0__py3-none-any.whl

midpoint_cli/client/object_query.py

@@ -0,0 +1,230 @@
+"""QueryType construction for Midpoint REST object searches.
+
+Name lookups, searches, filtered listings and completion all go through
+``POST ws/rest/<collection>/search`` with a ``<q:query>`` body built here, so the
+server filters and pages instead of the CLI downloading whole collections.
+
+The constructs used are part of the query language of every supported release
+(Midpoint 4.4 to 4.11, generic and native repository alike): ``equal``,
+``substring`` (with ``anchorStart``), ``inOid``, ``ref``, ``and``/``or``, ``text`` (a
+Midpoint Query Language filter, parsed by the server), the
+``polyStringOrig``/``polyStringNorm``/``stringIgnoreCase`` matching rules, and
+``paging`` with ``orderBy``/``maxSize``.
+
+Every value that may come from the command line is XML-escaped; paths and matching
+rule names are checked against a strict pattern because they are written verbatim.
+"""
+
+import re
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from xml.sax.saxutils import escape as xml_escape
+from xml.sax.saxutils import quoteattr
+
+from midpoint_cli.client.constants import COMMON_NS, QUERY_NS, ResultStatus, TaskExecutionState
+
+# Item paths and matching rule names are written unescaped, so only plain names are allowed.
+_SAFE_TOKEN = re.compile(r'[A-Za-z][A-Za-z0-9]*(/[A-Za-z][A-Za-z0-9]*)*')
+
+# Midpoint's canonical OID form. A reference in this form is taken as an OID without a name search.
+OID_RE = re.compile(r'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$', re.IGNORECASE)
+
+# Exact, case-sensitive name equality: what the CLI compared before searching on the server.
+NAME_EXACT = 'polyStringOrig'
+# Case- and accent-insensitive comparison of a PolyString; the server normalizes the query value too.
+POLYSTRING_NORM = 'polyStringNorm'
+STRING_IGNORE_CASE = 'stringIgnoreCase'
+
+# (path, matching rule) pairs that `<type> search` terms are matched against.
+USER_SEARCH_PATHS: tuple[tuple[str, str], ...] = (
+    ('name', POLYSTRING_NORM),
+    ('fullName', POLYSTRING_NORM),
+    ('emailAddress', STRING_IGNORE_CASE),
+)
+ROLE_SEARCH_PATHS: tuple[tuple[str, str], ...] = (
+    ('name', POLYSTRING_NORM),
+    ('displayName', POLYSTRING_NORM),
+)
+ORG_SEARCH_PATHS = ROLE_SEARCH_PATHS
+
+
+def is_oid(reference: str) -> bool:
+    """True if reference has Midpoint's canonical (UUID) OID form."""
+    return OID_RE.match(reference) is not None
+
+
+def _token(value: str, what: str) -> str:
+    if _SAFE_TOKEN.fullmatch(value) is None:
+        raise ValueError(f'Invalid query {what}: {value!r}')
+    return value
+
+
+def _value_filter(kind: str, path: str, value: str, matching: str | None = None, extra: str = '') -> str:
+    matching_xml = f'<q:matching>{_token(matching, "matching rule")}</q:matching>' if matching else ''
+    return (
+        f'<q:{kind}>{matching_xml}<q:path>{_token(path, "path")}</q:path>'
+        f'<q:value>{xml_escape(value)}</q:value>{extra}</q:{kind}>'
+    )
+
+
+def equal_filter(path: str, value: str, matching: str | None = None) -> str:
+    """An ``equal`` filter on a single-valued item."""
+    return _value_filter('equal', path, value, matching)
+
+
+def substring_filter(path: str, value: str, matching: str | None = None, anchor_start: bool = False) -> str:
+    """A ``substring`` filter; with anchor_start, a prefix match."""
+    extra = '<q:anchorStart>true</q:anchorStart>' if anchor_start else ''
+    return _value_filter('substring', path, value, matching, extra)
+
+
+def ref_filter(path: str, oid: str) -> str:
+    """A ``ref`` filter: the reference at path (e.g. resourceRef) points to the object with this OID."""
+    return f'<q:ref><q:path>{_token(path, "path")}</q:path><q:value oid={quoteattr(oid)}/></q:ref>'
+
+
+def in_oid_filter(oids: Iterable[str]) -> str:
+    """An ``inOid`` filter matching any of the given OIDs."""
+    values = ''.join(f'<q:value>{xml_escape(oid)}</q:value>' for oid in oids)
+    return f'<q:inOid>{values}</q:inOid>'
+
+
+def text_filter(text: str) -> str:
+    """A filter written in the Midpoint Query Language (Axiom), parsed by the server.
+
+    The ``text`` element of SearchFilterType is part of the query schema of 4.4 to 4.11. The
+    text is escaped like any value: the server, not the CLI, interprets it.
+    """
+    return f'<q:text>{xml_escape(text)}</q:text>'
+
+
+# `task ls --status` values: the task item each one tests and the values it accepts. Execution
+# states are TaskType/executionState (4.4+, values running, runnable, waiting, suspended, closed);
+# results are TaskType/resultStatus, the result of the last run.
+TASK_STATUS_FILTERS: dict[str, tuple[str, tuple[str, ...]]] = {
+    TaskExecutionState.RUNNING: ('executionState', (TaskExecutionState.RUNNING,)),
+    TaskExecutionState.RUNNABLE: ('executionState', (TaskExecutionState.RUNNABLE,)),
+    TaskExecutionState.WAITING: ('executionState', (TaskExecutionState.WAITING,)),
+    TaskExecutionState.SUSPENDED: ('executionState', (TaskExecutionState.SUSPENDED,)),
+    TaskExecutionState.CLOSED: ('executionState', (TaskExecutionState.CLOSED,)),
+    ResultStatus.IN_PROGRESS: ('resultStatus', (ResultStatus.IN_PROGRESS,)),
+    ResultStatus.SUCCESS: ('resultStatus', (ResultStatus.SUCCESS,)),
+    ResultStatus.WARNING: ('resultStatus', (ResultStatus.WARNING,)),
+    'failed': ('resultStatus', (ResultStatus.FATAL_ERROR, ResultStatus.PARTIAL_ERROR)),
+}
+
+
+def task_status_filter(statuses: Sequence[str]) -> str | None:
+    """Filter for `task ls --status`: tasks in any of the given statuses (see TASK_STATUS_FILTERS)."""
+    filters: list[str] = []
+    for status in statuses:
+        path, values = TASK_STATUS_FILTERS[status]
+        filters.extend(equal_filter(path, value) for value in values)
+    return or_filter(filters)
+
+
+def _combine(operator: str, filters: Sequence[str]) -> str | None:
+    if not filters:
+        return None
+    if len(filters) == 1:
+        return filters[0]
+    return f'<q:{operator}>' + ''.join(filters) + f'</q:{operator}>'
+
+
+def and_filter(filters: Sequence[str]) -> str | None:
+    """Combine filters with AND; a single filter is returned as is, none gives None."""
+    return _combine('and', filters)
+
+
+def or_filter(filters: Sequence[str]) -> str | None:
+    """Combine filters with OR; a single filter is returned as is, none gives None."""
+    return _combine('or', filters)
+
+
+def search_terms_filter(terms: Sequence[str], paths: Sequence[tuple[str, str]]) -> str | None:
+    """Filter for `<type> search` terms: each term is a substring of any of paths.
+
+    Terms prefixed with '+' are mandatory (AND); plain terms are optional (at least one must match).
+    """
+    mandatory = [t[1:] for t in terms if t.startswith('+') and t[1:]]
+    optional = [t for t in terms if t and not t.startswith('+')]
+
+    def path_filters(term: str) -> list[str]:
+        return [substring_filter(path, term, matching) for path, matching in paths]
+
+    def any_path(term: str) -> str:
+        combined = or_filter(path_filters(term))
+        if combined is None:
+            raise AssertionError
+        return combined
+
+    parts = [any_path(t) for t in mandatory]
+    # One flat OR for the optional terms: the 4.8 generic (H2) repository fails with a
+    # SQL error on an OR nested in an OR when one of the paths is emailAddress.
+    optional_part = or_filter([f for t in optional for f in path_filters(t)])
+    if optional_part is not None:
+        parts.append(optional_part)
+    return and_filter(parts)
+
+
+@dataclass
+class ObjectQuery:
+    """A Midpoint QueryType for an object search.
+
+    ``filter`` is a filter fragment built with the helpers of this module, which escape
+    every value; it is never assembled from raw user input.
+    """
+
+    filter: str | None = None
+    limit: int | None = None
+    order_by: str | None = None
+
+    def to_xml(self) -> str:
+        """Render the query as a Midpoint ``<q:query>`` XML document."""
+        filter_block = f'<q:filter>{self.filter}</q:filter>' if self.filter else ''
+
+        paging_items = ''
+        if self.order_by:
+            paging_items += f'<q:orderBy>{_token(self.order_by, "path")}</q:orderBy>'
+        if self.limit is not None and self.limit > 0:
+            paging_items += f'<q:maxSize>{int(self.limit)}</q:maxSize>'
+        paging = f'<q:paging>{paging_items}</q:paging>' if paging_items else ''
+
+        return f'<q:query xmlns:q="{QUERY_NS}" xmlns:c="{COMMON_NS}">{filter_block}{paging}</q:query>'
+
+    @classmethod
+    def name_equals(cls, name: str) -> 'ObjectQuery':
+        """Objects whose name is exactly name (case-sensitive)."""
+        return cls(filter=equal_filter('name', name, NAME_EXACT))
+
+    @classmethod
+    def listing(
+        cls, limit: int | None = None, name_filter: str | None = None, filters: Sequence[str] = ()
+    ) -> 'ObjectQuery':
+        """An ls listing: names containing name_filter (case-insensitive), at most limit objects, by name.
+
+        filters are further filter fragments (built with this module), all of which must match.
+        """
+        name_part = [substring_filter('name', name_filter, POLYSTRING_NORM)] if name_filter else []
+        return cls(filter=and_filter([*name_part, *filters]), limit=limit, order_by='name')
+
+    @classmethod
+    def text(cls, text: str, limit: int | None = None) -> 'ObjectQuery':
+        """A `search` query: a Midpoint Query Language filter, at most limit objects, by name."""
+        return cls(filter=text_filter(text), limit=limit, order_by='name')
+
+    @classmethod
+    def name_prefix(cls, prefix: str, limit: int) -> 'ObjectQuery':
+        """Completion candidates: names starting with prefix (case-insensitive), at most limit, by name."""
+        object_filter = substring_filter('name', prefix, POLYSTRING_NORM, anchor_start=True) if prefix else None
+        return cls(filter=object_filter, limit=limit, order_by='name')
+
+    @classmethod
+    def terms(cls, terms: Sequence[str], paths: Sequence[tuple[str, str]]) -> 'ObjectQuery':
+        """A `<type> search` query, see search_terms_filter."""
+        return cls(filter=search_terms_filter(terms, paths), order_by='name')
+
+    @classmethod
+    def oids(cls, oids: Iterable[str]) -> 'ObjectQuery':
+        """Objects with any of the given OIDs."""
+        return cls(filter=in_oid_filter(oids))