Retire pcapstream references, note the preallocation trap is scpcap-scoped

pcapstream-server is abandoned in favor of scpcap; drop the stale reference
in the doc's status line.

Add a footnote to §7.2 clarifying that the preallocating-writer hazard we
just spent significant effort diagnosing and fixing in scpcap's raw-.pcap
tailer doesn't apply to this document's .pcap.zst format: the compressed
writer only ever appends, and nothing that preallocates writes .pcap.zst
directly, so fstat-based phys/src tracking here remains sound as-is.
This commit is contained in:
2026-08-28 10:33:46 -04:00
parent bc2ee2d374
commit aeb827b361
+7 -1
View File
@@ -1,6 +1,6 @@
# Streaming `.pcap.zst` Format # Streaming `.pcap.zst` Format
**Status:** implemented (Rust reference: `pcapstream-core`, `pcapstream-server`, `pcapstream-client`) **Status:** implemented (Rust reference: `scpcap`)
**Audience:** an implementer writing a C++ reader that streams pcap records out of a `.pcap.zst` **Audience:** an implementer writing a C++ reader that streams pcap records out of a `.pcap.zst`
file *while it is still being written*. file *while it is still being written*.
@@ -305,6 +305,12 @@ Only then do you know the final size, which for a `.pcap.zst` is the **source fr
(`src_pos`), *not* the physical file size. (For a raw `.pcap` the two coincide, which is a trap if (`src_pos`), *not* the physical file size. (For a raw `.pcap` the two coincide, which is a trap if
you generalize from the raw path.) you generalize from the raw path.)
*(This is strictly a hazard for a raw `.pcap` reader, not for this format: a writer that
preallocates space ahead of its real cursor can make even `fstat`'s reported size diverge from
real content, which requires content-level record validation to detect — not just the phys/src
split above. The `.pcap.zst` writer here never preallocates, and nothing that preallocates writes
`.pcap.zst` directly, so this doesn't apply to the format described in this document.)*
If (1) holds but (2) doesn't — the rename landed but there's still an unframed tail — **wait**. If (1) holds but (2) doesn't — the rename landed but there's still an unframed tail — **wait**.
Do not declare completion with a size you'd have to revise. Poll again; the tail is already fully Do not declare completion with a size you'd have to revise. Poll again; the tail is already fully
written, so this resolves on the next tick. written, so this resolves on the next tick.