[Galene] Heads up: incompatible changes to protocol

[Galene] Heads up: incompatible changes to protocol

[Juliusz Chroboczek]

Hi,

This is just to warn people that Galene's protocol will bump its version
within the next weeks.  The current status is as follows:

  - the server in the master branch speaks protocol 1;
  - the servers in the branch "stateful-token" speaks protocol 2;
  - the Javascript client speaks both protocols;
  - the Android client speaks both protocols.

I am not planning to implement any compatibility code on the server side;
on the other hand, I will maintain compatibility with protocol 1 on the
client side for at least a couple versions.

Changes in protocol 2
*********************

Dates are now encoded as strings in RFC 3339 format rather than numbers;
numbers can be used to specify relative dates ("so many milliseconds from
now"), which avoids issues with incorrect client-side clocks.

Error messages may now contain a machine-readable, stable identifier in
the "error" field in addition to the human readable string in the "value"
field.  This makes it possible for the client to react to server-side
messages without having to parse the (human-readable) error message.

Some errors have become non-fatal, they indicate that an action has not
been taken without dropping the connection.  Together with the previous
change, this makes it possible for a client to gracefully recover from an
error, most notably if a feature is not implemented by the server.

There is one new group action and one new user action, used for stateful
tokens (similar to Zoom invites).  This part of the protocol is still in
flux.

What do you need to do?
***********************

## If you're a user

If you're only using the web client, there's nothing to do.  If you're
using the Android client, you should upgrade to a version from 16 December
or later.

## If you're a Javascript frontend developer

Upgrade to a version of the protocol.js library dated 16 December or later.

The type of the "onchat" and "onusermessage" has changed, the "time" field
is now a "Date" object instead of an integer.  You may convert it to an
integer by using the "getTime" method.

## If you're speaking the protocol directly

Ensure that you send "[2,1]" in the version field in the handshake message
to the server, indicating that you speak both versions.  Accept server
handshakes with either version "[1]" or "[2]".

When parsing dates in "chat", "chathistory" and "usermessage" messages,
make sure that you accept both integer dates (in protocol 1) and strings
in RFC 3339 format (in protocol 2).  For example, in Javascript you may
simply use the "Date" constructor, in Python, you may use the
"datetime.fromisoformat" method, and in Go, use "time.RFC3339".

-- Juliusz