A shut port neither spans nor receives (#1274) #1276

Merged
jaylouisw merged 1 commit from fix/stp-shut-port into main 2026-11-09 21:21:37 +00:00
Owner

A shut port neither spans nor receives

Fixes #1274.

all up     blocked {s3:[Fa0/2]}   ping works
cable out  blocked {}             ping works
far shut   blocked {s3:[Fa0/2]}   ping FAILS      <- before this
far shut   blocked {}             ping works      <- after

Two defects, interlocking

1. The tree counted ports that could not carry a frame as edges. computeStp() asked only whether the
cable was up, so a port someone shut — and a port whose far end someone shut — stayed an edge. The tree then
kept blocking the port that would have healed the ring: pull the cable and the ring healed, shut the same port
and it did not, leaving a whole switch with no path to the rest of the network. It now asks
Device.ifaceStatus(iface, topo) — the rule every table in the console already shares (nine callers now).

2. A shut port still received. _deliver() checked the sending port and never the receiving one, so a
frame aimed at an administratively-down port was delivered, learned from and forwarded. The ring never
actually broke: frames were replicated around the break, s3 learned the far host on the port it could not
use, b's reply went out of a dead port, and a's ARP cache ended up holding

10.0.0.9 -> 02:00:00:00:04:00      (a's own address, a switch's bridge MAC)

Delivery into a shut port is now refused, counted once on the sender with a reason that names the far end
(peer port shut (pc eth0) — "your frame left Gi0 and the port it was going to is shut" is actionable;
link administratively down on a port that is up is not). A packet waiting on the ARP that request carried is
cleared rather than reported again at sweep time, so one lost ping is one counted loss — and the first reason
is the true one.

After

In the ring with a shut port: the far host is learned on the live side only, nothing is learned on the shut
port, zero loop: egress equals ingress drops, and both hosts' ARP caches hold only each other's real
MACs. Re-enabling the port restores exactly the previous tree.

Evidence

test/stp-shut-port.test.js — 27 checks, 13 of which fail with engine/simulator.js reverted:

  • the all-up ring blocks exactly one port and works;
  • a shut far port and a shut local port give the same tree a pulled cable gives — the assertion that
    makes "same physical outcome, same verdict" testable;
  • traffic crosses in all three failure shapes;
  • nothing is learned on a shut port, and the loop guard never fires;
  • neither host caches its own address, and each knows the other by its real MAC;
  • a frame aimed into a shut port is a reasoned discard naming the far end;
  • re-enabling restores the previous tree exactly;
  • a plain two-switch lab is untouched — the fix must not cry wolf.

One assertion in test/interface-drops.test.js pinned no ARP reply from 10.0.0.9, which was the most
precise reason the old code could offer. It now asserts the sharper peer port shut (pc eth0) while keeping
the load-bearing invariants: the tally equals the event log, and the ping's sentence is the discard's
sentence.

Suite: 151 suites, 6,332 assertions, 0 failed.

A shut port neither spans nor receives Fixes #1274. ``` all up blocked {s3:[Fa0/2]} ping works cable out blocked {} ping works far shut blocked {s3:[Fa0/2]} ping FAILS <- before this far shut blocked {} ping works <- after ``` ## Two defects, interlocking **1. The tree counted ports that could not carry a frame as edges.** `computeStp()` asked only whether the *cable* was up, so a port someone shut — and a port whose far end someone shut — stayed an edge. The tree then kept blocking the port that would have healed the ring: pull the cable and the ring healed, shut the same port and it did not, leaving a whole switch with no path to the rest of the network. It now asks `Device.ifaceStatus(iface, topo)` — the rule every table in the console already shares (nine callers now). **2. A shut port still received.** `_deliver()` checked the *sending* port and never the receiving one, so a frame aimed at an administratively-down port was delivered, learned from and forwarded. The ring never actually broke: frames were replicated around the break, `s3` learned the far host on the port it could not use, `b`'s reply went out of a dead port, and `a`'s ARP cache ended up holding ``` 10.0.0.9 -> 02:00:00:00:04:00 (a's own address, a switch's bridge MAC) ``` Delivery into a shut port is now refused, counted **once** on the sender with a reason that names the far end (`peer port shut (pc eth0)` — "your frame left Gi0 and the port it was going to is shut" is actionable; `link administratively down` on a port that is up is not). A packet waiting on the ARP that request carried is cleared rather than reported again at sweep time, so one lost ping is one counted loss — and the first reason is the true one. ## After In the ring with a shut port: the far host is learned on the live side only, **nothing** is learned on the shut port, **zero** `loop: egress equals ingress` drops, and both hosts' ARP caches hold only each other's real MACs. Re-enabling the port restores exactly the previous tree. ## Evidence `test/stp-shut-port.test.js` — 27 checks, **13 of which fail** with `engine/simulator.js` reverted: * the all-up ring blocks exactly one port and works; * a shut **far** port and a shut **local** port give the *same tree* a pulled cable gives — the assertion that makes "same physical outcome, same verdict" testable; * traffic crosses in all three failure shapes; * nothing is learned on a shut port, and the loop guard never fires; * neither host caches its own address, and each knows the other by its real MAC; * a frame aimed into a shut port is a reasoned discard naming the far end; * re-enabling restores the previous tree exactly; * a plain two-switch lab is untouched — the fix must not cry wolf. One assertion in `test/interface-drops.test.js` pinned `no ARP reply from 10.0.0.9`, which was the most precise reason the old code could offer. It now asserts the sharper `peer port shut (pc eth0)` while keeping the load-bearing invariants: the tally equals the event log, and the ping's sentence is the discard's sentence. Suite: 151 suites, 6,332 assertions, 0 failed.
A shut port neither spans nor receives (#1274)
All checks were successful
CI / Classify the change (pull_request) Successful in 12s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 15s
CI / Test (Node 20) (pull_request) Successful in 2m32s
CI / Test (Node 18) (pull_request) Successful in 2m39s
CI / Server smoke test (pull_request) Successful in 36s
CI / Docker build (pull_request) Successful in 43s
CI / Test (Node 22) (pull_request) Successful in 1m58s
83c2b8db8c
Two defects that together black-holed a switch in a four-switch ring:

  all up     blocked {s3:[Fa0/2]}   ping works
  cable out  blocked {}             ping works
  far shut   blocked {s3:[Fa0/2]}   ping FAILS   <- s3 has no usable path left

1. `computeStp()` put a port in the tree if its *cable* was up, so a port someone shut - and a port whose far
   end someone shut - stayed an edge, and the tree kept blocking the port that would have healed the ring.
   Pull the cable and the ring healed; shut the same port and it did not. It now asks
   `Device.ifaceStatus(iface, topo)`, the same rule every table in the console uses.

2. `_deliver()` checked the *sending* port - enabled, peer, link up - and never the receiving one. A frame
   aimed at an administratively-down port was delivered, learned from and forwarded, so the ring never
   actually broke: frames were replicated around it, s3 learned the far host on the port it could not use,
   b's reply went out of a dead port, and a's ARP cache ended up holding its own address mapped to a switch's
   bridge MAC. Delivery into a shut port is now refused, counted once on the sender with a reason that names
   the far end (`peer port shut (pc eth0)`), and a packet waiting on the ARP that request carried is cleared
   rather than reported again at sweep time - one lost ping is one counted loss, and the first reason is the
   true one.

After the fix all four cases - all up, cable pulled, far port shut, local port shut - leave the ring with no
blocked port and traffic crossing. In the shut case the far host is learned on the live side only, nothing is
learned on the shut port, there are zero `loop: egress equals ingress` drops, and both hosts' ARP caches hold
only each other's real MACs.

test/stp-shut-port.test.js (27 checks): the all-up ring blocks exactly one port and works; a shut far port and
a shut local port give the same tree a pulled cable gives; traffic crosses in all three; nothing is learned
on a shut port and the loop guard never fires; neither host caches its own address; a frame aimed into a shut
port is a reasoned discard naming the far end; re-enabling the port restores the previous tree; and a plain
two-switch lab is untouched. 13 of the 27 fail with engine/simulator.js reverted.

test/interface-drops.test.js: one assertion pinned `no ARP reply from 10.0.0.9`, which was the most precise
reason the old code could offer. It now asserts the sharper `peer port shut (pc eth0)` and keeps the
load-bearing invariants - the tally equals the event log, and the ping's sentence is the discard's sentence.

Suite: 151 suites, 6,332 assertions, 0 failed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-09 21:21:34 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!1276
No description provided.