The packet log showed a bare token for 17 event types #1475

Closed
opened 2026-11-12 04:09:54 +00:00 by jaylouisw · 1 comment
Owner

The symptom

The packet log is the panel whose job is to explain what happened to a frame. Seventeen of the fifty-four event types the engine emits had no legend line, so they fell through to default: return e.type and the row read:

garp
vrrp
tap-inject-refused
flow-refused

Not an error, not a blank — a row that names a mechanism instead of saying what happened, in the one place a learner goes to find out. One of the seventeen was added the day before (the arp-conflict event in #1473), which is what made the cause obvious: nothing connected the engine's event vocabulary to the legend, so a new _emit({ type: … }) was silently a new bare token.

emitted types: 54      legend cases: 37      with no line: 17
arp-conflict  bgp-session  flow-close  flow-data  flow-open  flow-refused
flow-reset  forward  garp  lldp  nat-drop  nat-inbound  nat-outbound
split  tap  tap-inject-refused  vrrp

The fix

  • All seventeen get a sentence carrying the numbers and addresses the event actually has: a flow names both ends and its number, a VRRP election names the winner and the priority, a NAT refusal names the translation that failed, LLDP names who was discovered and on which port.
  • A case may only read fields its event carries. A sentence written against a remembered payload prints undefined in the panel meant to explain things, so the test reads each emit site's field list from the engine source and compares. It caught one immediately: flow-reset read e.proto, which that event does not carry — a reset is TCP by definition.
  • Duplicate addresses, NAT drops, refused tap injections and refused flows join the existing drop colour class instead of passing as ordinary chatter.
  • tap-inject-refused now carries a reason on the wire, so the log can say why the frame was not re-injected instead of only that it wasn't.
  • The legend is exposed as __pf.describeEvent, the same way the rest of the UI is exposed for tests.

The test that makes it stop happening

test/event-legend.test.js enumerates the vocabulary from engine/ rather than from a hand-written list: every _emit({ type: … }) and events.push({ type: … }) must have a case, no case may describe an event the engine no longer emits, no type may be described twice, and every real emit-site payload must render as a sentence rather than its bare type.

$ node test/event-legend.test.js                     # 54 event types, 105 emit sites
18 passed, 0 failed

$ git stash push web/app.js engine/simulator.js && node test/event-legend.test.js
8 passed, 10 failed     # and it names all seventeen missing types

The general rule, worth stating once: a view may not display a token it cannot explain. If the engine can emit it, the panel says what it means — and the connection between the two is a test, not a habit.

Neighbours green: ui-render 38, ui-dom-contract 19, ui-action-failures 13, arp-conflict 26, runtime-agreement 10, report-sweep 21. Syntax 304 files OK. Full suite: 236 suites, 8827 assertions, 0 failed.

## The symptom The packet log is the panel whose job is to explain what happened to a frame. Seventeen of the fifty-four event types the engine emits had no legend line, so they fell through to `default: return e.type` and the row read: ``` garp vrrp tap-inject-refused flow-refused ``` Not an error, not a blank — a row that names a mechanism instead of saying what happened, in the one place a learner goes to find out. One of the seventeen was added the day before (the `arp-conflict` event in #1473), which is what made the cause obvious: nothing connected the engine's event vocabulary to the legend, so a new `_emit({ type: … })` was silently a new bare token. ``` emitted types: 54 legend cases: 37 with no line: 17 arp-conflict bgp-session flow-close flow-data flow-open flow-refused flow-reset forward garp lldp nat-drop nat-inbound nat-outbound split tap tap-inject-refused vrrp ``` ## The fix - All seventeen get a sentence carrying the numbers and addresses the event actually has: a flow names both ends and its number, a VRRP election names the winner and the priority, a NAT refusal names the translation that failed, LLDP names who was discovered and on which port. - **A case may only read fields its event carries.** A sentence written against a remembered payload prints `undefined` in the panel meant to explain things, so the test reads each emit site's field list from the engine source and compares. It caught one immediately: `flow-reset` read `e.proto`, which that event does not carry — a reset is TCP by definition. - Duplicate addresses, NAT drops, refused tap injections and refused flows join the existing `drop` colour class instead of passing as ordinary chatter. - `tap-inject-refused` now carries a `reason` on the wire, so the log can say why the frame was not re-injected instead of only that it wasn't. - The legend is exposed as `__pf.describeEvent`, the same way the rest of the UI is exposed for tests. ## The test that makes it stop happening `test/event-legend.test.js` enumerates the vocabulary from `engine/` rather than from a hand-written list: every `_emit({ type: … })` and `events.push({ type: … })` must have a case, no case may describe an event the engine no longer emits, no type may be described twice, and every real emit-site payload must render as a sentence rather than its bare type. ``` $ node test/event-legend.test.js # 54 event types, 105 emit sites 18 passed, 0 failed $ git stash push web/app.js engine/simulator.js && node test/event-legend.test.js 8 passed, 10 failed # and it names all seventeen missing types ``` The general rule, worth stating once: **a view may not display a token it cannot explain.** If the engine can emit it, the panel says what it means — and the connection between the two is a test, not a habit. Neighbours green: `ui-render` 38, `ui-dom-contract` 19, `ui-action-failures` 13, `arp-conflict` 26, `runtime-agreement` 10, `report-sweep` 21. Syntax 304 files OK. Full suite: 236 suites, 8827 assertions, 0 failed.
Author
Owner

Landed as #1476 (edd262cb). Post-merge on main: event-legend 18, ui-render 38, tree clean.

All 54 event types now have a sentence, and the legend may only read fields the event carries - the check reads each emit site's field list straight out of engine/, which is how it caught flow-reset reading e.proto that the event never sends. A view may not display a token it cannot explain.

Landed as #1476 (`edd262cb`). Post-merge on `main`: `event-legend` 18, `ui-render` 38, tree clean. All 54 event types now have a sentence, and the legend may only read fields the event carries - the check reads each emit site's field list straight out of `engine/`, which is how it caught `flow-reset` reading `e.proto` that the event never sends. A view may not display a token it cannot explain.
Sign in to join this conversation.
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#1475
No description provided.