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
Copy file name to clipboardExpand all lines: connections/README.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -181,7 +181,7 @@ If the peers agree on a protocol, multistream-select's job is done, and future
181
181
traffic over the channel will adhere to the rules of the agreed-upon protocol.
182
182
183
183
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.
184
+
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.
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.
16
+
When closing a connection or resetting a stream, it's useful to provide the peer
17
+
with a code that explains the reason for the closure. This enables the peer to
18
+
better respond to the abrupt closures. For instance, it can implement a backoff
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 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.
17
21
18
22
## Semantics
19
23
Error codes are unsigned 32-bit integers. The range 0 to 10000 is reserved for
20
24
libp2p errors. Application specific errors can be defined by protocols from
21
-
integers outside of this range. Implementations supporting error codes MUST
22
-
provide the error code provided by the other end to the application.
23
-
24
-
Error codes provide a best effort guarantee that the error will be propagated to
25
-
the application layer. This provides backwards compatibility with older nodes,
26
-
allows smaller implementations, and using transports that don't provide a
27
-
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
30
-
way of signaling an error while closing the read end of the stream on a yamux
31
-
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.
32
28
33
29
### Connection Close and Stream Reset Error Codes
34
-
Error codes are defined separately for Connection Close and Stream Reset. Stream
35
-
Reset errors are from the range 0 to 5000 and Connection Close errors are from
36
-
the range 5001 to 10000. Having separate errors for Connection Close and stream
37
-
reset requires some overlap between the error code definitions but provides more
38
-
information to the receiver. Receiving a `Bad Request: Connection Closed` error
39
-
on reading from a stream also tells the receiver that no more streams can be
40
-
started on the same connection. Implementations MUST provide the Connection
41
-
Close error code on streams that are reset as a result of remote closing the
42
-
connection.
43
-
44
-
For stream resets, when the underlying transport supports it, implementations
45
-
SHOULD allow sending an error code on both closing the read side of the stream, and resetting the write side of the stream.
46
-
47
-
## Libp2p Error Codes
48
-
TODO!
49
-
50
-
## Wire Encoding
51
-
Different transports will encode the 32-bit error code differently.
52
-
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
+
47
+
see [Libp2p error codes](./libp2p-error-codes.md) for the libp2p reserved error
48
+
codes.
49
+
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
+
53
53
### QUIC
54
54
QUIC provides the ability to send an error on closing the read end of the
55
55
stream, resetting the write end of the stream and on closing the connection.
56
56
57
-
For stream resets, the error code MUST be sent on the `RESET_STREAM` or the
58
-
`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
68
-
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.
69
67
70
-
For Connection Close, the 32-bit Length field is interpreted as the error
71
-
code.
68
+
For Connection Close, the 32-bit Length field is interpreted as the error code.
72
69
73
-
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
70
+
For Stream Resets, the error code is sent in the `Window Update` frame, with the
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 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.
77
75
78
76
### WebRTC
79
-
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.
77
+
There is no way to provide any information on closing a peer connection in
78
+
WebRTC. Providing error codes on Connection Close will be taken up in the
79
+
future.
80
80
81
-
For Stream Resets, the error code can be sent in the `errorCode` field of the WebRTC message with `flag` set to `RESET_STREAM` .
81
+
For Stream Resets, the error code can be sent in the `errorCode` field of the
82
+
WebRTC message with `flag` set to `RESET_STREAM`.
82
83
83
84
### WebTransport
84
85
Error codes for WebTransport will be introduced when browsers upgrade to draft-9
@@ -90,3 +91,6 @@ as the latest WebTransport draft,
allows for a 4-byte error code to be sent on stream resets, we will introduce
92
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