Two boards stop sharing a file, a created board is saved, a non-board file is refused, and a board name is decoded (#1315) #1316

Merged
jaylouisw merged 1 commit from fix/persistence-honesty into main 2026-11-10 01:56:48 +00:00
Owner

Two boards stop sharing a file, a created board is saved, a non-board file is refused, and a board name is decoded.

Fixes #1315.

The persistence code reads well and carries a comment explaining why the debounce was removed (on Windows a kill
calls TerminateProcess, so nothing on a timer survives). Nobody had ever checked the disk. Four defects came out.

1. Two boards whose names look alike shared one file

const safe = String(id).replace(/[^A-Za-z0-9._-]/g, '_');
return path.join(TOPO_DIR, safe + '.json');

a b and a_b both become a_b.json — two boards, one file: whichever saves last wins, and after a restart only
one of them exists. Measured, with a device on each board:

files on disk: a_b.json, default.json     (two, not three)

2. A board that was created was not saved

POST /api/topologies {id:"lab"} answered 201 and put it in memory; nothing wrote it until something else mutated
it. "Make a board, name it, come back tomorrow" lost it, and GET /api/topologies would not list it.

3. A file that parses but is not a board was adopted as an empty board

Topology.fromJSON() is tolerant on purpose (it reads old files), so {"format":"packetforge-topology"} — or any
object without devices/links — became an empty board under that id. The operator opened the app and their lab was
gone, with nothing said and nothing logged. The read-side twin of #1309.

4. A board called a b could be created and then never reached again

The topology id was taken out of the path with no decoding, so once a client percent-encoded it — which it must —
every endpoint answered 404. Port names learned this in #1307; boards had not.

Fixes

The file name is injective (a short hash of the id is appended when sanitisation loses information) and the id is
written inside the file, so the name never has to be reversed; a created board is saved when it is acknowledged; the
envelope is checked before a file is adopted, and a file that is not a board is left alone and named in the log;
the path segment for a board id is percent-decoded, with a malformed escape treated as a bad request; and a failed
save names the path it could not write, not just the board.

Evidence

test/persistence.test.js — 27 checks over the real disk:

  • every mutating endpoint has written its change by the time it answers (device, config, port shutdown, cable,
    removal) — read back from the JSON file, not from the API;
  • a SIGKILL with no warning immediately after an answer loses nothing on restart;
  • two boards whose ids sanitise alike are two files, each naming its own board, both back after a restart, and saving
    one leaves the other byte for byte;
  • a wrong-format file, a document with no devices and no links, and a truncated file are all refused and left on
    disk
    , named in the log, while the good boards still load;
  • a save into an impossible directory names the path.

With server/index.js reverted, 13 of the 27 fail — no id in the file, two files instead of three for the
look-alike names, a board that cannot be reached by its own name, and one board's device count reading 0 after a
restart.

docs/ARCHITECTURE.md: "What is on the disk" — the five rules, each of which a bug taught.

Suite: 173 suites, 6,945 assertions, 0 failed.

Two boards stop sharing a file, a created board is saved, a non-board file is refused, and a board name is decoded. Fixes #1315. The persistence code reads well and carries a comment explaining why the debounce was removed (on Windows a kill calls `TerminateProcess`, so nothing on a timer survives). Nobody had ever checked the disk. Four defects came out. ## 1. Two boards whose names look alike shared one file ```js const safe = String(id).replace(/[^A-Za-z0-9._-]/g, '_'); return path.join(TOPO_DIR, safe + '.json'); ``` `a b` and `a_b` both become `a_b.json` — two boards, one file: whichever saves last wins, and after a restart only one of them exists. Measured, with a device on each board: ``` files on disk: a_b.json, default.json (two, not three) ``` ## 2. A board that was created was not saved `POST /api/topologies {id:"lab"}` answered 201 and put it in memory; nothing wrote it until something else mutated it. "Make a board, name it, come back tomorrow" lost it, and `GET /api/topologies` would not list it. ## 3. A file that parses but is not a board was adopted as an **empty** board `Topology.fromJSON()` is tolerant on purpose (it reads old files), so `{"format":"packetforge-topology"}` — or any object without `devices`/`links` — became an empty board under that id. The operator opened the app and their lab was gone, with nothing said and nothing logged. The read-side twin of #1309. ## 4. A board called `a b` could be created and then never reached again The topology id was taken out of the path with no decoding, so once a client percent-encoded it — which it must — every endpoint answered 404. Port names learned this in #1307; boards had not. ## Fixes The file name is **injective** (a short hash of the id is appended when sanitisation loses information) and the id is written inside the file, so the name never has to be reversed; a created board is saved when it is acknowledged; the envelope is checked before a file is adopted, and a file that is not a board is **left alone and named in the log**; the path segment for a board id is percent-decoded, with a malformed escape treated as a bad request; and a failed save names the path it could not write, not just the board. ## Evidence `test/persistence.test.js` — **27 checks** over the real disk: * every mutating endpoint has written its change **by the time it answers** (device, config, port shutdown, cable, removal) — read back from the JSON file, not from the API; * a **SIGKILL** with no warning immediately after an answer loses nothing on restart; * two boards whose ids sanitise alike are two files, each naming its own board, both back after a restart, and saving one leaves the other **byte for byte**; * a wrong-format file, a document with no devices and no links, and a truncated file are all refused and **left on disk**, named in the log, while the good boards still load; * a save into an impossible directory names the path. With `server/index.js` reverted, **13 of the 27 fail** — no id in the file, two files instead of three for the look-alike names, a board that cannot be reached by its own name, and one board's device count reading 0 after a restart. `docs/ARCHITECTURE.md`: "What is on the disk" — the five rules, each of which a bug taught. Suite: 173 suites, 6,945 assertions, 0 failed.
Two boards stop sharing a file, a created board is saved, a non-board file is refused, and a board name is decoded (#1315)
Some checks failed
CI / Classify the change (pull_request) Successful in 13s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 16s
CI / Test (Node 20) (pull_request) Failing after 2m47s
CI / Test (Node 18) (pull_request) Failing after 2m59s
CI / Server smoke test (pull_request) Successful in 37s
CI / Docker build (pull_request) Successful in 1m14s
CI / Test (Node 22) (pull_request) Successful in 2m33s
0f4bb2e146
The persistence code reads well and carries a comment explaining why the debounce was removed. Nobody had ever
checked the disk. Four defects.

1. Two boards whose names look alike shared one file

  const safe = String(id).replace(/[^A-Za-z0-9._-]/g, '_');
  return path.join(TOPO_DIR, safe + '.json');

a b and a_b both became a_b.json: whichever saved last won, and after a restart only one existed. Measured -
POST /api/topologies {id:"a b"} and {id:"a_b"}, a device on each -> files on disk: a_b.json, default.json.

2. A board that was created was not saved

POST /api/topologies {id:"lab"} answered 201 and put it in memory; nothing wrote it until something else mutated
it, so "make a board, name it, come back tomorrow" lost it and GET /api/topologies would not list it.

3. A file that parsed but was not a board was adopted as an EMPTY board

Topology.fromJSON() is tolerant on purpose (it reads old files), so {"format":"packetforge-topology"} - or any
object without devices/links - became an empty board under that id. The operator opened the app and their lab was
gone, with nothing said and nothing logged. The read-side twin of #1309.

4. A board called `a b` could be created and then never reached again

The topology id was taken out of the path with no decoding, so once a client percent-encoded it - which it must -
every endpoint answered 404. Port names learned this in #1307; boards had not.

Fixes: the file name is injective (a short hash of the id is appended when sanitisation loses information) and the
id is written inside the file, so the name never has to be reversed; a created board is saved when it is
acknowledged; the envelope is checked before a file is adopted, and a file that is not a board is left alone and
named in the log; the path segment for a board id is percent-decoded with a malformed escape treated as a bad
request rather than an exception; and a failed save names the path it could not write, not just the board.

test/persistence.test.js: 27 checks over the real disk. Every mutating endpoint has written its change by the time
it answers (device, config, port shutdown, cable, removal) - read back from the JSON file, not from the API. A
SIGKILL with no warning immediately after an answer loses nothing on restart. Two boards whose ids sanitise alike
are two files, each naming its own board, both back after a restart, and saving one leaves the other byte for byte.
A wrong-format file, a document with no devices and no links, and a truncated file are all refused and left on
disk, named in the log, while the good boards still load. And a save into an impossible directory names the path.

With server/index.js reverted, 13 of the 27 fail - no id in the file, two files instead of three for the look-alike
names, a board that cannot be reached by its own name, and one board's device count reading 0 after a restart.

docs/ARCHITECTURE.md: "What is on the disk" - the five rules, each of which a bug taught.

Suite: 173 suites, 6,945 assertions, 0 failed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-10 01:56:45 +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!1316
No description provided.