Error codes are assigned an inappropriate ordinal for JSON-RPC spec

The error codes defined below:

https://github.com/microsoft/vscode-languageserver-node/blob/66f91b3583a19ae621214d908ce19c9b2d182626/jsonrpc/src/common/messages.ts#L46-L49

are set to values within the JSON-RPC spec reserved range for server implementations:

code	message	meaning
-32000 to -32099	Server error	Reserved for implementation-defined server-errors.

This JSON-RPC library does not ever use ServerNotInitialized. Who is using this? If LSP is using it, shouldn’t it be using a value defined in the range for the application layer?

The remainder of the space is available for application defined errors.

It may be too late to ‘fix’ this, but I wanted to file this issue to draw attention that there is a JSON-RPC spec reserved range for error codes including a subrange reserved for the JSON-RPC implementation itself. Having the app-layer overlap with the implementation layer means that other JSON-RPC implementations (e.g. StreamJsonRpc) that want to use this particular value within their reserved range may cause malfunctions in the remote party that receives the error code and misinterprets it as an app-layer error.

To call out the conflicts we already have:

vscode-jsonrpc	error code	StreamJsonRpc
UnknownErrorCode	-32001	NoMarshaledObjectFound
ServerNotInitialized	-32002	ResponseSerializationFailure (proposed)
serverErrorEnd	-32000	InvocationError
serverErrorStart	-32099	(undefined)

While it’s understandable that JSON-RPC implementations may define a given error code to mean different things, at least it’s all in the implementation layer and won’t be misinterpreted by the application. But when we have higher level protocols like LSP using error codes within the implementation-reserved range, we’re going to get some bad behavior in the app that misinterprets the error code.

Can we add a comment to the source code (and LSP spec perhaps) so that future error codes are not defined in the library-reserved range?

[rcjsuen]

@rcjsuen That makes sense, but to what end? We’re probably not going to be able to change the LSP spec.

If we can’t remove them then we should at least deprecate those values and introduce new ones. At least new clients and servers won’t make this mistake then.

By doing nothing we are continuing to make things difficult for people who implement the JSON RPC specification.

[rcjsuen]

But wouldn’t that again result in the same problem that you and me use the same code for a different meaning ?

That isn’t the issue. That’s what people are supposed to do. The error codes in that range are not for the application layer to interpret.

People that use a JSON RPC library should not assign meaning to error codes in those ranges because every JSON RPC implementation is going to be using error codes in that range for different purposes.

The people that implement a JSON RPC library should be the ones assigning their own custom meaning to an arbitrary code within that range. The application layer should simply surface it to the user as a generic “server error” failure case.

The issue here is that the LSP (the application layer) currently specifically defines -32002 as the error code for ServerNotInitialized. However, JSON RPC library A may be calling -32002 as OutOfMemory and JSON RPC library B may be calling it SocketClosed. These two very different error messages are going to be interpreted by LSP clients as “the server hasn’t initialized yet” because they use the code -32002 when that isn’t what either JSON RPC library is trying to convey at all.