A port count has an upper bound, and there is one expansion rule rather than two (#1319) #1320

Merged
jaylouisw merged 1 commit from fix/port-count-bound into main 2026-11-10 02:28:00 +00:00
Owner

A port count has an upper bound, and there is one expansion rule rather than two.

Fixes #1319.

Two findings in the same corner. The second is a boot-time denial of service.

1. Two copies of the expansion rule, and a test that could not see the difference

devices/registry.js and engine/topology.js each had an expandInterfaces. The test meant to keep them in step
compared port names over the catalogue — so a divergence in any other field, on any spec outside the catalogue,
or in any edge case was invisible by construction.

Measured: over all 2,015 specs the copies agree on every field of every port today, so the drift had not
happened — but they had already diverged where it counts:

devices/registry.js    count: 1000000  ->  refused as a broken spec
engine/topology.js     count: 1000000  ->  built a million ports

engine/topology.js carried the comment "the cleanest end state is for engine/topology.js to call this function
instead of keeping its own copy … so for now the two are kept in step by that test."
The test does not keep them in
step; nothing can.

2. count has a documented ceiling that nothing enforced

docs/DEVICE_SCHEMA.md says count is 1..512. The gate was "a positive whole number", so:

  • count: 1000000 passed → a million ports at boot;
  • count: Infinity passed too (Math.floor(Infinity) === Infinity, Infinity > 0) → expanding it never returns.

With the two files reverted, the new test dies with exit 134 after 2 of 15 checks — an allocation failure
building the list, before the server serves anything. One spec file, or one hand-edited saved board (/load never
passes through the loader).

Fixes

engine/topology.js delegates to devices/registry.effectiveInterfaces — one implementation, the end state that
file has described since #71. portCountProblem() is the one rule for a template's count, used by the loader (which
names the file) and by the expander (which covers the doors the loader does not guard). The message names the range
and prints Infinity as Infinity, not null.

Evidence

test/port-count.test.js — 15 checks: the engine no longer loops over a count of its own and agrees with the
registry on every field of every port of 2,015 specs; nine impossible counts (0, -1, 1.5, "8", Infinity, -Infinity, NaN, 513, 1000000) all refused with the range named; 512 still expands to 512 and an absent count to one port; two
impossible spec files reported by the loader while the sane one beside them loads; and a device built straight from a
spec — the door the loader does not guard — refused the same way, leaving no half-built device behind.

test/fuzz-importer.test.js: its two count expectations pinned the old wording ("must be a positive whole number")
— precisely the wording that was not enough. Updated to the range, with the reason stated in the test.

docs/DEVICE_SCHEMA.md: "One expansion rule", and the ceiling paragraph now says where the rule lives.

Suite: 175 suites, 6,985 assertions, 0 failed.

A port count has an upper bound, and there is one expansion rule rather than two. Fixes #1319. Two findings in the same corner. The second is a boot-time denial of service. ## 1. Two copies of the expansion rule, and a test that could not see the difference `devices/registry.js` and `engine/topology.js` each had an `expandInterfaces`. The test meant to keep them in step compared port **names** over the catalogue — so a divergence in any other field, on any spec outside the catalogue, or in any edge case was invisible by construction. Measured: over all 2,015 specs the copies agree on **every field of every port** today, so the drift had not happened — but they had already diverged where it counts: ``` devices/registry.js count: 1000000 -> refused as a broken spec engine/topology.js count: 1000000 -> built a million ports ``` `engine/topology.js` carried the comment *"the cleanest end state is for engine/topology.js to call this function instead of keeping its own copy … so for now the two are kept in step by that test."* The test does not keep them in step; nothing can. ## 2. `count` has a documented ceiling that nothing enforced `docs/DEVICE_SCHEMA.md` says `count` is **1..512**. The gate was "a positive whole number", so: * `count: 1000000` passed → a million ports at boot; * `count: Infinity` passed too (`Math.floor(Infinity) === Infinity`, `Infinity > 0`) → expanding it never returns. With the two files reverted, the new test **dies with exit 134 after 2 of 15 checks** — an allocation failure building the list, before the server serves anything. One spec file, or one hand-edited saved board (`/load` never passes through the loader). ## Fixes `engine/topology.js` delegates to `devices/registry.effectiveInterfaces` — one implementation, the end state that file has described since #71. `portCountProblem()` is the one rule for a template's count, used by the loader (which names the file) and by the expander (which covers the doors the loader does not guard). The message names the range and prints `Infinity` as `Infinity`, not `null`. ## Evidence `test/port-count.test.js` — **15 checks**: the engine no longer loops over a count of its own and agrees with the registry on every field of every port of 2,015 specs; nine impossible counts (`0, -1, 1.5, "8", Infinity, -Infinity, NaN, 513, 1000000`) all refused with the range named; 512 still expands to 512 and an absent count to one port; two impossible spec files reported by the loader while the sane one beside them loads; and a device built straight from a spec — the door the loader does not guard — refused the same way, leaving no half-built device behind. `test/fuzz-importer.test.js`: its two count expectations pinned the old wording (*"must be a positive whole number"*) — precisely the wording that was not enough. Updated to the range, with the reason stated in the test. `docs/DEVICE_SCHEMA.md`: "One expansion rule", and the ceiling paragraph now says where the rule lives. Suite: 175 suites, 6,985 assertions, 0 failed.
A port count has an upper bound, and there is one expansion rule rather than two (#1319)
Some checks failed
CI / Classify the change (pull_request) Successful in 16s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 19s
CI / Test (Node 18) (pull_request) Failing after 22s
CI / Test (Node 22) (pull_request) Successful in 2m47s
CI / Test (Node 20) (pull_request) Successful in 3m8s
CI / Server smoke test (pull_request) Successful in 33s
CI / Docker build (pull_request) Successful in 1m6s
8216b3494c
Two findings in the same corner; the second is a boot-time denial of service.

1. Two copies of the expansion rule, and the test between them could not see the difference

devices/registry.js and engine/topology.js each had an expandInterfaces. The test meant to keep them in step compared
port NAMES over the catalogue, so a divergence in any other field, on any spec outside the catalogue, or in any edge
case was invisible by construction. Measured: over all 2,015 specs the copies agree on every field of every port
today, so the drift had not happened - but they had already diverged where it counts:

  devices/registry.js    count: 1000000  ->  refused as a broken spec
  engine/topology.js     count: 1000000  ->  built a million ports

engine/topology.js carried the comment "the cleanest end state is for engine/topology.js to call this function
instead of keeping its own copy ... so for now the two are kept in step by that test". The test does not keep them in
step; nothing can.

2. `count` has a documented ceiling that nothing enforced

docs/DEVICE_SCHEMA.md says count is 1..512. The gate was "a positive whole number", so count: 1000000 passed and the
loader built a million ports at boot; count: Infinity passed too, because Math.floor(Infinity) === Infinity and
Infinity > 0, and expanding it never returns. With the two files reverted, test/port-count.test.js dies with exit 134
after 2 of 15 checks - an allocation failure building the list, before the server serves anything.

Fixes: engine/topology.js delegates to devices/registry.effectiveInterfaces - one implementation, the end state that
file has described since #71; portCountProblem() in the registry is the one rule for a template's count, used by the
loader (which names the file) and by the expander (which covers the doors the loader does not guard, such as a
hand-edited saved board); the message names the range and prints Infinity as Infinity rather than null.

test/port-count.test.js: 15 checks. The engine no longer loops over a count of its own, and agrees with the registry
on every field of every port of 2,015 specs. Nine impossible counts (0, -1, 1.5, "8", Infinity, -Infinity, NaN, 513,
1000000) are all refused with the range in the message, while 512 still expands to 512 and an absent count to one
port. Two impossible spec files are reported by the loader with the range named, the sane one beside them loads, and
a device built straight from a spec - the door the loader does not guard - is refused the same way, leaving no
half-built device behind.

test/fuzz-importer.test.js: its two count expectations pinned the old wording ("must be a positive whole number"),
which is precisely the wording that was not enough. Updated to the range, with the reason in the test.

docs/DEVICE_SCHEMA.md: "One expansion rule", and the ceiling paragraph now says where the rule lives.

Suite: 175 suites, 6,985 assertions, 0 failed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-10 02:27:55 +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!1320
No description provided.