You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -181,7 +182,7 @@ If the peers agree on a protocol, multistream-select's job is done, and future
181
182
traffic over the channel will adhere to the rules of the agreed-upon protocol.
182
183
183
184
If a peer receives a `"na"` response to a proposed protocol id, they can either
184
-
try again with a different protocol id or close the channel.
185
+
try again with a different protocol id or close the channel with error code `PROTOCOL_NEGOTIATION_FAILED` as defined in [libp2p error codes](./../error-codes/README.md) spec
Copy file name to clipboardExpand all lines: error-codes/README.md
+32-40
Original file line number
Diff line number
Diff line change
@@ -17,80 +17,69 @@ When closing a connection or resetting a stream, it's useful to provide the peer
17
17
with a code that explains the reason for the closure. This enables the peer to
18
18
better respond to the abrupt closures. For instance, it can implement a backoff
19
19
strategy to retry _only_ when it receives a `RATE_LIMITED` error code. An error
20
-
code doesn't always indicate an error condition. For example, a connection may
21
-
be closed because a connection to the same peer over a better transport is
22
-
available.
20
+
code doesn't always indicate an error condition. For example, a node can terminate an idle connection, or close a connection because a connection to the same peer over a better transport is available. In both these cases, it can signal an appropriate error code to the other end.
23
21
24
22
## Semantics
25
23
Error codes are unsigned 32-bit integers. The range 0 to 10000 is reserved for
26
24
libp2p errors. Application specific errors can be defined by protocols from
27
-
integers outside of this range. Implementations supporting error codes MUST
28
-
provide the error code provided by the other end to the application.
29
-
30
-
Error codes provide a best effort guarantee that the error will be propagated to
31
-
the application layer. This provides backwards compatibility with older nodes,
32
-
allows smaller implementations, and using transports that don't provide a
33
-
mechanism to provide an error code. For example, Yamux has no equivalent of
frame that would tell the peer that the node has stopped reading. So there's no
36
-
way of signaling an error while closing the read end of the stream on a yamux
37
-
connection.
25
+
integers outside of this range. Error Codes can be signaled on Closing a connection or on resetting a Stream.
26
+
27
+
From an application perspective, error codes provide a best effort guarantee. On resetting a libp2p stream or closing a connection with an error code, the error code may or may not be delivered to the application on the remote end. The specifics depend on the transport used. For example, WebTransport doesn't support error codes at all, while WebRTC doesn't support Connection Close error codes, but supports Stream Reset error codes.
38
28
39
29
### Connection Close and Stream Reset Error Codes
40
-
Error codes are defined separately for Connection Close and Stream Reset. Stream
41
-
Reset errors are from the range 0 to 5000 and Connection Close errors are from
42
-
the range 5001 to 10000. Having separate errors for Connection Close and stream
43
-
reset requires some overlap between the error code definitions but provides more
44
-
information to the receiver. Receiving a `Bad Request: Connection Closed` error
45
-
on reading from a stream also tells the receiver that no more streams can be
46
-
started on the same connection. Implementations MUST provide the Connection
47
-
Close error code on streams that are reset as a result of remote closing the
48
-
connection.
49
-
50
-
For stream resets, when the underlying transport supports it, implementations
51
-
SHOULD allow sending an error code on both closing the read side of the stream,
52
-
and resetting the write side of the stream.
53
-
54
-
## Libp2p Reserved Error Codes
30
+
Error codes are defined separately for Connection Close and Stream Reset. The namespace doesn't overlap as it is clear from the context whether the stream was reset by the other end, or it was reset as a result of a connection close.
31
+
Implementations MUST provide the Connection Close error code on streams that are reset as a result of remote closing the connection.
32
+
33
+
Libp2p streams are reset unilaterally, calling `Reset` on a stream resets both the read and write end of a stream. For transports, like QUIC, which support cancelling the read and write ends of the stream separately, implementations MAY provide the ability to signal error codes separately on resetting either end.
34
+
35
+
## Error Codes Registry
36
+
Libp2p connections are shared by multiple applications. The same connection used in the dht may be used for gossip sub, or for any other application. Any of these applications can close the underlying connection on an error, resetting streams used by the other applications. To correctly distinguish which application closed the connection, Connection Close error codes are allocated to applications from a central registry.
37
+
38
+
For simplicity, we manage both Connection Close and Stream Reset error codes from a central registry. The libp2p error codes registry is at: https://github.com/libp2p/error-codes/
39
+
40
+
### Libp2p Reserved Error Codes
41
+
Error code 0 signals that no error code was provided. Implementations MUST handle closing a connection with error code 0 as they handle closing a connection with no error code, and resetting a stream with error code 0 as they handle resetting a stream with no error.
42
+
43
+
Error codes from 1 to 100 are reserved for transport errors. These are used by the transports to terminate connections on transport errors.
44
+
45
+
Error codes from 100 - 10000 are reserved for libp2p. This includes multistream error codes, as it is necessary for libp2p connection establishment over TCP, but not kad-dht or gossip-sub error codes.
46
+
55
47
see [Libp2p error codes](./libp2p-error-codes.md) for the libp2p reserved error
56
48
codes.
57
49
58
-
## Wire Encoding
59
-
Different transports will encode the 32-bit error code differently.
60
-
50
+
## Transport Specification and Wire Encoding
51
+
Different transports will encode the 32-bit error code differently on the wire. They also provide different semantics: Webtransport doesn't define error codes, WebRTC doesn't support Connection Close error codes, Yamux error codes on Connection Close cannot be reliably sent over the wire.
52
+
61
53
### QUIC
62
54
QUIC provides the ability to send an error on closing the read end of the
63
55
stream, resetting the write end of the stream and on closing the connection.
64
56
65
-
For stream resets, the error code MUST be sent on the `RESET_STREAM` or the
66
-
`STOP_SENDING` frame using the `Application Protocol Error Code` field as per
57
+
For stream resets, the error code MUST be sent on `RESET_STREAM` and `STOP_SENDING` frames using the `Application Protocol Error Code` field as per
Yamux has no `STOP_SENDING` frame, so there's no way to signal an error on
76
-
closing the read side of the stream.
66
+
Yamux streams are reset unilaterally. Receiving a stream frame with `RST` flag set resets both the read and write end of the stream. So, there's no way to separately signal error code on closing the read end of the stream, or resetting the write end of the stream.
77
67
78
68
For Connection Close, the 32-bit Length field is interpreted as the error code.
79
69
80
70
For Stream Resets, the error code is sent in the `Window Update` frame, with the
81
71
32-bit Length field interpreted as the error code. See [yamux spec
Note: On TCP connections with `SO_LINGER` set to 0, the Connection Close error
85
-
code may not be delivered.
74
+
Connection Close error code delivery to the other end depends on the OS TCP implementation and the TCP options used for the socket. In particular, when `SO_LINGER` TCP option is set to 0 and the implementation closes the connection immediately after writing the error code containing frame, the error code may not be delivered.
86
75
87
76
### WebRTC
88
77
There is no way to provide any information on closing a peer connection in
89
78
WebRTC. Providing error codes on Connection Close will be taken up in the
90
79
future.
91
80
92
81
For Stream Resets, the error code can be sent in the `errorCode` field of the
93
-
WebRTC message with `flag` set to `RESET_STREAM`.
82
+
WebRTC message with `flag` set to `RESET_STREAM`.
94
83
95
84
### WebTransport
96
85
Error codes for WebTransport will be introduced when browsers upgrade to draft-9
@@ -102,3 +91,6 @@ as the latest WebTransport draft,
allows for a 4-byte error code to be sent on stream resets, we will introduce
104
93
error codes over WebTransport later.
94
+
95
+
### Multistream Select
96
+
Multistream-Select is used to negotiate Security protocol for TCP connections before a stream muxer has been selected. There's only one error code defined for such cases, `PROTOCOL_NEGOTIATION_FAILED`. To encode this error, send the string `101` prefixed with the length and close the TCP connection.
0 commit comments