fix(engines): dpkt float timestamps, Simple Packet Blocks and raw-IP tracing (#1501, #1520, #1548)

[JarryShaw]

Please follow the guide below

• You will be asked some questions, please read them carefully and answer honestly

• Put an x into all the boxes [ ] relevant to your pull request (like that [x])

• Use Preview tab to see how your pull request will actually look like

• Searched for similar pull requests

• Followed the coding style (make pylint, make mypy, make isort)

• make test passes, and a test case covers the change

• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible — 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?

Tick the commit type your subject line carries.

• fix — corrects a defect
• feat — adds a feature
• perf — changes performance, not behaviour
• refactor — changes neither behaviour nor performance
• test — tests only
• docs — documentation only
• ci — workflows or build tooling
• release — bumps the version or rolls up a distribution
• chore — anything else

---

Description of your pull request and other information

Three dpkt-engine defects, one commit.

• fix(engines): the dpkt engine passes a Decimal timestamp for nanosecond PCAP #1501: the dpkt reassembly and flow-tracing adapters (pcapkit/toolkit/dpkt.py) passed the reader's timestamp through unchanged, so a nanosecond PCAP handed them a Decimal. They now hand on float(timestamp), which is what pcapkit/toolkit/pcap.py and the scapy toolkit do. The PCAP frame record is still built from the exact timestamp attached to the frame, so nanosecond traces stay byte-exact and their labels now match the default engine's.
• fix(engines): the dpkt engine's own PCAPNGReader drops Simple Packet Blocks #1520: PCAPNGReader now yields Simple Packet Blocks. Each one is parsed with pcapkit's PCAPNG against interface 0, with data length min(original_len, snaplen). Like the default engine, it dates the block at the epoch, and it keeps the block's original length. The stale .. important:: block in docs/source/pcapkit/foundation/engines/3rdparty.rst that said dpkt drops these blocks is replaced by one sentence describing this.
• fix(toolkit): the dpkt engine traces no TCP on a raw-IP link type #1548: on LINKTYPE 228/229 dpkt reads a frame as a bare IP/IP6, and a bare packet has no .ip/.ip6 attribute. All four adapters now treat such a packet as its own network layer. Stripping Ethernet from tcp.pcap (228) and http6.cap (229) now gives PCAP traces byte-identical to the default engine's.

Deletes Gap(1501) and Gap(1520) from the engine-agreement table. Every new test fails on main.

Closes #1501
Closes #1520
Closes #1548

[JarryShaw]

Verdict: GOOD TO GO at 46a9e1ee7. Cross-reviewed on Sonnet; the author ran Opus.

• fix(engines): the dpkt engine passes a Decimal timestamp for nanosecond PCAP #1501: all four dpkt adapters now hand on an exact float (DecimalTimestamp on main), the same as the default engine. On a nanosecond PCAP the TCP trace files are byte-identical to the default engine's, and the flow labels now match too.

• fix(engines): the dpkt engine's own PCAPNGReader drops Simple Packet Blocks #1520: test.pcapng gives 5 frames, identical to the default engine. An SPB matches the default engine in each case tested:

  • section 2 after a second SHB, with an IDB of the same link type or a different one;
  • a section with no IDB, which raises the same FormatError;
  • a snaplen below the original length;
  • two IDBs;
  • both byte orders.

  3,000 fuzzed SPBs gave no mismatch.

• fix(toolkit): the dpkt engine traces no TCP on a raw-IP link type #1548: on link types 228 and 229 (classic PCAP and PCAP-NG), flows, labels, trace bytes and reassembly all match the default engine. Both engines give nothing on 101, so fix(protocols): the default engine does not dissect LINKTYPE_RAW (101) in PCAP and PCAP-NG #1502 is unaffected.

• Fail-before: each fix reverted alone is caught by its own tests (9 / 10 / 4 failures). Only Gap(1501) and Gap(1520) are removed. Coverage rises: toolkit/dpkt.py 97 → 98%, engines/dpkt.py 89 → 90%.

Not blocking:

• Default-engine bug, now fix(engines): a Simple Packet Block keeps its padding when the interface snaplen is 0 #1558: with an IDB snaplen of 0, the default engine keeps an SPB's padding (60 octets instead of 57). I reproduced it; this PR's dpkt output is the correct one.
• Reassembly on raw IP: this is only unit-tested. No end-to-end test covers it.

[github-actions]

Coverage: 89.66% (unit tier, Python 3.14, b4702f17c, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	4	20	4	93.55%
pcapkit/const	18858	957	2366	871	91.03%
pcapkit/corekit	2240	67	722	34	96.32%
pcapkit/dumpkit	258	2	90	2	98.85%
pcapkit/foundation	2780	129	984	47	94.26%
pcapkit/interface	108	7	36	5	91.67%
pcapkit/protocols	16993	230	4546	191	98.02%
pcapkit/toolkit	702	93	232	7	85.65%
pcapkit/utilities	431	4	124	4	98.56%
pcapkit/vendor	4409	2342	1006	157	43.25%

Per-file detail: the coverage-html artifact of this run.

[JarryShaw]

resolve conflicts

[JarryShaw]

On it. #1531 merged, so the worker is rebasing onto main. The conflict is in the Gap table of test_engine_agreement_runtime.py, on adjacent rows. The rebased head gets a delta review.

[JarryShaw]

Verdict: GOOD TO GO at f0e0802fd. This was a Sonnet delta review; the author ran Opus. The rebase over #1531 is clean.

• Patch unchanged: the added and removed lines are identical to the reviewed 46a9e1ee7, 392 each. I re-compared them myself. Only the context in test_engine_agreement_runtime.py moved.
• Gap table: against main, the table change is a pure 13-line deletion of Gap(1501) and Gap(1520). Every other row is as on main.
• Recently merged work still passes: the PR's dpkt tests (43 passed), tests/foundation/engines (129 passed), tests/toolkit (124 passed), and the new tests from fix(protocols): an IPv4 Total Length of 0 is TSO, and one inside the header is bogus (#1547) #1554, refactor(corekit): merge the two DeferredPacket classes into corekit.packet (#1516) #1532 and test: keep the per-class pcapkit import in 12 classes that re-imported per test (#1538) #1557 all pass. dpkt's agreement cases ran with the rows gone.

[JarryShaw]

resolve conflicts

[JarryShaw]

On it. #1535 merged as ea883a648, and the author is rebasing onto main (2770404b9). The conflict is in the Gap table in tests/foundation/engines/test_engine_agreement_runtime.py: #1535 deleted its #1513 row next to this PR's #1501 and #1520 rows, and the rebase keeps both deletions. It also re-checks against #1556 and #1560, which merged at the same time. The verdict resets to review: pending on the new head.

[JarryShaw]

Verdict: GOOD TO GO at b4702f17c, carried forward from f0e0802fd after the rebase onto a3da376dd.

• Conflict: only in the KNOWN_FAILURES table. Against main, this PR now deletes exactly 13 lines from test_engine_agreement_runtime.py, which are the Gap(1501) and Gap(1520) rows, and adds nothing.
• Rest of the PR: outside that table, the diff against main matches the old commit's diff against its parent, ignoring index lines. I checked that myself.
• Re-runs on the new head: the author re-ran these against fix(toolkit): trace and reassemble a TCP segment whose header the snapshot cut (#1518) #1556, perf(const): load the TCP and UDP app-type registries on first use (#1538) #1560, fix(protocols): a next-layer hit resolves its descriptor instead of memoising the class (#1559) #1561 and fix(protocols): a later IPv4 fragment's data is raw, not an upper-layer header (#1553) #1562 and all passed:
  • the agreement module: 3 passed, 828 skipped, 414 subtests;
  • the dpkt and scapy engine modules: 14 passed;
  • test_dpkt_unit.py: 22 passed;
  • the trace runtime: 12 passed;
  • fix(toolkit): trace and reassemble a TCP segment whose header the snapshot cut (#1518) #1556's snapped-capture tests: 10 passed;
  • perf(const): load the TCP and UDP app-type registries on first use (#1538) #1560's lazy-registry test: 14 passed.