Draft: draft-ietf-quic-transport

Commentary: Minor nits and changes . 
 A few nits and quibbles , but that is where we are .
Paragraph (version A):
Streams are means by which an application protocol exchanges
information.  Streams are ordered sequences of bytes.  Two types of
stream can be created: bidirectional streams, which allow both
endpoints to send data; and unidirectional streams, which allow a
single endpoint to send.  A credit-based scheme is used to limit
stream creation and to bound the amount of data that can be sent.
Paragraph (version B):
Application protocols exchange information over a QUIC connection via
streams, which are ordered sequences of bytes.  Two types of stream
can be created: bidirectional streams, which allow both endpoints to
send data; and unidirectional streams, which allow a single endpoint
to send data.  A credit-based scheme is used to limit stream creation
and to bound the amount of data that can be sent.
Paragraph (version A):
address-validation specifies critical denial of service
mitigation mechanisms,
Paragraph (version B):
address-validation describes address validation and critical
denial of service mitigations,
Paragraph (version A):
error-handling provides general guidance for error handling.
Paragraph (version B):
error-handling provides guidance for stream and connection
error handling.
Paragraph (version A):
QUIC does not provide a mechanism for exchanging prioritization
information.  Instead, it relies on receiving priority information
from the application that uses QUIC.
Paragraph (version B):
QUIC does not provide a mechanism for exchanging prioritization
information.  Instead, it relies on receiving priority information
from the application.
Paragraph (version A):
This document does not define an API for QUIC, but instead defines a
set of functions on streams that application protocols can rely upon.
An application protocol can assume that an implementation of QUIC
provides an interface that includes the operations described in this
section.  An implementation designed for use with a specific
application protocol might provide only those operations that are
used by that protocol.
Paragraph (version B):
This document does not define an API for QUIC, but instead defines a
set of functions on streams that application protocols can rely upon.
An application protocol can assume that a QUIC implementation
provides an interface that includes the operations described in this
section.  An implementation designed for use with a specific
application protocol might provide only those operations that are
used by that protocol.
Paragraph (version A):
These state machines shown in this section are largely informative.
This document uses stream states to describe rules for when and how
different types of frames can be sent and the reactions that are
expected when different types of frames are received.  Though these
state machines are intended to be useful in implementing QUIC, these
states are not intended to constrain implementations.  An
implementation can define a different state machine as long as its
behavior is consistent with an implementation that implements these
states.
Paragraph (version B):
The state machines shown in this section are largely informative.
This document uses stream states to describe rules for when and how
different types of frames can be sent and the reactions that are
expected when different types of frames are received.  Though these
state machines are intended to be useful in implementing QUIC, these
states are not intended to constrain implementations.  An
implementation can define a different state machine as long as its
behavior is consistent with an implementation that implements these
states.
Paragraph (version A):
A STOP_SENDING frame requests that the receiving endpoint send a
RESET_STREAM frame.  An endpoint that receives a STOP_SENDING frame
MUST send a RESET_STREAM frame if the stream is in the Ready or Send
state.  If the stream is in the "Data Sent" state, an endpoint MAY
defer sending the RESET_STREAM frame until the packets containing
outstanding data are acknowledged or declared lost.  If any
outstanding data is declared lost, the endpoint SHOULD send a
RESET_STREAM frame instead of retransmitting the data.
Paragraph (version B):
A STOP_SENDING frame requests that the receiving endpoint send a
RESET_STREAM frame.  An endpoint that receives a STOP_SENDING frame
MUST send a RESET_STREAM frame if the stream is in the Ready or Send
state.  If the stream is in the "Data Sent" state, the endpoint MAY
defer sending the RESET_STREAM frame until the packets containing
outstanding data are acknowledged or declared lost.  If any
outstanding data is declared lost, the endpoint SHOULD send a
RESET_STREAM frame instead of retransmitting the data.
Paragraph (version A):
An endpoint SHOULD copy the error code from the STOP_SENDING frame to
the RESET_STREAM frame it sends, but MAY use any application error
code.  The endpoint that sends a STOP_SENDING frame MAY ignore the
error code carried in any RESET_STREAM frame it receives.
Paragraph (version B):
An endpoint SHOULD copy the error code from the STOP_SENDING frame to
the RESET_STREAM frame it sends, but MAY use any application error
code.  An endpoint that sends a STOP_SENDING frame MAY ignore the
error code in any RESET_STREAM frames subsequently received for that
stream.
Paragraph (version B):
It is necessary to limit the amount of data that a receiver could
buffer, to prevent a fast sender from overwhelming a slow receiver,
or to prevent a malicious sender from consuming a large amount of
memory at a receiver.  To enable a receiver to limit memory
commitment to a connection and to apply back pressure on the sender,
streams are flow controlled both individually and as an aggregate.  A
QUIC receiver controls the maximum amount of data the sender can send
on a stream at any time, as described in data-flow-control and fc-
credit.
Paragraph (version A):
Data sent in CRYPTO frames is not flow controlled in the same way as
stream data.  QUIC relies on the cryptographic protocol
implementation to avoid excessive buffering of data; see QUIC-TLS.
The implementation SHOULD provide an interface to QUIC to tell it
about its buffering limits so that there is not excessive buffering
at multiple layers.
Paragraph (version B):
Data sent in CRYPTO frames is not flow controlled in the same way as
stream data.  QUIC relies on the cryptographic protocol
implementation to avoid excessive buffering of data; see QUIC-TLS.
To avoid excessive buffering at multiple layers, QUIC implementations
SHOULD provide an interface for the cryptographic protocol
implementation to communicate its buffering limits.
Paragraph (version A):
A receiver sets initial limits for all streams by sending transport
parameters during the handshake (transport-parameters).  A receiver
sends MAX_STREAM_DATA (frame-max-stream-data) or MAX_DATA (frame-max-
data) frames to the sender to advertise larger limits.
Paragraph (version A):
A receiver can advertise a larger limit for a stream by sending a
MAX_STREAM_DATA frame with the corresponding stream ID.  A
MAX_STREAM_DATA frame indicates the maximum absolute byte offset of a
stream.  A receiver could use the current offset of data consumed to
determine the flow control offset to be advertised.
Paragraph (version A):
A receiver can advertise a larger limit for a connection by sending a
MAX_DATA frame, which indicates the maximum of the sum of the
absolute byte offsets of all streams.  A receiver maintains a
cumulative sum of bytes received on all streams, which is used to
check for violations of the advertised connection or stream data
limits.  A receiver might use a sum of bytes consumed on all streams
to determine the maximum data limit to be advertised.
Paragraph (version B):
A receiver sets initial limits for all streams through transport
parameters during the handshake (transport-parameters).
Subsequently, a receiver sends MAX_STREAM_DATA (frame-max-stream-
data) or MAX_DATA (frame-max-data) frames to the sender to advertise
larger limits.
Paragraph (version B):
A receiver can advertise a larger limit for a stream by sending a
MAX_STREAM_DATA frame with the corresponding stream ID.  A
MAX_STREAM_DATA frame indicates the maximum absolute byte offset of a
stream.  A receiver could determine the flow control offset to be
advertised based on the current offset of data consumed on that
stream.
Paragraph (version B):
A receiver can advertise a larger limit for a connection by sending a
MAX_DATA frame, which indicates the maximum of the sum of the
absolute byte offsets of all streams.  A receiver maintains a
cumulative sum of bytes received on all streams, which is used to
check for violations of the advertised connection or stream data
limits.  A receiver could determine the maximum data limit to be
advertised based on the sum of bytes consumed on all streams.
Paragraph (version A):
If a sender has sent data up to the limit, it will be unable to send
new data and is considered blocked.  A sender SHOULD send a
STREAM_DATA_BLOCKED or DATA_BLOCKED frame to indicate it has data to
write but is blocked by flow control limits.  If a sender is blocked
for a period longer than the idle timeout (idle-timeout), the
receiver might close the connection even when the sender has data
that is available for transmission.  To keep the connection from
closing, a sender that is flow control limited SHOULD periodically
send a STREAM_DATA_BLOCKED or DATA_BLOCKED frame when it has no ack-
eliciting packets in flight.
Paragraph (version B):
If a sender has sent data up to the limit, it will be unable to send
new data and is considered blocked.  A sender SHOULD send a
STREAM_DATA_BLOCKED or DATA_BLOCKED frame to indicate to the receiver
that it has data to write but is blocked by flow control limits.  If
a sender is blocked for a period longer than the idle timeout (idle-
timeout), the receiver might close the connection even when the
sender has data that is available for transmission.  To keep the
connection from closing, a sender that is flow control limited SHOULD
periodically send a STREAM_DATA_BLOCKED or DATA_BLOCKED frame when it
has no ack-eliciting packets in flight.
Paragraph (version A):
To avoid blocking a sender, a receiver MAY send a MAX_STREAM_DATA or
MAX_DATA frame multiple times within a round trip or send it early
enough to allow for recovery from loss of the frame.
Paragraph (version B):
To avoid blocking a sender, a receiver MAY send a MAX_STREAM_DATA or
MAX_DATA frame multiple times within a round trip or send it early
enough to allow time for loss of the frame and subsequent recovery.
Paragraph (version A):
An endpoint that is unable to ensure that a peer has flow control
credit on the order of the current BDP will have receive throughput
limited by flow control.  Lost packets can cause gaps in the receive
buffer, delaying the application from consuming data and freeing up
flow control window.
Paragraph (version B):
If an endpoint cannot ensure that its peer always has available flow
control credit that is greater than the peer's bandwidth-delay
product on this connection, its receive throughput will be limited by
flow control.
Paragraph (version B):
Packet loss can cause gaps in the receive buffer, preventing the
application from consuming data and freeing up receive buffer space.
Paragraph (version A):
The final size of a stream is always signaled to the recipient.  The
final size is the sum of the Offset and Length fields of a STREAM
frame with a FIN flag, noting that these fields might be implicit.
Alternatively, the Final Size field of a RESET_STREAM frame carries
this value.  This ensures that all ways that a stream can be closed
result in the number of bytes on the stream being reliably
transmitted.  This guarantees that both endpoints agree on how much
flow control credit was consumed by the stream.
Paragraph (version B):
A sender always communicates the final size of a stream to the
receiver reliably, no matter how the stream is terminated.  The final
size is the sum of the Offset and Length fields of a STREAM frame
with a FIN flag, noting that these fields might be implicit.
Alternatively, the Final Size field of a RESET_STREAM frame carries
this value.  This guarantees that both endpoints agree on how much
flow control credit was consumed by the sender on that stream.
Paragraph (version A):
Once a final size for a stream is known, it cannot change.  If a
RESET_STREAM or STREAM frame is received indicating a change in the
final size for the stream, an endpoint SHOULD respond with a
FINAL_SIZE_ERROR error; see error-handling.  A receiver SHOULD treat
receipt of data at or beyond the final size as a FINAL_SIZE_ERROR
error, even after a stream is closed.  Generating these errors is not
mandatory, but only because requiring that an endpoint generate these
errors also means that the endpoint needs to maintain the final size
state for closed streams, which could mean a significant state
commitment.
Paragraph (version B):
Once a final size for a stream is known, it cannot change.  If a
RESET_STREAM or STREAM frame is received indicating a change in the
final size for the stream, an endpoint SHOULD respond with a
FINAL_SIZE_ERROR error; see error-handling.  A receiver SHOULD treat
receipt of data at or beyond the final size as a FINAL_SIZE_ERROR
error, even after a stream is closed.  Generating these errors is not
mandatory, because requiring that an endpoint generate these errors
also means that the endpoint needs to maintain the final size state
for closed streams, which could mean a significant state commitment.
Paragraph (version A):
As with stream and connection flow control, this document leaves when
and how many streams to advertise to a peer via MAX_STREAMS to
implementations.  Implementations might choose to increase limits as
streams close to keep the number of streams available to peers
roughly consistent.
Paragraph (version B):
As with stream and connection flow control, this document leaves
implementations to decide when and how many streams should be
advertised to a peer via MAX_STREAMS.  Implementations might choose
to increase limits as streams are closed, to keep the number of
streams available to peers roughly consistent.