tft-request-watch 0.36.0__py3-none-any.whl

tft_request_watch/__init__.py

@@ -0,0 +1,3 @@
+"""tft-request-watch — wait on Testing Farm requests with optional restart on retriable errors."""
+
+__version__ = "0.36.0"

tft_request_watch/__main__.py

@@ -0,0 +1,8 @@
+"""python -m tft_request_watch."""
+
+import sys
+
+from tft_request_watch.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

tft_request_watch/api_client.py

@@ -0,0 +1,42 @@
+"""HTTP helpers for Testing Farm request polling."""
+
+from __future__ import annotations
+
+from urllib.parse import urljoin
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util import Retry
+
+
+def build_session(http_retries: int, backoff_factor: float) -> requests.Session:
+    """Build a requests session for API polling with transient-error retries."""
+    session = requests.Session()
+    retry = Retry(
+        total=http_retries,
+        backoff_factor=backoff_factor,
+        status_forcelist=[502, 503, 504],
+        allowed_methods=frozenset({"GET"}),
+    )
+    adapter = HTTPAdapter(max_retries=retry)
+    session.mount("https://", adapter)
+    session.mount("http://", adapter)
+    return session
+
+
+def fetch_request(
+    api_base: str,
+    request_id: str,
+    session: requests.Session,
+    request_timeout: float,
+) -> dict:
+    """GET ``{api_base}/requests/{request_id}`` and return JSON object."""
+    base = api_base.rstrip("/") + "/"
+    url = urljoin(base, f"requests/{request_id}")
+    response = session.get(url, timeout=request_timeout)
+    response.raise_for_status()
+    data = response.json()
+    if not isinstance(data, dict):
+        msg = f"unexpected JSON from API (expected object): {type(data).__name__}"
+        raise TypeError(msg)
+    return data

tft_request_watch/cli.py

@@ -0,0 +1,206 @@
+"""CLI for tft-request-watch."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+from tft_request_watch import __version__
+from tft_request_watch.merge_cmd import run_merge
+from tft_request_watch.watch_core import WatchConfig
+from tft_request_watch.watch_core import run_watch
+from tft_request_watch.watch_core import watch_config_defaults
+
+_DEFAULT_TESTING_FARM_API = "https://api.dev.testing-farm.io/v0.1"
+_WD = watch_config_defaults()
+
+
+# ── watch subcommand ──────────────────────────────────────────────────────────
+
+
+def _add_watch_parser(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser(
+        "watch",
+        help="Watch a Testing Farm request and restart on retriable failures.",
+        description=(
+            "Wait for a Testing Farm request to finish.  Restarts the request when "
+            "the API reports retriable infrastructure errors, or when a required test "
+            "task is aborted."
+        ),
+    )
+    p.add_argument(
+        "--api-url",
+        default=_DEFAULT_TESTING_FARM_API,
+        help=f"Testing Farm API base URL (default: {_DEFAULT_TESTING_FARM_API})",
+    )
+    p.add_argument(
+        "--request-id",
+        default="",
+        help="Request UUID to watch. If empty, exit successfully without doing anything.",
+    )
+    p.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Query and watch the request but skip write operations (restart, cancel). "
+        "Logs what would have been done and exits successfully.",
+    )
+    p.add_argument(
+        "--hard-timeout-hours",
+        type=int,
+        default=_WD["hard_timeout_hours"],
+        metavar="H",
+        help=(
+            f"Cancel the request via testing-farm after H hours"
+            f" (default: {_WD['hard_timeout_hours']})."
+        ),
+    )
+    p.add_argument(
+        "--max-restarts",
+        type=int,
+        default=_WD["max_restarts"],
+        metavar="N",
+        help=f"Maximum retriable-error handling iterations (default: {_WD['max_restarts']}).",
+    )
+    p.add_argument(
+        "--restart-sleep-seconds",
+        type=int,
+        default=_WD["restart_sleep_seconds"],
+        metavar="S",
+        help=(
+            f"Seconds to sleep before testing-farm restart"
+            f" (default: {_WD['restart_sleep_seconds']})."
+        ),
+    )
+    p.add_argument(
+        "--http-timeout",
+        type=float,
+        default=_WD["http_timeout"],
+        metavar="SEC",
+        help=(
+            f"Per-call HTTP timeout in seconds when polling the Testing Farm API"
+            f" (default: {_WD['http_timeout']})."
+        ),
+    )
+    p.add_argument(
+        "--http-retries",
+        type=int,
+        default=_WD["http_retries"],
+        metavar="N",
+        help=f"urllib3 retry count for HTTP GET (default: {_WD['http_retries']}).",
+    )
+    p.add_argument(
+        "--http-backoff-factor",
+        type=float,
+        default=_WD["http_backoff_factor"],
+        metavar="F",
+        help=f"Backoff factor for HTTP retries (default: {_WD['http_backoff_factor']}).",
+    )
+    p.add_argument(
+        "--result-file",
+        metavar="PATH",
+        default=None,
+        help="Write a JSON list of per-run results to PATH (accumulated across restarts).",
+    )
+    p.add_argument(
+        "--required-task",
+        dest="required_tasks",
+        action="append",
+        default=[],
+        metavar="TASK",
+        help=(
+            "Restart the affected plan(s) if this test is aborted (result=error) in the"
+            " XUnit results. Use the test path without the discover alias prefix"
+            " (e.g. /distribution/install). Can be specified multiple times."
+        ),
+    )
+    p.set_defaults(func=_cmd_watch)
+
+
+def _cmd_watch(ns: argparse.Namespace) -> int:
+    cfg = WatchConfig(
+        api_url=ns.api_url,
+        request_id=ns.request_id,
+        dry_run=ns.dry_run,
+        hard_timeout_hours=ns.hard_timeout_hours,
+        max_restarts=ns.max_restarts,
+        restart_sleep_seconds=ns.restart_sleep_seconds,
+        http_timeout=ns.http_timeout,
+        http_retries=ns.http_retries,
+        http_backoff_factor=ns.http_backoff_factor,
+        result_file=ns.result_file,
+        required_tasks=ns.required_tasks,
+    )
+    return run_watch(cfg)
+
+
+# ── merge subcommand ──────────────────────────────────────────────────────────
+
+
+def _add_merge_parser(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser(
+        "merge",
+        help="Merge XUnit XML results from a tft-request-watch result JSON file.",
+        description=(
+            "Fetch the XUnit XML for every run recorded in RESULT_JSON and produce a single "
+            "merged XML at OUTPUT.  Testsuites from restarted plans (annotated via "
+            "restarted_plans in the JSON) are replaced with the retry results; all other "
+            "testsuites are kept from the original run."
+        ),
+    )
+    p.add_argument(
+        "result_json",
+        metavar="RESULT_JSON",
+        help="Path to the tft-request-watch result JSON file.",
+    )
+    p.add_argument("output", metavar="OUTPUT", help="Path to write the merged XUnit XML.")
+    p.add_argument(
+        "--timeout",
+        type=float,
+        default=120.0,
+        metavar="SECONDS",
+        help="HTTP request timeout for fetching XUnit URLs (default: 120).",
+    )
+    p.set_defaults(func=_cmd_merge)
+
+
+def _cmd_merge(ns: argparse.Namespace) -> int:
+    return run_merge(ns.result_json, ns.output, ns.timeout)
+
+
+# ── entry point ───────────────────────────────────────────────────────────────
+
+
+def main(args: list[str] | None = None) -> int:
+    """Entry point for console script."""
+    parser = argparse.ArgumentParser(
+        prog="tft-request-watch",
+        description="Testing Farm request watcher and XUnit result merger.",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Enable DEBUG logging on stderr.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    _add_watch_parser(subparsers)
+    _add_merge_parser(subparsers)
+
+    ns = parser.parse_args(args=args)
+    logging.basicConfig(
+        level=logging.DEBUG if ns.debug else logging.INFO,
+        format="%(levelname)s: %(message)s",
+        stream=sys.stderr,
+        force=True,
+    )
+    logging.getLogger(__name__).info("tft-request-watch v%s", __version__)
+    return ns.func(ns)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tft_request_watch/merge_cmd.py

@@ -0,0 +1,166 @@
+"""Merge XUnit XML results from a tft-request-watch JSON result file."""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING
+from xml.etree import ElementTree as ET
+
+from tft_request_watch.api_client import build_session
+from tft_request_watch.watch_core import fetch_xunit_xml
+from tft_request_watch.watch_core import get_testsuite_arch
+
+if TYPE_CHECKING:
+    import requests
+
+logger = logging.getLogger(__name__)
+
+
+def merge_xunit(
+    base_xml: str,
+    retry_xml: str,
+    restarted_plans: dict[str, list[str]],
+) -> str:
+    """Merge *retry_xml* into *base_xml*, replacing ``(arch, plan_name)`` testsuites.
+
+    Testsuites listed in *restarted_plans* are removed from *base_xml* and replaced
+    by the matching testsuites from *retry_xml*.  All other testsuites are kept
+    unchanged.  The ``overall-result`` attribute on the root element is recomputed
+    from the merged set of testsuite results.
+
+    If either XML cannot be parsed the original *base_xml* is returned unchanged.
+    """
+    try:
+        base_root = ET.fromstring(base_xml)  # noqa: S314
+        retry_root = ET.fromstring(retry_xml)  # noqa: S314
+    except ET.ParseError:
+        logger.exception("Could not parse XUnit XML for merge")
+        return base_xml
+
+    to_replace: set[tuple[str, str]] = {
+        (arch, plan) for arch, plans in restarted_plans.items() for plan in plans
+    }
+
+    # Build lookup of retry testsuites for the pairs we need to replace
+    retry_lookup: dict[tuple[str, str], ET.Element] = {}
+    for ts in retry_root.findall("testsuite"):
+        key = (get_testsuite_arch(ts), ts.get("name", ""))
+        if key in to_replace:
+            retry_lookup[key] = ts
+
+    # Remove matched testsuites from base, then append replacements from retry
+    for ts in list(base_root.findall("testsuite")):
+        if (get_testsuite_arch(ts), ts.get("name", "")) in to_replace:
+            base_root.remove(ts)
+    for ts in retry_lookup.values():
+        base_root.append(ts)
+
+    # Recompute overall-result
+    suite_results = {ts.get("result", "") for ts in base_root.findall("testsuite")}
+    if "error" in suite_results:
+        overall = "error"
+    elif "failed" in suite_results:
+        overall = "failed"
+    elif suite_results <= {"passed"}:
+        overall = "passed"
+    else:
+        overall = "unknown"
+    base_root.set("overall-result", overall)
+
+    return '<?xml version="1.0" encoding="UTF-8"?>\n' + ET.tostring(
+        base_root,
+        encoding="unicode",
+    )
+
+
+def _fetch_all_xml(
+    entries: list[dict],
+    session: requests.Session,
+    timeout: float,
+) -> list[str | None]:
+    """Fetch XUnit XML for every entry that has a ``xunit_url``.  Returns one item per entry."""
+    xmls: list[str | None] = []
+    for i, entry in enumerate(entries):
+        url = entry.get("xunit_url") or (entry.get("result") or {}).get("xunit_url", "")
+        if not url:
+            logger.warning("Entry %d (id=%s) has no xunit_url; skipping.", i, entry.get("id"))
+            xmls.append(None)
+        else:
+            xml = fetch_xunit_xml(url, session, timeout)
+            if xml is None:
+                logger.error("Failed to fetch XUnit for entry %d (id=%s).", i, entry.get("id"))
+            xmls.append(xml)
+    return xmls
+
+
+def merge_results(entries: list[dict], xmls: list[str | None]) -> str | None:
+    """Merge XUnit XMLs according to the ``restarted_plans`` annotations in *entries*.
+
+    Returns the merged XML string, or ``None`` if no usable XML was found.
+    """
+    base: str | None = None
+    base_idx: int = -1
+    for i, xml in enumerate(xmls):
+        if xml is not None:
+            base = xml
+            base_idx = i
+            break
+    if base is None:
+        logger.error("No XUnit XML could be fetched; cannot produce merged output.")
+        return None
+
+    for i in range(base_idx + 1, len(entries)):
+        retry_xml = xmls[i]
+        if retry_xml is None:
+            logger.warning(
+                "Skipping entry %d (id=%s): no XUnit available.",
+                i,
+                entries[i].get("id"),
+            )
+            continue
+        restarted_plans: dict[str, list[str]] = entries[i].get("restarted_plans") or {}
+        if not restarted_plans:
+            # No annotation → full restart, replace everything
+            logger.info(
+                "Entry %d (id=%s) has no restarted_plans; replacing entire base with this run.",
+                i,
+                entries[i].get("id"),
+            )
+            base = retry_xml
+        else:
+            base = merge_xunit(base, retry_xml, restarted_plans)
+
+    return base
+
+
+def run_merge(result_json: str, output: str, timeout: float = 120.0) -> int:
+    """Read *result_json*, fetch XUnit URLs, merge, and write to *output*. Returns exit code."""
+    try:
+        entries = json.loads(Path(result_json).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        logger.exception("Could not read result JSON %s", result_json)
+        return 1
+
+    if not isinstance(entries, list):
+        logger.error("Result JSON must be a list of entries; got %s.", type(entries).__name__)
+        return 1
+    if not entries:
+        logger.error("Result JSON is empty; nothing to merge.")
+        return 1
+
+    session = build_session(http_retries=3, backoff_factor=0.5)
+    xmls = _fetch_all_xml(entries, session, timeout)
+    merged = merge_results(entries, xmls)
+    if merged is None:
+        return 1
+
+    try:
+        Path(output).write_text(merged, encoding="utf-8")
+        logger.info("Wrote merged XUnit: %s", output)
+    except OSError:
+        logger.exception("Could not write %s", output)
+        return 1
+
+    return 0