polfan-server-js-client 0.3.2 → 0.3.3

package/build/types/state-tracker/RoomMessagesHistory.d.ts

@@ -6,6 +6,7 @@ export declare class RoomMessagesHistory {
     private tracker;
     private historyWindows;
     private traverseLock;
+    private timeLimitedHistory;
     constructor(room: Room, tracker: ChatStateTracker);
     /**
      * Returns a history window object for the given topic ID, allowing you to view message history.
@@ -20,14 +21,24 @@ export declare class RoomMessagesHistory {
      *
      * The window bindings are preserved; only windows that the application had
      * actually pulled to the latest page (state === LATEST) are refreshed, with
-     * a single resetToLatest instead of a chain of catch-up requests. Windows
-     * that were never pulled (LIVE) or belong to an ephemeral room are left
-     * untouched so their in-memory context survives the reconnect.
+     * a single request instead of a chain of catch-up requests. Windows that
+     * were never pulled (LIVE) or belong to an ephemeral room are left untouched
+     * so their in-memory context survives the reconnect.
+     *
+     * How a refreshed window is rebuilt depends on the room history mode: rooms
+     * keeping the full history are simply reset to the latest page (it can
+     * always be traversed back on demand), while rooms with a time-limited
+     * history (MaxAge) load the messages missed during the downtime on top of
+     * the already loaded ones, with the messages returned in both deduplicated.
+     * The maxAge retention applies to what the server serves - so that users
+     * joining later do not see the older conversation - and never to what this
+     * client already has: messages the user witnessed stay in the window until
+     * they are pushed out by its own size limit.
      */
     resync(room: Room): Promise<void>;
     private handleRoomUpdated;
     private handleNewTopic;
     private handleTopicDeleted;
     private createHistoryWindowForTopic;
-    private updateTraverseLock;
+    private updateHistoryMode;
 }

package/build/types/state-tracker/TopicHistoryWindow.d.ts

@@ -34,6 +34,7 @@ export declare abstract class TraversableRemoteCollection<ItemT, EventMapT exten
         fetchLimit: number;
         lastFetchCount: number;
         oldestId: string | null;
+        gaps: string[];
     };
     /**
      * Number of items to fetch per request.
@@ -62,12 +63,44 @@ export declare abstract class TraversableRemoteCollection<ItemT, EventMapT exten
      */
     set retainRatio(value: number);
     get hasLatest(): boolean;
+    /**
+     * IDs of the items the window could not stitch to the ones loaded before
+     * them: there is a gap in front of each of them, i.e. the item right above
+     * it in the window is not its real predecessor and an unknown number of
+     * items in between was never fetched.
+     *
+     * Such a gap appears when the collection is resynchronised after a
+     * reconnect (see resyncToLatest) and more items than a single page arrived
+     * while the connection was down. The markers are kept in the window order
+     * and disappear together with the items they point at.
+     */
+    get gaps(): readonly string[];
     get hasOldest(): boolean;
     abstract createMirror(): TraversableRemoteCollection<ItemT, EventMapT>;
     resetToLatest(force?: boolean): Promise<void>;
+    /**
+     * Refresh the window with the latest page, keeping the already loaded items
+     * instead of replacing them.
+     *
+     * This is the reconnect-friendly variant of resetToLatest: the items missed
+     * while the connection was down are pulled with a single request and merged
+     * on top of the loaded ones (items returned in both are deduplicated), so
+     * the context the application already had does not disappear. The window
+     * size limit is the only thing that pushes the oldest items out.
+     *
+     * An empty or partial page is not a reason to drop anything: it only means
+     * the collection has little (or nothing) left on the remote side, while the
+     * items loaded earlier are still valid. When the page is full and does not
+     * reach the loaded items, an unknown number of items in between was never
+     * fetched - both parts are still kept, and the seam between them is recorded
+     * in `gaps` so the application can show where the history is not continuous.
+     */
+    resyncToLatest(): Promise<void>;
     fetchPrevious(): Promise<void>;
     fetchNext(): Promise<void>;
     jumpTo(id: string): Promise<void>;
+    delete(...ids: string[]): void;
+    deleteAll(): void;
     protected abstract fetchLatestItems(): Promise<ItemT[]>;
     protected abstract fetchItemsBefore(): Promise<ItemT[] | null>;
     protected abstract fetchItemsAfter(): Promise<ItemT[] | null>;
@@ -76,6 +109,20 @@ export declare abstract class TraversableRemoteCollection<ItemT, EventMapT exten
     protected refreshFetchedState(): Promise<void>;
     protected addItems(newItems: ItemT[], to: 'head' | 'tail'): void;
     protected emitChangeWithDiff(itemChanged: boolean, originalState: WindowState): void;
+    /**
+     * Record that the history is not continuous in front of the given item.
+     */
+    protected markGapBefore(id: string): void;
+    /**
+     * Forget the gap in front of the given item - the items before it are known
+     * to be its real predecessors now.
+     */
+    protected clearGapBefore(id: string): void;
+    /**
+     * Forget the gap markers pointing at items that are no longer in the window
+     * (trimmed, deleted or replaced), so `gaps` never refers to nothing.
+     */
+    protected dropDanglingGaps(): void;
     /**
      * Return array with messages trimmed using High/Low Watermark strategy.
      */
@@ -100,6 +147,7 @@ export declare class TopicHistoryWindow extends TraversableRemoteCollection<Mess
     get isTraverseLocked(): boolean;
     setTraverseLock(lock: boolean): Promise<void>;
     resetToLatest(force?: boolean): Promise<void>;
+    resyncToLatest(): Promise<void>;
     fetchNext(): Promise<void>;
     fetchPrevious(): Promise<void>;
     jumpTo(id: string): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polfan-server-js-client",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "JavaScript client library for handling communication with Polfan chat server.",
   "author": "Jarosław Żak",
   "license": "MIT",

package/src/state-tracker/RoomMessagesHistory.ts

@@ -6,6 +6,7 @@ import {TopicHistoryWindow, WindowState} from "./TopicHistoryWindow";
 export class RoomMessagesHistory {
     private historyWindows = new IndexedCollection<string, TopicHistoryWindow>();
     private traverseLock: boolean = false;
+    private timeLimitedHistory: boolean = false;
 
     public constructor(
         private room: Room,
@@ -15,7 +16,7 @@ export class RoomMessagesHistory {
         this.tracker.client.on('NewTopic', ev => this.handleNewTopic(ev));
         this.tracker.client.on('TopicDeleted', ev => this.handleTopicDeleted(ev));
 
-        this.updateTraverseLock(this.room);
+        this.updateHistoryMode(this.room);
 
         if (this.room.defaultTopic) {
             this.createHistoryWindowForTopic(this.room.defaultTopic);
@@ -46,13 +47,23 @@ export class RoomMessagesHistory {
      *
      * The window bindings are preserved; only windows that the application had
      * actually pulled to the latest page (state === LATEST) are refreshed, with
-     * a single resetToLatest instead of a chain of catch-up requests. Windows
-     * that were never pulled (LIVE) or belong to an ephemeral room are left
-     * untouched so their in-memory context survives the reconnect.
+     * a single request instead of a chain of catch-up requests. Windows that
+     * were never pulled (LIVE) or belong to an ephemeral room are left untouched
+     * so their in-memory context survives the reconnect.
+     *
+     * How a refreshed window is rebuilt depends on the room history mode: rooms
+     * keeping the full history are simply reset to the latest page (it can
+     * always be traversed back on demand), while rooms with a time-limited
+     * history (MaxAge) load the messages missed during the downtime on top of
+     * the already loaded ones, with the messages returned in both deduplicated.
+     * The maxAge retention applies to what the server serves - so that users
+     * joining later do not see the older conversation - and never to what this
+     * client already has: messages the user witnessed stay in the window until
+     * they are pushed out by its own size limit.
      */
     public async resync(room: Room): Promise<void> {
         this.room = room;
-        this.updateTraverseLock(room);
+        this.updateHistoryMode(room);
 
         if (this.room.defaultTopic) {
             this.createHistoryWindowForTopic(this.room.defaultTopic);
@@ -68,7 +79,13 @@ export class RoomMessagesHistory {
                     continue;
                 }
 
-                if (window.state === WindowState.LATEST) {
+                if (window.state !== WindowState.LATEST) {
+                    continue;
+                }
+
+                if (this.timeLimitedHistory) {
+                    await window.resyncToLatest();
+                } else {
                     await window.resetToLatest(true);
                 }
             } catch (_e) {
@@ -83,7 +100,7 @@ export class RoomMessagesHistory {
         if (this.room.id === ev.room.id) {
             this.room = ev.room;
 
-            this.updateTraverseLock(ev.room);
+            this.updateHistoryMode(ev.room);
 
             if (ev.room.defaultTopic) {
                 this.createHistoryWindowForTopic(ev.room.defaultTopic);
@@ -134,7 +151,8 @@ export class RoomMessagesHistory {
         }
     }
 
-    private updateTraverseLock(room: Room): void {
-        this.traverseLock = room.history.mode === 'Ephemeral';
+    private updateHistoryMode(room: Room): void {
+        this.traverseLock = room.history?.mode === 'Ephemeral';
+        this.timeLimitedHistory = room.history?.mode === 'MaxAge';
     }
 }

package/src/state-tracker/TopicHistoryWindow.ts

@@ -45,6 +45,7 @@ export abstract class TraversableRemoteCollection<
         fetchLimit: number,
         lastFetchCount: number,
         oldestId: string | null,
+        gaps: string[],
     } = {
         current: WindowState.LIVE,
         ongoing: undefined,
@@ -53,6 +54,7 @@ export abstract class TraversableRemoteCollection<
         fetchLimit: 50,
         lastFetchCount: 0,
         oldestId: null,
+        gaps: [],
     };
 
     /**
@@ -103,6 +105,21 @@ export abstract class TraversableRemoteCollection<
         return [WindowState.LATEST, WindowState.LIVE].includes(this.state);
     }
 
+    /**
+     * IDs of the items the window could not stitch to the ones loaded before
+     * them: there is a gap in front of each of them, i.e. the item right above
+     * it in the window is not its real predecessor and an unknown number of
+     * items in between was never fetched.
+     *
+     * Such a gap appears when the collection is resynchronised after a
+     * reconnect (see resyncToLatest) and more items than a single page arrived
+     * while the connection was down. The markers are kept in the window order
+     * and disappear together with the items they point at.
+     */
+    public get gaps(): readonly string[] {
+        return [...this.internalState.gaps];
+    }
+
     public get hasOldest(): boolean {
         return this.state === WindowState.OLDEST
             || this.state === WindowState.LATEST && this.length < this.fetchLimit
@@ -128,11 +145,68 @@ export abstract class TraversableRemoteCollection<
         }
 
         this._items.deleteAll(); // Directly call deleteAll to prevent event emit.
+        this.internalState.gaps = []; // Whole content is replaced, old markers mean nothing.
         this.addItems(result, 'tail');
         this.internalState.current = WindowState.LATEST;
         this.emitChangeWithDiff(true, originalState);
     }
 
+    /**
+     * Refresh the window with the latest page, keeping the already loaded items
+     * instead of replacing them.
+     *
+     * This is the reconnect-friendly variant of resetToLatest: the items missed
+     * while the connection was down are pulled with a single request and merged
+     * on top of the loaded ones (items returned in both are deduplicated), so
+     * the context the application already had does not disappear. The window
+     * size limit is the only thing that pushes the oldest items out.
+     *
+     * An empty or partial page is not a reason to drop anything: it only means
+     * the collection has little (or nothing) left on the remote side, while the
+     * items loaded earlier are still valid. When the page is full and does not
+     * reach the loaded items, an unknown number of items in between was never
+     * fetched - both parts are still kept, and the seam between them is recorded
+     * in `gaps` so the application can show where the history is not continuous.
+     */
+    public async resyncToLatest(): Promise<void> {
+        if (this.internalState.ongoing) {
+            return;
+        }
+
+        let result;
+        const originalState = this.state;
+        this.internalState.ongoing = WindowState.LATEST;
+
+        try {
+            result = await this.fetchLatestItems();
+            this.internalState.lastFetchCount = result.length;
+        } finally {
+            this.internalState.ongoing = undefined;
+        }
+
+        const loaded = this.items;
+        const fetchedIds = new Set(result.map(item => this.getId(item)));
+        // Items present in the page are taken from it - the server copy is the
+        // up-to-date one.
+        const retained = loaded.filter(item => ! fetchedIds.has(this.getId(item)));
+
+        // Nothing can be missing in between when there is nothing to stitch,
+        // when the page is everything the remote side has (it is shorter than
+        // the requested limit), or when the page reaches the newest loaded item.
+        const isContinuous = ! retained.length
+            || result.length < this.internalState.fetchLimit
+            || fetchedIds.has(this.getId(loaded[loaded.length - 1]));
+
+        if (! isContinuous) {
+            this.markGapBefore(this.getId(result[0]));
+        }
+
+        this._items.deleteAll(); // Directly call deleteAll to prevent event emit.
+        this.addItems([...retained, ...result], 'tail');
+        this.internalState.current = WindowState.LATEST;
+        this.emitChangeWithDiff(true, originalState);
+    }
+
     public async fetchPrevious(): Promise<void> {
         if (this.internalState.ongoing || this.hasOldest) {
             return;
@@ -140,6 +214,7 @@ export abstract class TraversableRemoteCollection<
 
         let result;
         const originalState = this.state;
+        const firstItem = this.getAt(0);
         this.internalState.ongoing = WindowState.PAST;
 
         try {
@@ -154,7 +229,6 @@ export abstract class TraversableRemoteCollection<
         }
 
         if (! result.length) {
-            const firstItem = this.getAt(0);
             this.internalState.oldestId = firstItem ? this.getId(firstItem) : null;
 
             await this.refreshFetchedState();
@@ -168,6 +242,13 @@ export abstract class TraversableRemoteCollection<
             return;
         }
 
+        if (firstItem) {
+            // The fetch asked for the items right before the one that was first,
+            // so whatever came back is its real predecessor: a gap marked in
+            // front of it (it used to be the top of the window) is closed now.
+            this.clearGapBefore(this.getId(firstItem));
+        }
+
         this.addItems(result, 'head');
         await this.refreshFetchedState();
         this.emitChangeWithDiff(true, originalState);
@@ -217,6 +298,7 @@ export abstract class TraversableRemoteCollection<
 
             if (result) {
                 this._items.deleteAll(); // Directly call deleteAll to prevent event emit.
+                this.internalState.gaps = []; // Whole content is replaced, old markers mean nothing.
                 this.addItems(result, 'tail');
                 await this.refreshFetchedState();
             }
@@ -227,6 +309,16 @@ export abstract class TraversableRemoteCollection<
         this.emitChangeWithDiff(!!result, originalState);
     }
 
+    public delete(...ids: string[]): void {
+        super.delete(...ids);
+        this.dropDanglingGaps();
+    }
+
+    public deleteAll(): void {
+        super.deleteAll();
+        this.internalState.gaps = [];
+    }
+
     protected abstract fetchLatestItems(): Promise<ItemT[]>;
 
     protected abstract fetchItemsBefore(): Promise<ItemT[] | null>;
@@ -255,6 +347,8 @@ export abstract class TraversableRemoteCollection<
         // Directly calls to prevent event emit.
         this._items.deleteAll();
         this._items.set(...(result.map(item => [this.getId(item), item] as [string, ItemT])));
+
+        this.dropDanglingGaps();
     }
 
     protected emitChangeWithDiff(itemChanged: boolean, originalState: WindowState): void {
@@ -263,6 +357,37 @@ export abstract class TraversableRemoteCollection<
         }
     }
 
+    /**
+     * Record that the history is not continuous in front of the given item.
+     */
+    protected markGapBefore(id: string): void {
+        if (! this.internalState.gaps.includes(id)) {
+            this.internalState.gaps = [...this.internalState.gaps, id];
+        }
+    }
+
+    /**
+     * Forget the gap in front of the given item - the items before it are known
+     * to be its real predecessors now.
+     */
+    protected clearGapBefore(id: string): void {
+        if (this.internalState.gaps.includes(id)) {
+            this.internalState.gaps = this.internalState.gaps.filter(gapId => gapId !== id);
+        }
+    }
+
+    /**
+     * Forget the gap markers pointing at items that are no longer in the window
+     * (trimmed, deleted or replaced), so `gaps` never refers to nothing.
+     */
+    protected dropDanglingGaps(): void {
+        if (! this.internalState.gaps.length) {
+            return;
+        }
+
+        this.internalState.gaps = this.internalState.gaps.filter(id => this.has(id));
+    }
+
     /**
      * Return array with messages trimmed using High/Low Watermark strategy.
      */
@@ -347,6 +472,13 @@ export class TopicHistoryWindow extends TraversableRemoteCollection<
         return super.resetToLatest(force);
     }
 
+    public async resyncToLatest(): Promise<void> {
+        if (this.internalState.traverseLock) {
+            return;
+        }
+        return super.resyncToLatest();
+    }
+
     public async fetchNext(): Promise<void> {
         if (this.internalState.traverseLock) {
             return;

package/tests/history-window.test.ts

@@ -209,6 +209,137 @@ test('history window - reset to latest', async () => {
     [7,8,9].forEach(id => expect(window.items.map(item => item.id)).toContain(id));
 });
 
+test('history window - resync to latest merges the new page into loaded items', async () => {
+    const window = new TestableHistoryWindow();
+    window.limit = 10;
+    window.fetchLimit = 3;
+
+    await window.resetToLatest(); // [7,8,9]
+    await window.fetchPrevious(); // [4,5,6,7,8,9]
+
+    await window.resyncToLatest(); // fetched [7,8,9] overlaps -> nothing is lost
+
+    expect(window.state).toEqual(WindowState.LATEST);
+    expect(window.items.map(item => item.id)).toEqual([4, 5, 6, 7, 8, 9]);
+});
+
+test('history window - resync to latest trims the merged items to the limit', async () => {
+    const window = new TestableHistoryWindow();
+    window.limit = 4;
+    window.fetchLimit = 3;
+
+    await window.resetToLatest(); // [7,8,9]
+    await window.fetchPrevious(); // [4,5,6,7] (trimmed to the limit)
+
+    // [4,5,6,7] merged with the page [7,8,9] -> [4,5,6,7,8,9], trimmed again.
+    await window.resyncToLatest();
+
+    expect(window.state).toEqual(WindowState.LATEST);
+    expect(window.items.map(item => item.id)).toEqual([6, 7, 8, 9]);
+});
+
+test('history window - resync to latest marks the gap instead of dropping items', async () => {
+    const window = new TestableHistoryWindow();
+    window.limit = 10;
+    window.fetchLimit = 3;
+
+    await window.jumpTo('1'); // [0,1,2]
+
+    expect(window.gaps).toEqual([]);
+
+    // A full page ([7,8,9]) that does not reach the newest loaded item (2):
+    // items 3..6 were never fetched, so the seam in front of 7 is marked.
+    await window.resyncToLatest();
+
+    expect(window.state).toEqual(WindowState.LATEST);
+    expect(window.items.map(item => item.id)).toEqual([0, 1, 2, 7, 8, 9]);
+    expect(window.gaps).toEqual([7]);
+});
+
+test('history window - gap marker disappears with the item it points at', async () => {
+    const window = new TestableHistoryWindow();
+    window.limit = 10;
+    window.fetchLimit = 3;
+
+    await window.jumpTo('1'); // [0,1,2]
+    await window.resyncToLatest(); // [0,1,2] | [7,8,9]
+
+    expect(window.gaps).toEqual([7]);
+
+    window.delete(7);
+
+    expect(window.gaps).toEqual([]);
+});
+
+test('history window - gap marker is closed by fetching what is before it', async () => {
+    const window = new TestableHistoryWindow();
+    window.limit = 10;
+    window.fetchLimit = 3;
+
+    await window.jumpTo('1'); // [0,1,2]
+    await window.resyncToLatest(); // [0,1,2] | [7,8,9]
+    window.delete(0, 1, 2); // the items above the gap are gone, 7 is the top one
+
+    expect(window.gaps).toEqual([7]);
+
+    // Whatever comes back was fetched as the direct predecessor of 7, so the
+    // history is continuous again.
+    await window.fetchPrevious(); // [4,5,6,7,8,9]
+
+    expect(window.items.map(item => item.id)).toEqual([4, 5, 6, 7, 8, 9]);
+    expect(window.gaps).toEqual([]);
+});
+
+test('history window - gap markers are cleared when the whole window is replaced', async () => {
+    const window = new TestableHistoryWindow();
+    window.limit = 10;
+    window.fetchLimit = 3;
+
+    await window.jumpTo('1'); // [0,1,2]
+    await window.resyncToLatest(); // [0,1,2] | [7,8,9]
+
+    expect(window.gaps).toEqual([7]);
+
+    await window.resetToLatest(true); // [7,8,9] - a continuous window again
+
+    expect(window.items.map(item => item.id)).toEqual([7, 8, 9]);
+    expect(window.gaps).toEqual([]);
+});
+
+test('history window - gap marker is forgotten when trimmed out of the window', async () => {
+    const window = new TestableHistoryWindow();
+    window.limit = 10;
+    window.fetchLimit = 3;
+
+    await window.jumpTo('1'); // [0,1,2]
+    await window.resyncToLatest(); // [0,1,2] | [7,8,9]
+
+    expect(window.gaps).toEqual([7]);
+
+    // The window shrinks and the trimming pushes item 7 (and everything above
+    // it) out, so the marker has nothing left to point at.
+    window.limit = 2;
+    await window.resyncToLatest();
+
+    expect(window.items.map(item => item.id)).toEqual([8, 9]);
+    expect(window.gaps).toEqual([]);
+});
+
+test('history window - resync to latest keeps loaded items when the page is not full', async () => {
+    const window = new TestableHistoryWindow();
+    window.limit = 10;
+    window.fetchLimit = 5; // The fetch returns 3 items only - all there is.
+
+    await window.jumpTo('1'); // [0,1,2,3]
+
+    // Nothing is missing in between: the page is everything the remote side has,
+    // so the loaded items are kept even though the page does not reach them.
+    await window.resyncToLatest();
+
+    expect(window.state).toEqual(WindowState.LATEST);
+    expect(window.items.map(item => item.id)).toEqual([0, 1, 2, 3, 7, 8, 9]);
+});
+
 test('history window - jump to message', async () => {
     const window = new TestableHistoryWindow();
     window.limit = 5;