review comments

Author: sukunrt

error-codes/README.md

@@ -1,25 +1,29 @@
 # Error Codes
 
+| Lifecycle Stage | Maturity      | Status | Latest Revision |
+| --------------- | ------------- | ------ | --------------- |
+| 1A              | Working Draft | Active | r0, 2023-01-23  |
+
+Authors: [@sukunrt]
+
+Interest Group: [@marcopolo], [@achingbrain]
+
+[@MarcoPolo]: https://github.com/MarcoPolo
+[@achingbrain]: https://github.com/achingbrain
+
 ## Introduction
-In the event that a node detects violation of a protocol or is unable to
-complete the necessary steps required for the protocol, it's useful to provide a
-reason for disconnection to the other end. This error code can be sent on both
-Connection Close and Stream Reset. Its purpose is similar to http response
-status. A server, on receiving an invalid request can reset the stream providing
-a `BAD_REQUEST` error code, when it's busy handling too many requests can
-provide a `RATE_LIMITED` error code, etc. An error code doesn't always indicate
-an error condition. For example, a connection may be closed prematurely because
-a connection to the same peer on a better transport is available. 
+
+When closing a connection or resetting a stream, it's useful to provide the peer with a code that explains the reason for the closure. This enables the peer to better respond to the abrupt closures. For instance, it can implement a backoff strategy to retry _only_ when it receives a `RATE_LIMITED` error code. An error code doesn't always indicate an error condition. For example, a connection may be closed because a connection to the same peer on a better transport is available. 
 
 ## Semantics
-Error codes are unsigned 32bit integers. The range 0 to 10000 is reserved for
+Error codes are unsigned 32-bit integers. The range 0 to 10000 is reserved for
 libp2p errors. Application specific errors can be defined by protocols from
 integers outside of this range. Implementations supporting error codes MUST
 provide the error code provided by the other end to the application.
 
-Error codes provide a best effort guarantee that the error will be propogated to
-the applciation layer. This provides backwards compatibility with older nodes,
-allows smaller implementations and using transports that don't provide a
+Error codes provide a best effort guarantee that the error will be propagated to
+the application layer. This provides backwards compatibility with older nodes,
+allows smaller implementations, and using transports that don't provide a
 mechanism to provide an error code. For example, Yamux has no equivalent of
 QUIC's [STOP_SENDING](https://www.rfc-editor.org/rfc/rfc9000.html#section-3.5-4)
 frame that would tell the peer that the node has stopped reading. So there's no
@@ -38,18 +42,17 @@ Close error code on streams that are reset as a result of remote closing the
 connection. 
 
 For stream resets, when the underlying transport supports it, implementations
-SHOULD allow sending an error code on both closing the read side of the stream
-and resetting the write side of the stream. 
+SHOULD allow sending an error code on both closing the read side of the stream, and resetting the write side of the stream. 
 
 ## Libp2p Error Codes
 TODO!
 
 ## Wire Encoding
-Different transports will encode the 32bit error code differently. 
+Different transports will encode the 32-bit error code differently. 
 
 ### QUIC
 QUIC provides the ability to send an error on closing the read end of the
-stream, reseting the write end of the stream and on closing the connection. 
+stream, resetting the write end of the stream and on closing the connection. 
 
 For stream resets, the error code MUST be sent on the `RESET_STREAM` or the
 `STOP_SENDING` frame using the `Application Protocol Error Code` field as per
@@ -64,34 +67,26 @@ using the Error Code field as defined in the
 Yamux has no `STOP_SENDING` frame, so there's no way to signal an error on
 closing the read side of the stream.
 
-For Connection Close, the 32bit Length field is to be interpreted as the error
-code. The error code MUST be sent as an  Big Endian unsigned 32 bit integer. 
+For Connection Close, the 32-bit Length field is interpreted as the error
+code.
 
-For Stream Resets, the error code is sent as the first 4 bytes of the Data Frame
-following the header with RST flag set as defined in the [yamux spec
+For Stream Resets, the error code is sent in the `Window Update` frame, with the 32-bit Length field interpreted as the error code. See [yamux spec
 extension](https://github.com/libp2p/specs/pull/622).
 
-Note: On TCP connections with `SO_LINGER` set to 0, the error code on connection
-close may not be delivered.  
+Note: On TCP connections with `SO_LINGER` set to 0, the Connection Close error code may not be delivered.  
 
 ### WebRTC
-Since WebRTC doesn't provide reliable delivery for frames that are followed by
-closing of the underlying data channel, there's no simple way to introduce error
-codes in the current implementation. Consider the most common use case of
-resetting both read and write sides of the stream and closing the data channel.
-The chrome implementation will not deliver the final `RESET_STREAM` msg and
-while the go implementation will delivery the `RESET_STREAM` frame and then
-close the data channel, there's no guarantee that the chrome implementation will
-provide the `RESET_STREAM` msg to the application layer after it receives the
-data channel close message. 
+There is no way to provide any information on closing a peer connection in WebRTC. Providing error codes on Connection Close will be taken up in the future. 
+
+For Stream Resets, the error code can be sent in the `errorCode` field of the WebRTC message with `flag` set to `RESET_STREAM` .
 
 ### WebTransport
-Error codes for webtransport will be introduced when browsers upgrade to draft-9
-of the spec. The current webtransport spec implemented by chrome and firefox is
-[draft-2 of webtransport over
-http3](https://www.ietf.org/archive/id/draft-ietf-webtrans-http3-02.html#section-4.3-2).
-This version allows for only a 1 byte error code. 1 byte is too restrictive and
-as the latest webtransport draft,
-(draft-9)[https://www.ietf.org/archive/id/draft-ietf-webtrans-http3-02.html#section-4.3-2]
-allows for a 4 byte error code to be sent on stream resets, we will introduce
-error codes over webtransport later.
+Error codes for WebTransport will be introduced when browsers upgrade to draft-9
+of the spec. The current WebTransport spec implemented by Chrome and Firefox is
+[draft-2 of WebTransport over
+HTTP/3](https://www.ietf.org/archive/id/draft-ietf-webtrans-http3-02.html#section-4.3-2).
+This version allows for only a 1-byte error code. 1 byte is too restrictive and
+as the latest WebTransport draft,
+[draft-9](https://www.ietf.org/archive/id/draft-ietf-webtrans-http3-02.html#section-4.3-2)
+allows for a 4-byte error code to be sent on stream resets, we will introduce
+error codes over WebTransport later.

webrtc/README.md

@@ -76,6 +76,9 @@ message Message {
   optional Flag flag=1;
 
   optional bytes message = 2;
+
+  // errorCode is the reason for resetting the stream. This field is only meaningful when flag is set to RESET_STREAM 
+  optional uint32 errorCode = 3;
 }
 ```