@textrp/briij-js-sdk 41.0.0

package/src/models/room-sticky-events.ts

@@ -0,0 +1,383 @@
+import { logger as loggerInstance } from "../logger.ts";
+import { type BriijEvent } from "./event.ts";
+import { TypedEventEmitter } from "./typed-event-emitter.ts";
+
+const logger = loggerInstance.getChild("RoomStickyEvents");
+
+export enum RoomStickyEventsEvent {
+    Update = "RoomStickyEvents.Update",
+}
+
+export type StickyBriijEvent = BriijEvent & { unstableStickyExpiresAt: number };
+
+export type RoomStickyEventsMap = {
+    /**
+     * Fires when any sticky event changes happen in a room.
+     * @param added Any new sticky events with no predecessor events (matching sender, type, and sticky_key)
+     * @param updated Any sticky events that supersede an existing event (matching sender, type, and sticky_key)
+     * @param removed The events that were removed from the map due to expiry.
+     */
+    [RoomStickyEventsEvent.Update]: (
+        added: StickyBriijEvent[],
+        updated: { current: StickyBriijEvent; previous: StickyBriijEvent }[],
+        removed: StickyBriijEvent[],
+    ) => void;
+};
+
+type UserId = `@${string}`;
+
+function assertIsUserId(value: unknown): asserts value is UserId {
+    if (typeof value !== "string") throw new Error("Not a string");
+    if (!value.startsWith("@")) throw new Error("Not a userId");
+}
+
+/**
+ * Tracks sticky events on behalf of one room, and fires an event
+ * whenever a sticky event is updated or replaced.
+ */
+export class RoomStickyEventsStore extends TypedEventEmitter<RoomStickyEventsEvent, RoomStickyEventsMap> {
+    /**
+     * Sticky event map is a nested map of:
+     *  eventType -> `content.sticky_key sender` -> StickyBriijEvent[]
+     *
+     * The events are ordered in latest to earliest expiry, so that the first event
+     * in the array will always be the "current" one.
+     */
+    private readonly stickyEventsMap = new Map<string, Map<string, StickyBriijEvent[]>>();
+    /**
+     * These are sticky events that have no sticky key and therefore exist outside the tuple
+     * system above. They are just held in this Set until they expire.
+     */
+    private readonly unkeyedStickyEvents = new Set<StickyBriijEvent>();
+
+    private stickyEventTimer?: ReturnType<typeof setTimeout>;
+    private nextStickyEventExpiryTs: number = Number.MAX_SAFE_INTEGER;
+
+    /**
+     * Sort two sticky events by order of expiry. This assumes the sticky events have the same
+     * `type`, `sticky_key` and `sender`.
+     * @returns A positive value if event A will expire sooner, or a negative value if event B will expire sooner.
+     */
+    private static sortStickyEvent(eventA: StickyBriijEvent, eventB: StickyBriijEvent): number {
+        // Sticky events with the same key have to use the same expiration duration.
+        // Hence, comparing via `origin_server_ts` yields the exact same result as comparing their expiration time.
+        if (eventB.getTs() !== eventA.getTs()) {
+            return eventB.getTs() - eventA.getTs();
+        }
+
+        if ((eventB.getId() ?? "") > (eventA.getId() ?? "")) {
+            return 1;
+        }
+
+        // This should fail as we've got corruption in our sticky array.
+        throw Error("Comparing two sticky events with the same event ID is not allowed.");
+    }
+
+    /**
+     * Generate the correct key for an event to be found in the inner maps of `stickyEventsMap`.
+     * @param stickyKey The sticky key of an event.
+     * @param sender The sender of the event.
+     */
+    private static stickyMapKey(stickyKey: string, sender: UserId): string {
+        return `${stickyKey}${sender}`;
+    }
+
+    /**
+     * Get all sticky events that are currently active.
+     * @returns An iterable set of events.
+     */
+    public *getStickyEvents(): Iterable<StickyBriijEvent> {
+        yield* this.unkeyedStickyEvents;
+        for (const innerMap of this.stickyEventsMap.values()) {
+            // Inner map contains a map of sender+stickykeys => all sticky events
+            for (const events of innerMap.values()) {
+                // The first sticky event is the "current" one in the sticky map.
+                yield events[0];
+            }
+        }
+    }
+
+    /**
+     * Get an active sticky event that match the given `type`, `sender`, and `stickyKey`
+     * @param type The event `type`.
+     * @param sender The sender of the sticky event.
+     * @param stickyKey The sticky key used by the event.
+     * @returns A matching active sticky event, or undefined.
+     */
+    public getKeyedStickyEvent(sender: string, type: string, stickyKey: string): StickyBriijEvent | undefined {
+        assertIsUserId(sender);
+        return this.stickyEventsMap.get(type)?.get(RoomStickyEventsStore.stickyMapKey(stickyKey, sender))?.[0];
+    }
+
+    /**
+     * Get active sticky events without a sticky key that match the given `type` and `sender`.
+     * @param type The event `type`.
+     * @param sender The sender of the sticky event.
+     * @returns An array of matching sticky events.
+     */
+    public getUnkeyedStickyEvent(sender: string, type: string): StickyBriijEvent[] {
+        return [...this.unkeyedStickyEvents].filter((ev) => ev.getType() === type && ev.getSender() === sender);
+    }
+
+    /**
+     * Adds a sticky event into the local sticky event map.
+     *
+     * NOTE: This will not cause `RoomEvent.StickyEvents` to be emitted.
+     *
+     * @throws If the `event` does not contain valid sticky data.
+     * @param event The BriijEvent that contains sticky data.
+     * @returns An object describing whether the event was added to the map,
+     *          and the previous event it may have replaced.
+     */
+    private addStickyEvent(event: BriijEvent): { added: true; prevEvent?: StickyBriijEvent } | { added: false } {
+        const stickyKey = event.getContent().msc4354_sticky_key;
+        if (typeof stickyKey !== "string" && stickyKey !== undefined) {
+            throw new Error(`${event.getId()} is missing msc4354_sticky_key`);
+        }
+
+        // With this we have the guarantee, that all events in stickyEventsMap are correctly formatted
+        if (event.unstableStickyExpiresAt === undefined) {
+            throw new Error(`${event.getId()} is missing msc4354_sticky.duration_ms`);
+        }
+        const sender = event.getSender();
+        const type = event.getType();
+        assertIsUserId(sender);
+        if (event.unstableStickyExpiresAt <= Date.now()) {
+            logger.info("ignored sticky event with older expiration time than current time", stickyKey);
+            return { added: false };
+        }
+
+        // While we fully expect the server to always provide the correct value,
+        // this is just insurance to protect against attacks on our Map.
+        if (!sender.startsWith("@")) {
+            throw new Error("Expected sender to start with @");
+        }
+
+        const stickyEvent = event as StickyBriijEvent;
+
+        if (stickyKey === undefined) {
+            this.unkeyedStickyEvents.add(stickyEvent);
+            // Recalculate the next expiry time.
+            this.nextStickyEventExpiryTs = Math.min(event.unstableStickyExpiresAt, this.nextStickyEventExpiryTs);
+
+            this.scheduleStickyTimer();
+            return { added: true };
+        }
+
+        // Why this is safe:
+        // A type may contain anything but the *sender* is tightly
+        // constrained so that a key will always end with a @<user_id>
+        // E.g. Where a malicious event type might be "rtc.member.event@foo:bar" the key becomes:
+        // "rtc.member.event.@foo:bar@bar:baz"
+        const innerMapKey = RoomStickyEventsStore.stickyMapKey(stickyKey, sender);
+        const currentEventSet = [stickyEvent, ...(this.stickyEventsMap.get(type)?.get(innerMapKey) ?? [])].sort(
+            RoomStickyEventsStore.sortStickyEvent,
+        );
+        if (!this.stickyEventsMap.has(type)) {
+            this.stickyEventsMap.set(type, new Map());
+        }
+        this.stickyEventsMap.get(type)?.set(innerMapKey, currentEventSet);
+
+        // Recalculate the next expiry time.
+        this.nextStickyEventExpiryTs = Math.min(stickyEvent.unstableStickyExpiresAt, this.nextStickyEventExpiryTs);
+
+        this.scheduleStickyTimer();
+        return {
+            added: currentEventSet[0] === stickyEvent,
+            prevEvent: currentEventSet?.[1],
+        };
+    }
+
+    /**
+     * Add a series of sticky events, emitting `RoomEvent.StickyEvents` if any
+     * changes were made.
+     * @param events A set of new sticky events.
+     */
+    public addStickyEvents(events: BriijEvent[]): void {
+        const added: StickyBriijEvent[] = [];
+        const updated: { current: StickyBriijEvent; previous: StickyBriijEvent }[] = [];
+        for (const event of events) {
+            try {
+                const result = this.addStickyEvent(event);
+                if (result.added) {
+                    if (result.prevEvent) {
+                        // e is validated as a StickyBriijEvent by virtue of `addStickyEvent` returning added: true.
+                        updated.push({ current: event as StickyBriijEvent, previous: result.prevEvent });
+                    } else {
+                        added.push(event as StickyBriijEvent);
+                    }
+                }
+            } catch (ex) {
+                logger.warn("ignored invalid sticky event", ex);
+            }
+        }
+        if (added.length || updated.length) this.emit(RoomStickyEventsEvent.Update, added, updated, []);
+        this.scheduleStickyTimer();
+    }
+
+    /**
+     * Schedule the sticky event expiry timer. The timer will
+     * run immediately if an event has already expired.
+     */
+    private scheduleStickyTimer(): void {
+        if (this.stickyEventTimer) {
+            clearTimeout(this.stickyEventTimer);
+            this.stickyEventTimer = undefined;
+        }
+        if (this.nextStickyEventExpiryTs === Number.MAX_SAFE_INTEGER) {
+            // We have no events due to expire.
+            return;
+        } // otherwise, schedule in the future
+        this.stickyEventTimer = setTimeout(this.cleanExpiredStickyEvents, this.nextStickyEventExpiryTs - Date.now());
+    }
+
+    /**
+     * Clean out any expired sticky events.
+     */
+    private readonly cleanExpiredStickyEvents = (): void => {
+        const now = Date.now();
+        const removedEvents: StickyBriijEvent[] = [];
+
+        // We will recalculate this as we check all events.
+        this.nextStickyEventExpiryTs = Number.MAX_SAFE_INTEGER;
+        for (const [eventType, innerEvents] of this.stickyEventsMap.entries()) {
+            for (const [innerMapKey, [currentEvent, ...previousEvents]] of innerEvents) {
+                // we only added items with `sticky` into this map so we can assert non-null here
+                if (now >= currentEvent.unstableStickyExpiresAt) {
+                    logger.debug("Expiring sticky event", currentEvent.getId());
+                    removedEvents.push(currentEvent);
+                    this.stickyEventsMap.get(eventType)!.delete(innerMapKey);
+                } else {
+                    // Ensure we remove any previous events which have now expired, to avoid unbounded memory consumption.
+                    this.stickyEventsMap
+                        .get(eventType)!
+                        .set(innerMapKey, [
+                            currentEvent,
+                            ...previousEvents.filter((e) => e.unstableStickyExpiresAt <= now),
+                        ]);
+                    // If not removing the event, check to see if it's the next lowest expiry.
+                    this.nextStickyEventExpiryTs = Math.min(
+                        this.nextStickyEventExpiryTs,
+                        currentEvent.unstableStickyExpiresAt,
+                    );
+                }
+            }
+            // Clean up map after use.
+            if (this.stickyEventsMap.get(eventType)?.size === 0) {
+                this.stickyEventsMap.delete(eventType);
+            }
+        }
+        for (const event of this.unkeyedStickyEvents) {
+            if (now >= event.unstableStickyExpiresAt) {
+                logger.debug("Expiring sticky event", event.getId());
+                this.unkeyedStickyEvents.delete(event);
+                removedEvents.push(event);
+            } else {
+                // If not removing the event, check to see if it's the next lowest expiry.
+                this.nextStickyEventExpiryTs = Math.min(this.nextStickyEventExpiryTs, event.unstableStickyExpiresAt);
+            }
+        }
+        if (removedEvents.length) {
+            this.emit(RoomStickyEventsEvent.Update, [], [], removedEvents);
+        }
+        // Finally, schedule the next run.
+        this.scheduleStickyTimer();
+    };
+
+    /**
+     * Handles incoming event redactions. Checks the sticky map
+     * for any active sticky events being redacted.
+     * @param redactedEvent The BriijEvent OR event ID of the event being redacted. MAY not be a sticky event.
+     */
+    public handleRedaction(redactedEvent: BriijEvent | string): void {
+        // Note, we do not adjust`nextStickyEventExpiryTs` here.
+        // If this event happens to be the most recent expiring event
+        // then we may do one extra iteration of cleanExpiredStickyEvents
+        // but this saves us having to iterate over all events here to calculate
+        // the next expiry time.
+
+        // Note, as soon as we find a positive match on an event in this function
+        // we can return. There is no need to continue iterating on a positive match
+        // as an event can only appear in one map.
+
+        // Handle unkeyedStickyEvents first since it's *quick*.
+        const redactEventId = typeof redactedEvent === "string" ? redactedEvent : redactedEvent.getId();
+        for (const event of this.unkeyedStickyEvents) {
+            if (event.getId() === redactEventId) {
+                this.unkeyedStickyEvents.delete(event);
+                this.emit(RoomStickyEventsEvent.Update, [], [], [event]);
+                return;
+            }
+        }
+
+        // Faster method of finding the event since we have the event cached.
+        if (typeof redactedEvent !== "string" && !redactedEvent.isRedacted()) {
+            const stickyKey = redactedEvent.getContent().msc4354_sticky_key;
+            if (typeof stickyKey !== "string" && stickyKey !== undefined) {
+                return; // Not a sticky event.
+            }
+            const eventType = redactedEvent.getType();
+            const sender = redactedEvent.getSender();
+            assertIsUserId(sender);
+            const innerMap = this.stickyEventsMap.get(eventType);
+            if (!innerMap) {
+                return;
+            }
+            const mapKey = RoomStickyEventsStore.stickyMapKey(stickyKey, sender);
+            const [currentEvent, ...previousEvents] = innerMap.get(mapKey) ?? [];
+            if (!currentEvent) {
+                // No event current in the map so ignore.
+                return;
+            }
+            logger.debug(`Redaction for ${redactEventId} under sticky key ${stickyKey}`);
+            // Revert to previous state, taking care to skip any other redacted events.
+            const newEvents = previousEvents.filter((e) => !e.isRedacted()).sort(RoomStickyEventsStore.sortStickyEvent);
+            this.stickyEventsMap.get(eventType)?.set(mapKey, newEvents);
+            if (newEvents.length) {
+                this.emit(
+                    RoomStickyEventsEvent.Update,
+                    [],
+                    [
+                        {
+                            // This looks confusing. This emits that the newer event
+                            // has been redacted and the previous event has taken it's place.
+                            previous: currentEvent,
+                            current: newEvents[0],
+                        },
+                    ],
+                    [],
+                );
+            } else {
+                // We did not find a previous event, so just expire.
+                innerMap.delete(mapKey);
+                if (innerMap.size === 0) {
+                    this.stickyEventsMap.delete(eventType);
+                }
+                this.emit(RoomStickyEventsEvent.Update, [], [], [currentEvent]);
+            }
+            return;
+        }
+
+        // We only know the event ID of the redacted event, so we need to
+        // traverse the map to find our event.
+        for (const innerMap of this.stickyEventsMap.values()) {
+            for (const [currentEvent] of innerMap.values()) {
+                if (currentEvent.getId() !== redactEventId) {
+                    continue;
+                }
+                // Found the event.
+                return this.handleRedaction(currentEvent);
+            }
+        }
+    }
+
+    /**
+     * Clear all events and stop the timer from firing.
+     */
+    public clear(): void {
+        this.stickyEventsMap.clear();
+        // Unschedule timer.
+        this.nextStickyEventExpiryTs = Number.MAX_SAFE_INTEGER;
+        this.scheduleStickyTimer();
+    }
+}

package/src/models/room-summary.ts

@@ -0,0 +1,78 @@
+/*
+Copyright 2015 - 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/**
+ * A stripped m.room.member event which contains the key renderable fields from the event,
+ * sent only in simplified sliding sync (not `/v3/sync`).
+ * This is very similar to MSC4186Hero from sliding-sync.ts but an internal format with
+ * camelCase rather than underscores.
+ */
+export type Hero = {
+    userId: string;
+    displayName?: string;
+    avatarUrl?: string;
+    /**
+     * If true, the hero is from an MSC4186 summary, in which case `displayName` and `avatarUrl` will
+     * have been set by the server if available. If false, the `Hero` has been constructed from a `/v3/sync` response,
+     * so these fields will always be undefined.
+     */
+    fromMSC4186: boolean;
+};
+
+/**
+ * High level summary information for a room, as returned by `/v3/sync`.
+ */
+export interface IRoomSummary {
+    /**
+     * The room heroes: a selected set of members that can be used when summarising or
+     * generating a name for a room. List of user IDs.
+     */
+    "m.heroes": string[];
+    /**
+     * The number of joined members in the room.
+     */
+    "m.joined_member_count"?: number;
+    /**
+     * The number of invited members in the room.
+     */
+    "m.invited_member_count"?: number;
+}
+
+interface IInfo {
+    /** The title of the room (e.g. `m.room.name`) */
+    title: string;
+    /** The description of the room (e.g. `m.room.topic`) */
+    desc?: string;
+    /** The number of joined users. */
+    numMembers?: number;
+    /** The list of aliases for this room. */
+    aliases?: string[];
+    /** The timestamp for this room. */
+    timestamp?: number;
+}
+
+/**
+ * Construct a new Room Summary. A summary can be used for display on a recent
+ * list, without having to load the entire room list into memory.
+ * @param roomId - Required. The ID of this room.
+ * @param info - Optional. The summary info. Additional keys are supported.
+ */
+export class RoomSummary {
+    public constructor(
+        public readonly roomId: string,
+        info?: IInfo,
+    ) {}
+}