wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #1648 from matrix-org/matthew/device_list_update

Browse source 
document device list synchronisation over federation.
This commit is contained in:
Matthew Hodgson 2018-09-03 16:54:36 +01:00 • committed by GitHub
commit 6dab4b28f8
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 220 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

46
specification/server_server_api.rst
View file

@ -1122,6 +1122,52 @@ nothing else.
{{openid_ss_http_api}}
Device Management
-----------------
Details of a user's devices must be efficiently published to other users and kept
up-to-date. This is critical for reliable end-to-end encryption, in order for users
to know which devices are participating in a room. It's also required for to-device
messaging to work. This section is intended to complement the `Device Management module`_
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 a local cache from the result of a ``/user/keys/query`` API
on the remote server. However, subsequent updates to the cache should be applied
by consuming ``m.device_list_update`` EDUs. Each new ``m.device_list_update`` EDU
describes an incremental change to one device for a given user which should replace
any existing entry in the local server's cache of that device list. Servers must send
``m.device_list_update`` EDUs to all the servers who share a room with a given
local user, and must be sent whenever that user's device list changes (i.e. for new or
deleted devices, when that user joins a room which contains servers which are not
already receiving updates for that user's device list, or changes in device information
such as the device's human-readable name).
Servers send ``m.device_list_update`` EDUs in a sequence per origin 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 ``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
be one ``prev_id`` in the EDU.
This forms a simple directed acyclic graph of ``m.device_list_update`` EDUs, showing
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``
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,
rather than inventing a whole different DAG. The same room could be used for
profiles, presence lists, etc.
{{user_devices_ss_http_api}}
{{definition_ss_event_schemas_m_device_list_update}}
End-to-End Encryption
---------------------