Merge pull request #278 from matrix-org/erikj/presence

Update presence spec.

api/client-server/presence.yaml

@@ -45,11 +45,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_active:
+                type: boolean
+                description: "Whether the user is currently active"
             required: ["presence"]
       responses:
         200:
@@ -90,7 +93,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
@@ -181,8 +184,6 @@ paths:
               [
                 {
                   "content": {
-                    "avatar_url": "mxc://matrix.org/AfwefuigfWEfhuiPP",
-                    "displayname": "Alice Margatroid",
                     "last_active_ago": 395,
                     "presence": "offline",
                     "user_id": "@alice:matrix.org"
@@ -191,11 +192,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"
                 }

specification/modules/presence.rst

@@ -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_cs_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
+The server maintains a timestamp of the last time it saw a pro-active event from
-pro-active event from the user. A pro-active event may be sending a message to a
+the user. A pro-active event may be sending a message to a room or changing
-room or changing presence state to a higher level of availability. Levels of
+presence state to ``online``. This timestamp is presented via a key called
-availability are defined from low to high as follows:
+``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 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.
 
-- ``offline``
+Idle timeout
-- ``unavailable``
+~~~~~~~~~~~~
-- ``online``
-- ``free_for_chat``
 
-Based on this list, changing state from ``unavailable`` to ``online`` counts as
+The server will automatically set a user's presence to ``unavailable`` if their
-a pro-active event, whereas ``online`` to ``unavailable`` does not. This
+last active time was over a threshold value (e.g. 5 minutes). Clients can
-timestamp is presented via a key called ``last_active_ago`` which gives the
+manually set a user's presence to ``unavailable``. Any activity that bumps the
-relative number of milliseconds since the pro-active event.
+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.
-