Introduce protocol handshake

[hackaugusto]

Abstract

Nodes must be able to detect if the protocol versions are compatible with each other.

Motivation

During client upgrades the network will have mixed protocols versions. Having a handshake improves the network health by avoiding communication across incompatible versions.

Specification

To be done.

Is a monotonic increasing version number sufficient? Are capabilities necessary?

Backwards Compatibility

This needs new messages which are not available for older clients.

[LefterisJP]

This is related: #2161 I guess or even a duplicate?

[andrevmatos]

One possible approach on this is to, instead of using new messages, a node could inform its protocol version through transport, e.g. matrix's displayName, which is already used for other metadata (currently, used only for the proof-of-keys signature of userId, but expansible through added-and-signed custom fields).

[hackaugusto]

Yeah, the means which are used to inform the version can be transport dependent. However, we need to first decide on a scheme, what are the minimum requirements for a version scheme which allows us to upgrade so that nodes can decide when communication will work.

[hackaugusto]

Question is: Are there reasons to believe the message format will evolve separately from application compatibility? (At first I thought #3184 would be a reason to change the semantics of the protocol without changing the protocol format, now I'm not so sure.)

I'm asking this because if we believe the semantics are tied to the messages, we can just have an monotonic increasing protocol version number. Otherwise we may need capabilities.

[andrevmatos]

We did implement Capabilities in Light Client, in a backwards compatible manner.
Here's how we did it:

• own and peer's Capabilities are something in the form: Dict[str, Any], where the key is the capability's name (str), and value can be anything JSON, but so far we're dealing only with bool and str
• this caps is a node's property, where we can compare our own and partner's/peer's picked from their presence/profile
• These Capabilities are de/serialized as follows:
  • Over the list of key/value pairs:
    • If value is a bool and is True, this key/value pair can become just the key; if False, ignore
    • Else, it's currently serializing to string in the form f'{key}="{value}"
  • join this list of key/key-value pairs with ,
    • e.g.: { "noDelivery": True, "noReceive": False, "randomCap": "test" } => 'noDelivery,randomCap="test"'
  • This string is put in Matrix's avatar_url, and picked & parsed together with user's presence
• Now, whenever we are doing anything with the user, we can compare if some caps of ours is set, and compare that with partner's caps
  • e.g.: if peer.caps.get('noDelivery'): # skip sending Delivered
  • e.g.: if self.caps.get('webRTC') and peer.caps.get('webRTC'): # try to open webRTC channel
• Our current list of caps:
  • noDelivery: we don't need Delivered messages, but won't care if you send either
  • noReceive: we will ignore received transfers, so don't bother or you'll need to expire it later
  • noMediate: same as above, but for mediating
  • webRTC: we support WebRTC channels for p2p messaging

Notice all of this is just convention, so if any node doesn't support some capability, or even doesn't support capabilities at all, uses some caps different than ours, or don't respect our caps, behavior still flows as before (e.g. Delivered message is sent or received), so we can implement whatever we want and support only agreed behaviors

[konradkonrad]

• current light client boolean flags are here
• it seems the light client implementation uses the avatar_url

ToDo:

• add documentation about capability flags
• introduce capabilities in constants.py and settings.py
• add capability parser
• set capabilities in avatar_url
• parse peer capabilities and persist in peer state
• supply our capabilities to node state

Questions:

How to deal with changing peer capabilities?

We should re-query peer capabilities on node reachability changes. This could become a part of the ActionChangeNodeNetworkState state change. Does this need its own state change though?

What should happen to an in-flight transfer, if the peer capabilities change?

[andrevmatos]

We should re-query peer capabilities on node reachability changes.

This comes automatically from matrix as part of presences updates for users of interest (users we have a room with, even if one of the global rooms), and is pushed to room's state (on rooms where state is kept, not global rooms). There are endpoints to query explicitly if we didn't get this field as part of a presence update. Here's how we did it.

What should happen to an in-flight transfer, if the peer capabilities change?

We only verify capabilities in the critical points: e.g. when beginning to send a transfer, or when user came online and we're opening a webRTC channel with them. Since our capabilities are "by convention", it's safe and still covered by the protocol if this changes (e.g. the partner may reject the transfer if they want and let it expire).