@mulingai-npm/redis 3.42.0 → 3.43.1

package/dist/managers/mulingstream-speaker-manager.d.ts

@@ -36,6 +36,18 @@ export declare class MulingstreamSpeakerManager {
     removeSpeakerBySocketId(socketId: string): Promise<boolean>;
     removeSpeakersByUserId(userId: string): Promise<number>;
     removeSpeakersByRoomId(roomId: string): Promise<number>;
+    /**
+     * Remove a speaker by its own id, without needing a live socket mapping.
+     *
+     * This is the removal that always works, and it is the one the cleanup
+     * sweeps must use. Removing by socket depends on `socket:<id>:speaker`
+     * still pointing at the record, and after a reconnect self-heal it does
+     * not: see updateSocketId. A ghost with a broken mapping is exactly the
+     * record a sweep is trying to delete, so resolving it through the mapping
+     * fails on precisely the case that matters and the ghost survives every
+     * sweep for the full 24 hour TTL.
+     */
+    removeSpeakerBySpeakerId(speakerId: string): Promise<boolean>;
     private removeSpeakerById;
     getSpeakerBySpeakerId(speakerId: string): Promise<MulingstreamSpeakerData | null>;
     getSpeakerBySocketId(socketId: string): Promise<MulingstreamSpeakerData | null>;
@@ -54,6 +66,22 @@ export declare class MulingstreamSpeakerManager {
     /**
      * Update socketId for a speaker (called by heartbeat self-heal when reconnect creates a new socket).
      * Mirrors the listener-side self-heal pattern — see MULINGSTREAM_RELIABILITY_ROADMAP.md §0.2.
+     *
+     * ─── THE MAPPING MOVES WITH THE FIELD, OR THE RECORD BECOMES A GHOST ───
+     *
+     * This used to rewrite the field alone, and that one omission is where
+     * every ghost speaker came from. `socket:<id>:speaker` is how a socket is
+     * resolved back to its speaker, and it is how disconnect, leave and both
+     * cleanup sweeps find the record they mean to delete. Leave it pointing at
+     * the OLD socket and the record becomes unreachable from the socket that
+     * actually owns it: the speaker's own disconnect finds nothing to remove,
+     * so the record survives its socket and lives out the 24 hour TTL.
+     *
+     * Room 500032 held four of them on 2026-08-27, one per Go Live that day,
+     * and three had a socketId field that did not match the socket in their own
+     * key: the signature of exactly this. They are not harmless. Ghosts inflate
+     * every "is anyone still in this room" count, and cleaning one up is what
+     * told a live congregation the speaker had left.
      */
     updateSocketId(speakerId: string, newSocketId: string): Promise<boolean>;
     updateTargetLanguages(socketId: string, languages: string[]): Promise<boolean>;

package/dist/managers/mulingstream-speaker-manager.js

@@ -129,6 +129,20 @@ class MulingstreamSpeakerManager {
                 deleted += 1;
         return deleted;
     }
+    /**
+     * Remove a speaker by its own id, without needing a live socket mapping.
+     *
+     * This is the removal that always works, and it is the one the cleanup
+     * sweeps must use. Removing by socket depends on `socket:<id>:speaker`
+     * still pointing at the record, and after a reconnect self-heal it does
+     * not: see updateSocketId. A ghost with a broken mapping is exactly the
+     * record a sweep is trying to delete, so resolving it through the mapping
+     * fails on precisely the case that matters and the ghost survives every
+     * sweep for the full 24 hour TTL.
+     */
+    async removeSpeakerBySpeakerId(speakerId) {
+        return this.removeSpeakerById(speakerId);
+    }
     async removeSpeakerById(speakerId) {
         const key = this.buildKey(speakerId);
         const data = await this.redisClient.hgetall(key);
@@ -136,6 +150,21 @@ class MulingstreamSpeakerManager {
             await this.cleanIndexes(speakerId);
             return false;
         }
+        /*
+         * Drop the mapping for the socket this record CURRENTLY holds, before
+         * the hash goes.
+         *
+         * cleanIndexes can only delete the socket baked into the speakerId,
+         * which is the socket the record was created with. A record that has
+         * been through a reconnect self-heal holds a different one in its
+         * field, and nothing else will ever delete that key: it would sit
+         * pointing at a deleted speaker until its TTL, and getSpeakerBySocketId
+         * would resolve a socket to a record that no longer exists.
+         */
+        const currentSocketId = data.socketId;
+        if (currentSocketId) {
+            await this.redisClient.del(`socket:${currentSocketId}:speaker`);
+        }
         await this.redisClient.del(key);
         await this.cleanIndexes(speakerId);
         return true;
@@ -231,12 +260,37 @@ class MulingstreamSpeakerManager {
     /**
      * Update socketId for a speaker (called by heartbeat self-heal when reconnect creates a new socket).
      * Mirrors the listener-side self-heal pattern — see MULINGSTREAM_RELIABILITY_ROADMAP.md §0.2.
+     *
+     * ─── THE MAPPING MOVES WITH THE FIELD, OR THE RECORD BECOMES A GHOST ───
+     *
+     * This used to rewrite the field alone, and that one omission is where
+     * every ghost speaker came from. `socket:<id>:speaker` is how a socket is
+     * resolved back to its speaker, and it is how disconnect, leave and both
+     * cleanup sweeps find the record they mean to delete. Leave it pointing at
+     * the OLD socket and the record becomes unreachable from the socket that
+     * actually owns it: the speaker's own disconnect finds nothing to remove,
+     * so the record survives its socket and lives out the 24 hour TTL.
+     *
+     * Room 500032 held four of them on 2026-08-27, one per Go Live that day,
+     * and three had a socketId field that did not match the socket in their own
+     * key: the signature of exactly this. They are not harmless. Ghosts inflate
+     * every "is anyone still in this room" count, and cleaning one up is what
+     * told a live congregation the speaker had left.
      */
     async updateSocketId(speakerId, newSocketId) {
         const speaker = await this.getSpeakerBySpeakerId(speakerId);
         if (speaker === null)
             return false;
+        const previousSocketId = speaker.socketId;
         await this.redisClient.hset(this.buildKey(speakerId), { socketId: newSocketId });
+        // Old mapping first: if the process dies between the two, an absent
+        // mapping is recoverable (the next heartbeat re-heals it) while a
+        // mapping pointing at the wrong record is not.
+        if (previousSocketId && previousSocketId !== newSocketId) {
+            await this.redisClient.del(`socket:${previousSocketId}:speaker`);
+        }
+        await this.redisClient.set(`socket:${newSocketId}:speaker`, speakerId);
+        await this.redisClient.expire(`socket:${newSocketId}:speaker`, EXPIRATION);
         return true;
     }
     async updateTargetLanguages(socketId, languages) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mulingai-npm/redis",
-    "version": "3.42.0",
+    "version": "3.43.1",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "repository": {