The Age column is a number, and an old neighbour is not a neighbour (#1397) #1398

Merged
jaylouisw merged 1 commit from feat/arp-ageing into main 2026-11-10 23:33:04 +00:00
Owner

The Age column is a number, and an old neighbour is not a neighbour. Fixes #1397.

show arp printed Age (min) as a header over a hard-coded - on every row, and said why in the code and in
docs/CLI.md: "the simulator counts steps, not minutes". That stopped being true when convergence gave the model an
instant in milliseconds — and that instant already ages the MAC table (#1395).

ARP_AGE_MS = 14,400 s, the IOS default `arp timeout`
learned at t=10 min    present at 30 min, aged 20     gone at 5 h
a reply re-learns       using an entry does not (a cache hit is not hearing)

What changed

  • Device.learnArp(ip, mac, port, atMs) stamps when the neighbour was heard. The instant lives in a parallel
    arpSeenAt map, so arp stays address → MAC for every reader and fixture that has ever written one.
  • Device.arpLookup(ip, nowMs) — the aged reader, and the egress path uses it: a stale entry resolves to
    nothing, so the frame is ARP'd for instead of being sent to a neighbour that has moved.
  • Device.ageArps(nowMs) — one sweep, dropping the address, the port and the instant together.
  • show arp prints minutes since the neighbour was heard, and rows leave when they age out. - now means
    nothing dated this entry — which is exactly what a fixture or an imported lab produces — and such an entry is
    never aged, because inventing an age for it would be worse than saying nothing.

Documentation corrected while there

docs/SIMULATION.md still said "nothing ages it: no MAC ageing timer, no ARP timeout" (wrong since #1395 as well)
and listed ARP cache ageing under Absent. The MAC row there now states the age and the forwarding rule, the ARP
row moved to Modelled, and the LLDP note no longer claims the model has no clock to age a neighbour with.

Evidence

test/arp-ageing.test.js — 31 checks: the age in minutes at two instants, the row gone at 6 h with the address,
the port and the lookup all cleared, a reply re-learning it (and a cache hit not refreshing the age), the data plane
ARPing again instead of using a stale neighbour — measured in the same ping's event list, before and after: cache
hits and no ARP frames while fresh, no cache hits and ARP frames once aged, and the ping still succeeding because
ARP answers — undated entries never ageing, and a sweep that drops only what aged.

Reverting engine/cli.js fails 6; engine/simulator.js fails 8; engine/device.js stops the suite at the
first ping (arpLookup is gone). test/runtime-agreement.test.js reads the new row shape (null, printed as -).

Suite: 201 suites, 7,730 assertions, 0 failed. Syntax: 269 files, OK.

The Age column is a number, and an old neighbour is not a neighbour. Fixes #1397. `show arp` printed `Age (min)` as a header over a hard-coded `-` on every row, and said why in the code and in `docs/CLI.md`: *"the simulator counts steps, not minutes"*. That stopped being true when convergence gave the model an instant in milliseconds — and that instant already ages the MAC table (#1395). ``` ARP_AGE_MS = 14,400 s, the IOS default `arp timeout` learned at t=10 min present at 30 min, aged 20 gone at 5 h a reply re-learns using an entry does not (a cache hit is not hearing) ``` ## What changed * **`Device.learnArp(ip, mac, port, atMs)`** stamps when the neighbour was heard. The instant lives in a parallel `arpSeenAt` map, so `arp` stays address → MAC for every reader and fixture that has ever written one. * **`Device.arpLookup(ip, nowMs)`** — the aged reader, and **the egress path uses it**: a stale entry resolves to nothing, so the frame is ARP'd for instead of being sent to a neighbour that has moved. * **`Device.ageArps(nowMs)`** — one sweep, dropping the address, the port and the instant together. * **`show arp`** prints minutes since the neighbour was heard, and rows leave when they age out. `-` now means *nothing dated this entry* — which is exactly what a fixture or an imported lab produces — and such an entry is never aged, because inventing an age for it would be worse than saying nothing. ## Documentation corrected while there `docs/SIMULATION.md` still said *"nothing ages it: no MAC ageing timer, no ARP timeout"* (wrong since #1395 as well) and listed ARP cache ageing under **Absent**. The MAC row there now states the age and the forwarding rule, the ARP row moved to **Modelled**, and the LLDP note no longer claims the model has no clock to age a neighbour with. ## Evidence `test/arp-ageing.test.js` — **31 checks**: the age in minutes at two instants, the row gone at 6 h with the address, the port and the lookup all cleared, a reply re-learning it (and a cache hit not refreshing the age), the data plane ARPing again instead of using a stale neighbour — measured in the same ping's event list, before and after: cache hits and no ARP frames while fresh, no cache hits and ARP frames once aged, and the ping still succeeding because ARP answers — undated entries never ageing, and a sweep that drops only what aged. Reverting `engine/cli.js` fails **6**; `engine/simulator.js` fails **8**; `engine/device.js` stops the suite at the first ping (`arpLookup` is gone). `test/runtime-agreement.test.js` reads the new row shape (`null`, printed as `-`). Suite: **201 suites, 7,730 assertions, 0 failed**. Syntax: 269 files, OK.
The Age column is a number, and an old neighbour is not a neighbour (#1397)
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 14s
CI / Test (Node 20) (pull_request) Successful in 2m45s
CI / Test (Node 18) (pull_request) Successful in 2m54s
CI / Server smoke test (pull_request) Successful in 30s
CI / Docker build (pull_request) Successful in 39s
CI / Test (Node 22) (pull_request) Successful in 2m18s
18679a7fd4
`show arp` printed `Age (min)` as a header over a hard-coded `-` on every row, and said why in the code and
in docs/CLI.md: "the simulator counts steps, not minutes". That stopped being true when convergence gave
the model an instant in milliseconds - and that instant already ages the MAC table (#1395).

    ARP_AGE_MS = 14,400 s, the IOS default `arp timeout`
    learned at t=10 min    present at 30 min, aged 20     gone at 5 h
    a reply re-learns       using an entry does not (a cache hit is not hearing)

Fixed:

* `Device.learnArp(ip, mac, port, atMs)` stamps when the neighbour was heard. The instant lives in a
  parallel `arpSeenAt` map so `arp` stays ip -> mac for every reader and fixture that ever wrote one.
* `Device.arpLookup(ip, nowMs)` - the aged reader, and the egress path uses it: a stale entry resolves to
  nothing, so the frame is ARP'd for instead of being sent to a neighbour that has moved.
* `Device.ageArps(nowMs)` - one sweep, dropping the address, the port and the instant together.
* `show arp` prints minutes since the neighbour was heard, and rows leave when they age out. `-` now means
  "nothing dated this entry", which is exactly what a fixture or an imported lab produces - and such an
  entry is never aged, because inventing an age for it would be worse than saying nothing.

Documentation corrected while there: docs/SIMULATION.md still said "nothing ages it: no MAC ageing timer,
no ARP timeout" (wrong since #1395 as well) and listed ARP cache ageing under **Absent**; the LLDP note
claimed the model had no clock to age a neighbour with.

Evidence: test/arp-ageing.test.js, 31 checks - the age in minutes at two instants, the row gone at 6 h
with the address, the port and the lookup all cleared, a reply re-learning it (and a cache hit not), the
data plane ARPing again instead of using a stale neighbour (measured: cache hits and ARP frames in the
same ping's event list, before and after), undated entries never ageing, and a sweep that drops only what
aged. Reverting engine/cli.js fails 6; engine/simulator.js fails 8; engine/device.js stops the suite at
the first ping. test/runtime-agreement.test.js reads the new row shape (null, printed as '-').

Suite: 201 suites, 7,730 assertions, 0 failed. Syntax: 269 files, OK.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-10 23:32:59 +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!1398
No description provided.