From 569d496430fb983b92de6603433e5c575d48ddd7 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Mon, 12 Jan 2015 16:57:02 +0000 Subject: [PATCH] Rearrange sections --- drafts/erikj_federation.rst | 178 +++++++++++++++++++----------------- 1 file changed, 93 insertions(+), 85 deletions(-) diff --git a/drafts/erikj_federation.rst b/drafts/erikj_federation.rst index 5efc6a90..68087b2b 100644 --- a/drafts/erikj_federation.rst +++ b/drafts/erikj_federation.rst @@ -37,6 +37,84 @@ User Id ``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 ------------- @@ -119,6 +197,16 @@ include validation). #. Allow. +Definitions +~~~~~~~~~~~ + +Required Power Level + A given event type has an associated *required power level*. This is given + by the current ``m.room.power_levels`` event, it is either listed explicitly + in the ``events`` section or given by either ``state_default`` or + ``events_default`` depending on if the event type is a state event or not. + + Auth events ~~~~~~~~~~~ @@ -147,14 +235,12 @@ events and the event being authed. **TODO**: Clean the above explanations up a bit. -Definitions -~~~~~~~~~~~ +Auth chain resolution +~~~~~~~~~~~~~~~~~~~~~ + +**TODO**: If an auth check fails, or if we get told something we accepted +should have been rejected, we need to try and determine who is right. -Required Power Level - A given event type has an associated *required power level*. This is given - by the current ``m.room.power_levels`` event, it is either listed explicitly - in the ``events`` section or given by either ``state_default`` or - ``events_default`` depending on if the event type is a state event or not. State Resolution @@ -162,84 +248,6 @@ State Resolution **TODO** -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 ========