synapse/docs/client-server/model/presence.rst

API Efficiency

A simple implementation of presence messaging has the ability to cause a large amount of Internet traffic relating to presence updates. In order to minimise the impact of such a feature, the following observations can be made:

• There is no point in a Home Server polling status for peers in a user's presence list if the user has no clients connected that care about it.
• It is highly likely that most presence subscriptions will be symmetric - a given user watching another is likely to in turn be watched by that user.
• It is likely that most subscription pairings will be between users who share at least one Room in common, and so their Home Servers are actively exchanging message PDUs or transactions relating to that Room.
• Presence update messages do not need realtime guarantees. It is acceptable to delay delivery of updates for some small amount of time (10 seconds to a minute).

The general model of presence information is that of a HS registering its interest in receiving presence status updates from other HSes, which then promise to send them when required. Rather than actively polling for the currentt state all the time, HSes can rely on their relative stability to only push updates when required.

A Home Server should not rely on the longterm validity of this presence information, however, as this would not cover such cases as a user's server crashing and thus failing to inform their peers that users it used to host are no longer available online. Therefore, each promise of future updates should carry with a timeout value (whether explicit in the message, or implicit as some defined default in the protocol), after which the receiving HS should consider the information potentially stale and request it again.

However, because of the likelyhood that two home servers are exchanging messages relating to chat traffic in a room common to both of them, the ongoing receipt of these messages can be taken by each server as an implicit notification that the sending server is still up and running, and therefore that no status changes have happened; because if they had the server would have sent them. A second, larger timeout should be applied to this implicit inference however, to protect against implementation bugs or other reasons that the presence state cache may become invalid; eventually the HS should re-enquire the current state of users and update them with its own.

The following workflows can therefore be used to handle presence updates:

1 When a user first appears online their HS sends a message to each other HS

containing at least one user to be watched; each message carrying both a notification of the sender's new online status, and a request to obtain and watch the target users' presence information. This message implicitly promises the sending HS will now push updates to the target HSes.

2 The target HSes then respond a single message each, containing the current

status of the requested user(s). These messages too implicitly promise the target HSes will themselves push updates to the sending HS.

As these messages arrive at the sending user's HS they can be pushed to the user's client(s), possibly batched again to ensure not too many small messages which add extra protocol overheads.

At this point, all the user's clients now have the current presence status information for this moment in time, and have promised to send each other updates in future.

3 The HS maintains two watchdog timers per peer HS it is exchanging presence

information with. The first timer should have a relatively small expiry (perhaps 1 minute), and the second timer should have a much longer time (perhaps 1 hour).

4 Any time any kind of message is received from a peer HS, the short-term

presence timer associated with it is reset.

5 Whenever either of these timers expires, an HS should push a status reminder

to the target HS whose timer has now expired, and request again from that server the status of the subscribed users.

6 On receipt of one of these presence status reminders, an HS can reset both

of its presence watchdog timers.

To avoid bursts of traffic, implementations should attempt to stagger the expiry of the longer-term watchdog timers for different peer HSes.

When individual users actively change their status (either by explicit requests from clients, or inferred changes due to idle timers or client timeouts), the HS should batch up any status changes for some reasonable amount of time (10 seconds to a minute). This allows for reduced protocol overheads in the case of multiple messages needing to be sent to the same peer HS; as is the likely scenario in many cases, such as a given human user having multiple user accounts.

API Requirements

The data model presented here puts the following requirements on the APIs:

Client-Server

Requests that a client can make to its Home Server

• get/set current presence state Basic enumeration + ability to set a custom piece of text
• report per-device idle time After some (configurable?) idle time the device should send a single message to set the idle duration. The HS can then infer a "start of idle" instant and use that to keep the device idleness up to date. At some later point the device can cancel this idleness.
• report per-device type Inform the server that this device is a "mobile" device, or perhaps some other to-be-defined category of reduced capability that could be presented to other users.
• start/stop presence polling for my presence list It is likely that these messages could be implicitly inferred by other messages, though having explicit control is always useful.
• get my presence list [implicit poll start?] It is possible that the HS doesn't yet have current presence information when the client requests this. There should be a "don't know" type too.
• add/remove a user to my presence list

Server-Server

Requests that Home Servers make to others

• request permission to add a user to presence list
• allow/deny a request to add to a presence list
• perform a combined presence state push and subscription request For each sending user ID, the message contains their new status. For each receiving user ID, the message should contain an indication on whether the sending server is also interested in receiving status from that user; either as an immediate update response now, or as a promise to send future updates.

Server to Client

[[TODO(paul): There also needs to be some way for a user's HS to push status updates of the presence list to clients, but the general server-client event model currently lacks a space to do that.]]