diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/client-server/model/presence.rst | 149 |
1 files changed, 0 insertions, 149 deletions
diff --git a/docs/client-server/model/presence.rst b/docs/client-server/model/presence.rst deleted file mode 100644 index 811bac3fab..0000000000 --- a/docs/client-server/model/presence.rst +++ /dev/null @@ -1,149 +0,0 @@ -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.]] |