[#84714] Add an app sending requests to a protoplaster server

Co-authored-by: Maciej Sobkowski <msobkowski@antmicro.com>
Signed-off-by: Maciej Sobkowski <msobkowski@antmicro.com>

Author: mandrys

.ci.yml

@@ -11,7 +11,7 @@ check-code-quality:
     - apt -y update
     - apt -y install python3 pipx git
     - pipx install yapf==0.40.2
-    - yapf -ipr protoplaster/
+    - yapf -ipr protoplaster/ manager/
     - test $(git status --porcelain | wc -l) -eq 0 || { git diff; false; }
 
 installation-test:

README.md

@@ -296,3 +296,30 @@ ip:
 ### Running as root
 By default, `sudo` doesn't preserve `PATH`. 
 To run `protoplaster-system-report` installed by a non-root user as root, invoke `protoplaster-system-report --sudo`
+
+## Protoplaster manager
+Protoplaster provides `protoplaster-mgmt`, a tool to remotely control Protoplaster via the API.
+For more detailed information, see the help messages associated with each subcommand.
+
+```
+usage: protoplaster-mgmt [-h] [--url URL] [--config CONFIG] [--config-dir CONFIG_DIR] [--report-dir REPORT_DIR] [--artifact-dir ARTIFACT_DIR] {configs,runs} ...
+
+Tool for managing Protoplaster via remote API
+
+options:
+  -h, --help            show this help message and exit
+  --url URL             URL to a device running Protoplaster server (default: http://127.0.0.1:5000/)
+  --config CONFIG       Config file with values for url, config-dir, report-dir, artifact-dir
+  --config-dir CONFIG_DIR
+                        Directory to save fetched config (default: ./)
+  --report-dir REPORT_DIR
+                        Directory to save a test report (default: ./)
+  --artifact-dir ARTIFACT_DIR
+                        Directory to save a test artifact (default: ./)
+
+available commands:
+  {configs,runs}
+    configs             Configs management
+    runs                Test runs management
+
+```

manager/__init__.py

@@ -0,0 +1,98 @@
+import argparse
+import json
+import os.path
+import requests
+from pathlib import Path
+
+StrPath = str | Path
+
+
+def check_status(response: requests.models.Response):
+    if response.status_code != 200:
+        print(f"Error {response.status_code}: {response.json()['error']}")
+        return True
+    return False
+
+
+def configs_list(args):
+    r = requests.get(f"{args.url}/api/v1/configs")
+    if check_status(r):
+        return
+    print(f"Available configs:")
+    print(json.dumps(r.json(), indent=4))
+
+
+def config_upload(args):
+    try:
+        files = {'file': open(args.path, 'rb')}
+    except Exception as e:
+        print(f"Failed to open the config to upload: {str(e)}")
+        return
+    r = requests.post(f"{args.url}/api/v1/configs", files=files)
+    if check_status(r):
+        return
+    print(f"Uploaded `{args.path}`")
+
+
+def config_info(args):
+    r = requests.get(f"{args.url}/api/v1/configs/{args.name}")
+    if check_status(r):
+        return
+    print(f"Config info fetched from the server:")
+    print(json.dumps(r.json(), indent=4))
+
+
+def config_fetch(args):
+    r = requests.get(f"{args.url}/api/v1/configs/{args.name}/file")
+    if check_status(r):
+        return
+    save_path = os.path.join(args.config_dir, args.name)
+    try:
+        with open(save_path, "wb") as file:
+            file.write(r.content)
+        print(f"Config written to {save_path}")
+    except Exception as e:
+        print(f"Failed to save the config: {str(e)}")
+
+
+def config_delete(args):
+    r = requests.delete(f"{args.url}/api/v1/configs/{args.name}")
+    if check_status(r):
+        return
+    print(f"Config '{args.name}' deleted")
+
+
+def add_configs_parser(parser: argparse._SubParsersAction):
+    configs = parser.add_parser("configs", help="Configs management")
+    sub = configs.add_subparsers(required=True, title="Configs commands")
+
+    list = sub.add_parser("list", help="List available test configs")
+    list.set_defaults(func=configs_list)
+
+    upload = sub.add_parser("upload", help="Upload a test config")
+    upload.set_defaults(func=config_upload)
+    upload.add_argument("--path",
+                        type=str,
+                        required=True,
+                        help="Path to a test config file")
+
+    info = sub.add_parser("info", help="Information about a test config")
+    info.set_defaults(func=config_info)
+    info.add_argument("--name",
+                      type=str,
+                      required=True,
+                      help="Test config name")
+
+    fetch = sub.add_parser("fetch", help="Fetch a test config file")
+    fetch.set_defaults(func=config_fetch)
+    fetch.add_argument("--name",
+                       type=str,
+                       required=True,
+                       help="Test config name")
+
+    delete = sub.add_parser("delete", help="Delete a test config file")
+    delete.set_defaults(func=config_delete)
+    delete.add_argument("--name",
+                        type=str,
+                        required=True,
+                        help="Test config name")

manager/configs.py

@@ -0,0 +1,4 @@
+url: http://127.0.0.1:5000
+config-dir: configs
+report-dir: reports
+artifact-dir: artifacts

manager/defaults.yml

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+
+import argparse
+import os
+import requests
+import sys
+import traceback
+import yaml
+
+import manager.configs
+import manager.runs
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Tool for managing Protoplaster via remote API", )
+
+    parser.add_argument(
+        "--url",
+        default="http://127.0.0.1:5000/",
+        help=
+        "URL to a device running Protoplaster server (default: http://127.0.0.1:5000/)",
+    )
+    parser.add_argument(
+        "--config",
+        help=
+        "Config file with values for url, config-dir, report-dir, artifact-dir",
+    )
+    parser.add_argument(
+        "--config-dir",
+        default="./",
+        metavar="CONFIG_DIR",
+        help="Directory to save fetched config (default: ./)",
+    )
+    parser.add_argument(
+        "--report-dir",
+        default="./",
+        help="Directory to save a test report (default: ./)",
+    )
+    parser.add_argument(
+        "--artifact-dir",
+        default="./",
+        help="Directory to save a test artifact (default: ./)",
+    )
+
+    subparsers = parser.add_subparsers(required=True,
+                                       title="available commands")
+
+    # Add all subparsers for the different subcommands
+    manager.configs.add_configs_parser(subparsers)
+    manager.runs.add_runs_parser(subparsers)
+    # Wrap argv so when no arguments are passed, we inject a help screen
+    wrapped_args = None if sys.argv[1:] else ["--help"]
+
+    args = parser.parse_args(args=wrapped_args)
+
+    config = {}
+    if args.config is not None:
+        try:
+            with open(args.config) as file:
+                config = yaml.safe_load(file)
+        except Exception as e:
+            print(f"Failed to read config: {e}")
+            exit(1)
+
+    url = config.get("url", args.url)
+    config_dir = config.get("config-dir", args.config_dir)
+    report_dir = config.get("report-dir", args.report_dir)
+    artifact_dir = config.get("artifact-dir", args.artifact_dir)
+
+    try:
+        ret = args.func(args)
+        if ret is not None:
+            print("protoplaster-mgmt:", ret)
+            exit(1)
+    except requests.ConnectionError as e:
+        print("protoplaster-mgmt: Connection to the server failed:", e)
+        exit(1)
+    except requests.Timeout as e:
+        print("protoplaster-mgmt: Server request timed out:", e)
+        exit(1)
+    except RuntimeError as e:
+        print("protoplaster-mgmt:", e)
+        exit(1)
+    except Exception:
+        traceback.print_exc()
+        print("protoplaster-mgmt: Unhandled exception!")
+        exit(1)
+
+
+if __name__ == "__main__":
+    main()

manager/protoplaster_mgmt.py

@@ -0,0 +1,118 @@
+import argparse
+import json
+import os.path
+import requests
+from pathlib import Path
+
+StrPath = str | Path
+
+
+def check_status(response: requests.models.Response):
+    if response.status_code != 200:
+        print(f"Error {response.status_code}: {response.json()['error']}")
+        return True
+    return False
+
+
+def test_runs_list(args):
+    r = requests.get(f"{args.url}/api/v1/test-runs")
+    if check_status(r):
+        return
+    print("Tests runs on the server:")
+    print(json.dumps(r.json(), indent=4))
+
+
+def test_run_trigger(args):
+    params = {
+        "config_name": args.test_config,
+        "test_suite_name": args.test_suite or ""
+    }
+    r = requests.post(f"{args.url}/api/v1/test-runs", json=params)
+    if check_status(r):
+        return
+    print("Triggered a test run:")
+    print(json.dumps(r.json(), indent=4))
+
+
+def test_run_info(args):
+    r = requests.get(f"{args.url}/api/v1/test-runs/{args.id}")
+    if check_status(r):
+        return
+    print(f"Test info fetched from the server:")
+    print(json.dumps(r.json(), indent=4))
+
+
+def test_run_abort(args):
+    r = requests.delete(f"{args.url}/api/v1/test-runs/{args.id}")
+    if check_status(r):
+        return
+    print(f"Test deleted from the server:")
+    print(json.dumps(r.json(), indent=4))
+
+
+def test_run_report(args):
+    r = requests.get(f"{args.url}/api/v1/test-runs/{args.id}/report")
+    if check_status(r):
+        return
+    save_path = os.path.join(args.report_dir, f"{args.id}.csv")
+    try:
+        with open(save_path, "wb") as file:
+            file.write(r.content)
+        print(f"Report written to {save_path}")
+    except Exception as e:
+        print(f"Failed to save the report: {str(e)}")
+
+
+def test_run_artifact(args):
+    r = requests.get(
+        f"{args.url}/api/v1/test-runs/{args.id}/artifacts/{args.name}")
+    if check_status(r):
+        return
+    save_path = os.path.join(args.artifact_dir, args.name)
+    try:
+        with open(save_path, "wb") as file:
+            file.write(r.content)
+        print(f"Artifact written to {save_path}")
+    except Exception as e:
+        print(f"Failed to save the artifact: {str(e)}")
+
+
+def add_runs_parser(parser: argparse._SubParsersAction):
+
+    runs = parser.add_parser("runs", help="Test runs management")
+    sub = runs.add_subparsers(required=True, title="Test runs commands")
+
+    list = sub.add_parser("list", help="List test runs")
+    list.set_defaults(func=test_runs_list)
+
+    run = sub.add_parser("run", help="Trigger a test run")
+    run.set_defaults(func=test_run_trigger)
+    run.add_argument(
+        "--test-config",
+        required=True,
+        help="Test config name for this test run",
+    )
+    run.add_argument(
+        "--test-suite",
+        help="Test suite name for this test run",
+    )
+
+    info = sub.add_parser("info", help="Information about a test run")
+    info.set_defaults(func=test_run_info)
+    info.add_argument("--id", type=str, required=True, help="Test run ID")
+
+    abort = sub.add_parser("abort", help="Abort a pending test run")
+    abort.set_defaults(func=test_run_abort)
+    abort.add_argument("--id", type=str, required=True, help="Test run ID")
+
+    report = sub.add_parser("report", help="Fetch test run report")
+    report.set_defaults(func=test_run_report)
+    report.add_argument("--id", type=str, required=True, help="Test run ID")
+
+    artifact = sub.add_parser("artifact", help="Fetch test run artifact")
+    artifact.set_defaults(func=test_run_artifact)
+    artifact.add_argument("--id", type=str, required=True, help="Test run ID")
+    artifact.add_argument("--name",
+                          type=str,
+                          required=True,
+                          help="Artifact name")

manager/runs.py

@@ -6,10 +6,14 @@ authors=[{name = "Antmicro Ltd"}]
 license={text = "Apache Software License (http://www.apache.org/licenses/LICENSE-2.0)"}
 dynamic = ["dependencies"]
 
+[tool.setuptools.packages.find]
+include = ["protoplaster*", "manager*"]
+
 [project.scripts]
 protoplaster = 'protoplaster.protoplaster:main'
 protoplaster-test-report = 'protoplaster.report_generators.test_report.protoplaster_test_report:main'
 protoplaster-system-report = 'protoplaster.report_generators.system_report.protoplaster_system_report:main'
+protoplaster-mgmt = 'manager.protoplaster_mgmt:main'
 
 [tool.setuptools.dynamic]
 dependencies = {file = ["requirements.txt"]}