A port name with a slash can be toggled; one response stops shadowing state (#1307) #1308

Merged
jaylouisw merged 1 commit from fix/port-url-and-state-shape into main 2026-11-10 00:55:08 +00:00
Owner

A port name with a slash can be toggled, and one response stops shadowing state.

Fixes #1307.

Found while auditing that every state payload has the same shape after #1304/#1305. Unrelated to that work, and
much worse.

1. The inspector's shutdown toggle did nothing on most of the catalogue

POST /api/topologies/:name/interfaces/:device/:port required exactly one path segment for the port
(parts.length === 6). A port name is 1/1/1, Fa0/1, Gi0/0/2 — it contains slashes — so the URL the UI builds
splits into extra segments and the endpoint never matches. Measured against a live server:

POST .../interfaces/d1/1/1/1        -> 404 {"error":"unknown endpoint: .../interfaces/d1/1/1/1"}
POST .../interfaces/d1/1%2F1%2F1    -> 404 {"error":"interface not found"}

The plain form falls through to the router's 404; the encoded form reaches the handler and is never decoded. The
▲/▼ control was rendered, wired, and inert for every device whose ports are named that way. Nothing caught it
because every test drove the engine directly, not the URL.

Fixed: the port is the rest of the path (parts.slice(5).join('/'))), decoded, so both forms reach the same
port. The UI now percent-encodes the segment as well, because that is what a correct client does.

2. state appeared twice in one response object

POST .../links/:id/state
{ ok, linkId, state: 'up'|'down', atMs, reconvergeAtMs, changed, convergence, state: fullState(topo) }

The link's own string and the whole topology under the same key. It worked by luck: JavaScript keeps the later
key. Reorder those lines and the UI stores state: "down" and blanks the board. The string is now linkState, so
state means one thing.

Evidence

test/state-payload-shape.test.js — 21 checks.

  • Structurally, over the server source: every state: handed out comes from fullState() (directly or through
    a local that does), and a topology is serialised bare exactly twice — the saved file and fullState() itself.
  • Over HTTP against a spawned server: every endpoint that returns a state returns a complete one
    (verdicts.checked, byLink, issues, errorCount, runtime) — load, add device, add link, config,
    interface, get, toggle, ping — and a refused cable is still counted afterwards.
  • The two bugs above: a slash-named port toggles in plain and percent-encoded form, and the port really is
    down afterwards; the cable-state response names its string linkState.
  • The WebSocket: the connect frame and every broadcast after a mutation carry the same shape.

With server/index.js reverted, 4 checks fail — the toggle reports 404 for both forms and the ports stay
enabled ({"p5":true,"p6":true}).

A budget is asserted too, because fullState() now does work per cable: 5.3 ms for a 200-cable lab against a
60 ms tripwire, printed so a regression shows before it crosses the line.

docs/ARCHITECTURE.md: "Port names in URLs" — what the path looks like and what went wrong when it did not.

Suite: 169 suites, 6,864 assertions, 0 failed.

A port name with a slash can be toggled, and one response stops shadowing `state`. Fixes #1307. Found while auditing that every state payload has the same shape after #1304/#1305. Unrelated to that work, and much worse. ## 1. The inspector's shutdown toggle did nothing on most of the catalogue `POST /api/topologies/:name/interfaces/:device/:port` required exactly one path segment for the port (`parts.length === 6`). A port name is `1/1/1`, `Fa0/1`, `Gi0/0/2` — it contains slashes — so the URL the UI builds splits into extra segments and the endpoint never matches. Measured against a live server: ``` POST .../interfaces/d1/1/1/1 -> 404 {"error":"unknown endpoint: .../interfaces/d1/1/1/1"} POST .../interfaces/d1/1%2F1%2F1 -> 404 {"error":"interface not found"} ``` The plain form falls through to the router's 404; the encoded form reaches the handler and is never decoded. The ▲/▼ control was rendered, wired, and **inert** for every device whose ports are named that way. Nothing caught it because every test drove the engine directly, not the URL. **Fixed:** the port is the rest of the path (`parts.slice(5).join('/'))`), decoded, so both forms reach the same port. The UI now percent-encodes the segment as well, because that is what a correct client does. ## 2. `state` appeared twice in one response object ``` POST .../links/:id/state { ok, linkId, state: 'up'|'down', atMs, reconvergeAtMs, changed, convergence, state: fullState(topo) } ``` The link's own string and the whole topology under the same key. It worked **by luck**: JavaScript keeps the later key. Reorder those lines and the UI stores `state: "down"` and blanks the board. The string is now `linkState`, so `state` means one thing. ## Evidence `test/state-payload-shape.test.js` — 21 checks. * **Structurally, over the server source:** every `state:` handed out comes from `fullState()` (directly or through a local that does), and a topology is serialised bare exactly twice — the saved file and `fullState()` itself. * **Over HTTP against a spawned server:** every endpoint that returns a state returns a complete one (`verdicts.checked`, `byLink`, `issues`, `errorCount`, `runtime`) — load, add device, add link, config, interface, get, toggle, ping — and a refused cable is still counted afterwards. * **The two bugs above:** a slash-named port toggles in plain and percent-encoded form, and the port really is down afterwards; the cable-state response names its string `linkState`. * **The WebSocket:** the connect frame and every broadcast after a mutation carry the same shape. With `server/index.js` reverted, **4 checks fail** — the toggle reports 404 for both forms and the ports stay enabled (`{"p5":true,"p6":true}`). A budget is asserted too, because `fullState()` now does work per cable: **5.3 ms for a 200-cable lab** against a 60 ms tripwire, printed so a regression shows before it crosses the line. `docs/ARCHITECTURE.md`: "Port names in URLs" — what the path looks like and what went wrong when it did not. Suite: 169 suites, 6,864 assertions, 0 failed.
A port name with a slash can be toggled, and one response stops shadowing state (#1307)
All checks were successful
CI / Classify the change (pull_request) Successful in 14s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 17s
CI / Test (Node 20) (pull_request) Successful in 2m17s
CI / Test (Node 18) (pull_request) Successful in 2m25s
CI / Server smoke test (pull_request) Successful in 31s
CI / Docker build (pull_request) Successful in 41s
CI / Test (Node 22) (pull_request) Successful in 1m55s
6df38ea9dc
Found while auditing that every state payload has the same shape after #1304/#1305. Unrelated to that work, and
much worse.

1. The inspector's shutdown toggle did nothing on most of the catalogue.

POST /api/topologies/:name/interfaces/:device/:port required exactly one path segment for the port
(parts.length === 6). A port name is 1/1/1, Fa0/1, Gi0/0/2 - it contains slashes - so the URL the UI builds splits
into extra segments and the endpoint never matches. Measured against a live server:

  POST .../interfaces/d1/1/1/1        -> 404 {"error":"unknown endpoint: .../interfaces/d1/1/1/1"}
  POST .../interfaces/d1/1%2F1%2F1    -> 404 {"error":"interface not found"}

The plain form falls through to the router's 404; the encoded form reaches the handler and is never decoded. The
▲/▼ control was rendered, wired, and inert for every device whose ports are named that way. Nothing caught it
because every test drove the engine directly, not the URL.

Fixed: the port is the rest of the path (parts.slice(5).join('/')) and it is decoded, so both forms reach the same
port. The UI now percent-encodes the segment as well, because that is what a correct client does.

2. `state` appeared twice in one response object.

POST .../links/:id/state returned { ok, linkId, state: 'up'|'down', atMs, reconvergeAtMs, changed, convergence,
state: fullState(topo) } - the link's own string and the whole topology under the same key. It worked by luck:
JavaScript keeps the later key. Reorder those lines and the UI stores state: "down" and blanks the board. The
string is now `linkState`, so `state` means one thing.

test/state-payload-shape.test.js: 21 checks. Structurally, over the server source: every `state:` handed out comes
from fullState() (directly or through a local that does), and a topology is serialised bare exactly twice - the
saved file and fullState() itself. Over HTTP against a spawned server: every endpoint that returns a state returns
a complete one (verdicts/checked, byLink, issues, errorCount, runtime) - load, add device, add link, config,
interface, get, toggle, ping - and a refused cable is still counted afterwards. Plus the two bugs above, and the
WebSocket: the connect frame and every broadcast after a mutation carry the same shape. With server/index.js
reverted, 4 checks fail and the toggle reports 404 for both forms with the ports still enabled.

A budget is asserted too, because fullState() now does work per cable: 5.3 ms for a 200-cable lab against a 60 ms
tripwire (printed, so a regression shows before it crosses the line).

docs/ARCHITECTURE.md: "Port names in URLs" - what the path looks like and what went wrong when it did not.

Suite: 169 suites, 6,864 assertions, 0 failed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-10 00:55:05 +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!1308
No description provided.