A ping over HTTP can be asked at an instant, and its packets are counted (#1381) #1382

Merged
jaylouisw merged 1 commit from feat/ping-instant into main 2026-11-10 20:42:58 +00:00
Owner

POST /ping could not be asked at an instant, and its packets were counted nowhere. Fixes #1381.

Simulator.ping() has honoured opts.atMs since convergence was modelled, and the console spells it
ping <address> at <ms>. The endpoint dropped both the instant and the accounting.

1. The instant

Every HTTP ping was asked at Infinity, so on a lab that is still converging you could not ask — through the API or
the UI — "will this work in five seconds?", the one question the convergence model exists to answer. Measured on a
switch whose access ports listen for 30 s, the API answered success at t=0 where the console answers converging.

Now atMs is read, validated (400 E_BAD_INSTANT for anything that is not a time at or after 0), and passed
through; the answer reports runAtMs so it cannot be mistaken for an answer about another moment. atMs: 0 is
legal — it is a time, not a missing value.

2. The accounting

The endpoint ran new Simulator(topo) — a second simulator with its own flow state — so the frames a ping sent were
invisible to /flows, while the same ping typed into the console was counted. That is defect #1335, fixed for the
console endpoint in #1337 and left standing here.

Now the ping runs on simForFlows(topo): one board, one accounting. Its frames land in the port tallies /flows
reports and show interfaces prints, and the answer carries those counters back rather than a second set.

The device totals in counters are flow accounting — transport payload — so ICMP deliberately does not move them;
the port tallies are interface accounting and count every frame. That split is now written down in
docs/ARCHITECTURE.md, because it cost me a false start: my first version of the test asserted on the device totals
and read as a defect in the ping when it was the documented behaviour working as intended.

Evidence

test/ping-instant.test.js — 22 checks, each question asked on its own board so no answer can depend on how
many questions came before it:

  • at t=0 the API answers reason: "converging" with convergingUntilMs: 30000 and runAtMs: 0; at t=60000 the
    same ping succeeds and reports runAtMs: 60000;
  • the console, on a board of its own, says the same thing at the same instant;
  • -1, "abc" and {} are 400 E_BAD_INSTANT; 0 is accepted;
  • before a ping the host has carried nothing as far as /flows knows; after a three-echo ping its port tally is at
    least 3 packets with non-zero bytes; the ping answer's counters are the same number /flows reports, and so is
    the N packets output line show interfaces prints;
  • and a ping typed into the console lands in the same tally.

Reverting server/index.js fails 10 of 22 — the instant assertions and the accounting ones.

docs/ARCHITECTURE.md gains the atMs contract, runAtMs, and the flow-vs-interface accounting split.

Suite: 194 suites, 7,466 assertions, 0 failed. Syntax: 262 files, OK.

`POST /ping` could not be asked at an instant, and its packets were counted nowhere. Fixes #1381. `Simulator.ping()` has honoured `opts.atMs` since convergence was modelled, and the console spells it `ping <address> at <ms>`. The endpoint dropped both the instant and the accounting. ## 1. The instant Every HTTP ping was asked at *Infinity*, so on a lab that is still converging you could not ask — through the API or the UI — "will this work in five seconds?", the one question the convergence model exists to answer. Measured on a switch whose access ports listen for 30 s, the API answered `success` at t=0 where the console answers `converging`. Now `atMs` is read, validated (`400 E_BAD_INSTANT` for anything that is not a time at or after 0), and passed through; the answer reports **`runAtMs`** so it cannot be mistaken for an answer about another moment. `atMs: 0` is legal — it is a time, not a missing value. ## 2. The accounting The endpoint ran `new Simulator(topo)` — a second simulator with its own flow state — so the frames a ping sent were invisible to `/flows`, while the same ping typed into the console was counted. That is defect #1335, fixed for the console endpoint in #1337 and left standing here. Now the ping runs on `simForFlows(topo)`: one board, one accounting. Its frames land in the port tallies `/flows` reports and `show interfaces` prints, and the answer carries those counters back rather than a second set. The device totals in `counters` are *flow* accounting — transport payload — so ICMP deliberately does not move them; the port tallies are *interface* accounting and count every frame. That split is now written down in `docs/ARCHITECTURE.md`, because it cost me a false start: my first version of the test asserted on the device totals and read as a defect in the ping when it was the documented behaviour working as intended. ## Evidence `test/ping-instant.test.js` — **22 checks**, each question asked on **its own board** so no answer can depend on how many questions came before it: * at t=0 the API answers `reason: "converging"` with `convergingUntilMs: 30000` and `runAtMs: 0`; at t=60000 the same ping succeeds and reports `runAtMs: 60000`; * the console, on a board of its own, says the same thing at the same instant; * `-1`, `"abc"` and `{}` are `400 E_BAD_INSTANT`; `0` is accepted; * before a ping the host has carried nothing as far as `/flows` knows; after a three-echo ping its port tally is at least 3 packets with non-zero bytes; the ping answer's counters are **the same number** `/flows` reports, and so is the `N packets output` line `show interfaces` prints; * and a ping typed into the console lands in the same tally. Reverting `server/index.js` fails **10 of 22** — the instant assertions and the accounting ones. `docs/ARCHITECTURE.md` gains the `atMs` contract, `runAtMs`, and the flow-vs-interface accounting split. Suite: **194 suites, 7,466 assertions, 0 failed**. Syntax: 262 files, OK.
A ping over HTTP can be asked at an instant, and its packets are counted (#1381)
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 2m38s
CI / Test (Node 18) (pull_request) Successful in 2m49s
CI / Server smoke test (pull_request) Successful in 29s
CI / Docker build (pull_request) Successful in 54s
CI / Test (Node 22) (pull_request) Failing after 2m39s
2beb282704
POST /ping took `{src, dst, count}` and nothing else. Two things were missing from that.

The instant. Simulator.ping() has honoured `opts.atMs` since convergence was modelled, and the console
spells it `ping <address> at <ms>`. The endpoint never read it, so every HTTP ping was asked at Infinity:
on a lab that is still converging you could not ask, through the API or the UI, "will this work in five
seconds?" - the one question the convergence model exists to answer. Measured on a switch whose access
ports listen for 30 s, the API answered `success` at t=0 where the console answers `converging`. Now atMs
is read, validated (400 E_BAD_INSTANT for anything that is not a time at or after 0), and passed through,
and the answer reports runAtMs so it cannot be mistaken for an answer about another moment. atMs 0 is
legal: it is a time, not a missing value.

The accounting. The endpoint ran `new Simulator(topo)` - a second simulator with its own flow state - so
the frames a ping sent were invisible to /flows, while the same ping typed into the console was counted.
That is defect #1335, fixed for the console endpoint in #1337 and left standing here. Now the ping runs on
simForFlows(topo): one board, one accounting. Its frames land in the port tallies /flows reports and
`show interfaces` prints, and the answer carries those counters back rather than a second set.

The device totals in `counters` are flow accounting (transport payload), so ICMP deliberately does not
move them; the port tallies are interface accounting and count every frame. That split is written down in
docs/ARCHITECTURE.md, because it cost me a false start: my first test asserted on the device totals and
read as a defect in the ping when it was the documented behaviour.

Evidence: test/ping-instant.test.js, 22 checks, each question asked on its own board so no answer depends
on how many questions came before it - at t=0 the API answers reason "converging" with
convergingUntilMs 30000 and runAtMs 0; at t=60000 the same ping succeeds and reports runAtMs 60000; the
console says the same thing at the same instant; -1/"abc"/{} are 400 E_BAD_INSTANT and 0 is accepted;
before a ping the host has carried nothing as far as /flows knows, and after a three-echo ping its port
tally is at least 3 packets with non-zero bytes; the ping answer's counters are the same number /flows
reports and the same `N packets output` line `show interfaces` prints; and a console ping lands in the
same tally. Reverting server/index.js fails 10 of 22.

Suite: 194 suites, 7,466 assertions, 0 failed. Syntax: 262 files, OK.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-10 20:42:54 +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!1382
No description provided.