One tally, printed twice, and a summary you can read back (#1417) #1418

Merged
jaylouisw merged 1 commit from fix/counters-and-summary into main 2026-11-11 03:36:17 +00:00
Owner

Closes #1417.

The guard that was missing. The per-port counters live in the engine's flow state, published by fullState() as runtime[id].counters.ports, and are printed by show interfaces one block per port. Six pairs of surfaces in this repository have drifted apart after being written twice (port state, PoE, the routes table, the switchport sentence, show arp, show vrrp); counters had no test comparing them at all, and web/app.js does not read them yet, so a disagreement would have been discovered by whoever writes the next table.

test/counters-agreement.test.js (32 checks) compares the two directly, engine-only so it is deterministic:

  • a clean crossing - three pings, both ports counted, and the two numbers are literally the same number;
  • a flooded frame - the frame left more than one port and every port agrees;
  • a policy refusal - the drop lands on the ingress port, with a reason on both sides;
  • a shut port - zero on both sides, not absent from one;
  • a reset - flow.resetFlowState() zeroes the console and the payload together;
  • every switch in the catalogue with a console - one block per interface, nothing counted when nothing crossed;
  • and the reverse direction: a port the payload counts is a port the console prints.

The defect that fell out of writing it. A drop summary is one bracketed list of reasons, and a reason is prose that can bring its own brackets:

before:  2 drops (ACL 101 denied (in) x2)          <- the list closes early, and nests
 after:  2 drops ("ACL 101 denied (in)" x2)

A reason that brings brackets is now quoted, so a summary is one level deep whatever the reason says. The suite reads a summary back into exactly the reasons and counts the payload recorded, and checks a reason with no brackets is not quoted for nothing.

Three existing assertions pinned the old rendering; they now accept either, because what they check is that the reason and its count are present - not the punctuation.

Evidence. 32 checks; with engine/cli.js reverted the quoting assertion fails (31/1). Suite: 209 suites, 8,021 assertions, 0 failed; syntax 277 files OK. Docs: docs/CLI.md under "What the port threw away".

Closes #1417. **The guard that was missing.** The per-port counters live in the engine's flow state, published by `fullState()` as `runtime[id].counters.ports`, and are printed by `show interfaces` one block per port. Six pairs of surfaces in this repository have drifted apart after being written twice (port state, PoE, the routes table, the switchport sentence, `show arp`, `show vrrp`); counters had no test comparing them at all, and `web/app.js` does not read them yet, so a disagreement would have been discovered by whoever writes the next table. `test/counters-agreement.test.js` (32 checks) compares the two directly, engine-only so it is deterministic: - a clean crossing - three pings, both ports counted, and the two numbers are literally the same number; - a flooded frame - the frame left more than one port and every port agrees; - a policy refusal - the drop lands on the ingress port, with a reason on both sides; - a shut port - zero on both sides, not absent from one; - a reset - `flow.resetFlowState()` zeroes the console and the payload together; - every switch in the catalogue with a console - one block per interface, nothing counted when nothing crossed; - and the reverse direction: a port the payload counts is a port the console prints. **The defect that fell out of writing it.** A drop summary is one bracketed list of reasons, and a reason is prose that can bring its own brackets: ``` before: 2 drops (ACL 101 denied (in) x2) <- the list closes early, and nests after: 2 drops ("ACL 101 denied (in)" x2) ``` A reason that brings brackets is now quoted, so a summary is one level deep whatever the reason says. The suite reads a summary back into exactly the reasons and counts the payload recorded, and checks a reason with no brackets is not quoted for nothing. Three existing assertions pinned the old rendering; they now accept either, because what they check is that the reason and its count are present - not the punctuation. **Evidence.** 32 checks; with `engine/cli.js` reverted the quoting assertion fails (31/1). Suite: **209 suites, 8,021 assertions, 0 failed**; syntax 277 files OK. Docs: `docs/CLI.md` under "What the port threw away".
One tally, printed twice, and a summary you can read back (#1417)
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 2m42s
CI / Test (Node 18) (pull_request) Successful in 2m52s
CI / Server smoke test (pull_request) Successful in 24s
CI / Docker build (pull_request) Successful in 42s
CI / Test (Node 22) (pull_request) Successful in 2m31s
a816e504e4
The per-port counters exist in two places: the engine's flow state, which fullState() publishes as runtime[id].counters.ports, and show interfaces, which prints one block per port. Every other pair of surfaces in this codebase that reimplemented one rule had drifted - port state, PoE, the routes table, the switchport sentence - and counters had no guard at all, because web/app.js does not read them yet: an agreement bug here would be found by whoever writes the next table, not by us.

test/counters-agreement.test.js compares the two directly (21 checks, engine-only, so deterministic), over the five ways a frame can end: a clean crossing, a flooded frame, a policy refusal, a shut port, and a reset - then over every switch in the catalogue with a console (one block per interface, nothing counted when nothing crossed). Port by port and reason by reason, the console and the payload must be the same numbers.

Writing that comparison found the second thing. A drop summary is one bracketed list of reasons, and a reason is prose that can bring its own brackets: '2 drops (ACL 101 denied (in) x2)' closes the list early for anyone reading it as a list. A reason that brings brackets is now quoted - '2 drops ("ACL 101 denied (in)" x2)' - so the summary is one level deep whatever the reason says, and the new section reads a summary back into exactly the reasons and counts the payload recorded (and checks a reason with no brackets is not quoted for nothing).

Three existing assertions pinned the old rendering; they now accept either, since what they check is that the reason and its count are present.

Evidence: test/counters-agreement.test.js 32 checks. With engine/cli.js reverted, the quoting assertion fails (31/1). Suite: 209 suites, 8,021 assertions, 0 failed; syntax 277 files OK.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-11 03:36:14 +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!1418
No description provided.