midpoint-cli 1.6.0__py3-none-any.whl

midpoint_cli/client/server_version.py

@@ -0,0 +1,74 @@
+"""Midpoint server version, and the version-dependent choices the client makes.
+
+The version comes from the ``version`` field of ``actuator/info``, which every
+supported release (4.4 to 4.11) fills from the Maven project version, e.g.
+``4.8.14``, ``4.11.0`` or ``4.10-SNAPSHOT``. When it cannot be read, callers
+pass ``None`` and fall back to the older heuristics.
+"""
+
+import re
+from dataclasses import dataclass, field
+
+_VERSION_RE = re.compile(r'^\s*v?(\d+)\.(\d+)(?:\.(\d+))?')
+
+
+@dataclass(frozen=True, order=True)
+class MidpointVersion:
+    major: int
+    minor: int
+    patch: int = 0
+    text: str = field(default='', compare=False)
+
+    def at_least(self, major: int, minor: int, patch: int = 0) -> bool:
+        return (self.major, self.minor, self.patch) >= (major, minor, patch)
+
+    def __str__(self) -> str:
+        return self.text or f'{self.major}.{self.minor}.{self.patch}'
+
+
+def parse_server_version(text: object) -> MidpointVersion | None:
+    """Parse a Midpoint version string such as ``4.8.14`` or ``4.11-SNAPSHOT``; None if it is not one."""
+    if not isinstance(text, str):
+        return None
+    match = _VERSION_RE.match(text)
+    if match is None:
+        return None
+    major, minor, patch = match.groups()
+    return MidpointVersion(int(major), int(minor), int(patch or 0), text.strip())
+
+
+def describe_version(version: MidpointVersion | None) -> str:
+    """Name the server version in a message, e.g. 'Midpoint 4.8.14' or 'Midpoint (version unknown)'."""
+    return f'Midpoint {version}' if version is not None else 'Midpoint (version unknown)'
+
+
+# TaskType/executionState replaced executionStatus in 4.4. The 4.4.11 to 4.11.0 schemas only
+# know executionState, and the task's last run result is TaskType/resultStatus in all of them.
+TASK_EXECUTION_STATE_SINCE = (4, 4)
+
+# Midpoint 4.11 makes MEL the default script language and refuses Groovy until the server
+# opts in, so earlier versions never answer with a script refusal.
+GROOVY_REFUSED_BY_DEFAULT_SINCE = (4, 11)
+
+# The audit script reaches Spring beans through SpringApplicationContextHolder. 4.5 added it to
+# model-impl; 4.4 only has the workflow-impl copy (checked in the v4.4.11 and v4.5 sources).
+_CONTEXT_HOLDER_MODEL_IMPL = 'com.evolveum.midpoint.model.impl.expr.SpringApplicationContextHolder'
+_CONTEXT_HOLDER_WORKFLOW_IMPL = 'com.evolveum.midpoint.wf.impl.processes.common.SpringApplicationContextHolder'
+_CONTEXT_HOLDER_MODEL_IMPL_SINCE = (4, 5)
+
+
+def task_uses_execution_state(version: MidpointVersion) -> bool:
+    """Whether the server names the task state executionState (4.4+) rather than executionStatus."""
+    return version.at_least(*TASK_EXECUTION_STATE_SINCE)
+
+
+def groovy_refused_by_default(version: MidpointVersion | None) -> bool:
+    """Whether a Groovy refusal is possible: on 4.11+ servers, or when the version is unknown."""
+    return version is None or version.at_least(*GROOVY_REFUSED_BY_DEFAULT_SINCE)
+
+
+def audit_context_holder_class(version: MidpointVersion | None) -> str:
+    """Fully qualified SpringApplicationContextHolder class the audit script imports on this version."""
+    if version is not None and not version.at_least(*_CONTEXT_HOLDER_MODEL_IMPL_SINCE):
+        return _CONTEXT_HOLDER_WORKFLOW_IMPL
+    return _CONTEXT_HOLDER_MODEL_IMPL

midpoint_cli/client/session.py

@@ -0,0 +1,142 @@
+import logging
+import math
+import os
+import time
+import typing
+
+from requests import PreparedRequest, Response
+from requests.adapters import HTTPAdapter
+from urllib3 import Retry
+from urllib3.exceptions import MaxRetryError, ReadTimeoutError, SSLError
+
+from midpoint_cli.client.observer import MidpointCommunicationObserver
+
+# Connection failures are retried with a fixed pause between attempts, within an overall
+# wall-clock budget counted from the first failure of a request. Retries only fire when no
+# answer was received, so an error status from the server is never retried. Callers that
+# start a Midpoint server and invoke the CLI straight away (integration and sandbox
+# scripts) should wait for the server themselves, or raise the budget with MIDPOINT_TIMEOUT.
+RETRY_TIMEOUT_SECONDS = 120.0
+RETRY_TIMEOUT_ENV_VAR = 'MIDPOINT_TIMEOUT'
+RETRY_BACKOFF_SECONDS = 2
+# Attempt cap derived from the time budget: the deadline is the real limit, the count only
+# keeps urllib3's own bookkeeping consistent with it.
+RETRY_ATTEMPTS = math.ceil(RETRY_TIMEOUT_SECONDS / RETRY_BACKOFF_SECONDS)
+
+# Read timeout: how long one REST call waits for the server's answer once connected. Some
+# calls (large searches, resource tests, synchronous task runs) legitimately take minutes.
+# A read timeout is never retried: the server may still be processing the request.
+READ_TIMEOUT_SECONDS = 300.0
+READ_TIMEOUT_ENV_VAR = 'MIDPOINT_READ_TIMEOUT'
+
+logger = logging.getLogger(__name__)
+
+
+def parse_retry_timeout(raw: str) -> float | None:
+    """Parse a retry budget in seconds; None unless *raw* holds a finite positive number."""
+    try:
+        value = float(raw)
+    except ValueError:
+        return None
+    if not math.isfinite(value) or value <= 0:
+        return None
+    return value
+
+
+def _timeout_from_environment(variable: str, default: float, environ: typing.Mapping[str, str] | None) -> float:
+    if environ is None:
+        environ = os.environ
+    raw = environ.get(variable)
+    if raw is None or raw.strip() == '':
+        return default
+    value = parse_retry_timeout(raw)
+    if value is None:
+        logger.warning(
+            'Ignoring %s=%r: expected a positive number of seconds; using %s s.',
+            variable,
+            raw,
+            default,
+        )
+        return default
+    return value
+
+
+def retry_timeout_seconds(environ: typing.Mapping[str, str] | None = None) -> float:
+    """Return the retry budget in seconds, from MIDPOINT_TIMEOUT when it holds a positive number."""
+    return _timeout_from_environment(RETRY_TIMEOUT_ENV_VAR, RETRY_TIMEOUT_SECONDS, environ)
+
+
+def read_timeout_seconds(environ: typing.Mapping[str, str] | None = None) -> float:
+    """Return the read timeout in seconds, from MIDPOINT_READ_TIMEOUT when it holds a positive number."""
+    return _timeout_from_environment(READ_TIMEOUT_ENV_VAR, READ_TIMEOUT_SECONDS, environ)
+
+
+def retry_attempts_for(timeout_seconds: float) -> int:
+    """Number of retries that fits in the given budget at RETRY_BACKOFF_SECONDS per pause."""
+    return max(1, math.ceil(timeout_seconds / RETRY_BACKOFF_SECONDS))
+
+
+class CustomRetryManager(Retry):
+    def __init__(
+        self,
+        observer: MidpointCommunicationObserver,
+        timeout_seconds: float = RETRY_TIMEOUT_SECONDS,
+        deadline: float | None = None,
+        **kwargs,
+    ):
+        self._observer = observer
+        self.timeout_seconds = timeout_seconds
+        # time.monotonic() value after which no further retry is attempted. None until the
+        # first failure of a request, so the mounted template never starts the clock.
+        self.deadline = deadline
+        super().__init__(**kwargs)
+
+    def get_backoff_time(self):
+        return RETRY_BACKOFF_SECONDS
+
+    def new(self, **kw: typing.Any) -> 'CustomRetryManager':
+        kw.setdefault('timeout_seconds', self.timeout_seconds)
+        kw.setdefault('deadline', self.deadline)
+        result = super().new(observer=self._observer, **kw)
+        return result
+
+    def increment(self, *args, **kwargs) -> 'CustomRetryManager':
+        self._observer.on_http_error()
+        error = kwargs.get('error')
+        url = kwargs.get('url', args[1] if len(args) > 1 else None)
+        # A TLS failure (bad certificate, protocol mismatch) will not fix itself while the
+        # server boots, so give up at once instead of spending the whole retry budget on it.
+        if isinstance(error, SSLError):
+            raise MaxRetryError(kwargs.get('_pool'), url, error) from error  # type: ignore[arg-type]  # as in urllib3
+        # The request reached the server, which may still be working on it: repeating it would
+        # at best wait another full read timeout and at worst apply a PUT or DELETE twice.
+        # Raised as is, like urllib3 does for read=False, so requests reports a ReadTimeout.
+        if isinstance(error, ReadTimeoutError):
+            raise error
+
+        now = time.monotonic()
+        deadline = self.deadline if self.deadline is not None else now + self.timeout_seconds
+        # Stop when the next pause would end past the deadline, so the overall wait is the
+        # budget plus at most one connect timeout of the attempt already in flight.
+        if error is not None and now + RETRY_BACKOFF_SECONDS > deadline:
+            raise MaxRetryError(kwargs.get('_pool'), url, error) from error  # type: ignore[arg-type]  # as in urllib3
+
+        result = super().increment(*args, **kwargs)
+        result.deadline = deadline
+        return result
+
+
+class CustomHTTPAdapter(HTTPAdapter):
+    def __init__(self, observer: MidpointCommunicationObserver, **kwargs):
+        super().__init__(**kwargs)
+        self._observer = observer
+
+    def send(self, request: PreparedRequest, *args: typing.Any, **kwargs: typing.Any) -> Response:
+        self._observer.on_http_call()
+        try:
+            response = super().send(request, *args, **kwargs)
+        except Exception:
+            self._observer.on_http_failure()
+            raise
+        self._observer.on_http_success()
+        return response

midpoint_cli/client/task_definitions.py

@@ -0,0 +1,110 @@
+"""TaskType documents for the tasks the CLI creates: resource import and reconciliation, report export.
+
+Midpoint has no REST operation that reconciles a resource or runs a report, and the one that
+imports from a resource (``POST resources/{oid}/import/{objectClass}``) only takes an object
+class. The CLI therefore creates the same activity-based task the GUI creates, by POSTing it to
+``ws/rest/tasks``; the server starts a ``runnable`` task on its own.
+
+Every construct used is in the task schema of 4.4.11, 4.8.14 and 4.11.0 (common-tasks-3.xsd):
+``activity/work`` with ``import``, ``reconciliation`` (``resourceObjects`` of type
+ResourceObjectSetType: ``resourceRef``, ``kind``, ``intent``, ``objectclass``) and
+``reportExport`` (``reportRef``). The archetypes assigned are initial objects of those releases
+(501 Reconciliation task, 503 Import task, 511 Report export task), so the GUI lists the tasks
+with the ones it creates. ``ownerRef`` and ``schedulingState`` are left out: the task manager
+sets the owner to the logged-in user and derives the scheduling state from ``executionState``.
+
+Every value that comes from the command line is XML-escaped.
+"""
+
+import re
+from datetime import UTC, datetime
+from xml.sax.saxutils import escape as xml_escape
+from xml.sax.saxutils import quoteattr
+
+from midpoint_cli.client.constants import COMMON_NS, RESOURCE_INSTANCE_NS
+
+ARCHETYPE_RECONCILIATION_TASK = '00000000-0000-0000-0000-000000000501'
+ARCHETYPE_IMPORT_TASK = '00000000-0000-0000-0000-000000000503'
+ARCHETYPE_REPORT_EXPORT_TASK = '00000000-0000-0000-0000-000000000511'
+
+# ShadowKindType values that designate resource objects (unknown is not a valid selection).
+SHADOW_KINDS = ('account', 'entitlement', 'generic')
+
+# An object class is written as a QName in the resource instance namespace, so only a plain
+# local name (e.g. AccountObjectClass, inetOrgPerson) is accepted.
+_OBJECT_CLASS = re.compile(r'[A-Za-z_][A-Za-z0-9_.-]*')
+
+# The activity work item of each resource task kind, with its archetype and name prefix.
+RESOURCE_TASKS: dict[str, tuple[str, str, str]] = {
+    'import': ('import', ARCHETYPE_IMPORT_TASK, 'Import from'),
+    'reconcile': ('reconciliation', ARCHETYPE_RECONCILIATION_TASK, 'Reconciliation of'),
+}
+
+
+def _timestamp(now: datetime | None = None) -> str:
+    """A UTC timestamp for task names, so two runs do not create tasks with the same name."""
+    return (now or datetime.now(UTC)).strftime('%Y-%m-%d %H:%M:%S UTC')
+
+
+def _task(name: str, archetype_oid: str, object_ref: str, work: str) -> str:
+    return (
+        f'<task xmlns="{COMMON_NS}" xmlns:c="{COMMON_NS}" xmlns:ri="{RESOURCE_INSTANCE_NS}">'
+        f'<name>{xml_escape(name)}</name>'
+        f'<assignment><targetRef oid="{archetype_oid}" type="c:ArchetypeType"/></assignment>'
+        '<executionState>runnable</executionState>'
+        f'{object_ref}'
+        f'<activity><work>{work}</work></activity>'
+        '</task>'
+    )
+
+
+def resource_task_name(
+    operation: str, resource_name: str, kind: str | None, intent: str | None, object_class: str | None
+) -> str:
+    """The name of a resource import or reconciliation task, e.g. 'Import from HR (account/default) 2026-...'."""
+    _, _, prefix = RESOURCE_TASKS[operation]
+    selection = object_class or '/'.join(part for part in (kind, intent) if part)
+    suffix = f' ({selection})' if selection else ''
+    return f'{prefix} {resource_name}{suffix} {_timestamp()}'
+
+
+def resource_task_xml(
+    operation: str,
+    name: str,
+    resource_oid: str,
+    kind: str | None = None,
+    intent: str | None = None,
+    object_class: str | None = None,
+) -> str:
+    """A runnable import ('import') or reconciliation ('reconcile') task for objects of one resource.
+
+    The objects are selected by kind and intent, by object class, or both, as in the GUI.
+    """
+    work_item, archetype_oid, _ = RESOURCE_TASKS[operation]
+    if kind is not None and kind not in SHADOW_KINDS:
+        raise ValueError(f'Invalid kind {kind!r}: expected one of {", ".join(SHADOW_KINDS)}')
+    if object_class is not None and _OBJECT_CLASS.fullmatch(object_class) is None:
+        raise ValueError(f'Invalid object class {object_class!r}: expected a local name such as AccountObjectClass')
+
+    objects = f'<resourceRef oid={quoteattr(resource_oid)} type="c:ResourceType"/>'
+    if kind:
+        objects += f'<kind>{kind}</kind>'
+    if intent:
+        objects += f'<intent>{xml_escape(intent)}</intent>'
+    if object_class:
+        objects += f'<objectclass>ri:{object_class}</objectclass>'
+    work = f'<{work_item}><resourceObjects>{objects}</resourceObjects></{work_item}>'
+    object_ref = f'<objectRef oid={quoteattr(resource_oid)} type="c:ResourceType"/>'
+    return _task(name, archetype_oid, object_ref, work)
+
+
+def report_task_name(report_name: str) -> str:
+    """The name of a report export task, e.g. 'Export of report Users 2026-...'."""
+    return f'Export of report {report_name} {_timestamp()}'
+
+
+def report_task_xml(name: str, report_oid: str) -> str:
+    """A runnable classic report export task: the server writes the output as a ReportData object."""
+    work = f'<reportExport><reportRef oid={quoteattr(report_oid)} type="c:ReportType"/></reportExport>'
+    object_ref = f'<objectRef oid={quoteattr(report_oid)} type="c:ReportType"/>'
+    return _task(name, ARCHETYPE_REPORT_EXPORT_TASK, object_ref, work)

midpoint_cli/prompt/__init__.py

@@ -0,0 +1,196 @@
+import contextlib
+import shlex
+import sys
+from cmd import Cmd
+from pathlib import Path
+
+from prompt_toolkit import PromptSession
+from prompt_toolkit.history import FileHistory
+from prompt_toolkit.styles import Style
+
+from midpoint_cli.client import MidpointClient
+from midpoint_cli.prompt.audit import AuditClientPrompt
+from midpoint_cli.prompt.complete import MidpointCompleter
+from midpoint_cli.prompt.configuration import ResolvedConfiguration
+from midpoint_cli.prompt.connector import ConnectorClientPrompt
+from midpoint_cli.prompt.console import OUTPUT_TABLE, get_console, print_error, set_output_format
+from midpoint_cli.prompt.delete import DeleteClientPrompt
+from midpoint_cli.prompt.get import GetClientPrompt
+from midpoint_cli.prompt.info import InfoClientPrompt
+from midpoint_cli.prompt.log import LogClientPrompt
+from midpoint_cli.prompt.org import OrgClientPrompt
+from midpoint_cli.prompt.output import OutputClientPrompt
+from midpoint_cli.prompt.put import PutClientPrompt
+from midpoint_cli.prompt.report import ReportClientPrompt
+from midpoint_cli.prompt.resource import ResourceClientPrompt
+from midpoint_cli.prompt.role import RoleClientPrompt
+from midpoint_cli.prompt.script import ScriptClientPrompt
+from midpoint_cli.prompt.search import SearchClientPrompt
+from midpoint_cli.prompt.shadow import ShadowClientPrompt
+from midpoint_cli.prompt.task import TaskClientPrompt
+from midpoint_cli.prompt.user import UserClientPrompt
+
+
+def open_history(history_file: Path) -> FileHistory:
+    """Open the command history, keeping it readable by the owner only.
+
+    History lines can carry OIDs, user names and anything else typed at the prompt, so the
+    file is created with mode 0600 and an existing file is tightened to it. prompt_toolkit
+    would otherwise create it with the process umask (commonly 0644).
+    """
+    history_file.touch(mode=0o600, exist_ok=True)
+    with contextlib.suppress(OSError):
+        history_file.chmod(0o600)
+    return FileHistory(str(history_file))
+
+
+__all__ = ['MidpointClientPrompt', 'MidpointCompleter', 'open_history']
+
+
+class MidpointClientPrompt(
+    Cmd,
+    TaskClientPrompt,
+    GetClientPrompt,
+    PutClientPrompt,
+    DeleteClientPrompt,
+    ResourceClientPrompt,
+    UserClientPrompt,
+    OrgClientPrompt,
+    RoleClientPrompt,
+    ScriptClientPrompt,
+    InfoClientPrompt,
+    LogClientPrompt,
+    AuditClientPrompt,
+    ShadowClientPrompt,
+    ConnectorClientPrompt,
+    ReportClientPrompt,
+    SearchClientPrompt,
+    OutputClientPrompt,
+):
+    def __init__(
+        self,
+        client: MidpointClient,
+        configuration: ResolvedConfiguration | None = None,
+        output_format: str = OUTPUT_TABLE,
+    ):
+        Cmd.__init__(self)
+        set_output_format(output_format)
+        is_a_tty = hasattr(sys.stdin, 'isatty') and sys.stdin.isatty()
+        self.client = client
+        self.configuration = configuration
+        self.error_code = 0
+        self.error_message = None
+        # Sticky across commands: the exit code of the first failed line, so a piped script
+        # fails if any line failed, with that line's code (e.g. a `script run` sys.exit(3)).
+        self.first_error_code = 0
+        self.prompt = '\033[32mmidpoint\033[0m> ' if is_a_tty else ''
+        self.intro = 'Welcome to Midpoint client ! Type ? for a list of commands' if is_a_tty else None
+        self._is_tty = is_a_tty
+
+        # Initialize prompt-toolkit session for interactive mode
+        self._session: PromptSession | None = None
+        if is_a_tty:
+            prompt_style = Style.from_dict({'prompt': 'fg:green bold'})
+            self._session = PromptSession(
+                history=open_history(Path.home() / '.midpoint-cli-history'),
+                completer=MidpointCompleter(type(self), client=self.client),
+                style=prompt_style,
+                complete_while_typing=True,
+                enable_history_search=True,
+            )
+
+    def default(self, line: str) -> None:
+        """Report an unrecognized command instead of letting it pass with exit 0.
+
+        cmd.Cmd.default only prints to stdout, so a typo in a script went unnoticed.
+        """
+        command = line.split()[0] if line.split() else line
+        self.error_code = 1
+        self.error_message = f'Unknown command: {command}'
+
+    def _reset_error(self) -> None:
+        self.error_code = 0
+        self.error_message = None
+
+    def _log_error(self) -> None:
+        if self.error_message:
+            print_error(self.error_message)
+
+    def onecmd(self, line: str) -> bool:
+        self._reset_error()
+
+        # True stops the command loop (exit, EOF); a blank or rejected line never does.
+        res = False
+        if line.strip() == '':
+            pass
+        elif self._check_quoting(line):
+            try:
+                res = Cmd.onecmd(self, line)
+            except SystemExit as e:
+                # argparse exits 0 for -h and 2 for a usage error, which it has
+                # already printed; only the exit code is left to set.
+                self.error_code = 1 if e.code else 0
+
+        if self.error_code and not self.first_error_code:
+            self.first_error_code = self.error_code
+        self._log_error()
+        return res
+
+    @property
+    def any_error(self) -> bool:
+        """True once any command of this session has failed."""
+        return bool(self.first_error_code)
+
+    def _check_quoting(self, line: str) -> bool:
+        """Reject a line shlex cannot split (e.g. an unbalanced quote) before any command runs."""
+        try:
+            shlex.split(line)
+        except ValueError as e:
+            self.error_code = 1
+            self.error_message = f'Invalid quoting: {e}'
+            return False
+        return True
+
+    def can_exit(self) -> bool:
+        return True
+
+    def do_EOF(self, inp: str) -> bool:
+        console = get_console()
+        console.print()
+        return self.do_exit(inp)
+
+    def do_exit(self, inp: str) -> bool:
+        return True
+
+    def help_exit(self) -> None:
+        print('Exit the shell')
+
+    def cmdloop(self, intro: object | None = None) -> None:
+        """Enhanced cmdloop using prompt-toolkit for interactive mode."""
+        if self._session and self._is_tty:
+            # Use prompt-toolkit for enhanced interactive experience
+            console = get_console()
+            if intro or self.intro:
+                console.print(intro or self.intro, style='cyan')
+
+            stop = None
+            while not stop:
+                try:
+                    line = self._session.prompt([('class:prompt', 'midpoint> ')])
+                    line = self.precmd(line)
+                    stop = self.onecmd(line)
+                    stop = self.postcmd(stop, line)
+                except KeyboardInterrupt:
+                    console.print('^C')
+                    continue
+                except EOFError:
+                    console.print()
+                    break
+                except Exception as e:
+                    print_error(f'Unexpected error: {e}')
+                    continue
+
+            self.postloop()
+        else:
+            # Fall back to standard cmd.Cmd for non-TTY
+            Cmd.cmdloop(self, intro)