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

gini/domain/riders.py

@@ -0,0 +1,309 @@
+"""Riders — how a Source/Sink runs on its donor, and what its output *means*.
+
+A rider has no container: it runs a tool INSIDE its donor (a Machine, Router, …). This module is the
+pure, testable half of that — it turns a rider + its properties into a command to exec on the donor
+(`build_command`) and turns the tool's raw output into a single gradable measurement
+(`parse_measurement`). No Docker here: the thin adapter that actually execs lives in
+`services.rider_runner`, exactly like `domain.probes` ↔ `services.probe_runner`.
+
+The measurement is the "output-as-measurement" from the I/O design: one scalar (loss %, ok %, packet
+count) that grading asserts on and that a composition edge can branch on. The raw text is the
+"output-as-data" shown in the console.
+"""
+from __future__ import annotations
+
+import re
+
+from . import devices as _devices
+
+
+class RiderError(ValueError):
+    pass
+
+
+def _int(v, default: int) -> int:
+    try:
+        return max(0, int(str(v).strip()))
+    except (TypeError, ValueError):
+        return default
+
+
+def build_command(rider_type: str, props: dict | None = None) -> list[str]:
+    """The argv to exec INSIDE the donor for this rider. Raises RiderError if a required field
+    (e.g. a ping/http Target) is missing, so the UI can prompt instead of running a broken command."""
+    props = props or {}
+    dt = _devices.REGISTRY.get(rider_type)
+    if dt is None or not getattr(dt, "rider", False):
+        raise RiderError(f"{rider_type} is not a rider")
+
+    # Count == 0 → run CONTINUOUSLY (until the student stops it); Count == N → do N and auto-stop.
+    if rider_type == "ping_probe":
+        target = (props.get("Target") or "").strip()
+        if not target:
+            raise RiderError("Ping Probe has no Target — set one in the inspector, or attach it to a "
+                             "donor that's wired to something to auto-pick a reachable neighbour.")
+        n = _int(props.get("Count"), 0)
+        argv = ["ping"]
+        if n > 0:
+            argv += ["-c", str(n)]
+        argv += ["-W", "1", target]
+        return argv
+
+    if rider_type == "http_probe":
+        target = (props.get("Target") or "").strip()
+        if not target:
+            raise RiderError("HTTP Probe needs a Target (the host/service to request).")
+        path = (props.get("Path") or "/").strip() or "/"
+        if not path.startswith("/"):
+            path = "/" + path
+        n = _int(props.get("Count"), 0)
+        url = f"http://{target}{path}"
+        # one line per request: "<http_code> <time_total_seconds>"
+        one = (f'curl -sS -o /dev/null -m 5 -w "%{{http_code}} %{{time_total}}\\n" {url} '
+               f'|| echo "000 0"')
+        if n > 0:
+            script = f'for i in $(seq {n}); do {one}; done'
+        else:
+            script = f'while true; do {one}; sleep 0.5; done'
+        return ["sh", "-lc", script]
+
+    if rider_type == "packet_view":
+        n = _int(props.get("Count"), 0)
+        filt = (props.get("Filter") or "").strip()
+        # default to the GINI overlay (gini0), NOT `any` — otherwise students see Docker-bridge
+        # (eth0) plumbing mixed with their drawn network. Interface is overridable.
+        iface = (props.get("Interface") or "gini0").strip() or "gini0"
+        argv = ["tcpdump", "-n", "-l", "-i", iface]     # -l = line-buffered, so it streams live
+        if n > 0:
+            argv += ["-c", str(n)]
+        if filt:
+            argv += filt.split()
+        return argv
+
+    if rider_type == "dns_probe":
+        name = (props.get("Target") or props.get("Query") or "").strip()
+        if not name:
+            raise RiderError("DNS Probe needs a Target — the hostname or service name to resolve.")
+        n = _int(props.get("Count"), 0)
+        # `getent hosts` uses the system resolver (files→DNS), so it honours the overlay entries
+        # GINI writes into /etc/hosts and returns the gini0 address — `dig` would bypass hosts and
+        # hit Docker's bridge DNS instead. Output line: "<HH:MM:SS> <ip-or-empty>".
+        lookup = "getent hosts %s 2>/dev/null | head -1 | awk '{print $1}'" % name
+        one = 'echo "$(date +%%T) $(%s)"' % lookup
+        script = ("for i in $(seq %d); do %s; sleep 1; done" % (n, one)) if n > 0 \
+            else ("while true; do %s; sleep 1; done" % one)
+        return ["sh", "-lc", script]
+
+    if rider_type == "traceroute_probe":
+        target = (props.get("Target") or "").strip()
+        if not target:
+            raise RiderError("Traceroute needs a Target to trace a path to.")
+        return ["traceroute", "-n", "-w", "2", target]
+
+    if rider_type == "iperf_client":
+        target = (props.get("Target") or "").strip()
+        if not target:
+            raise RiderError("iPerf Client needs a Target running an iPerf Server.")
+        secs = _int(props.get("Seconds"), 10) or 10
+        argv = ["iperf3", "-c", target, "-t", str(secs)]
+        # cap the rate: unlimited iperf saturates the user-space fabric and pins the Docker VM's CPU.
+        # A bounded rate is a controlled, repeatable measurement. "0"/"unlimited" opts out.
+        rate = (props.get("Bitrate") or "").strip()
+        if rate and rate.lower() not in ("0", "unlimited", "max"):
+            argv += ["-b", rate]
+        return argv
+
+    if rider_type == "iperf_server":
+        return ["iperf3", "-s"]
+
+    if rider_type == "iface_stats":
+        # stream rx/tx counters from /proc/net/dev, one snapshot per second
+        return ["sh", "-lc", 'while true; do cat /proc/net/dev; echo "==="; sleep 1; done']
+
+    if rider_type in ("xv6_shell", "xv6_workload"):
+        raise RiderError("xv6 riders run over the console, not docker — use xv6_command().")
+
+    raise RiderError(f"no command builder for rider {rider_type}")
+
+
+def xv6_command(rider_type: str, props: dict | None = None) -> str:
+    """The line to TYPE into an xv6 Machine's console (the qemu-serial driver), for riders that ride
+    an xv6 donor. Raises RiderError if a required field is missing."""
+    props = props or {}
+    if rider_type == "xv6_shell":
+        cmd = (props.get("Command") or "").strip()
+        if not cmd:
+            raise RiderError("Shell Probe needs a Command to run on the xv6 Machine (e.g. 'ls').")
+        return cmd
+    if rider_type == "xv6_workload":
+        prog = (props.get("Program") or "spin").strip()
+        args = (props.get("Args") or "").strip()
+        line = prog + (f" {args}" if args else "")
+        if str(props.get("Background", "true")).lower() in ("true", "1", "yes"):
+            line += " &"                                 # run in the background so several compete
+        return line
+    raise RiderError(f"{rider_type} is not an xv6 rider")
+
+
+# --------------------------------------------------------------------------- #
+# measurement parsing — raw tool output → one gradable scalar (+ a few extras)
+# --------------------------------------------------------------------------- #
+_PING_LOSS = re.compile(r"(\d+(?:\.\d+)?)%\s*packet loss")
+_PING_RTT = re.compile(r"=\s*[\d.]+/([\d.]+)/[\d.]+")     # min/AVG/max…
+_PING_TXRX = re.compile(r"(\d+)\s+packets transmitted,\s*(\d+)\s+(?:packets )?received")
+_TCPDUMP_CAP = re.compile(r"(\d+)\s+packets captured")
+
+
+def parse_measurement(rider_type: str, raw: str) -> dict:
+    """Reduce a rider's raw output to a measurement dict. Always returns a dict (never raises); an
+    unparseable output yields {'ok': False} so the caller can show 'no reading' rather than crash."""
+    raw = raw or ""
+
+    if rider_type == "ping_probe":
+        loss = _PING_LOSS.search(raw)
+        rtt = _PING_RTT.search(raw)
+        txrx = _PING_TXRX.search(raw)
+        times = [float(t) for t in re.findall(r"time=([\d.]+)", raw)]     # per-reply RTTs
+        seqs = [int(s) for s in re.findall(r"(?:icmp_seq|seq)=(\d+)", raw)]
+        out: dict = {"ok": bool(loss or times)}
+        if loss:                                             # finite run: trust the summary
+            out["loss_pct"] = float(loss.group(1))
+        elif seqs:                                           # streaming: derive from per-packet lines
+            sent, recv = max(seqs) + 1, len(times)
+            out["loss_pct"] = round(max(0.0, (sent - recv) / sent * 100), 1) if sent else 0.0
+        if rtt:
+            out["rtt_avg_ms"] = float(rtt.group(1))
+        elif times:
+            out["rtt_avg_ms"] = round(sum(times) / len(times), 3)
+        if txrx:
+            out["transmitted"], out["received"] = int(txrx.group(1)), int(txrx.group(2))
+        elif seqs:
+            out["transmitted"], out["received"] = max(seqs) + 1, len(times)
+        return out
+
+    if rider_type == "http_probe":
+        codes, times = [], []
+        for line in raw.splitlines():
+            parts = line.split()
+            if len(parts) == 2 and parts[0].isdigit():
+                codes.append(int(parts[0]))
+                try:
+                    times.append(float(parts[1]))
+                except ValueError:
+                    pass
+        if not codes:
+            return {"ok": False}
+        ok = sum(1 for c in codes if 200 <= c < 300)
+        out = {"ok": True, "requests": len(codes), "ok_count": ok,
+               "ok_pct": round(100.0 * ok / len(codes), 1)}
+        if times:
+            out["avg_ms"] = round(1000.0 * sum(times) / len(times), 1)
+        return out
+
+    if rider_type == "packet_view":
+        low = raw.lower()
+        if "not found" in low or "permission denied" in low or "no such device" in low:
+            return {"ok": False, "error": raw.strip().splitlines()[-1] if raw.strip() else "failed"}
+        cap = _TCPDUMP_CAP.search(raw)
+        if cap:
+            return {"ok": True, "packets": int(cap.group(1))}
+        lines = [ln for ln in raw.splitlines() if re.match(r"^\d\d:\d\d:\d\d", ln)]
+        if lines:
+            return {"ok": True, "packets": len(lines)}
+        if "listening on" in low:            # tcpdump ran fine, the link was just idle
+            return {"ok": True, "packets": 0}
+        return {"ok": False}
+
+    if rider_type == "dns_probe":
+        # each line: "<HH:MM:SS> <ip> <ip> ..."  (empty tail = failed to resolve)
+        rows = [ln.split() for ln in raw.splitlines() if re.match(r"^\d\d:\d\d:\d\d", ln)]
+        if not rows:
+            return {"ok": False}
+        answered = sum(1 for r in rows if len(r) > 1)
+        last = next((" ".join(r[1:]) for r in reversed(rows) if len(r) > 1), "")
+        return {"ok": True, "queries": len(rows), "resolved": answered,
+                "resolved_pct": round(100.0 * answered / len(rows), 1), "answer": last}
+
+    if rider_type == "traceroute_probe":
+        hops = [ln for ln in raw.splitlines() if re.match(r"^\s*\d+\s", ln)]
+        if not hops:
+            return {"ok": False}
+        reached = not any("* * *" in h for h in hops[-1:])
+        return {"ok": True, "hops": len(hops), "reached": reached}
+
+    if rider_type in ("iperf_client", "iperf_server"):
+        # iperf3 prints "... 942 Mbits/sec ..." lines; take the last rate seen
+        rates = re.findall(r"([\d.]+)\s*([KMG])bits/sec", raw)
+        if "not found" in raw.lower() or "unable" in raw.lower() or "error" in raw.lower():
+            return {"ok": bool(rates), "error": raw.strip().splitlines()[-1] if raw.strip() else ""}
+        if not rates:
+            return {"ok": "iperf" in raw.lower() or "Server listening" in raw}
+        val, unit = rates[-1]
+        mbps = float(val) * {"K": 0.001, "M": 1.0, "G": 1000.0}[unit]
+        return {"ok": True, "mbps": round(mbps, 1)}
+
+    if rider_type == "iface_stats":
+        # sum non-loopback interface counters from the LAST /proc/net/dev block
+        blocks = raw.split("===")
+        block = next((b for b in reversed(blocks) if ":" in b), "")
+        rx_p = tx_p = 0
+        for ln in block.splitlines():
+            if ":" not in ln or ln.strip().startswith("Inter") or ln.strip().startswith("face"):
+                continue
+            name, _, rest = ln.partition(":")
+            nm = name.strip()
+            if nm == "lo" or nm.startswith("eth"):   # hide loopback + the Docker-bridge plumbing
+                continue
+            f = rest.split()
+            if len(f) >= 16:
+                rx_p += int(f[1]); tx_p += int(f[9])
+        if not block.strip():
+            return {"ok": False}
+        return {"ok": True, "rx_packets": rx_p, "tx_packets": tx_p}
+
+    return {"ok": False}
+
+
+# the gradable metrics each rider exposes (metric key, human label) — drives output-check authoring
+METRICS: dict[str, list[tuple[str, str]]] = {
+    "ping_probe": [("loss_pct", "packet loss %"), ("rtt_avg_ms", "avg RTT (ms)")],
+    "http_probe": [("ok_pct", "2xx success %"), ("avg_ms", "avg latency (ms)")],
+    "dns_probe": [("resolved_pct", "resolved %")],
+    "traceroute_probe": [("hops", "hop count")],
+    "iperf_client": [("mbps", "throughput (Mbit/s)")],
+    "iperf_server": [("mbps", "throughput (Mbit/s)")],
+    "packet_view": [("packets", "packets captured")],
+    "iface_stats": [("rx_packets", "rx packets"), ("tx_packets", "tx packets")],
+}
+
+
+def metrics_for(rider_type: str) -> list[tuple[str, str]]:
+    return METRICS.get(rider_type, [])
+
+
+def summarize(rider_type: str, m: dict) -> str:
+    """A one-line, human summary of a measurement for the inspector chip."""
+    if not m or not m.get("ok"):
+        return "no reading"
+    if rider_type == "ping_probe":
+        s = f"{m.get('loss_pct', '?')}% loss"
+        if "rtt_avg_ms" in m:
+            s += f" · {m['rtt_avg_ms']} ms avg"
+        return s
+    if rider_type == "http_probe":
+        s = f"{m.get('ok_pct', '?')}% 2xx ({m.get('ok_count', 0)}/{m.get('requests', 0)})"
+        if "avg_ms" in m:
+            s += f" · {m['avg_ms']} ms avg"
+        return s
+    if rider_type == "packet_view":
+        return f"{m.get('packets', 0)} packets"
+    if rider_type == "dns_probe":
+        ans = m.get("answer", "")
+        return f"{m.get('resolved_pct', '?')}% resolved" + (f" → {ans}" if ans else "")
+    if rider_type == "traceroute_probe":
+        return f"{m.get('hops', 0)} hops" + ("" if m.get("reached", True) else " (unreached)")
+    if rider_type in ("iperf_client", "iperf_server"):
+        return f"{m.get('mbps', 0)} Mbit/s" if "mbps" in m else "listening"
+    if rider_type == "iface_stats":
+        return f"rx {m.get('rx_packets', 0)} · tx {m.get('tx_packets', 0)} pkts"
+    return "ok"

gini/domain/router_modules.py

@@ -0,0 +1,224 @@
+"""Router Lab model — the gRouter's data-plane as a composable module graph.
+
+Pure-Python and Qt-free so it's testable and (later) maps onto the real gRouter's
+module graph over the control protocol. Today it drives the Router Lab editor and a
+local packet trace for the step-through debugger.
+
+Model (matches the consolidated gRouter design):
+  * a MODE gate at ingress: 'legacy' | 'openflow' (OpenFlow = flow table front door,
+    legacy pipeline becomes its NORMAL action),
+  * a fixed BASE pipeline (parse -> route -> rewrite),
+  * an ordered list of INLINE add-on / custom modules that compose in series.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class ModuleType:
+    key: str
+    label: str
+    icon: str           # an icon key from ui.theme.icons
+    accent: str         # accent color key
+    kind: str           # base | inline | custom
+    description: str
+    default_params: dict = field(default_factory=dict)
+    # How this VNF maps onto the REAL gRouter data-plane module (gpipe): (module_name,
+    # arg_param_key or None). None => illustrative (no real backend yet — labeled as such).
+    gpipe: tuple | None = None
+
+    @property
+    def real(self) -> bool:
+        """True if this service function has a real gRouter data-plane backend (deployable
+        via `gpipe add …`), False if it's an illustrative teaching stub."""
+        return self.gpipe is not None
+
+
+BASE: list[ModuleType] = [
+    ModuleType("parse", "Parse", "grid", "slate", "base", "Ethernet / ARP / IP parse"),
+    ModuleType("route", "Route lookup", "router", "blue", "base", "Longest-prefix match"),
+    ModuleType("rewrite", "Rewrite", "send", "blue", "base", "Dec TTL, checksum, next-hop MAC"),
+]
+
+# Inline VNFs (service functions). `gpipe` names the gRouter data-plane function that
+# actually runs, so a module carrying one is REAL — it is programmed into the router and
+# moves packets. Every inline VNF now qualifies: classify and tap were the last two
+# illustrative entries, and the QoS and Tap work gave both a backend.
+#
+# The illustrative modules are now the CUSTOM ones below: a Lua or native VNF is real
+# only once you have written and compiled it, which is the point of that tier.
+INLINE: list[ModuleType] = [
+    ModuleType("acl", "ACL / Firewall", "firewall", "amber", "inline",
+               "Stateless packet filter (drop a CIDR)", {"deny": "10.0.3.0/24"},
+               gpipe=("acl", "deny")),
+    ModuleType("nat", "NAT", "gateway", "indigo", "inline",
+               "Source NAT / masquerade to an address", {"ip": "203.0.113.1"},
+               gpipe=("nat", "ip")),
+    ModuleType("block", "Block IP", "firewall", "red", "inline",
+               "Drop packets to a destination IP (native Zig module)", {"ip": "10.0.3.5"},
+               gpipe=("block", "ip")),
+    ModuleType("rate", "Rate limit", "queue", "green", "inline",
+               "Token-bucket policer — drops packets that exceed a set rate",
+               {"spec": "100/200"}, gpipe=("rate", "spec")),
+    ModuleType("classify", "QoS classifier", "layout", "teal", "inline",
+               "Mark matching traffic with a DSCP class", {"spec": "10.0.3.0/24:ef"},
+               gpipe=("classify", "spec")),
+    ModuleType("tap", "Tap / capture", "link", "purple", "inline",
+               "Mirror matching packets to a .pcap under /captures "
+               "(host: ~/.gini/captures) — open it in Wireshark",
+               {"path": "/captures/cap.pcap"}, gpipe=("tap", "path")),
+]
+
+# Inline VNFs you write yourself — a Lua script (interpreted per packet) or a native module you
+# compile in. Both share the same gpipe seam as the built-in native functions once implemented.
+CUSTOM: list[ModuleType] = [
+    ModuleType("lua", "Lua VNF", "compile", "cyan", "custom",
+               "Per-packet Lua hook — a `process(pkt, ctx)` function you write",
+               {"script": "function process(pkt, ctx)\n  return CONTINUE\nend"}),
+    ModuleType("native", "Native VNF", "controller", "purple", "custom",
+               "A native (Zig / C) data-plane module you compile in", {}),
+]
+
+MODULE_BY_KEY: dict[str, ModuleType] = {m.key: m for m in (*BASE, *INLINE, *CUSTOM)}
+
+
+@dataclass
+class ModuleInstance:
+    type_key: str
+    name: str
+    params: dict = field(default_factory=dict)
+
+    @property
+    def type(self) -> ModuleType:
+        return MODULE_BY_KEY[self.type_key]
+
+
+@dataclass
+class Stage:
+    label: str
+    kind: str            # ingress | mode | base | inline | egress
+    key: str | None      # module type key (None for ingress/egress)
+    accent: str
+    locked: bool
+    index: int | None    # index into program.inline (for inline stages), else None
+
+
+def _ip_in_cidr(ip: str, cidr: str) -> bool:
+    """True if dotted-quad `ip` falls inside `cidr` (e.g. '10.0.2.0/24'). Mirrors the C ACL's
+    mask-and-compare, so the offline trace agrees with what the real gRouter would drop."""
+    try:
+        net, _, bits = cidr.partition("/")
+        bits = int(bits) if bits else 32
+        to_int = lambda a: sum(int(o) << (24 - 8 * i) for i, o in enumerate(a.split(".")))
+        mask = (0xffffffff << (32 - bits)) & 0xffffffff if bits else 0
+        return (to_int(ip) & mask) == (to_int(net) & mask)
+    except Exception:
+        return False
+
+
+class RouterProgram:
+    def __init__(self) -> None:
+        self.mode = "legacy"             # 'legacy' | 'openflow'
+        self.inline: list[ModuleInstance] = []
+        self.classifier = ""             # which traffic enters the chain ("" = all)
+
+    # SFC: classifier + deploy to the real gRouter -------------------------- #
+    def set_classifier(self, expr: str) -> None:
+        self.classifier = (expr or "").strip()
+
+    def deploy_commands(self) -> list[str]:
+        """The `gpipe` argument-lines that program THIS chain into the running gRouter (each
+        is sent as `gpipe <cmd>`): clear, then add each service function that has a real
+        data-plane backend, in order. Illustrative modules are skipped."""
+        cmds = ["clear"]
+        for inst in self.inline:
+            g = inst.type.gpipe
+            if g is None:
+                continue
+            name, argkey = g
+            arg = inst.params.get(argkey) if argkey else None
+            cmds.append(f"add {name} {arg}" if arg else f"add {name}")
+        return cmds
+
+    def illustrative(self) -> list[ModuleInstance]:
+        """Inline functions with no real gRouter backend yet (shown, not deployed)."""
+        return [i for i in self.inline if i.type.gpipe is None]
+
+    # editing -------------------------------------------------------------- #
+    def add(self, type_key: str) -> ModuleInstance:
+        mt = MODULE_BY_KEY[type_key]
+        inst = ModuleInstance(type_key, mt.label, dict(mt.default_params))
+        self.inline.append(inst)
+        return inst
+
+    def remove(self, index: int) -> None:
+        if 0 <= index < len(self.inline):
+            self.inline.pop(index)
+
+    def move(self, index: int, delta: int) -> None:
+        j = index + delta
+        if 0 <= index < len(self.inline) and 0 <= j < len(self.inline):
+            self.inline[index], self.inline[j] = self.inline[j], self.inline[index]
+
+    def set_mode(self, mode: str) -> None:
+        self.mode = "openflow" if mode == "openflow" else "legacy"
+
+    # the canonical ordered pipeline --------------------------------------- #
+    def stages(self) -> list[Stage]:
+        out: list[Stage] = [Stage("ingress", "ingress", None, "slate", True, None)]
+        if self.mode == "openflow":
+            out.append(Stage("OpenFlow flow table", "mode", "openflow", "teal", True, None))
+        parse = BASE[0]
+        out.append(Stage(parse.label, "base", parse.key, parse.accent, True, None))
+        for i, inst in enumerate(self.inline):
+            mt = inst.type
+            out.append(Stage(inst.name, "inline", mt.key, mt.accent, False, i))
+        for mt in BASE[1:]:
+            out.append(Stage(mt.label, "base", mt.key, mt.accent, True, None))
+        out.append(Stage("egress", "egress", None, "slate", True, None))
+        return out
+
+    # local packet trace (drives the step debugger) ------------------------ #
+    def trace(self, dst: str = "10.0.2.10") -> list[str]:
+        verdicts: list[str] = []
+        dropped = False
+        for st in self.stages():
+            if dropped:
+                verdicts.append("—")
+                continue
+            if st.kind == "ingress":
+                verdicts.append(f"in · dst {dst}")
+            elif st.kind == "mode":
+                verdicts.append("match → NORMAL (to legacy)")
+            elif st.kind == "egress":
+                verdicts.append("sent ✓")
+            elif st.key == "acl":
+                deny = self.inline[st.index].params.get("deny", "")
+                if deny and _ip_in_cidr(dst, deny):
+                    verdicts.append(f"DROP (matches deny {deny})")
+                    dropped = True
+                else:
+                    verdicts.append("pass")
+            elif st.key == "block":
+                tgt = self.inline[st.index].params.get("ip", "")
+                if tgt and dst == tgt:
+                    verdicts.append(f"DROP (blocks {tgt})")
+                    dropped = True
+                else:
+                    verdicts.append("pass")
+            elif st.key == "nat":
+                verdicts.append("rewrite source · continue")
+            elif st.key == "route":
+                verdicts.append("→ next-hop eth1")
+            elif st.key == "rewrite":
+                verdicts.append("ttl-- · checksum")
+            elif st.key == "rate":
+                verdicts.append("policer · within rate → pass")
+            elif st.key == "classify":
+                verdicts.append("mark DSCP · continue")
+            elif st.key == "tap":
+                verdicts.append("mirror → pcap · continue")
+            else:
+                verdicts.append("pass")
+        return verdicts

gini/domain/routetable.py

@@ -0,0 +1,67 @@
+"""Routing/ARP-table parsing — turn the gRouter's `route` and `arp` CLI dumps into rows for
+the Router Lab's routing view.
+
+A regular router is the C gRouter; at runtime `element_query(router, "route show")` prints
+its route table and `element_query(router, "arp show")` its ARP cache (the gRouter CLI needs
+the `show` subcommand — a bare `route`/`arp` prints nothing). This module parses both.
+Pure/text-only, so it's unit-tested without Docker.
+
+`route` output (from routetable.c printRouteTable):
+    Index   Network         Netmask         Nexthop         Interface
+    [0]     10.0.1.0        255.255.255.0   0.0.0.0         tun1
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+_ROUTE_RE = re.compile(r"^\[(\d+)\]\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s*$")
+
+
+@dataclass
+class RouteEntry:
+    index: int
+    network: str
+    netmask: str
+    nexthop: str          # 0.0.0.0 == directly connected
+    iface: str
+
+    @property
+    def direct(self) -> bool:
+        return self.nexthop in ("0.0.0.0", "*", "", "0")
+
+    def nexthop_str(self) -> str:
+        return "direct (on-link)" if self.direct else self.nexthop
+
+
+def parse_routes(text: str) -> list[RouteEntry]:
+    """Rows of the gRouter route table (lines like `[0] net mask nexthop iface`)."""
+    out: list[RouteEntry] = []
+    for line in (text or "").splitlines():
+        m = _ROUTE_RE.match(line.strip())
+        if m:
+            out.append(RouteEntry(int(m.group(1)), m.group(2), m.group(3),
+                                  m.group(4), m.group(5)))
+    return out
+
+
+# ARP cache: the gRouter prints IP<->MAC pairs; be tolerant about exact columns and just
+# pull the first dotted-quad IP and first MAC on each line.
+_IP_RE = re.compile(r"\b(\d{1,3}(?:\.\d{1,3}){3})\b")
+_MAC_RE = re.compile(r"\b([0-9a-fA-F]{2}(?::[0-9a-fA-F]{2}){5})\b")
+
+
+@dataclass
+class ArpEntry:
+    ip: str
+    mac: str
+
+
+def parse_arp(text: str) -> list[ArpEntry]:
+    out: list[ArpEntry] = []
+    for line in (text or "").splitlines():
+        ip = _IP_RE.search(line)
+        mac = _MAC_RE.search(line)
+        if ip and mac:
+            out.append(ArpEntry(ip.group(1), mac.group(1)))
+    return out

gini/domain/scoring.py

@@ -0,0 +1,76 @@
+"""Scoring — objective results → completion + a broad band.
+
+Completion is deterministic (GINI's runtime supplies the objective facts; the AI never scores).
+We check *completion*, not quality: how many objectives are met, whether `complete_when` is
+satisfied, and whether it was done on time / within attempts. Bands are intentionally coarse.
+
+`complete_when`: `all` | `any` | `at_least(n)`. A `pending` (behavioral, un-run) objective counts
+as not-yet-met.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .objectives import ObjectiveResult
+
+GOLD, PASS, PARTIAL, INCOMPLETE = "gold", "pass", "partial", "incomplete"
+
+_AT_LEAST = re.compile(r"at_least\(\s*(\d+)\s*\)")
+
+
+@dataclass
+class Score:
+    band: str
+    met: int
+    total: int
+    complete: bool
+    pending: int              # behavioral objectives not yet run
+    forks_done: int = 0       # how many difficulty forks the student fully completed
+    forks_total: int = 0      # forks this mission offers (0 = a plain, fork-less mission)
+
+    @property
+    def summary(self) -> str:
+        s = f"{self.met}/{self.total} objectives"
+        if self.pending:
+            s += f" ({self.pending} awaiting a run)"
+        if self.forks_total:
+            s += f" · {self.forks_done}/{self.forks_total} harder forks"
+        return s
+
+
+def is_complete(results, complete_when: str = "all") -> bool:
+    met = sum(1 for r in results if r.met)
+    total = len(results)
+    cw = (complete_when or "all").strip()
+    if cw == "any":
+        return met >= 1
+    m = _AT_LEAST.fullmatch(cw)
+    if m:
+        return met >= int(m.group(1))
+    return met == total and total > 0          # 'all' (default)
+
+
+def score(results, *, complete_when: str = "all", on_time: bool = True,
+          forks_done: int = 0, forks_total: int = 0) -> Score:
+    """Compute the band from CORE objective results, lifted by difficulty forks.
+
+    Fork-less mission (forks_total == 0) — unchanged, so nothing regresses:
+        gold = complete AND on time · pass = complete · partial = some met · incomplete = none.
+
+    Forked mission — the fork is the difficulty knob (GINI_AUTHORING_DESIGN.md):
+        the golden (easy) path completing earns PASS; **gold now means you also took a harder fork**.
+        So a student can't coast to gold on the easy path — gold is reserved for going deeper.
+    """
+    results = list(results)
+    met = sum(1 for r in results if r.met)
+    pending = sum(1 for r in results if r.status == "pending")
+    complete = is_complete(results, complete_when)          # completion is CORE-only; forks are extra
+    if not complete:
+        band = PARTIAL if met > 0 else INCOMPLETE
+    elif forks_total == 0:
+        band = GOLD if on_time else PASS                    # legacy semantics preserved exactly
+    else:
+        band = GOLD if (forks_done >= 1 and on_time) else PASS
+    return Score(band=band, met=met, total=len(results), complete=complete, pending=pending,
+                 forks_done=forks_done, forks_total=forks_total)