Wire DHCP into the data path: the library had no caller #1055

Merged
jaylouisw merged 1 commit from feat/dhcp-wired-1051 into main 2026-11-08 08:34:25 +00:00
Owner

engine/dhcp.js modelled DHCPv4 completely — pool normalisation, validation, DISCOVER/OFFER,
REQUEST/ACK-NAK, renewals, reservations, exclusions, lease expiry — and nothing called it:

$ grep -c "dhcp" engine/simulator.js
0

A host configured with ip address dhcp set a flag, printed a confirmation, and stayed unaddressed
for the life of the lab. Every ping it sent then failed silently, so the lab read as a broken
configuration rather than a missing feature.

The caller

Simulator.computeDhcp() runs before the first packet of a run — when a real host would have done
it — and engine/segment.js walks the broadcast domain instead of assuming one:

  • a bridge passes the DISCOVER on, a router receives it and stops it;
  • a spanning-tree blocked port passes nothing, and neither does a port in Listening or Learning
    (which is what the convergence work in #1050 made meaningful);
  • an access/trunk pair only matches when the VLAN is really allowed through.

The lease lands on the interface — address, mask, gateway, DNS, lease time — the default gateway
comes from the pool when the host had none, and the exchange is a timeline event, so a lab can read
the ACK and the pool it came from.

The bug that cost a debugging round

The first version asked ipInPool(pool, serverIface.ip) to decide whether a server should answer.
That function answers "can this address be handed out" — and a router's own interface address is
deliberately not allocatable, so every correctly configured server was rejected as "no pool in
this subnet". The right question is subnet membership. The comment now says so where the mistake
was made, because it is an easy one to make twice.

Four failures, not one

Reason Meaning
no-server nothing in this broadcast domain holds a pool
no-pool a server is present, but its own address is in none of its pools
pool-exhausted every address in range is leased, reserved or excluded
nak the server refused to acknowledge the offered address

Reporting "no reply" for all four would have been the same bug in a different costume.

CLI

R1(config)#ip dhcp pool lan
R1(config-dhcp)#network 10.0.0.0 255.255.255.0
R1(config-dhcp)#default-router 10.0.0.1
R1(config-dhcp)#range 10.0.0.100 10.0.0.110
R1(config-dhcp)#excluded-address 10.0.0.100
R1(config-dhcp)#lease 0 12 0

The pool is validated once, when the sub-mode is left. network before range is the second
keystroke, not an error, and a CLI that scolds you mid-typing is a CLI people stop using. The
message is the library's own (E_DHCP_BAD_RANGE: … both rangeStart and rangeEnd are required) —
not a second opinion that can drift from the model.

Pools are serialised only when non-empty. A server that forgets its pools on save is broken, but
a device with none should not grow an empty array in every saved topology — the
examples-idempotent guard caught the first version of that, which is exactly why it exists.

Test

test/dhcp-in-path.test.js — 51 assertions: a lease in the events and on the interface, two hosts
with no collision, all four failure modes, exclusions and reservations from the CLI, the walk across
a switch and its refusal across a router, STP and VLAN boundaries, an early run that reports
converging instead of failing, and a save/load round trip.

Nine failed on the first run — one engine bug (leaseSeconds is internal; the lease came out as the
library default 86400 instead of the configured 43200) and eight of my own test mistakes, mostly
hosts cabled to separate router ports and therefore in different subnets. Fixed in the test where
the test was wrong.

Docs

docs/SIMULATION.md §5.1 used to read "absent from the data path … the largest gap between what the
repo looks like and what it does."
It now documents what is modelled and, precisely, what is not:
no relay, so a central server cannot serve a remote subnet — by design rather than by accident —
plus no snooping, no Option 82, no DHCPv6, and leases that are computed at run start rather than
aged.

98 suites, 4791 assertions, all passing.

Closes #1051.

`engine/dhcp.js` modelled DHCPv4 completely — pool normalisation, validation, DISCOVER/OFFER, REQUEST/ACK-NAK, renewals, reservations, exclusions, lease expiry — and nothing called it: ``` $ grep -c "dhcp" engine/simulator.js 0 ``` A host configured with `ip address dhcp` set a flag, printed a confirmation, and stayed unaddressed for the life of the lab. Every ping it sent then failed silently, so the lab read as a broken configuration rather than a missing feature. ## The caller `Simulator.computeDhcp()` runs before the first packet of a run — when a real host would have done it — and `engine/segment.js` **walks the broadcast domain instead of assuming one**: - a bridge passes the DISCOVER on, a router receives it and stops it; - a spanning-tree blocked port passes nothing, and neither does a port in Listening or Learning (which is what the convergence work in #1050 made meaningful); - an access/trunk pair only matches when the VLAN is really allowed through. The lease lands on the interface — address, mask, gateway, DNS, lease time — the default gateway comes from the pool when the host had none, and the exchange is a timeline event, so a lab can read the ACK and the pool it came from. ## The bug that cost a debugging round The first version asked `ipInPool(pool, serverIface.ip)` to decide whether a server should answer. That function answers *"can this address be handed out"* — and a router's own interface address is deliberately **not** allocatable, so every correctly configured server was rejected as "no pool in this subnet". The right question is subnet membership. The comment now says so where the mistake was made, because it is an easy one to make twice. ## Four failures, not one | Reason | Meaning | |---|---| | `no-server` | nothing in this broadcast domain holds a pool | | `no-pool` | a server is present, but its own address is in none of its pools | | `pool-exhausted` | every address in range is leased, reserved or excluded | | `nak` | the server refused to acknowledge the offered address | Reporting "no reply" for all four would have been the same bug in a different costume. ## CLI ``` R1(config)#ip dhcp pool lan R1(config-dhcp)#network 10.0.0.0 255.255.255.0 R1(config-dhcp)#default-router 10.0.0.1 R1(config-dhcp)#range 10.0.0.100 10.0.0.110 R1(config-dhcp)#excluded-address 10.0.0.100 R1(config-dhcp)#lease 0 12 0 ``` The pool is validated **once, when the sub-mode is left**. `network` before `range` is the second keystroke, not an error, and a CLI that scolds you mid-typing is a CLI people stop using. The message is the library's own (`E_DHCP_BAD_RANGE: … both rangeStart and rangeEnd are required`) — not a second opinion that can drift from the model. Pools are serialised **only when non-empty**. A server that forgets its pools on save is broken, but a device with none should not grow an empty array in every saved topology — the `examples-idempotent` guard caught the first version of that, which is exactly why it exists. ## Test `test/dhcp-in-path.test.js` — 51 assertions: a lease in the events *and* on the interface, two hosts with no collision, all four failure modes, exclusions and reservations from the CLI, the walk across a switch and its refusal across a router, STP and VLAN boundaries, an early run that reports `converging` instead of failing, and a save/load round trip. Nine failed on the first run — one engine bug (`leaseSeconds` is internal; the lease came out as the library default 86400 instead of the configured 43200) and eight of my own test mistakes, mostly hosts cabled to separate router ports and therefore in different subnets. Fixed in the test where the test was wrong. ## Docs `docs/SIMULATION.md` §5.1 used to read *"absent from the data path … the largest gap between what the repo looks like and what it does."* It now documents what is modelled and, precisely, what is not: **no relay**, so a central server cannot serve a remote subnet — by design rather than by accident — plus no snooping, no Option 82, no DHCPv6, and leases that are computed at run start rather than aged. **98 suites, 4791 assertions, all passing.** Closes #1051.
DHCP is in the data path: the library had no caller and now it has one
Some checks failed
CI / Test (Node 18) (pull_request) Failing after 1m17s
CI / Test (Node 20) (pull_request) Successful in 2m30s
CI / Test (Node 22) (pull_request) Successful in 2m7s
CI / Docker build (pull_request) Failing after 35m51s
CI / Server smoke test (pull_request) Failing after 36m4s
e7eb935a25
engine/dhcp.js modelled DHCPv4 completely - pool normalisation, validation, DISCOVER/OFFER,
REQUEST/ACK-NAK, renewals, reservations, exclusions, lease expiry - and engine/simulator.js never
required it. grep -c dhcp engine/simulator.js returned 0. A host configured with 'ip address dhcp'
set a flag, printed a confirmation, and stayed unaddressed forever, so every ping it sent failed
silently and the lab read as a broken configuration rather than a missing feature.

The caller:

- computeDhcp() runs before the first packet of a run, which is when a real host would have done it.
- engine/segment.js walks the broadcast domain instead of assuming one: bridges pass the DISCOVER
  on, routers stop it, a spanning-tree blocked port passes nothing, a disabled or unplugged port
  passes nothing, and an access/trunk pair only match when the VLAN really is allowed through.
  Ports in Listening or Learning pass nothing either, which is what the convergence work in the
  previous PR is for.
- A server answers only for a pool covering the subnet its own interface sits in - and that test is
  subnet membership, not ipInPool(), because the gateway is deliberately not allocatable and asking
  the allocator's question would reject every correctly configured router. That mistake cost one
  debugging round and is now commented where it was made.
- The lease lands on the interface (address, mask, gateway, DNS, lease time), the default gateway
  comes from the pool when the host had none, and the exchange is an event so a lab can read the
  ACK and the pool it came from.

The failures are the ones a real server produces, and they are distinguishable: no-server (nothing
in the domain holds a pool), no-pool (a server is there; its address is in none of its pools),
pool-exhausted, nak. "No reply" for all four would have been the same bug in a different costume.

CLI: 'ip dhcp pool <name>' with network / default-router / dns-server / range / excluded-address /
lease / host (reservation). The pool is validated once, when the sub-mode is left - a half-typed
pool is the second keystroke, not an error - and the message is the library's own, not a second
opinion that can drift from it.

Pools are serialised only when non-empty: a server that forgets its pools on save is broken (the lab
silently stops handing out addresses), but a device with none should not grow an empty array in
every saved topology. The examples-idempotent guard caught the first version of this.

test/dhcp-in-path.test.js: 51 assertions - a lease in the events and on the interface, two hosts
without collision, all four failure modes, exclusions and reservations from the CLI, the walk across
a switch and its refusal across a router, STP and VLAN boundaries, an early run that reports
converging instead of failing, and a save/load round trip. Nine of them failed first time, which is
the point.

docs/SIMULATION.md 5.1 said "absent from the data path ... this is the largest gap between what the
repo looks like and what it does". It now documents what is modelled and, precisely, what is not:
no relay, so a central server cannot serve a remote subnet - by design rather than by accident.

98 suites, 4791 assertions, all passing.

Closes #1051.
jaylouisw deleted branch feat/dhcp-wired-1051 2026-11-08 08:34:26 +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!1055
No description provided.