Start converting the presence module. Add Rationale admonition.

scripts/nature.css

@@ -282,3 +282,9 @@ td[colspan]:not([colspan="1"]) {
 thead {
     background: #eeeeee;
 }
+
+div.admonition-rationale {
+    background-color: #efe;
+    border: 1px solid #ccc;
+}
+

specification/1-client_server_api.rst

@@ -1092,6 +1092,27 @@ Profiles
 
 {{profile_http_api}}
 
+Events on Change of 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 cause an automatic
+propagation event to occur, informing likely-interested parties of the new
+values. This change is conveyed using two separate mechanisms:
+
+ - a ``m.room.member`` event is sent to every room the user is a member of,
+   to update the ``displayname`` and ``avatar_url``.
+ - a ``m.presence`` presence status update is sent, again containing the new
+   values of the ``displayname`` and ``avatar_url`` keys, in addition to the
+   required ``presence`` key containing the current presence state of the user.
+
+Both of these should be done automatically by the home server when a user
+successfully changes their display name or avatar URL fields.
+
+Additionally, when home servers emit room membership events for their own
+users, they should include the display name and avatar URL fields in these
+events so that clients already have these details to hand, and do not have to
+perform extra round trips to query it.
+
 Security
 --------
 

specification/modules/presence.rst

@@ -1,63 +1,89 @@
 Presence
 ========
  
-Each user has the concept of presence information. This encodes the
+Each user has presence information associated with them. This encodes the
-"availability" of that user, suitable for display on other user's clients.
+"availability" of that user, suitable for display on other clients.
 This is transmitted as an ``m.presence`` event and is one of the few events
-which are sent *outside the context of a room*. The basic piece of presence
+which are sent *outside the context of a room*. Their presence state is
-information is represented by the ``presence`` key, which is an enum of one
+represented by the ``presence`` key, which is an enum of one of the following:
-of the following:
 
       - ``online`` : The default state when the user is connected to an event
         stream.
-      - ``unavailable`` : The user is not reachable at this time.
+      - ``unavailable`` : The user is not reachable at this time e.g. they are
-      - ``offline`` : The user is not connected to an event stream.
+        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.
-      - ``hidden`` : Behaves as offline, but allows the user to see the client
-        state anyway and generally interact with client features. (Not yet
-        implemented in synapse).
-
-In addition, the server maintains a timestamp of the last time it saw a
-pro-active event from the user; either sending a message to a room, or
-changing presence state from a lower to a higher level of availability
-(thus: changing state from ``unavailable`` to ``online`` counts as a
-proactive event, whereas in the other direction it will not). This timestamp
-is presented via a key called ``last_active_ago``, which gives the relative
-number of milliseconds since the message is generated/emitted that the user
-was last seen active.
 
 Events
 ------
 
 {{presence_events}}
 
-Presence HTTP API
+Client behaviour
------------------
+----------------
-.. TODO-spec
+
-  - Define how users receive presence invites, and how they accept/decline them
+Clients can manually set/get their presence using the HTTP APIs 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
+----------------
+
+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
+home server 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. a user page which has a "start conversation" button).
+  This is bundled into a single event to avoid "flickering" on this page which
+  can occur if you received presence first and then display name later (the
+  user's name would flicker from their user ID to 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:
 
-Events on Change of Profile Information
+      - ``offline``
----------------------------------------
+      - ``unavailable``
-Because the profile displayname and avatar information are likely to be used in
+      - ``online``
-many places of a client's display, changes to these fields cause an automatic
+      - ``free_for_chat``
-propagation event to occur, informing likely-interested parties of the new
-values. This change is conveyed using two separate mechanisms:
 
- - a ``m.room.member`` event is sent to every room the user is a member of,
+Based on this list, changing state from ``unavailable`` to ``online`` counts as
-   to update the ``displayname`` and ``avatar_url``.
+a pro-active event, whereas ``online`` to ``unavailable`` does not. This
- - a ``m.presence`` presence status update is sent, again containing the new values of the
+timestamp is presented via a key called ``last_active_ago`` which gives the
-   ``displayname`` and ``avatar_url`` keys, in addition to the required
+relative number of milliseconds since the pro-active event.
-   ``presence`` key containing the current presence state of the user.
 
-Both of these should be done automatically by the home server when a user
+Security considerations
-successfully changes their displayname or avatar URL fields.
+-----------------------
     
-Additionally, when home servers emit room membership events for their own
+Presence information is shared with all users who share a room with the target
-users, they should include the displayname and avatar URL fields in these
+user. In large public rooms this could be undesirable.
-events so that clients already have these details to hand, and do not have to
-perform extra roundtrips to query it.