Add /turnServer endpoint

api/client-server/v1/voip.yaml

@@ -0,0 +1,68 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 Voice over IP API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/api/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/turnServer":
+    get:
+      summary: Obtain TURN server credentials.
+      description: |-
+        This API provides credentials for the client to use when initiating
+        calls.
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: The TURN server credentials.
+          examples:
+            application/json: |-
+              {
+                "username":"1443779631:@user:example.com",
+                "password":"JlKfBy1QwLrO20385QyAtEyIv0=",
+                "uris":[
+                  "turn:turn.example.com:3478?transport=udp",
+                  "turn:10.20.30.40:3478?transport=tcp",
+                  "turns:10.20.30.40:443?transport=tcp"
+                ],
+                "ttl":86400
+              }
+          schema:
+            type: object
+            properties:
+              username:
+                type: string
+                description: |-
+                  The username to use.
+              password:
+                type: string
+                description: |-
+                  The password to use.
+              uris:
+                type: array
+                items:
+                  type: string
+                description: A list of TURN URIs
+              ttl:
+                type: integer
+                description: The time-to-live in seconds
+            required: ["username", "password", "uris", "ttl"]
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+

specification/modules/voip_events.rst

@@ -10,8 +10,14 @@ communication.
 
 .. _message events: `sect:events`_
 
-Message Exchange
+Events
+------
+
+{{voip_events}}
+
+Client behaviour
 ----------------
+
 A call is set up with message events exchanged as follows:
 
 ::
@@ -39,14 +45,6 @@ Or a rejected call:
 
 Calls are negotiated according to the WebRTC specification.
 
-Events
-------
-
-{{voip_events}}
-
-Client behaviour
-----------------
-
 Glare
 ~~~~~
 
@@ -72,7 +70,7 @@ algorithm is as follows:
    the same room and is waiting for a response:
 
     * the client should perform a lexicographical comparison of the call IDs of
-      the two calls and use the **lesser** of the two calls, aborting the
+      the two calls and use the *lesser* of the two calls, aborting the
       greater. If the incoming call is the lesser, the client should accept
       this call on behalf of the user.
 
@@ -85,11 +83,17 @@ replaces it.
 Server behaviour
 ----------------
 
-TURN Servers
-~~~~~~~~~~~~
+The server MAY provide a TURN server which clients can use to contact the
+remote party. This server should be accessible via the HTTP endpoint listed
+below.
+
+{{voip_http_api}}
+
 
 Security considerations
 -----------------------
 
-
+Calls should only be placed to rooms with one other user in them. If they are
+placed to group chat rooms it is possible that another user will intercept and
+answer the call.