diff options
Diffstat (limited to 'docs/specification.rst')
| -rw-r--r-- | docs/specification.rst | 146 |
1 files changed, 123 insertions, 23 deletions
diff --git a/docs/specification.rst b/docs/specification.rst index 239e51b4f3..1d3c283331 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -347,11 +347,12 @@ Receiving live updates on a client Clients can receive new events by long-polling the home server. This will hold open the HTTP connection for a short period of time waiting for new events, returning early if an event occurs. This is called the `Event Stream`_. All events which are visible to the -client and match the client's query will appear in the event stream. When the request +client will appear in the event stream. When the request returns, an ``end`` token is included in the response. This token can be used in the next request to continue where the client left off. .. TODO + How do we filter the event stream? Do we ever return multiple events in a single request? Don't we get lots of request setup RTT latency if we only do one event per request? Do we ever support streaming requests? Why not websockets? @@ -473,7 +474,9 @@ action in a room a user must have a suitable power level. Power levels for users are defined in ``m.room.power_levels``, where both a default and specific users' power levels can be set. By default all users -have a power level of 0. +have a power level of 0, other than the room creator whose power level defaults to 100. +Power levels for users are tracked per-room even if the user is not present in +the room. State events may contain a ``required_power_level`` key, which indicates the minimum power a user must have before they can update that state key. The only @@ -483,11 +486,11 @@ To perform certain actions there are additional power level requirements defined in the following state events: - ``m.room.send_event_level`` defines the minimum level for sending non-state - events. Defaults to 5. + events. Defaults to 50. - ``m.room.add_state_level`` defines the minimum level for adding new state, - rather than updating existing state. Defaults to 5. + rather than updating existing state. Defaults to 50. - ``m.room.ops_level`` defines the minimum levels to ban and kick other users. - This defaults to a kick and ban levels of 5 each. + This defaults to a kick and ban levels of 50 each. Joining rooms @@ -1122,19 +1125,104 @@ Typing notifications Voice over IP ============= -.. NOTE:: - This section is a work in progress. +Matrix can also be used to set up VoIP calls. This is part of the core specification, +although is still in a very early stage. Voice (and video) over Matrix is based on +the WebRTC standards. -.. TODO Dave - - what are the event types. - - what are the valid keys/values. What do they represent. Any gotchas? - - In what sequence should the events be sent? - - How do you accept / decline inbound calls? How do you make outbound calls? - Give examples. - - How does negotiation work? Give examples. - - How do you hang up? - - What does call log information look like e.g. duration of call? +Call events are sent to a room, like any other event. This means that clients +must only send call events to rooms with exactly two participants as currently +the WebRTC standard is based around two-party communication. + +Events +------ +``m.call.invite`` +This event is sent by the caller when they wish to establish a call. + + Required keys: + - ``call_id`` : "string" - A unique identifier for the call + - ``offer`` : "offer object" - The session description + - ``version`` : "integer" - The version of the VoIP specification this message + adheres to. This specification is version 0. + + Optional keys: + None. + Example: + ``{ "version" : 0, "call_id": "12345", "offer": { "type" : "offer", "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]" } }`` + +``Offer Object`` + Required keys: + - ``type`` : "string" - The type of session description, in this case 'offer' + - ``sdp`` : "string" - The SDP text of the session description + +``m.call.candidate`` +This event is sent by callers after sending an invite and by the callee after answering. +Its purpose is to give the other party an additional ICE candidate to try using to +communicate. + + Required keys: + - ``call_id`` : "string" - The ID of the call this event relates to + - ``version`` : "integer" - The version of the VoIP specification this messages + adheres to. his specification is version 0. + - ``candidate`` : "candidate object" - Object describing the candidate. + +``Candidate Object`` + + Required Keys: + - ``sdpMid`` : "string" - The SDP media type this candidate is intended for. + - ``sdpMLineIndex`` : "integer" - The index of the SDP 'm' line this + candidate is intended for + - ``candidate`` : "string" - The SDP 'a' line of the candidate + +``m.call.answer`` + + Required keys: + - ``call_id`` : "string" - The ID of the call this event relates to + - ``version`` : "integer" - The version of the VoIP specification this messages + - ``answer`` : "answer object" - Object giving the SDK answer + +``Answer Object`` + Required keys: + - ``type`` : "string" - The type of session description. 'answer' in this case. + - ``sdp`` : "string" - The SDP text of the session description + +``m.call.hangup`` +Sent by either party to signal their termination of the call. This can be sent either once +the call has has been established or before to abort the call. + + Required keys: + - ``call_id`` : "string" - The ID of the call this event relates to + - ``version`` : "integer" - The version of the VoIP specification this messages + +Message Exchange +---------------- +A call is set up with messages exchanged as follows: + +:: + + Caller Callee + m.call.invite -----------> + m.call.candidate --------> + [more candidates events] + User answers call + <------ m.call.answer + [...] + <------ m.call.hangup + +Or a rejected call: + +:: + + Caller Callee + m.call.invite -----------> + m.call.candidate --------> + [more candidates events] + User rejects call + <------- m.call.hangup + +Calls are negotiated according to the WebRTC specification. + + Profiles ======== .. NOTE:: @@ -1149,8 +1237,8 @@ Profiles - Display name changes also generates m.room.member with displayname key f.e. room the user is in. -Internally within Matrix users are referred to by their user ID, which is not a -human-friendly string. Profiles grant users the ability to see human-readable +Internally within Matrix users are referred to by their user ID, which is typically +a compact unique identifier. Profiles grant users the ability to see human-readable names for other users that are in some way meaningful to them. Additionally, profiles can publish additional information, such as the user's age or location. @@ -1464,17 +1552,19 @@ Federation is the term used to describe how to communicate between Matrix home servers. Federation is a mechanism by which two home servers can exchange Matrix event messages, both as a real-time push of current events, and as a historic fetching mechanism to synchronise past history for clients to view. It -uses HTTP connections between each pair of servers involved as the underlying +uses HTTPS connections between each pair of servers involved as the underlying transport. Messages are exchanged between servers in real-time by active pushing from each server's HTTP client into the server of the other. Queries to fetch historic data for the purpose of back-filling scrollback buffers and the like -can also be performed. +can also be performed. Currently routing of messages between homeservers is full +mesh (like email) - however, fan-out refinements to this design are currently +under consideration. There are three main kinds of communication that occur between home servers: :Queries: These are single request/response interactions between a given pair of - servers, initiated by one side sending an HTTP GET request to obtain some + servers, initiated by one side sending an HTTPS GET request to obtain some information, and responded by the other. They are not persisted and contain no long-term significant history. They simply request a snapshot state at the instant the query is made. @@ -1690,7 +1780,7 @@ by the same origin as the current one, or other origins. Because of the distributed nature of participants in a Matrix conversation, it is impossible to establish a globally-consistent total ordering on the events. However, by annotating each outbound PDU at its origin with IDs of other PDUs it -has received, a partial ordering can be constructed allowing causallity +has received, a partial ordering can be constructed allowing causality relationships to be preserved. A client can then display these messages to the end-user in some order consistent with their content and ensure that no message that is semantically in reply of an earlier one is ever displayed before it. @@ -1776,7 +1866,7 @@ Retrieves a sliding-window history of previous PDUs that occurred on the given context. Starting from the PDU ID(s) given in the "v" argument, the PDUs that preceeded it are retrieved, up to a total number given by the "limit" argument. These are then returned in a new Transaction containing all -off the PDUs. +of the PDUs. To stream events all the events:: @@ -1961,6 +2051,9 @@ The ``retry_after_ms`` key SHOULD be included to tell the client how long they h in milliseconds before they can try again. .. TODO + - Surely we should recommend an algorithm for the rate limiting, rather than letting every + homeserver come up with their own idea, causing totally unpredictable performance over + federated rooms? - crypto (s-s auth) - E2E - Lawful intercept + Key Escrow @@ -1971,6 +2064,9 @@ Policy Servers .. NOTE:: This section is a work in progress. +.. TODO + We should mention them in the Architecture section at least... + Content repository ================== .. NOTE:: @@ -2069,6 +2165,9 @@ Transaction: A message which relates to the communication between a given pair of servers. A transaction contains possibly-empty lists of PDUs and EDUs. +.. TODO + This glossary contradicts the terms used above - especially on State Events v. "State" + and Non-State Events v. "Events". We need better consistent names. .. Links through the external API docs are below .. ============================================= @@ -2116,3 +2215,4 @@ Transaction: .. _/join/<room_alias_or_id>: /docs/api/client-server/#!/-rooms/join .. _`Event Stream`: /docs/api/client-server/#!/-events/get_event_stream + |