CC-BY-SA This work is licensed under a Creative Commons
Attribution-ShareAlike 4.0 International License

Source: gitlab.com/andybalaam

Matrix is a Distributed Real-time Database

Andy Balaam
element.io

Contents

What is Matrix?

A chat network

What is Matrix?

A group messaging network

What is Matrix?

An ecosystem

What is Matrix?

With bridges!

What is Matrix?

And bots!

What is Matrix?

An open network for secure, decentralized communication

What is Matrix?

An open network for secure, decentralized communication

What is Matrix?

An open network for secure, decentralized communication

What is Matrix?

An open network for secure, decentralized communication

What is Matrix?

An open network for secure, decentralized communication

Sending messages with curl

Run Synapse:

python -m synapse.app.homeserver \ --config-path homeserver.yaml

Sending messages with curl

Ask the server what version it is:

$ curl -s 'http://localhost:8008/_matrix/client/versions' { "versions": [ ..., "v1.2" ], "unstable_features": { ... } }

Sending messages with curl

Ask to register a new user:

$ curl -s '.../_matrix/client/r0/register' -d '{}' { "session": "sEdCvdBIiRxwqxULhKyBGNMx", "flows": [ { "stages": [ "m.login.dummy" ] } ], "params": {} }

Sending messages with curl

Register the user:

$ curl -s '.../_matrix/client/v1/register' -d '{ "auth": { "type": "m.login.dummy" }, "username": "curluser1", "password": "mypassword" }' { "user_id": "@curluser1:localhost", "home_server": "localhost", "access_token": "syt_Y3VybHVzZXIx_...", "device_id": "HHOGSCKLWW" }

Sending messages with curl

Find the types of login:

$ curl -s '.../_matrix/client/r0/login' { "flows": [ { "type": "m.login.password" }, { "type": "m.login.application_service" }, ... ] }

Sending messages with curl

Log in:

$ curl -s '.../matrix/client/v1/login' -d '{ "type":"m.login.password", "identifier": { "user": "@curluser1:localhost", "type": "m.id.user" }, "password":"mypassword" }' { "user_id": "@curluser1:localhost", "access_token": "syt_Y3VybHVzZXIx_...", "home_server": "localhost", "device_id": "HEUUQYFAMG", "well_known": { ... } }

Sending messages with curl

(Register another user:)

$ curl -s '.../_matrix/client/v1/register' -d '{ "auth": { "type": "m.login.dummy" }, "username": "curluser2", "password": "mypassword" }'

Sending messages with curl

Create a room:

$ curl -s '.../_matrix/client/r0/createRoom' -H 'Authorization: Bearer syt_Y3VybHVzZXIx_...' -d '{"invite":["@curluser2:localhost"]}' { "room_id": "!JRyYpMzvxJMAhVAPSv:localhost" }

Sending messages with curl

Sync: (initial sync)

$ curl -s '.../_matrix/client/r0/sync' -H 'Authorization: Bearer syt_Y3VybHVzZXIx_...' { "next_batch": "s41_4149_0_7_28_1_2_17_1", "account_data": { ... "presence": { ... "rooms": { "join": { "!JRyYpMzvxJMAhVAPSv:localhost": { "timeline": { "events": [ { "type": "m.room.create", ...

Sending messages with curl

Sync again:

$ curl -s '.../v1/sync?since=s41_4149_0_7_28_1_2_17_1' -H 'Authorization: Bearer syt_Y3VybHVzZXIx_...' { "next_batch": "s41_4159_0_7_28_1_2_17_1", "presence": { ...

Sending messages with curl

As user2, sync to find the invite:

$ curl -s '.../_matrix/client/v1/sync' -H 'Authorization: Bearer abc_Y3VybHVzZXIy_...' { "next_batch": "s41_4165_0_7_28_1_2_17_1", "account_data": { ... }, "presence": { ... }, "rooms": { "invite": { "!JRyYpMzvxJMAhVAPSv:localhost": { "invite_state": { "events": [ { "type": "m.room.create", ...

Sending messages with curl

"events": [ ... { "type": "m.room.member", "state_key": "@curluser1:localhost", "content": { "membership": "join", "displayname": "curluser1" }, "sender": "@curluser1:localhost" }, ...

Sending messages with curl

"events": [ ... { "type": "m.room.member", "state_key": "@curluser2:localhost", "content": { "membership": "invite", "displayname": "curluser2" }, "sender": "@curluser1:localhost", "event_id": "$rMb..." ... } ...

Sending messages with curl

As user2, check what rooms we are in:

$ curl -s '.../_matrix/client/r0/joined_rooms' -H 'Authorization: Bearer abc_Y3VybHVzZXIy_...' { "joined_rooms": [] }

Sending messages with curl

As user2, accept the invite:

$ curl -s '.../r0/rooms/!JRyYpMzvxJMAhVAPSv:localhost/join' -H 'Authorization: Bearer syt_Y3VybHVzZXIy_...' -d '{ "roomId": "!JRyYpMzvxJMAhVAPSv:localhost" }' { "room_id": "!JRyYpMzvxJMAhVAPSv:localhost" }

Sending messages with curl

As user2, check again:

$ curl -s '.../_matrix/client/r0/joined_rooms' -H 'Authorization: Bearer abc_Y3VybHVzZXIy_...' { "joined_rooms": [ "!JRyYpMzvxJMAhVAPSv:localhost" ] }

Sending messages with curl

As user2, sync again:

$ curl -s '.../_matrix/client/r0/sync?since=s41_4165_0_7_28_1_2_17_1' -H 'Authorization: Bearer abc_Y3VybHVzZXIy_...' { ... "rooms": { "join": { "!JRyYpMzvxJMAhVAPSv:localhost": { ... events here ... ...

Sending messages with curl

As user1, sync:

$ curl -s '.../_matrix/client/v1/sync?since=s41_4159_0_7_28_1_2_17_1' -H 'Authorization: Bearer syt_Y3VybHVzZXIx_...' { ... "events": [ { "type": "m.room.member", "sender": "@curluser2:localhost", ... }

Sending messages with curl

As user1, say something:

$ curl -s -X PUT '.../v1/rooms/!JRyYpMzvxJMAhVAPSv:localhost /send/m.room.message/mytransaction-A' -d '{ "body": "Hello from curl!", "msgtype": "m.text" }' -H 'Authorization: Bearer syt_Y3VybHVzZXIx_...' { "event_id": "$F_CZ9..." }

Sending messages with curl

As user2, sync:

$ curl -s '.../v1/sync?since=s42_4186_0_7_28_1_2_17_1' -H 'Authorization: Bearer abc_Y3VybHVzZXIy_...' ... "rooms": { "join": { "!JRyYpMzvxJMAhVAPSv:localhost": { "timeline": { "events": [ { "content": { "body": "Hello from curl!", "msgtype": "m.text" }, "sender": "@curluser1:localhost", "event_id": "$F_CZ9...", ...

Sending messages with curl

Syncing is a long poll ...

$ curl -s '.../v1/sync?timeout=1000000&since=s43_5796_0_7_28_1_2_17_1' -H 'Authorization: Bearer abc_Y3VybHVzZXIy_...' ...

Sending messages with curl

... that returns when something happens

$ curl -s '.../v1/sync?timeout=1000000&since=s43_5796_0_7_28_1_2_17_1' -H 'Authorization: Bearer abc_Y3VybHVzZXIy_...' ... "rooms": { "join": { "!JRyYpMzvxJMAhVAPSv:localhost": { "timeline": { "events": [ { "content": { "body": "It works!", "msgtype": "m.text" }, "sender": "@curluser1:localhost", "event_id": "$F_CZ9...", ...

Messages are events

"content" is what a client sends

{ "content": { "body": "hello", "msgtype": "m.text" }, "event_id": "$14606535757KCGXo:localhost", "origin_server_ts": 1460653575105, "sender": "@example:localhost", "type": "m.room.message", "unsigned": { "age": 800348 } }

Messages are events

The server assigns ID, sender etc.

{ "content": { "body": "hello", "msgtype": "m.text" }, "event_id": "$14606535757KCGXo:localhost", "origin_server_ts": 1460653575105, "sender": "@example:localhost", "type": "m.room.message", "unsigned": { "age": 800348 } }

Messages are events

The type is part of the URL we sent

$ curl -s -X PUT '.../send/m.room.message/mytransaction-A' ... "content": ... "event_id": "$14606535757KCGXo:localhost", "origin_server_ts": 1460653575105, "sender": "@example:localhost", "type": "m.room.message", "unsigned": { "age": 800348 } }

Messages are events

The content can vary

{ "content": { "body": "What *is* this?", "formatted_body": "What <b>is</b> this?", "format": "org.matrix.custom.html", "msgtype": "m.text" }, ...

Messages are events

Or maybe even like this4:

"type": "m.message", "content": { "m.message": [ { "mimetype": "text/plain", "body": "Something _new_?" }, { "mimetype": "text/html", "body": "Something <i>new</i>?" } ...

Other types of events

There are:

Other types of events

Some message events:

Other types of events

Normal messages we have already seen:

{ "content": { "body": "What *is* this?", "formatted_body": "What <b>is</b> this?", "format": "org.matrix.custom.html", "msgtype": "m.text" }, ...

Other types of events

Redactions destroy another event's content:

{ "content": { "reason": "Spamming" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts": 1432735824653, "redacts": "$fukweghifu23:localhost", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@example:example.org", "type": "m.room.redaction", "unsigned": { "age": 1234 } }

Other types of events

Polls allow asking a question:

{ "type": "org.matrix.msc3381.poll.start", "content": { "org.matrix.msc3381.poll.start": { "question": { "m.text": "Which?" }, "answers": [ { "id": "a", "m.text": "A, of course" }, { "id": "b", "m.text": "But B!" }, ] }, ...

Other types of events

Polls are unstable.

This is allowed/encouraged.

Find out more about polls in MSC33815.

Other types of events

Other types of events

Some state events:

Other types of events

Creation of a room:

{ "content": { "creator": "@example:example.org", "room_version": "9", ... }, "state_key": "", "type": "m.room.create", ...

Other types of events

Name of a room:

{ "content": { "name": "The best room" }, "state_key": "", "type": "m.room.name", ...

Other types of events

Membership of a person

{ "content": { "displayname": "Alice Margatroid", "membership": "join", ... }, "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@example:example.org", "state_key": "@alice:example.org", "type": "m.room.member", ...

Other types of events

Other types of events

Ephemeral events don't last long

{ "content": { "user_ids": [ "@alice:matrix.org", "@bob:example.com" ] }, "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "type": "m.typing" }

(Note: no event id)

State Resolution

State Resolution

The event graph

State Resolution

A split brain

State Resolution

A state conflict

State Resolution

In what order did important things happen?

State Resolution

Kahn's algorithm: no in-arrows means new

State Resolution

Kahn's algorithm: no in-arrows means new

State Resolution

Kahn's algorithm: no in-arrows means new

State Resolution

Kahn's algorithm: no in-arrows means new

State Resolution

Resolve ties using Matrix-specifics e.g. timestamp

State Resolution

Distributed Real-time Database

Chat requires a distributed real-time database

Distributed Real-time Database

A distributed real-time database is exactly what we need for many, many other things:

Matrix was always designed with this in mind.

Distributed Real-time Database

Video conferences and voice rooms

Distributed Real-time Database

Collaborative creativity

Distributed Real-time Database

Immersive environments

Distributed Real-time Database

Peer-to-peer

More info

Find out more about Matrix at matrix.org, especially:
The epic "Mega Matrix Holiday Special 2021" blog post

These slides:

http://artificialworlds.net/presentations/matrix-is-a-distributed-real-time-database

More info


artificialworlds.net

artificialworlds.net/blog

smolpxl.artificialworlds.net

youtube.com/ajbalaam
diode.zone/accounts/andybalaam

@andybalaam@mastodon.social
@andybalaam@twitter

Rabbit Escape