From 928fc5cbe5e5cfa3992ccb275d93751706fb1723 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 1 Sep 2018 03:08:53 +0100 Subject: [PATCH] incorporate review --- .../definitions/event-schemas/m.device_list_update.yaml | 9 ++++----- specification/server_server_api.rst | 6 +++--- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/api/server-server/definitions/event-schemas/m.device_list_update.yaml b/api/server-server/definitions/event-schemas/m.device_list_update.yaml index 0e7f0d32..49b49c3b 100644 --- a/api/server-server/definitions/event-schemas/m.device_list_update.yaml +++ b/api/server-server/definitions/event-schemas/m.device_list_update.yaml @@ -30,7 +30,7 @@ allOf: edu_type: type: enum enum: ['m.device_list_update'] - description: The string ``m.device_list_update`` + description: The string ``m.device_list_update``. example: "m.device_list_update" content: type: object @@ -55,7 +55,7 @@ allOf: type: integer description: |- An ID sent by the server for this update, unique for a given - user_id. Used to identify any gaps in the sequence of m.device_list_update + user_id. Used to identify any gaps in the sequence of ``m.device_list_update`` EDUs broadcast by a server. example: 6 prev_id: @@ -65,7 +65,7 @@ allOf: which have not been referred to already in an EDU's prev_id field. If the receiving server does not recognise any of the prev_ids, it means an EDU has been lost and the server should query a snapshot of the devicelist - via /user/keys/query in order to correctly interpret future m.device_list_update + via ``/user/keys/query`` in order to correctly interpret future ``m.device_list_update`` EDUs. May be missing or empty for the first EDU in a sequence. items: type: integer @@ -82,8 +82,7 @@ allOf: description: |- The updated identity keys (if any) for this device. May be absent if the device has no E2E keys defined. - allOf: - - $ref: ../../../client-server/definitions/device_keys.yaml + $ref: ../../../client-server/definitions/device_keys.yaml required: - user_id - device_id diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 45ac1c9f..ef5903ff 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -1008,14 +1008,14 @@ of the Client-Server API. Matrix currently uses a custom pubsub system for synchronising information about the list of devices for a given user over federation. When a server wishes to determine a remote user's device list for the first time, -it should populate its local cache by calling the /user/keys/query API +it should populate its local cache by calling the ``/user/keys/query`` API on the remote server. However, subsequent updates to the cache should be applied by consuming ``m.device_list_update`` EDUs, which must be sent by the remote server whenever a user's device list changes. Servers send ``m.device_list_update`` EDUs in a sequence per source user, each with a unique ``stream_id``. They also include a pointer to the most recent previous EDU(s) -that this update is relative to in the `pprev_id`` field. To simplify implementation +that this update is relative to in the ``prev_id`` field. To simplify implementation for clustered servers which could send multiple EDUs at the same time, the ``prev_id`` field should include all ``m.device_list_update`` EDUs which have not been yet been referenced in a EDU. If EDUs are emitted in series by a server, there should only ever @@ -1025,7 +1025,7 @@ This forms a simple directed acyclic graph of ``m.device_list_update`` EDUs, sho which EDUs a server needs to have received in order to apply an update to its local copy of the remote user's device list. If a server receives an EDU which refers to a ``prev_id`` it does not recognise, it must resynchronise its list by calling the -/user/keys/query API and resume the process. The response contains a ``stream_id`` +``/user/keys/query API`` and resume the process. The response contains a ``stream_id`` which should be used to correlate with subsequent ``m.device_list_update`` EDUs. .. TODO: this whole thing desperately feels like it should just be state in a room,