gini-toolkit 6.0.1.dev0__py3-none-any.whl

gini/services/rider_session.py

@@ -0,0 +1,171 @@
+"""Long-running Source/Sink execution — start, stream, and cleanly stop a rider on its donor.
+
+Unlike the one-shot `RiderRunner` (used for deterministic grading), a rider in the app runs
+CONTINUOUSLY: start its tool inside the donor, stream output live, stop on demand. Two things make
+this safe:
+
+  * **streaming** — a reader thread reads the tool's stdout line by line and pushes a rolling
+    {raw, measurement, running} snapshot to an `on_update` callback (the caller marshals it to the
+    GUI via a Qt signal);
+  * **clean teardown** — `docker exec` does not reliably kill the in-container process when the
+    client goes away, so each rider is launched via a tiny wrapper that writes its PID to a file;
+    `stop()` kills that PID inside the container, then terminates the local client. No orphans.
+
+Popen + the kill call are injectable so the whole lifecycle is unit-testable without Docker.
+"""
+from __future__ import annotations
+
+import shlex
+import subprocess
+import threading
+
+from ..domain import riders as _riders
+
+# donor neighbours a ping/http rider can auto-target (reachable by service name)
+_TARGETABLE = {"host", "router", "instance", "container", "kinstance", "web_app", "firewall"}
+
+
+class _Sess:
+    def __init__(self, rider_id, type_key, service, pidfile, proc, donor, inferred) -> None:
+        self.rider_id = rider_id
+        self.type_key = type_key
+        self.service = service
+        self.pidfile = pidfile
+        self.proc = proc
+        self.donor = donor
+        self.inferred = inferred
+        self.lines: list[str] = []
+        self.stop_flag = False
+
+
+class RiderSessions:
+    def __init__(self, orchestrator, *, popen_factory=None, timeout: float = 8.0) -> None:
+        self.orch = orchestrator
+        self._popen = popen_factory or subprocess.Popen
+        self.timeout = timeout
+        self._sessions: dict[str, _Sess] = {}
+        self._svc_cache: dict | None = None
+
+    # -- state -------------------------------------------------------------- #
+    def is_running(self, rider_id: str) -> bool:
+        return rider_id in self._sessions
+
+    def running_ids(self) -> list[str]:
+        return list(self._sessions)
+
+    def available(self) -> bool:
+        try:
+            states = self.orch.status()
+        except Exception:
+            return False
+        return any(str(s).startswith("running") for s in (states or {}).values())
+
+    def _service(self, name: str) -> str:
+        if self._svc_cache is None:
+            try:
+                self._svc_cache = {k.lower(): k for k in (self.orch.status() or {})}
+            except Exception:
+                self._svc_cache = {}
+        return self._svc_cache.get(name.lower(), name.lower())
+
+    def _infer_target(self, topo, donor_id: str, rider_id: str) -> str:
+        for nb in topo.neighbors(donor_id):
+            if nb.id != rider_id and nb.type_key in _TARGETABLE:
+                return nb.name
+        for d in topo.devices.values():
+            if d.id not in (donor_id, rider_id) and d.type_key in _TARGETABLE:
+                return d.name
+        return ""
+
+    # -- lifecycle ---------------------------------------------------------- #
+    def start(self, topo, rider_id: str, on_update) -> dict:
+        """Launch the rider on its donor and stream updates. Returns a start result dict."""
+        if rider_id in self._sessions:
+            return {"ok": True, "running": True, "already": True}
+        rider = topo.devices.get(rider_id)
+        if rider is None:
+            return {"ok": False, "error": "no such rider"}
+        donor = topo.donor_of(rider_id)
+        if donor is None:
+            return {"ok": False, "error": f"{rider.name} isn't attached to a donor yet."}
+
+        props = dict(rider.properties)
+        inferred = ""
+        if rider.type_key in ("ping_probe", "http_probe") and not (props.get("Target") or "").strip():
+            inferred = self._infer_target(topo, donor.id, rider_id)
+            if inferred:
+                props["Target"] = inferred
+        try:
+            argv = _riders.build_command(rider.type_key, props)
+        except _riders.RiderError as e:
+            return {"ok": False, "error": str(e)}
+
+        service = self._service(donor.name)
+        pidfile = f"/tmp/gini-rider-{rider_id}.pid"
+        # write our PID, then exec the tool (so `stop` can kill exactly this process in the container)
+        wrapped = ["sh", "-lc", f"echo $$ > {pidfile}; exec {shlex.join(argv)}"]
+        cmd = [*self.orch._dc, "exec", "-T", service, *wrapped]
+        wd = getattr(self.orch, "workdir", None)
+        try:
+            proc = self._popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+                               text=True, bufsize=1, cwd=str(wd) if wd else None)
+        except (FileNotFoundError, OSError) as e:
+            return {"ok": False, "error": f"couldn't start: {e}"}
+
+        sess = _Sess(rider_id, rider.type_key, service, pidfile, proc, donor.name, inferred)
+        self._sessions[rider_id] = sess
+        threading.Thread(target=self._reader, args=(sess, on_update), daemon=True).start()
+        return {"ok": True, "running": True, "donor": donor.name, "inferred_target": inferred}
+
+    def _snapshot(self, sess: _Sess, running: bool) -> dict:
+        raw = "\n".join(sess.lines)
+        m = _riders.parse_measurement(sess.type_key, raw)
+        return {"ok": True, "running": running, "raw": raw, "measurement": m,
+                "summary": _riders.summarize(sess.type_key, m), "donor": sess.donor,
+                "inferred_target": sess.inferred}
+
+    def _reader(self, sess: _Sess, on_update) -> None:
+        import time
+        last = 0.0
+        try:
+            for line in iter(sess.proc.stdout.readline, ""):
+                if sess.stop_flag:
+                    break
+                sess.lines.append(line.rstrip("\n"))
+                if len(sess.lines) > 300:
+                    sess.lines = sess.lines[-300:]
+                # THROTTLE: a high-rate rider (tcpdump under load prints per packet) would flood the
+                # GUI with rider_ran signals and freeze it. Coalesce to ~4 updates/sec; the final
+                # snapshot below always fires, so no data is lost — only intermediate redraws.
+                now = time.monotonic()
+                if now - last >= 0.25:
+                    on_update(sess.rider_id, self._snapshot(sess, running=True))
+                    last = now
+        except Exception:                                # noqa: BLE001 — a dead pipe just ends the run
+            pass
+        self._sessions.pop(sess.rider_id, None)          # finite run finished, or we were stopped
+        on_update(sess.rider_id, self._snapshot(sess, running=False))
+
+    def stop(self, rider_id: str) -> None:
+        sess = self._sessions.get(rider_id)
+        if sess is None:
+            return
+        sess.stop_flag = True
+        wd = getattr(self.orch, "workdir", None)
+        try:                                             # kill the tool INSIDE the container
+            subprocess.run(
+                [*self.orch._dc, "exec", "-T", sess.service, "sh", "-lc",
+                 f"kill $(cat {sess.pidfile}) 2>/dev/null; rm -f {sess.pidfile}"],
+                cwd=str(wd) if wd else None, capture_output=True, timeout=self.timeout)
+        except Exception:                                # noqa: BLE001
+            pass
+        for close in (lambda: sess.proc.terminate(), lambda: sess.proc.stdout.close()):
+            try:
+                close()
+            except Exception:                            # noqa: BLE001
+                pass
+        self._sessions.pop(rider_id, None)
+
+    def stop_all(self) -> None:
+        for rid in list(self._sessions):
+            self.stop(rid)

gini/services/shadow_store.py

@@ -0,0 +1,52 @@
+"""Housekeeping for the per-element shadow folders under ``~/.gini/xv6-shadows/``.
+
+The Load loop bind-mounts one folder per xv6 element (``~/.gini/xv6-shadows/<name>/gini_sched.c``)
+and, by design, never deletes it — a student's shadow persists across Stop/Run. The flip side is
+they accumulate (a renamed/removed element leaves an orphan). This module provides the explicit
+housekeeping: **reset** one element's folder (so the next Run re-seeds the stub) and **prune**
+orphans. Nothing here runs automatically — deleting student work is always a deliberate act.
+
+Pure (os/shutil/pathlib only); unit-tested with a ``GINI_HOME_DIR`` override.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+
+def _home() -> Path:
+    # Same rule as app.paths.gini_home / content.py, replicated to avoid an app import.
+    return Path(os.environ.get("GINI_HOME_DIR") or (Path.home() / ".gini")).expanduser()
+
+
+def shadows_root() -> Path:
+    return _home() / "xv6-shadows"
+
+
+def list_shadows() -> list[str]:
+    """Element names that currently have a shadow folder."""
+    root = shadows_root()
+    return sorted(p.name for p in root.iterdir() if p.is_dir()) if root.is_dir() else []
+
+
+def reset_shadow(name: str) -> bool:
+    """Delete one element's shadow folder so the next Run re-seeds a fresh stub. Returns True if a
+    folder was removed. (Live, the Machine Lab's Revert restores the stub *contents* without a Stop;
+    this is the offline / start-over path.)"""
+    d = shadows_root() / name
+    if d.is_dir():
+        shutil.rmtree(d, ignore_errors=True)
+        return True
+    return False
+
+
+def prune_shadows(keep) -> list[str]:
+    """Remove shadow folders whose element name is NOT in ``keep`` (orphans from deleted/renamed
+    elements). Pass the CURRENT set of xv6 element names. Returns the names removed."""
+    keep = set(keep or ())
+    removed = []
+    for name in list_shadows():
+        if name not in keep and reset_shadow(name):
+            removed.append(name)
+    return removed

gini/services/terminal.py

@@ -0,0 +1,45 @@
+"""Open a platform terminal running a command — the 'double-click to log in' plumbing.
+
+Mirrors old gBuilder's xterm-on-double-click, but cross-platform: a real terminal
+window the student types into (docker exec into a machine, or a console into a
+network element).
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+def open_terminal(title: str, cwd: str | Path, command: str) -> tuple[bool, str]:
+    cwd = str(cwd)
+    if sys.platform == "darwin":
+        script = f'cd {_q(cwd)} && clear && echo {_q("== " + title + " ==")} && {command}'
+        osa = f'tell application "Terminal" to do script "{script.replace(chr(34), chr(92) + chr(34))}"'
+        try:
+            subprocess.Popen(["osascript", "-e", osa,
+                              "-e", 'tell application "Terminal" to activate'])
+            return True, "opened Terminal"
+        except FileNotFoundError:
+            return False, "osascript not found"
+    # Linux: try the common terminal emulators
+    for term, args in (
+        ("x-terminal-emulator", ["-e"]),
+        ("gnome-terminal", ["--"]),
+        ("konsole", ["-e"]),
+        ("xterm", ["-e"]),
+    ):
+        if shutil.which(term):
+            full = f"cd {_q(cwd)}; {command}; exec ${{SHELL:-sh}}"
+            try:
+                subprocess.Popen([term, *args, "bash", "-lc", full])
+                return True, f"opened {term}"
+            except OSError:
+                continue
+    return False, ("no terminal emulator found — run manually:\n"
+                   f"  cd {cwd} && {command}")
+
+
+def _q(s: str) -> str:
+    return "'" + s.replace("'", "'\\''") + "'"

gini/setup/__init__.py

@@ -0,0 +1,17 @@
+"""GINI setup — the `gini-setup` command that brings in the container runtime + images.
+
+`pip install gini-toolkit` gives the desktop app; the heavy runtime (Docker/Colima) and the custom
+container images live outside the wheel. `gini-setup` detects/guides the runtime install and pulls
+the images from the registry, then writes a marker (~/.gini/setup.json) so `gbuilder` knows live Run
+is ready (Demo mode always works without it).
+"""
+from __future__ import annotations
+
+# Registry namespace for the published images. Placeholder until the GHCR org is created + CI pushes;
+# override with the GINI_REGISTRY env var.
+import os
+
+REGISTRY = os.environ.get("GINI_REGISTRY", "ghcr.io/gini-toolkit")
+
+# The custom images the app needs (third-party images like alpine/postgres are pulled by Compose).
+IMAGES = ["gini-xv6", "gini-oszoo", "gini-grouter", "gini-pox"]

gini/setup/cli.py

@@ -0,0 +1,109 @@
+"""`gini-setup` — one-time bootstrap of the container runtime + images.
+
+    gini-setup            # detect/guide the runtime, then pull the images
+    gini-setup --check    # report status and exit
+    gini-setup --update   # re-pull images (after `pip install -U gini-toolkit`)
+    gini-setup --yes      # run auto-install steps without prompting
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import images, marker, runtime
+
+
+def _confirm(question: str) -> bool:
+    try:
+        return input(f"{question} [y/N] ").strip().lower() in ("y", "yes")
+    except EOFError:
+        return False
+
+
+def _app_version() -> str:
+    from .. import __version__
+    return __version__
+
+
+def _do_check(os_name: str) -> int:
+    print(f"gini-toolkit {_app_version()}  ·  {os_name}")
+    print("  runtime:", "available" if runtime.docker_available() else "NOT found")
+    if marker.is_setup_done():
+        print(f"  setup:   done (version {marker.setup_version()})")
+        if marker.needs_update(_app_version()):
+            print("  note:    app was upgraded — run `gini-setup --update` to refresh images.")
+    else:
+        print("  setup:   not run yet")
+    return 0
+
+
+def _ensure_runtime(os_name: str, assume_yes: bool) -> bool:
+    if runtime.docker_available():
+        return True
+    plan = runtime.runtime_plan(os_name)
+    print(f"No container runtime found. GINI uses {plan['runtime']} on {os_name}.")
+    if plan["auto"]:
+        print("These commands can set it up:")
+        for c in plan["auto"]:
+            print("   ", c)
+        if assume_yes or _confirm("Run them now?"):
+            for c in plan["auto"]:
+                if runtime.run_shell(c) != 0:
+                    print("Step failed:", c, "\n\n", plan["manual"])
+                    return False
+        else:
+            print("\n" + plan["manual"])
+            return False
+    else:
+        print("\n" + plan["manual"])
+        return False
+    if not runtime.docker_available():
+        print("Runtime installed but not reachable yet — start it and re-run `gini-setup`.")
+        return False
+    return True
+
+
+def _pull(os_name: str) -> int:
+    refs = images.image_refs(_app_version())
+    print("Pulling images:")
+    for r in refs:
+        print("   ", r)
+    results = images.pull_images(refs)
+    ok = [r for r, s in results if s]
+    bad = [r for r, s in results if not s]
+    for r, s in results:
+        print("  ok  " if s else "  FAIL", r)
+    marker.write_marker({"version": _app_version(), "os": os_name,
+                         "tag": images.image_tag(_app_version()), "images": ok})
+    print("\nRecorded", marker.marker_path())
+    if bad:
+        print("\nSome images could not be pulled — they may not be published yet, or the registry "
+              "is unreachable. Live Run will be limited until they're available.")
+        return 2
+    print("\nSetup complete. Launch the app with:  gbuilder")
+    return 0
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="gini-setup",
+                                 description="Bring in the GINI container runtime + images.")
+    ap.add_argument("--check", action="store_true", help="report status and exit")
+    ap.add_argument("--update", action="store_true", help="re-pull images for the current version")
+    ap.add_argument("--yes", "-y", action="store_true", help="run auto-install steps without asking")
+    args = ap.parse_args(argv)
+    os_name = runtime.detect_os()
+
+    if args.check:
+        return _do_check(os_name)
+    if args.update:
+        if not runtime.docker_available():
+            print("No runtime — run `gini-setup` first.")
+            return 1
+        return _pull(os_name)
+    if not _ensure_runtime(os_name, args.yes):
+        return 1
+    return _pull(os_name)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gini/setup/images.py

@@ -0,0 +1,33 @@
+"""Pull the custom GINI images from the registry, pinned to the app version."""
+from __future__ import annotations
+
+import subprocess
+
+from . import IMAGES, REGISTRY
+
+
+def image_tag(version: str | None) -> str:
+    """A released version (e.g. 6.1.0) pins images to that tag; a dev/unreleased build uses 'latest'
+    (there's no matching published tag yet)."""
+    if not version:
+        return "latest"
+    if "dev" in version or "+" in version or version.startswith("0"):
+        return "latest"
+    return version
+
+
+def image_refs(version: str | None) -> list[str]:
+    tag = image_tag(version)
+    return [f"{REGISTRY}/{name}:{tag}" for name in IMAGES]
+
+
+def pull_images(refs, run=subprocess.run) -> list[tuple[str, bool]]:
+    """Pull each ref; return [(ref, ok)]. A failure is captured, not raised (image may be unpublished)."""
+    out = []
+    for ref in refs:
+        try:
+            r = run(["docker", "pull", ref], timeout=1800)
+            out.append((ref, r.returncode == 0))
+        except Exception:
+            out.append((ref, False))
+    return out

gini/setup/marker.py

@@ -0,0 +1,43 @@
+"""The setup marker — ~/.gini/setup.json — records that the runtime + images were brought in, so
+`gbuilder` can tell whether live Run is ready without re-probing everything on launch."""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+
+def gini_home() -> Path:
+    return Path(os.environ.get("GINI_HOME", str(Path.home() / ".gini")))
+
+
+def marker_path() -> Path:
+    return gini_home() / "setup.json"
+
+
+def read_marker() -> dict:
+    try:
+        return json.loads(marker_path().read_text())
+    except Exception:
+        return {}
+
+
+def write_marker(info: dict) -> None:
+    p = marker_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(info, indent=2))
+
+
+def is_setup_done() -> bool:
+    """True once at least one image has been pulled and recorded."""
+    return bool(read_marker().get("images"))
+
+
+def setup_version() -> str | None:
+    return read_marker().get("version")
+
+
+def needs_update(app_version: str) -> bool:
+    """The app was upgraded past the version setup last ran for -> user should re-run gini-setup."""
+    v = setup_version()
+    return is_setup_done() and v is not None and v != app_version

gini/setup/runtime.py

@@ -0,0 +1,69 @@
+"""Container-runtime detection + per-OS install guidance.
+
+The runtime can't be bundled, and it differs per OS (Colima is macOS/Linux only; Windows uses Docker
+Desktop/Podman). We detect a working Docker socket and, where we can, offer the auto-install commands
+— but only after the user consents (we never silently run privileged installers)."""
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+
+
+def detect_os() -> str:
+    return {"Darwin": "macos", "Linux": "linux", "Windows": "windows"}.get(
+        platform.system(), "unknown")
+
+
+def docker_available(run=subprocess.run) -> bool:
+    """True if a Docker-compatible CLI is present AND a daemon answers (Colima/Desktop/Engine/Podman)."""
+    if not shutil.which("docker"):
+        return False
+    try:
+        r = run(["docker", "info"], capture_output=True, timeout=15)
+        return r.returncode == 0
+    except Exception:
+        return False
+
+
+# Per-OS plan: the runtime we recommend, the commands we CAN auto-run (with consent), and the manual
+# fallback text. Colima is macOS/Linux; Windows has no Colima.
+_PLANS = {
+    "macos": {
+        "runtime": "Colima + docker CLI",
+        "auto": ["brew install colima docker",
+                 "colima start --cpu 2 --memory 4 --disk 30"],
+        "needs": "Homebrew",
+        "manual": ("Install Homebrew from https://brew.sh, then run:\n"
+                   "    brew install colima docker\n"
+                   "    colima start --cpu 2 --memory 4 --disk 30"),
+    },
+    "linux": {
+        "runtime": "Docker Engine",
+        "auto": [],   # distro-specific + needs sudo -> we guide rather than run
+        "needs": "sudo / your package manager",
+        "manual": ("Install Docker Engine for your distro "
+                   "(https://docs.docker.com/engine/install/) and add your user to the 'docker' "
+                   "group:  sudo usermod -aG docker $USER  (then log out/in). Podman also works."),
+    },
+    "windows": {
+        "runtime": "Docker Desktop (or Podman Desktop)",
+        "auto": ["winget install -e --id Docker.DockerDesktop"],
+        "needs": "winget + admin",
+        "manual": ("Install Docker Desktop (https://www.docker.com/products/docker-desktop) or "
+                   "Podman Desktop, then start it. (Colima is not available on Windows.)"),
+    },
+}
+
+
+def runtime_plan(os_name: str) -> dict:
+    return _PLANS.get(os_name, {"runtime": "a Docker-compatible runtime", "auto": [], "needs": "",
+                                "manual": "Install Docker or a compatible runtime and start it."})
+
+
+def run_shell(cmd: str, run=subprocess.run) -> int:
+    """Run one auto-install command, streaming to the console. Returns the exit code."""
+    try:
+        return run(cmd, shell=True).returncode
+    except Exception:
+        return 1

gini/ui/__init__.py

@@ -0,0 +1,3 @@
+from .main_window import MainWindow
+
+__all__ = ["MainWindow"]

gini/ui/assets/cue/_w.txt

@@ -0,0 +1 @@
+test