bytesim 0.1.0__py3-none-any.whl

bytesim/model/naming.py

@@ -0,0 +1,114 @@
+"""Renumbering devices in traversal order (BFS or DFS over the cabling)."""
+from __future__ import annotations
+
+from collections import deque
+
+from ..constants import KINDS, RANK
+from .base import NetworkBase
+from .types import NetError
+
+ORDERS = ("bfs", "dfs")
+
+
+class NamingMixin(NetworkBase):
+    def default_root(self) -> str | None:
+        """Where a traversal starts unless told otherwise: the first gateway,
+        else the first router, switch, then computer."""
+        devs = self.sorted_devices()
+        return devs[0].id if devs else None
+
+    def _neighbours(self, dev_id: str) -> list[str]:
+        """Devices cabled to dev_id, in the order of dev_id's own ports.
+
+        Naming follows the physical cabling, so every cable counts (failed or
+        control cables too) and computers are walked through like anything else.
+        """
+        ends = sorted((l.port_of(dev_id), l.other(dev_id)[0]) for l in self.links if l.touches(dev_id))
+        return [other for _, other in ends]
+
+    def traversal(self, order: str, root: str | None = None) -> list[str]:
+        """Every device id, in the order a BFS or DFS from root first reaches it.
+
+        Neighbours are taken in port order. Devices the root can't reach are
+        picked up by starting again from the next one in the old (kind, number)
+        order, so the result always covers the whole network.
+        """
+        if order not in ORDERS:
+            raise NetError(f"order must be one of: {', '.join(ORDERS)}")
+        root = self.get(root).id if root else self.default_root()
+        if root is None:
+            return []
+        starts = [root] + [d.id for d in self.sorted_devices() if d.id != root]
+        seen: set[str] = set()
+        out: list[str] = []
+        for start in starts:
+            if start in seen:
+                continue
+            if order == "bfs":
+                seen.add(start)
+                q = deque([start])
+                while q:
+                    u = q.popleft()
+                    out.append(u)
+                    for v in self._neighbours(u):
+                        if v not in seen:
+                            seen.add(v)
+                            q.append(v)
+            else:
+                # Iterative pre-order DFS: visit, then go deep through the first
+                # unvisited neighbour before trying the next port.
+                seen.add(start)
+                out.append(start)
+                stack = [iter(self._neighbours(start))]
+                while stack:
+                    v = next(stack[-1], None)
+                    if v is None:
+                        stack.pop()
+                    elif v not in seen:
+                        seen.add(v)
+                        out.append(v)
+                        stack.append(iter(self._neighbours(v)))
+        return out
+
+    def renumber(self, order: str, root: str | None = None) -> dict[str, str]:
+        """Renumber each kind 1..n in traversal order. Returns {old id: new id}
+        for every device whose id changed.
+
+        Cables, groups, addresses and DHCP settings follow their device. Switch
+        MAC tables are cleared, since MACs are derived from device ids. Counters
+        are reset so the next new device of each kind gets n+1.
+        """
+        visit = self.traversal(order, root)
+        counts = {k: 0 for k in KINDS}
+        new_num: dict[str, int] = {}
+        for did in visit:
+            dev = self.devices[did]
+            counts[dev.kind] += 1
+            new_num[did] = counts[dev.kind]
+        mapping = {did: f"{self.devices[did].kind}{n}" for did, n in new_num.items()}
+        changed = {old: new for old, new in mapping.items() if old != new}
+        self.counters = counts
+        if not changed:
+            return {}
+
+        def ren(did: str) -> str:
+            return mapping.get(did, did)
+
+        for did, n in new_num.items():
+            self.devices[did].num = n
+        self.devices = {d.id: d for d in sorted(self.devices.values(), key=lambda d: (RANK[d.kind], d.num))}
+        for l in self.links:
+            l.a, l.b = ren(l.a), ren(l.b)
+        self.groups = {g: [ren(m) if m in mapping else m for m in ms] for g, ms in self.groups.items()}
+        self.ifaces = {f"{ren(k.split(':')[0])}:{k.split(':')[1]}": v for k, v in self.ifaces.items()}
+        self.dhcp_off = {ren(d) for d in self.dhcp_off}
+        self.stp_off = {ren(d) for d in self.stp_off}
+        self.stp_priority = {ren(d): v for d, v in self.stp_priority.items()}
+        self.stp_blocked = {(ren(d), p) for d, p in self.stp_blocked}
+        self.stp_roots = {ren(d): ren(r) for d, r in self.stp_roots.items()}
+        self.stp_root_ports = {ren(d): p for d, p in self.stp_root_ports.items()}
+        self.storming = {ren(d) for d in self.storming}
+        self.mac_flaps = {ren(d): f for d, f in self.mac_flaps.items()}
+        self.mac_tables = {}
+        self.notes = []
+        return changed

bytesim/model/network.py

@@ -0,0 +1,138 @@
+"""The Network: every mixin combined, plus device/cable editing and JSON persistence."""
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+
+from ..constants import KINDS, MAX_PORTS
+from .addressing import AddressingMixin
+from .cloning import CloningMixin
+from .groups import GroupsMixin
+from .ha import HAMixin
+from .layer2 import Layer2Mixin
+from .layout import LayoutMixin
+from .naming import NamingMixin
+from .routing import RoutingMixin
+from .stp import SpanningTreeMixin
+from .types import Device, Iface, Link, NetError
+
+
+class Network(GroupsMixin, Layer2Mixin, AddressingMixin, RoutingMixin, HAMixin, LayoutMixin,
+              NamingMixin, SpanningTreeMixin, CloningMixin):
+    """A simulated network: devices, cables, groups, addresses and HA clusters.
+
+    Pure model, no UI: everything here can be driven from Python or tests.
+    """
+
+    def add(self, kind: str, nports: int | None = None) -> Device:
+        nports = KINDS[kind][1] if nports is None else nports
+        if not 1 <= nports <= MAX_PORTS:
+            raise NetError(f"port count must be 1..{MAX_PORTS}")
+        self.counters[kind] += 1
+        dev = Device(kind, self.counters[kind], nports)
+        self.devices[dev.id] = dev
+        return dev
+
+    def remove(self, dev_id: str) -> int:
+        dev = self.get(dev_id)
+        before = len(self.links)
+        self.links = [l for l in self.links if not l.touches(dev.id)]
+        del self.devices[dev.id]
+        self._drop_from_groups([dev.id])
+        for key in [k for k in self.ifaces if k.split(":")[0] == dev.id]:
+            del self.ifaces[key]
+        self.dhcp_off.discard(dev.id)
+        self.stp_off.discard(dev.id)
+        self.stp_priority.pop(dev.id, None)
+        self.storming.discard(dev.id)
+        self.mac_flaps.pop(dev.id, None)
+        self.mac_tables = {}
+        return before - len(self.links)
+
+    def resize(self, dev_id: str, nports: int) -> None:
+        dev = self.get(dev_id)
+        if not 1 <= nports <= MAX_PORTS:
+            raise NetError(f"port count must be 1..{MAX_PORTS}")
+        used = [l.port_of(dev.id) for l in self.links if l.touches(dev.id)]
+        if used and max(used) > nports:
+            raise NetError(f"{dev.id} port {max(used)} is in use; unlink it first")
+        dev.nports = nports
+        for p in range(nports + 1, MAX_PORTS + 1):
+            self.ifaces.pop(f"{dev.id}:{p}", None)
+
+    def connect(self, a: str, pa: int | None, b: str, pb: int | None, role: str = "data") -> Link:
+        da, db = self.get(a), self.get(b)
+        if da is db:
+            raise NetError("can't cable a device to itself")
+        ports = []
+        for dev, p in ((da, pa), (db, pb)):
+            if p is None:
+                p = self.free_port(dev)
+                if p is None:
+                    raise NetError(f"{dev.id} has no free ports (try `ports {dev.id} {dev.nports + 1}`)")
+            elif not 1 <= p <= dev.nports:
+                raise NetError(f"{dev.id} has no port {p} (it has {dev.nports})")
+            elif (l := self.link_on(dev.id, p)) is not None:
+                o, op = l.other(dev.id)
+                raise NetError(f"{dev.id}:{dev.port_name(p)} already cabled to {o}")
+            ports.append(p)
+        link = Link(da.id, ports[0], db.id, ports[1], role)
+        self.links.append(link)
+        return link
+
+    def disconnect(self, a: str, pa: int | None, b: str | None) -> int:
+        da = self.get(a)
+        db = self.get(b) if b else None
+
+        def match(l: Link) -> bool:
+            if not l.touches(da.id):
+                return False
+            if pa is not None and l.port_of(da.id) != pa:
+                return False
+            return db is None or l.other(da.id)[0] == db.id
+
+        before = len(self.links)
+        self.links = [l for l in self.links if not match(l)]
+        if len(self.links) != before:
+            self.mac_tables = {}      # topology changed: switches forget what they learned
+        return before - len(self.links)
+
+
+    # ---- persistence ---------------------------------------------------
+    def to_json(self) -> str:
+        return json.dumps({
+            "counters": self.counters,
+            "devices": [asdict(d) for d in self.devices.values()],
+            "links": [asdict(l) for l in self.links],
+            "groups": self.groups,
+            "ifaces": {k: asdict(v) for k, v in self.ifaces.items()},
+            "dhcp_off": sorted(self.dhcp_off),
+            "clusters": self.clusters,
+            "stp_off": sorted(self.stp_off, key=lambda d: (d[0], int(d[1:]))),
+            "stp_priority": self.stp_priority,
+        }, indent=2)
+
+    @classmethod
+    def from_json(cls, raw: str) -> "Network":
+        data = json.loads(raw)
+        net = cls()
+        net.counters.update(data["counters"])
+        for d in data["devices"]:
+            dev = Device(**d)
+            net.devices[dev.id] = dev
+        net.links = [Link(**l) for l in data["links"]]
+        names = set(data.get("groups", {}))
+        net.groups = {g: [d for d in ids if d in net.devices or d in names]
+                      for g, ids in data.get("groups", {}).items()}
+        net._drop_from_groups([])
+        for k, v in data.get("ifaces", {}).items():
+            if k.split(":")[0] in net.devices:
+                try:
+                    net.ifaces[k] = Iface(**v)
+                except TypeError:
+                    pass          # address from an older format: re-learned on load
+        net.dhcp_off = set(data.get("dhcp_off", [])) & set(net.devices)
+        net.clusters = {c: p for c, p in data.get("clusters", {}).items() if c in net.groups}
+        net.stp_off = set(data.get("stp_off", [])) & set(net.devices)
+        net.stp_priority = {d: int(v) for d, v in data.get("stp_priority", {}).items() if d in net.devices}
+        return net

bytesim/model/routing.py

@@ -0,0 +1,117 @@
+"""Forwarding: hosts deliver locally or via their gateway; routers find the cheapest path."""
+from __future__ import annotations
+
+import heapq
+
+from ..constants import VIP_HOST
+from .base import NetworkBase
+from .types import Leg, NetError, fmt
+
+
+class RoutingMixin(NetworkBase):
+    def route(self, src: str, dst: tuple[str, int] | None) -> list[Leg]:
+        """Path from a device to an interface (or to the internet if dst is None).
+
+        Each leg is one layer-2 hop between addressed interfaces. A host delivers
+        directly on its own network, otherwise via its gateway; routers know every
+        network of every router they share a network with (a toy IGP).
+        """
+        dev = self.devices[src]
+        if dev.kind == "s":
+            raise NetError(f"{src} is a switch: layer 2 only, it has no address to send from")
+        if not dev.up:
+            raise NetError(f"{src} is down")
+        if dst and dst[0] == src:
+            return []
+        dst_addr = self.addr_of(dst) if dst else None
+        if dev.kind in "rg":
+            return self._router_route(src, dst, dst_addr)
+        nics = self.addressed(src)
+        if not nics:
+            raise NetError(f"{src} has no address (try: dhcp {src})")
+        if dst:
+            for p, ifc in nics:
+                if ifc.net == dst_addr[0] and dst in self.segment(src, p):
+                    return [((src, p), dst, self.l2path((src, p), dst))]
+        problems = []
+        for p, ifc in nics:
+            if ifc.gw is None:
+                continue
+            seg = self.segment(src, p)
+            if ifc.gw == VIP_HOST:
+                owners = self.vip_owners(ifc.net)
+                here = [o for o in owners if o in seg]
+                if len(owners) > 1:
+                    self.notes.append(f"⚠ virtual gateway {fmt((ifc.net, VIP_HOST))} claimed by "
+                                      f"{' and '.join(o[0] for o in owners)} (ARP conflict: "
+                                      f"{src} happens to reach {here[0][0] if here else 'neither'})")
+                elif here:
+                    self.notes.append(f"gateway {fmt((ifc.net, VIP_HOST))} is virtual, "
+                                      f"owned by {here[0][0]} (active)")
+                gw = here[0] if here else None
+            else:
+                gw = next((e for e in seg if self.addr_of(e) == (ifc.net, ifc.gw)), None)
+            if gw is None:
+                problems.append(f"gateway {fmt((ifc.net, ifc.gw))} unreachable from {src}:{dev.port_name(p)}")
+                continue
+            try:
+                return [((src, p), gw, self.l2path((src, p), gw))] + self._router_route(gw[0], dst, dst_addr)
+            except NetError as e:
+                problems.append(str(e))
+        if problems:
+            raise NetError("; ".join(problems))
+        where = f"network {dst_addr[0]}" if dst_addr else "the internet"
+        raise NetError(f"{where} isn't local to {src} and {src} has no gateway")
+
+    def _router_route(self, start: str, dst: tuple[str, int] | None,
+                      dst_addr: tuple[int, int] | None) -> list[Leg]:
+        """Cheapest path in cable hops from a router to dst (or to any gateway).
+
+        Routers are nodes; two routers are adjacent when they share a network.
+        Counting cables rather than routers lets a direct fabric link win over
+        a detour back through a switched network."""
+        best: dict[str, int] = {start: 0}
+        prev: dict[str, tuple[str, Leg] | None] = {start: None}
+        heap: list[tuple[int, int, str, Leg | None]] = [(0, 0, start, None)]
+        tick = 0
+        done: set[str] = set()
+
+        def legs_to(u: str) -> list[Leg]:
+            out = []
+            while prev[u] is not None:
+                parent, leg = prev[u]
+                out.append(leg)
+                u = parent
+            return out[::-1]
+
+        while heap:
+            cost, _, u, final = heapq.heappop(heap)
+            if final is not None:                       # popped the destination itself
+                return legs_to(u) + [final]
+            if u in done:
+                continue
+            done.add(u)
+            if dst is None and self.devices[u].kind == "g":
+                return legs_to(u)
+            if dst is not None and dst[0] == u:
+                return legs_to(u)
+            for p, ifc in self.addressed(u):
+                seg = self.segment(u, p)
+                if dst is not None and dst in seg and ifc.net == dst_addr[0]:
+                    path = self.l2path((u, p), dst)
+                    tick += 1
+                    heapq.heappush(heap, (cost + len(path) - 1, tick, u, ((u, p), dst, path)))
+                for e in seg:
+                    a = self.addr_of(e)
+                    if not (self.is_router(e[0]) and a and a[0] == ifc.net) or e[0] in done:
+                        continue
+                    path = self.l2path((u, p), e)
+                    c = cost + len(path) - 1
+                    if c < best.get(e[0], 10**9):
+                        best[e[0]] = c
+                        prev[e[0]] = (u, ((u, p), e, path))
+                        tick += 1
+                        heapq.heappush(heap, (c, tick, e[0], None))
+        if dst is None:
+            raise NetError(f"no route from {start} to a gateway (internet)")
+        raise NetError(f"no route to network {dst_addr[0]} from {start}")

bytesim/model/stp.py

@@ -0,0 +1,315 @@
+"""Switching loops: spanning tree (STP), loop detection, flooding, broadcast storms.
+
+Switches run STP unless it is switched off for them. STP picks a root bridge
+in every switched area, keeps the shortest path tree to it, and blocks one end
+of every other switch-to-switch cable, so no loop forwards frames. A loop with
+no STP switch able to block it stays live: the next broadcast into it circles
+forever and multiplies. That is a broadcast storm, and it saturates every
+cable it touches until the loop is broken.
+"""
+from __future__ import annotations
+
+from collections import Counter, deque
+from dataclasses import dataclass, field
+
+from ..constants import RANK
+from .base import NetworkBase
+from .types import Link
+
+DEFAULT_PRIORITY = 32768
+
+
+@dataclass
+class Flood:
+    """What happened to one broadcast frame, generation by generation."""
+    source: tuple[str, int]
+    generations: list[dict[tuple[int, str], int]] = field(default_factory=list)  # (link, arriving at) -> copies
+    delivered: Counter = field(default_factory=Counter)      # (device, port) -> copies received
+    storm: bool = False
+    storm_switches: set[str] = field(default_factory=set)
+    storm_links: set[int] = field(default_factory=set)
+    flaps: dict[str, set[int]] = field(default_factory=dict)  # switch -> ports the source MAC arrived on
+
+    @property
+    def totals(self) -> list[int]:
+        return [sum(g.values()) for g in self.generations]
+
+
+class SpanningTreeMixin(NetworkBase):
+    # ---- configuration -------------------------------------------------
+    def stp_enabled(self, switch: str) -> bool:
+        return switch not in self.stp_off
+
+    def bridge_id(self, switch: str) -> tuple[int, int, int]:
+        """Lower wins the root election: priority, then kind and number."""
+        d = self.devices[switch]
+        return self.stp_priority.get(switch, DEFAULT_PRIORITY), RANK[d.kind], d.num
+
+    # ---- the switch-to-switch graph -------------------------------------
+    def _carries(self, l: Link, honor_stp: bool) -> bool:
+        """Could this cable forward frames, storms aside? (STP blocks optional.)"""
+        if not (l.up and not l.control and self.devices[l.a].up and self.devices[l.b].up):
+            return False
+        return not (honor_stp and ((l.a, l.pa) in self.stp_blocked or (l.b, l.pb) in self.stp_blocked))
+
+    def _trunks(self, honor_stp: bool) -> list[int]:
+        """Indices of cables joining two switches that can forward frames."""
+        return [i for i, l in enumerate(self.links)
+                if self.devices[l.a].kind == "s" and self.devices[l.b].kind == "s"
+                and self._carries(l, honor_stp)]
+
+    def _areas(self, trunks: list[int]) -> list[set[str]]:
+        """Switches grouped into areas joined by the given trunks."""
+        adj: dict[str, set[str]] = {d.id: set() for d in self.devices.values() if d.kind == "s"}
+        for i in trunks:
+            l = self.links[i]
+            adj[l.a].add(l.b)
+            adj[l.b].add(l.a)
+        out, seen = [], set()
+        for s in sorted(adj, key=lambda s: self.bridge_id(s)):
+            if s in seen:
+                continue
+            comp, q = {s}, deque([s])
+            while q:
+                for v in adj[q.popleft()]:
+                    if v not in comp:
+                        comp.add(v)
+                        q.append(v)
+            seen |= comp
+            out.append(comp)
+        return out
+
+    def loop_links(self, honor_stp: bool = True) -> set[int]:
+        """Trunks that lie on a loop (any cable that isn't a bridge in the graph theory sense)."""
+        trunks = self._trunks(honor_stp)
+        adj: dict[str, list[tuple[str, int]]] = {}
+        for i in trunks:
+            l = self.links[i]
+            adj.setdefault(l.a, []).append((l.b, i))
+            adj.setdefault(l.b, []).append((l.a, i))
+        disc: dict[str, int] = {}
+        low: dict[str, int] = {}
+        bridges: set[int] = set()
+        timer = [0]
+
+        def dfs(u: str, via: int) -> None:            # Tarjan's bridge finding (multigraph-safe)
+            disc[u] = low[u] = timer[0]
+            timer[0] += 1
+            for v, i in adj.get(u, []):
+                if i == via:
+                    continue
+                if v in disc:
+                    low[u] = min(low[u], disc[v])
+                else:
+                    dfs(v, i)
+                    low[u] = min(low[u], low[v])
+                    if low[v] > disc[u]:
+                        bridges.add(i)
+
+        for s in adj:
+            if s not in disc:
+                dfs(s, -1)
+        return set(trunks) - bridges
+
+    # ---- spanning tree ---------------------------------------------------
+    def stp_compute(self) -> tuple[set[tuple[str, int]], dict[str, str], dict[str, int]]:
+        """Blocked ports, each switch's root bridge, and each switch's root port.
+
+        Per switched area, the root is the STP switch with the lowest bridge id.
+        Switches without STP pass STP frames straight through (as real ones do),
+        so they can't block anything but don't hide loops either. Cables with
+        no STP end always forward; every other cable is added nearest-the-root
+        first, and one that would close a loop is blocked at its end farther
+        from the root (or its only STP end). What's left is loop-free except
+        for loops made entirely of non-STP switches, which nothing can break.
+        """
+        trunks = self._trunks(honor_stp=False)
+        blocked: set[tuple[str, int]] = set()
+        roots: dict[str, str] = {}
+        root_ports: dict[str, int] = {}
+        for area in self._areas(trunks):
+            bridges = [s for s in area if self.stp_enabled(s)]
+            if not bridges:
+                continue
+            root = min(bridges, key=self.bridge_id)
+            for s in area:
+                roots[s] = root
+            here = [i for i in trunks if self.links[i].a in area]
+            cost = self._hops_from(root, here)
+
+            parent = {s: s for s in area}           # union-find over what forwards
+
+            def find(s: str) -> str:
+                while parent[s] != s:
+                    parent[s] = parent[parent[s]]
+                    s = parent[s]
+                return s
+
+            def rank(i: int) -> tuple:
+                l = self.links[i]
+                near, far = sorted([(l.a, l.pa), (l.b, l.pb)],
+                                   key=lambda e: (cost[e[0]], self.bridge_id(e[0])))
+                return (cost[far[0]], cost[near[0]], self.bridge_id(near[0]), near[1])
+
+            forced = [i for i in here if not (self.stp_enabled(self.links[i].a)
+                                              or self.stp_enabled(self.links[i].b))]
+            for i in forced + sorted((i for i in here if i not in forced), key=rank):
+                l = self.links[i]
+                ra, rb = find(l.a), find(l.b)
+                if ra != rb:
+                    parent[ra] = rb
+                    continue
+                if i in forced:
+                    continue                         # an unbreakable loop: no STP end
+                ends = sorted([(l.a, l.pa), (l.b, l.pb)],
+                              key=lambda e: (cost[e[0]], self.bridge_id(e[0])), reverse=True)
+                blocked.add(next(e for e in ends if self.stp_enabled(e[0])))
+            # Root port: the forwarding cable that leads one hop closer to the root.
+            fwd = [i for i in here if (self.links[i].a, self.links[i].pa) not in blocked
+                   and (self.links[i].b, self.links[i].pb) not in blocked]
+            dist = self._hops_from(root, fwd)
+            for s in area:
+                if s == root or not self.stp_enabled(s) or s not in dist:
+                    continue
+                best = min(((self.bridge_id(self.links[i].other(s)[0]), self.links[i].port_of(s))
+                            for i in fwd if self.links[i].touches(s)
+                            and dist.get(self.links[i].other(s)[0], 10**9) < dist[s]), default=None)
+                if best:
+                    root_ports[s] = best[1]
+        return blocked, roots, root_ports
+
+    def _hops_from(self, start: str, trunks: list[int]) -> dict[str, int]:
+        dist = {start: 0}
+        q = deque([start])
+        while q:
+            u = q.popleft()
+            for i in trunks:
+                l = self.links[i]
+                if l.touches(u) and (v := l.other(u)[0]) not in dist:
+                    dist[v] = dist[u] + 1
+                    q.append(v)
+        return dist
+
+    def port_role(self, switch: str, port: int) -> str:
+        """root / designated / blocking / edge, or '' (unplugged, or STP off)."""
+        li = self.link_index(switch, port)
+        if li is None:
+            return ""
+        if (switch, port) in self.stp_blocked:
+            return "blocking"
+        if self.devices[self.links[li].other(switch)[0]].kind != "s":
+            return "edge"
+        if not self.stp_enabled(switch) or switch not in self.stp_roots:
+            return ""
+        return "root" if self.stp_root_ports.get(switch) == port else "designated"
+
+    def stp_update(self) -> list[str]:
+        """Re-run STP and end storms whose loop is gone. Returns notes on what changed."""
+        notes = []
+        before = self.stp_blocked
+        self.stp_blocked, self.stp_roots, self.stp_root_ports = self.stp_compute()
+        for sw, p in sorted(before - self.stp_blocked):
+            li = self.link_index(sw, p) if sw in self.devices else None
+            if li is not None and self._carries(self.links[li], honor_stp=False):
+                notes.append(f"STP {sw}:p{p} blocking → forwarding")
+        for sw, p in sorted(self.stp_blocked - before):
+            notes.append(f"STP {sw}:p{p} → blocking")
+        if self.storming:
+            # A storm lives as long as its area still has a forwarding loop.
+            looped = {d for i in self.loop_links(honor_stp=True)
+                      for d in (self.links[i].a, self.links[i].b)}
+            still: set[str] = set()
+            for area in self._areas(self._trunks(honor_stp=True)):
+                if area & self.storming and area & looped:
+                    still |= area & self.storming
+            ended = self.storming - still
+            if ended:
+                self.storming = still
+                for s in ended:
+                    self.mac_flaps.pop(s, None)
+                notes.append(f"broadcast storm over: {' '.join(sorted(ended, key=self.bridge_id))} "
+                             f"(loop broken)")
+        return notes
+
+    # ---- flooding ----------------------------------------------------------
+    def flood(self, src: tuple[str, int]) -> Flood:
+        """Send one broadcast frame out of an interface and follow every copy.
+
+        Switches copy it out of every forwarding port except the one it came in
+        on; anything else just receives it. Copies are counted exactly per
+        (cable, direction), so even an exponential storm stays cheap to model.
+        A loop-free area empties within as many hops as there are cables; if
+        frames are still alive after that, they are circling: a storm.
+        """
+        out = Flood(source=src)
+        li0 = self.link_index(*src)
+        if li0 is None:
+            return out
+
+        def ok(l: Link) -> bool:
+            return (self._carries(l, honor_stp=True)
+                    and l.a not in self.storming and l.b not in self.storming)
+
+        if not ok(self.links[li0]):
+            return out
+        state: Counter = Counter({(li0, self.links[li0].other(src[0])[0]): 1})
+        for _ in range(len(self.links) + 2):
+            out.generations.append(dict(state))
+            nxt: Counter = Counter()
+            for (li, dev), n in state.items():
+                port = self.links[li].port_of(dev)
+                if self.devices[dev].kind != "s":
+                    out.delivered[(dev, port)] += n
+                    continue
+                out.flaps.setdefault(dev, set()).add(port)
+                for lj, l in enumerate(self.links):
+                    if lj != li and l.touches(dev) and ok(l):
+                        nxt[(lj, l.other(dev)[0])] += n
+            if not nxt:
+                break
+            state = nxt
+        else:
+            out.storm = True
+            # Everything the circling frames touched over the last lap (a loop can't
+            # be longer than the number of cables), not just where they are now.
+            lap = out.generations[-(len(self.links) + 1):] + [dict(state)]
+            out.storm_links = {li for gen in lap for li, _ in gen}
+            out.storm_switches = {d for li in out.storm_links for d in (self.links[li].a, self.links[li].b)
+                                  if self.devices[d].kind == "s"}
+        out.flaps = {s: ps for s, ps in out.flaps.items() if len(ps) > 1}
+        return out
+
+    def start_storm(self, flood: Flood) -> None:
+        """Mark a storming area: its cables carry nothing but the storm from now on."""
+        mac = self.devices[flood.source[0]].mac(flood.source[1])
+        area = set()
+        for a in self._areas(self._trunks(honor_stp=True)):
+            if a & flood.storm_switches:
+                area |= a
+        self.storming |= area
+        for s, ports in flood.flaps.items():
+            self.mac_flaps.setdefault(s, {})[mac] = ports
+
+    def learn_flood(self, flood: Flood) -> None:
+        """Switches a (loop-free) broadcast passed through learn its sender's MAC."""
+        mac = self.devices[flood.source[0]].mac(flood.source[1])
+        for gen in flood.generations:
+            for li, dev in gen:
+                if self.devices[dev].kind == "s":
+                    self.mac_tables.setdefault(dev, {})[mac] = self.links[li].port_of(dev)
+
+    def storm_near(self, dev_id: str) -> set[str]:
+        """Storming switches in the switched area(s) this device is plugged into."""
+        seen, q, hit = {dev_id}, deque([dev_id]), set()
+        while q:
+            u = q.popleft()
+            for l in self.links:
+                if l.touches(u) and self._carries(l, honor_stp=True):
+                    v = l.other(u)[0]
+                    if v in seen or self.devices[v].kind != "s":
+                        continue
+                    seen.add(v)
+                    q.append(v)
+                    if v in self.storming:
+                        hit.add(v)
+        return hit