Spec currently_active time and idle timeout behaviour

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_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.
-