tomato/docs/minpgc.md

# Persistent conferences

This document describes the "minpgc" simple persistent conferences
implementation of PR #1069.

Many of the ideas derive from isotoxin's persistent conferences
implementation, PR #826.

## Specification of changes from pre-existing conference specification
We add one new packet type:

Rejoin Conference packet

| Length | Contents                        |
|:-------|:--------------------------------|
| `1`    | `uint8_t` (0x64)                |
| `33`   | Group chat identifier           |


A peer times out from a group if it has been inactive for 60s. When a peer
times out, we flag it as _frozen_. Frozen peers are disregarded for all
purposes except those discussed below - in particular no packets are sent to
them except as described below, they are omitted from the peer lists sent to
the client or in a Peer Response packet, and they are not considered when
determining closest peers for establishing direct connections.

A peer is considered to be active if we receive a group message or Rejoin
packet from it, or a New Peer message for it.

If a frozen peer is seen to be active, we remove its 'frozen' flag and send a
Name group message. (We can hold off on sending this message until the next
`tox_iterate`, and only send one message if many frozen peers become active at
once).

If we receive a New Peer message for a peer, we update its DHT pubkey.

If we receive a group message originating from an unknown peer, we drop the
message but send a Peer Query packet back to the peer who directly sent us the
message. (This is current behaviour; it's mentioned here because it's important
and not currently mentioned in the spec.)

If we receive a Rejoin packet from a peer we update its DHT pubkey, add a
temporary groupchat connection for the peer, and, once the connection is
online, send out a New Peer message announcing the peer, and a Name message.

Whenever we make a new friend connection, we check if the public key is that 
of any frozen peer. If so, we send it a Rejoin packet, add a temporary
groupchat connection for it, and, once the connection is online, send the
peer a Peer Query packet.

We do the same with a peer when we are setting it as frozen if we have a
friend connection to it.

The temporary groupchat connections established in sending and handling Rejoin
packets are not immediately operational (because group numbers are not known);
rather, an Online packet is sent when we handle a Rejoin packet.

When a connection is set as online as a result of an Online packet, we ping
the group.

When processing the reply to a Peer Query, we update the DHT pubkey of an
existing peer if and only if it is frozen or has not had its DHT pubkey
updated since it last stopped being frozen.

When we receive a Title Response packet, we set the title if it has never been
set or if at some point since it was last set, there were no unfrozen peers
(except us).

## Discussion
### Overview
The intention is to recover seamlessly from splits in the group, the most 
common form of which is a single peer temporarily losing all connectivity.

To see how this works, first note that groups (even before the changes
discussed here) have the property that for a group to be connected in the
sense that any peer will receive the messages of any other peer and have them
in their peerlist, it is necessary and sufficient that there is a path of
direct group connections between any two peers.

Now suppose the group is split into two connected components, with each member
of one component frozen according to the members of the other. Suppose there
are two peers, one in each component, which are using the above protocol, and
suppose they establish a friend connection. Then each will rejoin the other,
forming a direct group connection. Hence the whole group will become connected
(even if all other peers are using the unmodified protocol).

The Peer Query packet sent on rejoining hastens this process.

Peers who leave the group during a split will not be deleted by all peers
after the merge - but they will be set as frozen due to ping timeouts, which
is sufficient.

### Titles
If we have a split into components each containing multiple peers, and the
title is changed in one component, then peers will continue to disagree on the
title after the split. Short of a complicated voting system, this seems the
only reasonable behaviour.

### Implementation notes
Although I've described the logic in terms of an 'frozen' flag, it might 
actually make more sense in the implementation to have a separate list for 
frozen peers.

## Saving
Saving is implemented by simply saving all live groups with their group numbers
and full peer info for all peers. On reload, all peers are set as frozen.

Clients needs to support this by understanding that groups may exist on
start-up. Clients should call `tox_conference_get_chatlist` to obtain them. A
group which is deleted (with `tox_conference_delete`) is removed permanently
and will not be saved.

## Limitations
If a peer disconnects from the group for a period short enough that group
timeouts do not occur, and a name change occurs during this period, then the
name change will never be propagated.

One way to deal with this would be a general mechanism for storing and
requesting missed group messages. But this is considered out of scope of this
PR.

If a peer changes its DHT pubkey, the change might not be properly propagated
under various circumstances - in particular, if connections do not go down
long enough for the peer to become frozen.

One way to deal with this would be to add a group message announcing the
sending peer's current DHT pubkey, and treat it analogously to the Name
message.