You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
chore(foundation): decide the fate of the unused public Extractor.record_header #1104
Is your feature request related to a problem? Please describe. Extractor.record_header (pcapkit/foundation/extraction.py:840) is a public method, but nothing in pcapkit/ calls it. Only tests/foundation/test_extraction.py:847-861 and tests/foundation/test_extraction_no_eof.py:454 use it. #1022 changed only its typing.
Describe the solution you'd like
This needs the maintainer's decision. The options are:
Keep it and document it as public API.
Deprecate it for one release, then remove it.
Remove it now. This would be a breaking change.
Additional context
Found while verifying the #719 follow-up defects; see the #1090–#1102 wave.
The PCAP read path has never gone through record_header. The PCAP engine reads its own global header inside run() (engines/pcap.py:113); the PCAP-NG engine does the same. Git history shows what changed:
On 2023-04-14, 232a5e6a7 and 2afffde74 made the DPKT, Scapy and PyShark engines call ext.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, and 74707ebc8 removed the one in Scapy. DPKT now sets its own _offmt (engines/dpkt.py:179).
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 Header record.
I'd go with option 3: restore record_header as 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_header or _gbhdr. A JSON, plist or tree dump therefore has a Global Header record with the built-in engines and none with a third-party one.
It is the historical design.record_header dates 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 Header record. It would go in the changelog. If you agree, I'll do it after #1113 merges (same files) and fold #1127 into it.
Ruling from the maintainer: option (3). record_header becomes the shared global-header step for the DPKT, Scapy and PyShark engines again, so their dumps gain the Global Header record. The changelog will note this behaviour change.
Blocked until#1113 merges. It edits engines/scapy.py and extraction.py. #1127, Scapy with format='pcap', will be checked against this fix and folded in if it shares the cause.
Activity
JarryShaw commentedon Oct 6, 2026
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:232a5e6a7and2afffde74made the DPKT, Scapy and PyShark engines callext.record_header(). That borrowed the built-in engine to parse and dump the global header.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).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:
record_header(breaking).Global Headerrecord.Which would you prefer?
JarryShaw commentedon Oct 6, 2026
What's your recommendation? I think for a certain period of time, I used to do option 3.
JarryShaw commentedon Oct 6, 2026
I'd go with option 3: restore
record_headeras the shared header step for the third-party engines.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._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.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.JarryShaw commentedon Oct 6, 2026
cool, take (3) then.
JarryShaw commentedon Oct 6, 2026
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.fix(foundation): restore record_header as the shared global-header st…
fix(foundation): restore record_header as the shared global-header st…
fix(foundation): restore record_header as the shared global-header st…