Sort VoIP events semantically (#1967)

changelogs/client_server/newsfragments/1967.clarification

@@ -0,0 +1 @@
+Sort VoIP events semantically.

changelogs/internal/newsfragments/1967.clarification

@@ -0,0 +1 @@
+Add `x-weight` property for sorting events rendered with the `event-group` shortcode.

data/event-schemas/schema/m.call.answer.yaml

@@ -1,6 +1,7 @@
 {
     "type": "object",
     "description": "This event is sent by the callee when they wish to answer the call.",
+    "x-weight": 40,
     "allOf": [{
         "$ref": "core-event-schema/room_event.yaml"
     }],

data/event-schemas/schema/m.call.candidates.yaml

@@ -3,6 +3,7 @@ description: |-
   This event is sent by callers after sending an invite and by the callee after
   answering. Its purpose is to give the other party additional ICE candidates to
   try using to communicate.
+x-weight: 20
 allOf:
   - $ref: core-event-schema/room_event.yaml
 properties:

data/event-schemas/schema/m.call.hangup.yaml

@@ -21,6 +21,7 @@ description: |
       the new call unless the user had specifically chosen to do so.
    * `unknown_error`: Some other failure occurred that meant the client was unable to continue the call
       rather than the user choosing to end it.
+x-weight: 80
 allOf:
 - "$ref": core-event-schema/room_event.yaml
 properties:

data/event-schemas/schema/m.call.invite.yaml

@@ -1,6 +1,7 @@
 {
     "type": "object",
     "description": "This event is sent by the caller when they wish to establish a call.",
+    "x-weight": 10,
     "allOf": [{
         "$ref": "core-event-schema/room_event.yaml"
     }],

data/event-schemas/schema/m.call.negotiate.yaml

@@ -34,6 +34,7 @@ description: |
   attempt to validate the `type` field, but simply pass the object into the
   WebRTC API.
 x-addedInMatrixVersion: "1.7"
+x-weight: 60
 allOf:
 - "$ref": core-event-schema/room_event.yaml
 properties:

data/event-schemas/schema/m.call.reject.yaml

@@ -14,6 +14,7 @@ description: |
   Note that, unlike `m.call.hangup`, this event has no `reason` field: the rejection of
   a call is always implicitly because the user chose not to answer it.
 x-addedInMatrixVersion: "1.7"
+x-weight: 30
 allOf:
 - "$ref": core-event-schema/room_event.yaml
 properties:

data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml

@@ -1,5 +1,6 @@
 type: object
 x-addedInMatrixVersion: "1.11"
+x-weight: 70
 description: |-
   This event is sent by callers when they wish to update a stream's metadata
   but no negotiation is required.

data/event-schemas/schema/m.call.select_answer.yaml

@@ -2,6 +2,7 @@
     "type": "object",
     "description": "This event is sent by the caller's client once it has decided which other client to talk to, by selecting one of multiple possible incoming `m.call.answer` events. Its `selected_party_id` field indicates the answer it's chosen. The `call_id` and `party_id` of the caller is also included. If the callee's client sees a `select_answer` for an answer with party ID other than the one it sent, it ends the call and informs the user the call was answered elsewhere. It does not send any events. Media can start flowing before this event is seen or even sent.  Clients that implement previous versions of this specification will ignore this event and behave as they did before.",
     "x-addedInMatrixVersion": "1.7",
+    "x-weight": 50,
     "allOf": [{
         "$ref": "core-event-schema/room_event.yaml"
     }],

layouts/shortcodes/event-group.html

@@ -14,20 +14,24 @@
 
 {{ $base_path := "event-schemas/schema" }}
 
-{{ $events := index .Site.Data "event-schemas" "schema" }}
 {{ $group_name := .Params.group_name }}
 
-{{ range $event_name, $event_data := $events }}
-
+{{/* Filter events and prepare them for sorting */}}
+{{ $events := slice }}
+{{ range $event_name, $event_data := index .Site.Data "event-schemas" "schema" }}
     {{ $prefix := substr $event_name 0 (len $group_name) }}
     {{ if eq $prefix $group_name }}
-
-        {{ $path := delimit (slice $base_path $event_name) "/" }}
-        {{ $event_data = partial "json-schema/resolve-refs" (dict "schema" $event_data "path" $path) }}
-        {{ $event_data := partial "json-schema/resolve-allof" $event_data }}
-
-        {{ partial "events/render-event" (dict "event_name" $event_name "event_data" $event_data)}}
-
+        {{ $events = $events | append (dict "event_name" $event_name "event_data" $event_data) }}
     {{ end }}
+{{ end }}
+
+{{/* Render the events sorted by x-weight */}}
+{{ range sort $events "event_data.x-weight" }}
+
+    {{ $path := delimit (slice $base_path .event_name) "/" }}
+    {{ $event_data := partial "json-schema/resolve-refs" (dict "schema" .event_data "path" $path) }}
+    {{ $event_data := partial "json-schema/resolve-allof" $event_data }}
+
+    {{ partial "events/render-event" (dict "event_name" .event_name "event_data" $event_data)}}
 
 {{ end }}

openapi_extensions.md

@@ -41,3 +41,8 @@ same use as `format`, but that applies to the pattern of the property. We also
 define custom values for formats with the `mx-` prefix in
 `data/custom-formats.yaml`. Those values are recognized in the rendered
 specification and link to the definition of the format.
+
+## Custom `x-weight` key
+
+This property allows controlling the display order of events rendered with the
+`event-group` shortcode.