Specify how to handle foci better

Signed-off-by: Šimon Brandner <simon.bra.ag@gmail.com>

proposals/3898-sfu.md

@@ -26,39 +26,10 @@ right to subscribe to track?**
 The diagrams of how this all looks can be found in
 [MSC3401](https://github.com/matrix-org/matrix-spec-proposals/pull/3401).
 
-### State events
+### Additions to the `m.call.member` state event
 
-#### `m.call` state event
-
-This MSC proposes adding an _optional_ `m.foci` field to the `m.call` state
-event. It as list of recommended SFUs that the call initiator can recommend to
-users who do not want to use their own SFU (because they don't have one, or
-because they would be the only person on their SFU for their call, and so choose
-to connect direct to save bandwidth).
-
-For instance:
-
-```json
-{
-    "type": "m.call",
-    "state_key": "cvsiu2893",
-    "content": {
-        "m.intent": "m.room",
-        "m.type": "m.voice",
-        "m.name": "Voice room",
-        "m.foci": [
-            { "user_id": "@sfu-lon:matrix.org", "device_id": "FS5F589EF" },
-            { "user_id": "@sfu-nyc:matrix.org", "device_id": "VT4GA35VS" },
-        ],
-    }
-}
-```
-
-#### `m.call.member` state event
-
-This MSC proposes adding an _optional_ `m.foci` field to the `m.call.member`
-state event. It is used, if the user wants to be contacted via an SFU rather
-than called directly (either 1:1 or full mesh).
+This MSC proposes adding two _optional_ fields to the `m.call.member` state event:
+`m.foci.preferred` and `m.foci.active`.
 
 For instance:
 
@@ -70,50 +41,100 @@ For instance:
         "m.calls": [
             {
                 "m.call_id": "cvsiu2893",
-                "m.foci": [
-                    { "user_id": "@sfu-lon:matrix.org", "device_id": "FS5F589EF" },
-                    { "user_id": "@sfu-nyc:matrix.org", "device_id": "VT4GA35VS" },
-                ],
-                "m.devices": [...]
+                "m.devices": [{
+                    "device_id": "U738KDF9WJ",
+                    "m.foci.active": [
+                        { "user_id": "@sfu-lon:matrix.org", "device_id": "FS5F589EF" }
+                    ],
+                    "m.foci.preferred": [
+                        { "user_id": "@sfu-bon:matrix.org", "device_id": "3FSF589EF" },
+                        { "user_id": "@sfu-mon:matrix.org", "device_id": "GFSDH93EF" },
+                    ]
+                }]
             }
         ],
         "m.expires_ts":  1654616071686
     }
 }
 ```
 
-### Choosing an SFU
-
-**TODO: How does a client discover SFUs** **TODO: Is SFU identified by just
-`user_id` or `(user_id, device_id)`?**
-
-* When initiating a group call, we need to decide which devices to actually talk
-  to.
-  * If the client has no SFU configured, we try to use the `m.foci` in the
-    `m.call` event.
-    * If there are multiple `m.foci`, we select the closest one based on
-      latency, e.g. by trying to connect to all of them simultaneously and
-      discarding all but the first call to answer.
-    * If there are no `m.foci` in the `m.call` event, then we look at which foci
-      in `m.call.member` that are already in use by existing participants, and
-      select the most common one.  (If the focus is overloaded it can reject us
-      and we should then try the next most populous one, etc).
-    * If there are no `m.foci` in the `m.call.member`, then we connect full
-      mesh.
-    * If subsequently `m.foci` are introduced into the conference, then we
-      should transfer the call to them (effectively doing a 1:1->group call
-      upgrade).
-  * If the client does have an SFU configured, then we decide whether to use it.
-    * If other conf participants are already using it, then we use it.
-    * If there are other users from our homeserver in the conference, then we
-      use it (as presumably they should be using it too)
-    * If there are no other `m.foci` (either in the `m.call` or in the
-      participant state) then we use it.
-    * Otherwise, we save bandwidth on our SFU by not cascading and instead
-      behaving as if we had no SFU configured.
-* We do not recommend that users utilise an SFU to hide behind for privacy, but
-  instead use a TURN server, only providing relay candidates, rather than
-  consuming SFU resources and unnecessarily mandating the presence of an SFU.
+#### `m.foci.active`
+
+This field is a list of foci the user's device is publishing to. Usually, this
+list will have a length of 1, yet a client might publish to multiple foci if
+they are on different networks, for instance, or to simultaneously fan-out in
+different directions from the client if there is no nearby focus. If the client
+is participating full-mesh, it should either omit this field from the state
+event or leave the list empty.
+
+#### `m.foci.preferred`
+
+This field is a list of foci the client would prefer to switch to from the
+current active focus, if any other client also starts using the given focus. If
+the client is already using one of its preferred foci, it should either omit
+this field from the state event or leave the list empty.
+
+### Choosing a focus
+
+#### Discovering foci
+
+**TODO: How does a client discover foci? We could use well-known or a custom endpoint**
+
+Foci are identified by a tuple of `user_id` and `device_id`.
+
+#### Determining the best focus
+
+There are many ways to determine the best focus; this MSC recommends the
+following:
+
+- Is the quickest to respond to `m.call.invite` with `m.call.answer`.
+- Is the quickest to rapidly reject a spurious HTTPS request to a high-numbered
+  port on the SFU's IP address, if the SFU exposes its IP somewhere - similar to
+  the [apenwarr/blip](https://github.com/apenwarr/blip) trick, in order to
+  measure media-path latency rather than signalling path latency.
+- Has the best latency of data-channel traffic flows.
+- Has the best latency and bandwidth determined by sending a small splurge of
+  media down the pipe to probe.
+
+#### Joining a call
+
+The following diagram explains how a client chooses a focus when joining a call.
+
+```mermaid
+flowchart TD;
+wantsToJoin[Wants to join a call];
+hasPreferred(Has preferred focus?);
+callPreferred[Calls preferred foci without media to grab a slot];
+publishPreferred[Publishes `m.foci.preferred`];
+checkMembers(Call has more than 2 members including the client itself?);
+callFullMesh[Calls other member full-mesh];
+callMembersFoci[Tries calling foci from `m.call.member` events];
+orderFoci[Orders foci from best to worst];
+findFocusPreferredByOtherMember(Goes through ordered foci to find one which is preferred by at least one other member);
+callBestPreferred[Calls the focus];
+callBestActive[Calls the best active focus in room];
+publishActive[Publishes `m.foci.active`];
+
+wantsToJoin-->hasPreferred;
+hasPreferred--->|Yes|callPreferred;
+hasPreferred--->|No|checkMembers;
+callPreferred--->publishPreferred;
+publishPreferred--->checkMembers;
+checkMembers--->|Yes|callMembersFoci;
+checkMembers--->|No|callFullMesh;
+callMembersFoci--->orderFoci;
+orderFoci--->findFocusPreferredByOtherMember;
+findFocusPreferredByOtherMember--->|Found|callBestPreferred;
+callBestPreferred--->publishActive;
+findFocusPreferredByOtherMember--->|Not found|callBestActive;
+callBestActive--->publishActive;
+```
+
+#### Mid-call changes
+
+Once in a call, the client listens for changes to `m.call.member` state events
+and if another member starts using one of the client's preferred foci, the client
+switches to that focus.
 
 ### Initial offer/answer dance
 
@@ -269,6 +290,14 @@ participants leave, a new megolm session is created and shared with all
 participants over Olm.  The new session is only used once all participants have
 received it.
 
+### Notes
+
+#### Hiding behind foci
+
+We do not recommend that users utilise a focus to hide behind for privacy, but
+instead use a TURN server, only providing relay candidates, rather than
+consuming focus resources and unnecessarily mandating the presence of a focus.
+
 ## Potential issues
 
 The SFUs participating in a conference end up in a full mesh. Rather than