chainHead: Allow single connection calls and enforce order of events

[lexnv]

To avoid any confusion wrt the order of received events:

• State that the operationID is received before any other announcement that may contain the operationID
• The chainHead subscription ID is only valid in the context of the same established connection
  • This disallows the users from having one chainHead_follow connection; then call chainHead_storage from another connection (different socket) and drive the events on the first connection. For this to happen, the user would need to know the IP address of the server.

Closes https://github.com/paritytech/json-rpc-interface-spec/issues/125.

[tomaka]

I'm not such a fan of the word "connection". The JSON-RPC API doesn't necessarily go over a connection.

The fact that the JSON-RPC API is done over WebSocket is more or less out of scope (although, of course, pragmatically speaking we shouldn't design the API in such a way that it wouldn't work on WebSocket). In principle, given that you're only ever supposed to connect to JSON-RPC API to a node that you own, doing JSON-RPC over inter-process communication or function calls is arguably more idiomatic than over WebSocket.

Additionally, there's no reason why this is explained for chainHead_follow but not for sudo_network_watch or transactionsWatch, even though they're also concerned.

In my opinion, we should only mention the sentence about connections as a note in chainHead_follow, sudo_network_watch, and transactionsWatch, and add "in case of a JSON-RPC server that accepts multiple different client connections" as a preamble.

[josepot]

The problem with this is that now we must always add the same repetitive (and IMO superfluous) sentence whenever a method returns an opaque value for representing a subscription. For instance, this PR missed adding that same remark into the return value of the chainHead_unstable_follow method.

Wouldn't it be easier to add a general remark in the API specification section stating that any time that a method returns an opaque value representing a subscription, that opaque value is guaranteed to be returned before any of its upcoming notifications?

[jsdw]

Wouldn't it be easier to add a general remark in the API specification section stating that any time that a method returns an opaque value representing a subscription, that opaque value is guaranteed to be returned before any of its upcoming notifications?

This would work for me too!