Roadmap 1.4.0 — earn the benchmark

[EONRaider]

Tier 1 of the post-1.3.0 roadmap. Target version: 1.4.0 (minor).

Every item here is internal. The public API does not move, which is why
this is a minor and not a major.

#	Item	Measured gain
#82	Hoist protocol dispatch into module-level tables	91× / 42× on dispatch
#83	Render MAC addresses with bytes.hex(":")	16.5× on the call
#84	Stop re-validating addresses the decoder just generated	2.3 µs/frame
#85	Cache DNS section parsing instead of re-serializing	14 re-serializations → 1
#86	Add a reproducible benchmark harness and CI regression gate	—

The point of this tier

Measured on the 97-frame corpus (CPython 3.12, one machine):

	frames/sec
scapy 2.7.0	17,100
NETProtocols 1.3.0	36,500
NETProtocols with #82–#84 applied	89,200
dpkt 1.9.8	104,000

We are 2.1× faster than scapy and 2.9× slower than dpkt today.
After this tier: ~86% of dpkt and 5.2× scapy. A patched scratch copy
proving the 2.4× end-to-end figure passes all 698 tests unmodified.

Sequencing

#82 and #83 are independent and can land in either order. #84 should
follow them — regex validation only becomes the top remaining cost
once dispatch and MAC rendering are fixed, and measuring it before then
understates it. #85 is independent of all three. #86 closes the tier
and gates any performance claim reaching the README (see #101).

Do not publish numbers before this tier closes

The previous strategy note recommended publishing a benchmark table
immediately. Doing that today would put "2.9× slower than dpkt" in our
own README. Order matters: do the work, then make the claim.

Part of the post-1.3.0 roadmap: #107

[EONRaider]

Tier 1 progress: #82 merged (#118), CI green on 3.12/3.13/3.14.

Dispatch is now a lookup into a module-level table built once on first use; the deferred imports stay deferred, so the layer modules remain acyclic. The IPv6-only gating is baked into the table shape — the IPv4 table is the IPv6 one minus those numbers — and is asserted at the table level as well as through the public API.

Measured here (CPython 3.12, one machine, 200k calls / best of run):

	before	after
_ip_protocol_class	1439 ns	104 ns	13.9×
_ethertype_class	712 ns	86 ns	8.3×
corpus walk	58,300 f/s	76,500 f/s	1.31×

One correction to the table in this issue: the 91×/42× figures compare against a bare dict lookup. Measured through the function call, the ~90–100 ns call overhead now dominates, so the honest per-function numbers are 13.9× and 8.3×. The end-to-end corpus figure is unaffected and is what #86 will gate on.

Next: #84, then #85, then #86 closes the tier.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QJnVMNGwTRDktC4rkABtgt

---

Generated by Claude Code

[EONRaider]

Tier 1 progress: #84 merged (#119), CI green on 3.12/3.13/3.14.

Ethernet, ARP and IPv4 build their decoded instance directly (object.__new__ + object.__setattr__), skipping __init__/__post_init__ on the decode path only. Construction-time strictness is untouched and now pinned from both sides: the public constructors still raise, and a test patches the compiled patterns with a spy that fails if the decode path matches at all.

	before	after
Ethernet.decode	2330 ns	830 ns	2.8×
IPv4.decode	4936 ns	2596 ns	1.9×
corpus walk	76,500 f/s	113,200 f/s	1.48×

Cumulative #82 + #84: 58,300 → 113,200 frames/sec (1.94×) on this machine.

Two notes for the record:

• The saving is ~3.8 µs per Ethernet+IPv4 frame, not the ~2.3 µs this issue attributes to the regexes — bypassing the whole constructor path rather than only the validators accounts for the rest.
• Of the two options Stop re-validating addresses the decoder just generated #84 weighed, this is the object.__new__ one. A central helper taking **fields measured 855 ns against 393 ns inline (the per-field loop dominates, not the dict), so the shortcut is written out at the three sites with the reasoning recorded in _base.py.

Next: #85, then #86 closes the tier.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QJnVMNGwTRDktC4rkABtgt

---

Generated by Claude Code

[EONRaider]

Tier 1 closed. #85 (#120) and #86 (#121) merged, CI green on 3.12/3.13/3.14.

Where the tier landed

Corpus walk, CPython 3.12.3, x86-64 Linux, best of 9:

stage	frames/sec
v1.3.0 (as recorded in docs/CLAIMS.md)	36,500
+ #83 MAC rendering	~58,300
+ #82 dispatch tables	76,500
+ #84 decode-path validation	113,200
+ #85 DNS parsing (no corpus effect by design)	~114,000
measured with the #86 harness	121,945

Against the comparators, same frames, same loop: dpkt 1.9.8 → 105,292 (0.86× ours), scapy 2.7.0 → 19,657 (0.16× ours). The tier's prediction was 2.4× end to end and 86% of dpkt; the outcome is ~3.3× and 1.16× dpkt. The difference is #85 (absent from the scratch prototype) and best-of rather than mean.

The benchmark gate is advisory, and here is the data to fix that

continue-on-error: true for now — a threshold picked without runner numbers would fail unrelated PRs. #121's own run is the first data point, and it is encouraging:

• Runner: 108,232 f/s, dpkt 102,346, scapy 18,138 — the dpkt parity reproduces on hardware I never touched.
• Normalized 6.9130 against the committed baseline's 6.6662: +3.7%, despite a completely different machine. The calibration approach works.

On that evidence a real threshold of 10–15% looks defensible (cross-machine agreement ~4%, run-to-run ~2%), but it is your call and needs more than one runner sample. Flipping it to blocking is one line in ci.yml.

Two limits are documented in the harness rather than hidden: a calibration pass that runs too briefly measures the scheduler (it put 24% of noise into the gate before I sized it properly), and normalization cancels machine speed but not interpreter version (6.8 on 3.12 vs 7.6 on 3.13) — so the baseline names its Python and the job pins 3.12.

Claims register

docs/CLAIMS.md is re-measured. Claim 1.1 is now understated (6.2× scapy, not 2.1×); claim 1.2's gate is satisfied and measured. I have deliberately not touched the README: "matches dpkt while decoding further into the stack" is defensible on this evidence, "1.16× faster than dpkt" needs the depth and machine caveats attached, and that wording is yours to choose. Recommend a second machine before it goes on the front page.

Stopping here as agreed — #87 opens Tier 2 and has four public-API design questions I would rather put to you as a proposal than merge as a guess.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QJnVMNGwTRDktC4rkABtgt

---

Generated by Claude Code

[EONRaider]

All five items merged:

• Hoist protocol dispatch into module-level tables #82 — hoist protocol dispatch into module-level tables (#118)
• Render MAC addresses with bytes.hex(":") #83 — render MAC addresses with bytes.hex(":") (#117)
• Stop re-validating addresses the decoder just generated #84 — stop re-validating addresses the decoder just generated (#119)
• Cache DNS section parsing instead of re-serializing per access #85 — cache DNS section parsing instead of re-serializing per access (#120)
• Add a reproducible benchmark harness and a CI regression gate #86 — a reproducible benchmark harness and CI regression gate (#121)

Tier 1 of #107 is done. Per the roadmap's release policy, this shipped with 2.0.0 rather than as its own 1.4.0 release. Closing this out as part of a full roadmap sweep.

---

Generated by Claude Code