Implement Sticky Events MSC4354

spec/unit/models/event.spec.ts

@@ -20,6 +20,7 @@ import { type IContent, MatrixEvent, MatrixEventEvent } from "../../../src/model
 import { emitPromise } from "../../test-utils/test-utils";
 import {
     type IAnnotatedPushRule,
+    type IStickyEvent,
     type MatrixClient,
     PushRuleActionName,
     Room,
@@ -598,6 +599,34 @@ describe("MatrixEvent", () => {
         expect(stateEvent.isState()).toBeTruthy();
         expect(stateEvent.threadRootId).toBeUndefined();
     });
+
+    it("should calculate sticky duration correctly", async () => {
+        const evData: IStickyEvent = {
+            event_id: "$event_id",
+            type: "some_state_event",
+            content: {},
+            sender: "@alice:example.org",
+            origin_server_ts: 50,
+            msc4354_sticky: {
+                duration_ms: 1000,
+            },
+            unsigned: {
+                msc4354_sticky_duration_ttl_ms: 5000,
+            },
+        };
+        try {
+            jest.useFakeTimers();
+            jest.setSystemTime(0);
+            // Prefer unsigned
+            expect(new MatrixEvent({ ...evData } satisfies IStickyEvent).unstableStickyExpiresAt).toEqual(5000);
+            // Fall back to `duration_ms`
+            expect(
+                new MatrixEvent({ ...evData, unsigned: undefined } satisfies IStickyEvent).unstableStickyExpiresAt,
+            ).toEqual(1050);
+        } finally {
+            jest.useRealTimers();
+        }
+    });
 });
 
 function mainTimelineLiveEventIds(room: Room): Array<string> {

spec/unit/models/room-sticky-events.spec.ts

@@ -0,0 +1,259 @@
+import { type IStickyEvent, MatrixEvent } from "../../../src";
+import { RoomStickyEventsStore, RoomStickyEventsEvent } from "../../../src/models/room-sticky-events";
+
+describe("RoomStickyEvents", () => {
+    let stickyEvents: RoomStickyEventsStore;
+    const stickyEvent: IStickyEvent = {
+        event_id: "$foo:bar",
+        room_id: "!roomId",
+        type: "org.example.any_type",
+        msc4354_sticky: {
+            duration_ms: 15000,
+        },
+        content: {
+            msc4354_sticky_key: "foobar",
+        },
+        sender: "@alice:example.org",
+        origin_server_ts: Date.now(),
+        unsigned: {},
+    };
+
+    beforeEach(() => {
+        stickyEvents = new RoomStickyEventsStore();
+    });
+
+    afterEach(() => {
+        stickyEvents?.clear();
+    });
+
+    describe("addStickyEvents", () => {
+        it("should allow adding an event without a msc4354_sticky_key", () => {
+            stickyEvents.addStickyEvents([new MatrixEvent({ ...stickyEvent, content: {} })]);
+            expect([...stickyEvents.getStickyEvents()]).toHaveLength(1);
+        });
+        it("should not allow adding an event without a msc4354_sticky property", () => {
+            stickyEvents.addStickyEvents([new MatrixEvent({ ...stickyEvent, msc4354_sticky: undefined })]);
+            expect([...stickyEvents.getStickyEvents()]).toHaveLength(0);
+            stickyEvents.addStickyEvents([
+                new MatrixEvent({ ...stickyEvent, msc4354_sticky: { duration_ms: undefined } as any }),
+            ]);
+            expect([...stickyEvents.getStickyEvents()]).toHaveLength(0);
+        });
+        it("should not allow adding an event without a sender", () => {
+            stickyEvents.addStickyEvents([new MatrixEvent({ ...stickyEvent, sender: undefined })]);
+            expect([...stickyEvents.getStickyEvents()]).toHaveLength(0);
+        });
+        it("should not allow adding an event with an invalid sender", () => {
+            stickyEvents.addStickyEvents([new MatrixEvent({ ...stickyEvent, sender: "not_a_real_sender" })]);
+            expect([...stickyEvents.getStickyEvents()]).toHaveLength(0);
+        });
+        it("should ignore old events", () => {
+            stickyEvents.addStickyEvents([
+                new MatrixEvent({ ...stickyEvent, origin_server_ts: 0, msc4354_sticky: { duration_ms: 1 } }),
+            ]);
+            expect([...stickyEvents.getStickyEvents()]).toHaveLength(0);
+        });
+        it("should be able to just add an event", () => {
+            const originalEv = new MatrixEvent({ ...stickyEvent });
+            stickyEvents.addStickyEvents([originalEv]);
+            expect([...stickyEvents.getStickyEvents()]).toEqual([originalEv]);
+        });
+        it("should not replace events on ID tie break", () => {
+            const originalEv = new MatrixEvent({ ...stickyEvent });
+            stickyEvents.addStickyEvents([originalEv]);
+            stickyEvents.addStickyEvents([
+                new MatrixEvent({
+                    ...stickyEvent,
+                    event_id: "$abc:bar",
+                }),
+            ]);
+            expect([...stickyEvents.getStickyEvents()]).toEqual([originalEv]);
+        });
+        it("should not replace a newer event with an older event", () => {
+            const originalEv = new MatrixEvent({ ...stickyEvent });
+            stickyEvents.addStickyEvents([originalEv]);
+            stickyEvents.addStickyEvents([
+                new MatrixEvent({
+                    ...stickyEvent,
+                    origin_server_ts: 1,
+                }),
+            ]);
+            expect([...stickyEvents.getStickyEvents()]).toEqual([originalEv]);
+        });
+        it("should replace an older event with a newer event", () => {
+            const originalEv = new MatrixEvent({ ...stickyEvent });
+            const newerEv = new MatrixEvent({
+                ...stickyEvent,
+                origin_server_ts: Date.now() + 2000,
+            });
+            stickyEvents.addStickyEvents([originalEv]);
+            stickyEvents.addStickyEvents([newerEv]);
+            expect([...stickyEvents.getStickyEvents()]).toEqual([newerEv]);
+        });
+        it("should allow multiple events with the same sticky key for different event types", () => {
+            const originalEv = new MatrixEvent({ ...stickyEvent });
+            const anotherEv = new MatrixEvent({
+                ...stickyEvent,
+                type: "org.example.another_type",
+            });
+            stickyEvents.addStickyEvents([originalEv, anotherEv]);
+            expect([...stickyEvents.getStickyEvents()]).toEqual([originalEv, anotherEv]);
+        });
+
+        it("should emit when a new sticky event is added", () => {
+            const emitSpy = jest.fn();
+            stickyEvents.on(RoomStickyEventsEvent.Update, emitSpy);
+            const ev = new MatrixEvent({
+                ...stickyEvent,
+            });
+            stickyEvents.addStickyEvents([ev]);
+            expect([...stickyEvents.getStickyEvents()]).toEqual([ev]);
+            expect(emitSpy).toHaveBeenCalledWith([ev], []);
+        });
+        it("should emit when a new unkeyed sticky event is added", () => {
+            const emitSpy = jest.fn();
+            stickyEvents.on(RoomStickyEventsEvent.Update, emitSpy);
+            const ev = new MatrixEvent({
+                ...stickyEvent,
+                content: {},
+            });
+            stickyEvents.addStickyEvents([ev]);
+            expect([...stickyEvents.getStickyEvents()]).toEqual([ev]);
+            expect(emitSpy).toHaveBeenCalledWith([ev], []);
+        });
+    });
+
+    describe("getStickyEvents", () => {
+        it("should have zero sticky events", () => {
+            expect([...stickyEvents.getStickyEvents()]).toHaveLength(0);
+        });
+        it("should contain a sticky event", () => {
+            const ev = new MatrixEvent({
+                ...stickyEvent,
+            });
+            stickyEvents.addStickyEvents([ev]);
+            expect([...stickyEvents.getStickyEvents()]).toEqual([ev]);
+        });
+        it("should contain two sticky events", () => {
+            const ev = new MatrixEvent({
+                ...stickyEvent,
+            });
+            const ev2 = new MatrixEvent({
+                ...stickyEvent,
+                sender: "@fibble:bobble",
+                content: {
+                    msc4354_sticky_key: "bibble",
+                },
+            });
+            stickyEvents.addStickyEvents([ev, ev2]);
+            expect([...stickyEvents.getStickyEvents()]).toEqual([ev, ev2]);
+        });
+    });
+
+    describe("getKeyedStickyEvent", () => {
+        it("should have zero sticky events", () => {
+            expect(
+                stickyEvents.getKeyedStickyEvent(
+                    stickyEvent.sender,
+                    stickyEvent.type,
+                    stickyEvent.content.msc4354_sticky_key!,
+                ),
+            ).toBeUndefined();
+        });
+        it("should return a sticky event", () => {
+            const ev = new MatrixEvent({
+                ...stickyEvent,
+            });
+            stickyEvents.addStickyEvents([ev]);
+            expect(
+                stickyEvents.getKeyedStickyEvent(
+                    stickyEvent.sender,
+                    stickyEvent.type,
+                    stickyEvent.content.msc4354_sticky_key!,
+                ),
+            ).toEqual(ev);
+        });
+    });
+
+    describe("getUnkeyedStickyEvent", () => {
+        it("should have zero sticky events", () => {
+            expect(stickyEvents.getUnkeyedStickyEvent(stickyEvent.sender, stickyEvent.type)).toEqual([]);
+        });
+        it("should return a sticky event", () => {
+            const ev = new MatrixEvent({
+                ...stickyEvent,
+                content: {
+                    msc4354_sticky_key: undefined,
+                },
+            });
+            stickyEvents.addStickyEvents([ev]);
+            expect(stickyEvents.getUnkeyedStickyEvent(stickyEvent.sender, stickyEvent.type)).toEqual([ev]);
+        });
+    });
+
+    describe("cleanExpiredStickyEvents", () => {
+        beforeAll(() => {
+            jest.useFakeTimers();
+        });
+        afterAll(() => {
+            jest.useRealTimers();
+        });
+
+        it("should emit when a sticky event expires", () => {
+            jest.setSystemTime(0);
+            const ev = new MatrixEvent({
+                ...stickyEvent,
+                origin_server_ts: Date.now(),
+            });
+            const evLater = new MatrixEvent({
+                ...stickyEvent,
+                event_id: "$baz:bar",
+                sender: "@bob:example.org",
+                origin_server_ts: Date.now() + 1000,
+            });
+            stickyEvents.addStickyEvents([ev, evLater]);
+            const emitSpy = jest.fn();
+            stickyEvents.on(RoomStickyEventsEvent.Update, emitSpy);
+            jest.advanceTimersByTime(15000);
+            expect(emitSpy).toHaveBeenCalledWith([], [ev]);
+            // Then expire the next event
+            jest.advanceTimersByTime(1000);
+            expect(emitSpy).toHaveBeenCalledWith([], [evLater]);
+        });
+        it("should emit two events when both expire at the same time", () => {
+            const emitSpy = jest.fn();
+            stickyEvents.on(RoomStickyEventsEvent.Update, emitSpy);
+            jest.setSystemTime(0);
+            const ev1 = new MatrixEvent({
+                ...stickyEvent,
+                event_id: "$eventA",
+                origin_server_ts: 0,
+            });
+            const ev2 = new MatrixEvent({
+                ...stickyEvent,
+                event_id: "$eventB",
+                content: {
+                    msc4354_sticky_key: "key_2",
+                },
+                origin_server_ts: 0,
+            });
+            stickyEvents.addStickyEvents([ev1, ev2]);
+            expect(emitSpy).toHaveBeenCalledWith([ev1, ev2], []);
+            jest.advanceTimersByTime(15000);
+            expect(emitSpy).toHaveBeenCalledWith([], [ev1, ev2]);
+        });
+        it("should emit when a unkeyed sticky event expires", () => {
+            const emitSpy = jest.fn();
+            stickyEvents.on(RoomStickyEventsEvent.Update, emitSpy);
+            jest.setSystemTime(0);
+            const ev = new MatrixEvent({
+                ...stickyEvent,
+                content: {},
+                origin_server_ts: Date.now(),
+            });
+            stickyEvents.addStickyEvents([ev]);
+            jest.advanceTimersByTime(15000);
+            expect(emitSpy).toHaveBeenCalledWith([], [ev]);
+        });
+    });
+});

spec/unit/sync-accumulator.spec.ts

@@ -26,6 +26,7 @@ import {
     type ILeftRoom,
     type IRoomEvent,
     type IStateEvent,
+    type IStickyEvent,
     type IStrippedState,
     type ISyncResponse,
     SyncAccumulator,
@@ -1067,6 +1068,55 @@ describe("SyncAccumulator", function () {
             );
         });
     });
+
+    describe("MSC4354 sticky events", () => {
+        function stickyEvent(ts = 0): IStickyEvent {
+            const msgData = msg("test", "test text");
+            return {
+                ...msgData,
+                msc4354_sticky: {
+                    duration_ms: 1000,
+                },
+                origin_server_ts: ts,
+            };
+        }
+
+        beforeAll(() => {
+            jest.useFakeTimers();
+        });
+
+        afterAll(() => {
+            jest.useRealTimers();
+        });
+
+        it("should accumulate sticky events", () => {
+            jest.setSystemTime(0);
+            const ev = stickyEvent();
+            sa.accumulate(
+                syncSkeleton({
+                    msc4354_sticky: {
+                        events: [ev],
+                    },
+                }),
+            );
+            expect(sa.getJSON().roomsData[Category.Join]["!foo:bar"].msc4354_sticky?.events).toEqual([ev]);
+        });
+        it("should clear stale sticky events", () => {
+            jest.setSystemTime(1000);
+            const ev = stickyEvent(1000);
+            sa.accumulate(
+                syncSkeleton({
+                    msc4354_sticky: {
+                        events: [ev],
+                    },
+                }),
+            );
+            expect(sa.getJSON().roomsData[Category.Join]["!foo:bar"].msc4354_sticky?.events).toEqual([ev]);
+            jest.setSystemTime(2000); // Expire the event
+            sa.accumulate(syncSkeleton({}));
+            expect(sa.getJSON().roomsData[Category.Join]["!foo:bar"].msc4354_sticky?.events).toBeUndefined();
+        });
+    });
 });
 
 function syncSkeleton(

src/@types/requests.ts

@@ -107,6 +107,9 @@ export type SendActionDelayedEventRequestOpts = ParentDelayId;
 
 export type SendDelayedEventRequestOpts = SendTimeoutDelayedEventRequestOpts | SendActionDelayedEventRequestOpts;
 
+export function isSendDelayedEventRequestOpts(opts: object): opts is SendDelayedEventRequestOpts {
+    return (opts as TimeoutDelay).delay !== undefined || (opts as ParentDelayId).parent_delay_id !== undefined;
+}
 export type SendDelayedEventResponse = {
     delay_id: string;
 };