Document how presence EDUs work between servers

It's worth noting that Synapse does not make use of the `poll` or `unpoll` fields, and therefore the wording has been updated to permit servers to reject users. In the case of synapse, it would automatically reject everyone in the list by nature of ignoring it.

api/server-server/definitions/event-schemas/m.presence.accept.yaml

@@ -0,0 +1,45 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: Presence Invite Accept EDU
+description: |-
+  An EDU representing approval for the observing user to subscribe to the
+  presence of the the observed user.
+allOf:
+  - $ref: ../edu.yaml
+  - type: object
+    properties:
+      edu_type:
+        type: string
+        description: The string ``m.presence_accept``
+        example: "m.presence_accept"
+      content:
+        type: object
+        description: The invite information.
+        title: Invite Information
+        properties:
+          observed_user:
+            type: string
+            description: |-
+              The user ID that has approved the ``observer_user`` to
+              subscribe to their presence.
+            example: "@alice:elsewhere.com"
+          observer_user:
+            type: string
+            description: |-
+              The user ID that requested to subscribe to the presence of
+              the ``observed_user``.
+            example: "@john:matrix.org"
+        required: ['observer_user', 'observed_user']

api/server-server/definitions/event-schemas/m.presence.deny.yaml

@@ -0,0 +1,54 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: Presence Invite Deny EDU
+description: |-
+  An EDU representing a declination or revocation for the observing user
+  to subscribe to the presence of the observed user.
+example: {
+  "origin": "domain.com",
+  "destination": "elsewhere.org",
+  "edu_type": "m.presence_deny",
+  "content": {
+    "observed_user": "@alice:elsewhere.org",
+    "observer_user": "@john:domain.com"
+  }
+}
+allOf:
+  - $ref: ../edu.yaml
+  - type: object
+    properties:
+      edu_type:
+        type: string
+        description: The string ``m.presence_deny``
+        example: "m.presence_deny"
+      content:
+        type: object
+        description: The invite information.
+        title: Invite Information
+        properties:
+          observed_user:
+            type: string
+            description: |-
+              The user ID that has declined or revoked the ``observer_user`` from
+              subscribing to their presence.
+            example: "@alice:elsewhere.com"
+          observer_user:
+            type: string
+            description: |-
+              The user ID that requested to subscribe to the presence of
+              the ``observed_user``.
+            example: "@john:matrix.org"
+        required: ['observer_user', 'observed_user']

api/server-server/definitions/event-schemas/m.presence.invite.yaml

@@ -0,0 +1,44 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: Presence Invite EDU
+description: |-
+  An EDU representing a request to subscribe to a user's presence.
+allOf:
+  - $ref: ../edu.yaml
+  - type: object
+    properties:
+      edu_type:
+        type: string
+        description: The string ``m.presence_invite``
+        example: "m.presence_invite"
+      content:
+        type: object
+        description: The invite information.
+        title: Invite Information
+        properties:
+          observed_user:
+            type: string
+            description: |-
+              The user ID the ``observer_user`` would like to subscribe
+              to the presence of.
+            example: "@alice:elsewhere.com"
+          observer_user:
+            type: string
+            description: |-
+              The user ID that is wishing to subscribe to the presence of
+              the ``observed_user``.
+            example: "@john:matrix.org"
+        required: ['observer_user', 'observed_user']

api/server-server/definitions/event-schemas/m.presence.yaml

@@ -0,0 +1,97 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: Presence EDU
+description: |-
+  An EDU representing presence updates for users of the sending homeserver.
+  Can also be used to request additional presence updates for users of the
+  receiving homeserver.
+allOf:
+  - $ref: ../edu.yaml
+  - type: object
+    properties:
+      edu_type:
+        type: string
+        description: The string ``m.presence``
+        example: "m.presence"
+      content:
+        type: object
+        description: The presence updates and requests.
+        title: Presence Update
+        properties:
+          push:
+            type: array
+            description: |-
+              A list of presence updates that the receiving server is likely
+              to be interested in, or is subscribed to.
+            items:
+              type: object
+              title: User Presence Update
+              properties:
+                user_id:
+                  type: string
+                  description: The user ID this presence EDU is for.
+                  example: "@john:matrix.org"
+                presence:
+                  type: enum
+                  enum: ['offline', 'unavailable', 'online']
+                  description: The presence of the user.
+                  example: "online"
+                status_msg:
+                  type: string
+                  description: An optional description to accompany the presence.
+                  example: "Making cupcakes"
+                last_active_ago:
+                  type: integer
+                  format: int64
+                  description: |-
+                    The number of milliseconds that have ellapsed since the user
+                    last did something.
+                  example: 5000
+                currently_active:
+                  type: boolean
+                  description: |-
+                    Whether or not the user is currently using a device of theirs.
+                    Defaults to false.
+                  example: true
+              required: ['user_id', 'presence', 'last_active_ago']
+          poll:
+            type: array
+            description: |-
+              New user IDs that the sending server would like to subscribe to the
+              presence of. The sending server should not include users it has already
+              requested to be subscribed to.
+
+              The receiving server should ensure the sending server has reasonable
+              interest in subscribing to the provided users. The receiver may ignore 
+              a request to subscribe to a user the sender does not have reasonable
+              interest in. Reasonable interest may be residing in a room with the user,
+              being subscribed to a presence list, or some other requirement.
+
+              If non-empty, the receiving server should immediately send the presence
+              updates to the sender for the users requested.
+            items:
+              type: string
+            example: ["@alice:elsewhere.org"]
+          unpoll:
+            type: array
+            description: |-
+              New user IDs the sending server is no longer interested in receiving
+              presence updates for. The sending server should not include users it
+              has previously requested to be unsubscribed from.
+            items:
+              type: string
+            example: ["@bob:elsewhere.org"]
+        required: ['push']

scripts/templating/matrix_templates/units.py

@@ -49,6 +49,7 @@ SWAGGER_DEFINITIONS = {
     os.path.join(matrix_doc_dir, "api/identity/definitions"): "is",
     os.path.join(matrix_doc_dir, "api/push-gateway/definitions"): "push",
     os.path.join(matrix_doc_dir, "api/server-server/definitions"): "ss",
+    os.path.join(matrix_doc_dir, "api/server-server/definitions/presence"): "ss_presence",
 }
 EVENT_EXAMPLES = os.path.join(matrix_doc_dir, "event-schemas/examples")
 EVENT_SCHEMA = os.path.join(matrix_doc_dir, "event-schemas/schema")

specification/server_server_api.rst

@@ -838,57 +838,16 @@ Presence
 The server API for presence is based entirely on exchange of the following
 EDUs. There are no PDUs or Federation Queries involved.
 
-Performing a presence update and poll subscription request::
+Servers should only send presence updates for users that the receiving server
+would be interested in. This can include the receiving server sharing a room
+with a given user, or a user on the receiving server has added one of the 
+sending server's users to their presence list. 
 
-  EDU type: m.presence
-
-  Content keys:
-    push: (optional): list of push operations.
-      Each should be an object with the following keys:
-        user_id: string containing a User ID
-        presence: "offline"|"unavailable"|"online"|"free_for_chat"
-        status_msg: (optional) string of free-form text
-        last_active_ago: milliseconds since the last activity by the user
-
-    poll: (optional): list of strings giving User IDs
-
-    unpoll: (optional): list of strings giving User IDs
-
-The presence of this combined message is two-fold: it informs the recipient
-server of the current status of one or more users on the sending server (by the
-``push`` key), and it maintains the list of users on the recipient server that
-the sending server is interested in receiving updates for, by adding (by the
-``poll`` key) or removing them (by the ``unpoll`` key). The ``poll`` and
-``unpoll`` lists apply *changes* to the implied list of users; any existing IDs
-that the server sent as ``poll`` operations in a previous message are not
-removed until explicitly requested by a later ``unpoll``.
-
-On receipt of a message containing a non-empty ``poll`` list, the receiving
-server should immediately send the sending server a presence update EDU of its
-own, containing in a ``push`` list the current state of every user that was in
-the original EDU's ``poll`` list.
-
-Sending a presence invite::
-
-  EDU type: m.presence_invite
-
-  Content keys:
-    observed_user: string giving the User ID of the user whose presence is
-      requested (i.e. the recipient of the invite)
-    observer_user: string giving the User ID of the user who is requesting to
-      observe the presence (i.e. the sender of the invite)
-
-Accepting a presence invite::
-
-  EDU type: m.presence_accept
-
-  Content keys - as for m.presence_invite
-
-Rejecting a presence invite::
-
-  EDU type: m.presence_deny
-
-  Content keys - as for m.presence_invite
+Servers may also request additional users by including them in the ``poll``
+array on an ``m.presence`` update. The receiving server may ignore users
+requested in this array. The receiving server should maintain a list of
+subscribed users for the sending server, which is appended to by the ``poll``
+array and deleted from by the ``unpoll`` array.
 
 .. TODO-doc
   - Explain the timing-based round-trip reduction mechanism for presence
@@ -896,6 +855,14 @@ Rejecting a presence invite::
   - Explain the zero-byte presence inference logic
   See also: docs/client-server/model/presence
 
+{{definition_ss_event_schemas_m_presence}}
+
+{{definition_ss_event_schemas_m_presence_invite}}
+
+{{definition_ss_event_schemas_m_presence_accept}} 
+
+{{definition_ss_event_schemas_m_presence_accept}}
+
 Querying for information
 ------------------------