Send ICMP errors, and build traceroute on them #1484

Merged
jaylouisw merged 2 commits from feat/icmp-errors-traceroute into main 2026-11-12 05:19:50 +00:00
Owner

Send ICMP errors, and build traceroute on them

The engine decremented TTL, watched it hit zero, and dropped the packet with an event only the simulator can read. Same for no route. So traceroute was impossible in principle — the command works by provoking time exceeded from each hop in turn, and no hop ever answered — and a lab could not tell "the packet died at hop 3" from "the packet died here".

ICMP errors — _icmpErrorTo() sends type 11 (time exceeded, code 0) on TTL expiry and type 3 (destination unreachable, code 0) when there is no route, sourced from the router's address on the ingress interface and sent back out the interface the packet arrived on. It refuses to answer an ICMP error with an ICMP error, and refuses broadcast sources: that guard is what stops a routing loop becoming a storm. _sendIcmp() now takes a TTL so a probe can be aimed at one hop.

Traceroute — Simulator.traceroute() plus CLI traceroute <ip> / tracert. Probes carry TTL 1, 2, 3 …, so the nth router expires one and names itself; the probe that reaches the destination returns as an echo reply; a silent hop prints *. A destination-unreachable ends the trace with a refusal instead of grinding to maxHops, which is what a real one does.

Two things I got wrong by reading instead of running:

  • a TTL-1 probe to an unroutable network dies of TTL at the first router before anyone evaluates the route, so the refusal appears at hop 2, not hop 1 — my first test asserted hop 1 and was wrong;
  • a probe aimed at an address on the first hop's other interface times out rather than being answered, because ownsIpOn() will not treat it as local. That is a real modelling question about ingress-vs-egress ownership, not something this PR quietly changes.

docs/SIMULATION.md §3.2 said ICMP errors and traceroute were absent; rewritten. docs/CLI.md gains the command. 84 suites, 4220 assertions, 39 new in test/icmp-errors-traceroute.test.js.


Bridged from GitHub PR #1220 by @Jaylouisw — https://github.com/Jaylouisw/packetforge/pull/1220

Send ICMP errors, and build traceroute on them The engine decremented TTL, watched it hit zero, and dropped the packet with an event only the simulator can read. Same for no route. So `traceroute` was impossible in principle — the command works by provoking *time exceeded* from each hop in turn, and no hop ever answered — and a lab could not tell "the packet died at hop 3" from "the packet died here". **ICMP errors** — `_icmpErrorTo()` sends type 11 (time exceeded, code 0) on TTL expiry and type 3 (destination unreachable, code 0) when there is no route, sourced from the router's address on the **ingress** interface and sent back out the interface the packet arrived on. It refuses to answer an ICMP error with an ICMP error, and refuses broadcast sources: that guard is what stops a routing loop becoming a storm. `_sendIcmp()` now takes a TTL so a probe can be aimed at one hop. **Traceroute** — `Simulator.traceroute()` plus CLI `traceroute <ip>` / `tracert`. Probes carry TTL 1, 2, 3 …, so the nth router expires one and names itself; the probe that reaches the destination returns as an echo reply; a silent hop prints `*`. A destination-unreachable **ends** the trace with a refusal instead of grinding to `maxHops`, which is what a real one does. Two things I got wrong by reading instead of running: - a TTL-1 probe to an unroutable network dies of TTL at the first router *before* anyone evaluates the route, so the refusal appears at hop 2, not hop 1 — my first test asserted hop 1 and was wrong; - a probe aimed at an address on the first hop's *other* interface times out rather than being answered, because `ownsIpOn()` will not treat it as local. That is a real modelling question about ingress-vs-egress ownership, **not** something this PR quietly changes. `docs/SIMULATION.md` §3.2 said ICMP errors and traceroute were absent; rewritten. `docs/CLI.md` gains the command. 84 suites, 4220 assertions, 39 new in `test/icmp-errors-traceroute.test.js`. --- > Bridged from GitHub PR #1220 by @Jaylouisw — https://github.com/Jaylouisw/packetforge/pull/1220
Send ICMP errors, and build traceroute on them
Some checks failed
CI / Test (Node 18) (pull_request) Successful in 1m23s
CI / Test (Node 20) (pull_request) Successful in 1m21s
CI / Server smoke test (pull_request) Successful in 33s
CI / Docker build (pull_request) Failing after 9s
CI / Workflow lint (pull_request) Successful in 10s
CodeQL / Analyze (pull_request) Failing after 7s
CI / Test (Node 22) (pull_request) Successful in 1m10s
f80067cdee
The engine decremented TTL, watched it reach zero and dropped the packet with an event only the simulator can read. It did the same when it had no route. So traceroute was impossible in principle: the command works by provoking 'time exceeded' from each hop in turn, and no hop ever answered. It also meant a lab could not tell 'the packet died at hop 3' from 'the packet died here'.

_icmpErrorTo() sends type 11 (time exceeded, code 0) on TTL expiry and type 3 (destination unreachable, code 0) on no route, from the router's address on the ingress side, back out the interface the packet arrived on. It refuses to answer an ICMP error with an ICMP error and refuses broadcast sources: that guard is what keeps a routing loop from becoming a storm.

Simulator.traceroute() and a CLI 'traceroute <ip>' ('tracert'): probes carry TTL 1, 2, 3 ... so the nth router expires one and names itself; the probe that reaches the destination comes back as an echo reply. A silent hop prints '*'. A destination-unreachable ends the trace with a refusal rather than a timeout, which is what a real one does.

Two things learned by running it rather than reading it: a TTL-1 probe to an unroutable network dies of TTL at the first router before anyone evaluates the route (so the refusal is at hop 2, not hop 1 - my first test asserted the wrong thing), and an address on the router's other interface is not treated as local, so a probe aimed at a far-side address of the first hop times out rather than being answered. The second is a real modelling question filed separately, not papered over here.

docs/SIMULATION.md 3.2 rewritten - it said ICMP errors and traceroute were absent. 84 suites, 4220 assertions, 39 new in test/icmp-errors-traceroute.test.js.
jaylouisw force-pushed feat/icmp-errors-traceroute from f80067cdee
Some checks failed
CI / Test (Node 18) (pull_request) Successful in 1m23s
CI / Test (Node 20) (pull_request) Successful in 1m21s
CI / Server smoke test (pull_request) Successful in 33s
CI / Docker build (pull_request) Failing after 9s
CI / Workflow lint (pull_request) Successful in 10s
CodeQL / Analyze (pull_request) Failing after 7s
CI / Test (Node 22) (pull_request) Successful in 1m10s
to f544e238ab
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 13s
CI / Test (Node 20) (pull_request) Successful in 3m12s
CI / Test (Node 18) (pull_request) Successful in 3m22s
CI / Server smoke test (pull_request) Successful in 31s
CI / Docker build (pull_request) Successful in 42s
CI / Test (Node 22) (pull_request) Successful in 2m53s
2026-11-12 05:13:10 +00:00
Compare
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-12 05:18:29 +00:00
Author
Owner

Rebased onto main and landed (73718ab4). Two things came out of doing it by hand rather than with the API's "update" endpoint:

The red was a fossil, not a regression. This branch was based on d6a9db08 (2026-11-08), whose tree still contained the GitHub-legacy codeql.yml that dd8b024a later dropped from main. A pull_request run takes its workflow files from the head branch, so every check list for this PR showed CodeQL / Analyze = failure — a workflow that no longer exists anywhere on main. The rebase removed the file with the base, and the failure went with it. Nothing was deleted to make it go away.

Rebasing put the branch in front of a guard written after it. test/event-legend.test.js (#1475) enumerates every event type emitted in engine/ and requires the packet log to render a sentence for each. This branch emits icmp-error and traceroute-probe, and both fell through to their bare type names. web/app.js now names them:

ICMP TTL expired R1/Gi0/0/0  10.0.0.1 → 10.0.0.10  about 192.0.2.1
PROBE TTL 3  → 10.0.0.5

Only fields the emit sites actually carry (the legend suite checks that too).

Verified before pushing: icmp-errors-traceroute 39/39, event-legend 18/18, full suite 240 suites / 8,917 assertions with only the two legend failures that are now fixed. Post-merge on main: 39 and 18, tree clean.

Rebased onto `main` and landed (`73718ab4`). Two things came out of doing it by hand rather than with the API's "update" endpoint: **The red was a fossil, not a regression.** This branch was based on `d6a9db08` (2026-11-08), whose tree still contained the GitHub-legacy `codeql.yml` that `dd8b024a` later dropped from `main`. A `pull_request` run takes its workflow files from the head branch, so every check list for this PR showed `CodeQL / Analyze = failure` — a workflow that no longer exists anywhere on `main`. The rebase removed the file with the base, and the failure went with it. Nothing was deleted to make it go away. **Rebasing put the branch in front of a guard written after it.** `test/event-legend.test.js` (#1475) enumerates every event type emitted in `engine/` and requires the packet log to render a sentence for each. This branch emits `icmp-error` and `traceroute-probe`, and both fell through to their bare type names. `web/app.js` now names them: ``` ICMP TTL expired R1/Gi0/0/0 10.0.0.1 → 10.0.0.10 about 192.0.2.1 PROBE TTL 3 → 10.0.0.5 ``` Only fields the emit sites actually carry (the legend suite checks that too). Verified before pushing: `icmp-errors-traceroute` 39/39, `event-legend` 18/18, full suite 240 suites / 8,917 assertions with only the two legend failures that are now fixed. Post-merge on `main`: 39 and 18, tree clean.
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!1484
No description provided.