One question, three answers: what is a ping destination? (#1377) #1378

Merged
jaylouisw merged 1 commit from feat/ping-surface into main 2026-11-10 20:09:42 +00:00
Owner

One question — what is a ping destination? — asked in three places, answered three ways. Fixes #1377.

#1376 taught the console to resolve a hostname. The other two surfaces that ask the same question did not agree
with it, or with themselves:

surface behaviour
engine/cli.js ping refused every hostname; accepted 10.0.0.999, because net.isIp() only checks the shape
POST /ping passed the string to the engine, so 10.0.0.999 threw and came back as a 500
web/app.js dialog /^(\d{1,3}\.){3}\d{1,3}$/ — accepted 10.0.0.999, refused every hostname

And POST /ping never returned what the resolver said: a name that does not resolve sends no packet, yet the
answer was only replies: [{ success: false }] — indistinguishable from four lost echoes, so the UI drew a 0%
success rate for something that was never sent.

Fixed at each surface, with one rule

  • POST /ping validates the destination: 400 with code: "E_BAD_DESTINATION" and a message naming the
    problem (four octets, each 0-255; no whitespace; not empty).
  • The source device is looked up first, so {src:"nobody"} is still a 404 about the device it named rather
    than a 400 about a destination — the order is part of the contract and api-errors pins it.
  • POST /ping returns the resolver verdict: dns: { ok, status, address, serverIp }, or null for an
    address. The reply already carried reason: "dns-nxdomain" and sends nothing.
  • The inspector's Simulate tab takes an address or a name, validates with the same octet rule, and shows the
    resolution — or says the name did not resolve and that nothing was sent, instead of drawing a 0% success rate.

The browser cannot require the engine, so the rule is written twice; the test compares the two across a table of
strings (addresses, near-addresses, names, an empty target, a target with a space).

POST /api/topologies/default/ping  {"src":"d1","dst":"10.0.0.999"}
400 {"code":"E_BAD_DESTINATION","error":"dst \"10.0.0.999\" is not an IPv4 address (four octets, each 0-255)"}

Evidence

test/ping-surface.test.js — 21 checks: the dialog and the console accept and refuse the same strings; a
mistyped octet is a 400 with a code and a message; an empty or spaced destination is a 400; a missing source is a
400; a hostname is accepted and its resolution reported; a name with no zone comes back as a resolver verdict
with one failed reply whose reason says dns-*
, not as a crash; an address still works and reports no resolution.

  • reverting server/index.js → 9 of 21 fail
  • reverting web/app.js → 3 of 21 (the dialog rule and the two checks that name it)

docs/ARCHITECTURE.md gains "Ping, and what a destination is" with the request/response shapes and the 400.

Suite: 192 suites, 7,405 assertions, 0 failed. Syntax: 260 files, OK.

One question — what is a ping destination? — asked in three places, answered three ways. Fixes #1377. #1376 taught the console to resolve a hostname. The other two surfaces that ask the same question did not agree with it, or with themselves: | surface | behaviour | |---|---| | `engine/cli.js` `ping` | refused every hostname; accepted `10.0.0.999`, because `net.isIp()` only checks the *shape* | | `POST /ping` | passed the string to the engine, so `10.0.0.999` threw and came back as a **500** | | `web/app.js` dialog | `/^(\d{1,3}\.){3}\d{1,3}$/` — accepted `10.0.0.999`, refused every hostname | And `POST /ping` never returned what the resolver said: a name that does not resolve sends **no packet**, yet the answer was only `replies: [{ success: false }]` — indistinguishable from four lost echoes, so the UI drew a 0% success rate for something that was never sent. ## Fixed at each surface, with one rule * **`POST /ping` validates the destination**: `400` with `code: "E_BAD_DESTINATION"` and a message naming the problem (four octets, each 0-255; no whitespace; not empty). * **The source device is looked up first**, so `{src:"nobody"}` is still a `404` about the device it named rather than a `400` about a destination — the order is part of the contract and `api-errors` pins it. * **`POST /ping` returns the resolver verdict**: `dns: { ok, status, address, serverIp }`, or `null` for an address. The reply already carried `reason: "dns-nxdomain"` and sends nothing. * **The inspector's Simulate tab** takes an address or a name, validates with the same octet rule, and shows the resolution — or says the name did not resolve and that nothing was sent, instead of drawing a 0% success rate. The browser cannot `require` the engine, so the rule is written twice; the test compares the two across a table of strings (addresses, near-addresses, names, an empty target, a target with a space). ``` POST /api/topologies/default/ping {"src":"d1","dst":"10.0.0.999"} 400 {"code":"E_BAD_DESTINATION","error":"dst \"10.0.0.999\" is not an IPv4 address (four octets, each 0-255)"} ``` ## Evidence `test/ping-surface.test.js` — **21 checks**: the dialog and the console accept and refuse the same strings; a mistyped octet is a `400` with a code and a message; an empty or spaced destination is a `400`; a missing source is a `400`; a hostname is accepted and its resolution reported; **a name with no zone comes back as a resolver verdict with one failed reply whose reason says `dns-*`**, not as a crash; an address still works and reports no resolution. * reverting `server/index.js` → **9 of 21 fail** * reverting `web/app.js` → 3 of 21 (the dialog rule and the two checks that name it) `docs/ARCHITECTURE.md` gains "Ping, and what a destination is" with the request/response shapes and the `400`. Suite: **192 suites, 7,405 assertions, 0 failed**. Syntax: 260 files, OK.
One question, three answers: what is a ping destination? (#1377)
All checks were successful
CI / Classify the change (pull_request) Successful in 13s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 17s
CI / Test (Node 20) (pull_request) Successful in 2m50s
CI / Test (Node 18) (pull_request) Successful in 3m1s
CI / Server smoke test (pull_request) Successful in 30s
CI / Docker build (pull_request) Successful in 48s
CI / Test (Node 22) (pull_request) Successful in 2m23s
2ae39f1bda
#1376 taught the console to resolve a hostname. The other two surfaces that ask the same question did not
agree with it, or with themselves:

  engine/cli.js  ping        refused every name, and accepted 10.0.0.999 because net.isIp() only checks the
                             shape (three dots, one to three digits)
  POST /ping                 passed the string straight to the engine, so 10.0.0.999 threw inside
                             Simulator.ping() and came back as a 500 - a mistyped octet presented as a server
                             fault. A hostname worked, but nothing in the answer said the name had been
                             resolved, so a client could only report 0% packet loss for a DNS failure
  web/app.js     dialog      /^(\d{1,3}\.){3}\d{1,3}$/ - accepted 10.0.0.999 (and got the 500) and refused
                             every hostname

Fixed at each surface, with the same rule:
  - POST /ping validates the destination and answers 400 with code E_BAD_DESTINATION and a message naming
    what is wrong (four octets, each 0-255; no whitespace; not empty). The source device is looked up FIRST,
    so {src:"nobody"} is still a 404 about the device it named rather than a 400 about a destination.
  - POST /ping returns `dns: { ok, status, address, serverIp }` (or null for an address), so a resolver
    failure is legible as one. The reply already carried `reason: "dns-nxdomain"` and sends nothing.
  - the inspector's Simulate tab takes an address or a name, validates with the same octet rule, and shows
    the resolution - or says the name did not resolve and that nothing was sent, instead of drawing a 0%
    success rate for a name that never became a packet.

The browser cannot require the engine, so the rule is written twice; test/ping-surface.test.js compares the
two across a table of strings (addresses, near-addresses, names, an empty target, a target with a space).

Evidence: test/ping-surface.test.js, 21 checks - the two surfaces accept and refuse the same strings; a
mistyped octet is a 400 with a code and a message; an empty or spaced destination is a 400; a missing source
is still a 400 (and an unknown source a 404, verified by api-errors); a hostname is accepted and its
resolution reported; a name with no zone comes back as a resolver verdict with one failed reply whose
reason says dns-*, not as a crash; an address still works and reports no resolution. Reverting
server/index.js fails 9 of 21; reverting web/app.js fails 3 (the dialog rule and the two checks that name
it).

docs/ARCHITECTURE.md gains 'Ping, and what a destination is' with the request and response shapes and the
400.

Suite: 192 suites, 7,405 assertions, 0 failed. Syntax: 260 files, OK.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-10 20:09:38 +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!1378
No description provided.