From 71f5291a8f23fcba56fc819d0db7540c5c1eff46 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 10 Oct 2024 13:33:06 +0200 Subject: [PATCH 1/4] Sort VoIP events semantically Fixes: #937 Signed-off-by: Johannes Marbach --- data/event-schemas/schema/m.call.answer.yaml | 1 + .../schema/m.call.candidates.yaml | 1 + data/event-schemas/schema/m.call.hangup.yaml | 1 + data/event-schemas/schema/m.call.invite.yaml | 1 + .../schema/m.call.negotiate.yaml | 1 + data/event-schemas/schema/m.call.reject.yaml | 1 + .../m.call.sdp_stream_metadata_changed.yaml | 1 + .../schema/m.call.select_answer.yaml | 1 + layouts/shortcodes/event-group.html | 20 +++++++++++-------- 9 files changed, 20 insertions(+), 8 deletions(-) diff --git a/data/event-schemas/schema/m.call.answer.yaml b/data/event-schemas/schema/m.call.answer.yaml index 15e072020..f68ceea86 100644 --- a/data/event-schemas/schema/m.call.answer.yaml +++ b/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" }], diff --git a/data/event-schemas/schema/m.call.candidates.yaml b/data/event-schemas/schema/m.call.candidates.yaml index d43ede986..194cbda2d 100644 --- a/data/event-schemas/schema/m.call.candidates.yaml +++ b/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: diff --git a/data/event-schemas/schema/m.call.hangup.yaml b/data/event-schemas/schema/m.call.hangup.yaml index 0ca7fb655..46ae419a6 100644 --- a/data/event-schemas/schema/m.call.hangup.yaml +++ b/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: 70 allOf: - "$ref": core-event-schema/room_event.yaml properties: diff --git a/data/event-schemas/schema/m.call.invite.yaml b/data/event-schemas/schema/m.call.invite.yaml index c688d7b31..6b7818a64 100644 --- a/data/event-schemas/schema/m.call.invite.yaml +++ b/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" }], diff --git a/data/event-schemas/schema/m.call.negotiate.yaml b/data/event-schemas/schema/m.call.negotiate.yaml index e1a14f6f3..69216b444 100644 --- a/data/event-schemas/schema/m.call.negotiate.yaml +++ b/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: diff --git a/data/event-schemas/schema/m.call.reject.yaml b/data/event-schemas/schema/m.call.reject.yaml index d12a0b5c9..71379fb2e 100644 --- a/data/event-schemas/schema/m.call.reject.yaml +++ b/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: diff --git a/data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml b/data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml index 953817c2a..69e67eb17 100644 --- a/data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml +++ b/data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml @@ -1,5 +1,6 @@ type: object x-addedInMatrixVersion: "1.11" +x-weight: 60 description: |- This event is sent by callers when they wish to update a stream's metadata but no negotiation is required. diff --git a/data/event-schemas/schema/m.call.select_answer.yaml b/data/event-schemas/schema/m.call.select_answer.yaml index b47c1352b..fb16eddf9 100644 --- a/data/event-schemas/schema/m.call.select_answer.yaml +++ b/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" }], diff --git a/layouts/shortcodes/event-group.html b/layouts/shortcodes/event-group.html index ddaaf0946..536879532 100644 --- a/layouts/shortcodes/event-group.html +++ b/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 }} + {{ $events = $events | append (dict "event_name" $event_name "event_data" $event_data) }} + {{ end }} +{{ end }} - {{ $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 }} +{{/* Render the events sorted by x-weight or otherwise their event name */}} +{{ range sort $events "event_data.x-weight" "event_name" }} - {{ partial "events/render-event" (dict "event_name" $event_name "event_data" $event_data)}} + {{ $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 }} - {{ end }} + {{ partial "events/render-event" (dict "event_name" .event_name "event_data" $event_data)}} {{ end }} From aa3af365f6d26ee0b18f0928313c7d493e2015a8 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 10 Oct 2024 13:38:04 +0200 Subject: [PATCH 2/4] Add changelog --- changelogs/client_server/newsfragments/1967.clarification | 1 + changelogs/internal/newsfragments/1967.clarification | 1 + 2 files changed, 2 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1967.clarification create mode 100644 changelogs/internal/newsfragments/1967.clarification diff --git a/changelogs/client_server/newsfragments/1967.clarification b/changelogs/client_server/newsfragments/1967.clarification new file mode 100644 index 000000000..1b47b0685 --- /dev/null +++ b/changelogs/client_server/newsfragments/1967.clarification @@ -0,0 +1 @@ +Sort VoIP events semantically. diff --git a/changelogs/internal/newsfragments/1967.clarification b/changelogs/internal/newsfragments/1967.clarification new file mode 100644 index 000000000..9b86facac --- /dev/null +++ b/changelogs/internal/newsfragments/1967.clarification @@ -0,0 +1 @@ +Add `x-weight` property for sorting events rendered with the `event-group` shortcode. From 0f9668c06226c5485b3ab30a55f374fe28e5f047 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 14 Oct 2024 08:07:11 +0200 Subject: [PATCH 3/4] Document x-weight --- openapi_extensions.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/openapi_extensions.md b/openapi_extensions.md index e8fd1002a..017aaf7d4 100644 --- a/openapi_extensions.md +++ b/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. From 2b91e456e810c99fe9865adc39513649449abb2b Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 15 Oct 2024 08:43:56 +0200 Subject: [PATCH 4/4] Sort by weight only --- data/event-schemas/schema/m.call.hangup.yaml | 2 +- .../schema/m.call.sdp_stream_metadata_changed.yaml | 2 +- layouts/shortcodes/event-group.html | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/data/event-schemas/schema/m.call.hangup.yaml b/data/event-schemas/schema/m.call.hangup.yaml index 46ae419a6..94f77636f 100644 --- a/data/event-schemas/schema/m.call.hangup.yaml +++ b/data/event-schemas/schema/m.call.hangup.yaml @@ -21,7 +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: 70 +x-weight: 80 allOf: - "$ref": core-event-schema/room_event.yaml properties: diff --git a/data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml b/data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml index 69e67eb17..1ff2dca81 100644 --- a/data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml +++ b/data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml @@ -1,6 +1,6 @@ type: object x-addedInMatrixVersion: "1.11" -x-weight: 60 +x-weight: 70 description: |- This event is sent by callers when they wish to update a stream's metadata but no negotiation is required. diff --git a/layouts/shortcodes/event-group.html b/layouts/shortcodes/event-group.html index 536879532..7b80a964a 100644 --- a/layouts/shortcodes/event-group.html +++ b/layouts/shortcodes/event-group.html @@ -25,8 +25,8 @@ {{ end }} {{ end }} -{{/* Render the events sorted by x-weight or otherwise their event name */}} -{{ range sort $events "event_data.x-weight" "event_name" }} +{{/* 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) }}