Response content type negotiation

[alanz]

Based on an IRC discussion with @hamishmack
#61 And #66 are also relevant.

There are two different but related issues

1. Given that we end up with a specific set of well-known types that can be managed by a given IDE, we need to be able to manage versioning of these, if the format changes.
2. If we end up with a set of semantic types / widgets that can be meaningfully applied in an IDE, we will end up with uneven implementation of these in the set of supporting IDEs.

Both of these seem to require some kind of content negotiation.

A possible solution would be to include a description of the content types (in the sense of semantic type / widget) together with explicit versions in each request from the IDE for a given command. The supported types for a given command could potentially be returned as part of the CommandDesc.

[mgsloan]

This makes sense to me. Annotations are a good concrete example of the need to support multiple response types. We probably wouldn't want to send all the extra annotation metadata in the case that the editor doesn't do anything with it.

[cocreature]

@alanz Do you think we should support multiple versions or just add a version parameter to let the IDE detect if it supports the version of hie running or not?

Personally I would prefer the lattter since being able to create multiple versions is a lot of work on our side and might even be impossible since we can't necessarily reconstruct the old information if we remove something.

Apart from that something like a pvp version scheme for our json might make sense. So increment a minor version if only additions or other non breaking changes are introduced which might enable tho IDE to do new things, but doesn't break the previous behavior and major versions for breaking changes.

[alanz]

There are at least three things that have versions they know/care about

• The IDE
• HIE
• A Plugin

If there are well-known semantic/widget types, these should probably be versioned from the beginning, as part of the JSON definition. And I think at the JSON message level. (Using JSON as a standing for "whatever wire protocol is used in this transport")

In the case of a mismatch, depending on what it is, we could have HIE do some kind of mapping between versions to keep a given plugin/IDE combination happy.

Initially, supplying a list of known semantic/widget types to a plugin should allow it to either return the requested type, or fall back to the standard serialisation, with the proviso that the IDE handling of it may not be optimal.

Beyond that, I think we need to get a feel for real world cases. We do not want to overthink it in the beginning, rather get something simple out that works, and then evolve.

[alanz]

Superseded by move to LSP