atex 0.5__py3-none-any.whl → 0.7__py3-none-any.whl

atex/minitmt/scripts.py

@@ -1,51 +1,149 @@
-#from .. import util
+from pathlib import Path
 
-#run_test = util.dedent(fr'''
-#    # create a temp dir for everything, send it to the controller
-#    tmpdir=$(mktemp -d /var/tmp/atex-XXXXXXXXX)
-#    echo "tmpdir=$tmpdir"
-#
-#    # remove transient files if interrupted
-#    trap "rm -rf \"$tmpdir\"" INT
-#
-#    # wait for result reporting unix socket to be created by sshd
-#    socket=$tmpdir/results.sock
-#    while [[ ! -e $socket ]]; do sleep 0.1; done
-#    echo "socket=$socket"
-#
-#    # tell the controller to start logging test output
-#    echo ---
-#
-#    # install test dependencies
-#    rpms=( {' '.join(requires)} )
-#    to_install=()
-#    for rpm in "${{rpms[@]}}"; do
-#        rpm -q --quiet "$rpm" || to_install+=("$rpm")
-#    done
-#    dnf -y --setopt=install_weak_deps=False install "${{to_install[@]}}"
-#
-#    # run the test
-#    ...
-#    rc=$?
+from .. import util
+
+from . import fmf
+
+# NOTE that we split test execution into 3 scripts:
+#      - "setup script" (package installs, etc.)
+#      - "wrapper script" (runs test script)
+#      - "test script" (exact contents of the 'test:' FMF metadata key)
 #
-#    # test finished, clean up
-#    rm -rf "$tmpdir"
+#      this is to allow interactive test execution - the setup script
+#      can run in 'bash' via stdin pipe into 'ssh', creating the wrapper
+#      script somewhere on the disk, making it executable,
 #
-#    exit $rc
-#''')
+#      then the "wrapper" script can run via a separate 'ssh' execution,
+#      passed by an argument to 'ssh', leaving stdin/out/err untouched,
+#      allowing the user to interact with it (if run interactively)
 
-# TODO: have another version of ^^^^ for re-execution of test after a reboot
-#       or disconnect that sets tmpdir= from us (reusing on-disk test CWD)
-#       rather than creating a new one
-#         - the second script needs to rm -f the unix socket before echoing
-#           something back to let us re-create it via a new ssh channel open
-#           because StreamLocalBindUnlink doesn't seem to work
 
+def test_wrapper(*, test, tests_dir, test_exec, debug=False):
+    """
+    Generate a bash script that runs a user-specified test, preparing
+    a test control channel for it, and reporting its exit code.
+    The script must be as "transparent" as possible, since any output
+    is considered as test output and any unintended environment changes
+    will impact the test itself.
 
-# TODO: call ssh with -oStreamLocalBindUnlink=yes to re-initialize
-#       the listening socket after guest reboot
-#
-#       -R /var/tmp/atex-BlaBla/results.sock:/var/tmp/controller.sock
-#
-#       (make sure to start listening on /var/tmp/controller.sock before
-#        calling ssh to run the test)
+    'test' is a atex.minitmt.fmf.FMFTest instance.
+
+    'test_dir' is a remote directory (repository) of all the tests,
+    a.k.a. FMF metadata root.
+
+    'test_exec' is a remote path to the actual test to run.
+
+    'debug' specifies whether to include wrapper output inside test output.
+    """
+    out = "#!/bin/bash\n"
+
+    # stdout-over-ssh is used as Test Control (see TEST_CONTROL.md),
+    # so duplicate stderr to stdout, and then open a new fd pointing to the
+    # original stdout
+    out += "exec {orig_stdout}>&1 1>&2\n"
+
+    # TODO: if interactive, keep original stdin, else exec 0</dev/null ,
+    #       doing it here avoids unnecessary traffic (reading stdin) via ssh,
+    #       even if it is fed from subprocess.DEVNULL on the runner
+
+    if debug:
+        out += "set -x\n"
+
+    # use a subshell to limit the scope of the CWD change
+    out += "(\n"
+
+    # if TMT_PLAN_ENVIRONMENT_FILE exists, export everything from it
+    # (limited by the subshell, so it doesn't leak)
+    out += util.dedent("""
+        if [[ -f $TMT_PLAN_ENVIRONMENT_FILE ]]; then
+            set -o allexport
+            . "$TMT_PLAN_ENVIRONMENT_FILE"
+            set +o allexport
+        fi
+    """) + "\n"
+
+    # TODO: custom PATH with tmt-* style commands?
+
+    # join the directory with all tests and nested path of our test inside it
+    test_cwd = Path(tests_dir) / test.dir
+    out += f"cd '{test_cwd}' || exit 1\n"
+
+    # run the test script
+    # - the '-e -o pipefail' is to mimic what full fat tmt uses
+    out += (
+        "ATEX_TEST_CONTROL=$orig_stdout"
+        f" exec -a 'bash: atex running {test.name}'"
+        f" bash -e -o pipefail '{test_exec}'\n"
+    )
+
+    # subshell end
+    out += ")\n"
+
+    # write test exitcode to test control stream
+    out += "echo exitcode $? >&$orig_stdout\n"
+
+    # always exit the wrapper with 0 if test execution was normal
+    out += "exit 0\n"
+
+    return out
+
+
+def test_setup(*, test, wrapper_exec, test_exec, debug=False, **kwargs):
+    """
+    Generate a bash script that should prepare the remote end for test
+    execution.
+
+    The bash script itself will (among other things) generate two more bash
+    scripts: a test script (contents of 'test' from FMF) and a wrapper script
+    to run the test script.
+
+    'wrapper_exec' is the remote path where the wrapper script should be put.
+
+    'test_exec' is the remote path where the test script should be put.
+
+    'test' is a atex.minitmt.fmf.FMFTest instance.
+
+    'debug' specifies whether to make the setup script extra verbose.
+
+    Any 'kwargs' are passed to test_wrapper().
+    """
+    out = "#!/bin/bash\n"
+
+    # have deterministic stdin, avoid leaking parent console
+    # also avoid any accidental stdout output, we use it for wrapper path
+    if debug:
+        out += "exec {orig_stdout}>&1 1>&2\n"
+        out += "set -xe\n"
+    else:
+        out += "exec {orig_stdout}>&1 2>/dev/null 1>&2\n"
+        out += "set -e\n"
+
+    # install test dependencies
+    # - only strings (package names) in require/recommend are supported
+    if require := [x for x in fmf.listlike(test.data, "require") if isinstance(x, str)]:
+        out += "dnf -y --setopt=install_weak_deps=False install "
+        out += " ".join(f"'{pkg}'" for pkg in require) + "\n"
+    if recommend := [x for x in fmf.listlike(test.data, "recommend") if isinstance(x, str)]:
+        out += "dnf -y --setopt=install_weak_deps=False install --skip-broken "
+        out += " ".join(f"'{pkg}'" for pkg in recommend) + "\n"
+
+    # make the wrapper script
+    out += f"cat > '{wrapper_exec}' <<'ATEX_SETUP_EOF'\n"
+    out += test_wrapper(
+        test=test,
+        test_exec=test_exec,
+        debug=debug,
+        **kwargs,
+    )
+    out += "ATEX_SETUP_EOF\n"
+    # make the test script
+    out += f"cat > '{test_exec}' <<'ATEX_SETUP_EOF'\n"
+    out += test.data["test"]
+    out += "\n"  # for safety, in case 'test' doesn't have a newline
+    out += "ATEX_SETUP_EOF\n"
+    # make both executable
+    out += f"chmod 0755 '{wrapper_exec}' '{test_exec}'\n"
+
+    out += "exit 0\n"
+
+    return out

atex/minitmt/testcontrol.py

@@ -0,0 +1,354 @@
+import os
+import collections
+import json
+
+from .. import util
+
+
+class BufferFullError(Exception):
+    pass
+
+
+class NonblockLineReader:
+    """
+    Kind of like io.BufferedReader but capable of reading from non-blocking
+    sources (both O_NONBLOCK sockets and os.set_blocking(False) descriptors),
+    re-assembling full lines from (potentially) multiple read() calls.
+
+    It also takes a file descriptor (not a file-like object) and takes extra
+    care to read one-byte-at-a-time to not read (and buffer) more data from the
+    source descriptor, allowing it to be used for in-kernel move, such as via
+    os.sendfile() or os.splice().
+    """
+
+    def __init__(self, src, maxlen=4096):
+        """
+        'src' is an opened file descriptor (integer).
+
+        'maxlen' is a maximum potential line length, incl. the newline
+        character - if reached, a BufferFullError is raised.
+        """
+        self.src = src
+        self.eof = False
+        self.buffer = bytearray(maxlen)
+        self.bytes_read = 0
+
+    def readline(self):
+        r"""
+        Read a line and return it, without the '\n' terminating character,
+        clearing the internal buffer upon return.
+
+        Returns None if nothing could be read (BlockingIOError) or if EOF
+        was reached.
+        """
+        while self.bytes_read < len(self.buffer):
+            try:
+                data = os.read(self.src, 1)
+            except BlockingIOError:
+                return None
+
+            # stream EOF
+            if len(data) == 0:
+                self.eof = True
+                return None
+
+            char = data[0]
+
+            if char == 0x0a:  # \n
+                line = self.buffer[0:self.bytes_read]
+                self.bytes_read = 0
+                return line
+            else:
+                self.buffer[self.bytes_read] = char
+                self.bytes_read += 1
+
+        raise BufferFullError(f"line buffer reached {len(self.buffer)} bytes")
+
+    def clear(self):
+        """
+        Clear the internal buffer, clearing any partially-read line data.
+        """
+        self.bytes_read = 0
+
+
+class BadControlError(Exception):
+    """
+    Raised by TestControl when abnormalities are detected in the control stream,
+    such as invalid syntax, unknown control word, or bad or unexpected data for
+    any given control word.
+    """
+    pass
+
+
+class BadReportJSONError(BadControlError):
+    """
+    Raised on a syntactical or semantical error caused by the test not following
+    the TEST_CONROL.md specification when passing JSON data to the 'result'
+    control word.
+    """
+    pass
+
+
+class TestControl:
+    """
+    An implementation of the protocol described by TEST_CONTROL.md,
+    processing test-issued commands, results and uploaded files.
+    """
+
+    def __init__(self, *, control_fd, aggregator, duration, testout_fd):
+        """
+        'control_fd' is a non-blocking file descriptor to be read.
+
+        'aggregator' is an instance of a result aggregator (ie. CSVAggregator)
+        all the results and uploaded files will be written to.
+
+        'duration' is a class Duration instance.
+
+        'testout_fd' is an optional file descriptor handle which the test uses
+        to write its output to - useful here for the 'result' control word and
+        its protocol, which allows "hardlinking" the fd to a real file name.
+        """
+        self.control_fd = control_fd
+        self.stream = NonblockLineReader(control_fd)
+        self.aggregator = aggregator
+        self.duration = duration
+        self.testout_fd = testout_fd
+        self.eof = False
+        self.in_progress = None
+        self.partial_results = collections.defaultdict(dict)
+        self.result_seen = False
+        self.exit_code = None
+        self.reconnect = None
+
+    def process(self):
+        """
+        Read from the control file descriptor and potentially perform any
+        appropriate action based on commands read from the test.
+
+        Returns True if there is more data expected, False otherwise
+        (when the control file descriptor reached EOF).
+        """
+        # if a parser operation is in progress, continue calling it,
+        # avoid reading a control line
+        if self.in_progress:
+            try:
+                next(self.in_progress)
+                return
+            except StopIteration:
+                # parser is done, continue on to a control line
+                self.in_progress = None
+
+        try:
+            line = self.stream.readline()
+        except BufferFullError as e:
+            raise BadControlError(str(e)) from None
+
+        util.debug(f"got control line: {line}")
+
+        if self.stream.eof:
+            self.eof = True
+            return
+        # partial read or BlockingIOError, try next time
+        if line is None:
+            return
+        elif len(line) == 0:
+            raise BadControlError(r"empty control line (just '\n')")
+
+        line = line.decode()
+        word, _, arg = line.partition(" ")
+
+        if word == "result":
+            parser = self._parser_result(arg)
+        elif word == "duration":
+            parser = self._parser_duration(arg)
+        elif word == "exitcode":
+            parser = self._parser_exitcode(arg)
+        elif word == "reconnect":
+            parser = self._parser_reconnect(arg)
+        else:
+            raise BadControlError(f"unknown control word: {word}")
+
+        try:
+            next(parser)
+            # parser not done parsing, run it next time we're called
+            self.in_progress = parser
+        except StopIteration:
+            pass
+
+    @classmethod
+    def _merge(cls, dst, src):
+        """
+        Merge a 'src' dict into 'dst', using the rules described by
+        TEST_CONTROL.md for 'Partial results'.
+        """
+        for key, value in src.items():
+            # delete existing if new value is None (JSON null)
+            if value is None and key in dst:
+                del dst[key]
+                continue
+            # add new key
+            elif key not in dst:
+                dst[key] = value
+                continue
+
+            orig_value = dst[key]
+            # different type - replace
+            if type(value) is not type(orig_value):
+                dst[key] = value
+                continue
+
+            # nested dict, merge it recursively
+            if isinstance(value, dict):
+                cls._merge(orig_value, value)
+            # extensible list-like iterable, extend it
+            elif isinstance(value, (tuple, list)):
+                orig_value += value
+            # overridable types, doesn't make sense to extend them
+            elif isinstance(value, (str, int, float, bool, bytes, bytearray)):
+                dst[key] = value
+            # set-like, needs unioning
+            elif isinstance(value, set):
+                orig_value.update(value)
+            else:
+                raise BadReportJSONError(f"cannot merge type {type(value)}")
+
+    def _parser_result(self, arg):
+        try:
+            json_length = int(arg)
+        except ValueError as e:
+            raise BadControlError(f"reading json length: {str(e)}") from None
+
+        # read the full JSON
+        json_data = bytearray()
+        while json_length > 0:
+            try:
+                chunk = os.read(self.control_fd, json_length)
+            except BlockingIOError:
+                yield
+                continue
+            if chunk == b"":
+                raise BadControlError("EOF when reading data")
+            json_data += chunk
+            json_length -= len(chunk)
+            yield
+
+        # convert to native python dict
+        try:
+            result = json.loads(json_data)
+        except json.decoder.JSONDecodeError as e:
+            raise BadReportJSONError(f"JSON decode: {str(e)} caused by: {json_data}") from None
+
+        name = result.get("name")
+        if not name:
+            raise BadReportJSONError("'name' not specified, but mandatory")
+
+        # upload files
+        for entry in result.get("files", ()):
+            file_name = entry.get("name")
+            file_length = entry.get("length")
+            if not file_name or file_length is None:
+                raise BadReportJSONError(f"file entry missing 'name' or 'length': {entry}")
+            try:
+                file_length = int(file_length)
+            except ValueError as e:
+                raise BadReportJSONError(f"file entry {file_name} length: {str(e)}") from None
+
+            with self.aggregator.open_tmpfile() as fd:
+                while file_length > 0:
+                    try:
+                        # try a more universal sendfile first, fall back to splice
+                        try:
+                            written = os.sendfile(fd, self.control_fd, None, file_length)
+                        except OSError as e:
+                            if e.errno == 22:  # EINVAL
+                                written = os.splice(self.control_fd, fd, file_length)
+                            else:
+                                raise
+                    except BlockingIOError:
+                        yield
+                        continue
+                    if written == 0:
+                        raise BadControlError("EOF when reading data")
+                    file_length -= written
+                    yield
+                try:
+                    self.aggregator.link_tmpfile_to(name, file_name, fd)
+                except FileExistsError:
+                    raise BadReportJSONError(
+                        f"file '{file_name}' for '{name}' already exists",
+                    ) from None
+
+        # either store partial result + return,
+        # or load previous partial result and merge into it
+        partial = result.get("partial", False)
+        if partial:
+            # do not store the 'partial' key in the result
+            del result["partial"]
+            self._merge(self.partial_results[name], result)
+            # partial = do nothing
+            return
+
+        # if previously-stored partial result exist, merge the current one
+        # into it, but then use the merged result
+        # - avoid .get() or __getitem__() on defaultdict, it would create
+        #   a new key with an empty value if there was no partial result
+        if name in self.partial_results:
+            partial_result = self.partial_results[name]
+            del self.partial_results[name]
+            self._nested_merge(partial_result, result)
+            result = partial_result
+
+        if "testout" in result:
+            testout = result.get("testout")
+            if not testout:
+                raise BadReportJSONError("'testout' specified, but empty")
+            try:
+                self.aggregator.link_tmpfile_to(name, testout, self.testout_fd)
+            except FileExistsError:
+                raise BadReportJSONError(f"file '{testout}' for '{name}' already exists") from None
+
+        self.aggregator.report(result)
+
+        self.result_seen = True
+
+    def _parser_duration(self, arg):
+        if not arg:
+            raise BadControlError("duration argument empty")
+        # increment/decrement
+        if arg[0] == "+":
+            self.duration.increment(arg[1:])
+        elif arg[0] == "-":
+            self.duration.decrement(arg[1:])
+        # save/restore
+        elif arg == "save":
+            self.duration.save()
+        elif arg == "restore":
+            self.duration.restore()
+        else:
+            self.duration.set(arg)
+        # pretend to be a generator
+        if False:
+            yield
+
+    def _parser_exitcode(self, arg):
+        if not arg:
+            raise BadControlError("exitcode argument empty")
+        try:
+            code = int(arg)
+        except ValueError:
+            raise BadControlError(f"'{arg}' is not an integer exit code") from None
+        self.exit_code = code
+        # pretend to be a generator
+        if False:
+            yield
+
+    def _parser_reconnect(self, arg):
+        if not arg:
+            self.reconnect = "once"
+        elif arg == "always":
+            self.reconnect = "always"
+        else:
+            raise BadControlError(f"unknown reconnect arg: {arg}")
+        # pretend to be a generator
+        if False:
+            yield

atex/{orchestrator.py → orchestrator/__init__.py}

@@ -1,4 +1,6 @@
-from . import util
+import importlib as _importlib
+import pkgutil as _pkgutil
+#import threading as _threading
 
 
 class Orchestrator:
@@ -36,3 +38,22 @@ class Orchestrator:
         # gets return from run
         # writes it out to somewhere else
         ...
+
+
+_submodules = [
+    info.name for info in _pkgutil.iter_modules(__spec__.submodule_search_locations)
+]
+
+__all__ = [*_submodules, Orchestrator.__name__]  # noqa: PLE0604
+
+
+def __dir__():
+    return __all__
+
+
+# lazily import submodules
+def __getattr__(attr):
+    if attr in _submodules:
+        return _importlib.import_module(f".{attr}", __name__)
+    else:
+        raise AttributeError(f"module '{__name__}' has no attribute '{attr}'")