midpoint-cli 1.6.0__py3-none-any.whl

midpoint_cli/prompt/complete.py

@@ -0,0 +1,291 @@
+"""Tab completion for the interactive prompt.
+
+The completer derives everything from the command classes and their argparse parsers, so
+completion cannot drift from what the commands accept:
+
+* command names and descriptions come from the ``do_*`` methods and their docstrings;
+* subcommands come from the ``subparsers_<command>`` mapping each command dispatches with;
+* options come from each parser's option strings;
+* argument values (object types, task/user/role/org/resource/report names, file paths) come from
+  the ``completer`` kind attached to a parser argument with :func:`completes`, or from its
+  ``choices`` (e.g. logging levels); an ``OBJECT_OF_TYPE`` argument completes the names of the
+  type given in the ``OBJECT_TYPE`` argument before it (``get user <name>``).
+
+Object names are searched on the server by name prefix, at most :data:`COMPLETION_LIMIT` at a
+time, so completion does not download whole collections.
+"""
+
+import glob
+import os
+import shlex
+import time
+from argparse import Action, ArgumentParser
+from collections.abc import Iterator
+
+from prompt_toolkit.completion import CompleteEvent, Completer, Completion
+from prompt_toolkit.document import Document
+
+from midpoint_cli.client import MidpointClient
+from midpoint_cli.client.objects import MidpointObjectList, MidpointObjectTypes, MidpointTypeNotFound
+
+# Argument value kinds understood by MidpointCompleter.
+OBJECT_TYPE = 'object type'
+TASK = 'task'
+USER = 'user'
+ROLE = 'role'
+ORG = 'org'
+RESOURCE = 'resource'
+REPORT = 'report'
+FILE = 'file'
+# The name of an object whose type is the value of the OBJECT_TYPE argument (get, delete).
+OBJECT_OF_TYPE = 'object of type'
+
+# The object type whose names complete each object kind.
+_OBJECT_KIND_TYPES = {
+    TASK: MidpointObjectTypes.TASK,
+    USER: MidpointObjectTypes.USER,
+    ROLE: MidpointObjectTypes.ROLE,
+    ORG: MidpointObjectTypes.ORG,
+    RESOURCE: MidpointObjectTypes.RESOURCE,
+    REPORT: MidpointObjectTypes.REPORT,
+}
+_OBJECT_KINDS = tuple(_OBJECT_KIND_TYPES)
+
+# Most names offered per completion request: the server returns the first ones by name.
+COMPLETION_LIMIT = 50
+
+
+def completes(action: Action, kind: str) -> Action:
+    """Tag a parser argument with the kind of value the completer should offer for it."""
+    action.completer = kind  # type: ignore[attr-defined]
+    return action
+
+
+def _append_slash_if_dir(p: str) -> str:
+    if p and os.path.isdir(p) and p[-1] != os.sep:
+        return p + os.sep
+    else:
+        return p
+
+
+def split_command_line(text: str) -> tuple[list[str], str, int]:
+    """Split the text before the cursor the way shlex would, tolerating an unclosed quote.
+
+    Returns the completed words, the (unquoted) word under the cursor, and the length of
+    that word as typed, quotes included, so a completion can replace it.
+    """
+    words: list[str] = []
+    current = ''
+    in_word = False
+    quote: str | None = None
+    start = len(text)
+    for index, char in enumerate(text):
+        if quote is not None:
+            if char == quote:
+                quote = None
+            else:
+                current += char
+        elif char.isspace():
+            if in_word:
+                words.append(current)
+                current = ''
+                in_word = False
+        else:
+            if not in_word:
+                in_word = True
+                start = index
+            if char in '\'"':
+                quote = char
+            else:
+                current += char
+    if not in_word:
+        return words, '', 0
+    return words, current, len(text) - start
+
+
+def _object_kind_of_type(type_name: str) -> str | None:
+    """The object kind completing names of the type the user typed, or None for other types."""
+    try:
+        object_type = MidpointObjectTypes.find_by_name(type_name)
+    except MidpointTypeNotFound:
+        return None
+    for kind, kind_type in _OBJECT_KIND_TYPES.items():
+        if kind_type.value == object_type:
+            return kind
+    return None
+
+
+def _typed_object_type(parser: ArgumentParser, args: list[str]) -> str | None:
+    """The word given for the parser's OBJECT_TYPE positional, if already typed."""
+    positionals: list[str] = []
+    pending = False
+    for word in args:
+        if pending:
+            pending = False
+        elif word.startswith('-') and word != '-':
+            action = parser._option_string_actions.get(word)
+            pending = action is not None and action.nargs != 0
+        else:
+            positionals.append(word)
+
+    index = 0
+    for action in parser._actions:
+        if action.option_strings:
+            continue
+        if getattr(action, 'completer', None) == OBJECT_TYPE:
+            return positionals[index] if index < len(positionals) else None
+        index += action.nargs if isinstance(action.nargs, int) else 1
+    return None
+
+
+def _positional_for(parser: ArgumentParser, args: list[str]) -> Action | None:
+    """Return the action that the next word completes: an option value or a positional."""
+    pending: Action | None = None
+    index = 0
+    for word in args:
+        if pending is not None:
+            pending = None
+        elif word.startswith('-') and word != '-':
+            action = parser._option_string_actions.get(word)
+            if action is not None and action.nargs != 0:
+                pending = action
+        else:
+            index += 1
+    if pending is not None:
+        return pending
+
+    for action in parser._actions:
+        if action.option_strings:
+            continue
+        if action.nargs in ('*', '+'):
+            return action
+        count = action.nargs if isinstance(action.nargs, int) else 1
+        if index < count:
+            return action
+        index -= count
+    return None
+
+
+class MidpointCompleter(Completer):
+    """prompt_toolkit completer for the commands of ``command_class``."""
+
+    cache_ttl = 5  # Seconds a search result is reused, to avoid a server call per keystroke.
+
+    def __init__(self, command_class: type, client: MidpointClient | None = None) -> None:
+        self.command_class = command_class
+        self.client = client
+
+        # Main commands, with the first docstring line as description.
+        self.commands: dict[str, str] = {}
+        for name in sorted(dir(command_class)):
+            if name.startswith('do_') and name != 'do_EOF':
+                doc = getattr(command_class, name).__doc__
+                self.commands[name[3:]] = doc.strip().splitlines()[0] if doc else ''
+
+        # Completion candidates per (kind, name prefix), searched on the server.
+        self._cache: dict[tuple[str, str], tuple[float, MidpointObjectList]] = {}
+
+    def _get_objects(self, kind: str, prefix: str = '') -> MidpointObjectList:
+        """The objects of one kind whose name starts with prefix (case-insensitive), at most
+        COMPLETION_LIMIT, cached per (kind, prefix) for ``cache_ttl`` seconds; empty on any failure."""
+        if self.client is None:
+            return MidpointObjectList()
+
+        key = (kind, prefix)
+        now = time.time()
+        cached = self._cache.get(key)
+        if cached is not None and now - cached[0] < self.cache_ttl:
+            return cached[1]
+
+        try:
+            objects: MidpointObjectList = self.client.complete_names(
+                _OBJECT_KIND_TYPES[kind].value, prefix, COMPLETION_LIMIT
+            )
+        except Exception:
+            # A failing server must not break the prompt, and the failure is not cached:
+            # the next keystroke retries.
+            return MidpointObjectList()
+        self._cache[key] = (now, objects)
+        return objects
+
+    def get_completions(self, document: Document, complete_event: CompleteEvent) -> Iterator[Completion]:
+        words, current, typed = split_command_line(document.text_before_cursor)
+
+        if not words:
+            yield from self._complete_words(self.commands, current, typed)
+            return
+
+        command = words[0]
+        if command == 'help':
+            if len(words) == 1:
+                yield from self._complete_words(self.commands, current, typed)
+            return
+
+        subparsers = getattr(self.command_class, f'subparsers_{command}', None)
+        if subparsers is not None:
+            if len(words) == 1:
+                yield from self._complete_words(dict.fromkeys(subparsers, ''), current, typed)
+                return
+            parser = subparsers.get(words[1])
+            args = words[2:]
+        else:
+            parser = getattr(self.command_class, f'parser_{command}', None)
+            args = words[1:]
+
+        if parser is not None:
+            yield from self._complete_arguments(parser, args, current, typed)
+
+    @staticmethod
+    def _complete_words(candidates: dict[str, str], current: str, typed: int) -> Iterator[Completion]:
+        for word, description in candidates.items():
+            if word.startswith(current.lower()):
+                yield Completion(word, start_position=-typed, display_meta=description or None)
+
+    def _complete_arguments(
+        self, parser: ArgumentParser, args: list[str], current: str, typed: int
+    ) -> Iterator[Completion]:
+        if current.startswith('-'):
+            for option, option_action in parser._option_string_actions.items():
+                if option.startswith(current):
+                    yield Completion(option, start_position=-typed, display_meta=option_action.help)
+            return
+
+        action = _positional_for(parser, args)
+        kind = getattr(action, 'completer', None)
+        if kind == OBJECT_TYPE:
+            yield from self._complete_object_types(current, typed)
+        elif kind == FILE:
+            yield from self._complete_files(current, typed)
+        elif kind in _OBJECT_KINDS:
+            yield from self._complete_objects(kind, current, typed)
+        elif kind == OBJECT_OF_TYPE:
+            type_name = _typed_object_type(parser, args)
+            object_kind = _object_kind_of_type(type_name) if type_name else None
+            if object_kind is not None:
+                yield from self._complete_objects(object_kind, current, typed)
+        elif action is not None and action.choices:
+            # Choices such as logging levels, matched ignoring case.
+            for choice in map(str, action.choices):
+                if choice.lower().startswith(current.lower()):
+                    yield Completion(choice, start_position=-typed)
+
+    @staticmethod
+    def _complete_object_types(current: str, typed: int) -> Iterator[Completion]:
+        for object_type in MidpointObjectTypes:
+            tagname = object_type.value.tagname
+            if object_type.value.endpoint is not None and tagname.lower().startswith(current.lower()):
+                yield Completion(tagname, start_position=-typed, display_meta=object_type.value.object_type)
+
+    @staticmethod
+    def _complete_files(current: str, typed: int) -> Iterator[Completion]:
+        for path in sorted(glob.glob(glob.escape(current) + '*')):
+            path = _append_slash_if_dir(path)
+            yield Completion(shlex.quote(path), start_position=-typed, display=os.path.basename(path.rstrip(os.sep)))
+
+    def _complete_objects(self, kind: str, current: str, typed: int) -> Iterator[Completion]:
+        """Offer the names the server finds starting with the word, with the OID as metadata."""
+        for obj in self._get_objects(kind, current):
+            name = obj.get_name()
+            oid = obj.get_oid()
+            if name:
+                yield Completion(shlex.quote(name), start_position=-typed, display=name, display_meta=f'OID: {oid}')

midpoint_cli/prompt/configuration.py

@@ -0,0 +1,258 @@
+import ipaddress
+import logging
+import os
+import shlex
+from argparse import Namespace
+from configparser import ConfigParser
+from configparser import Error as ConfigParserError
+from dataclasses import dataclass, field
+from urllib.parse import urlsplit
+
+from midpoint_cli.client import MidpointClientConfiguration
+from midpoint_cli.client.session import (
+    READ_TIMEOUT_ENV_VAR,
+    READ_TIMEOUT_SECONDS,
+    RETRY_TIMEOUT_ENV_VAR,
+    RETRY_TIMEOUT_SECONDS,
+    parse_retry_timeout,
+)
+
+logger = logging.getLogger(__name__)
+
+_LOOPBACK_HOSTNAMES = frozenset({'localhost', 'localhost.localdomain'})
+
+HOME_CONFIGURATION_FILE = '~/.midpoint-cli.cfg'
+CONFIGURATION_FILE_VARIABLE = 'MIDPOINT_CLI_CONFIG'
+LEGACY_WORKING_DIRECTORY_FILE = 'midpoint-cli.cfg'
+
+
+class ConfigurationFileError(Exception):
+    """An explicitly requested configuration file is missing, unreadable or malformed."""
+
+
+def locate_configuration_file(cli_path: str | None, env_path: str | None) -> tuple[str | None, bool]:
+    """Return the configuration file to read and whether it was requested explicitly.
+
+    ``--config`` wins over ``MIDPOINT_CLI_CONFIG``; without either, only the home file is
+    read. A ``midpoint-cli.cfg`` in the working directory is never picked up implicitly: it
+    could come from any checkout and redirect the server URL that credentials are sent to.
+    """
+    explicit_path = cli_path or env_path
+    if explicit_path:
+        return os.path.expanduser(explicit_path), True
+
+    home_path = os.path.expanduser(HOME_CONFIGURATION_FILE)
+    if os.path.isfile(home_path):
+        return home_path, False
+    return None, False
+
+
+def load_configuration_file(path: str | None) -> ConfigParser:
+    """Parse *path* into a ConfigParser; an empty parser when *path* is None.
+
+    Raises ConfigurationFileError when the file cannot be read or parsed.
+    """
+    parser = ConfigParser()
+    if path is None:
+        return parser
+
+    if not os.path.isfile(path):
+        raise ConfigurationFileError(f'configuration file not found: {path}')
+
+    try:
+        read = parser.read(path)
+    except (ConfigParserError, UnicodeDecodeError) as e:
+        raise ConfigurationFileError(f'cannot parse configuration file {path}: {e}') from e
+
+    if not read:
+        raise ConfigurationFileError(f'cannot read configuration file: {path}')
+    return parser
+
+
+def is_unencrypted_remote_url(url: str) -> bool:
+    """True when *url* would carry HTTP Basic credentials in clear text off the local machine.
+
+    Only plain ``http://`` to a non-loopback host qualifies: ``https://`` is encrypted and
+    a loopback address never leaves the host, which is the normal sandbox setup.
+    """
+    try:
+        parts = urlsplit(url)
+    except ValueError:
+        return False
+
+    if parts.scheme.lower() != 'http':
+        return False
+
+    host = (parts.hostname or '').lower()
+    if not host:
+        return False
+    return not _is_loopback_host(host)
+
+
+def _is_loopback_host(host: str) -> bool:
+    if host in _LOOPBACK_HOSTNAMES:
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+def is_loopback_url(url: str) -> bool:
+    """True when *url* points at this machine (``localhost`` or a loopback address)."""
+    try:
+        host = (urlsplit(url).hostname or '').lower()
+    except ValueError:
+        return False
+    return bool(host) and _is_loopback_host(host)
+
+
+def configuration_file_permission_warning(path: str | None, config: ConfigParser, url: str) -> str | None:
+    """Warn, SSH-style, when *path* holds a password and other local users can access it.
+
+    A file without a password exposes nothing, and a password for a server on this machine
+    is the sandbox case (the committed midpoint-cli.cfg is 0644 by design), so both are
+    skipped to keep the warning meaningful. POSIX permission bits do not apply on Windows.
+    """
+    if path is None or os.name == 'nt':
+        return None
+    if 'Midpoint' not in config or 'password' not in config['Midpoint']:
+        return None
+    if is_loopback_url(url):
+        return None
+
+    try:
+        mode = os.stat(path).st_mode & 0o777
+    except OSError:
+        return None
+    if not mode & 0o077:
+        return None
+
+    return (
+        f'Configuration file {path} holds a password and is accessible by other users '
+        f'(mode {mode:04o}). Restrict it with: chmod 600 {shlex.quote(path)}'
+    )
+
+
+def ignored_working_directory_file(config_path: str | None) -> str | None:
+    """Name ./midpoint-cli.cfg when it exists but is not the configuration file in use."""
+    if not os.path.isfile(LEGACY_WORKING_DIRECTORY_FILE):
+        return None
+    if (
+        config_path is not None
+        and os.path.isfile(config_path)
+        and os.path.samefile(config_path, LEGACY_WORKING_DIRECTORY_FILE)
+    ):
+        return None
+    return LEGACY_WORKING_DIRECTORY_FILE
+
+
+SOURCE_DEFAULT = 'default'
+
+_SETTINGS = ('url', 'username', 'password', 'timeout', 'read_timeout')
+_ENVIRONMENT_VARIABLES = (
+    'MIDPOINT_URL',
+    'MIDPOINT_USERNAME',
+    'MIDPOINT_PASSWORD',
+    RETRY_TIMEOUT_ENV_VAR,
+    READ_TIMEOUT_ENV_VAR,
+)
+_OPTIONS = ('--url', '--username', '--password', '--timeout', '--read-timeout')
+_TIMEOUT_SETTINGS = frozenset({'timeout', 'read_timeout'})
+
+
+@dataclass
+class ResolvedConfiguration:
+    """The effective client configuration and, for each setting, where its value came from."""
+
+    configuration: MidpointClientConfiguration
+    sources: dict[str, str] = field(default_factory=lambda: dict.fromkeys(_SETTINGS, SOURCE_DEFAULT))
+
+    def set(self, setting: str, value: str | float | None, source: str) -> None:
+        """Use *value* for *setting*, recording *source*; an empty value leaves the setting unchanged."""
+        if value:
+            setattr(self.configuration, setting, value)
+            self.sources[setting] = source
+
+    def describe(self) -> str:
+        """One line naming the server, the user, the timeouts and where each setting came from."""
+        timeout = self.configuration.timeout if self.configuration.timeout is not None else RETRY_TIMEOUT_SECONDS
+        read_timeout = self.configuration.read_timeout
+        if read_timeout is None:
+            read_timeout = READ_TIMEOUT_SECONDS
+        return (
+            f'Server {self.configuration.url} (from {self.sources["url"]}), '
+            f'user {self.configuration.username} (from {self.sources["username"]}), '
+            f'password from {self.sources["password"]}, '
+            f'retry timeout {timeout:g} s (from {self.sources["timeout"]}), '
+            f'read timeout {read_timeout:g} s (from {self.sources["read_timeout"]})'
+        )
+
+
+def _file_timeout(setting: str, raw: str, file_source: str) -> float:
+    value = parse_retry_timeout(raw)
+    if value is None:
+        raise ConfigurationFileError(
+            f'invalid {setting} {raw!r} in {file_source}: expected a positive number of seconds'
+        )
+    return value
+
+
+def _environment_timeout(variable: str, raw: str | None) -> float | None:
+    if raw is None or raw.strip() == '':
+        return None
+    value = parse_retry_timeout(raw)
+    if value is None:
+        logger.warning('Ignoring %s=%r: expected a positive number of seconds.', variable, raw)
+    return value
+
+
+def resolve_client_configuration(
+    ns: Namespace, config: ConfigParser, env: list[str | None], config_file: str | None = None
+) -> ResolvedConfiguration:
+    """Merge defaults, the configuration file, the environment and the command line, in that order.
+
+    *env* holds the values of MIDPOINT_URL, MIDPOINT_USERNAME, MIDPOINT_PASSWORD,
+    MIDPOINT_TIMEOUT and MIDPOINT_READ_TIMEOUT, in that order; missing trailing values count
+    as unset. *config_file* only names the file in the recorded sources.
+
+    Raises ConfigurationFileError when the configuration file holds an invalid timeout; an
+    invalid MIDPOINT_TIMEOUT or MIDPOINT_READ_TIMEOUT is ignored with a warning.
+    """
+    if len(env) > len(_ENVIRONMENT_VARIABLES):
+        raise ValueError(f'expected at most {len(_ENVIRONMENT_VARIABLES)} environment values, got {len(env)}')
+    env = [*env, *[None] * (len(_ENVIRONMENT_VARIABLES) - len(env))]
+    resolved = ResolvedConfiguration(
+        MidpointClientConfiguration(timeout=RETRY_TIMEOUT_SECONDS, read_timeout=READ_TIMEOUT_SECONDS)
+    )
+    apply = resolved.set
+
+    # Configuration file
+
+    if 'Midpoint' in config:
+        section_mp = config['Midpoint']
+        file_source = f'configuration file {config_file}' if config_file else 'configuration file'
+        for setting in _SETTINGS:
+            if setting in section_mp:
+                raw = section_mp[setting]
+                file_value: float | str = (
+                    _file_timeout(setting, raw, file_source) if setting in _TIMEOUT_SETTINGS else raw
+                )
+                apply(setting, file_value, file_source)
+
+    # Environment variables
+
+    for setting, variable, raw_value in zip(_SETTINGS, _ENVIRONMENT_VARIABLES, env, strict=True):
+        value = _environment_timeout(variable, raw_value) if setting in _TIMEOUT_SETTINGS else raw_value
+        apply(setting, value, f'environment variable {variable}')
+
+    # Command-line parameters (argparse has already validated --timeout and --read-timeout)
+
+    for setting, option in zip(_SETTINGS, _OPTIONS, strict=True):
+        if setting == 'password' and getattr(ns, 'ask_password', False):
+            source = 'password prompt'
+        else:
+            source = f'command-line option {option}'
+        apply(setting, getattr(ns, setting, None), source)
+
+    return resolved

midpoint_cli/prompt/connector.py

@@ -0,0 +1,45 @@
+from argparse import ArgumentParser, RawTextHelpFormatter
+
+from midpoint_cli.prompt.base import PromptBase, add_listing_arguments
+from midpoint_cli.prompt.console import print_rows
+
+connector_parser = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='connector',
+    description='Inspect the connectors known to the server.',
+    epilog="""
+Available commands:
+  ls     List connectors with their type, version and bundle.
+""",
+)
+connector_parser.add_argument('command', help='Connector command to execute.')
+connector_parser.add_argument('arg', help='Optional command arguments.', nargs='*')
+
+connector_ls_parser = add_listing_arguments(
+    ArgumentParser(
+        formatter_class=RawTextHelpFormatter,
+        prog='connector ls',
+        description='List the connectors known to the server.',
+    ),
+    'connectors',
+)
+
+# Each subcommand with its parser; None for those taking no arguments.
+connector_subparsers: dict[str, ArgumentParser | None] = {'ls': connector_ls_parser}
+
+
+class ConnectorClientPrompt(PromptBase):
+    subparsers_connector = connector_subparsers
+
+    def do_connector(self, inp: str) -> None:
+        """Inspect connectors (subcommand: ls)."""
+        self._dispatch_subcommand(inp, connector_parser, connector_subparsers, {'ls': self._connector_ls})
+
+    def _connector_ls(self, args: list[str]) -> None:
+        ls_ns = connector_ls_parser.parse_args(args)
+        connectors = self.client.get_connectors(limit=ls_ns.limit, name_filter=ls_ns.filter)
+        print_rows(connectors, title='Connectors', noun='connectors')
+
+    @staticmethod
+    def help_connector() -> None:
+        connector_parser.print_help()