Ship decode_frame(), the chain walker

[EONRaider]

Summary

The README taught a hand-rolled eight-line loop, ARCHITECTURE.md showed it
again, and the test suite kept a private copy — so the library's most-used
function was the one function it did not provide.

fromnetprotocolsimportdecode_framepacket=decode_frame(frame) # Packet(Ethernet(...), IPv4(...), TCP(...))frame[packet.consumed:] # whatever the chain did not decode

Closes#88.

What's included

src/netprotocols/walk.py — decode_frame(), with the four things a
copy-pasted loop never has.

• An explicit starting layer.decode_frame(buf, start=IPv4) for a buffer
  that begins mid-stack — a tunnel payload, a packet quoted inside an ICMP
  error, a non-Ethernet link type. There was previously no way to ask for this.
• Bounded depth.max_depth (default 32) raises the new
  MaxDepthExceededError, rooted at ProtocolError like everything else.
• A lax mode.lax=True ends the walk on a ProtocolError and returns the
  layers decoded so far, with the reason on packet.stopped_by.
• Per-call decoder overrides.decode_as={"udp.port": {6969: DNS}}, built
  on A public protocol registry #87's Registry.derive().

Packet gains stopped_by (why a walk ended early; None for a packet you
built) and consumed (bytes its headers occupy). Both default to the
constructed-packet values, so Packet(eth, ip) is unchanged.

Copies retired — README.md, ARCHITECTURE.md, tests/test_corpus.py (now a
thin adapter), tests/test_contract.py (inline copy gone).

Tests — tests/test_walk.py, 85 new tests.

Verification

• uv run ruff check and uv run ruff format --check are clean
• uv run mypy is clean (strict)
• uv run pytest passes locally — 882 passed, coverage 99.88% (gate 98%)
• CHANGELOG.md has an entry under ## [Unreleased]

New protocol or dispatch change — also:

• Decode contract in src/netprotocols/_base.py unchanged; next_protocol() gains an optional parameter, covered below
• No new EtherType / IPProtocol numbers
• No new protocol classes, so tests/test_fuzz.py::ALL_PROTOCOLS is unchanged
• No new fixtures — the walker is exercised over the existing corpus
• README.md and ARCHITECTURE.md both updated (this issue's criterion is that they stop teaching the loop)

Notes

I was wrong in #87 about this being a small change

I said derive() would make decode_as "a small change rather than a second
dispatch mechanism." The derive() part held; the rest did not. next_protocol()
takes no arguments and reads the process-wide tables directly, so a walker
holding a custom registry had no way to redirect it — and decision 1 on #87
explicitly ruled out changing that signature.

The resolution is an optionalregistry=None parameter, passed to the same
dispatch helpers as before. That matters because the helpers already own their
table names, so nothing is duplicated and there is no second dispatch path to
keep in sync. Every existing zero-argument call is unaffected.

Cost, measured in one process (identical bodies, one with the parameter):

no param 72.5 ns
optional param 74.6 ns (+2.1)

+2.1 ns per dispatch, roughly 0.1% of a frame decode. A first cross-run
comparison suggested +15 ns; that was the machine noise documented in #87
(±10–15% between consecutive runs), not the parameter. The in-process A/B is
the number that resolves.

If you'd rather this signature stayed frozen, the alternative is dropping
decode_as from #88 and reopening Q4 — say so and I'll do that instead.

memoryview: benchmarked, then rejected

The issue said to benchmark rather than assume, so I did. Wrapping each frame in
a memoryview measures 0.95× on the corpus — 5% slower — because for a
single small frame the view costs more to build than the copy it saves. That
matches the warning in #100.

So the walker slices whatever it is handed and never converts: bytes stays
fastest for one frame, and a memoryview over a large contiguous capture buffer
keeps slices zero-copy, which is #100's 1.8× case. Converting internally would
have been worse than either. Byte-exact round-tripping through a memoryview is
asserted over the corpus.

What the depth guard actually saves

Not a runaway chain — every header validates its own declared length, so chains
already terminated. The case it saves is a zero-length header that chains to
itself: the cursor never advances and the walk never ends. Nothing in the
decode contract forbids that, and since #87 a third-party registration can
produce it. tests/test_walk.py::TestHostileChains builds exactly that and
asserts the walker returns rather than hangs.

Two deliberate exclusions

scripts/benchmark.py keeps its raw loop. It measures decode throughput
against a committed baseline; wrapping it in Packet construction would change
what the gate measures and invalidate benchmarks/baseline.json. Worth
revisiting as a separate --walker comparison.

#92's decode_lax() is not in here.#92 asks that its lenient mode and this
one "share one concept, not invent two", and it wants the stop reason to be
#91's structured diagnostic. So stopped_by holds the ProtocolError itself
rather than a new parallel type — when #91 gives those exceptions structure,
this contract gains it for free with no API change.

On the README

Touching it was this issue's acceptance criterion, so I did — but only the
decoding section, plus a short new section on registering a protocol we don't
ship (which #87 left undocumented anywhere user-facing). The coverage table and
everything comparative are untouched.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QJnVMNGwTRDktC4rkABtgt

---

Generated by Claude Code