diff options
Diffstat (limited to 'docs/specification.rst')
| -rw-r--r-- | docs/specification.rst | 176 |
1 files changed, 153 insertions, 23 deletions
diff --git a/docs/specification.rst b/docs/specification.rst index a329c07542..b15792c00d 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? @@ -417,6 +418,16 @@ which can be set when creating a room: If this is included, an ``m.room.topic`` event will be sent into the room to indicate the topic for the room. See `Room Events`_ for more information on ``m.room.topic``. +``invite`` + Type: + List + Optional: + Yes + Value: + A list of user ids to invite. + Description: + This will tell the server to invite everyone in the list to the newly created room. + Example:: { @@ -473,7 +484,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 +496,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 @@ -908,6 +921,22 @@ prefixed with ``m.`` ``ban_level`` will be greater than or equal to ``kick_level`` since banning is more severe than kicking. +``m.room.aliases`` + Summary: + These state events are used to inform the room about what room aliases it has. + Type: + State event + JSON format: + ``{ "aliases": ["string", ...] }`` + Example: + ``{ "aliases": ["#foo:example.com"] }`` + Description: + A server `may` inform the room that it has added or removed an alias for + the room. This is purely for informational purposes and may become stale. + Clients `should` check that the room alias is still valid before using it. + The ``state_key`` of the event is the homeserver which owns the room + alias. + ``m.room.message`` Summary: A message. @@ -1124,19 +1153,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:: @@ -1151,8 +1265,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. @@ -1466,17 +1580,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. @@ -1692,7 +1808,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. @@ -1778,7 +1894,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:: @@ -1858,6 +1974,10 @@ victim would then include in their view of the chatroom history. Other servers in the chatroom would reject the invalid messages and potentially reject the victims messages as well since they depended on the invalid messages. +.. TODO + Track trustworthiness of HS or users based on if they try to pretend they + haven't seen recent events, and fake a splitbrain... --M + Threat: Block Network Traffic +++++++++++++++++++++++++++++ @@ -1963,6 +2083,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 @@ -1973,6 +2096,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:: @@ -2071,6 +2197,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 .. ============================================= @@ -2118,3 +2247,4 @@ Transaction: .. _/join/<room_alias_or_id>: /docs/api/client-server/#!/-rooms/join .. _`Event Stream`: /docs/api/client-server/#!/-events/get_event_stream + |