Expand architecture section to introduce room IDs, room aliases, user IDs, events and federation.

This commit is contained in:
Kegan Dougal 2014-08-29 11:41:48 +01:00
parent 171d8b032f
commit ac56ac67cc

View file

@ -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