From cbe466e5729a06ae4b036714ae7d1c555579768c Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 23 Feb 2016 09:00:55 +0000 Subject: [PATCH 1/6] Update API docs --- api/client-server/presence.yaml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/api/client-server/presence.yaml b/api/client-server/presence.yaml index d9a1b866..fc47029c 100644 --- a/api/client-server/presence.yaml +++ b/api/client-server/presence.yaml @@ -49,11 +49,14 @@ paths: properties: presence: type: string - enum: ["online", "offline", "unavailable", "free_for_chat"] + enum: ["online", "offline", "unavailable"] description: The new presence state. status_msg: type: string description: "The status message to attach to this state." + currently_online: + type: boolean + description: "Whether the user is currently active" required: ["presence"] responses: 200: @@ -94,7 +97,7 @@ paths: properties: presence: type: string - enum: ["online", "offline", "unavailable", "free_for_chat"] + enum: ["online", "offline", "unavailable"] description: This user's presence. last_active_ago: type: integer @@ -185,8 +188,6 @@ paths: [ { "content": { - "avatar_url": "mxc://matrix.org/AfwefuigfWEfhuiPP", - "displayname": "Alice Margatroid", "last_active_ago": 395, "presence": "offline", "user_id": "@alice:matrix.org" @@ -195,11 +196,10 @@ paths: }, { "content": { - "avatar_url": "mxc://matrix.org/FWEhuiwegfWEfhuiwf", - "displayname": "Marisa Kirisame", "last_active_ago": 16874, "presence": "online", - "user_id": "@marisa:matrix.org" + "user_id": "@marisa:matrix.org", + "currently_active": true }, "type": "m.presence" } From f1a8306d080fe319703b13c77f4ce114ba5458f7 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 23 Feb 2016 11:13:02 +0000 Subject: [PATCH 2/6] Spec currently_active time and idle timeout behaviour --- specification/modules/presence.rst | 79 ++++++++++-------------------- 1 file changed, 27 insertions(+), 52 deletions(-) diff --git a/specification/modules/presence.rst b/specification/modules/presence.rst index 4eddaeee..7459ca7c 100644 --- a/specification/modules/presence.rst +++ b/specification/modules/presence.rst @@ -20,7 +20,7 @@ membership of a room. A presence list is a list of user IDs whose presence the user wants to follow. To be added to this list, the user being added must be invited by the list owner who must accept the invitation. - + User's presence state is represented by the ``presence`` key, which is an enum of one of the following: @@ -30,8 +30,6 @@ of one of the following: idle. - ``offline`` : The user is not connected to an event stream or is explicitly suppressing their profile information from being sent. -- ``free_for_chat`` : The user is generally willing to receive messages - moreso than default. Events ------ @@ -46,67 +44,44 @@ listed below. {{presence_http_api}} -Idle timeout -~~~~~~~~~~~~ - -Clients SHOULD implement an "idle timeout". This is a timer which fires after -a period of inactivity on the client. The definition of inactivity varies -depending on the client. For example, web implementations may determine -inactivity to be not moving the mouse for a certain period of time. When this -timer fires it should set the presence state to ``unavailable``. When the user -becomes active again (e.g. by moving the mouse) the client should set the -presence state to ``online``. A timeout value between 1 and 5 minutes is -recommended. - Server behaviour ---------------- Each user's homeserver stores a "presence list" per user. Once a user accepts a presence list, both user's HSes must track the subscription. -Propagating profile information -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Because the profile display name and avatar information are likely to be used in -many places of a client's display, changes to these fields SHOULD cause an -automatic propagation event to occur, informing likely-interested parties of the -new values. One of these change mechanisms SHOULD be via ``m.presence`` events. -These events should set ``displayname`` and ``avatar_url`` to the new values -along with the presence-specific keys. This SHOULD be done automatically by the -homeserver when a user successfully changes their display name or avatar URL. - -.. admonition:: Rationale - - The intention for sending this information in ``m.presence`` is so that any - "user list" can display the *current* name/presence for a user ID outside the - scope of a room e.g. for a user page. This is bundled into a single event for - several reasons. The user's display name can change per room. This - event provides the "canonical" name for the user. In addition, the name is - bundled into a single event for the ease of client implementations. If this - was not done, the client would need to search all rooms for their own - membership event to pull out the display name. - - Last active ago ~~~~~~~~~~~~~~~ -The server maintains a timestamp of the last time it saw a -pro-active event from the user. A pro-active event may be sending a message to a -room or changing presence state to a higher level of availability. Levels of -availability are defined from low to high as follows: +The server maintains a timestamp of the last time it saw a pro-active event from +the user. A pro-active event may be sending a message to a room or changing +presence state to ``online``. This timestamp is presented via a key called +``last_active_ago`` which gives the relative number of milliseconds since the +pro-active event. + +To reduce the number of presence updates sent to clients the server may include +a ``currently_active`` boolean field when the presence state is ``online``. When +true, the server will not send further updates to the last active time until an +update is sent to the client with either a) ``currently_active`` set to false or +b) a presence state other than ``online``. During this period clients must +consider the user to be currently active, irrespective of the last active time. + +The last active time must be up to date whenever the server gives a presence +event to the client; the ``currently_active`` mechanism should purely be used to +disable as opposed to disabling last active tracking. Thus clients can fetch up +to date last active times by explicitly requesting the presence for a given +user. -- ``offline`` -- ``unavailable`` -- ``online`` -- ``free_for_chat`` +Idle timeout +~~~~~~~~~~~~ -Based on this list, changing state from ``unavailable`` to ``online`` counts as -a pro-active event, whereas ``online`` to ``unavailable`` does not. This -timestamp is presented via a key called ``last_active_ago`` which gives the -relative number of milliseconds since the pro-active event. +The server will automatically set a users presence to ``unavailable`` if their +last active time was over 5 minutes ago. Clients can manually set a users +presence to ``unavailable``. Any activity that bumps the last active time on any +of the user's clients will cause the server to automatically set their presence +to ``online``. Security considerations ----------------------- - + Presence information is shared with all users who share a room with the target user. In large public rooms this could be undesirable. - From bc68177471066ed0797c612fc026fcfeb8647791 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 1 Mar 2016 16:07:25 +0000 Subject: [PATCH 3/6] Grammar --- specification/modules/presence.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/modules/presence.rst b/specification/modules/presence.rst index 7459ca7c..19fe13ba 100644 --- a/specification/modules/presence.rst +++ b/specification/modules/presence.rst @@ -74,8 +74,8 @@ user. Idle timeout ~~~~~~~~~~~~ -The server will automatically set a users presence to ``unavailable`` if their -last active time was over 5 minutes ago. Clients can manually set a users +The server will automatically set a user's presence to ``unavailable`` if their +last active time was over 5 minutes ago. Clients can manually set a user's presence to ``unavailable``. Any activity that bumps the last active time on any of the user's clients will cause the server to automatically set their presence to ``online``. From 167a08a80516f193800838988440664de3adb6b4 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 1 Mar 2016 16:13:41 +0000 Subject: [PATCH 4/6] Allow idle timeout to be configurable --- specification/modules/presence.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/modules/presence.rst b/specification/modules/presence.rst index 19fe13ba..de327e3c 100644 --- a/specification/modules/presence.rst +++ b/specification/modules/presence.rst @@ -75,10 +75,10 @@ Idle timeout ~~~~~~~~~~~~ The server will automatically set a user's presence to ``unavailable`` if their -last active time was over 5 minutes ago. Clients can manually set a user's -presence to ``unavailable``. Any activity that bumps the last active time on any -of the user's clients will cause the server to automatically set their presence -to ``online``. +last active time was over a threshold value (e.g. 5 minutes). Clients can +manually set a user's presence to ``unavailable``. Any activity that bumps the +last active time on any of the user's clients will cause the server to +automatically set their presence to ``online``. Security considerations ----------------------- From 3d4d91a462c8d211caf857d3b9ce3d2421871e81 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 1 Mar 2016 16:15:59 +0000 Subject: [PATCH 5/6] Reword to make sense --- specification/modules/presence.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/modules/presence.rst b/specification/modules/presence.rst index de327e3c..52e59970 100644 --- a/specification/modules/presence.rst +++ b/specification/modules/presence.rst @@ -66,10 +66,10 @@ b) a presence state other than ``online``. During this period clients must consider the user to be currently active, irrespective of the last active time. The last active time must be up to date whenever the server gives a presence -event to the client; the ``currently_active`` mechanism should purely be used to -disable as opposed to disabling last active tracking. Thus clients can fetch up -to date last active times by explicitly requesting the presence for a given -user. +event to the client. The ``currently_active`` mechanism should purely be used by +servers to stop sending continuous presence updates, as opposed to disabling +last active tracking entirely. Thus clients can fetch up to date last active +times by explicitly requesting the presence for a given user. Idle timeout ~~~~~~~~~~~~ From 2691d4925bf9f0ce90185bee66c064ddae68430d Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Wed, 22 Jun 2016 14:07:24 +0100 Subject: [PATCH 6/6] s/currently_online/currently_active/ --- api/client-server/presence.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/presence.yaml b/api/client-server/presence.yaml index fc47029c..4f637698 100644 --- a/api/client-server/presence.yaml +++ b/api/client-server/presence.yaml @@ -54,7 +54,7 @@ paths: status_msg: type: string description: "The status message to attach to this state." - currently_online: + currently_active: type: boolean description: "Whether the user is currently active" required: ["presence"]