New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Change message params types to match JSON-RPC spec #373

Merged
merged 3 commits into from Mar 8, 2018

Conversation

Projects
None yet
2 participants
@Xanewok
Copy link
Contributor

Xanewok commented Jan 12, 2018

Since the interface is supposed to describe message format to match JSON-RPC spec,
the params type must be specified as either Array or Object.

From spec:

4.2 Parameter Structures

If present, parameters for the rpc call MUST be provided as a Structured value. Either by-position through an Array or by-name through an Object.

Change message params types to match JSON-RPC spec
Since the interface is supposed to describe message format to match [JSON-RPC spec](http://www.jsonrpc.org/specification),
the params type must be specified as either `Array` or `Object`.

From spec:
> 4.2 Parameter Structures
>
> If present, parameters for the rpc call MUST be provided as a Structured value. Either by-position through an Array or by-name through an Object.
@Xanewok

This comment has been minimized.

Copy link
Contributor

Xanewok commented Jan 12, 2018

Analogous to cquery-project/cquery#247, sending not structured values as params (which is currently allowed here via any type), if present, can upset brittle clients/servers, which are parsing messages literally as per JSON-RPC spec.

@dbaeumer

This comment has been minimized.

Copy link
Member

dbaeumer commented Jan 15, 2018

Although we use JSON-RPC as a transport layer we decided to limit the params to a single object. This is why on the specification level we ony support a single object. From a spec point of view we should change the property to object. Does that make sense.

@Xanewok

This comment has been minimized.

Copy link
Contributor

Xanewok commented Jan 16, 2018

I understand that such a limitation might be convenient, however I believe there's a large benefit to retaining the compositional nature of the protocol. It's beneficial to be able to reuse existing JSON-RPC libs and format as is - we could simply add a note, such as 'Array params are technically allowed, but practically unused in LSP' to maintain the compatibility with the JSON-RPC protocol. This would be a win-win, I believe.

@dbaeumer

This comment has been minimized.

Copy link
Member

dbaeumer commented Jan 18, 2018

We do so in the json-rpc library we use and maintain. It allows to handle arrays correct according to the JSON-RPC spec. Limiting this in the protocol is IMO a fair thing to do and nothing we can change without starting to break since users can implement custom messages. I don't see why we should allow array parameters and then say that they very likely will not work. Implementors of the protocol can still use existing JSON-RPC libs since they will work as design with 0 / 1 parameter.

@Xanewok

This comment has been minimized.

Copy link
Contributor

Xanewok commented Jan 18, 2018

I realize this is mostly nitpicking, but we should be more consistent here: we can't just say we use and define interface for JSON-RPC messages, yet do otherwise.

Limiting this in the protocol is IMO a fair thing to do and nothing we can change without starting to break since users can implement custom messages.

The thing is, someone could've implemented custom messages passing params as arrays, which is correct under current phrasing that we use JSON-RPC spec, and also currently (in contradiction to previous phrasing) specified any type for params.

If we were to limit legal params type only to object, then we both technically break JSON-RPC compliance and break possible custom messages.

That is why I meant that we could still allow for Array<any> params - this would still leave some leeway for other possible custom messages to still possibly use legal array params as per JSON-RPC spec and would also disallow other illegal params types (e.g. primitives).

@dbaeumer

This comment has been minimized.

Copy link
Member

dbaeumer commented Feb 9, 2018

You do have a valid point with us claiming that we support JSON-RPC and that custom messages could send arrays. So I would opt to do the following:

  • we fix the request / notification definitions.
  • we add a clear sentence to the Language Server Protocol section to say that in the protocol itself we only use 0 / 1 param.
@Xanewok

This comment has been minimized.

Copy link
Contributor

Xanewok commented Feb 22, 2018

@dbaeumer done, I mentioned in the section that object types here are only used, but in general the LSP shouldn't disallow params of Array<any> type.

@dbaeumer dbaeumer merged commit fd86b9f into Microsoft:gh-pages Mar 8, 2018

1 check passed

license/cla All CLA requirements met.

@Xanewok Xanewok deleted the Xanewok:patch-3 branch Apr 26, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment