Support sending and receiving MSC4354 Sticky Event metadata. #19365

reivilibre · 2026-01-09T16:36:23Z

Follows: #19340 (a necessary bugfix for /event/ to set this metadata)

Partially supersedes: #18968

This PR implements the first batch of work to support MSC4354 Sticky Events.

Sticky events are events that have been configured with a finite 'stickiness' duration,
capped to 1 hour per current MSC draft.

Whilst an event is sticky, we provide stronger delivery guarantees for the event, both to
our clients and to remote homeservers, essentially making it reliable delivery as long as we
have a functional connection to the client/server and until the stickiness expires.

This PR merely supports creating sticky events and receiving the sticky TTL metadata in clients.
It is not suitable for trialling sticky events since none of the other semantics are implemented.

The current plan is to follow this PR up with more PRs, roughly parcelled up as follows:

Implement the sliding sync extension specified in MSC4354, to proactively notify
Implement the oldschool sync support, specified in MSC4354, to do the same but for clients still using oldschool sync.
Notice new servers joining rooms and proactively tell them about sticky events.
Add special federation catch-up support for sticky events, so that (as long as we have a connection) they don't get 'dropped' in the gaps between federation /send requests.
Re-evaluate soft-failed sticky events when we think that might be possible

Add MSC4354 experimental feature flag
Expose MSC4354 enablement on /versions
Add constants for sticky events
Add sticky_events table
Add sticky events store and stream
EventBase: add the concept of sticky_duration
EventBuilder: allow building events with sticky event fields
store method: insert_sticky_events_txn
When persisting currently-sticky events, add to sticky event stream
Allow clients to send sticky events
Including delayed events
Add test helper for sending sticky events
Expose the sticky event TTL to clients
Add a test for sticky TTL calculation and exposure to clients

Including delayed events

Signed-off-by: Olivier 'reivilibre <oliverw@matrix.org>

synapse/api/constants.py

MadLittleMods · 2026-01-22T16:20:28Z

synapse/api/constants.py

+
+class StickyEvent:
+    QUERY_PARAM_NAME: Final = "org.matrix.msc4354.sticky_duration_ms"
+    FIELD_NAME: Final = "msc4354_sticky"


Suggested change

FIELD_NAME: Final = "msc4354_sticky"

EVENT_FIELD_NAME: Final = "msc4354_sticky"

MadLittleMods · 2026-01-22T16:21:29Z

synapse/api/constants.py

+    Maximum stickiness duration as specified in MSC4354.
+    Ensures that data in the /sync response can go down and not grow unbounded.
+    """
+    MAX_EVENTS_IN_SYNC: Final = 100


Why 100? (we should explain in the attribute docstring)

(also not used yet)

MadLittleMods · 2026-01-22T16:24:28Z

synapse/api/constants.py

+
+
+class StickyEvent:
+    QUERY_PARAM_NAME: Final = "org.matrix.msc4354.sticky_duration_ms"


We should explain what endpoint this applies to

MadLittleMods · 2026-01-22T16:28:03Z

synapse/api/constants.py

+
+class StickyEvent:
+    QUERY_PARAM_NAME: Final = "org.matrix.msc4354.sticky_duration_ms"
+    FIELD_NAME: Final = "msc4354_sticky"


The separation between StickyEventField and StickyEvent.FIELD_NAME is slightly mind bending.

MadLittleMods · 2026-01-22T18:17:23Z

synapse/storage/databases/main/events.py

+                if self._msc4354_enabled and event.sticky_duration():
+                    # The de-outliered event is sticky. Update the sticky events table to ensure
+                    # we deliver this down /sync.
+                    self.store.insert_sticky_events_txn(txn, [event])


Are we going to give up on events that were valid sticky events sent within the hour but before msc4354_enabled?

Seems like a fine trade-off but we should at-least comment about it.

Hmm. Didn't consider that, not too worried about it, but on the other hand we could track sticky events even if we don't deliver them, whilst the feature is turned off.

Thoughts overall?

No specific thoughts. Both have tradeoffs. With the current setup, you can completely turn the feature off and I think it's pretty acceptable to drop them on the floor since this an hour window max. But it could also just make more sense for things to behave the same.

For things like the Sliding Sync feature, we had to think about this a lot harder as there was no time limit.

MadLittleMods · 2026-01-22T18:22:12Z

synapse/handlers/delayed_events.py

+                    event_dict[StickyEvent.FIELD_NAME] = {
+                        "duration_ms": event.sticky_duration_ms,
+                    }


Seems like we should re-use StickyEventField here

(applies to other places)

MadLittleMods · 2026-01-22T18:25:38Z

tests/rest/client/test_sticky_events.py

+            f"{EventUnsignedContentFields.STICKY_TTL} field unexpectedly found in {event_id}: {event}",
+        )
+
+    def test_sticky_event_via_event_endpoint(self) -> None:


We should also have a test for when a sticky event is sent but msc4354_enabled: False

MadLittleMods · 2026-01-22T18:30:04Z

synapse/storage/databases/main/delayed_events.py

 @attr.s(slots=True, frozen=True, auto_attribs=True)
 class EventDetails:
    room_id: RoomID
    type: EventType
    state_key: StateKey | None
    origin_server_ts: Timestamp | None
    content: JsonDict
    device_id: DeviceID | None
+    sticky_duration_ms: int | None


 @attr.s(slots=True, frozen=True, auto_attribs=True)
 class DelayedEventDetails(EventDetails):
    delay_id: DelayID
    user_localpart: UserLocalpart


I haven't looked into the details but should we have a similarly named StickyEventDetails that includes sticky_duration_ms instead of in EventDetails

I think this is purely tracking the sticky duration so that when we send the delayed event, we can mark it as sticky at that time.

Interestingly DelayedEventDetails inherits from EventDetails but there are no standalone usage of EventDetails.

I guess the idea was just to compartmentalise 'this is information for sending the event' and 'this is the information for scheduling it', then again I don't know why the user localpart ( = sender ?) is stored on the delayed event side then.

Anyway, to me it seems reasonable to have it be part of the event details themselves. If we had StickyEventDetails in addition, DelayedEventDetails would have to inherit from that and I don't think the extra layer would help us with anything. (maybe I'm missing something from this design though)

tests/rest/client/utils.py

Co-authored-by: Eric Eastwood <erice@element.io>

reivilibre requested a review from a team as a code owner January 9, 2026 16:36

reivilibre changed the title ~~Support sending and receiving [MSC4354 Sticky Event](https://github.com/matrix-org/matrix-spec-proposals/pull/4354) metadata.~~ Support sending and receiving MSC4354 Sticky Event metadata. Jan 9, 2026

reivilibre force-pushed the rei/sticky_events1 branch from 2b83332 to 53d4486 Compare January 9, 2026 16:43

reivilibre added 3 commits January 12, 2026 12:09

Add MSC4354 experimental feature flag

aaa229f

Expose MSC4354 enablement on /versions

a25a5b5

Add constants for sticky events

7abcf6d

reivilibre force-pushed the rei/sticky_events1 branch 2 times, most recently from e49d4bd to 78ee6e8 Compare January 16, 2026 09:00

reivilibre added 11 commits January 16, 2026 09:07

Add sticky_events table

c2d4cf4

Add sticky events store and stream

ec5f2f8

EventBase: add the concept of sticky_duration

003fe1f

EventBuilder: allow building events with sticky event fields

c7075d6

store method: insert_sticky_events_txn

0a4f7e6

When persisting currently-sticky events, add to sticky event stream

53e4968

Allow clients to send sticky events

137c457

Including delayed events

Add test helper for sending sticky events

90e9539

Expose the sticky event TTL to clients

9a0b28e

Add a test for sticky TTL calculation and exposure to clients

b41ef41

Newsfile

fb67e9a

Signed-off-by: Olivier 'reivilibre <oliverw@matrix.org>

reivilibre force-pushed the rei/sticky_events1 branch from 78ee6e8 to fb67e9a Compare January 16, 2026 09:07

MadLittleMods reviewed Jan 22, 2026

View reviewed changes

reivilibre and others added 3 commits January 22, 2026 20:19

Use Duration

383d97c

Tweak comment on SQL column

47306d2

Update synapse/config/workers.py

beead8a

Co-authored-by: Eric Eastwood <erice@element.io>

reivilibre force-pushed the rei/sticky_events1 branch from 1c2a9ad to beead8a Compare January 22, 2026 20:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Support sending and receiving MSC4354 Sticky Event metadata. #19365

Support sending and receiving MSC4354 Sticky Event metadata. #19365

Uh oh!

reivilibre commented Jan 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

MadLittleMods Jan 22, 2026

Uh oh!

MadLittleMods Jan 22, 2026

Uh oh!

MadLittleMods Jan 22, 2026

Uh oh!

MadLittleMods Jan 22, 2026

Uh oh!

MadLittleMods Jan 22, 2026

Uh oh!

reivilibre Jan 22, 2026

Uh oh!

MadLittleMods Jan 22, 2026

Uh oh!

MadLittleMods Jan 22, 2026

Uh oh!

MadLittleMods Jan 22, 2026

Uh oh!

MadLittleMods Jan 22, 2026

Uh oh!

reivilibre Jan 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	FIELD_NAME: Final = "msc4354_sticky"
	EVENT_FIELD_NAME: Final = "msc4354_sticky"



		class StickyEvent:
		QUERY_PARAM_NAME: Final = "org.matrix.msc4354.sticky_duration_ms"

Support sending and receiving MSC4354 Sticky Event metadata. #19365

Are you sure you want to change the base?

Support sending and receiving MSC4354 Sticky Event metadata. #19365

Uh oh!

Conversation

reivilibre commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

reivilibre commented Jan 9, 2026 •

edited

Loading