Skip to content

Commit

Permalink
review comments
Browse files Browse the repository at this point in the history
  • Loading branch information
sukunrt committed Sep 10, 2024
1 parent 693b487 commit 070f090
Show file tree
Hide file tree
Showing 2 changed files with 39 additions and 41 deletions.
77 changes: 36 additions & 41 deletions error-codes/README.md
Original file line number Diff line number Diff line change
@@ -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 over 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
Expand All @@ -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
Expand All @@ -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.
3 changes: 3 additions & 0 deletions webrtc/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
```

Expand Down

0 comments on commit 070f090

Please sign in to comment.