Count the timers: a lab can now be asked what it does at t=5 s #1050

Merged
jaylouisw merged 1 commit from feat/convergence-timing into main 2026-11-08 08:21:07 +00:00
Owner

Every timer in this engine was validated and then discarded. forward-delay 15, hello 10,
dead 40, advertise 1 were parsed, range-checked (engine/ospf.js even rejects dead < hello),
and then counted for nothing — because computeStp() blocked its ports and computeOspf()
installed its routes at t=0.

A lab could therefore only ever show the converged answer. The interval a technician actually
watches — link light green, nothing passing — could not be reproduced.

The model

engine/convergence.js answers one question in milliseconds: when is this process done? It is
pure — configuration in, times out, no clock, no state, no side effects.

Process Ready at
STP two forward delays (Listening, then Learning) — 30 s at the 802.1D default
OSPF hello + exchange for the adjacency, then the SPF hold — 16 s at defaults
DHCP the four-message exchange — 1 s
VRRP 3 × Advertisement_Interval + Skew_Time — 3.6 s at priority 100

Simulator.setRunTime(ms) selects the instant. Infinity is the default, so every existing lab
and test behaves exactly as before; the suite confirms it, and that required the second bug fix
below.

Unfinished processes leave their device in the state the standard puts it in, not in a special
simulation state:

SW1#converge
Process   Device                 Ready   Basis
stp       SW1                    30000 ms  listening + learning (15 s forward-delay each)

Fully converged at 30000 ms.
SW1#ping 10.0.0.2 1 at 5000
Success rate is 0 percent (0/1)
% Still converging at t=5000 ms: stp on SW1 (ready at 30000 ms)

That last line matters more than it looks. Request timed out and the spanning tree is still learning are the same three dots in a timeline and mean opposite things — one is a broken lab, the
other is a working lab that is not up yet.

Ping replies also print a real millisecond time now (time=0.307 ms), from propagation in each
medium, serialisation from frame size and line rate, and store-and-forward per hop, rather than a
hop count wearing a time= label.

Two bugs the tests caught while writing them

  • reset() rewound the run instant. My first patch landed in reset(), and ping() calls
    reset() before doing anything — so every run silently set itself back to "converged" and the
    feature did nothing. Caught by the gated-lab test asserting a port is Listening at t=5 s.
  • ping({ atMs }) was documented and not read. Rather than soften docs/CONVERGENCE.md, the
    engine honours it, and a test pins that it is not silently ignored.

Test

test/convergence-timing.test.js — 62 assertions: the timer arithmetic against the standards
(including learnEndMs and priority 255 with no skew), the schedule's ordering and completeness, a
switch that drops a ping at 5 s and 20 s and answers at 30 s, two OSPF routers whose far subnet is
unreachable at 8 s and reachable at 20 s, the CLI forms, and the pinning of the Infinity default.

What is deliberately not modelled

Stated in docs/CONVERGENCE.md rather than left to be discovered: no real-time interleaving (a
question is answered as of an instant; nothing runs a clock during a run), no hello loss or
dead-interval expiry, no re-convergence after a topology change, no STP role changes over time, no
cable pulled mid-convergence. A timing feature that overstates itself is worse than no timing
feature.

97 suites, 4740 assertions, all passing.

Closes #1049.

Every timer in this engine was validated and then discarded. `forward-delay 15`, `hello 10`, `dead 40`, `advertise 1` were parsed, range-checked (`engine/ospf.js` even rejects `dead < hello`), and then counted for nothing — because `computeStp()` blocked its ports and `computeOspf()` installed its routes at t=0. A lab could therefore only ever show the converged answer. The interval a technician actually watches — link light green, nothing passing — could not be reproduced. ## The model `engine/convergence.js` answers one question in milliseconds: **when is this process done?** It is pure — configuration in, times out, no clock, no state, no side effects. | Process | Ready at | |---|---| | STP | two forward delays (Listening, then Learning) — 30 s at the 802.1D default | | OSPF | hello + exchange for the adjacency, then the SPF hold — 16 s at defaults | | DHCP | the four-message exchange — 1 s | | VRRP | 3 × Advertisement_Interval + Skew_Time — 3.6 s at priority 100 | `Simulator.setRunTime(ms)` selects the instant. **`Infinity` is the default**, so every existing lab and test behaves exactly as before; the suite confirms it, and that required the second bug fix below. Unfinished processes leave their device in the state the *standard* puts it in, not in a special simulation state: ``` SW1#converge Process Device Ready Basis stp SW1 30000 ms listening + learning (15 s forward-delay each) Fully converged at 30000 ms. ``` ``` SW1#ping 10.0.0.2 1 at 5000 Success rate is 0 percent (0/1) % Still converging at t=5000 ms: stp on SW1 (ready at 30000 ms) ``` That last line matters more than it looks. `Request timed out` and `the spanning tree is still learning` are the same three dots in a timeline and mean opposite things — one is a broken lab, the other is a working lab that is not up yet. Ping replies also print a real millisecond time now (`time=0.307 ms`), from propagation in each medium, serialisation from frame size and line rate, and store-and-forward per hop, rather than a hop count wearing a `time=` label. ## Two bugs the tests caught while writing them - **`reset()` rewound the run instant.** My first patch landed in `reset()`, and `ping()` calls `reset()` before doing anything — so every run silently set itself back to "converged" and the feature did nothing. Caught by the gated-lab test asserting a port is Listening at t=5 s. - **`ping({ atMs })` was documented and not read.** Rather than soften `docs/CONVERGENCE.md`, the engine honours it, and a test pins that it is not silently ignored. ## Test `test/convergence-timing.test.js` — 62 assertions: the timer arithmetic against the standards (including `learnEndMs` and priority 255 with no skew), the schedule's ordering and completeness, a switch that drops a ping at 5 s and 20 s and answers at 30 s, two OSPF routers whose far subnet is unreachable at 8 s and reachable at 20 s, the CLI forms, and the pinning of the `Infinity` default. ## What is deliberately not modelled Stated in `docs/CONVERGENCE.md` rather than left to be discovered: no real-time interleaving (a question is answered *as of* an instant; nothing runs a clock during a run), no hello loss or dead-interval expiry, no re-convergence after a topology change, no STP role changes over time, no cable pulled mid-convergence. A timing feature that overstates itself is worse than no timing feature. **97 suites, 4740 assertions, all passing.** Closes #1049.
Control planes take time now: the timers were parsed and then thrown away
Some checks are pending
CI / Test (Node 18) (pull_request) Has started running
CI / Test (Node 22) (pull_request) Has started running
CI / Server smoke test (pull_request) Has started running
CI / Docker build (pull_request) Successful in 52s
CI / Test (Node 20) (pull_request) Has started running
4dbe885c3a
Every timer in this engine was validated and then discarded. forward-delay 15, hello 10, dead 40
were range-checked, stored, and never counted, because computeStp() blocked its ports and
computeOspf() installed its routes at t=0. The effect: a lab could only ever show the converged
answer. You could not power a switch on and watch the seconds where the link light is green and
nothing passes, which is the first thing a technician meets on real gear, and it is half of what
Packet Tracer teaches.

engine/convergence.js answers one question in milliseconds - when is this process done - and is
pure: it reads configuration and returns times, no clock, no state, no side effects.

- STP: a port destined to forward sits in Listening for one forward delay then Learning for
  another, and drops traffic in both (802.1D defaults, 15 s each). A port destined to block is
  Blocking from t=0, which is what it is.
- OSPF: adjacency at hello + exchange, routes after the SPF hold.
- DHCP: nothing until the four-message exchange completes.
- VRRP: the VIP is not answered for 3 x Advertisement_Interval + Skew_Time (RFC 5798).

Simulator.setRunTime(ms) selects the instant; Infinity is the default and leaves every existing lab
and test behaving exactly as before. A process that has not finished leaves its device in the state
the standard puts it in rather than a special simulation state.

A failed ping now says why. "Request timed out" and "the spanning tree is still learning" look
identical in a timeline and mean opposite things:

  SW1#ping 10.0.0.2 1 at 5000
  Success rate is 0 percent (0/1)
  % Still converging at t=5000 ms: stp on SW1 (ready at 30000 ms)

Replies also print a real millisecond time now - propagation from each medium's velocity,
serialisation from frame size and line rate, store-and-forward per hop - instead of a hop count
wearing the label "time".

Two bugs found by the tests while writing them, both of which would have made the feature silently
useless: the first patch put runAtMs in reset() rather than the constructor, and ping() calls
reset() first, so every run rewound itself to "converged"; and ping({atMs}) was documented but never
read, so the engine now honours it rather than the doc being softened.

test/convergence-timing.test.js: 62 assertions over the timer arithmetic, the schedule, the gated
lab (a switch that drops a ping at 5 s and 20 s and answers at 30 s), OSPF routes that appear only
after SPF, and the CLI output. Defaults are pinned: an untouched Simulator still runs converged.

docs/CONVERGENCE.md states what is NOT modelled - no real-time interleaving, no hello loss or
dead-interval expiry, no re-convergence after a topology change - because a timing feature that
overstates itself is worse than none.

97 suites, 4740 assertions, all passing.

Closes #1049.
jaylouisw deleted branch feat/convergence-timing 2026-11-08 08:21:08 +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!1050
No description provided.