The canvas, the front panel and the inspector now agree with the engine about a port (#1238) #1240

Merged
jaylouisw merged 1 commit from fix/port-state-one-rule into main 2026-11-09 17:37:24 +00:00
Owner

The canvas, the front panel and the inspector now agree with the engine about a port (#1238)

Fixes #1238. Follows #1237, which fixed the same defect in the CLI.

Three views describe a port and each of them answered the older question — did somebody shut it — and
printed the answer as the status. In faceplate.js that was the cell's data-state, in canvas.js the
tooltip suffix, in app.js the status bar. So an unplugged port read as healthy in the three places
you look when a link will not come up.

One rule, three callers

portState(facts) / portStateText(facts) now live in web/faceplate.js and the other two call them.
Facts are passed in rather than looked up, so a view that cannot see the topology says undefined and
gets "not down" instead of guessing: an unknown cable is not a missing cable.

Situation Verdict Panel/canvas text
shut on the port down administratively down
nothing plugged in notconnect down (no cable)
cable patched, link down down down (link down)
far port shut down down (peer shut down)
otherwise cabled / up up

notconnect is deliberately not down: painting every unused port on a 48-port faceplate red would
say "fault" 46 times. The tooltip still states the operational truth.

Found while doing it: a cut cable

docs/LINK-STATE.md documents link down — the ports stay patched, the simulator will not carry a
frame. Neither the CLI nor the UI knew about it: the port reported up/up with a dead cable between
it and its peer. The engine's Device.ifaceStatus() and the UI rule both grew a link down verdict,
distinct from no cable, because the two faults have different fixes. (blocked — STP — is not
treated as down: the link is physically up; only state === 'down' is.)

Evidence

test/port-state-agreement.test.js — 37 checks:

  • the engine's Device.ifaceStatus() and the UI's portStateText() name each situation identically,
    case for case, on a real two-router lab;
  • the front panel renders fp-notconnect + down (no cable) for an empty socket (and no fp-down), and
    fp-down + administratively down for a shut one;
  • the canvas, loaded with faceplate.js first, prints down (no cable) / administratively down in its
    port tooltips and nothing about being down for a healthy cabled port;
  • a cable taken down with setLinkState() reads down (link down) in the engine, the panel and the
    canvas, keeps its peer, and carries no packet;
  • index.html loads faceplate.js before canvas.js before app.js — the order the shared rule needs;
  • neither the canvas nor the inspector derives the status from enabled any more.

Reverting web/ makes the suite fail outright (portStateText is the thing under test).

One existing assertion had to change, and it is worth naming: test/faceplate.test.js asserted "an
empty socket is up but not cabled"
. That was the bug, written down as a requirement. It now asserts
notconnect and the reason, with a comment saying what it used to claim.

docs/LINK-STATE.md gains a table of what each view says per situation; docs/CLI.md gains the
link down row.

Suite: 134 suites, 5,861 assertions, 0 failed.

The canvas, the front panel and the inspector now agree with the engine about a port (#1238) Fixes #1238. Follows #1237, which fixed the same defect in the CLI. Three views describe a port and each of them answered the older question — *did somebody shut it* — and printed the answer as the status. In faceplate.js that was the cell's `data-state`, in canvas.js the tooltip suffix, in app.js the status bar. So an **unplugged** port read as healthy in the three places you look when a link will not come up. ## One rule, three callers `portState(facts)` / `portStateText(facts)` now live in `web/faceplate.js` and the other two call them. Facts are passed in rather than looked up, so a view that cannot see the topology says `undefined` and gets "not down" instead of guessing: **an unknown cable is not a missing cable**. | Situation | Verdict | Panel/canvas text | |---|---|---| | shut on the port | `down` | `administratively down` | | nothing plugged in | `notconnect` | `down (no cable)` | | cable patched, `link down` | `down` | `down (link down)` | | far port shut | `down` | `down (peer shut down)` | | otherwise | `cabled` / `up` | `up` | `notconnect` is deliberately not `down`: painting every unused port on a 48-port faceplate red would say "fault" 46 times. The tooltip still states the operational truth. ## Found while doing it: a cut cable `docs/LINK-STATE.md` documents `link down` — the ports stay patched, the simulator will not carry a frame. **Neither the CLI nor the UI knew about it**: the port reported up/up with a dead cable between it and its peer. The engine's `Device.ifaceStatus()` and the UI rule both grew a `link down` verdict, distinct from `no cable`, because the two faults have different fixes. (`blocked` — STP — is *not* treated as down: the link is physically up; only `state === 'down'` is.) ## Evidence `test/port-state-agreement.test.js` — 37 checks: * the engine's `Device.ifaceStatus()` and the UI's `portStateText()` name each situation identically, case for case, on a real two-router lab; * the front panel renders `fp-notconnect` + `down (no cable)` for an empty socket (and no `fp-down`), and `fp-down` + `administratively down` for a shut one; * the canvas, loaded with faceplate.js first, prints `down (no cable)` / `administratively down` in its port tooltips and nothing about being down for a healthy cabled port; * a cable taken down with `setLinkState()` reads `down (link down)` in the engine, the panel and the canvas, keeps its peer, and carries no packet; * `index.html` loads faceplate.js before canvas.js before app.js — the order the shared rule needs; * neither the canvas nor the inspector derives the status from `enabled` any more. Reverting `web/` makes the suite fail outright (`portStateText` is the thing under test). One existing assertion had to change, and it is worth naming: `test/faceplate.test.js` asserted *"an empty socket is up but not cabled"*. That was the bug, written down as a requirement. It now asserts `notconnect` and the reason, with a comment saying what it used to claim. `docs/LINK-STATE.md` gains a table of what each view says per situation; `docs/CLI.md` gains the `link down` row. Suite: 134 suites, 5,861 assertions, 0 failed.
The canvas, the front panel and the inspector now agree with the engine about a port (#1238)
All checks were successful
CI / Classify the change (pull_request) Successful in 11s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 17s
CI / Test (Node 18) (pull_request) Successful in 2m2s
CI / Test (Node 20) (pull_request) Successful in 1m57s
CI / Server smoke test (pull_request) Successful in 34s
CI / Docker build (pull_request) Successful in 39s
CI / Test (Node 22) (pull_request) Successful in 1m41s
c1fb5b935c
Fixes #1238. Follows #1237, which fixed the same defect in the CLI.

Three views describe a port and each of them answered the older question — *did somebody shut it* — and
printed the answer as the status. In faceplate.js that was the cell's `data-state`, in canvas.js the
tooltip suffix, in app.js the status bar. So an **unplugged** port read as healthy in the three places
you look when a link will not come up.

## One rule, three callers

`portState(facts)` / `portStateText(facts)` now live in `web/faceplate.js` and the other two call them.
Facts are passed in rather than looked up, so a view that cannot see the topology says `undefined` and
gets "not down" instead of guessing: **an unknown cable is not a missing cable**.

| Situation | Verdict | Panel/canvas text |
|---|---|---|
| shut on the port | `down` | `administratively down` |
| nothing plugged in | `notconnect` | `down (no cable)` |
| cable patched, `link down` | `down` | `down (link down)` |
| far port shut | `down` | `down (peer shut down)` |
| otherwise | `cabled` / `up` | `up` |

`notconnect` is deliberately not `down`: painting every unused port on a 48-port faceplate red would
say "fault" 46 times. The tooltip still states the operational truth.

## Found while doing it: a cut cable

`docs/LINK-STATE.md` documents `link down` — the ports stay patched, the simulator will not carry a
frame. **Neither the CLI nor the UI knew about it**: the port reported up/up with a dead cable between
it and its peer. The engine's `Device.ifaceStatus()` and the UI rule both grew a `link down` verdict,
distinct from `no cable`, because the two faults have different fixes. (`blocked` — STP — is *not*
treated as down: the link is physically up; only `state === 'down'` is.)

## Evidence

`test/port-state-agreement.test.js` — 37 checks:

* the engine's `Device.ifaceStatus()` and the UI's `portStateText()` name each situation identically,
  case for case, on a real two-router lab;
* the front panel renders `fp-notconnect` + `down (no cable)` for an empty socket (and no `fp-down`), and
  `fp-down` + `administratively down` for a shut one;
* the canvas, loaded with faceplate.js first, prints `down (no cable)` / `administratively down` in its
  port tooltips and nothing about being down for a healthy cabled port;
* a cable taken down with `setLinkState()` reads `down (link down)` in the engine, the panel and the
  canvas, keeps its peer, and carries no packet;
* `index.html` loads faceplate.js before canvas.js before app.js — the order the shared rule needs;
* neither the canvas nor the inspector derives the status from `enabled` any more.

Reverting `web/` makes the suite fail outright (`portStateText` is the thing under test).

One existing assertion had to change, and it is worth naming: `test/faceplate.test.js` asserted *"an
empty socket is up but not cabled"*. That was the bug, written down as a requirement. It now asserts
`notconnect` and the reason, with a comment saying what it used to claim.

`docs/LINK-STATE.md` gains a table of what each view says per situation; `docs/CLI.md` gains the
`link down` row.

Suite: 134 suites, 5,861 assertions, 0 failed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-09 17:37:19 +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!1240
No description provided.