The console over HTTP has its own counters, takes no instant, and prints a spanning tree computed at another instant #1335

Closed
opened 2026-11-10 10:13:53 +00:00 by jaylouisw · 1 comment
Owner

The console driven over HTTP is not the same console as the one in the browser, in three ways. All measured
against POST /api/topologies/:id/config/:devId.

1. One board, two sets of counters

The session was built on new Simulator(topo) — a second accounting, with its own flow state:

POST /flows {src: host, dst: host, bytes: 100}     -> 201
GET  /api/topologies/default  runtime[host].counters.ports.eth0 = { packetsIn: 4, bytesIn: 114 }
POST /config/host {commands:['show interfaces eth0']}
     console prints:  0 packets input, 0 bytes
                     0 packets output, 0 bytes

Traffic counted by /flows was invisible to the console, and traffic the console generated (ping) was invisible to
the payload — one board, two sets of counters, and no way for an operator to tell which one they were reading.

2. Every answer is given at Infinity

:config takes no instant, so the console always answers "once everything has settled". The cable endpoint takes
atMs and reports a full convergence schedule, so the API could report a lab mid-convergence and could not ask the
console about it.

3. show spanning-tree prints whatever was computed last

dev.stp is written by whichever Simulator computed it last, and every HTTP request builds its own. After a cable was
cut at 20000, a console asked at 25000 printed:

1/1/1         designated    forwarding        <- it is still listening at 25000

What must be true instead

  • the console session shares the topology's flow state, so the counters it prints are the counters the payload
    publishes;
  • :config accepts atMs, applies it on every request (a cached session must not pin a later caller to an
    instant it did not ask for), and answers with runAtMs (null = settled) and convergence;
  • show spanning-tree recomputes the tree at the attached simulator's instant before reading it.
The console driven over HTTP is not the same console as the one in the browser, in three ways. All measured against `POST /api/topologies/:id/config/:devId`. ## 1. One board, two sets of counters The session was built on `new Simulator(topo)` — a second accounting, with its own flow state: ``` POST /flows {src: host, dst: host, bytes: 100} -> 201 GET /api/topologies/default runtime[host].counters.ports.eth0 = { packetsIn: 4, bytesIn: 114 } POST /config/host {commands:['show interfaces eth0']} console prints: 0 packets input, 0 bytes 0 packets output, 0 bytes ``` Traffic counted by `/flows` was invisible to the console, and traffic the console generated (`ping`) was invisible to the payload — one board, two sets of counters, and no way for an operator to tell which one they were reading. ## 2. Every answer is given at `Infinity` `:config` takes no instant, so the console always answers "once everything has settled". The cable endpoint takes `atMs` and reports a full convergence schedule, so the API could report a lab mid-convergence and could not ask the console about it. ## 3. `show spanning-tree` prints whatever was computed last `dev.stp` is written by whichever Simulator computed it last, and every HTTP request builds its own. After a cable was cut at 20000, a console asked at 25000 printed: ``` 1/1/1 designated forwarding <- it is still listening at 25000 ``` ## What must be true instead * the console session shares the topology's flow state, so the counters it prints are the counters the payload publishes; * `:config` accepts `atMs`, applies it on **every** request (a cached session must not pin a later caller to an instant it did not ask for), and answers with `runAtMs` (`null` = settled) and `convergence`; * `show spanning-tree` recomputes the tree at the attached simulator's instant before reading it.
Author
Owner

Fixed on fix/sfp-plus-connectors (pushed, 35ea271), all three parts, each measured against a real server.

1. One board, one set of counters. Two causes, both at the session/simulator boundary:

  • /config built its session on new Simulator(topo) — its own flow table. It now uses the topology's
    (simForFlows), re-attached on every request rather than only at creation.
  • Per-port counters were a Map owned by one Simulator, so a /flows call counted frames on a run nobody could ask about afterwards. They now live on the topology, like the flow table.

Measured before → after on a PC + switch board:

POST /flows {src: PC1, dst: SW1, bytes: 400}   201
POST /config/PC1 {show interfaces eth0}        output: 0 packets -> 8 packets
POST /config/PC1 {show flows counters}         "none - nothing has been offered yet" -> the flow, 400 bytes
POST /config/PC1 {ping 10.9.9.1}               runtime[PC1].counters.packetsOut: 0 -> 4

The last line is the other direction: the data path counted only frames carrying an l4, so an ICMP echo
moved the port counters and nothing the payload published. Every IP frame is now counted, with payload
bytes 0 where there is no transport payload — which is what that table means.

2. atMs on every request. { commands, atMs }; "converged"/null/absent means settled; a negative
number is 400 E_BAD_INSTANT. The answer carries runAtMs (null = settled) and convergence, the same
schedule the cable endpoint returns. Applied per request, not at session creation, so a cached session
cannot pin the next caller to an instant they never asked for.

3. show spanning-tree at the attached instant. The derived control planes are now keyed on a topology
revision (Topology.rev, bumped by device/link changes and by markChange), so a cable removed through
DELETE /links/:id — which touches no simulator at all — is in the next answer from a cached session.
show spanning-tree at 25000 recomputes at that instant rather than printing what a previous Simulator wrote.

Test: test/server-console-instant.test.js, 25 assertions against a real server on a free port. The two
guards that matter were proved able to fail: dropping the revision from the plane cache key fails "the
cached session re-derives the tree after a cable was removed elsewhere"
(that request sends only the view,
because an enable in the same request marks the planes stale and would otherwise hide the defect).
Full suite on this commit: 212 suites, 8939 assertions, 0 failed.

Docs: docs/ARCHITECTURE.md rows for the endpoint, plus CHANGELOG.

Fixed on `fix/sfp-plus-connectors` (pushed, `35ea271`), all three parts, each measured against a real server. **1. One board, one set of counters.** Two causes, both at the session/simulator boundary: * `/config` built its session on `new Simulator(topo)` — its own flow table. It now uses the topology's (`simForFlows`), re-attached on every request rather than only at creation. * Per-port counters were a `Map` owned by one `Simulator`, so a `/flows` call counted frames on a run nobody could ask about afterwards. They now live on the topology, like the flow table. Measured before → after on a PC + switch board: ``` POST /flows {src: PC1, dst: SW1, bytes: 400} 201 POST /config/PC1 {show interfaces eth0} output: 0 packets -> 8 packets POST /config/PC1 {show flows counters} "none - nothing has been offered yet" -> the flow, 400 bytes POST /config/PC1 {ping 10.9.9.1} runtime[PC1].counters.packetsOut: 0 -> 4 ``` The last line is the other direction: the data path counted only frames carrying an `l4`, so an ICMP echo moved the port counters and nothing the payload published. Every IP frame is now counted, with payload bytes 0 where there is no transport payload — which is what that table means. **2. `atMs` on every request.** `{ commands, atMs }`; `"converged"`/`null`/absent means settled; a negative number is `400 E_BAD_INSTANT`. The answer carries `runAtMs` (`null` = settled) and `convergence`, the same schedule the cable endpoint returns. Applied per request, not at session creation, so a cached session cannot pin the next caller to an instant they never asked for. **3. `show spanning-tree` at the attached instant.** The derived control planes are now keyed on a topology revision (`Topology.rev`, bumped by device/link changes and by `markChange`), so a cable removed through `DELETE /links/:id` — which touches no simulator at all — is in the next answer from a cached session. `show spanning-tree at 25000` recomputes at that instant rather than printing what a previous Simulator wrote. **Test:** `test/server-console-instant.test.js`, 25 assertions against a real server on a free port. The two guards that matter were proved able to fail: dropping the revision from the plane cache key fails *"the cached session re-derives the tree after a cable was removed elsewhere"* (that request sends only the view, because an `enable` in the same request marks the planes stale and would otherwise hide the defect). Full suite on this commit: **212 suites, 8939 assertions, 0 failed**. Docs: `docs/ARCHITECTURE.md` rows for the endpoint, plus CHANGELOG.
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#1335
No description provided.