Skip to content

Ship decode_frame() — the chain walker belongs in the library #88

Description

@EONRaider

Target: 2.0.0 (Tier 2 — from codec to platform)

README.md:70-77 hands users a chain-walking loop to copy and paste.
ARCHITECTURE.md shows it again. tests/test_corpus.py:33-43 carries
its own copy. RootWire has one too.

The library's most-used function is not in the library.

What to do

Ship it, with the things a copy-pasted eight-line loop never has:

  • A maximum depth guard, so a crafted frame cannot loop the walker.
    (test_fuzz.py already asserts termination, so the invariant exists
    — it just isn't enforced in shipped code.)
  • memoryview walking internally. Note the measurement in A pcap/pcapng reader that takes bytes, not filenames #100: this
    is only worth it for a large contiguous buffer; for a single frame
    it is marginally slower. Benchmark before assuming.
  • An explicit starting layer, borrowed from gopacket's
    NewPacket(data, LayerTypeEthernet, opts) — you cannot currently
    ask us to decode a buffer that starts at IPv4.
  • A lenient mode returning the layers decoded so far alongside the
    error, which is what a capture tool needs when frame 4,000,001 is
    malformed. See A named lax decode mode for deliberately truncated input #92 for the strict/lax split this should align with.

Acceptance criteria

  • decode_frame(buf) returns a Packet and the README stops
    teaching a hand-rolled loop.
  • decode_frame(buf, start=IPv4) works.
  • Depth is bounded; a hostile frame cannot hang the walker.
  • tests/test_corpus.py uses the shipped walker rather than its
    own copy.

Part of #104.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions