Устройства

В спецификации Matrix термин «устройство» имеет особое значение. Как пользователь, я могу иметь несколько устройств: настольный клиент, несколько веб-браузеров, устройство Android, iPhone и т. д. В целом, они относятся к реальному устройству в физическом мире, но у вас может быть несколько браузеров на физическом устройстве или несколько клиентских приложений Matrix на мобильном устройстве, каждое из которых будет представлять собой отдельное устройство.

Устройства используются в первую очередь для управления ключами, применяемыми для сквозного шифрования (каждое устройство получает свою собственную копию ключей дешифрования), но они также помогают пользователям управлять своим доступом — например, путем отзыва доступа к определенным устройствам.

Когда пользователь впервые использует клиент, он регистрируется как новое устройство. Срок службы устройств может зависеть от типа клиента. Веб-клиент, вероятно, потеряет все свое состояние при выходе из системы и будет создавать новое устройство каждый раз при входе в систему, чтобы гарантировать, что криптографические ключи не будут переданы новому пользователю. В мобильном клиенте повторное использование устройства может быть допустимым, если сессия входа в систему истекает, при условии, что пользователь остается тем же.

Устройства идентифицируются по уникальному идентификатору device_id, который является единственным в рамках возможностей конкретного пользователя.

Пользователь может присвоить устройству удобочитаемое отображаемое имя, чтобы упростить управление своими устройствами.

События

Графы событий

События, которыми обмениваются участники внутри комнаты, хранятся в ориентированном ациклическом графе (DAG), называемом «графом событий». Частичный порядок этого графа определяет хронологический порядок событий внутри комнаты. Каждое событие в графе имеет список из нуля или более «родительских» событий, которые относятся к любым предшествующим событиям, не имеющим хронологического преемника с точки зрения домашнего сервера, создавшего это событие.

Как правило, у события есть один родитель: самое последнее сообщение в комнате на момент его отправки. Однако домашние серверы могут законно конкурировать друг с другом при отправке сообщений, в результате чего у одного события может быть несколько преемников. Таким образом, следующее событие, добавленное в граф, будет иметь несколько родителей. Каждый граф событий имеет одно корневое событие без родителей.

Для упорядочивания и упрощения хронологического сравнения событий в графе домашние серверы поддерживают depthполе метаданных для каждого события. Значение метаданных события depth— это положительное целое число, строго большее глубины любого из его родительских событий. Корневое событие должно иметь глубину 1. Таким образом, если одно событие предшествует другому, то оно должно иметь строго меньшую глубину.

Структура помещения

Комната — это концептуальное пространство, где пользователи могут отправлять и получать события. События отправляются в комнату, и все участники этой комнаты, имеющие достаточный доступ, получат это событие. Комнаты внутри системы однозначно идентифицируются с помощью «идентификаторов комнат», которые имеют следующий вид:

!opaque_id:domain 

Для каждой комнаты существует ровно один идентификатор. Хотя идентификатор комнаты и содержит домен, он используется лишь для глобального присвоения имен идентификаторам комнат. Комната НЕ находится в указанном домене.

Следующая концептуальная схема показывает m.room.messageотправку события в комнату !qporfwt:matrix.org:

{ @alice:matrix.org } { @bob:example.org } | ^ | | [HTTP POST] [HTTP GET] Room ID: !qporfwt:matrix.org Room ID: !qporfwt:matrix.org Event type: m.room.message Event type: m.room.message Content: { JSON object } Content: { JSON object } | | V | +------------------+ +------------------+ | homeserver | | homeserver | | matrix.org | | example.org | +------------------+ +------------------+ | ^ | [HTTP PUT] | | Room ID: !qporfwt:matrix.org | | Event type: m.room.message | | Content: { JSON object } | `-------> Pointer to the preceding message ------` PKI signature from matrix.org Transaction-layer metadata PKI Authorization header  .................................... | Shared Data | | State: | | Room ID: !qporfwt:matrix.org | | Servers: matrix.org, example.org | | Members: | | - @alice:matrix.org | | - @bob:example.org | | Messages: | | - @alice:matrix.org | | Content: { JSON object } | |....................................| 

Федерация поддерживает общие структуры данных для каждой комнаты между несколькими домашними серверами. Данные разделены на message eventsи state events.

Сообщения о событиях: Они описывают кратковременные, разовые действия в помещении, такие как мгновенные сообщения, установление VoIP-соединения, передача файлов и т. д. В целом, они описывают коммуникационную активность.

События состояния: Они описывают обновления определенной постоянной информации («состояния»), связанной с комнатой, такой как название комнаты, тема, состав участников, участвующие серверы и т. д. Состояние моделируется как таблица поиска пар ключ/значение для каждой комнаты, где каждый ключ представляет собой кортеж из state_keyи event type. Каждое событие состояния обновляет значение заданного ключа.

Состояние комнаты в данный момент времени определяется путем рассмотрения всех событий, предшествующих данному событию и включающих его в граф. В случаях, когда события описывают одно и то же состояние, применяется алгоритм разрешения конфликтов слияния. Алгоритм разрешения состояний является транзитивным и не зависит от состояния сервера, поскольку он должен последовательно выбирать одно и то же событие независимо от сервера или порядка получения событий. События подписываются исходным сервером (подпись включает родительские связи, тип, глубину и хеш полезной нагрузки) и передаются по федерации участвующим серверам в комнате, в настоящее время с использованием топологии полной сетки. Серверы также могут запрашивать заполнение событий по федерации у других серверов, участвующих в комнате.

Псевдонимы комнат

Каждой комнате также может быть несколько «псевдонимов комнат», которые выглядят следующим образом:

#room_alias:domain 

Псевдоним комнаты «указывает» на идентификатор комнаты и представляет собой удобочитаемую метку, по которой комнаты публикуются и обнаруживаются. Идентификатор комнаты, на который указывает псевдоним, можно получить, посетив указанный домен. Обратите внимание, что сопоставление псевдонима комнаты с идентификатором комнаты не является фиксированным и может со временем изменяться, указывая на другой идентификатор комнаты. По этой причине клиентам СЛЕДУЕТ один раз преобразовать псевдоним комнаты в идентификатор комнаты, а затем использовать этот идентификатор в последующих запросах.

При разрешении псевдонима комнаты сервер также ответит списком серверов, находящихся в этой комнате, которые можно использовать для присоединения.

HTTP GET #matrix:example.org !aaabaa:matrix.org | ^ | | _______V____________________|____ | example.org | | Mappings: | | #matrix >> !aaabaa:matrix.org | | #golf >> !wfeiofh:sport.com | | #bike >> !4rguxf:matrix.org | |________________________________| 

Личность

Пользователи в Matrix идентифицируются по своему идентификатору пользователя Matrix. Однако для идентификации пользователей Matrix также могут использоваться существующие пространства имен сторонних идентификаторов. «Идентификатор» Matrix описывает как идентификатор пользователя, так и любые другие существующие идентификаторы из пространств имен сторонних организаций, связанные с его учетной записью. Пользователи Matrix могут связывать сторонние идентификаторы (3PID), такие как адреса электронной почты, учетные записи в социальных сетях и номера телефонов, со своим идентификатором пользователя. Связывание 3PID создает сопоставление между 3PID и идентификатором пользователя. Это сопоставление затем может использоваться пользователями Matrix для определения идентификаторов пользователей своих контактов. Для обеспечения подлинности сопоставления между 3PID и идентификатором пользователя используется глобальный федеративный кластер доверенных «серверов идентификации» (IS) для проверки 3PID, а также для сохранения и репликации сопоставлений.

Использование информационной системы (ИС) не является обязательным условием для того, чтобы клиентское приложение стало частью экосистемы Matrix. Однако без неё клиенты не смогут искать идентификаторы пользователей, используя сторонние идентификаторы (3PID).

Профили

Пользователи могут публиковать произвольные данные типа ключ/значение, связанные с их учетной записью.

• например, удобочитаемое имя пользователя, URL-адрес фотографии профиля, контактная информация (адрес электронной почты, номера телефонов, URL-адреса веб-сайтов и т. д.).

Личные данные пользователя

Пользователи также могут хранить в своей учетной записи произвольные закрытые данные типа ключ/значение — например, настройки клиента или параметры конфигурации сервера, для которых нет специального API. API симметричен управлению данными профиля.

Общие понятия

Во всех API-интерфейсах Matrix есть ряд общих черт. Они описаны здесь.

пространства имен

Использование пространств имен помогает предотвратить конфликты между различными приложениями и самой спецификацией. В тех случаях, когда используются пространства имен, m.префиксы указывают на то, что поле контролируется спецификацией. Пользовательские или неуказанные пространства имен, используемые на практике, ДОЛЖНЫ использовать соглашение об именовании пакетов Java для предотвращения конфликтов.

Например, типы событий, определенные в спецификации, находятся в пространстве имен под специальным m.префиксом, однако любой клиент может отправить пользовательский тип события, например com.example.game.score(при условии, что у клиента есть права доступа к com.exampleпространству имен), без необходимости помещать событие в это m.пространство имен.

Временные метки

Если не указано иное, временные метки представляют собой количество миллисекунд, прошедших с начала эпохи Unix (1970-01-01 00:00:00 UTC), но без учета високосных секунд, так что каждые сутки составляют ровно 86 400 000 миллисекунд.

Это означает, что метки времени могут повторяться в течение високосных секунд. Большинство языков программирования предоставляют метки времени в этом формате изначально, например, ECMAScript . В спецификации это может обозначаться как POSIX, Unix или просто «время в миллисекундах».

Версии спецификаций

Вся матрица выпускается под единым номером спецификации в форме vX.Y.

• Изменение, приводящее к Xсущественным или критическим изменениям, отражает именно это изменение. Точное время увеличения этого числа оставлено на усмотрение основной команды разработчиков спецификации, однако оно предназначено для таких изменений, как отказ от JSON, изменение алгоритма подписи или когда большое количество Yизменений заслуживает повышения номера основной версии.
• Изменение Yпредставляет собой обратно совместимое или «управляемое» обратно совместимое изменение спецификации, обычно в виде новых функций.

Кроме того, к версии спецификации могут быть применены произвольные метаданные, если за ней следует -. Например, v1.1-alpha. Использование этого не строго регламентировано, но предназначено для использования в предварительных сборках спецификации.

Обратите внимание, что хотя v1.2предполагается обратная совместимость с v1.1, нет гарантии, что будущие версии будут полностью обратно совместимы с v1.1. Например, если /testбудет введен в v1.1и объявлен устаревшим в v1.2, то его можно будет удалить в v1.3. Более подробная информация об этом описана в политике устаревания ниже.

Версионирование конечных точек

Все API-интерфейсы в спецификации имеют индивидуальные версии. Это означает, что /v3/sync(например) может быть объявлен устаревшим в пользу другого /v4/syncбез каких-либо последствий /v3/profile. Сервер, поддерживающий эту функцию, /v4/syncпродолжит обслуживать сервер /v3/profileтак же, как и раньше.

Когда MSC предлагает внести критические изменения в конечную точку, он также должен объявить существующую конечную точку устаревшей. Для некоторых конечных точек это может быть неявным, например, /v4/syncпутем введения (объявления устаревшей /v3/sync), однако для более сложных примеров MSC должен явно объявить конечную точку устаревшей.

Политика амортизации

Для перехода от стабильного (по умолчанию) состояния к устаревшему требуется MSC. После того, как состояние устаревает достаточно долго (обычно 1 версия), его можно удалить из спецификации с помощью другого MSC.

Реализации Matrix обязаны реализовывать устаревшую функциональность спецификации, хотя, если эта функциональность впоследствии будет удалена, реализация может отказаться от её поддержки (если она не рекламирует поддержку версии, включающей устаревшую функциональность). Например, если /test была объявлена ​​устаревшей в v1.2 и удалена в v1.3, то реализация, которая хочет рекламировать поддержку , v1.2 должна будет реализовать /test, даже если она также рекламирует поддержку v1.3. Если эта реализация рекламирует только поддержку , v1.3 то ей не потребуется реализовывать /test.

Устаревшее версионирование

До внедрения этой системы различные API-интерфейсы Matrix версионировались индивидуально. С новым подходом к версионированию спецификаций это больше невозможно.

Для исторической справки, версии API были обозначены примерно так: rX.Y.Z где X обозначает критическое изменение,  Y обратно совместимое изменение, а Z— исправление или незначительное изменение API.

Текущая глобальная система версионирования была введена в v1.1. Matrix 1.0 не соответствовала напрямую версии спецификации; вместо этого она основывалась на следующих версиях для отдельных API:

v1.0 Серверы не должны возвращать этот параметр в GET /_matrix/client/versions ответе.

Лицензия

Спецификация Matrix распространяется под лицензией Apache License, Version 2.0 .