show arp names the port, and says when the neighbour is stale (#1253) #1254

Merged
jaylouisw merged 1 commit from fix/show-arp-interface into main 2026-11-09 19:07:21 +00:00
Owner

show arp names the port, and says when the neighbour is stale

Fixes #1253.

Protocol  Address          Age (min)  Hardware Addr     Interface
Internet  10.0.0.9         -          02:00:00:00:02:00 Gi0
Internet  10.0.0.10        -          02:00:00:00:03:00 Gi0 (down: link down)

The Interface column used to be a header over nothing — every row stopped at the MAC — so the one table that
tells you where a neighbour lives could not tell you. The engine had the same gap: Device.arp is
Map(ip → mac) and nothing recorded the port, even though the ARP handler has inIface in scope at all
three learning sites.

Every entry also looked identical whether its port was up, shut or uncabled, so a stale cache entry read as
evidence the address was reachable — the exact belief someone is checking when they run the command.

Now

  • Device.learnArp(ip, mac, portName) is the single entry point and keeps arpPorts; all three simulator
    call sites pass inIface, so a future site cannot forget the port.
  • show arp prints the port with the reason when it can no longer carry a frame —
    (administratively down), (down: no cable), (down: link down), (down: peer shut down). "down"
    alone sends you hunting a cable when the cable is fine and the far port is shut.
  • The entry is not deleted when the port goes down: a real ARP cache does not empty when a cable is
    pulled, and the state is what marks it stale.
  • An entry with no recorded port (a topology restored from an older file) prints -; a port that no longer
    exists prints its name and (gone).
  • Age (min) stays -, and the docs now say why: the simulator counts steps, not minutes, and a step count
    in a minutes column is a number with the wrong unit.
  • Rows sort numerically, so 10.0.0.9 comes before 10.0.0.10 rather than after it.

Evidence

test/show-arp.test.js — 28 checks:

  • both neighbours listed, and every row has as many columns as the header (the assertion that would
    have caught the original defect);
  • the interface printed is the port the engine recorded, facing the switch, and the hardware address is the
    one the data plane uses;
  • numeric address order;
  • a shut port marks the entry and keeps it; a pulled cable marks it with a different reason
    (down: link down) — driven through sim.setLinkState(), not by poking a field;
  • a restored entry with no port prints -; a vanished port prints (gone);
  • a device with no topology names the port and invents no state it cannot know;
  • re-learning moves the port, as a real cache does.

Reverting engine/cli.js fails 16 of the 28.

docs/CLI.md gains a "Reading show arp" section.

Suite: 140 suites, 6,021 assertions, 0 failed.

`show arp` names the port, and says when the neighbour is stale Fixes #1253. ``` Protocol Address Age (min) Hardware Addr Interface Internet 10.0.0.9 - 02:00:00:00:02:00 Gi0 Internet 10.0.0.10 - 02:00:00:00:03:00 Gi0 (down: link down) ``` The Interface column used to be a header over nothing — every row stopped at the MAC — so the one table that tells you where a neighbour lives could not tell you. The engine had the same gap: `Device.arp` is `Map(ip → mac)` and nothing recorded the port, even though the ARP handler has `inIface` in scope at all three learning sites. Every entry also looked identical whether its port was up, shut or uncabled, so a stale cache entry read as evidence the address was reachable — the exact belief someone is checking when they run the command. ## Now * `Device.learnArp(ip, mac, portName)` is the single entry point and keeps `arpPorts`; all three simulator call sites pass `inIface`, so a future site cannot forget the port. * `show arp` prints the port **with the reason** when it can no longer carry a frame — `(administratively down)`, `(down: no cable)`, `(down: link down)`, `(down: peer shut down)`. "down" alone sends you hunting a cable when the cable is fine and the far port is shut. * The entry is **not deleted** when the port goes down: a real ARP cache does not empty when a cable is pulled, and the state is what marks it stale. * An entry with no recorded port (a topology restored from an older file) prints `-`; a port that no longer exists prints its name and `(gone)`. * `Age (min)` stays `-`, and the docs now say why: the simulator counts steps, not minutes, and a step count in a minutes column is a number with the wrong unit. * Rows sort numerically, so `10.0.0.9` comes before `10.0.0.10` rather than after it. ## Evidence `test/show-arp.test.js` — 28 checks: * both neighbours listed, and **every row has as many columns as the header** (the assertion that would have caught the original defect); * the interface printed is the port the engine recorded, facing the switch, and the hardware address is the one the data plane uses; * numeric address order; * a shut port marks the entry and keeps it; a **pulled cable** marks it with a different reason (`down: link down`) — driven through `sim.setLinkState()`, not by poking a field; * a restored entry with no port prints `-`; a vanished port prints `(gone)`; * a device with no topology names the port and invents no state it cannot know; * re-learning moves the port, as a real cache does. Reverting `engine/cli.js` fails 16 of the 28. `docs/CLI.md` gains a "Reading `show arp`" section. Suite: 140 suites, 6,021 assertions, 0 failed.
show arp names the port, and says when the neighbour is stale (#1253)
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 10s
CI / Test (Node 18) (pull_request) Successful in 1m56s
CI / Test (Node 20) (pull_request) Successful in 1m51s
CI / Server smoke test (pull_request) Successful in 35s
CI / Docker build (pull_request) Successful in 37s
CI / Test (Node 22) (pull_request) Successful in 1m42s
1590ef90a4
The command printed a five-column header and three-column rows: the Interface column was a title over
nothing, so the one table that tells you where a neighbour lives could not tell you. The engine had the same
gap - `Device.arp` is Map(ip -> mac) - even though the ARP handler has `inIface` in scope at all three
learning sites.

Every entry also looked the same whether its port was up, shut, or had no cable, so a stale cache entry read
as evidence that the address was reachable. That is the belief someone is checking when they run this
command.

Now:
* `Device.learnArp(ip, mac, portName)` is the single entry point and records the port in `arpPorts`; all
  three simulator call sites pass `inIface`, so a future call site cannot forget it.
* `show arp` prints the port, and appends the reason when it can no longer carry a frame - `(administratively
  down)`, `(down: no cable)`, `(down: link down)`, `(down: peer shut down)`. The reason is part of the cell
  because "down" alone sends you looking for a cable when the cable is fine and the far port is shut.
* the entry is NOT deleted when the port goes down: a real cache does not empty when a cable is pulled, and
  the state is what marks it stale.
* an entry with no recorded port (a topology restored from an older file) prints `-` rather than a guess;
  a port that no longer exists prints its name and `(gone)`.
* `Age (min)` stays `-`, and the docs now say why: the simulator counts steps, not minutes.
* rows are sorted numerically, so 10.0.0.9 comes before 10.0.0.10 rather than after it.

test/show-arp.test.js (28 checks): both neighbours listed; every row carries as many columns as the header;
the interface printed is the port the engine recorded, facing the switch; the hardware address matches the
table the data plane uses; numeric sort; a shut port marks the entry and keeps it; a pulled cable marks it
with a different reason; a restored entry prints `-`; a vanished port prints `(gone)`; a device with no
topology names the port and invents no state; and re-learning moves the port. Reverting engine/cli.js fails
16 of the 28.

Suite: 140 suites, 6,021 assertions, 0 failed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-09 19:07:18 +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!1254
No description provided.