refactor: extract duplicated wire-unit arithmetic across mh/ipv6_route/hopopt/ipv6_opts

[JarryShaw]

Closes #495 — the last open item from the post-wave-1 consistency sweep. Pure refactor: 168 duplicated arithmetic sites replaced by five helpers, with no behaviour change.

Why this is not tidying

Two shipped defects came from exactly this duplication. #487 computed Hdr Ext Len in four places and got four different wrong answers. #398 (29dfd351b) was one conceptual +2/-2 unit mismatch that had to be diagnosed once and then patched independently in six files — hopopt.py 130 lines, ipv6_opts.py 131, mh.py 130, plus all three schema files at 46/46/47.

What changed

scope	sites	helper
ipv6_route.py total header octets	4	ipv6_route_header_length(), beside the existing ipv6_route_data_length()
mh.py message length	25	MH._mh_message_length()
mh.py option length	92	MH._mh_option_length()
hopopt.py option length	17	HOPOPT._hopopt_option_length()
ipv6_opts.py option length	17	IPv6_Opts._ipv6_opts_option_length()

The mh.py message-length case is the clearest: the write side was already unified at mh.py:1438 while the read side stayed duplicated 25 ways, and that value feeds _decode_next_layer(mh, schema.next, length - mh.length) — the same role Hdr Ext Len played in #487.

ipv6_route_header_length() is defined as 4 + ipv6_route_data_length(hdr_ext_len), which keeps the two related-but-distinct quantities visibly related: 8 + 8k total header octets versus 4 + 8k data octets. Confusing those two was #487.

Deliberately NOT done

The hopopt.py/ipv6_opts.py shared base class. Those two files are one implementation twice (406 changed lines out of ~1950, overwhelmingly renaming), and collapsing them would subsume a large part of this issue — but it is a cross-cutting change that deserves its own issue and its own review, so the option-length helpers here are per-class rather than one shared helper across the two files. That boundary was drawn on purpose.

Also untouched, and already retired with reasons in #495: pcap.py/pcapng.py not scaling fragment offsets (they consume already-scaled values, unlike the third-party adapters, so the asymmetry is correct); pypcap.py/pcap_ct.py raising UnsupportedCall throughout; HIP's single length=schema.len * 8 + 8 call site, which has nothing to share with.

The trap this change had to avoid

reassembly/tcp.py and reassembly/ip.py look like near-duplicates and must not be merged: RFC 791 lines 1892-1894 mandate last-write-wins for IP, RFC 9293 §3.10 mandates first-write-wins for TCP, and #443 settled that deliberately. Neither file is in this diff — 0 reassembly files, verifiable from git diff --name-only origin/main...HEAD.

Verification

Helper arithmetic checked independently of the tests — 240 comparisons over k = 0..39 against the original expressions, 0 mismatches:

ipv6_route_header_length(k) == k*8 + 8      ipv6_route_data_length(k) == 4 + k*8
MH._mh_message_length(k)    == (k+1)*8      MH._mh_option_length(k)   == k + 2
HOPOPT._hopopt_option_length(k) == k + 2    IPv6_Opts._ipv6_opts_option_length(k) == k + 2

Every old pattern is gone, and the counts match #495's measurements exactly:

                            main   branch
mh  (header.length + 1) * 8   25      0
ipv6_route  length * 8 + 8     4      0
hopopt      .len + 2          17      0
ipv6_opts   .len + 2          17      0

Byte-identity against main, which is the only proof that matters for a refactor. Construct-then-parse across IPv6-Route source-route with 0/1/2/3 addresses, six MH message types, and the HOPOPT/IPv6-Opts Router-Alert option, dumped to JSON from both trees:

BEFORE (main):     md5 d797c44b0c1b
AFTER  (#495):     md5 d797c44b0c1b
diff: IDENTICAL

Critically, 0 error-ish lines in that output — so this is a comparison of real results, not of two identical crashes. (A driver that dies the same way on both trees reports "identical" while proving nothing; that happened earlier in this programme and is worth guarding against explicitly.)

Tests on the directly affected paths: test_option_roundtrip_unit.py + test_mh_unit.py + test_ipv6_extension_unit.py → 98 passed, 860 subtests passed. EXPECTED_FAILURES inspected by importing the module (it cannot be grepped — ** unpacking): 59 entries, none needing an update.

One deliberate omission

No dedicated unit tests for the five helpers. That follows the house precedent set by #487/#489: IPv6_Route._make_hdr_ext_len and ipv6_route_data_length have no dedicated tests either and are exercised through the existing round-trip suite. Adding a new convention here rather than following the existing one seemed the wrong call for a refactor, but it is a judgement worth disagreeing with — the arithmetic check above is a script, not a committed test.