jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-quic-qlog-h3-events

Commentary: Same as but for the h3 events file . See Issue
Paragraph (version A):
Note: we use the CDDL unwrap operator (~) here to make HTTPParameters
into a re-usable list of fields.  The unwrap operator copies the
fields from the referenced type into the target type directly,
extending the target with the unwrapped fields.  TODO: explain this
better + provide reference and maybe an example.
Paragraph (version B):
Note: The CDDL unwrap operator (~) makes HTTPParameters into a re-
usable list of fields.  The unwrap operator copies the fields from
the referenced type into the target type directly, extending the
target with the unwrapped fields.  TODO: explain this better +
provide reference and maybe an example.
Paragraph (version A):
HTTP equivalent to the packet_received event.  This event is emitted
when we actually parse the HTTP/3 frame.  Note: this is not
necessarily the same as when the HTTP/3 data is actually received on
the QUIC layer.  For that, see the "data_moved" event in QLOG-QUIC.
Paragraph (version B):
HTTP equivalent to the packet_received event.  This event is emitted
when the HTTP/3 frame is parsed.  Note: this is not necessarily the
same as when the HTTP/3 data is actually received on the QUIC layer.
For that, see the "data_moved" event in QLOG-QUIC.
Draft: draft-ietf-quic-qlog-quic-events

Commentary: This field is not particularly useful , because will always be 16 , see 's a property of the TLS cipher suite in use , so it can be trivially looked up , if necessary 
 So this is a bit of a tough one for me , since I 've gone through the pain of trying to determine the length of the TLS trailer for TLS - over - TCP from wireshark output that does NOT explicitly include the size and also makes it difficult to get the proper cipher name to heuristically determine it . That said , for QUIC V1 it 's indeed all 16 , so you -could- make an argument we can drop it here and add it back in with a V2.1 / V3 if new ciphers start being used . I do n't have a particularly big preference either way . If we do this change though , the prose could use tightening , because in the current version we have 2 sentences after another that indicate the aead_length depends on the cipher suite . 
 I 'm leaning on the side of removing this field . The information is made redundant by the cipher suite . Things that care about the tag length can do a lookup or make their own assumptions based on other information 
 Discussed on call . will make the requested prose change and should be good to go . 
 Rebased and tightened the text around the tag length . 
 Minus the comment above , this LGTM .
Paragraph (version B):
QUIC packets always include an AEAD authentication tag at the end.
In general, the length of the AEAD tag depends on the TLS cipher
suite, although all cipher suites used in QUIC v1 use a 16 byte tag.
Draft: draft-ietf-quic-qlog-h3-events

Commentary: In doing the exercise to try and define a new DATAGRAM extension for qlog ( at ) , it became clear that we only had a CDDL extension point for the events themselves ( ) but NOT for the individual QUIC and HTTP/3 frames . This is needed so we can add the CDDL definitions for new frames in other documents and have them properly matched to the CDDL expectations of " main document " events like and . 
 LGTM modulo some editorial nits
Paragraph (version B):
The generic "$HTTPFrame" is defined here as a CDDL extension point (a
"socket" or "plug").  It can be extended to support additional HTTP/3
frame types.
Paragraph (version B):
The generic "$QuicFrame" is defined here as a CDDL extension point (a
"socket" or "plug").  It can be extended to support additional QUIC
frame types.
Draft: draft-ietf-quic-qlog-h3-events

Commentary: Part of addressing . I started with the h3 doc because it 's smaller and simpler . This moves the category specific data definitions to be underneath the respective HTTP/3 or QPACK section of the document . The markdown diff is hard to assess , better to look at the html and diff preview 
 Note that RFC format does n't like more than 3 levels in a table of contents . This means that specific h3 frames , qpack instructions and block prefixes are not shown . If we think that matters , we either need to promote the data defitions one level , or flatten them into the thrid - level . 
 This also relates to In both the QUIC and H3 documents , the interesting data of each event is defined in the appendix . Typically , appendicesare used for only additional or informative content . Since the data is part of the normative schema , I 'd suggest the definitions need to be promoted into the main body of the text . 
 Agreed this should n't be in appendix . Do want to keep the data definitions together though , instead of e.g. , defining each where they are first used in an event . Since you are splitting the event categories into a Section per Category would this mean 1 new top - level Section for the data definitions ( so just lift them up from appendices as they are ) or split out more ?
Paragraph (version A):
This document defines events in two categories: http (http-ev) and
qpack (qpack-ev).
Paragraph (version B):
This document defines events in two categories, written as lowercase
to follow convention: http (http-ev) and qpack (qpack-ev).
Paragraph (version A):
Note: like all category values, the "http" category is written in
lowercase.
Paragraph (version B):
HTTP/3 events extend the "$ProtocolEventBody" extension point defined
in QLOG-MAIN.
Paragraph (version A):
Note: like all category values, the "qpack" category is written in
lowercase.
Paragraph (version A):
The QPACK events mainly serve as an aid to debug low-level QPACK
issues.  The higher-level, plaintext header values SHOULD (also) be
logged in the http.frame_created and http.frame_parsed event data
(instead).
Paragraph (version B):
The following data field definitions can be used in HTTP/3 events.
Paragraph (version B):
The HTTPApplicationError defines the general $ApplicationError
definition in the qlog QUIC definition, see QLOG-QUIC.
Paragraph (version B):
QPACK events extend the "$ProtocolEventBody" extension point defined
in QLOG-MAIN.
Paragraph (version B):
QPACK events mainly serve as an aid to debug low-level QPACK
issues.The higher-level, plaintext header values SHOULD (also) be
logged in the http.frame_created and http.frame_parsed event data
(instead).
Paragraph (version B):
The following data field definitions can be used in QPACK events.
Paragraph (version B):
Note: the instructions do not have explicit encoder/decoder types,
since there is no overlap between the instructions of both types in
neither name nor function.
Draft: draft-ietf-quic-qlog-main-schema

Commentary: There 's too much text here that does n't aid the reader . Delete it to be clear that we 're using  as the notational convention for examples . If this text was valuable , it should be somewhere else . 
 I still feel we should have a " forward reference " here , indicating that we also discuss I - JSON and Streaming JSON considerations in this document , rather than making it seem we only do " pure  " due to the examples . Put differently , something like this should still be mentioned in this location imo : 
 But the fact it can be serialized to I - JSON has nothing to do with notational conventions used in this document , because we do n't use any I - JSON . 
 I just pushed a commit with a proposal to split up the original text to keep only a minimal amount in " Notational Conventions " but keep the core message alive in the introduction ( which seemed the most logical location for now ) . I the " unless otherwise indicated " , as there are some examples of JSON - SEQ near the end of the document that obviously do n't use RFC8259 notation directly . Please review and if approved , merge :)
Paragraph (version B):
The qlog schema can be serialized in many ways (e.g., JSON, CBOR,
protobuf, etc).  This document describes only how to employ JSON, its
subset I-JSON, and its streamable derivative JSON-Text-Sequences.
Paragraph (version A):
While the qlog schemas are format-agnostic, and can be serialized in
many ways (e.g., JSON, CBOR, protobuf, ...), this document only
describes how to employ JSON, its subset I-JSON, and its streamable
derivative JSON-Text-Sequences as textual serialization options.  As
such, examples are provided in JSON.  Other documents may describe
how to utilize other concrete serialization options, though tips and
requirements for these are also listed in this document (concrete-
formats).
Paragraph (version B):
All timestamps and time-related values (e.g., offsets) in qlog are
logged as "float64" in the millisecond resolution.
Paragraph (version B):
Other qlog documents can define their own CDDL-compatible (struct)
types (e.g., separately for each Packet type that a protocol
supports).
Paragraph (version B):
Serialization examples in this document use JSON (JSON) unless
otherwise indicated.
Draft: draft-ietf-quic-qlog-h3-events

Commentary: First , these documents can now refer to the published QUIC RFCs . While doing that , let 's just replace all [ REF ] with { { REF } } , which works better for our tooling . Lastly , lets brush up the cross references between documents a bit . 
 I checked this locally and everything was good . It 's easy enough to fix up later if I did break something . 
 qlog alreaady refers to the -34 drafts . Nominally this change should be easy . Although some section references might need double checking . 
 lgtm , assuming that the build tool correctly sets the links to the RFCs
Paragraph (version A):
This document describes the values of the qlog name ("category" +
"event") and "data" fields and their semantics for the HTTP/3 and
QPACK protocols.  This document is based on draft-34 of the HTTP/3
I-D QUIC-HTTP and draft-21 of the QPACK I-D QUIC-QPACK.  QUIC events
are defined in a separate document QLOG-QUIC.
Paragraph (version B):
This document describes the values of the qlog name ("category" +
"event") and "data" fields and their semantics for HTTP/3 RFC9114 and
QPACK QPACK.
Paragraph (version A):
This document describes the values of the qlog name ("category" +
"event") and "data" fields and their semantics for the QUIC protocol.
This document is based on draft-34 of the QUIC I-Ds QUIC-TRANSPORT,
QUIC-RECOVERY, and QUIC-TLS.  HTTP/3 and QPACK events are defined in
a separate document QLOG-H3.
Paragraph (version B):
This document describes the values of the qlog name ("category" +
"event") and "data" fields and their semantics for QUIC; see QUIC-
TRANSPORT, QUIC-RECOVERY, and QUIC-TLS.
Draft: draft-ietf-quic-qlog-quic-events

Commentary: While DPLPMTUD is optional , there 's an about it in QUIC transport . Minimal support for this in qlog would define an event for every increase of the MTU : I do n't think we need a separate event for the sending of an MTU probe packet , but we should probably standardize a for this . Suggestion : . Open question : Do we want a separate failure event ? Failure would be either the loss of an MTU probe packet , or ( for implementations that pay attention to ICMP packets ) the receipt of an ICMP Packet Too Big ( PTB ) message . 
 I agree it would be useful to have this information in qlog . In terms of design , as always there are several options : 1 ) have separate events for this ( , , , etc . ) 2 ) integrate them into existing events ( triggers on and , new field in ) 3 ) a combination of these approaches ( which is what you suggest IIUC ) This is imo a good example of where we need clear design guidelines on how to add new information / events to qlog . 
 Revisiting this after a long time : is problematic , as this would essentially be a copy of the normal event ( it is allowed , although not recommended , to just send normal application data as a probe packet ) . The trigger seems to be the best solution here needs to be a separate event , there 's just no way we can reasonably collapse this into an acknowledgment event is what I 'm still undecided about . This logically belongs to the regular event , we 'd just need a way to attach " oh and by the way , this was a MTU probe packet " . In fact , it would be really useful to have it on that event , since the congestion control implications are very different for lost MTU packets ( i.e. , you would n't decrease your cwnd ) . 
 I have to disagree with myself here . The sending of the packet might have been triggered by something else , it 's just that the stack decided to send a probe packet . I suggest : a optional on the and events . a event . 
 Supporting DPLPMTUTD events seems important to cover in the base specs .
Paragraph (version B):
This event indicates that the estimated Path MTU was updated.  This
happens as part of the Path MTU discovery process.
Draft: draft-ietf-quic-qlog-quic-events

Commentary: quic : fix artwork line length quic :   between refs to unfool xml2rfc Fixes part of The changes are tedious but also not too onerous . The main issue you have is that there 's lots of comments here and there that break length limits . So I 've just picked a line length that will appease xml2rfc . The changes you have in mind might have obviated the errors anyway . But if not , these changes will set a strong foundation to know how to shut xml2rfc up . 
 According to the official IETF draft guidelines , line length should not be longer than 72 ASCII characters ( , and ) . For some reason , I had previously understood this to be 82 characters , and so the current texts are 10 characters too wide ... Since this will be somewhat of a tedious process ( which can be done largely automatically but with manual checks ) which will impact allmost all parts of the documents , I propose we do this in a single burst somewhere down the line . cc 
 Chatted a bit with rmarx offline . The errors that xml2rfc moans about are about artwork , not body text etc . Over the 3 PRs I created , there might look like a lot of churn but it is all constrained to the artwork pieces . In my opinion , it 's better to fix these now ( or nullify the json validation errors ) so that we do n't start ignoring things that exist or get newly introduced . 
 This should be fixed as of main - schema-02 and h3 / quic - events-01 . For future reference : hard limit of 72 is only needed inside " figures " ( including code blocks ! ) . Running text paragraphs / lists / etc . can be done by the tooling itself .
Paragraph (version A):
This document describes the values of the qlog name ("category" +
"event") and "data" fields and their semantics for the QUIC protocol.
This document is based on draft-34 of the QUIC I-Ds QUIC-RECOVERY
QUIC-TLS.  HTTP/3 and QPACK events are defined in a separate document
QLOG-H3.
Paragraph (version B):
This document describes the values of the qlog name ("category" +
"event") and "data" fields and their semantics for the QUIC protocol.
This document is based on draft-34 of the QUIC I-Ds QUIC-TRANSPORT,
QUIC-RECOVERY, and QUIC-TLS.  HTTP/3 and QPACK events are defined in
a separate document QLOG-H3.
Draft: draft-marx-qlog-event-definitions-quic-h3

Commentary: Not 100 % sure this is enough for all the latest draft-27(+ ) changes though , a TODO in the draft for that purpose . Also a packetnumberspace field to metrics_updated to be flexible for implementations that do n't want to implement all types of events . It 's not a great fit at that location , but it seemed the most synergistic without having a completely new event type . PTAL 
 Currently , we log in . However , we can have multiple PTO 's running across multiple PN spaces and there is no proper way to correlate them with a PN space in metricsupdated . This also impacts the event types . Possible resolutions : Add pnspace attribute to   count into a separate event ( potentially merge with loss_timer ? )  : reason more about how these metrics are tied to PN spaces in general ( are there others than PTO that are duplicated ) cc 
 Most other metrics in the event are independent of the PN space , so that would be weird . I 'd prefer to do that . Not sure if it makes sense to merge is with the loss timer events , since we also need to be able to log a reset of the PTO count to 0 ( which does n't require setting of a timer ) .
Paragraph (version A):
This event is emitted when the single recovery loss timer is set.
Paragraph (version B):
Note: to indicate an active timer's timeout update, a new "set" event
is used.
Paragraph (version A):
This event is emitted when the single recovery loss timer fires.