a cable whose port name needs the resolver is restored, not dropped #1529

Merged
jaylouisw merged 1 commit from fix/1519-topology-silent-link-loss into main 2026-11-15 18:40:53 +00:00
Owner

Fixes #1519

First: what the reproduction actually shows

The reproduction does not reproduce as written, and two of its premises are stale. Saying so before the fix, because a fix for a bug I could not see is a guess:

  • GigabitEthernet1/0/1 written exactly does not throw. At 1b1e1287, a two-device document whose link names the port exactly as the catalogue spells it loads with 1 link and no issues: exact spelling : devices=2 links=1 issues=0, link l1 d1/GigabitEthernet1/0/25 -- d2/GigabitEthernet1/0/25 peerSet=true/true.
  • fromJSON is not silent, and has not been since #1323. A cable that cannot be rebuilt already lands in loadIssues - one entry per cable, with the link id - and every state payload publishes it. The bare catch at topology.js:607-611 is gone; engine/topology.js is 907 lines, not 8,000.
  • The two-copy premise is stale. engine/cli.js no longer holds a copy of the naming rules: since #40/#1247 it imports resolvePortName/portKey from engine/iface-name.js, and test/iface-name-agreement.test.js fails the moment a copy comes back. cli.js:232 / cli.js:14085 do not exist (cli.js is 4,367 lines). There is already one resolver, and I did not add a fourth.

What is real, and reproduces, is the strictness the issue is about - sitting in the wrong function. connect() resolves names; the loader's pre-check cableProblem() asked dev.interfaces.has(end.iface), an exact map lookup. So the gate in front of connect() was stricter than connect(), and a document whose port names need the resolver lost every cable, with a report claiming the port did not exist. ether1 on a device whose port is eth1 is exactly the case #39 introduced the resolver for.

Before the fix (1b1e1287)

MikroTik CCR1009-7G-1C-1S+ (panel names eth1..eth7) with four cables naming the console spelling ether1..ether4:

--- A2 four MikroTik cables in the console spelling
    resolver says: eth1/eth1 , eth2/eth2 , eth3/eth3 , eth4/eth4
    declared=4 restored=0 issues=4
      [error] E_LINK_ENDPOINT_MISSING link=l1 :: cable end d1/ether1 names a port that device does not have
      [error] E_LINK_ENDPOINT_MISSING link=l2 :: cable end d1/ether2 names a port that device does not have
      [error] E_LINK_ENDPOINT_MISSING link=l3 :: cable end d1/ether3 names a port that device does not have
      [error] E_LINK_ENDPOINT_MISSING link=l4 :: cable end d1/ether4 names a port that device does not have

Case-only spelling, and a genuinely absent port:

--- B GigabitEthernet names, case folded by the resolver
    resolver says: GigabitEthernet1/0/25/GigabitEthernet1/0/26
    declared=1 restored=0 issues=1
      [error] E_LINK_ENDPOINT_MISSING link=l1 :: cable end d1/gigabitethernet1/0/25 names a port that device does not have
--- C exact GigabitEthernet spelling
    declared=1 restored=1 issues=0
--- D one good cable and one naming a port the device does not have
    declared=2 restored=1 issues=1
      [error] E_LINK_ENDPOINT_MISSING link=l2 :: cable end d1/GigabitEthernet1/0/99 names a port that device does not have

Compare the resolver's own answer on the same names in A2 and B: eth1, GigabitEthernet1/0/25. The ports existed; only the spelling differed. (C shows the exact spelling already worked - the contradiction above.)

After the fix (cd39a926)

--- A2 four MikroTik cables in the console spelling
    declared=4 restored=4 issues=0
      l1:eth1->eth1 peer=eth1
      l2:eth2->eth2 peer=eth2
      l3:eth3->eth3 peer=eth3
      l4:eth4->eth4 peer=eth4
--- B GigabitEthernet names, case folded by the resolver
    declared=1 restored=1 issues=0
      l1:GigabitEthernet1/0/25->GigabitEthernet1/0/26 peer=GigabitEthernet1/0/26
--- C exact GigabitEthernet spelling
    declared=1 restored=1 issues=0
      l1:GigabitEthernet1/0/25->GigabitEthernet1/0/26 peer=GigabitEthernet1/0/26
--- D one good cable and one naming a port the device does not have
    declared=2 restored=1 issues=1
      [warning] E_LINK_ENDPOINT_MISSING link=l2 :: cable l2 end d1/GigabitEthernet1/0/99 names a port d1 does not have
      l1:GigabitEthernet1/0/25->GigabitEthernet1/0/26 peer=GigabitEthernet1/0/26

What changed

engine/topology.js

  • cableProblem() resolves each end with ifaceName.resolvePortName() - the same function connect() and the console use - instead of dev.interfaces.has(). One naming table, as before; the callers of it are unchanged: cli.js (ten call sites, plus the module export the naming test pins), device.js:415 (resolveIface), and topology.js itself (validateLink, mediaOptions, connect).
  • A cable that cannot be rebuilt is a warning, not an error: the board loaded, one cable of it did not. Both loss paths now name the cable - cable l2 end d1/... names a port d1 does not have and cable l2 was not restored: ... - still one entry per lost cable, so declared - restored equals the number of link entries. That invariant is asserted, so a cable cannot go missing quietly.

test/topology-load-links.test.js (new, 27 checks)

  • a document whose cables name MikroTik console spellings loads with every cable, on the port the resolver named, with iface.peer set on both ends (peer is the thing only connect() sets);
  • a case-folded GigabitEthernet spelling loads, and the exact catalogue spelling still loads quietly;
  • a document with one genuinely absent port keeps the survivors and reports one warning naming the cable id and the port, with the counts asserted to account for each other;
  • a cable the engine refuses (two cables into one port) is a warning naming the cable and quoting the engine sentence.

docs/ARCHITECTURE.md - "A cable is restored or explained" now documents the severity, the message shape, and that link names are resolved through the one table rather than string-matched.

Tests

  • before (1b1e1287): 248 suite(s) in 799.7 s - 9137 assertions passed, 0 failed
  • after (cd39a926): 249 suite(s) in 424.9 s - 9164 assertions passed, 0 failed (the new suite is topology-load-links 27 passed; every pre-existing suite still green)
  • npm run syntax: 319 files, all OK

The two suites the brief called known-broken - canonical-urls and spec-vs-description - passed at HEAD in this worktree. The baseline run had zero failures, so there was nothing for me to skip.

Not fixed here

loadIssues is published in every state payload but nothing under web/ reads it (grep -rni loadissue web/ has no hits), so on the canvas a lost cable is still not shown - it is only visible over the API. Wiring that up is a UI change with its own DOM contract, so it belongs in its own issue rather than in this fix.

Fixes #1519 ## First: what the reproduction actually shows The reproduction does **not** reproduce as written, and two of its premises are stale. Saying so before the fix, because a fix for a bug I could not see is a guess: * **`GigabitEthernet1/0/1` written exactly does not throw.** At `1b1e1287`, a two-device document whose link names the port exactly as the catalogue spells it loads with 1 link and no issues: `exact spelling : devices=2 links=1 issues=0`, `link l1 d1/GigabitEthernet1/0/25 -- d2/GigabitEthernet1/0/25 peerSet=true/true`. * **`fromJSON` is not silent, and has not been since #1323.** A cable that cannot be rebuilt already lands in `loadIssues` - one entry per cable, with the link id - and every state payload publishes it. The bare `catch` at `topology.js:607-611` is gone; `engine/topology.js` is 907 lines, not 8,000. * **The two-copy premise is stale.** `engine/cli.js` no longer holds a copy of the naming rules: since #40/#1247 it imports `resolvePortName`/`portKey` from `engine/iface-name.js`, and `test/iface-name-agreement.test.js` fails the moment a copy comes back. `cli.js:232` / `cli.js:14085` do not exist (`cli.js` is 4,367 lines). **There is already one resolver, and I did not add a fourth.** What *is* real, and reproduces, is the strictness the issue is about - sitting in the wrong function. `connect()` resolves names; the loader's pre-check `cableProblem()` asked `dev.interfaces.has(end.iface)`, an exact map lookup. So the gate **in front of** `connect()` was stricter than `connect()`, and a document whose port names need the resolver lost every cable, with a report claiming the port did not exist. `ether1` on a device whose port is `eth1` is exactly the case #39 introduced the resolver for. ### Before the fix (`1b1e1287`) MikroTik CCR1009-7G-1C-1S+ (panel names `eth1..eth7`) with four cables naming the console spelling `ether1..ether4`: ``` --- A2 four MikroTik cables in the console spelling resolver says: eth1/eth1 , eth2/eth2 , eth3/eth3 , eth4/eth4 declared=4 restored=0 issues=4 [error] E_LINK_ENDPOINT_MISSING link=l1 :: cable end d1/ether1 names a port that device does not have [error] E_LINK_ENDPOINT_MISSING link=l2 :: cable end d1/ether2 names a port that device does not have [error] E_LINK_ENDPOINT_MISSING link=l3 :: cable end d1/ether3 names a port that device does not have [error] E_LINK_ENDPOINT_MISSING link=l4 :: cable end d1/ether4 names a port that device does not have ``` Case-only spelling, and a genuinely absent port: ``` --- B GigabitEthernet names, case folded by the resolver resolver says: GigabitEthernet1/0/25/GigabitEthernet1/0/26 declared=1 restored=0 issues=1 [error] E_LINK_ENDPOINT_MISSING link=l1 :: cable end d1/gigabitethernet1/0/25 names a port that device does not have --- C exact GigabitEthernet spelling declared=1 restored=1 issues=0 --- D one good cable and one naming a port the device does not have declared=2 restored=1 issues=1 [error] E_LINK_ENDPOINT_MISSING link=l2 :: cable end d1/GigabitEthernet1/0/99 names a port that device does not have ``` Compare the resolver's own answer on the same names in A2 and B: `eth1`, `GigabitEthernet1/0/25`. The ports existed; only the spelling differed. (C shows the exact spelling already worked - the contradiction above.) ### After the fix (`cd39a926`) ``` --- A2 four MikroTik cables in the console spelling declared=4 restored=4 issues=0 l1:eth1->eth1 peer=eth1 l2:eth2->eth2 peer=eth2 l3:eth3->eth3 peer=eth3 l4:eth4->eth4 peer=eth4 --- B GigabitEthernet names, case folded by the resolver declared=1 restored=1 issues=0 l1:GigabitEthernet1/0/25->GigabitEthernet1/0/26 peer=GigabitEthernet1/0/26 --- C exact GigabitEthernet spelling declared=1 restored=1 issues=0 l1:GigabitEthernet1/0/25->GigabitEthernet1/0/26 peer=GigabitEthernet1/0/26 --- D one good cable and one naming a port the device does not have declared=2 restored=1 issues=1 [warning] E_LINK_ENDPOINT_MISSING link=l2 :: cable l2 end d1/GigabitEthernet1/0/99 names a port d1 does not have l1:GigabitEthernet1/0/25->GigabitEthernet1/0/26 peer=GigabitEthernet1/0/26 ``` ## What changed `engine/topology.js` * `cableProblem()` resolves each end with `ifaceName.resolvePortName()` - the same function `connect()` and the console use - instead of `dev.interfaces.has()`. One naming table, as before; the callers of it are unchanged: `cli.js` (ten call sites, plus the module export the naming test pins), `device.js:415` (`resolveIface`), and `topology.js` itself (`validateLink`, `mediaOptions`, `connect`). * A cable that cannot be rebuilt is a `warning`, not an `error`: the board loaded, one cable of it did not. Both loss paths now name the cable - `cable l2 end d1/... names a port d1 does not have` and `cable l2 was not restored: ...` - still one entry per lost cable, so `declared - restored` equals the number of link entries. That invariant is asserted, so a cable cannot go missing quietly. `test/topology-load-links.test.js` (new, 27 checks) * a document whose cables name MikroTik console spellings loads with every cable, on the port the resolver named, with `iface.peer` set on both ends (peer is the thing only `connect()` sets); * a case-folded `GigabitEthernet` spelling loads, and the exact catalogue spelling still loads quietly; * a document with one genuinely absent port keeps the survivors and reports one warning naming the cable id and the port, with the counts asserted to account for each other; * a cable the engine refuses (two cables into one port) is a warning naming the cable and quoting the engine sentence. `docs/ARCHITECTURE.md` - "A cable is restored or explained" now documents the severity, the message shape, and that link names are resolved through the one table rather than string-matched. ## Tests * **before** (`1b1e1287`): `248 suite(s) in 799.7 s - 9137 assertions passed, 0 failed` * **after** (`cd39a926`): `249 suite(s) in 424.9 s - 9164 assertions passed, 0 failed` (the new suite is `topology-load-links 27 passed`; every pre-existing suite still green) * `npm run syntax`: 319 files, all OK The two suites the brief called known-broken - `canonical-urls` and `spec-vs-description` - **passed at HEAD in this worktree**. The baseline run had zero failures, so there was nothing for me to skip. ## Not fixed here `loadIssues` is published in every state payload but nothing under `web/` reads it (`grep -rni loadissue web/` has no hits), so on the canvas a lost cable is still not shown - it is only visible over the API. Wiring that up is a UI change with its own DOM contract, so it belongs in its own issue rather than in this fix.
a cable whose port name needs the resolver is restored, not dropped
All checks were successful
CI / Classify the change (pull_request) Successful in 15s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 19s
CI / Test (Node 18) (pull_request) Successful in 3m16s
CI / Test (Node 20) (pull_request) Successful in 3m1s
CI / Server smoke test (pull_request) Successful in 36s
CI / Docker build (pull_request) Successful in 47s
CI / Test (Node 22) (pull_request) Successful in 3m2s
cd39a92690
The loader's pre-check asked `interfaces.has()`, an exact map lookup, while
`connect()` resolves names through engine/iface-name.js. The pre-check is
stricter, so a cable naming `ether1` on a device whose port is `eth1` - the
console spelling an older lab file carries, which is the case the resolver
exists for (#39) - was refused before `connect()` could resolve it, and the
board came back with the cable missing and a report saying the port did not
exist. Four such cables loaded as zero links.

`cableProblem()` now asks the same resolver the console and `connect()` use,
so there is still exactly one naming table.

A cable that cannot be rebuilt is now a warning rather than an error, and the
sentence names the cable id and the end that failed. The board loads; one
cable of it did not, and every loss is one entry, so a document that loads
with fewer links than it declares says which.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-15 18:40:38 +00:00
jaylouisw force-pushed fix/1519-topology-silent-link-loss from cd39a92690
All checks were successful
CI / Classify the change (pull_request) Successful in 15s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 19s
CI / Test (Node 18) (pull_request) Successful in 3m16s
CI / Test (Node 20) (pull_request) Successful in 3m1s
CI / Server smoke test (pull_request) Successful in 36s
CI / Docker build (pull_request) Successful in 47s
CI / Test (Node 22) (pull_request) Successful in 3m2s
to 0e7ecc2c05
All checks were successful
CI / Classify the change (pull_request) Successful in 16s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 20s
CI / Test (Node 20) (pull_request) Successful in 3m3s
CI / Test (Node 18) (pull_request) Successful in 3m23s
CI / Server smoke test (pull_request) Successful in 33s
CI / Docker build (pull_request) Successful in 43s
CI / Test (Node 22) (pull_request) Successful in 3m14s
2026-11-15 18:40:42 +00:00
Compare
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!1529
No description provided.