Merge branch 'develop' of github.com:matrix-org/synapse into develop

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
+