Repository navigation
chore(foundation): decide the fate of the unused public Extractor.record_header #1104
Description
Activity
The PCAP read path has never gone through
record_header. The PCAP engine reads its own global header insiderun()(engines/pcap.py:113); the PCAP-NG engine does the same. Git history shows what changed:- On 2023-04-14,
232a5e6a7and2afffde74made the DPKT, Scapy and PyShark engines callext.record_header(). That borrowed the built-in engine to parse and dump the global header. - On 2023-04-27,
429f1a09a("no need to call builtin engine") removed those calls from DPKT and PyShark, and74707ebc8removed the one in Scapy. DPKT now sets its own_offmt(engines/dpkt.py:179). - Since then, nothing has called
record_header, and the Scapy engine was left without the_offmtassignment that the header dump used to set. That is fix(foundation): Extractor.output message, make_name registry pollution, scapy engine _offmt #1095's third defect.
So the options are:
- Remove
record_header(breaking). - Keep it as public API.
- Restore it as the shared header step, so the third-party engines also dump the global header. This is a behaviour change: their output would gain a
Global Headerrecord.
Which would you prefer?
- On 2023-04-14,
What's your recommendation? I think for a certain period of time, I used to do option 3.
I'd go with option 3: restore
record_headeras the shared header step for the third-party engines.- Consistent output. None of the DPKT, Scapy or PyShark engines reads or dumps the global header today; each has 0 references to
Global Header,record_headeror_gbhdr. A JSON, plist or tree dump therefore has aGlobal Headerrecord with the built-in engines and none with a third-party one. - Fixes the follow-on gaps.
- Setting
_offmtwas a side effect of the header dump. Bringing the header step back also covers zero-frame captures; fix(foundation): Extractor.output message, make_name registry pollution, scapy engine _offmt #1113's per-frame fix leaves that gap open. PCAPIO.__init__requiresprotocol, the link type from the global header. That is probably why Scapy withformat='pcap'fails (fix(scapy): the scapy engine fails with format='pcap' #1127). I have not verified this yet.
- Setting
- It is the historical design.
record_headerdates from 2023-04-14 (232a5e6a7), and its only callers were removed on 2023-04-27.
The cost is a behaviour change: third-party dumps gain a
Global Headerrecord. It would go in the changelog. If you agree, I'll do it after #1113 merges (same files) and fold #1127 into it.- Consistent output. None of the DPKT, Scapy or PyShark engines reads or dumps the global header today; each has 0 references to
cool, take (3) then.
Ruling from the maintainer: option (3).
record_headerbecomes the shared global-header step for the DPKT, Scapy and PyShark engines again, so their dumps gain theGlobal Headerrecord. The changelog will note this behaviour change.Blocked until #1113 merges. It edits
engines/scapy.pyandextraction.py. #1127, Scapy withformat='pcap', will be checked against this fix and folded in if it shares the cause.- added and removed
on Oct 6, 2026
Is your feature request related to a problem? Please describe.
Extractor.record_header(pcapkit/foundation/extraction.py:840) is a public method, but nothing inpcapkit/calls it. Onlytests/foundation/test_extraction.py:847-861andtests/foundation/test_extraction_no_eof.py:454use it. #1022 changed only its typing.Describe the solution you'd like
This needs the maintainer's decision. The options are:
Additional context
Found while verifying the #719 follow-up defects; see the #1090–#1102 wave.