From d6ade65e87ad88b9be3b0900655d93319452f7f3 Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Fri, 25 Sep 2026 11:34:12 -0400 Subject: [PATCH] docs(pcapng): repoint the generator's stale journal-defect citation `_journal_entry`'s docstring in examples/generators/pcapng.py cited pcapkit/protocols/schema/misc/pcapng.py:1376 for the padding-splitting defect its alignment workaround exists to avoid. That line number was correct when the comment was written, but the defect itself was fixed earlier than the citation implied and by a different change than first attributed here. - The fix is #699 (closing #678): it added the `not line.strip(b'\x00')` guard that ends a journal entry on its own NUL padding instead of misreading it as a binary field name. #728/#723 only moved that guard while rewriting the parser to walk `self.entry` instead of splitting it -- confirmed with `git log -S "strip(b'\x00')"` and by diffing 8af2cfda7 against 73b8cc87f. #723 is about content shredded by the `b'\n\n'` split, a different symptom. - Cite the fix and the mechanism instead of a bare line number. - Say the workaround stays because dropping it regenerates the untracked `test.pcapng` fixture (examples/captures/* is gitignored), not because it touches committed bytes -- and say the measurement found no `SchemaWarning`, not "no warning": an unrelated `ExtractionWarning: EOF reached` fires on the aligned entry too. - Fix `_Blocks.journal`'s docstring, which credited "the caller" for padding `entry` when `_Blocks.block` does it. Measured directly: built a misaligned journal entry through the real _Blocks writer, bypassing _journal_entry's alignment loop, and parsed it with the current Extractor -- one entry, zero SchemaWarnings, on both the aligned and misaligned forms. make isort and pytest tests/protocols/misc/test_pcapng_unit.py (88 passed, 1 skipped, 1753 subtests) both clean. Closes #791 --- examples/generators/pcapng.py | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/examples/generators/pcapng.py b/examples/generators/pcapng.py index 76a70c4f68..6860acfc5a 100644 --- a/examples/generators/pcapng.py +++ b/examples/generators/pcapng.py @@ -342,8 +342,9 @@ def dsb(self, secrets_type: 'int', secrets: 'bytes', def journal(self, entry: 'bytes') -> 'bytes': """:manpage:`systemd(1)` Journal Export Block. - ``entry`` is padded out to a 4-octet boundary by the caller rather than - here -- see :func:`_journal_entry` for why that distinction matters. + ``entry`` is padded out to a 4-octet boundary by :meth:`_Blocks.block`, + not here -- see :func:`_journal_entry` for why that distinction used to + matter. """ return self.block(BLOCK_JOURNAL, entry) @@ -402,15 +403,16 @@ def _read_epb_packets(path: 'pathlib.Path') -> 'list[bytes]': def _journal_entry(message: 'str', realtime_us: 'int') -> 'bytes': """Build a :manpage:`systemd(1)` journal export entry of 4-octet length. - The block body is padded to a 4-octet boundary like every other PCAP-NG - block, but pcapkit hands the padding to its journal-entry parser along with - the entry itself, and the parser then reads the NULs as the start of a - binary field and raises ``struct.error: unpack requires a buffer of 8 - bytes``. Choosing a message whose entry is already aligned means no padding - is added, which the specification allows and which keeps the fixture - parseable. The underlying defect is - ``pcapkit/protocols/schema/misc/pcapng.py:1376`` splitting ``self.entry`` - without first stripping the block padding. + The block body is padded to a 4-octet boundary by :meth:`_Blocks.block`, + so a message whose entry is already aligned gets no padding at all. That + used to be load-bearing: an unaligned entry's own NUL padding was read as + a binary field name and raised a bare ``struct.error`` (fixed in `#699 + `__, which made a + NUL-only line end the entry). Measured on ``ef859f776``: a misaligned + entry now parses with no ``SchemaWarning``. The loop stays only because + removing it regenerates ``test.pcapng`` -- an untracked fixture change, + not a prose one; see `#791 + `__. """ while True: