Expand architecture section to introduce room IDs, room aliases, user IDs, events and federation.
This commit is contained in:
Kegan Dougal
parent
171d8b032f
commit
ac56ac67cc
|
|
@ -9,7 +9,9 @@ TODO(Introduction) : Matthew
|
||||||
|
|
||||||
Architecture
|
Architecture
|
||||||
============
|
============
|
||||||
- Sending a message from A to B
|
|
||||||
|
Clients transmit data to other clients through home servers (HSes). Clients do not communicate with each
|
||||||
|
other directly.
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
|
|
@ -26,39 +28,42 @@ Architecture
|
||||||
| |<--------( HTTP )-----------| |
|
| |<--------( HTTP )-----------| |
|
||||||
+------------------+ Federation +------------------+
|
+------------------+ Federation +------------------+
|
||||||
|
|
||||||
- Client is an end-user (web app, mobile app) which uses C-S APIs to talk to the home server.
|
A "Client" is an end-user, typically a human using a web application or mobile app. Clients use the
|
||||||
A given client is typically responsible for a single user.
|
"Client-to-Server" (C-S) API to communicate with their home server. A single Client is usually
|
||||||
- A single user is represented by a User ID, scoped to the home server which allocated the account.
|
responsible for a single user account. A user account is represented by their "User ID". This ID is
|
||||||
User IDs MUST have @ prefix; looks like @foo:domain - domain indicates the user's home
|
namespaced to the home server which allocated the account and looks like::
|
||||||
server.
|
|
||||||
- Home server provides C-S APIs and has the ability to federate with other HSes.
|
@localpart:domain
|
||||||
Typically responsible for N clients.
|
|
||||||
- Federation's purpose is to share content between interested HSes; no SPOF.
|
The ``localpart`` of a user ID may be a user name, or an opaque ID identifying this user.
|
||||||
- Events are actions within the system. Typically each action (e.g. sending a message)
|
|
||||||
correlates with exactly one event. Each event has a ``type`` string.
|
|
||||||
- ``type`` values SHOULD be namespaced according to standard Java package naming conventions,
|
A "Home Server" is a server which provides C-S APIs and has the ability to federate with other HSes.
|
||||||
with a ``.`` delimiter e.g. ``com.example.myapp.event``
|
It is typically responsible for multiple clients. "Federation" is the term used to describe the
|
||||||
- Events are typically send in the context of a room.
|
sharing of data between two or more home servers.
|
||||||
|
|
||||||
|
Data in Matrix is encapsulated in an "Event". An event is an action within the system. Typically each
|
||||||
|
action (e.g. sending a message) correlates with exactly one event. Each event has a ``type`` which is
|
||||||
|
used to differentiate different kinds of data. ``type`` values SHOULD be namespaced according to standard
|
||||||
|
Java package naming conventions, e.g. ``com.example.myapp.event``. Events are usually sent in the context
|
||||||
|
of a "Room".
|
||||||
|
|
||||||
Room structure
|
Room structure
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
A room is a conceptual place where users can send and receive messages. Rooms
|
A room is a conceptual place where users can send and receive events. Rooms
|
||||||
can be created, joined and left. Messages are sent to a room, and all
|
can be created, joined and left. Events are sent to a room, and all
|
||||||
participants in that room will receive the message. Rooms are uniquely
|
participants in that room will receive the event. Rooms are uniquely
|
||||||
identified via a room ID. There is exactly one room ID for each room. Each
|
identified via a "Room ID", which look like::
|
||||||
room can also have an alias. Each room can have many aliases.
|
|
||||||
|
|
||||||
- Room IDs MUST have ! prefix; looks like !foo:domain - domain is simply for namespacing,
|
!opaque_id:domain
|
||||||
the room does NOT reside on any one domain. NOT human readable.
|
|
||||||
|
|
||||||
- Room Aliases MUST have # prefix; looks like #foo:domain - domain indicates where this
|
There is exactly one room ID for each room. Whilst the room ID does contain a
|
||||||
alias can be mapped to a room ID. Key point: human readable / friendly.
|
domain, it is simply for namespacing room IDs. The room does NOT reside on the
|
||||||
|
domain specified. Room IDs are not meant to be human readable.
|
||||||
|
|
||||||
- Aliases can be queried on the domain they specify, which will return a room ID if a
|
The following diagram shows an ``m.room.message`` event being sent in the room
|
||||||
mapping exists. These mappings can change.
|
``!qporfwt:matrix.org``::
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
{ @alice:matrix.org } { @bob:domain.com }
|
{ @alice:matrix.org } { @bob:domain.com }
|
||||||
| ^
|
| ^
|
||||||
|
|
@ -73,18 +78,48 @@ room can also have an alias. Each room can have many aliases.
|
||||||
| matrix.org |<-------Federation------->| domain.com |
|
| matrix.org |<-------Federation------->| domain.com |
|
||||||
+------------------+ +------------------+
|
+------------------+ +------------------+
|
||||||
| ................................. |
|
| ................................. |
|
||||||
|______| Shared State |_______|
|
|______| Partially Shared State |_______|
|
||||||
| Room ID: !qporfwt:matrix.org |
|
| Room ID: !qporfwt:matrix.org |
|
||||||
| Servers: matrix.org, domain.com |
|
| Servers: matrix.org, domain.com |
|
||||||
| Members: |
|
| Members: |
|
||||||
| - @alice:matrix.org |
|
| - @alice:matrix.org |
|
||||||
| - @bob:domain.com |
|
| - @bob:domain.com |
|
||||||
|.................................|
|
|.................................|
|
||||||
|
|
||||||
- Federation's goal is to maintain the shared state. Don't need FULL state in order
|
Federation maintains shared state between multiple home servers, such that when an event is
|
||||||
to be a part of a room.
|
sent to a room, the home server knows where to forward the event on to, and how to process
|
||||||
- Introduce the DAG.
|
the event. Home servers do not need to have completely shared state in order to participate
|
||||||
- Events are wrapped in PDUs.
|
in a room. State is scoped to a single room, and federation ensures that all home servers
|
||||||
|
have the information they need, even if that means the home server has to request more
|
||||||
|
information from another home server before processing the event.
|
||||||
|
|
||||||
|
Room Aliases
|
||||||
|
------------
|
||||||
|
|
||||||
|
Each room can also have multiple "Room Aliases", which looks like::
|
||||||
|
|
||||||
|
#room_alias:domain
|
||||||
|
|
||||||
|
A room alias "points" to a room ID. The room ID the alias is pointing to can be obtained
|
||||||
|
by visiting the domain specified. Room aliases are designed to be human readable strings
|
||||||
|
which can be used to publicise rooms. Note that the mapping from a room alias to a
|
||||||
|
room ID is not fixed, and may change over time to point to a different room ID. For this
|
||||||
|
reason, Clients SHOULD resolve the room alias to a room ID once and then use that ID on
|
||||||
|
subsequent requests.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
GET
|
||||||
|
#matrix:domain.com !aaabaa:matrix.org
|
||||||
|
| ^
|
||||||
|
| |
|
||||||
|
_______V____________________|____
|
||||||
|
| domain.com |
|
||||||
|
| Mappings: |
|
||||||
|
| #matrix >> !aaabaa:matrix.org |
|
||||||
|
| #golf >> !wfeiofh:sport.com |
|
||||||
|
| #bike >> !4rguxf:matrix.org |
|
||||||
|
|________________________________|
|
||||||
|
|
||||||
|
|
||||||
Identity
|
Identity
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue