midpoint-cli 1.6.0__py3-none-any.whl

midpoint_cli/client/observer.py

@@ -0,0 +1,29 @@
+from abc import ABC, abstractmethod
+
+
+class MidpointCommunicationObserver(ABC):
+    @abstractmethod
+    def on_http_call(self):
+        pass
+
+    @abstractmethod
+    def on_http_error(self):
+        pass
+
+    @abstractmethod
+    def on_http_success(self):
+        pass
+
+    def on_http_failure(self):  # noqa: B027
+        """A request failed for good: no answer once the retries, if any, were exhausted."""
+
+
+class NopMidpointCommunicationObserver(MidpointCommunicationObserver):
+    def on_http_call(self):
+        pass
+
+    def on_http_error(self):
+        pass
+
+    def on_http_success(self):
+        pass

midpoint_cli/client/patch.py

@@ -0,0 +1,113 @@
+import contextlib
+import errno
+import os
+import re
+import sys
+
+FOLLOW_SYMLINKS_ENV_VAR = 'MIDPOINT_CLI_FOLLOW_SYMLINKS'
+_TRUE_VALUES = ('1', 'true', 'yes', 'on')
+
+
+def _follow_symlinks_allowed() -> bool:
+    """Whether the user opted in to writing exports through a symbolic link."""
+    return os.environ.get(FOLLOW_SYMLINKS_ENV_VAR, '').strip().lower() in _TRUE_VALUES
+
+
+def _symlink_refused(path: str) -> OSError:
+    message = (
+        f'{path} is a symbolic link; refusing to write through it '
+        f'(write to the link target instead, or set {FOLLOW_SYMLINKS_ENV_VAR}=1)'
+    )
+    return OSError(errno.ELOOP, message, path)
+
+
+def private_file_opener(path: str, flags: int) -> int:
+    """Opener for open() that keeps the file readable by its owner only.
+
+    Exported and patched object XML can carry connector passwords and PII. A new file is
+    created with mode 0600 directly, so there is no window where it is world-readable; an
+    existing file is tightened to 0600 before anything is written to it. Owners who cannot
+    change the mode of an existing file (e.g. one owned by someone else) still get it written.
+
+    The file itself must not be a symbolic link: a link planted in a shared directory would
+    otherwise redirect the export to, and truncate, whatever file it points to. O_NOFOLLOW
+    enforces this atomically where the platform has it; elsewhere the path is checked just
+    before opening. Only the last path component is checked, so linked directories still work.
+    Setting MIDPOINT_CLI_FOLLOW_SYMLINKS=1 restores the old behaviour for deliberate links.
+    """
+    refuse_links = not _follow_symlinks_allowed()
+    if refuse_links:
+        nofollow = getattr(os, 'O_NOFOLLOW', 0)
+        if nofollow:
+            flags |= nofollow
+        elif os.path.islink(path):
+            raise _symlink_refused(path)
+    try:
+        fd = os.open(path, flags, 0o600)
+    except OSError as e:
+        # O_NOFOLLOW reports a link as ELOOP (EMLINK on some BSDs); name the actual cause.
+        if refuse_links and e.errno in (errno.ELOOP, errno.EMLINK) and os.path.islink(path):
+            raise _symlink_refused(path) from e
+        raise
+    if hasattr(os, 'fchmod'):
+        with contextlib.suppress(OSError):
+            os.fchmod(fd, 0o600)
+    return fd
+
+
+def write_private_file(path: str, text: str) -> None:
+    """Write text to path, creating or truncating the file with mode 0600.
+
+    Raises OSError (with a descriptive strerror) when path is a symbolic link, unless
+    MIDPOINT_CLI_FOLLOW_SYMLINKS is set.
+    """
+    with open(path, 'w', opener=private_file_opener) as f:
+        f.write(text)
+
+
+class PatchError(ValueError):
+    """A patch file line cannot be applied (e.g. it is not a valid regular expression)."""
+
+
+def patch_from_string(body: str, patch: str) -> str:
+    """Apply a line-oriented patch to body and return the result.
+
+    Each non-blank line not starting with '#' is ``PATTERN => REPLACEMENT``; a line without
+    ' =>' deletes every match of PATTERN. Only the first ' =>' separates the two sides, so a
+    replacement may itself contain '=>'. Both sides are stripped of surrounding whitespace.
+
+    PATTERN is a Python regular expression and REPLACEMENT a re.sub template, on purpose:
+    patches can use constructs such as ``<!--.*`` and ``\\1``. Regex metacharacters ('.', '(',
+    '*', '\\', ...) therefore keep their regex meaning and must be escaped to match literally;
+    a backslash in a replacement value (e.g. a password) must be doubled. A line that matches
+    nothing prints a warning and leaves body unchanged. An invalid pattern or template raises
+    PatchError naming the offending line.
+    """
+    for line in patch.splitlines():
+        line = line.strip()
+        if line != '' and line[0] != '#':
+            items = line.split(' =>', 1)
+            if len(items) == 1:
+                pattern = items[0]
+                replacement = ''
+            else:
+                pattern, replacement = items
+            try:
+                body, subs = re.subn(pattern.strip(), replacement.strip(), body)
+            except re.error as e:
+                raise PatchError(f'invalid patch line {line!r}: {e}') from e
+
+            if subs == 0:
+                print('Warning: replacement not applied:', line, file=sys.stderr)
+
+    return body
+
+
+def patch_from_file(xml_body: str, patch_file: str, patch_write: bool) -> str:
+    with open(patch_file) as f:
+        patch_text = f.read()
+        xml_body = patch_from_string(xml_body, patch_text)
+    if patch_write:
+        write_private_file(patch_file + '.xml', xml_body)
+
+    return xml_body

midpoint_cli/client/progress.py

@@ -0,0 +1,80 @@
+from abc import ABC, abstractmethod
+from datetime import datetime
+
+
+class ProgressMonitor(ABC):
+    """Abstract base class for task progress monitors."""
+
+    @abstractmethod
+    def update(self, progress: int) -> None:
+        """Update the progress display with the current progress value."""
+        pass
+
+    def update_with_stats(self, progress: int, success_count: int = 0, failure_count: int = 0) -> None:
+        """
+        Update the progress display with current progress and success/failure statistics.
+
+        This is an optional method that implementations can override to display
+        detailed statistics. Default implementation falls back to simple update().
+
+        Args:
+            progress: Current progress value (total items processed)
+            success_count: Number of successfully processed items
+            failure_count: Number of failed items
+        """
+        self.update(progress)
+
+    def set_expected_total(self, total: int | None) -> None:  # noqa: B027
+        """
+        Set the number of items the task expects to process, when the server knows it.
+
+        Optional: monitors that draw a bar can show the progress against it. None means
+        the total is unknown.
+        """
+        ...
+
+    def log_event(self, event) -> None:  # noqa: B027
+        """
+        Render a single audit event inline alongside the progress display.
+
+        Default is a no-op so monitors that don't care about audit (e.g. NopProgressMonitor)
+        need not implement this. TTY monitors should print above the progress bar; non-TTY
+        monitors should print on a fresh line so they don't fuse with batched output.
+        """
+        ...
+
+    def set_task_start_time(self, start_time: datetime | None) -> None:  # noqa: B027
+        """
+        Set the task's original start time for elapsed time calculation.
+
+        This allows the progress monitor to show elapsed time from when the task
+        originally started, not from when monitoring began. Optional method that
+        implementations can override if they support elapsed time display.
+
+        Args:
+            start_time: The datetime when the task originally started, or None
+        """
+        ...
+
+    @abstractmethod
+    def __enter__(self):
+        """Enter context manager."""
+        pass
+
+    @abstractmethod
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Exit context manager."""
+        pass
+
+
+class NopProgressMonitor(ProgressMonitor):
+    """No-op implementation."""
+
+    def update(self, progress: int) -> None:
+        pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        pass