error codes: provide error codes on stream reset and connection close #623
Conversation
sukunrt
force-pushed
the
error-codes
branch
from
3b23cde to
070f090
Compare
Do we need to? Application protocols can have conflicting error codes. From the application context, it's clear which is the relevant error. I am planning to reserve a space for libp2p to use for its errors and let applications do whatever they like with the application error codes space. |
They're not conflicting, since the application protocol is negotiated during the QUIC handshake.
This is not correct, thanks to multistream. |
sukunrt
force-pushed
the
error-codes
branch
from
d0db0b2 to
3060cd0
Compare
|
I see. All connections are just libp2p connections and they can speak multiple application protocols any of which may close the underlying connection on error. |
sukunrt
force-pushed
the
error-codes
branch
3 times, most recently
from
196f49e to
168a610
Compare
sukunrt
requested review from
MarcoPolo,
achingbrain,
yiannisbot,
marten-seemann and
jxs
error-codes/README.md
Outdated
| ``` | ||
|
|
||
| ### Multistream Select | ||
| 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. |
There was a problem hiding this comment.
This is not too useful. The most common case here is a server rejecting a connection because the handling it exceeds some resource limit. In such cases Writing on the connection and closing will cause the write to be dropped because almost certainly there will be unread data in the read buffer.
There was a problem hiding this comment.
To be clear, does this end with a new line or no newline?
This also sounds like it would require spec changes for multistream select (similar to the wording here).
With the point you bring up, maybe it's not worth adding error codes to MSS right now.
error-codes/README.md
Outdated
| ## Error Codes Registry | ||
| 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. | ||
|
|
||
| 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/ |
There was a problem hiding this comment.
Is there much value in having this be a separate repo? Why not have it in the specs repo in a sub folder of error-codes?
There was a problem hiding this comment.
It'll require reviewing PRs for new allocations here. We can start here and then move to a new repo if needed. How does that sound?
error-codes/README.md
Outdated
| 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. | ||
|
|
||
| ### WebRTC | ||
| There is no way to provide any information on closing a peer connection in |
There was a problem hiding this comment.
The wording here is confusing.
| 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. | ||
|
|
||
| ## Error Codes Registry | ||
| 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. |
There was a problem hiding this comment.
We should outline a process to allocate these error codes. e.g. something as simple as:
- A user requests a certain number of error codes.
- We ensure it's a reasonable request.
- Verify the number is reasonable (e.g. not 16k errors)
- Verify there is no conflict.
- Allocate that in a high number space.
The process exists so that we can make it easier for future reviewers.
error-codes/README.md
Outdated
| ### Libp2p Reserved Error Codes | ||
| 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. | ||
|
|
||
| Error codes from 1 to 100 are reserved for transport errors. These are used by the transports to terminate connections on transport errors. |
There was a problem hiding this comment.
Can we make these ranges that fit neatly into a bit mask? It'll look and feel nicer to say transport errors are error codes between 0x01 and 0x7f. Same for the libp2p reserved error codes.
No description provided.