bytesim 0.1.0__py3-none-any.whl

bytesim/__init__.py

@@ -0,0 +1,14 @@
+"""ByteSim: a text-mode network simulator.
+
+The model (``bytesim.model``) can be used on its own::
+
+    from bytesim import Network
+    net = Network()
+    net.add("r"); net.add("c")
+    net.connect("r1", None, "c1", None)
+"""
+__version__ = "0.1.0"
+
+from .model import Device, Iface, Link, NetError, Network  # noqa: E402
+
+__all__ = ["Device", "Iface", "Link", "NetError", "Network", "__version__"]

bytesim/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

bytesim/cli.py

@@ -0,0 +1,45 @@
+"""Command-line entry point: ``bytesim [FILE] [--demo NAME] [--run CMD ...]``."""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="bytesim",
+        description="A text-mode network simulator: gateways, routers, switches and computers, "
+                    "cabled together and simulated in your terminal.")
+    p.add_argument("file", nargs="?", type=Path,
+                   help="a saved network (.json) or a topology (.yaml) to open")
+    p.add_argument("--demo", choices=["basic", "ha", "loop"], help="start with a sample network")
+    p.add_argument("--run", "-c", metavar="CMD", action="append", default=[],
+                   help="a console command to run at startup (repeatable)")
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return p
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = build_parser().parse_args(argv)
+    from .model import NetError, Network
+    from .topology import load_topology, looks_like_topology
+    from .tui import ByteSimApp
+
+    network, topology = None, False
+    if args.file is not None:
+        try:
+            text = args.file.read_text()
+            topology = looks_like_topology(text)
+            network = load_topology(text) if topology else Network.from_json(text)
+        except (OSError, ValueError, KeyError, TypeError, NetError) as e:
+            sys.exit(f"bytesim: couldn't open {args.file}: {e}")
+    startup = ([f"demo {args.demo}"] if args.demo else []) + args.run
+    # A topology carries no positions, so it starts auto-arranged.
+    ByteSimApp(network=network, startup=startup, auto=True if topology else None).run()
+
+
+if __name__ == "__main__":
+    main()

bytesim/constants.py

@@ -0,0 +1,48 @@
+"""Device kinds, sizes and the token grammar shared by the model and the UI."""
+from __future__ import annotations
+
+import re
+
+KINDS = {
+    "g": ("gateway", 4, "magenta"),
+    "r": ("router", 4, "cyan"),
+    "s": ("switch", 8, "green"),
+    "c": ("computer", 1, "dodger_blue1"),
+}
+
+RANK = {"g": 0, "r": 1, "s": 2, "c": 3}
+
+ALIASES = {
+    "g": "g", "gw": "g", "gateway": "g",
+    "r": "r", "router": "r",
+    "s": "s", "sw": "s", "switch": "s",
+    "c": "c", "pc": "c", "computer": "c", "host": "c",
+}
+
+MAX_PORTS = 64
+
+BOX_H = 4          # top border, label, port row, bottom border
+
+LAYER_GAP = 5      # empty rows between layers (room for link routing)
+
+H_GAP = 4          # columns between neighbouring boxes
+
+
+# Auto-numbering: prefix(n) stands for n new names, each prefix + the lowest free number.
+# s(2) → two new switches; fab(1) → one new group named fab<next>.
+AUTO = re.compile(r"^([A-Za-z][\w-]*?)\((\d+)\)$")
+REF = re.compile(r"^([grsc])(\d+)(?::(?:p|nic|eth)?(\d+))?$", re.I)
+
+GROUP_NAME = re.compile(r"^[a-z][\w-]{0,15}$", re.I)
+
+ADDR = re.compile(r"^\(?(\d+),(\d+)\)?$")   # (network, host) e.g. (2,14) or 2,14
+
+HOST_MAX = 255                                # 8-bit host numbers: 1..254, 255 = broadcast
+
+VIP_HOST = 254                                # virtual gateway shared by an HA router cluster
+
+POOL = range(10, VIP_HOST)                    # DHCP / ad-hoc hosts; routers take 1, 2, ...
+
+ROLES = ("data", "control", "control-backup", "fabric")
+
+POLICIES = ("none", "quorum", "witness")

bytesim/demos.py

@@ -0,0 +1,74 @@
+"""Ready-made networks. Each builder returns (network, hint for the console)."""
+from __future__ import annotations
+
+from typing import Callable
+
+from .model import Network
+
+
+def basic() -> tuple[Network, str]:
+    """A gateway, two routers, three switches and ten computers (two of them an ad-hoc pair)."""
+    net = Network()
+    net.add("g", 2)
+    for _ in range(2):
+        net.add("r", 4)
+    for _ in range(3):
+        net.add("s", 6)
+    for i in range(10):
+        net.add("c", 2 if i == 2 else 1)
+    for a, b in [("g1", "r1"), ("r1", "r2"), ("r1", "s1"), ("r1", "s2"), ("r2", "s3"),
+                 ("s1", "c1"), ("s1", "c2"), ("s1", "c3"), ("s2", "c3"), ("s2", "c4"),
+                 ("s2", "c5"), ("s3", "c6"), ("s3", "c7"), ("s3", "c8"),
+                 ("c9", "c10")]:
+        net.connect(a, None, b, None)
+    net.group_add("core", ["r1", "r2"])
+    net.group_add("fab1", ["s1", "s2", "s3"])
+    return net, ("[green]demo network loaded[/] — try [cyan]ping c1 c8[/], [cyan]mcast c1 c4 c6 c8[/], "
+                 "[cyan]dhcp c4[/], [cyan]ip[/], or [cyan]ping c9 c10[/] (an ad-hoc pair, no router)")
+
+
+def ha() -> tuple[Network, str]:
+    """Two fabrics joined by a clustered router pair with redundant control links."""
+    net = Network()
+    for _ in range(2):
+        net.add("r", 6)
+    for _ in range(4):
+        net.add("s", 6)
+    for _ in range(6):
+        net.add("c", 1)
+    for a, pa, b in [("s1", None, "s2"), ("s3", None, "s4"), ("r1", 1, "s1"), ("r2", 1, "s2"),
+                     ("r1", 2, "s3"), ("r2", 2, "s4"),
+                     ("s1", None, "c1"), ("s1", None, "c2"), ("s2", None, "c3"),
+                     ("s3", None, "c4"), ("s3", None, "c5"), ("s4", None, "c6")]:
+        net.connect(a, pa, b, None)
+    net.connect("r1", 5, "r2", 5, "control")
+    net.connect("r1", 6, "r2", 6, "control-backup")
+    net.connect("r1", 4, "r2", 4, "fabric")
+    net.group_add("fab1", ["s1", "s2"])
+    net.group_add("fab2", ["s3", "s4"])
+    net.group_add("rfab1", ["r1", "r2"])
+    net.clusters["rfab1"] = "none"
+    return net, ("[green]HA demo loaded[/]: r1+r2 form cluster rfab1 between fab1 and fab2.\n"
+                 "  try [cyan]ping c1 c6[/], then [cyan]fail r1:5[/], [cyan]fail r1:6[/] (split-brain), "
+                 "[cyan]cluster rfab1 policy=witness[/], [cyan]fail r1[/], [cyan]fail r1:2[/], [cyan]restore all[/]")
+
+
+def loop() -> tuple[Network, str]:
+    """Three switches cabled in a triangle with spanning tree switched off."""
+    net = Network()
+    net.add("r", 2)
+    for _ in range(3):
+        net.add("s", 6)
+    for _ in range(3):
+        net.add("c", 1)
+    for a, b in [("r1", "s1"), ("s1", "s2"), ("s2", "s3"), ("s3", "s1"),
+                 ("s1", "c1"), ("s2", "c2"), ("s3", "c3")]:
+        net.connect(a, None, b, None)
+    net.group_add("ring", ["s1", "s2", "s3"])
+    net.stp_off = {"s1", "s2", "s3"}
+    return net, ("[green]loop demo loaded[/]: s1–s2–s3 form a triangle and STP is off.\n"
+                 "  try [cyan]broadcast c1[/] (or [cyan]ping c1 c2[/]) to set off a storm, then "
+                 "[cyan]stp on[/], [cyan]stp[/], [cyan]fail s1:2[/], [cyan]ping c1 c2[/]")
+
+
+DEMOS: dict[str, Callable[[], tuple[Network, str]]] = {"basic": basic, "ha": ha, "loop": loop}

bytesim/model/__init__.py

@@ -0,0 +1,5 @@
+"""The network model: devices, cables, groups, addressing, routing and HA. No UI code."""
+from .network import Network
+from .types import Device, Iface, Leg, Link, NetError, fmt
+
+__all__ = ["Device", "Iface", "Leg", "Link", "NetError", "Network", "fmt"]

bytesim/model/addressing.py

@@ -0,0 +1,160 @@
+"""Addresses as (network, 8-bit host); router autoconfig, DHCP and ad-hoc."""
+from __future__ import annotations
+
+from ..constants import HOST_MAX, POOL, VIP_HOST
+from .base import NetworkBase
+from .types import Iface, NetError, fmt
+
+
+class AddressingMixin(NetworkBase):
+    def iface(self, dev_id: str, port: int) -> Iface:
+        key = f"{dev_id}:{port}"
+        if key not in self.ifaces:
+            self.ifaces[key] = Iface("dhcp" if self.devices[dev_id].kind == "c" else "auto")
+        return self.ifaces[key]
+
+    def addr_of(self, ifc: tuple[str, int]) -> tuple[int, int] | None:
+        i = self.ifaces.get(f"{ifc[0]}:{ifc[1]}")
+        return i.addr if i else None
+
+    def addressed(self, dev_id: str) -> list[tuple[int, Iface]]:
+        dev = self.devices[dev_id]
+        if dev.kind == "s":
+            return []
+        return [(p, self.iface(dev_id, p)) for p in range(1, dev.nports + 1)
+                if self.iface(dev_id, p).addr]
+
+    def hosts_on(self, net: int) -> set[int]:
+        return {i.host for i in self.ifaces.values() if i.net == net and i.host is not None}
+
+    def resolve(self, addr: tuple[int, int]) -> tuple[str, int] | None:
+        if addr[1] == VIP_HOST and (owners := self.vip_owners(addr[0])):
+            return owners[0]
+        for key, i in self.ifaces.items():
+            if i.addr == addr:
+                d, p = key.split(":")
+                return d, int(p)
+        return None
+
+    def local_net(self, nic: tuple[str, int]) -> int | None:
+        """Network id already in use on this broadcast domain (routers' first)."""
+        seg = sorted(self.segment(*nic), key=lambda e: not self.is_router(e[0]))
+        return next((self.addr_of(e)[0] for e in seg if self.addr_of(e)), None)
+
+    def new_net(self) -> int:
+        used = {i.net for i in self.ifaces.values() if i.net is not None}
+        return next(n for n in range(1, 10**6) if n not in used)
+
+    def autoconf_routers(self) -> list[str]:
+        """Give every cabled router/gateway port an address on its local network,
+        opening a new network id if the segment doesn't have one yet."""
+        notes = []
+        for dev in self.sorted_devices():
+            if dev.kind not in "rg":
+                continue
+            for p in range(1, dev.nports + 1):
+                ifc = self.iface(dev.id, p)
+                if ifc.mode != "auto":
+                    continue
+                li = self.link_index(dev.id, p)
+                if li is None or self.links[li].control:
+                    ifc.clear()          # unplugged, or a control link: no data address
+                    continue
+                if not self.usable(self.links[li]):
+                    continue             # failed: keep the config for when it comes back
+                local = self.local_net((dev.id, p))
+                if ifc.addr and (local is None or local == ifc.net):
+                    continue
+                net = local if local is not None else self.new_net()
+                used = self.hosts_on(net)
+                ifc.net, ifc.gw, ifc.via = net, None, "auto"
+                ifc.host = next(h for h in range(1, HOST_MAX) if h not in used)
+                notes.append(f"{dev.id}:{dev.port_name(p)} → {fmt(ifc.addr)}")
+        return notes
+
+    def dhcp_server(self, client: tuple[str, int]) -> tuple[str, int] | None:
+        for e in self.segment(*client):
+            if self.is_router(e[0]) and e[0] not in self.dhcp_off and self.addr_of(e):
+                return e
+        return None
+
+    def _free_host(self, net: int, ifc: Iface) -> int:
+        used = self.hosts_on(net) - ({ifc.host} if ifc.net == net else set())
+        if ifc.net == net and ifc.host in POOL and ifc.host not in used:
+            return ifc.host        # keep the number we already had on this network
+        host = next((h for h in POOL if h not in used), None)
+        if host is None:
+            raise NetError(f"network {net} is full (no free 8-bit host numbers)")
+        return host
+
+    def lease(self, client: tuple[str, int]) -> tuple[str, tuple[str, int] | None]:
+        """DHCP for a client NIC (falls back to ad-hoc). Returns (outcome, server)."""
+        ifc = self.iface(*client)
+        server = self.dhcp_server(client)
+        if server is None:
+            self.adhoc(client)
+            return "adhoc", None
+        snet, _ = self.addr_of(server)
+        gw = self.expected_gw(server)
+        if ifc.via == "dhcp" and ifc.net == snet and ifc.gw == gw:
+            return "renew", server
+        ifc.host = self._free_host(snet, ifc)
+        ifc.net, ifc.gw, ifc.via = snet, gw, "dhcp"
+        return "lease", server
+
+    def expected_gw(self, server: tuple[str, int]) -> int:
+        """Gateway a DHCP server hands out: its own host, or its cluster's virtual one."""
+        return VIP_HOST if self.cluster_of(server[0]) else self.addr_of(server)[1]
+
+    def adhoc(self, nic: tuple[str, int]) -> None:
+        """Take an unused host number on the local network, no server involved."""
+        ifc = self.iface(*nic)
+        local = self.local_net(nic)
+        if ifc.via == "adhoc" and ifc.addr and local in (None, ifc.net):
+            return
+        net = local if local is not None else self.new_net()
+        ifc.host = self._free_host(net, ifc)
+        ifc.net, ifc.gw, ifc.via = net, None, "adhoc"
+
+    def reconcile(self, skip: frozenset[tuple[str, int]] = frozenset()) -> list[str]:
+        """Bring every address in line with the current cabling. Returns what changed.
+
+        STP runs first (it decides which cables forward). Router ports
+        autoconfigure; unplugged client NICs release; DHCP clients
+        (re)lease when a server is reachable, keep a lease when none is, and fall
+        back to ad-hoc when they have nothing. ``skip`` leaves some NICs alone
+        (the UI animates their DHCP exchange itself).
+        """
+        notes = self.stp_update()  # type: ignore[attr-defined]
+        notes += [f"addr {n}" for n in self.autoconf_routers()]
+        for d in self.sorted_devices():
+            if d.kind != "c":
+                continue
+            for p in range(1, d.nports + 1):
+                nic, ifc = (d.id, p), self.iface(d.id, p)
+                name = f"{d.id}:{d.port_name(p)}"
+                if self.link_index(d.id, p) is None:
+                    if ifc.mode in ("dhcp", "adhoc") and ifc.addr:
+                        notes.append(f"{name} link down: released {fmt(ifc.addr)}")
+                        ifc.clear()
+                    continue
+                if nic in skip:
+                    continue
+                old = ifc.addr
+                try:
+                    if ifc.mode == "adhoc":
+                        self.adhoc(nic)
+                    elif ifc.mode == "dhcp":
+                        server = self.dhcp_server(nic)
+                        if server is None:
+                            # Nobody to ask: keep a lease we hold, else go ad-hoc.
+                            if not ifc.addr or ifc.via == "adhoc":
+                                self.adhoc(nic)
+                        elif (ifc.via != "dhcp" or ifc.net != self.addr_of(server)[0]
+                              or ifc.gw != self.expected_gw(server)):
+                            self.lease(nic)
+                except NetError as e:
+                    notes.append(f"{name}: {e}")
+                if ifc.addr != old:
+                    notes.append(f"{name} → {fmt(ifc.addr)} via {ifc.via}")
+        return notes

bytesim/model/base.py

@@ -0,0 +1,57 @@
+"""State shared by every part of the network model, plus the basic lookups."""
+from __future__ import annotations
+
+from ..constants import KINDS, RANK
+from .types import Device, Iface, Link, NetError
+
+
+class NetworkBase:
+    """Holds the network's state. The mixins in this package add behaviour on top."""
+
+    def __init__(self) -> None:
+        self.devices: dict[str, Device] = {}
+        self.links: list[Link] = []
+        self.counters = {k: 0 for k in KINDS}
+        self.groups: dict[str, list[str]] = {}    # group -> member device ids / group names
+        self.ifaces: dict[str, Iface] = {}        # "c1:1" -> Iface
+        self.dhcp_off: set[str] = set()           # routers/gateways not serving DHCP
+        self.mac_tables: dict[str, dict[str, int]] = {}   # switch -> {mac: port}
+        self.clusters: dict[str, str] = {}        # HA cluster (a group of routers) -> split policy
+        self.notes: list[str] = []                # remarks from the last route() for the console
+        self.stp_off: set[str] = set()            # switches with spanning tree switched off
+        self.stp_priority: dict[str, int] = {}    # bridge priority (default 32768; lower = root)
+        self.stp_blocked: set[tuple[str, int]] = set()    # (switch, port) held blocking by STP
+        self.stp_roots: dict[str, str] = {}       # switch -> its area's root bridge
+        self.stp_root_ports: dict[str, int] = {}  # switch -> port toward the root
+        self.storming: set[str] = set()           # switches drowning in a broadcast storm
+        self.mac_flaps: dict[str, dict[str, set[int]]] = {}  # switch -> mac -> ports it flapped between
+
+    def get(self, dev_id: str) -> Device:
+        try:
+            return self.devices[dev_id.lower()]
+        except KeyError:
+            raise NetError(f"no such device: {dev_id}") from None
+
+    def sorted_devices(self) -> list[Device]:
+        return sorted(self.devices.values(), key=lambda d: (RANK[d.kind], d.num))
+
+    def link_on(self, dev_id: str, port: int) -> Link | None:
+        for l in self.links:
+            if (l.a == dev_id and l.pa == port) or (l.b == dev_id and l.pb == port):
+                return l
+        return None
+
+    def link_index(self, dev_id: str, port: int) -> int | None:
+        for i, l in enumerate(self.links):
+            if (l.a == dev_id and l.pa == port) or (l.b == dev_id and l.pb == port):
+                return i
+        return None
+
+    def free_port(self, dev: Device) -> int | None:
+        for p in range(1, dev.nports + 1):
+            if self.link_on(dev.id, p) is None:
+                return p
+        return None
+
+    def is_router(self, dev_id: str) -> bool:
+        return self.devices[dev_id].kind in "rg"

bytesim/model/cloning.py

@@ -0,0 +1,249 @@
+"""Cloning a group: its devices, nested groups and internal cables."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from ..constants import GROUP_NAME, RANK, REF
+from .base import NetworkBase
+from .types import Device, Iface, Link, NetError
+
+
+@dataclass
+class CloneResult:
+    group: str                          # the new top-level group
+    devices: dict[str, str]             # old device id -> new device id
+    groups: dict[str, str]              # old group name -> new group name
+    cables: int                         # internal cables copied
+    skipped: int                        # cables to the outside, not copied
+    rewired: int = 0                    # outside cables re-made onto new endpoints
+    moved: list[str] | None = None      # "r3:p6→p7": ports that couldn't be kept
+
+
+class CloningMixin(NetworkBase):
+    def next_group_name(self, base: str, reserved: frozenset[str] = frozenset()) -> str:
+        """A free group name like base: fab1 → fab2 (or fab3…), core → core-2."""
+        m = re.match(r"^(.*?)(\d+)$", base)
+        stem, n, sep = (m[1], int(m[2]), "") if m else (base, 1, "-")
+        while True:
+            n += 1
+            name = f"{stem}{sep}{n}"[-16:]
+            if (name not in self.groups and name not in self.devices and name not in reserved
+                    and not REF.match(name)):
+                return name
+
+    def endpoint_map(self, pairs: list[tuple[str, str]], group: str) -> dict[str, str]:
+        """Old outside endpoint → new one, from (old, new) pairs of groups or devices.
+
+        Group members are matched by position, so the two sides need the same size.
+        Neither side may be inside the group being cloned."""
+        inside = set(self.devices_in(group))  # type: ignore[attr-defined]
+
+        def expand(ref: str) -> list[str]:
+            ref = ref.lower()
+            if ref in self.groups:
+                return self.devices_in(ref)    # type: ignore[attr-defined]
+            if ref in self.devices:
+                return [ref]
+            raise NetError(f"{ref} is neither a group nor a device")
+
+        mapping: dict[str, str] = {}
+        for old, new in pairs:
+            a, b = expand(old), expand(new)
+            if len(a) != len(b):
+                raise NetError(f"{old} has {len(a)} devices but {new} has {len(b)}: they're matched one to one")
+            for x, y in zip(a, b):
+                if x in inside or y in inside:
+                    raise NetError(f"{x if x in inside else y} is inside {group}: endpoints must be outside it")
+                if x in mapping:
+                    raise NetError(f"{x} is listed twice")
+                if self.devices[x].kind != self.devices[y].kind:
+                    raise NetError(f"{x} is a {self.devices[x].name} but {y} is a {self.devices[y].name}")
+                mapping[x] = y
+        return mapping
+
+    def clone_group(self, name: str, new_name: str | None = None, dx: int = 0, dy: int = 0,
+                    rewire: list[tuple[str, str]] | None = None) -> CloneResult:
+        """Copy a group: every device in it (nested groups too), every cable with
+        both ends inside, the group tree, cluster policies, STP and DHCP-server
+        settings. Cables to the outside are not copied, unless ``rewire`` says where
+        they go: pairs of (old endpoint, new endpoint), groups or devices, e.g.
+        [("rfab1", "rfab2"), ("rfab2", "rfab3")]. A cable from the group to a device
+        of the old endpoint is re-made from the copy to the matching device of the
+        new one (same port number there if it's free, else the first free one).
+
+        Copies start healthy (nothing failed) and without addresses: interfaces keep
+        their mode, except static ones, which would clash, so they become DHCP
+        (computers) or automatic (routers). The new group joins the original's
+        parent. dx/dy shift the copies' positions.
+        """
+        if name not in self.groups:
+            raise NetError(f"no such group: {name}")
+        if new_name is not None:
+            if not GROUP_NAME.match(new_name) or REF.match(new_name):
+                raise NetError(f"bad group name {new_name!r}: start with a letter and must not look like a device id")
+            if new_name in self.groups or new_name in self.devices:
+                raise NetError(f"{new_name} already exists")
+
+        members = self.devices_in(name)       # type: ignore[attr-defined]
+        inside = set(members)
+        ends = self.endpoint_map(rewire or [], name)
+
+        # Check room on every new endpoint before creating anything.
+        outside = [l for l in self.links if (l.a in inside) != (l.b in inside)]
+        need: dict[str, int] = {}
+        for l in outside:
+            far = l.b if l.a in inside else l.a
+            if far in ends:
+                need[ends[far]] = need.get(ends[far], 0) + 1
+        for dev, n in need.items():
+            free = sum(1 for p in range(1, self.devices[dev].nports + 1) if self.link_on(dev, p) is None)
+            if free < n:
+                d = self.devices[dev]
+                raise NetError(f"{dev} needs {n} free port{'s' if n != 1 else ''} for the copy but has {free} "
+                               f"(try `ports {dev} {d.nports + n - free}`)")
+
+        # Devices, in a stable order so new numbers follow the old ones.
+        dev_map: dict[str, str] = {}
+        for old in sorted(members, key=lambda d: (RANK[d[0]], int(d[1:]))):
+            src: Device = self.devices[old]
+            new: Device = self.add(src.kind, src.nports)  # type: ignore[attr-defined]
+            new.x, new.y = src.x + dx, src.y + dy
+            dev_map[old] = new.id
+
+        # Internal cables keep their ports and roles. Outside ones are re-made onto
+        # their new endpoint if one was given, else left behind.
+        cables = skipped = rewired = 0
+        moved: list[str] = []
+        for l in list(self.links):
+            if l.a in inside and l.b in inside:
+                self.links.append(Link(dev_map[l.a], l.pa, dev_map[l.b], l.pb, l.role))
+                cables += 1
+            elif l.a in inside or l.b in inside:
+                near, near_port = (l.a, l.pa) if l.a in inside else (l.b, l.pb)
+                far, far_port = (l.b, l.pb) if l.a in inside else (l.a, l.pa)
+                if far not in ends:
+                    skipped += 1
+                    continue
+                target = ends[far]
+                port = self._port_like(target, far_port)
+                if port != far_port:
+                    moved.append(f"{target}:p{far_port}→p{port}")
+                self.links.append(Link(dev_map[near], near_port, target, port, l.role))
+                rewired += 1
+
+        # The group tree, depth first, so every nested group gets a fresh name.
+        group_map: dict[str, str] = {}
+
+        def copy(g: str, forced: str | None) -> str:
+            new_g = forced or self.next_group_name(g)
+            self.groups[new_g] = []           # reserve the name before naming children
+            group_map[g] = new_g
+            self.groups[new_g] = [copy(m, None) if m in self.groups else dev_map[m]
+                                  for m in list(self.groups[g])]
+            if g in self.clusters:
+                self.clusters[new_g] = self.clusters[g]
+            return new_g
+
+        top = copy(name, new_name)
+        parent = self.parent_of(name)         # type: ignore[attr-defined]
+        if parent is not None:
+            siblings = self.groups[parent]
+            siblings.insert(siblings.index(name) + 1, top)
+
+        # Per-device settings travel with the copy; addresses don't.
+        for old, new in dev_map.items():
+            if old in self.stp_off:
+                self.stp_off.add(new)
+            if old in self.stp_priority:
+                self.stp_priority[new] = self.stp_priority[old]
+            if old in self.dhcp_off:
+                self.dhcp_off.add(new)
+            for p in range(1, self.devices[old].nports + 1):
+                ifc = self.ifaces.get(f"{old}:{p}")
+                if ifc is None:
+                    continue
+                mode = ifc.mode
+                if mode == "static":
+                    mode = "dhcp" if self.devices[old].kind == "c" else "auto"
+                self.ifaces[f"{new}:{p}"] = Iface(mode)
+        return CloneResult(top, dev_map, group_map, cables, skipped, rewired, moved)
+
+    def _port_like(self, dev: str, port: int) -> int:
+        """The same port number if it's free on dev, else dev's first free port."""
+        if port <= self.devices[dev].nports and self.link_on(dev, port) is None:
+            return port
+        free = self.free_port(self.devices[dev])
+        if free is None:
+            raise NetError(f"{dev} has no free ports")
+        return free
+
+    def copy_cabling(self, src: str, dst: str, pairs: list[tuple[str, str]]) -> CablingResult:
+        """Give group dst the same outside cabling src has to some endpoints, but onto others.
+
+        ``pairs`` are (old endpoint, new endpoint), groups or devices: for every cable
+        from a device of src to a device of an old endpoint, a cable is made from the
+        matching device of dst to the matching device of the new endpoint. Matching
+        is by position, so src and dst (and each endpoint pair) need the same size
+        and kinds. No devices are created and src's internal cables are not copied.
+        Cables dst already has are counted, so running it twice changes nothing.
+        Ports: the same number as the original where free, else the first free one.
+        Everything is checked before any cable is made.
+        """
+        for g in (src, dst):
+            if g not in self.groups:
+                raise NetError(f"no such group: {g}")
+        a, b = self.devices_in(src), self.devices_in(dst)   # type: ignore[attr-defined]
+        if len(a) != len(b):
+            raise NetError(f"{src} has {len(a)} devices but {dst} has {len(b)}: they're matched one to one")
+        match: dict[str, str] = {}
+        for x, y in zip(a, b):
+            if self.devices[x].kind != self.devices[y].kind:
+                raise NetError(f"{x} is a {self.devices[x].name} but {y} is a {self.devices[y].name}")
+            match[x] = y
+        ends = self.endpoint_map(pairs, src)
+        clash = set(ends.values()) & set(b)
+        if clash:
+            raise NetError(f"{sorted(clash)[0]} is inside {dst}: endpoints must be outside it")
+
+        # The pattern: how many cables (per role) join each src device to each old endpoint.
+        wanted: dict[tuple[str, str, str], list[tuple[int, int]]] = {}
+        for l in self.links:
+            for near, far in ((l.a, l.b), (l.b, l.a)):
+                if near in match and far in ends:
+                    key = (match[near], ends[far], l.role)
+                    wanted.setdefault(key, []).append((l.port_of(near), l.port_of(far)))
+        made: list[tuple[str, int, str, int, str]] = []
+        already = 0
+        for (x, y, role), ports in wanted.items():
+            have = sum(1 for l in self.links if l.role == role and {l.a, l.b} == {x, y})
+            already += min(have, len(ports))
+            for px, py in ports[have:]:
+                made.append((x, px, y, py, role))
+
+        need: dict[str, int] = {}
+        for x, _, y, _, _ in made:
+            need[x] = need.get(x, 0) + 1
+            need[y] = need.get(y, 0) + 1
+        for dev, n in need.items():
+            free = sum(1 for p in range(1, self.devices[dev].nports + 1) if self.link_on(dev, p) is None)
+            if free < n:
+                nports = self.devices[dev].nports
+                raise NetError(f"{dev} needs {n} free port{'s' if n != 1 else ''} but has {free} "
+                               f"(try `ports {dev} {nports + n - free}`)")
+
+        moved: list[str] = []
+        for x, px, y, py, role in made:
+            qx, qy = self._port_like(x, px), self._port_like(y, py)
+            moved += [f"{d}:p{p}→p{q}" for d, p, q in ((x, px, qx), (y, py, qy)) if p != q]
+            self.links.append(Link(x, qx, y, qy, role))
+        if made:
+            self.mac_tables = {}
+        return CablingResult(len(made), already, moved)
+
+
+@dataclass
+class CablingResult:
+    made: int                           # cables created
+    already: int                        # cables the pattern wanted that already existed
+    moved: list[str]                    # "r3:p6→p7": ports that couldn't mirror the original