Make link state real, and re-converge when a cable is pulled #1058

Merged
jaylouisw merged 1 commit from feat/link-state-renewal into main 2026-11-08 09:02:47 +00:00
Owner

Link has carried state: 'up' | 'down' | 'blocked' since the physical layer was built, and
nothing in the engine ever read it. Link.isUp() existed, was exported, was serialised — and had no
caller:

$ grep -rn "isUp()" engine/*.js
engine/link.js:  isUp() { return this.state !== 'down'; }

So a cable marked down still carried every frame, still counted as a bridge port, and was still
walked by the DHCP segment search. The field was decoration, and the failure it hid was total: a
lab could show a cut link passing traffic.

What a state change now does — four things, all of them what real gear does

  1. Frames die at the cable. A frame crossing a down link is dropped with reason: 'link down'
    and the link id, so the timeline says where it died rather than going quiet.
  2. The spanning tree is rebuilt. A port whose cable is down is not a bridge port, so a redundant
    topology finds the other way. This is the whole reason STP exists, and it cannot be demonstrated
    if the tree ignores link state.
  3. Forwarding tables are flushed. A topology change empties every bridge's MAC table. Keeping
    the entries is how a real network black-holes after a failure: traffic is unicast into the port
    that used to lead somewhere.
  4. The schedule re-bases. Every control-plane timer runs again from the instant of the change.
R1#link down l5 at 10000
Link l5 (SW1:Fa0/1 <-> SW2:Fa0/1) is now down.
Network converges again at 40000 ms.

Re-convergence, end to end

A redundant triangle of three switches, host to host:

baseline                     ping ok    SW3 blocked Fa0/1 (the reserve path)
link down SW1-SW3            ping ok    nothing blocked — traffic moved to SW2
link up   SW1-SW3            ping ok    the reserve is blocked again

With no second path it stays broken, and healing one link brings it back. With the change at 10 s:

asked at result
11 s fails, reason: 'converging'
20 s fails, reason: 'converging'
41 s succeeds

getConvergence().convergedAtMs is 40 000, and the schedule carries fromMs: 10000 plus an entry
for the change itself, so nothing in it claims to be ready before the event that caused it.

Two things the tests caught that I had wrong

The change instant lived in the wrong place. I first kept it on the Simulator, and a lab
reloaded from disk reverted to fromMs: 0 — it would have reported the network as converged at 30 s
because something converged at 30 s, hours before the cable was pulled. It belongs on the topology
(lastChangeAtMs) and on the link (stateSinceMs), and it is saved.

lastChangeAtMs: 0 on every file. Writing the field unconditionally broke
examples-idempotent — four regenerated examples grew a field they had no business carrying. A lab
built and never disturbed has nothing to say about when it changed, so the field is written only
when it is non-zero. Same for stateSinceMs on a link that never moved.

The UI

A down cable is drawn dashed and red and carries data-link-state, and the cable context menu
gains Take link down / Bring link up — distinct from Delete cable, because unpatching a
port and cutting a cable are different operations. The status line reports when the network will be
whole again.

POST /api/topologies/:id/links/:linkId/state   { "state": "down", "atMs": 10000 }

Test

  • test/link-state.test.js — 67 assertions: the defect itself (a down link carries nothing, and
    the drop names the link), setLinkState refusals and idempotence, the tree healing around a
    failure, a network with no second path staying broken and recovering, the re-based schedule at
    11/20/41 s, MAC table flush, the DHCP segment walk refusing to cross a cut cable, save/load of
    state + stateSinceMs + lastChangeAtMs, and the CLI surface including every refusal.
  • test/link-state-drawing.test.js — 13 assertions: the renderer marks a down cable, keeps its
    medium class, stays clickable, and the stylesheet really dashes and recolours it.

Three failures while writing these, all real: STP was only rebuilt at run start (so a lab querying
straight after a change saw the old tree), and two were the test inspecting the 16 px transparent
grab band and calling it the drawing.

Docs

New docs/LINK-STATE.md, with a What this does not model section: no degraded links (no CRC
errors, no flapping), no autonegotiation on recovery, no interface self-test failure, and no RSTP
fast convergence
— re-convergence costs the same 30 s as a boot, because the timer model is
802.1D. That is the largest single inaccuracy here and it is stated rather than papered over.

docs/CONVERGENCE.md gains the re-convergence case, docs/SIMULATION.md gains §5.3b with the
defect and its enforcement points, docs/CLI.md the commands, README the capability row.

101 suites, 4 920 assertions, all passing.

Closes #1057.

`Link` has carried `state: 'up' | 'down' | 'blocked'` since the physical layer was built, and nothing in the engine ever read it. `Link.isUp()` existed, was exported, was serialised — and had no caller: ``` $ grep -rn "isUp()" engine/*.js engine/link.js: isUp() { return this.state !== 'down'; } ``` So a cable marked `down` still carried every frame, still counted as a bridge port, and was still walked by the DHCP segment search. The field was decoration, and the failure it hid was total: **a lab could show a cut link passing traffic.** ## What a state change now does — four things, all of them what real gear does 1. **Frames die at the cable.** A frame crossing a down link is dropped with `reason: 'link down'` and the link id, so the timeline says where it died rather than going quiet. 2. **The spanning tree is rebuilt.** A port whose cable is down is not a bridge port, so a redundant topology finds the other way. This is the whole reason STP exists, and it cannot be demonstrated if the tree ignores link state. 3. **Forwarding tables are flushed.** A topology change empties every bridge's MAC table. Keeping the entries is how a real network black-holes after a failure: traffic is unicast into the port that used to lead somewhere. 4. **The schedule re-bases.** Every control-plane timer runs again *from the instant of the change*. ``` R1#link down l5 at 10000 Link l5 (SW1:Fa0/1 <-> SW2:Fa0/1) is now down. Network converges again at 40000 ms. ``` ## Re-convergence, end to end A redundant triangle of three switches, host to host: ``` baseline ping ok SW3 blocked Fa0/1 (the reserve path) link down SW1-SW3 ping ok nothing blocked — traffic moved to SW2 link up SW1-SW3 ping ok the reserve is blocked again ``` With no second path it stays broken, and healing one link brings it back. With the change at 10 s: | asked at | result | |---|---| | 11 s | fails, `reason: 'converging'` | | 20 s | fails, `reason: 'converging'` | | 41 s | succeeds | `getConvergence().convergedAtMs` is 40 000, and the schedule carries `fromMs: 10000` plus an entry for the change itself, so nothing in it claims to be ready before the event that caused it. ## Two things the tests caught that I had wrong **The change instant lived in the wrong place.** I first kept it on the `Simulator`, and a lab reloaded from disk reverted to `fromMs: 0` — it would have reported the network as converged at 30 s because *something* converged at 30 s, hours before the cable was pulled. It belongs on the topology (`lastChangeAtMs`) and on the link (`stateSinceMs`), and it is saved. **`lastChangeAtMs: 0` on every file.** Writing the field unconditionally broke `examples-idempotent` — four regenerated examples grew a field they had no business carrying. A lab built and never disturbed has nothing to say about when it changed, so the field is written only when it is non-zero. Same for `stateSinceMs` on a link that never moved. ## The UI A down cable is drawn **dashed and red** and carries `data-link-state`, and the cable context menu gains **Take link down** / **Bring link up** — distinct from **Delete cable**, because unpatching a port and cutting a cable are different operations. The status line reports when the network will be whole again. ``` POST /api/topologies/:id/links/:linkId/state { "state": "down", "atMs": 10000 } ``` ## Test - `test/link-state.test.js` — **67 assertions**: the defect itself (a down link carries nothing, and the drop names the link), `setLinkState` refusals and idempotence, the tree healing around a failure, a network with no second path staying broken and recovering, the re-based schedule at 11/20/41 s, MAC table flush, the DHCP segment walk refusing to cross a cut cable, save/load of state + `stateSinceMs` + `lastChangeAtMs`, and the CLI surface including every refusal. - `test/link-state-drawing.test.js` — **13 assertions**: the renderer marks a down cable, keeps its medium class, stays clickable, and the stylesheet really dashes and recolours it. Three failures while writing these, all real: STP was only rebuilt at run start (so a lab querying straight after a change saw the old tree), and two were the test inspecting the 16 px transparent grab band and calling it the drawing. ## Docs New `docs/LINK-STATE.md`, with a *What this does not model* section: no degraded links (no CRC errors, no flapping), no autonegotiation on recovery, no interface self-test failure, and **no RSTP fast convergence** — re-convergence costs the same 30 s as a boot, because the timer model is 802.1D. That is the largest single inaccuracy here and it is stated rather than papered over. `docs/CONVERGENCE.md` gains the re-convergence case, `docs/SIMULATION.md` gains §5.3b with the defect and its enforcement points, `docs/CLI.md` the commands, README the capability row. **101 suites, 4 920 assertions, all passing.** Closes #1057.
Make link state real, and re-converge when a cable is pulled
All checks were successful
CI / Server smoke test (pull_request) Successful in 52s
CI / Test (Node 18) (pull_request) Successful in 2m23s
CI / Docker build (pull_request) Successful in 17s
CI / Test (Node 20) (pull_request) Successful in 2m17s
CI / Test (Node 22) (pull_request) Successful in 2m27s
71591e4398
Link has carried state: 'up' | 'down' | 'blocked' since the physical layer was built, and nothing
in the engine ever read it. isUp() existed, was exported, was serialised - and had no caller. So a
cable marked down still carried every frame, still counted as a bridge port, and was still walked by
the DHCP segment search. The field was decoration, and the failure it hid was total: a lab could
show a cut link passing traffic.

Four things a state change now does, all of them what real gear does:

- Frames die at the cable, dropped with reason 'link down' and the link id, so the timeline says
  where the frame died instead of going quiet.
- The spanning tree is rebuilt. A port whose cable is down is not a bridge port, so a redundant
  topology finds the other way - which is the whole reason STP exists.
- Every bridge's MAC table is flushed on the topology change. Keeping the entries is how a network
  black-holes after a failure: traffic is unicast into the port that used to lead somewhere.
- The convergence schedule re-bases at the instant of the change, so the control-plane timers run
  again from there and a lab can show the window in which nothing works.

  R1#link down l5 at 10000
  Link l5 (SW1:Fa0/1 <-> SW2:Fa0/1) is now down.
  Network converges again at 40000 ms.

A redundant triangle heals: breaking the direct link unblocks the reserve path and traffic moves;
healing it puts the reserve back. With no second path the lab stays broken until one is restored.
Asked at 11 s and 20 s the answer is reason 'converging'; at 41 s it works, and
getConvergence().convergedAtMs is 40000.

Two things the tests caught that were wrong in my first cut: the change instant was kept on the
Simulator, so a lab reloaded from disk reverted to fromMs 0 and would have claimed to be converged
because something converged hours earlier - it now lives on the topology and the link, and is saved;
and writing lastChangeAtMs unconditionally broke examples-idempotent, so it is written only when
non-zero, as is stateSinceMs on a link that never moved.

UI: a down cable is drawn dashed and red and carries data-link-state; the cable menu gains Take link
down / Bring link up, distinct from Delete cable because unpatching and cutting are different
operations. New route POST /api/topologies/:id/links/:linkId/state. New CLI: link up|down|state <id>
[at <ms>] and links.

test/link-state.test.js, 67 assertions. test/link-state-drawing.test.js, 13.

docs/LINK-STATE.md documents what is not modelled: no degraded links, no flapping, no
autonegotiation on recovery, and no RSTP fast convergence - re-convergence costs the same 30 s as a
boot because the timer model is 802.1D.

101 suites, 4920 assertions, all passing.

Closes #1058.
jaylouisw force-pushed feat/link-state-renewal from 71591e4398
All checks were successful
CI / Server smoke test (pull_request) Successful in 52s
CI / Test (Node 18) (pull_request) Successful in 2m23s
CI / Docker build (pull_request) Successful in 17s
CI / Test (Node 20) (pull_request) Successful in 2m17s
CI / Test (Node 22) (pull_request) Successful in 2m27s
to 24fe06e6b8
All checks were successful
CI / Server smoke test (pull_request) Successful in 39s
CI / Docker build (pull_request) Successful in 15s
CI / Test (Node 18) (pull_request) Successful in 2m15s
CI / Test (Node 20) (pull_request) Successful in 2m20s
CI / Test (Node 22) (pull_request) Successful in 2m10s
2026-11-08 09:02:01 +00:00
Compare
jaylouisw deleted branch feat/link-state-renewal 2026-11-08 09:02:49 +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!1058
No description provided.