Spec currently_active time and idle timeout behaviour

pull/278/head
Erik Johnston 9 years ago
parent cbe466e572
commit f1a8306d08

@ -30,8 +30,6 @@ of one of the following:
idle. idle.
- ``offline`` : The user is not connected to an event stream or is - ``offline`` : The user is not connected to an event stream or is
explicitly suppressing their profile information from being sent. explicitly suppressing their profile information from being sent.
- ``free_for_chat`` : The user is generally willing to receive messages
moreso than default.
Events Events
------ ------
@ -46,67 +44,44 @@ listed below.
{{presence_http_api}} {{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 Server behaviour
---------------- ----------------
Each user's homeserver stores a "presence list" per user. Once a user accepts 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. 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 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 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`` 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 users presence to ``unavailable`` if their
a pro-active event, whereas ``online`` to ``unavailable`` does not. This last active time was over 5 minutes ago. Clients can manually set a users
timestamp is presented via a key called ``last_active_ago`` which gives the presence to ``unavailable``. Any activity that bumps the last active time on any
relative number of milliseconds since the pro-active event. of the user's clients will cause the server to automatically set their presence
to ``online``.
Security considerations Security considerations
----------------------- -----------------------
Presence information is shared with all users who share a room with the target Presence information is shared with all users who share a room with the target
user. In large public rooms this could be undesirable. user. In large public rooms this could be undesirable.

Loading…
Cancel
Save