MatrixRTC: Support the optional leave_reason in rtc membership content by BillCarsonFr · Pull Request #5437 · matrix-org/matrix-js-sdk

BillCarsonFr · 2026-07-21T08:45:34Z

Adds support for leave_reason as per MSC4143

Breaking change:

Leave event has now a leave_reason optional key instead of enpty
Previously for leaving the membership manager was just firing the scheduled leave, now we are cancelling it, then we send a proper leave event with the reason

Checklist

Tests written for new code (and old code if feasible).
New or updated public/exported symbols have accurate TSDoc documentation.
Linter and other CI checks pass.
Sign-off given on the changes (see CONTRIBUTING.md).

Johennes

Overall looks good. Just some details.

Copilot

Pull request overview

This PR adds MSC4143 leave_reason support to MatrixRTC membership leave flows, propagating an optional structured leave reason through the public session API and membership manager, and updating event typings and unit tests accordingly.

Changes:

Introduces LeaveReason / leave_reason types and constants, and includes leave_reason in leave and delayed-leave event content.
Updates the membership action scheduler/manager to send an explicit leave event (optionally with reason) and cancel any scheduled delayed leave.
Extends event type mappings and updates unit tests to validate the new leave behavior.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/matrixrtc/types.ts	Adds `LeaveReason` types/constants and leave event content shape.
src/matrixrtc/MembershipManagerActionScheduler.ts	Threads leave-reason action data through the scheduler and triggers cancel+leave actions.
src/matrixrtc/MembershipManager.ts	Implements sending `{ leave_reason }`, cancels scheduled delayed leave, and updates action/data plumbing.
src/matrixrtc/MatrixRTCSession.ts	Exposes `leaveReason` through `leaveRoomSession` and filters leave-only events.
src/matrixrtc/index.ts	Re-exports selected leave-reason constants from the public entrypoint.
src/matrixrtc/IMembershipManager.ts	Extends the public `leave()` API with an optional leave reason.
src/@types/event.ts	Updates event content typings to permit `leave_reason`.
spec/unit/matrixrtc/MembershipManager.spec.ts	Updates/adds tests for cancel + explicit leave event behavior and content.

Comments suppressed due to low confidence (1)

src/matrixrtc/types.ts:248

The LEAVE_REASON_DELAYED constant uses code "delayed_leaved", but MSC4143 specifies the generic code as "delayed_leave". This should match the LeaveCode union and the spec value for wire compatibility.

export const LEAVE_REASON_DELAYED: LeaveReason = {
    code: "delayed_leaved",
    reason: "The user was removed due to inactivity (no heartbeat received).",

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

dbkr

Mostly looks fine but you've said 'feat' in the PR title but 'task' in the label. It sounds like an enhancement (we use the labels instead of conventional commits because our PR titles go in the changelog).

OOO

robintown · 2026-08-03T08:44:37Z

+/** The member left intentionally (e.g. by hanging up a call) */
+export const LEAVE_REASON_HANGUP: LeaveReason = {
+    code: "leave",
+    reason: "The member left intentionally (e.g. by hanging up a call).",


It feels a little funny to have a user-facing string that's nonspecific about the type of application. I would rather omit the reasons in this file and (ideally) instead have them passed to the membership manager by the application's code.

robintown · 2026-08-03T08:54:39Z

    [M_POLL_START.name]: PollStartEventContent;
    [M_POLL_END.name]: PollEndEventContent;
-    [EventType.RTCMembership]: RtcMembershipData | { msc4354_sticky_key: string }; // An object containing just the sticky key is empty.
+    [EventType.RTCMembership]: RtcMembershipData | { msc4354_sticky_key: string; leave_reason?: LeaveReason };


Shouldn't there be more properties in this variant, like slot_id and member?

robintown · 2026-08-03T08:57:51Z

+        | SessionMembershipData
+        | LeaveMembershipEventContent
+        | EmptyObject;
    [EventType.RTCMembership]: RtcMembershipData | EmptyObject;


By the way, should this state event type still exist? (If so, should it also get a LeaveMembershipEventContent variant?)

robintown · 2026-08-03T09:00:34Z

+        | LeaveMembershipEventContent
+        | EmptyObject;


The EmptyObject variant is redundant to the LeaveMembershipEventContent variant, since that interface also admits an empty object

robintown · 2026-08-03T09:03:35Z

    const eventKeysCount = Object.keys(content).filter((k) => k !== "msc4354_sticky_key").length;
    // Don't even bother about empty events (saves us from costly type/"key in" checks in bigger rooms)
-    if (eventKeysCount === 0) return false;
+    if (eventKeysCount === 0 || (eventKeysCount === 1 && "leave_reason" in content)) return false;


Suggested change

if (eventKeysCount === 0 || (eventKeysCount === 1 && "leave_reason" in content)) return false;

if (eventKeysCount === 0 || "leave_reason" in content) return false;

To account for the other keys that can be part of a leave membership (slot_id etc.)

robintown · 2026-08-03T09:05:38Z

+    /**
+     * Additional parameters of the action
+     */
+    data?: MembershipActionData[MembershipActionType];


Suggested change

data?: MembershipActionData[MembershipActionType];

data: MembershipActionData[MembershipActionType];

Seems reasonable to require the data when it's specified for an action type

robintown · 2026-08-03T09:13:22Z

+            replace: [
+                {
+                    ts: Date.now(),
+                    type: MembershipActionType.SendLeaveEvent,
+                    data: leaveReason ? { leaveReason } : undefined,
+                },
+                {
+                    ts: Date.now(),
+                    type: MembershipActionType.CancelledScheduledDelayedLeaveEvent,
+                },
+            ],


I am glad to see that this is sending the leave event before canceling, since that's presumably a better way of dealing with the lack of atomicity in this operation. But ideally, the membership manager would only cancel the delayed event in step 2 if it actually succeeds at sending the leave event in step 1. Do you see any way to make the machine do that?

robintown · 2026-08-03T09:16:44Z

-        this.clientWithSticky._unstable_sendStickyDelayedEvent(
+    protected clientSendDelayedDisconnectMembership: () => Promise<SendDelayedEventResponse> = () => {
+        this.logger.debug(
+            `StickyMembershipManager send delayed disconnect membership event memberId: ${this.memberId}`,


Suggested change

`StickyMembershipManager send delayed disconnect membership event memberId: ${this.memberId}`,

`send delayed disconnect membership event memberId: ${this.memberId}`,

(It's already prefixed)

BillCarsonFr added the T-Task Tasks for the team like planning label Jul 21, 2026

github-actions Bot deployed to PR Documentation Preview July 21, 2026 08:46 View deployment

feat(rtc): Add support for leave_reason in rtc membership

92707b2

BillCarsonFr force-pushed the valere/rtc/leave_reason branch from 2456592 to 92707b2 Compare July 21, 2026 12:02

github-actions Bot deployed to PR Documentation Preview July 21, 2026 12:03 View deployment

BillCarsonFr marked this pull request as ready for review July 21, 2026 13:39

BillCarsonFr requested review from a team as code owners July 21, 2026 13:39

BillCarsonFr requested review from AndrewFerr, MidhunSureshR and dbkr July 21, 2026 13:39

Johennes previously requested changes Jul 21, 2026

View reviewed changes

Comment thread src/matrixrtc/MembershipManager.ts Outdated

Comment thread src/matrixrtc/MembershipManager.ts Outdated

Comment thread src/matrixrtc/types.ts

Comment thread src/matrixrtc/MembershipManagerActionScheduler.ts

Johennes mentioned this pull request Jul 24, 2026

MSC4143: MatrixRTC – Real-time communication over Matrix matrix-org/matrix-spec-proposals#4143

Open

5 tasks

BillCarsonFr added 2 commits July 27, 2026 14:37

review: Update leave reason as per MSC

c287dd9

review: first leave then cancel delayed event

5483987

github-actions Bot deployed to PR Documentation Preview July 27, 2026 12:38 View deployment

BillCarsonFr requested review from Copilot and robintown and removed request for AndrewFerr July 27, 2026 12:40

Copilot started reviewing on behalf of BillCarsonFr July 27, 2026 12:40 View session

Merge branch 'develop' into valere/rtc/leave_reason

bc0e6de

github-actions Bot deployed to PR Documentation Preview July 27, 2026 12:42 View deployment

Copilot AI reviewed Jul 27, 2026

View reviewed changes

Comment thread src/matrixrtc/types.ts Outdated

Comment thread src/matrixrtc/MembershipManager.ts Outdated

Comment thread src/matrixrtc/MembershipManager.ts Outdated

Comment thread src/matrixrtc/MatrixRTCSession.ts

Comment thread src/@types/event.ts Outdated

Comment thread src/matrixrtc/index.ts

BillCarsonFr added 2 commits July 28, 2026 09:33

fix typo in leave reason

73085f8

code review

9f7cad4

github-actions Bot deployed to PR Documentation Preview July 28, 2026 07:47 View deployment

Merge branch 'develop' into valere/rtc/leave_reason

1124286

github-actions Bot deployed to PR Documentation Preview July 28, 2026 08:02 View deployment

BillCarsonFr requested a review from Johennes July 28, 2026 08:04

Merge branch 'develop' into valere/rtc/leave_reason

805f766

github-actions Bot deployed to PR Documentation Preview July 29, 2026 12:39 View deployment

dbkr reviewed Jul 30, 2026

View reviewed changes

Comment thread src/matrixrtc/types.ts

Comment thread src/matrixrtc/MembershipManagerActionScheduler.ts Outdated

Comment thread src/matrixrtc/MatrixRTCSession.ts Outdated

code review

80f56fd

BillCarsonFr added T-Enhancement and removed T-Task Tasks for the team like planning labels Jul 30, 2026

BillCarsonFr changed the title ~~feat(rtc): Add support for leave_reason in rtc membership~~ MatrixRTC: Support the optional leave_reason in rtc membership content Jul 30, 2026

Merge branch 'develop' into valere/rtc/leave_reason

61d472a

BillCarsonFr requested a review from dbkr July 30, 2026 13:35

dbkr approved these changes Jul 31, 2026

View reviewed changes

BillCarsonFr added 3 commits July 31, 2026 15:30

fix linter / format

ca54296

Merge branch 'develop' into valere/rtc/leave_reason

0511cb2

lint fix

bcba2db

github-actions Bot deployed to PR Documentation Preview August 1, 2026 17:57 View deployment

BillCarsonFr enabled auto-merge August 2, 2026 08:55

robintown reviewed Aug 3, 2026

View reviewed changes

	if (eventKeysCount === 0 \|\| (eventKeysCount === 1 && "leave_reason" in content)) return false;
	if (eventKeysCount === 0 \|\| "leave_reason" in content) return false;

	data?: MembershipActionData[MembershipActionType];
	data: MembershipActionData[MembershipActionType];

	`StickyMembershipManager send delayed disconnect membership event memberId: ${this.memberId}`,
	`send delayed disconnect membership event memberId: ${this.memberId}`,

Uh oh!

Uh oh!

Conversation

BillCarsonFr commented Jul 21, 2026

Checklist

Uh oh!

Johennes left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dbkr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants