[Galene] Versioning the Galene protocol

[Galene] Versioning the Galene protocol

[Juliusz Chroboczek]

Hi,

Following Rémi's issues, and since there are a number of third-party
clients for Galène slowly starty to emerge [1,2,3], I think the time has
come to add some versioning and extensibility to the Galene protocol.

Now Galene uses three different protocols:

1. A very simple REST interface, that is used to populate the list of
   public groups and to discover group parameters before connecting.

2. A WebSocket based protocol, used for chat and audio/video codec
   negotiation.

3. The whole WebRTC protocol stack, which is used for transmitting audio
   and video.

The protocol that needs versioning is the WebSocket-based protocol, number
(2) above.  It is described here:

  https://galene.org/README.PROTOCOL.html#message-syntax

I've given it some thought, and here are my plans.  Please let me know if
you think I'm missing something.

1. I'm going to ignore the built-in protocol negotiation of the WebSocket
   transport, since I don't feel that version negotiation should be done
   at this layer.

2. The protocol starts with an exchange of 'handshake' messages.  I'm
   going to add a field 'version' to the handshake messages, and if the
   versions don't match, the connection fails.

   Since the client sends it handshake first, this means that the client
   will need to commit to a single version, while the server will be able
   to adapt its version depending on what was announced by the client.  An
   alternative would be to allow the client to announce a list of versions
   that it supports -- is that useful?

3. If it is useful, we may add an "extensions" field to the handshake
   message, in order to allow a peer to announce that it supports
   extensions to the protocol, for example new groupactions.

Other than the versioning, I have only one change to make to the protocol
right now: I'm planning to require that the client request explicitly that
it is interested in chat messages.  (Currently, the client needs to
actively request media streams, but it has no way to state that it is not
interested in chat messages.)

Comments welcome, none of this has been implemented yet, so it's easy to
change.

[1] https://github.com/garage44/pyrite
[2] https://github.com/erdnaxe/galene-stream
[3] https://github.com/igniterealtime/openfire-galene-plugin

-- Juliusz

[Galene] Fw: Re: Versioning the Galene protocol

[Jeroen van Veen]

Hi Juliusz,

> 2. The protocol starts with an exchange of 'handshake' messages. I'm
> going to add a field 'version' to the handshake messages, and if the
> versions don't match, the connection fails.

Sounds good! Additionally, it may be useful to have the protocol.js as a npm package
in the Galene repo with its own releases on npm. This would make it easier for external
Javascript projects to work with the protocol library. It would add some complexity for
Galene's own client, but an additional bundle step may not even be necessary when using
es-modules.

The current flow to use an updated protocol.js is to copy-paste it from
the Galene repo into its own file locally, and then add an export to expose the
ServerConnection & Stream. Easy to do, but having a library with its own
semver may make it easier to communicate major/minor/patch protocol changes.

> Since the client sends it handshake first, this means that the client
> will need to commit to a single version, while the server will be able
> to adapt its version depending on what was announced by the client. An
> alternative would be to allow the client to announce a list of versions
> that it supports -- is that useful?

Why support multiple versions of the same protocol? Wouldn't that only complicate
things at the Galene side? I don't mind personally to stick to a version of the protocol,
that was made to work with that particular version of Galene.

> 3. If it is useful, we may add an "extensions" field to the handshake
> message, in order to allow a peer to announce that it supports
> extensions to the protocol, for example new group actions.
>
> Other than the versioning, I have only one change to make to the protocol
> right now: I'm planning to require that the client request explicitly that
> it is interested in chat messages. (Currently, the client needs to
> actively request media streams, but it has no way to state that it is not
> interested in chat messages.)

Would that be to be able to subscribe to certain kind of messages? (e.g. chat)
Otherwise, I don't understand the use for it. Could you ellaborate?
Would it be a problem to just be able to use newly added group actions
in the protocol without explicitly having to mention that it's part
of an extension?

cheers,

Jeroen


> ------- Original Message -------
> Op woensdag 13 juli 2022 om 7:16 PM schreef Juliusz Chroboczek jch@irif.fr:
>
>
>
> > Hi,
> >
> > Following Rémi's issues, and since there are a number of third-party
> > clients for Galène slowly starty to emerge [1,2,3], I think the time has
> > come to add some versioning and extensibility to the Galene protocol.
> >
> > Now Galene uses three different protocols:
> >
> > 1. A very simple REST interface, that is used to populate the list of
> > public groups and to discover group parameters before connecting.
> >
> > 2. A WebSocket based protocol, used for chat and audio/video codec
> > negotiation.
> >
> > 3. The whole WebRTC protocol stack, which is used for transmitting audio
> > and video.
> >
> > The protocol that needs versioning is the WebSocket-based protocol, number
> > (2) above. It is described here:
> >
> > https://galene.org/README.PROTOCOL.html#message-syntax
> >
> > I've given it some thought, and here are my plans. Please let me know if
> > you think I'm missing something.
> >
> > 1. I'm going to ignore the built-in protocol negotiation of the WebSocket
> > transport, since I don't feel that version negotiation should be done
> > at this layer.
> >
> > 2. The protocol starts with an exchange of 'handshake' messages. I'm
> > going to add a field 'version' to the handshake messages, and if the
> > versions don't match, the connection fails.
> >
> > Since the client sends it handshake first, this means that the client
> > will need to commit to a single version, while the server will be able
> > to adapt its version depending on what was announced by the client. An
> > alternative would be to allow the client to announce a list of versions
> > that it supports -- is that useful?
> >
> > 3. If it is useful, we may add an "extensions" field to the handshake
> > message, in order to allow a peer to announce that it supports
> > extensions to the protocol, for example new groupactions.
> >
> > Other than the versioning, I have only one change to make to the protocol
> > right now: I'm planning to require that the client request explicitly that
> > it is interested in chat messages. (Currently, the client needs to
> > actively request media streams, but it has no way to state that it is not
> > interested in chat messages.)
> >
> > Comments welcome, none of this has been implemented yet, so it's easy to
> > change.
> >
> > [1] https://github.com/garage44/pyrite
> > [2] https://github.com/erdnaxe/galene-stream
> > [3] https://github.com/igniterealtime/openfire-galene-plugin
> >
> > -- Juliusz
> > _______________________________________________
> > Galene mailing list -- galene@lists.galene.org
> > To unsubscribe send an email to galene-leave@lists.galene.org

[Galene] Re: Fw: Re: Versioning the Galene protocol

[Juliusz Chroboczek]

> Why support multiple versions of the same protocol? Wouldn't that only
> complicate things at the Galene side? I don't mind personally to stick
> to a version of the protocol, that was made to work with that particular
> version of Galene.

If the server cannot support multiple versions, then every change to the
protocol breaks all non-web clients.  (There's Galene-stream already, and
I'd really like to see a native client for Android that can do screenshare.)

> Would that be to be able to subscribe to certain kind of messages? (e.g. chat)

In order to join a group, you currently do:

    C->S: join(groupname)
    S->C: joined(groupname)
    S->C: chathistory, chathistory, chathistory
    C->S: request(audio, video)

There is no way to avoid receiving the chat history, and there's no way to
avoid receiving chat messages.  The proposed protocol is

    C->S: join(groupname)
    S->C: joined(groupname)
    C->S: request(audio, video, chat)
    S->C: chathistory, chathistory, chathistory

Unless you explicitly request chat, you're not going to get the burst of
chathistory messages, and you're not going to get any chat messages.

> Would it be a problem to just be able to use newly added group actions
> in the protocol without explicitly having to mention that it's part
> of an extension?

If you send a groupaction that the server doesn't know about, you'll
receive an error message.  It would be useful to be able to avoid exposing
a group action in the UI if the server doesn't support it, and that's what
the extension mechanism could be useful for.  Whether this will prove
necessary will depend on whether useful native clients surface.

Ideally, of course, we'd have a single protocol that is used across
multiple servers.  Unfortunately, the only standardised videoconferencing
protocols are SIP and Jingle, both of which are somewhat strange (streamed
XML, giggle).

-- Juliusz

[Galene] Re: Fw: Re: Versioning the Galene protocol

[Jeroen van Veen]

> > Why support multiple versions of the same protocol? Wouldn't that only
>
> > complicate things at the Galene side? I don't mind personally to stick
> > to a version of the protocol, that was made to work with that particular
> > version of Galene.
>
> If the server cannot support multiple versions, then every change to the
> protocol breaks all non-web clients. (There's Galene-stream already, and
> I'd really like to see a native client for Android that can do screenshare.)

The web-version and protocol.js are always in-sync with the current version of Galene(same repo),
Galene-stream has its own protocol.py (https://github.com/erdnaxe/galene-stream/blob/main/galene_stream/galene.py),
and Pyrite uses a slightly modified protocol.js from the Galene repo. It seems useful to be able to keep the protocol
implementations in all used languages in sync, by making use of the included package managers (pip/npm/...)
for the versioning. A new version of Galene with an updated protocol would then mean updating the protocol implementations
in all languages and require the third-parties to update their dependencies. For instance:
https://github.com/matrix-org/matrix-rust-sdk
https://github.com/matrix-org/matrix-js-sdk

> Ideally, of course, we'd have a single protocol that is used across
> multiple servers. Unfortunately, the only standardised videoconferencing
> protocols are SIP and Jingle, both of which are somewhat strange (streamed
> XML, giggle).

I tried building a SIP conferencing client (https://github.com/garage44/ca11) with Asterisk SFU some years ago.
Asterisk itself is quite amazing, but I found SIP (over websockets) personally too complex to deal with signalling.
It may be nice to call in a conference with a Cisco phone, but who cares when everyone is using a softphone anyway.
A common signalling protocol for SFU's may be nice from a client perspective, and maybe even for interoperability
between SFU's. However, the more interoperability and standardization, the more it may start to look like SIP (or XMPP).