bytesim 0.1.0__py3-none-any.whl

bytesim/tui/commands/topology.py

@@ -0,0 +1,255 @@
+"""Building the network: devices, cables, roles, failures, files, modes."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from ... import demos
+from ...constants import ALIASES, KINDS, REF, ROLES
+from ...model import Link, NetError, Network
+from ...topology import dump_topology, load_topology, looks_like_topology
+from ..help import HELP
+from ..theme import ROLE_COLOR
+from .base import CommandHost
+from .registry import command
+
+DEFAULT_FILE = "bytesim.json"
+
+
+class TopologyCommands(CommandHost):
+    @command("help", "?", "h")
+    def cmd_help(self, args: list[str], opts: dict[str, str]) -> None:
+        self.log_msg(HELP)
+
+    @command("add", "new", "+")
+    def cmd_add(self, args: list[str], opts: dict[str, str]) -> None:
+        net = self.net
+        if not args or args[0].lower() not in ALIASES:
+            raise NetError("usage: add <g|r|s|c> [ports] [count]")
+        kind = ALIASES[args[0].lower()]
+        try:
+            nports = int(args[1]) if len(args) > 1 else None
+            count = int(args[2]) if len(args) > 2 else 1
+        except ValueError:
+            raise NetError("ports and count must be numbers") from None
+        if not 1 <= count <= 100:
+            raise NetError("count must be 1..100")
+        made = []
+        for _ in range(count):
+            d = net.add(kind, nports)
+            if not self.auto:
+                net.place_new(d)
+            made.append(d)
+        kindword = "NIC" if kind == "c" else "port"
+        n = made[0].nports
+        self.log_msg(f"[green]+[/] {KINDS[kind][0]} {' '.join(d.id for d in made)} "
+                     f"({n} {kindword}{'s' if n != 1 else ''})")
+        self.changed()
+        self.canvas.select(made[-1].id)
+
+    @command("link", "connect", "ln", "cable")
+    def cmd_link(self, args: list[str], opts: dict[str, str]) -> None:
+        net = self.net
+        if len(args) != 2:
+            raise NetError("usage: link <id>[:port] <id>[:port] [role=...]")
+        role = opts.get("role", "data")
+        if role not in ROLES:
+            raise NetError(f"role must be one of: {', '.join(ROLES)}")
+        (a, pa), (b, pb) = self._ref(args[0]), self._ref(args[1])
+        l = net.connect(a, pa, b, pb, role)
+        da, db = net.devices[l.a], net.devices[l.b]
+        self.log_msg(f"[green]⇄[/] [{da.color}]{l.a}[/]:{da.port_name(l.pa)} ── "
+                     f"[{db.color}]{l.b}[/]:{db.port_name(l.pb)}"
+                     + (f" [{ROLE_COLOR[role]}]{role}[/]" if role != "data" else ""))
+        # Plugging in a computer kicks off a (visible) DHCP exchange.
+        ends = [(d, p) for d, p in ((da, l.pa), (db, l.pb))
+                if d.kind == "c" and net.iface(d.id, p).mode == "dhcp" and not self.graph
+                and not self.replaying]          # scripts re-address once, at the end
+        self.changed(skip=frozenset((d.id, p) for d, p in ends))
+        for d, p in ends:                 # by Device: auto-renumber may have renamed it
+            self._dhcp_exchange((d.id, p))  # type: ignore[attr-defined]
+
+    @command("unlink", "disconnect", "cut")
+    def cmd_unlink(self, args: list[str], opts: dict[str, str]) -> None:
+        if not 1 <= len(args) <= 2:
+            raise NetError("usage: unlink <id>[:port] [id]")
+        a, pa = self._ref(args[0])
+        b = self._ref(args[1])[0] if len(args) == 2 else None
+        n = self.net.disconnect(a, pa, b)
+        self.log_msg(f"[yellow]✂[/] removed {n} cable{'s' if n != 1 else ''}" if n
+                     else "[dim]no matching cables[/]")
+        self.changed()
+
+    @command("del", "rm", "delete", "remove")
+    def cmd_del(self, args: list[str], opts: dict[str, str]) -> None:
+        if not args:
+            raise NetError("usage: del <id> [id ...]")
+        for tok in args:
+            did, _ = self._ref(tok)
+            n = self.net.remove(did)
+            self.log_msg(f"[red]−[/] {did} deleted ({n} cable{'s' if n != 1 else ''} removed)")
+        self.changed()
+
+    @command("ports", "nics", "resize")
+    def cmd_ports(self, args: list[str], opts: dict[str, str]) -> None:
+        if args and args[0].lower() == "copy":     # ports copy src(old, …) dst(new, …): cabling only
+            self.copy_cabling(args[1:])  # type: ignore[attr-defined]
+            return
+        if len(args) != 2 or not args[1].isdigit():
+            raise NetError("usage: ports <id> <count>")
+        did, _ = self._ref(args[0])
+        self.net.resize(did, int(args[1]))
+        self.log_msg(f"{did} now has {args[1]} ports")
+        self.changed()
+
+    @command("role")
+    def cmd_role(self, args: list[str], opts: dict[str, str]) -> None:
+        role = args[-1].lower() if args else ""
+        if len(args) < 2 or role not in ROLES:
+            raise NetError(f"usage: role <id[:port]> [id] <{'|'.join(ROLES)}>")
+        for l in self._links_matching(args[:-1]):
+            l.role = role
+            self.log_msg(f"{self._link_text(l)} is now [{ROLE_COLOR[role]}]{role}[/]")
+        self.changed()
+
+    @command("fail", "down")
+    def cmd_fail(self, args: list[str], opts: dict[str, str]) -> None:
+        self._fail(args, up=False)
+
+    @command("restore", "up", "repair")
+    def cmd_restore(self, args: list[str], opts: dict[str, str]) -> None:
+        self._fail(args, up=True)
+
+    @command("mode")
+    def cmd_mode(self, args: list[str], opts: dict[str, str]) -> None:
+        if not args or args[0].lower() not in ("graph", "addr", "ip", "address"):
+            self.log_msg(f"mode: [b]{'graph' if self.graph else 'addr'}[/]  (mode graph | mode addr)")
+            return
+        self.graph = args[0].lower() == "graph"
+        self.log_msg("[b]graph mode[/]: traffic follows cables only, addresses ignored" if self.graph
+                     else "[b]address mode[/]: networks, gateways and DHCP apply")
+        self.changed()
+
+    @command("auto", "arrange", "layout")
+    def cmd_auto(self, args: list[str], opts: dict[str, str]) -> None:
+        self.arrange(announce=True)  # type: ignore[attr-defined]
+
+    @command("list", "ls")
+    def cmd_list(self, args: list[str], opts: dict[str, str]) -> None:
+        net = self.net
+        for d in net.sorted_devices():
+            used = sum(1 for l in net.links if l.touches(d.id))
+            self.log_msg(f"[{d.color}]{d.id:<4}[/] {d.name:<8} {used}/{d.nports} "
+                         f"{'NICs' if d.kind == 'c' else 'ports'}")
+        for l in net.links:
+            self.log_msg("  " + self._link_text(l))
+        if net.groups:
+            self.dispatch(["groups"])
+        if not net.devices:
+            self.log_msg("[dim]empty network[/]")
+
+    @command("clear")
+    def cmd_clear(self, args: list[str], opts: dict[str, str]) -> None:
+        self.replace_network(Network(), auto=True)  # type: ignore[attr-defined]
+        self.log_msg("[yellow]network cleared[/]")
+
+    @command("demo")
+    def cmd_demo(self, args: list[str], opts: dict[str, str]) -> None:
+        name = args[0].lower() if args else "basic"
+        if name not in demos.DEMOS:
+            raise NetError(f"demos: {', '.join(demos.DEMOS)}")
+        net, hint = demos.DEMOS[name]()
+        self.replace_network(net, auto=True)  # type: ignore[attr-defined]
+        self.log_msg(hint)
+
+    @command("save")
+    def cmd_save(self, args: list[str], opts: dict[str, str]) -> None:
+        path = Path(args[0] if args else DEFAULT_FILE).expanduser()
+        try:
+            path.write_text(self.net.to_json())
+        except OSError as e:
+            raise NetError(f"couldn't save {path}: {e}") from None
+        self.log_msg(f"saved to {path}")
+
+    @command("load", "open")
+    def cmd_load(self, args: list[str], opts: dict[str, str]) -> None:
+        path = Path(args[0] if args else DEFAULT_FILE).expanduser()
+        try:
+            text = path.read_text()
+            topology = looks_like_topology(text)
+            net = load_topology(text) if topology else Network.from_json(text)
+        except NetError as e:
+            raise NetError(f"{path}: {e}") from None
+        except (OSError, ValueError, KeyError, TypeError) as e:
+            raise NetError(f"couldn't load {path}: {e}") from None
+        # A topology has no positions, so it's laid out; a save file keeps its own.
+        self.replace_network(net, auto=topology)  # type: ignore[attr-defined]
+        self.log_msg(f"loaded {path} ({len(net.devices)} devices, {len(net.links)} cables"
+                     + (", topology: auto-arranged)" if topology else ")"))
+
+    @command("export")
+    def cmd_export(self, args: list[str], opts: dict[str, str]) -> None:
+        if args and args[0].lower() == "script":            # export script [mode] [file]
+            self.export_script(args[1:])  # type: ignore[attr-defined]
+            return
+        if not 1 <= len(args) <= 2 or (len(args) == 2 and args[1].lower() != "ports"):
+            raise NetError("usage: export <file.yaml> [ports]   (ports = pin every cable to its ports)")
+        path = Path(args[0]).expanduser()
+        pin = len(args) == 2
+        try:
+            path.write_text(dump_topology(self.net, pin_ports=pin))
+        except OSError as e:
+            raise NetError(f"couldn't write {path}: {e}") from None
+        self.log_msg(f"exported topology to {path}"
+                     + (" (every port pinned)" if pin else " (compact: meshes folded, ports allocated on load)"))
+
+    @command("quit", "exit", "q")
+    def cmd_quit(self, args: list[str], opts: dict[str, str]) -> None:
+        self.exit()  # type: ignore[attr-defined]
+
+    # ---- helpers -------------------------------------------------------
+    def _link_text(self, l: Link, state: bool = True) -> str:
+        net = self.net
+        txt = f"{l.a}:{net.devices[l.a].port_name(l.pa)} ── {l.b}:{net.devices[l.b].port_name(l.pb)}"
+        if l.role != "data":
+            txt += f" [{ROLE_COLOR[l.role]}]{l.role}[/]"
+        return txt + (" [red]✕ down[/]" if state and not l.up else "")
+
+    def _links_matching(self, args: list[str]) -> list[Link]:
+        """Cables picked by `id:port` or `id[:port] id[:port]`."""
+        if not 1 <= len(args) <= 2:
+            raise NetError("pick a cable with id:port, or two device ids")
+        (a, pa) = self._ref(args[0])
+        self.net.get(a)
+        b, pb = self._ref(args[1]) if len(args) == 2 else (None, None)
+        if b is None and pa is None:
+            raise NetError(f"which cable of {a}? use {a}:<port> or name the other end")
+        hit = [l for l in self.net.links if l.touches(a)
+               and (pa is None or l.port_of(a) == pa)
+               and (b is None or (l.other(a)[0] == b and (pb is None or l.other(a)[1] == pb)))]
+        if not hit:
+            raise NetError("no matching cable")
+        return hit
+
+    def _fail(self, args: list[str], up: bool) -> None:
+        net = self.net
+        verb = "restored" if up else "failed"
+        if not args:
+            raise NetError(f"usage: {'restore' if up else 'fail'} <id> | <id:port> | <id> <id>"
+                           + (" | all" if up else ""))
+        if up and args[0].lower() == "all":
+            for d in net.devices.values():
+                d.up = True
+            for l in net.links:
+                l.up = True
+            self.log_msg("[green]✓ everything restored[/]")
+        elif len(args) == 1 and REF.match(args[0]) and self._ref(args[0])[1] is None:
+            d = net.get(self._ref(args[0])[0])
+            d.up = up
+            self.log_msg(f"[{'green' if up else 'red'}]{'✓' if up else '✕'} {d.id} {verb}[/]")
+        else:
+            for l in self._links_matching(args):
+                l.up = up
+                self.log_msg(f"[{'green' if up else 'red'}]{'✓' if up else '✕'}[/] cable "
+                             f"{self._link_text(l, state=False)} {verb}")
+        net.mac_tables = {}
+        self.changed()

bytesim/tui/commands/traffic.py

@@ -0,0 +1,312 @@
+"""Sending things: ping, unicast and multicast, in address or graph mode."""
+from __future__ import annotations
+
+import random
+
+from rich.markup import escape
+
+from ...constants import ADDR, HOST_MAX, REF
+from ...model import Leg, NetError, fmt
+from ..cables import route
+from .base import CommandHost
+from .registry import command
+
+
+class TrafficCommands(CommandHost):
+    INTERNET = ("internet", "inet", "wan")
+
+    @staticmethod
+    def _flatten(legs: list[Leg]) -> list[tuple[str, int]]:
+        path: list[tuple[str, int]] = []
+        for _, _, p in legs:
+            path.extend(p if not path else p[1:])
+        return path
+
+    @staticmethod
+    def _reverse(path: list[tuple[str, int]]) -> list[tuple[str, int]]:
+        return [(path[-1][0], -1)] + [(path[i][0], path[i + 1][1]) for i in range(len(path) - 2, -1, -1)]
+
+    def _ifname(self, ifc: tuple[str, int]) -> str:
+        return f"{ifc[0]}:{self.net.devices[ifc[0]].port_name(ifc[1])}"
+
+    def _parse_addr(self, tok: str) -> tuple[int, int] | None:
+        m = ADDR.match(tok)
+        if not m:
+            return None
+        net, host = int(m[1]), int(m[2])
+        if net < 1 or not 1 <= host < HOST_MAX:
+            raise NetError(f"bad address {tok}: network ≥ 1, host 1..{HOST_MAX - 1}")
+        return net, host
+
+    def _resolve_dst(self, tok: str) -> tuple[str, list[tuple[str, int]] | None]:
+        """A destination token -> (label, candidate interfaces); None means the internet."""
+        net = self.net
+        if tok.lower() in self.INTERNET:
+            return "internet", None
+        if (addr := self._parse_addr(tok)) is not None:
+            hit = net.resolve(addr)
+            if hit is None:
+                raise NetError(f"nobody has {fmt(addr)} (ARP got no reply)")
+            return f"{fmt(addr)} {hit[0]}", [hit]
+        did, port = self._ref(tok)
+        dev = net.get(did)
+        if dev.kind == "s":
+            raise NetError(f"{did} is a switch (layer 2): it has no address to reach")
+        if port:
+            if not net.iface(did, port).addr:
+                raise NetError(f"{did}:{dev.port_name(port)} has no address")
+            return f"{did}:{dev.port_name(port)}", [(did, port)]
+        cands = [(did, p) for p, _ in net.addressed(did)]
+        if not cands:
+            raise NetError(f"{did} has no address (try: dhcp {did})")
+        return did, cands
+
+    def _best_route(self, src: str, cands: list[tuple[str, int]] | None) -> list[Leg]:
+        if cands is None:
+            return self.net.route(src, None)
+        best, err = None, None
+        for c in cands:
+            try:
+                legs = self.net.route(src, c)
+            except NetError as e:
+                err = e
+                continue
+            if best is None or len(self._flatten(legs)) < len(self._flatten(best)):
+                best, self._last_dst = legs, c
+        if best is None:
+            raise err  # type: ignore[misc]
+        return best
+
+    def _src(self, tok: str) -> str:
+        did = self.net.get(self._ref(tok)[0]).id
+        if self.net.devices[did].kind == "s" and not self.graph:
+            raise NetError(f"{did} is a switch (layer 2): it can't originate addressed traffic")
+        return did
+
+    def _plan(self, src: str, tok: str) -> tuple[str, list[tuple[str, int]], list[Leg] | None, bool]:
+        """Work out how a packet gets from src to tok: (label, device path, legs, to-internet).
+
+        In graph mode it's the shortest cable path; in address mode it follows
+        networks and gateways, and legs records each layer-2 hop."""
+        net = self.net
+        internet = tok.lower() in self.INTERNET
+        if self.graph:
+            if ADDR.match(tok):
+                raise NetError("graph mode ignores addresses: use device ids (or `mode addr`)")
+            tree = net.tree(src)
+            if internet:
+                dst = next((d for d in tree if net.devices[d].kind == "g"), None)
+                if dst is None:
+                    raise NetError(f"no gateway reachable from {src}")
+                label = "internet"
+            else:
+                dst = net.get(self._ref(tok)[0]).id
+                label = dst
+            path = net.path_in(tree, dst)
+            if path is None:
+                raise NetError(f"{dst} is not reachable from {src}"
+                               + self.storm_hint(src, dst))  # type: ignore[attr-defined]
+            return label, path, None, internet
+        net.notes.clear()
+        label, cands = self._resolve_dst(tok)
+        try:
+            legs = self._best_route(src, cands)
+        except NetError as e:
+            hint = self.storm_hint(src, *(c[0] for c in cands or []))  # type: ignore[attr-defined]
+            raise NetError(f"{e}{hint}") from None
+        # Each hop starts with an ARP request: a broadcast. Into a live loop, that's a storm.
+        for a, b, _ in legs:
+            fl = net.flood(a)
+            if fl.storm:
+                self.set_off_storm(fl, f"the ARP for {fmt(net.addr_of(b))} from {self._ifname(a)}")  # type: ignore[attr-defined]
+                raise NetError(f"{self._ifname(a)} never got an ARP reply: its broadcast set off a storm")
+        return label, self._flatten(legs), legs, internet
+
+    def _learn(self, legs: list[Leg] | None, both_ways: bool = False) -> None:
+        for a, b, p in legs or []:
+            self.net.learn(a, p)
+            if both_ways:
+                self.net.learn(b, self._reverse(p))
+
+    def _log_route(self, kind: str, color: str, src: str, label: str,
+                   path: list[tuple[str, int]], legs: list[Leg] | None, internet: bool) -> None:
+        net = self.net
+        chain = " → ".join(f"[{net.devices[d].color}]{d}[/]" for d, _ in path)
+        if internet:
+            chain += " → [magenta]☁[/]"
+        if legs is None:
+            self.log_msg(f"[b {color}]{kind}[/] {src} → {label}: {chain}")
+            return
+        frm = fmt(net.addr_of(legs[0][0]))
+        to = "internet" if internet else label.split()[0] if label.startswith("(") else fmt(net.addr_of(self._last_dst))
+        self.log_msg(f"[b {color}]{kind}[/] {frm} → {to} [dim]({src} → {label})[/]: {chain}")
+        for a, b, _ in legs:
+            self.log_msg(f"  [dim]ARP {fmt(net.addr_of(b))} is-at {net.devices[b[0]].mac(b[1])} "
+                         f"(asked by {self._ifname(a)})[/]")
+        for note in dict.fromkeys(net.notes):
+            self.log_msg(f"  [{'red' if note.startswith('⚠') else 'orchid'}]{escape(note)}[/]")
+
+    def _routers_in(self, path: list[tuple[str, int]], legs: list[Leg] | None) -> int:
+        if legs is not None:
+            return len(legs) - 1
+        return sum(1 for d, _ in path[1:-1] if self.net.is_router(d))
+
+    @command("ping", "trace", "tracert", "traceroute")
+    def cmd_ping(self, args: list[str], opts: dict[str, str]) -> None:
+        if len(args) != 2:
+            raise NetError("usage: ping <src> <id|(net,host)|internet>")
+        src = self._src(args[0])
+        if args[1].lower() not in self.INTERNET and self._ref_or_none(args[1]) == src:
+            self.log_msg(f"{src}: reply from self (loopback)")
+            return
+        try:
+            label, path, legs, internet = self._plan(src, args[1])
+        except NetError as e:
+            raise NetError(f"ping {src} → {args[1]}: {e}") from None
+        if len(path) < 2:
+            self.log_msg(f"[green]{src} is a gateway: internet reachable directly[/]")
+            return
+        self._log_route("PING", "red", src, label, path, legs, internet)
+        self._learn(legs, both_ways=True)
+        back = self._reverse(path)
+        c = self.canvas
+        links = [li for _, li in path[1:]]
+        c.heat(links)
+        ttl = 64 - self._routers_in(path, legs)
+        rtt = sum(random.uniform(0.15, 0.6) for _ in path) * 2 + (12 if internet else 0)
+
+        def arrived() -> None:
+            c.flash_device(path[-1][0], "red")
+            c.send_packet(self._cells(back), "green", replied)
+
+        def replied() -> None:
+            c.cool(links)
+            c.flash_device(src, "green")
+            self.log_msg(f"  [green]reply from {label}[/]: hops={len(path) - 1} "
+                         f"ttl={ttl} time={rtt:.2f} ms")
+            self.refresh_sidebar()
+
+        c.send_packet(self._cells(path), "red", arrived)
+
+    def _ref_or_none(self, tok: str) -> str | None:
+        m = REF.match(tok)
+        return f"{m[1].lower()}{int(m[2])}" if m else None
+
+    def _cells(self, path: list[tuple[str, int]]) -> list[tuple[int, int]]:
+        """Screen cells a packet crosses along a path, port to port."""
+        net = self.net
+        cells: list[tuple[int, int]] = []
+        for (u, _), (v, li) in zip(path, path[1:]):
+            l = net.links[li]
+            pts = route(net, l, li)
+            if l.a != u:
+                pts = pts[::-1]
+            du, dv = net.devices[u], net.devices[v]
+            cells.append((du.port_x(l.port_of(u)), du.y + 2))
+            cells.extend(pts)
+            cells.append((dv.port_x(l.port_of(v)), dv.y + 2))
+        return cells
+
+    @command("unicast", "ucast", "send")
+    def cmd_unicast(self, args: list[str], opts: dict[str, str]) -> None:
+        """One packet, one destination, no reply."""
+        if len(args) != 2:
+            raise NetError("usage: unicast <src> <id|(net,host)|internet>")
+        src = self._src(args[0])
+        if self._ref_or_none(args[1]) == src:
+            raise NetError("source and destination are the same device")
+        try:
+            label, path, legs, internet = self._plan(src, args[1])
+        except NetError as e:
+            raise NetError(f"unicast {src} → {args[1]}: {e}") from None
+        if len(path) < 2:
+            raise NetError(f"{src} is a gateway: nothing to send through")
+        self._log_route("UNICAST", "orange1", src, label, path, legs, internet)
+        self._learn(legs)
+        c = self.canvas
+        links = [li for _, li in path[1:]]
+        c.heat(links)
+        routers = self._routers_in(path, legs)
+
+        def delivered() -> None:
+            c.cool(links)
+            c.flash_device(path[-1][0], "orange1")
+            self.log_msg(f"  [orange1]delivered to {label}[/]: {len(path) - 1} hops, "
+                         f"{routers} router{'s' if routers != 1 else ''}")
+            self.refresh_sidebar()
+
+        c.send_packet(self._cells(path), "orange1", delivered)
+
+    def _targets(self, toks: list[str]) -> list[str]:
+        """Expand device ids, addresses and group names into a list of device ids."""
+        out: list[str] = []
+        for t in toks:
+            if t.lower() in ("all", "*"):
+                ids = [d.id for d in self.net.sorted_devices() if d.kind == "c"]
+            elif t.lower() in self.net.groups:
+                ids = [d for d in self.net.devices_in(t.lower())
+                       if self.graph or self.net.devices[d].kind != "s"]   # switches can't receive
+            elif ADDR.match(t) and not self.graph:
+                ids = [self._resolve_dst(t)[1][0][0]]  # type: ignore[index]
+            else:
+                ids = [self.net.get(self._ref(t)[0]).id]
+            out.extend(i for i in ids if i not in out)
+        return out
+
+    @command("multicast", "mcast")
+    def cmd_multicast(self, args: list[str], opts: dict[str, str]) -> None:
+        """One packet, copied only where the paths to the receivers split."""
+        if len(args) < 2:
+            raise NetError("usage: multicast <src> <id|(net,host)|group|all> [...]")
+        net = self.net
+        src = self._src(args[0])
+        receivers = [d for d in self._targets(args[1:]) if d != src]
+        if not receivers:
+            raise NetError("no receivers (the source can't send to itself)")
+        paths: dict[str, list[tuple[str, int]]] = {}
+        lost: list[str] = []
+        for d in receivers:
+            try:
+                _, path, legs, _ = self._plan(src, d)
+            except NetError as e:
+                lost.append(f"{d} ({e})")
+                continue
+            self._learn(legs)
+            paths[d] = path
+        recv_txt = " ".join(f"[{net.devices[d].color}]{d}[/]" for d in receivers)
+        frm = src if self.graph else f"{fmt(next((i.addr for _, i in net.addressed(src)), None))} [dim]({src})[/]"
+        self.log_msg(f"[b bright_magenta]MULTICAST[/] {frm} → {recv_txt}")
+        for msg in lost:
+            self.log_msg(f"  [red]✗ unreachable: {escape(msg)}[/]")
+        if not paths:
+            return
+
+        # Links in the distribution tree, and where copies get made.
+        tree_links = {li for p in paths.values() for _, li in p[1:]}
+        children: dict[str, set[str]] = {}
+        for p in paths.values():
+            for (u, _), (v, _) in zip(p, p[1:]):
+                children.setdefault(u, set()).add(v)
+        forks = [f"{u}×{len(vs)}" for u, vs in children.items() if len(vs) > 1]
+        unicast_cost = sum(len(p) - 1 for p in paths.values())
+        self.log_msg(f"  copies made at: {' '.join(forks) or 'none (single path)'}")
+        self.log_msg(f"  {len(tree_links)} link transmissions "
+                     f"(separate unicasts would need {unicast_cost})")
+
+        # All copies leave together and share cells until their paths split,
+        # so on screen one packet visibly forks at each branching device.
+        c = self.canvas
+        c.heat(tree_links)
+        pending = [len(paths)]
+
+        def arrived(dst: str) -> None:
+            c.flash_device(dst, "bright_magenta")
+            pending[0] -= 1
+            if pending[0] == 0:
+                c.cool(tree_links)
+                self.log_msg(f"  [bright_magenta]delivered to {len(paths)} receiver{'s' if len(paths) != 1 else ''}[/]: "
+                             + " ".join(paths))
+                self.refresh_sidebar()
+
+        for dst, p in paths.items():
+            c.send_packet(self._cells(p), "bright_magenta", lambda d=dst: arrived(d))

bytesim/tui/help.py

@@ -0,0 +1,50 @@
+"""The text shown by the `help` command (Rich markup)."""
+
+HELP = """\
+[b]Commands[/]  (device ids: g1 r2 s3 c4 · ports: r1:3 or c2:nic2)
+  [cyan]add[/] <g|r|s|c> \\[ports] \\[count]   add devices    e.g. [i]add s 24[/], [i]add c 2 3[/]
+  [cyan]<id> <id>[/]                       cable two devices (first free ports)
+  [cyan]<id>:<port> <id>:<port>[/]         cable specific ports, e.g. [i]r1:2 s1:8[/]
+  [cyan]<id>[/]                            select device, then move it with arrow keys
+  [cyan]unlink[/] <id>\\[:port] \\[id]         remove cable(s)
+  [cyan]del[/] <id>                        delete a device
+  [cyan]ports[/] <id> <n>                  change port / NIC count
+  [cyan]ping[/] <id> <id|addr|internet>    echo request + reply (follows networks + gateways)
+  [cyan]unicast[/] <src> <id|addr>         one-way packet to a single device
+  [cyan]multicast[/] <src> <ids|groups|all> one packet, copied where paths split, e.g. [i]mcast c1 pcs c8[/]
+  [cyan]group[/] <name> <id|group ...>      logical layer; groups nest, e.g. [i]group dc1 fab1 rfab1[/]
+  [cyan]group[/] <name>  or  <name>         select a group (arrows / drag its frame move everything in it)
+  [cyan]ungroup[/] <name> \\[member ...]      take members out, or dissolve (members move up a level)
+  [cyan]clone[/] <group> \\[new-name]          copy a group: devices, nested groups, internal cables
+  [cyan]ports copy[/] <group>(old, …) <group>(new, …)   cable an existing group the way another is cabled, e.g.
+                                    [i]ports copy link1(rfab1, rfab2) link2(rfab2, rfab3)[/]
+  [cyan]copy[/] <group>(old, …) <new>(new, …)   the same, creating the new group as a clone first
+                                    a name like [i]fab(1)[/] means the next free fabN (group, clone)
+  [cyan]renumber[/] bfs|dfs \\[root]           renumber each kind 1..n in BFS/DFS order from root (default g1…)
+  [cyan]renumber auto[/] bfs|dfs \\[root] · [cyan]renumber off[/]   keep renumbering after every change
+  [cyan]export[/] <file.yaml> \\[ports]          declarative topology (load reads it back); ports = exact
+  [cyan]export script[/] \\[readable|shortest|explicit] \\[file]   the commands that rebuild this network
+  [cyan]run[/] <file>                       run a script of commands (after [cyan]clear[/] for an export)
+  [cyan]groups[/] · [cyan]auto[/] (re-arrange) · [cyan]list[/] · [cyan]demo[/] · [cyan]clear[/] · [cyan]save[/]/[cyan]load[/] \\[file] · [cyan]quit[/]
+[b]Addressing[/]  an address is (network, host): network id + 8-bit host, e.g. [i](2,14)[/]
+  MACs name the physical port: R1A = r1 port 1. A network spans every switch it touches.
+  Routers/gateways take host 1, 2… on each network and serve DHCP; computers lease hosts 10+,
+  or take a free host on their own when no server answers (ad-hoc)
+  [cyan]ip[/] \\[id\\[:port]]                    table of MACs, networks and hosts
+  [cyan]ip[/] <id:port> (net,host) \\[gw]      static, e.g. [i]ip c5 (2,50) 1[/]  ·  [cyan]ip[/] <id:port> dhcp|adhoc|none
+  [cyan]dhcp[/] <id\\[:nic]|all>                run DHCP (animated DISCOVER broadcast + OFFER)
+  [cyan]release[/] <id\\[:nic]|all>             give up a lease  ·  [cyan]adhoc[/] <id\\[:nic]|all>  self-assign
+  [cyan]dhcpd[/] <router> on|off             turn a router's DHCP server on or off
+  [cyan]mode[/] graph|addr                   graph mode: pure connectivity, no addressing rules
+[b]Loops, STP, storms[/]  switches run spanning tree unless it's switched off for them
+  [cyan]broadcast[/] <id\\[:port]>                 flood one frame; into a live loop it becomes a storm
+  [cyan]stp[/]  ·  [cyan]stp[/] on|off  ·  [cyan]stp[/] <switch…> on|off  ·  [cyan]stp priority[/] <switch> <n>  ·  [cyan]demo loop[/]
+[b]Roles, failures, HA[/]
+  [cyan]<id> <id> role=[/]data|control|control-backup|fabric   cable with a role (control = heartbeat only, ═)
+  [cyan]role[/] <id:port>|<id> <id> <role>       change a cable's role  (fabric = router↔router data, ━)
+  [cyan]fail[/] <id> | <id:port> | <id> <id>     kill a device or cable(s) · [cyan]restore[/] … | all
+  [cyan]cluster[/] <name> <routers…> \\[policy=none|quorum|witness]   HA pair/group sharing gateway host 254
+  [cyan]cluster[/] <name>  ·  [cyan]clusters[/]  ·  [cyan]uncluster[/] <name>  ·  [cyan]demo ha[/]
+  [cyan]undo[/] \\[n] · [cyan]redo[/] \\[n] · [cyan]history[/]   step back through changes (u / U on the canvas)
+[b]Canvas keys[/]  arrows move (shift = x4) · tab cycle · a arrange · x delete · u undo · U redo
+  hjkl / drag background / wheel pan · drag a box to move · v show/hide addresses · enter or : → command line"""