diff options
Diffstat (limited to 'docs/specification.rst')
| -rw-r--r-- | docs/specification.rst | 101 |
1 files changed, 68 insertions, 33 deletions
diff --git a/docs/specification.rst b/docs/specification.rst index d650683efc..c1559c886c 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -9,7 +9,9 @@ TODO(Introduction) : Matthew 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 )-----------| | +------------------+ Federation +------------------+ -- Client is an end-user (web app, mobile app) which uses C-S APIs to talk to the home server. - A given client is typically responsible for a single user. -- A single user is represented by a User ID, scoped to the home server which allocated the account. - User IDs MUST have @ prefix; looks like @foo:domain - domain indicates the user's home - server. -- Home server provides C-S APIs and has the ability to federate with other HSes. - Typically responsible for N clients. -- Federation's purpose is to share content between interested HSes; no SPOF. -- 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, - with a ``.`` delimiter e.g. ``com.example.myapp.event`` -- Events are typically send in the context of a room. +A "Client" is an end-user, typically a human using a web application or mobile app. Clients use the +"Client-to-Server" (C-S) API to communicate with their home server. A single Client is usually +responsible for a single user account. A user account is represented by their "User ID". This ID is +namespaced to the home server which allocated the account and looks like:: + + @localpart:domain + +The ``localpart`` of a user ID may be a user name, or an opaque ID identifying this user. + + +A "Home Server" is a server which provides C-S APIs and has the ability to federate with other HSes. +It is typically responsible for multiple clients. "Federation" is the term used to describe the +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 -------------- -A room is a conceptual place where users can send and receive messages. Rooms -can be created, joined and left. Messages are sent to a room, and all -participants in that room will receive the message. Rooms are uniquely -identified via a room ID. There is exactly one room ID for each room. Each -room can also have an alias. Each room can have many aliases. +A room is a conceptual place where users can send and receive events. Rooms +can be created, joined and left. Events are sent to a room, and all +participants in that room will receive the event. Rooms are uniquely +identified via a "Room ID", which look like:: -- Room IDs MUST have ! prefix; looks like !foo:domain - domain is simply for namespacing, - the room does NOT reside on any one domain. NOT human readable. + !opaque_id:domain -- Room Aliases MUST have # prefix; looks like #foo:domain - domain indicates where this - alias can be mapped to a room ID. Key point: human readable / friendly. +There is exactly one room ID for each room. Whilst the room ID does contain a +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 - mapping exists. These mappings can change. - -:: +The following diagram shows an ``m.room.message`` event being sent in the room +``!qporfwt:matrix.org``:: { @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 | +------------------+ +------------------+ | ................................. | - |______| Shared State |_______| - | Room ID: !qporfwt:matrix.org | + |______| Partially Shared State |_______| + | Room ID: !qporfwt:matrix.org | | Servers: matrix.org, domain.com | | Members: | | - @alice:matrix.org | | - @bob:domain.com | |.................................| -- Federation's goal is to maintain the shared state. Don't need FULL state in order - to be a part of a room. -- Introduce the DAG. -- Events are wrapped in PDUs. +Federation maintains shared state between multiple home servers, such that when an event is +sent to a room, the home server knows where to forward the event on to, and how to process +the event. Home servers do not need to have completely shared state in order to participate +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 |