docs(protocols): tighten the internet-layer prose and cut timed context (#719)

[JarryShaw]

• Searched for similar pull requests
• Followed the coding style (docstrings and comments only; no code touched)
• make test passes, and a test case covers the change (N/A: prose only; tests/protocols/internet 279 passed, tests/project 268 passed)
• Changelog: N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

• docs — documentation only

---

Description of your pull request and other information

Internet-layer half A of the #719 prose sweep (mh, esp, ipv6, ip, __init__; the other seven files needed nothing).

• mh.py: the four RFC-inline enums state the closed-enumeration and no-get-override decisions once, without the issue history. Their claim that an unassigned value degrades the whole IPv6 packet (with a stale ipv6.py line reference) is replaced by what IPv6 does now: substitute IPv6_Ext for the failing MH layer. Registry comments named _read_option_/_read_extension_, which do not exist (_read_opt_/_read_ext_). Issue tags, "used to", "currently" removed from the notes.
• ipv6.py: __generic_ext_codes__ and the structural next check described as they are; dropped the claim that MANIFEST.in excludes the Shim6 placeholder from the wheel.
• ip.py: no longer lists AH/ESP (they derive from IPsec); __init__.py: "Deprecated / Base Classes" is "Base Classes".
• esp.py: issue citations and history dropped; two headings recased.

Checks: Sphinx -n, 29 warnings on these files vs 37 on main, none new. AST with docstrings and bare strings stripped equals main for every file:

file	AST equal
internet/__init__.py, esp.py, ip.py, ipv6.py, mh.py	True
ipsec.py, ipv6_frag.py, NotImplemented/{ecn,icmp,icmpv6,igmp,shim6}.py	True (unchanged)

[JarryShaw]

Cross-review verdict on 100fe88d9: NEEDS CHANGES (ran on Opus; authored on Sonnet). One finding, plus a related stale test comment.

esp.py:460-461 — half the new ESPStatus claim is wrong. It says "get and _missing_ come from EnumLookup". EnumLookup defines only get, get_all and _validate_value. I re-checked on the PR head: the MRO is ESPStatus → EnumLookup → IntEnum → … → Enum, _missing_ resolves on stdlib Enum, and ESPStatus(250) raises a builtin ValueError. The pre-PR text was right on this point.

tests/protocols/internet/test_mh_unit.py:1444 still says an unassigned code costs "the whole packet's over IPv6". That contradicts the PR's corrected mh.py prose and the subtest at :1825. Fix it here so the claim is consistent everywhere.

The mh.py behavioural claim is confirmed with real packets. The reviewer built Ethernet + IPv6 (NH 135) + MH + UDP frames: a valid FBack, FBack and LRA with unassigned status 50, and an HI with an unassigned IPv6AddressPrefix option code. In every unassigned case only the MH slot becomes IPv6_Ext (Ethernet:IPv6:IPv6-Ext:UDP:Raw), and the IPv6 header, UDP and payload all survive. The mechanism is ipv6.py:529-535.

Confirmed: the _read_opt_ / _read_ext_ names (71 and 3 readers); the ip.py hierarchy (AH and ESP are IPsec, not IP); no deprecation on IP/IPsec; the dropped MANIFEST.in claim (a built wheel holds all 33 placeholders); all 99 table rows (24 / 71 / 4, no mismatches); member counts 6 and 4.

Nit, worth taking: the 52167e331 ruling now survives only as "a get override was rejected". Name what it was rejected in favour of: deleted, not widened to accept default.

[JarryShaw]

Cross-review verdict on fdde56310: NEEDS CHANGES (ran on Opus; authored on Sonnet). One sentence, in a test docstring.

tests/protocols/internet/test_mh_unit.py:1442-1445 gets the two halves the wrong way round. It says an unassigned code "degrades the MH parse to Raw via @beholder … over IPv4 that is the MH message". I re-checked both cases on the PR head with the same FBack MH carrying UDP hello, once valid and once with status 50:

• IPv4: valid parses as IPv4:MH:UDP:Raw. Status 50 parses as IPv4:Mobility_Header. The layer after IPv4 is a single Raw holding MH, UDP and the payload, so everything above MH is lost, not just the MH message.
• IPv6: status 50 parses as Ethernet:IPv6:IPv6-Ext:UDP:Raw. Only the MH header is replaced, and UDP and the payload still parse.

So Raw is the IPv4 path only, and IPv4 loses more than IPv6. Suggested: "…so an unassigned code no longer grows the class. Over IPv4 @beholder replaces the MH layer and everything above it with Raw; over IPv6 only the MH header is replaced, by IPv6_Ext, and the layers above it still parse."

Everything else is confirmed:

• esp.py:460-462: every clause holds. get and get_all come from EnumLookup, _missing_ from enum.Enum, and ESPStatus(250) raises a plain ValueError.
• The fix(mh): two kept get overrides advertise the base default argument and reject it with TypeError #935 rationale: it now names the rejected alternative ("deleted, not widened to accept default").
• The NAI comment reads as one point.
• Scope: range-diff shows nothing else changed. No assertion moved, and test_mh_unit.py passes (52 passed, 499 subtests).

[JarryShaw]

Cross-review verdict on a7dda2df8: GOOD TO GO (ran on Opus; authored on Sonnet). All round-2 findings are fixed.

• The test_mh_unit.py comment now matches how the parser behaves. I checked both cases on this head with the same FBack MH carrying UDP hello:
  • Over IPv4, @beholder replaces the MH layer and everything above it with Raw. The packet parses as IPv4:Mobility_Header, and a single Raw holds MH, UDP and the payload.
  • Over IPv6, only the MH header is replaced by IPv6_Ext. The packet parses as Ethernet:IPv6:IPv6-Ext:UDP:Raw.
• Scope: the commit changes only that docstring (+5/−4). The file's AST still matches main once docstrings are stripped, and test_mh_unit.py passes: 52 passed, 499 subtests.
• Carried forward and confirmed:
  • the ESPStatus get/get_all/_missing_ clauses
  • the mh.py IPv6 behaviour, checked against real packets
  • the fix(mh): two kept get overrides advertise the base default argument and reject it with TypeError #935 rationale, which now names the rejected alternative
  • the ip.py class hierarchy
  • the dropped MANIFEST.in claim
  • all 99 table rows
• Not verified: a full Sphinx -n build, the per-class abc cache claim, and LMAAddressCode at the packet level.