Repository navigation
docs: document the 1.1.0 error semantics in README - #333
Open
mikemiles-dev wants to merge 1 commit into
Open
mikemiles-dev wants to merge 1 commit into
mikemiles-dev wants to merge 1 commit into
Conversation
README is the crate's top-level rustdoc via include_str!, so it is what lands on docs.rs. None of the four 1.1.0 entries were reflected in it, and two of the gaps made the existing text actively wrong rather than merely incomplete. parse_bytes no longer stops at the first message-level error: a malformed IPFIX message is discarded on its own and parsing resumes at the next one, so packets can appear both before and after the reported error, and the reported error is the first rather than the last. README said "Error after N packets", which now misleads on both counts. iter_packets likewise continues past a recoverable error instead of ending the stream. Its example showed an Err arm and said nothing about whether iteration continued, which is precisely the question the change altered the answer to. Document when it resumes and when it still stops, and that v5, v7 and v9 always stop because none of them can locate the next message. Add a Chained messages and error recovery section covering RFC 7011 section 9.1 discard semantics and AutoScopedParser::parse_from_source re-deriving the scope per surviving message, since "chained" appeared nowhere in README despite being the subject of two 1.1.0 fixes. Document NoTemplateReason: the pending-flow section claimed NoTemplate flowsets are cached and replayed without qualification, but an UndecodableBody flowset deliberately never is, because no template arriving later changes its octets. A table now distinguishes the two reasons and points at is_replayable(). List MalformedSetFraming and DecodedOutputLimitExceeded among the error types, and describe what the former carries and why it is distinct from Partial. DecodedOutputLimitExceeded was already used in an earlier section but had never been listed. check-readme-sync.sh passed throughout and caught none of this; it compares section headers against a lib.rs that has none, since lib.rs is just the include_str! attribute. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #332 — base is
fix/ipfix-skip-undecodable-set, because this documentsNoTemplateReason, which that PR introduces. GitHub will retarget this tomainonce #332 merges.README.mdis the crate's top-level rustdoc via#![doc = include_str!("../README.md")], so it is what lands on docs.rs. None of the four 1.1.0 entries inRELEASES.mdwere reflected in it, and two of the gaps made the existing text actively wrong rather than merely incomplete.What was wrong
parse_bytes()error semantics. README said "Error after {} packets". Both halves of that are now misleading: a malformed IPFIX message is discarded on its own and parsing resumes at the next one, so packets can appear both before and after the reported error — and when several messages fail,errorholds the first, not the last.iter_packets()continuation. The example showed anErrarm and said nothing about whether iteration continued. That is exactly the question #330 changed the answer to. Now documented: it resumes when a discarded message locates the next one, and stops only when no trustworthy boundary remains — a length below the 16-octet Message Header, one leaving nothing behind it, or a filtered version. v5, v7 and v9 always stop, since none can locate the next message after a failure.Chained messages were undocumented. The word "chained" appeared nowhere in README, despite being the subject of two 1.1.0 fixes (#329, #330). New section covering RFC 7011 §9.1 discard semantics and
AutoScopedParser::parse_from_sourcere-deriving the scope per surviving message.NoTemplateReasonwas undocumented. The pending-flow section saidNoTemplateflowsets are cached and replayed, without qualification. AnUndecodableBodyflowset deliberately never is — no template arriving later changes its octets. A table now distinguishes the two reasons and points atis_replayable().Two error variants were missing from the list.
MalformedSetFraming(new in 1.1.0) andDecodedOutputLimitExceeded(already used in an earlier section but never listed). The former now also describes what it carries and why it is distinct fromPartial.Note on the sync check
./scripts/check-readme-sync.shpassed throughout and caught none of this. It compares section headers against alib.rsthat has none — becauselib.rsis theinclude_str!attribute — so that comparison is vacuous and it only ever verifies that doc tests compile and a ToC exists. Not fixed here, but worth knowing it is not the safety net its name suggests.Docs only; no code changes.
./scripts/check-all.shpasses all 7 checks.