Interface status now means "this port can carry a frame" (#1237) #1239

Merged
jaylouisw merged 1 commit from fix/interface-status-honest into main 2026-11-09 17:11:36 +00:00
Owner

Interface status now means "this port can carry a frame" (#1237)

Fixes #1237.

show ip interface brief answered one question — did somebody shut this port — and printed the answer
in the Status column. A port with no cable therefore reported up / up, in the table people copy into
bug reports when a link will not come up. show interfaces went further and contradicted itself two
lines apart:

Gi0/0/0 (ethernet, 1G), MAC 02:00:00:00:00:01
  status: up
  ip: 10.0.1.1/24
  peer: disconnected

Now

A single Device.ifaceStatus(iface, topo) answers the question once, and both commands use it:

Condition Status Protocol
shut down here administratively down down
no cable (peer is null) down down
cabled, far port shut down down down
wireless radio up (its link is the radio) up
otherwise up up

show interfaces carries the reason: status: down (no cable), protocol: down /
status: down (peer shut down), protocol: down. The block can no longer say status: up above
peer: disconnected.

The topology is passed in explicitly, because it is the only thing that knows a cable is missing. A
device that was never put in a topology has no cables to report on, so it keeps its old answer — asserted
in the tests, so it stays a decision rather than drifting into a default.

Evidence

test/interface-status.test.js — 24 checks on a real two-router lab:

  • a cabled port reads up and a ping crosses it, so the word means something;
  • an unconnected port with an address reads down / down, and nothing can reach that address;
  • shutting the far port makes the near port read down (not administratively down — nobody shut it
    here), a ping fails, and show interfaces names peer shut down;
  • shutting the local port reads administratively down;
  • the unconnected port's show interfaces block says down (no cable) and never claims up while the
    peer line says disconnected;
  • a bare device keeps up without a topology and reports down with one and no cable;
  • the property: for every port on both routers, the row's up/down matches whether that port can
    actually carry a frame (own side enabled, peer exists and is enabled).

Reverting engine/cli.js + engine/device.js fails 10 of them.

docs/CLI.md gains "Reading show ip interface brief" with the table above, the reason strings, the
wireless carve-out and the no-topology limit.

Follow-up, not in this PR

The web UI still derives status from enabled in three places — web/canvas.js:379 (canvas tooltip),
web/faceplate.js:477 (port title) and web/app.js:1586 (inspector footer) — so an unplugged port on
the canvas is still described as healthy. That is the same defect on a different code path, and it needs
its own tests over the canvas's link model rather than the engine's Topology; filed separately rather
than bolted on here.

Suite: 133 suites, 5,817 assertions, 0 failed.

Interface status now means "this port can carry a frame" (#1237) Fixes #1237. `show ip interface brief` answered one question — *did somebody shut this port* — and printed the answer in the Status column. A port with **no cable** therefore reported `up / up`, in the table people copy into bug reports when a link will not come up. `show interfaces` went further and contradicted itself two lines apart: ``` Gi0/0/0 (ethernet, 1G), MAC 02:00:00:00:00:01 status: up ip: 10.0.1.1/24 peer: disconnected ``` ## Now A single `Device.ifaceStatus(iface, topo)` answers the question once, and both commands use it: | Condition | Status | Protocol | |---|---|---| | shut down here | `administratively down` | `down` | | no cable (`peer` is null) | `down` | `down` | | cabled, far port shut down | `down` | `down` | | wireless radio | `up` (its link is the radio) | `up` | | otherwise | `up` | `up` | `show interfaces` carries the reason: `status: down (no cable), protocol: down` / `status: down (peer shut down), protocol: down`. The block can no longer say `status: up` above `peer: disconnected`. The topology is passed in explicitly, because it is the only thing that knows a cable is missing. A device that was never put in a topology has no cables to report on, so it keeps its old answer — asserted in the tests, so it stays a decision rather than drifting into a default. ## Evidence `test/interface-status.test.js` — 24 checks on a real two-router lab: * a cabled port reads up **and a ping crosses it**, so the word means something; * an unconnected port with an address reads `down / down`, and nothing can reach that address; * shutting the *far* port makes the near port read `down` (not `administratively down` — nobody shut it here), a ping fails, and `show interfaces` names `peer shut down`; * shutting the local port reads `administratively down`; * the unconnected port's `show interfaces` block says `down (no cable)` and never claims up while the peer line says disconnected; * a bare device keeps `up` without a topology and reports `down` with one and no cable; * **the property**: for every port on both routers, the row's up/down matches whether that port can actually carry a frame (own side enabled, peer exists and is enabled). Reverting `engine/cli.js` + `engine/device.js` fails 10 of them. `docs/CLI.md` gains "Reading `show ip interface brief`" with the table above, the reason strings, the wireless carve-out and the no-topology limit. ## Follow-up, not in this PR The web UI still derives status from `enabled` in three places — `web/canvas.js:379` (canvas tooltip), `web/faceplate.js:477` (port title) and `web/app.js:1586` (inspector footer) — so an unplugged port on the canvas is still described as healthy. That is the same defect on a different code path, and it needs its own tests over the canvas's link model rather than the engine's `Topology`; filed separately rather than bolted on here. Suite: 133 suites, 5,817 assertions, 0 failed.
Interface status now means "this port can carry a frame" (#1237)
All checks were successful
CI / Classify the change (pull_request) Successful in 10s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 13s
CI / Test (Node 18) (pull_request) Successful in 1m40s
CI / Test (Node 20) (pull_request) Successful in 1m39s
CI / Server smoke test (pull_request) Successful in 33s
CI / Docker build (pull_request) Successful in 40s
CI / Test (Node 22) (pull_request) Successful in 1m38s
97292626c8
Fixes #1237.

`show ip interface brief` answered one question — *did somebody shut this port* — and printed the answer
in the Status column. A port with **no cable** therefore reported `up / up`, in the table people copy into
bug reports when a link will not come up. `show interfaces` went further and contradicted itself two
lines apart:

```
Gi0/0/0 (ethernet, 1G), MAC 02:00:00:00:00:01
  status: up
  ip: 10.0.1.1/24
  peer: disconnected
```

## Now

A single `Device.ifaceStatus(iface, topo)` answers the question once, and both commands use it:

| Condition | Status | Protocol |
|---|---|---|
| shut down here | `administratively down` | `down` |
| no cable (`peer` is null) | `down` | `down` |
| cabled, far port shut down | `down` | `down` |
| wireless radio | `up` (its link is the radio) | `up` |
| otherwise | `up` | `up` |

`show interfaces` carries the reason: `status: down (no cable), protocol: down` /
`status: down (peer shut down), protocol: down`. The block can no longer say `status: up` above
`peer: disconnected`.

The topology is passed in explicitly, because it is the only thing that knows a cable is missing. A
device that was never put in a topology has no cables to report on, so it keeps its old answer — asserted
in the tests, so it stays a decision rather than drifting into a default.

## Evidence

`test/interface-status.test.js` — 24 checks on a real two-router lab:

* a cabled port reads up **and a ping crosses it**, so the word means something;
* an unconnected port with an address reads `down / down`, and nothing can reach that address;
* shutting the *far* port makes the near port read `down` (not `administratively down` — nobody shut it
  here), a ping fails, and `show interfaces` names `peer shut down`;
* shutting the local port reads `administratively down`;
* the unconnected port's `show interfaces` block says `down (no cable)` and never claims up while the
  peer line says disconnected;
* a bare device keeps `up` without a topology and reports `down` with one and no cable;
* **the property**: for every port on both routers, the row's up/down matches whether that port can
  actually carry a frame (own side enabled, peer exists and is enabled).

Reverting `engine/cli.js` + `engine/device.js` fails 10 of them.

`docs/CLI.md` gains "Reading `show ip interface brief`" with the table above, the reason strings, the
wireless carve-out and the no-topology limit.

## Follow-up, not in this PR

The web UI still derives status from `enabled` in three places — `web/canvas.js:379` (canvas tooltip),
`web/faceplate.js:477` (port title) and `web/app.js:1586` (inspector footer) — so an unplugged port on
the canvas is still described as healthy. That is the same defect on a different code path, and it needs
its own tests over the canvas's link model rather than the engine's `Topology`; filed separately rather
than bolted on here.

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