Merge pull request #278 from matrix-org/erikj/presence
Update presence spec.
This commit is contained in:
Erik Johnston
GitHub
commit
e80e32173f
2 changed files with 34 additions and 59 deletions
|
|
@ -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"
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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_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
|
||||
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.
|
||||
|
||||
- ``offline``
|
||||
- ``unavailable``
|
||||
- ``online``
|
||||
- ``free_for_chat``
|
||||
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.
|
||||
|
||||
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 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.
|
||||
|
||||
Idle timeout
|
||||
~~~~~~~~~~~~
|
||||
|
||||
The server will automatically set a user's presence to ``unavailable`` if their
|
||||
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
|
||||
-----------------------
|
||||
|
||||
|
||||
Presence information is shared with all users who share a room with the target
|
||||
user. In large public rooms this could be undesirable.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue