add some canonical error codes

Author: sukunrt

error-codes/README.md

@@ -13,7 +13,13 @@ Interest Group: [@marcopolo], [@achingbrain]
 
 ## Introduction
 
-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. 
+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 32-bit integers. The range 0 to 10000 is reserved for
@@ -42,10 +48,12 @@ 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!
+## Libp2p Reserved Error Codes
+see [Libp2p error codes](./libp2p-error-codes.md) for the libp2p reserved error
+codes.
 
 ## Wire Encoding
 Different transports will encode the 32-bit error code differently. 
@@ -67,18 +75,22 @@ 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 32-bit Length field is interpreted as the error
-code.
+For Connection Close, the 32-bit Length field is interpreted as the error code.
 
-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
+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 Connection Close error code may not be delivered.  
+Note: On TCP connections with `SO_LINGER` set to 0, the Connection Close error
+code may not be delivered.  
 
 ### WebRTC
-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. 
+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` .
+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

error-codes/libp2p-error-codes.md

@@ -0,0 +1,32 @@
+# Libp2p error codes
+
+## TODO!
+make this a CSV
+
+## Connection Error Codes
+
+| Name | Code | Description |
+| --- | --- | --- |
+| NO_ERROR | 0 | No reason provided for disconnection. This is equivalent to closing a connection or resetting a stream without any error code. | 
+| Reserved For Transport | 0x1 - 0x1000 | Reserved for transport level error codes. | 
+| GATED | 0x1001 | The connection was gated. Most likely the IP / node is blacklisted. |
+| RESOURCE_LIMIT_EXCEEDED | 0x1002 | Rejected because we ran into a resource limit. Implementations MAY retry with a backoff |
+| RATE_LIMITED | 0x1003 | Rejected because the connection was rate limited. Implementations MAY retry with a backoff |
+| PROTOCOL_VIOLATION | 0x1004 | Peer violated the protocol |
+| SUPPLANTED | 0x1005 | Connection closed because a connection over a better tranpsort was available |
+| GARBAGE_COLLECTED | 0x1006 | Connection was garbage collected |
+| SHUTDOWN | 0x1007 | The node is going down |
+| PROTOCOL_NEGOTIATION_FAILED | 0x1008 | Rejected because we couldn't negotiate a protocol |
+
+
+## Stream Error Codes
+
+| Name | Code | Description |
+| --- | --- | --- |
+| NO_ERROR | 0 | No reason provided for disconnection. This is equivalent to resetting a stream without any error code. | 
+| Reserved For Transport | 0x1 - 0x1000 | Reserved for transport level error codes. | 
+| PROTOCOL_NEGOTIATION_FAILED | 0x1001 | Rejected because we couldn't negotiate a protocol |
+| RESOURCE_LIMIT_EXCEEDED | 0x1002 | Connection rejected because we ran into a resource limit. Implementations MAY retry with a backoff |
+| RATE_LIMITED | 0x1003 | Rejected because the connection was rate limited. Implementations MAY retry with a backoff |
+| BAD_REQUEST | 0x1004 | Rejected because the request was invalid |
+| PROTOCOL_VIOLATION | 0x1005 | Rejected because the stream protocol was violated. MAY be used interchangably with `BAD_REQUEST` |