A learned MAC is not here for ever (#1395) #1396

Merged
jaylouisw merged 1 commit from feat/mac-ageing into main 2026-11-10 23:13:12 +00:00
Owner

A learned MAC is not here for ever. Fixes #1395.

The switch table had no timestamps at all. An entry stayed until its port changed VLAN or the lab was reloaded —
which is why show mac address-table had to append a note saying the row might be stale, and why its own source
comment said "real switches age entries out, this one does not".

The simulator has had an instant in milliseconds since convergence was modelled, so an entry can be stamped with when
it was heard and aged against the question being asked:

learned at t=60 s     present at 200 s (140 s silent)     gone at 400 s (340 s silent)
heard again at 250 s  present at 500 s                    the age is silence, not a lifetime

What changed

  • Device.learnMac(vid, mac, port, atMs) — one writer, storing { port, atMs }.
  • Device.macLookup(vid, mac, nowMs) — the aged reader. An entry older than MAC_AGE_MS (300 s, named once)
    answers nothing, and the forwarding decision uses it: a frame is never sent to a port the table only
    remembers; when the lookup answers nothing the frame floods, exactly as for an address never seen. The timeline's
    "forward or flood" reading asks the same lookup, so the record and the decision cannot disagree.
  • Device.ageMacs(nowMs) — the sweep the report runs, so a long run does not carry a table of addresses nobody
    has spoken from since the first second.
  • show mac address-table gains an Age column (140s), and rows leave when they age out. No instant means no
    ageing, which is exactly what every caller got before.
  • An entry with no timestamp — a fixture's, an imported lab's, an older caller's — is never aged and reports -.
    The payload still publishes runtime[id].macTable as address -> port; the rows in runtime[id].mac carry the age.

Two defects the change itself found, both caught by the existing suite

  • flushMacsOnPort() read where.name, so once an entry became { port, atMs } a flush matched nothing and
    silently dropped zero entries — a port changing VLAN kept every stale row. It reads port now, and still
    tolerates an interface object.
  • the audit line recording forwarded or flooded read table.has(...) beside the decision; it asks the aged lookup
    now.

Evidence

test/mac-ageing.test.js — 19 checks: the age of an entry at three instants, traffic refreshing it (440 s after
it was first learned it is still there), the aged lookup answering null, a frame flooding when nothing is
remembered (proven by stubbing the one method the decision reads), hand-written entries never ageing, and per-VLAN
rows listed once.

Reverting engine/device.js fails 2, engine/simulator.js 6 (the printout shows age: "-" at every instant
and the row surviving 340 s of silence), engine/cli.js 5.

test/mac-table.test.js reads the five-column table through one PORT constant and gains an assertion that an
undated entry reports no age. docs/CLI.md gains "What the MAC table remembers, and for how long";
docs/ARCHITECTURE.md records the age and why the payload shape is unchanged.

Suite: 200 suites, 7,699 assertions, 0 failed. Syntax: 268 files, OK.

A learned MAC is not here for ever. Fixes #1395. The switch table had no timestamps at all. An entry stayed until its port changed VLAN or the lab was reloaded — which is why `show mac address-table` had to append a note saying the row might be stale, and why its own source comment said *"real switches age entries out, this one does not"*. The simulator has had an instant in milliseconds since convergence was modelled, so an entry can be stamped with when it was heard and aged against the question being asked: ``` learned at t=60 s present at 200 s (140 s silent) gone at 400 s (340 s silent) heard again at 250 s present at 500 s the age is silence, not a lifetime ``` ## What changed * **`Device.learnMac(vid, mac, port, atMs)`** — one writer, storing `{ port, atMs }`. * **`Device.macLookup(vid, mac, nowMs)`** — the aged reader. An entry older than `MAC_AGE_MS` (300 s, named once) answers nothing, and the **forwarding decision uses it**: a frame is never sent to a port the table only remembers; when the lookup answers nothing the frame floods, exactly as for an address never seen. The timeline's "forward or flood" reading asks the same lookup, so the record and the decision cannot disagree. * **`Device.ageMacs(nowMs)`** — the sweep the report runs, so a long run does not carry a table of addresses nobody has spoken from since the first second. * **`show mac address-table`** gains an `Age` column (`140s`), and rows leave when they age out. No instant means no ageing, which is exactly what every caller got before. * An entry with **no timestamp** — a fixture's, an imported lab's, an older caller's — is never aged and reports `-`. The payload still publishes `runtime[id].macTable` as address -> port; the rows in `runtime[id].mac` carry the age. ## Two defects the change itself found, both caught by the existing suite * `flushMacsOnPort()` read `where.name`, so once an entry became `{ port, atMs }` a flush matched **nothing** and silently dropped zero entries — a port changing VLAN kept every stale row. It reads `port` now, and still tolerates an interface object. * the audit line recording *forwarded or flooded* read `table.has(...)` beside the decision; it asks the aged lookup now. ## Evidence `test/mac-ageing.test.js` — **19 checks**: the age of an entry at three instants, traffic refreshing it (440 s after it was first learned it is still there), the aged lookup answering `null`, a frame flooding when nothing is remembered (proven by stubbing the one method the decision reads), hand-written entries never ageing, and per-VLAN rows listed once. Reverting `engine/device.js` fails **2**, `engine/simulator.js` **6** (the printout shows `age: "-"` at every instant and the row surviving 340 s of silence), `engine/cli.js` **5**. `test/mac-table.test.js` reads the five-column table through one `PORT` constant and gains an assertion that an undated entry reports no age. `docs/CLI.md` gains "What the MAC table remembers, and for how long"; `docs/ARCHITECTURE.md` records the age and why the payload shape is unchanged. Suite: **200 suites, 7,699 assertions, 0 failed**. Syntax: 268 files, OK.
A learned MAC is not here for ever (#1395)
Some checks failed
CI / Classify the change (pull_request) Successful in 11s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 15s
CI / Test (Node 20) (pull_request) Successful in 2m33s
CI / Test (Node 18) (pull_request) Successful in 2m39s
CI / Server smoke test (pull_request) Successful in 32s
CI / Docker build (pull_request) Successful in 46s
CI / Test (Node 22) (pull_request) Failing after 2m33s
af9a049995
The switch table had no timestamps at all. An entry stayed until its port changed VLAN or the lab was
reloaded - which is why `show mac address-table` had to append a note saying the row might be stale, and
why its own source comment said "real switches age entries out, this one does not".

The simulator has had an instant in milliseconds since convergence was modelled, so an entry can be
stamped with when it was heard and aged against the question being asked:

  learned at t=60 s    present at 200 s (140 s silent)     gone at 400 s (340 s silent)
  heard again at 250 s  present at 500 s                    the age is silence, not a lifetime

Fixed:

* `Device.learnMac(vid, mac, port, atMs)` - one writer, storing `{ port, atMs }`.
* `Device.macLookup(vid, mac, nowMs)` - the aged reader. An entry older than MAC_AGE_MS (300 s, named
  once) answers nothing, and the forwarding decision uses it, so a frame is never sent to a port the
  table only remembers: when the lookup answers nothing the frame floods, exactly as it does for an
  address never seen. The timeline's "forward or flood" reading asks the same lookup, so the record and
  the decision cannot disagree.
* `Device.ageMacs(nowMs)` - the sweep the report runs, so a long run does not carry a table of addresses
  nobody has spoken from since the first second.
* `show mac address-table` gains an Age column ("140s"), and rows leave when they age out. No instant
  means no ageing, which is exactly what every caller got before.
* An entry with no timestamp - a fixture's, an imported lab's, an older caller's - is never aged and
  reports `-`. That is the honest reading: nothing recorded when it was seen, so the engine does not
  invent an age for it. The payload still publishes `runtime[id].macTable` as address -> port; the rows
  in `runtime[id].mac` carry the age.

Two defects found by the change itself, both caught by the existing suite:

* `flushMacsOnPort()` read `where.name`, so once an entry became `{ port, atMs }` a flush matched nothing
  and silently dropped zero entries - a port changing VLAN kept every stale row. It reads `port` now and
  still tolerates an interface object.
* the audit line that records whether a frame was forwarded or flooded read `table.has(...)` beside the
  decision; it asks the aged lookup now.

Evidence: test/mac-ageing.test.js, 19 checks - the age of an entry at three instants, traffic refreshing
it, the aged lookup answering null, a frame flooding when nothing is remembered (proven by stubbing the
one method the decision reads), hand-written entries never ageing, and per-VLAN rows. Reverting
engine/device.js fails 2, engine/simulator.js 6, engine/cli.js 5. test/mac-table.test.js reads the
five-column table through one PORT constant and gains an assertion that an undated entry reports no age.

Suite: 200 suites, 7,699 assertions, 0 failed. Syntax: 268 files, OK.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-10 23:13:09 +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!1396
No description provided.