pub struct RuleCitation {
pub drafts: (u8, u8),
pub section: &'static str,
pub sentence: &'static str,
pub code_name: Option<&'static str>,
}Expand description
One draft’s own words for one rule: the sentence, the section it sits in, and what that draft calls the code it answers the rule with.
§A citation with no draft in it is a citation about no draft
AboveCodecRule names a rule across every draft that states it, and that
is what makes one rule one row in a conformance report rather than rows
that happen to rhyme. The sentence cannot be shared that way: one
quoted sentence per rule, printed beside whichever draft was negotiated,
publishes words the negotiated draft does not contain.
AboveCodecRule::DuplicateTrackAlias is the worked example. Draft-18
states it in Section 11.1 and spells the code DUPLICATE_TRACK_ALIAS;
draft-07 states it in Section 6.4, in different words, and spells the same
code Duplicate Track Alias. Publishing draft-18’s row against a draft-07
session would be three wrong facts at once — sentence, section and name —
each dressed as evidence, and the row would read as checked.
The close code is a separate field and is not flattened with them. It
comes from each draft’s own EndpointError::session_error_code, and those
fourteen tables answer 0x4 on drafts 07 through 10 and 0x5 from draft-11 on.
Draft-07 numbers 0x5 Parameter Length Mismatch, so a row that borrows a
neighbour’s name for its own number names a different error entirely. The
sentence, the section and the name are the three things a reader uses to
check the number, which is why each is stored per run.
§Runs, and not a row per draft
Twenty-eight rules with a citation per draft is several hundred rows, and most of them would be one sentence written out again. A row here covers a run: every draft over which one sentence sits under one section. The sentence itself is a named constant, so a wording shared by three runs — or by two different rules, which is what happens where one sentence states both the parity rule and the sequence rule — is written once and pointed at from each.
Seventy-eight rows over fifty-five sentences cover every rule this build can publish. The row count is a fact about the drafts rather than about the representation: runs break where draft-14 renamed Protocol Violation to PROTOCOL_VIOLATION, where draft-16 changed terminate to close, and — far more often than either — where a section number moved under a sentence that did not change at all. The Track Alias rule alone runs 6.4, 7.4, 8.6, 8.7, 8.8, 9.8, 9.10, 9.9, 11.1 across the drafts, and only four of those eight moves coincide with a change of wording.
§What checks it
scripts/check-drafts.py rule 8 reads this table out of this file and holds
every row against the drafts it names: that the sentence is in every draft
of the run, that it sits in the section the row gives, and that the code
name the row carries is a name the sentence itself uses. It is the only rule
in that script that reads a Rust value rather than a comment, and it is here
because a citation the gate cannot see is not a checked citation. A
catalogue of sentences kept outside this workspace is walked by no gate
here, so its rows are read by no machine at all.
§What is deliberately not here
Whether the negotiated draft answers the rule with a session close.
session_error_code answers that, per draft, quoting the sentence that
names it, and a second copy of that answer here could disagree with it. So a
row whose Self::code_name is None is a draft that states the rule and
names no code for it — not a draft that states no consequence. Two rules
here are in that position on some of their drafts and neither is a gap: the
end-of-Track rule says the receiver MUST terminate the session without
naming which code, and drafts 07 through 10 state the Subscribe ID
uniqueness requirement with no consequence at all, which is why those
drafts’ session_error_code answers None for it and no row is ever
published there.
Fields§
§drafts: (u8, u8)The first and last draft this citation is claimed for, inclusive.
section: &'static strThe section every draft in Self::drafts files the sentence under.
One section for the whole run, because the run is cut wherever the number moves. That is why a rule can have more rows than it has wordings.
sentence: &'static strThe sentence, in those drafts’ own words.
Verbatim, including what a transcriber would want to correct: the cross-references the renderings carry inside the sentence, draft-14’s SUBSCRIBE_UDPATE, the stray backtick draft-15 renders before PROTOCOL_VIOLATION, and draft-11’s missing full stop. Every one of those is load-bearing — the gate compares against the rendering, so a sentence tidied up is a sentence no draft has.
code_name: Option<&'static str>What these drafts call the session error code they answer the rule with, where the sentence names one.
The name and not the number. The number is
EndpointError::session_error_code’s answer and travels beside the rule
already; what a reader cannot get from the number is that draft-07 calls
0x4 Duplicate Track Alias while draft-14 calls 0x5
DUPLICATE_TRACK_ALIAS.