From 4b76181f740c02f96b1b0f80ddbbaa9f6c4bad56 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 15 Jan 2015 13:53:54 +0000 Subject: [PATCH] Rearrange sections --- drafts/erikj_federation.rst | 255 ++++++++++++++++++------------------ 1 file changed, 127 insertions(+), 128 deletions(-) diff --git a/drafts/erikj_federation.rst b/drafts/erikj_federation.rst index be026871..ab89cfae 100644 --- a/drafts/erikj_federation.rst +++ b/drafts/erikj_federation.rst @@ -1,135 +1,8 @@ Federation ========== -.. sectnum +.. sectnum:: .. contents:: Table of Contents -Constructing a new event ------------------------- - - **TODO** - -When constructing a new event, the server should insert the following fields: - -- ``prev_events``: The list of event ids of what the server believes are the - current leaf nodes of the event graph (i.e., nodes that have been received - but are yet to be referenced by another event). -- ``depth``: An integer one greater than the maximum depth of the event's - previous events. -- ``auth_events``: The list of event ids that authorizes this event. This - should be a subset of the current state. -- ``origin_server_ts``: The time the server created the event. -- ``origin``: The name of the server. - - -Signing and Hashes -~~~~~~~~~~~~~~~~~~ - - **TODO** - -Validation ----------- - - **TODO** - -Domain specific string - A string of the form ``:``, where is a - single character, ```` is an arbitrary string that does not - include a colon, and `` is a valid server name. - -``room_id`` - A domain specific string with prefix ``!`` that is static across all events - in a graph and uniquely identifies it. The ``domain`` should be that of the - home server that created the room (i.e., the server that generated the - first ``m.room.create`` event). - -``sender`` - The entity that logically sent the event. This is usually a user id, but - can also be a server name. - -User Id - A domain specific string with prefix ``@`` representing a user account. The - ``domain`` is the home server of the user and is the server used to contact - the user. - -Joining a room --------------- - -If a user requests to join a room that the server is already in (i.e. the a -user on that server has already joined the room) then the server can simply -generate a join event and send it as normal. - -If the server is not already in the room it needs to will need to join via -another server that is already in the room. This is done as a two step process. - -First, the local server requests from the remote server a skeleton of a join -event. The remote does this as the local server does not have the event graph -to use to fill out the ``prev_events`` key in the new event. Critically, the -remote server does not process the event it responded with. - -Once the local server has this event, it fills it out with any extra data and -signs it. Once ready the local server sends this event to a remote server -(which could be the same or different from the first remote server), this -remote server then processes the event and distributes to all the other -participating servers in that room. The local server is told about the -current state and complete auth chain for the join event. The local server -can then process the join event itself. - - -.. Note:: - Finding which server to use to join any particular room is not specified. - - -Inviting a user ---------------- - -To invite a remote user to a room we need their home server to sign the invite -event. This is done by sending the event to the remote server, which then signs -the event, before distributing the invite to other servers. - -Failures --------- - -A server can notify a remote server about something it thinks it has done -wrong using the failures mechanism. For example, the remote accepted an event -the local think it shouldn't have. - -A failure has a severity level depending on the action taken by the local -server. These levels are: - -``FATAL`` - The local server could not parse the event, for example due to a missing - required field. - -``ERROR`` - The local server *could* parse the event, but it was rejected. For example, - the event may have failed an authorization check. - -``WARN`` - The local server accepted the event, but something was unexpected about it. - For example, the event may have referenced another event the local server - thought should be rejected. - -A failure also includes several other fields: - -``code`` - A numeric code (to be defined later) indicating a particular type of - failure. - -``reason`` - A short string indicating what was wrong, for diagnosis purposes on the - remote server. - -``affected`` - The event id of the event this failure is responding to. For example, if - an accepted event referenced a rejected event, this would point to the - accepted one. - -``source`` - The event id of the event that was the source of this unexpected behaviour. - For example, if an accepted event referenced a rejected event, this would - point to the rejected one. - - Authorization ------------- @@ -305,6 +178,132 @@ If a server discovers that it disagrees with another about the current state, it can follow the same process outlined in *Auth chain resolution* to resolve these conflicts. +Constructing a new event +------------------------ + + **TODO** + +When constructing a new event, the server should insert the following fields: + +- ``prev_events``: The list of event ids of what the server believes are the + current leaf nodes of the event graph (i.e., nodes that have been received + but are yet to be referenced by another event). +- ``depth``: An integer one greater than the maximum depth of the event's + previous events. +- ``auth_events``: The list of event ids that authorizes this event. This + should be a subset of the current state. +- ``origin_server_ts``: The time the server created the event. +- ``origin``: The name of the server. + + +Signing and Hashes +~~~~~~~~~~~~~~~~~~ + + **TODO** + +Validation +---------- + + **TODO** + +Domain specific string + A string of the form ``:``, where is a + single character, ```` is an arbitrary string that does not + include a colon, and `` is a valid server name. + +``room_id`` + A domain specific string with prefix ``!`` that is static across all events + in a graph and uniquely identifies it. The ``domain`` should be that of the + home server that created the room (i.e., the server that generated the + first ``m.room.create`` event). + +``sender`` + The entity that logically sent the event. This is usually a user id, but + can also be a server name. + +User Id + A domain specific string with prefix ``@`` representing a user account. The + ``domain`` is the home server of the user and is the server used to contact + the user. + +Joining a room +-------------- + +If a user requests to join a room that the server is already in (i.e. the a +user on that server has already joined the room) then the server can simply +generate a join event and send it as normal. + +If the server is not already in the room it needs to will need to join via +another server that is already in the room. This is done as a two step process. + +First, the local server requests from the remote server a skeleton of a join +event. The remote does this as the local server does not have the event graph +to use to fill out the ``prev_events`` key in the new event. Critically, the +remote server does not process the event it responded with. + +Once the local server has this event, it fills it out with any extra data and +signs it. Once ready the local server sends this event to a remote server +(which could be the same or different from the first remote server), this +remote server then processes the event and distributes to all the other +participating servers in that room. The local server is told about the +current state and complete auth chain for the join event. The local server +can then process the join event itself. + + +.. Note:: + Finding which server to use to join any particular room is not specified. + + +Inviting a user +--------------- + +To invite a remote user to a room we need their home server to sign the invite +event. This is done by sending the event to the remote server, which then signs +the event, before distributing the invite to other servers. + +Failures +-------- + +A server can notify a remote server about something it thinks it has done +wrong using the failures mechanism. For example, the remote accepted an event +the local think it shouldn't have. + +A failure has a severity level depending on the action taken by the local +server. These levels are: + +``FATAL`` + The local server could not parse the event, for example due to a missing + required field. + +``ERROR`` + The local server *could* parse the event, but it was rejected. For example, + the event may have failed an authorization check. + +``WARN`` + The local server accepted the event, but something was unexpected about it. + For example, the event may have referenced another event the local server + thought should be rejected. + +A failure also includes several other fields: + +``code`` + A numeric code (to be defined later) indicating a particular type of + failure. + +``reason`` + A short string indicating what was wrong, for diagnosis purposes on the + remote server. + +``affected`` + The event id of the event this failure is responding to. For example, if + an accepted event referenced a rejected event, this would point to the + accepted one. + +``source`` + The event id of the event that was the source of this unexpected behaviour. + For example, if an accepted event referenced a rejected event, this would + point to the rejected one. + Appendix ========