@mulingai-npm/redis 3.18.0 → 3.18.4

package/dist/managers/chunk-sequencer-manager.d.ts

@@ -0,0 +1,90 @@
+import { RedisClient } from '../redis-client';
+/**
+ * Chunk waiting room entry
+ */
+export interface WaitingChunk {
+    chunkNumber: number;
+    arrivedAt: number;
+    language: string;
+}
+/**
+ * Sequencer configuration (passed from settings)
+ */
+export interface SequencerConfig {
+    timeoutMs: number;
+    maxWaitingRoom: number;
+    maxGapSize: number;
+}
+/**
+ * Chunk Sequencer Manager
+ * Maintains strict chunk ordering per room per language
+ * Holds out-of-order chunks in a waiting room with timeout
+ */
+export declare class ChunkSequencerManager {
+    private redisClient;
+    constructor(redisClient: RedisClient);
+    /**
+     * Redis key for expected chunk number
+     * Format: sequencer:{roomId}:{language}:expectedChunk
+     */
+    private expectedChunkKey;
+    /**
+     * Redis key for waiting room (ZSET)
+     * Format: sequencer:{roomId}:{language}:waiting
+     * Score: arrivalTimestamp
+     * Member: chunkNumber
+     */
+    private waitingRoomKey;
+    /**
+     * Get the next expected chunk number for a room/language
+     * Returns 1 if not initialized yet (first chunk)
+     */
+    getExpectedChunk(roomId: string, language: string): Promise<number>;
+    /**
+     * Set the expected chunk number
+     */
+    setExpectedChunk(roomId: string, language: string, chunkNumber: number): Promise<void>;
+    /**
+     * Increment the expected chunk number
+     */
+    incrementExpectedChunk(roomId: string, language: string): Promise<number>;
+    /**
+     * Add a chunk to the waiting room
+     * Uses ZSET with timestamp as score for timeout checking
+     */
+    addToWaitingRoom(roomId: string, chunkNumber: number, language: string): Promise<void>;
+    /**
+     * Get all chunks in waiting room sorted by arrival time (oldest first)
+     */
+    getWaitingChunks(roomId: string, language: string): Promise<WaitingChunk[]>;
+    /**
+     * Remove a chunk from the waiting room
+     */
+    removeFromWaitingRoom(roomId: string, chunkNumber: number, language: string): Promise<void>;
+    /**
+     * Clear the entire waiting room for a room/language
+     * Used when skipping ahead (Option C)
+     */
+    clearWaitingRoom(roomId: string, language: string): Promise<number>;
+    /**
+     * Get the size of the waiting room
+     */
+    getWaitingRoomSize(roomId: string, language: string): Promise<number>;
+    /**
+     * Check if a specific chunk is in the waiting room
+     */
+    isChunkInWaitingRoom(roomId: string, chunkNumber: number, language: string): Promise<boolean>;
+    /**
+     * Get chunks that have exceeded the timeout
+     */
+    getTimedOutChunks(roomId: string, language: string, timeoutMs: number): Promise<WaitingChunk[]>;
+    /**
+     * Clean up all sequencer state for a room/language
+     * Called when room ends
+     */
+    cleanupSequencerState(roomId: string, language: string): Promise<void>;
+    /**
+     * Clean up all sequencer state for an entire room (all languages)
+     */
+    cleanupRoomSequencerState(roomId: string): Promise<void>;
+}

package/dist/managers/chunk-sequencer-manager.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChunkSequencerManager = void 0;
+/**
+ * Chunk Sequencer Manager
+ * Maintains strict chunk ordering per room per language
+ * Holds out-of-order chunks in a waiting room with timeout
+ */
+class ChunkSequencerManager {
+    constructor(redisClient) {
+        this.redisClient = redisClient;
+    }
+    /**
+     * Redis key for expected chunk number
+     * Format: sequencer:{roomId}:{language}:expectedChunk
+     */
+    expectedChunkKey(roomId, language) {
+        return `sequencer:${roomId}:${language}:expectedChunk`;
+    }
+    /**
+     * Redis key for waiting room (ZSET)
+     * Format: sequencer:{roomId}:{language}:waiting
+     * Score: arrivalTimestamp
+     * Member: chunkNumber
+     */
+    waitingRoomKey(roomId, language) {
+        return `sequencer:${roomId}:${language}:waiting`;
+    }
+    /**
+     * Get the next expected chunk number for a room/language
+     * Returns 1 if not initialized yet (first chunk)
+     */
+    async getExpectedChunk(roomId, language) {
+        const key = this.expectedChunkKey(roomId, language);
+        const value = await this.redisClient.get(key);
+        if (!value) {
+            // Initialize to 1 for first chunk
+            await this.redisClient.set(key, '1');
+            await this.redisClient.expire(key, 3600); // 1 hour TTL
+            return 1;
+        }
+        return parseInt(value, 10);
+    }
+    /**
+     * Set the expected chunk number
+     */
+    async setExpectedChunk(roomId, language, chunkNumber) {
+        const key = this.expectedChunkKey(roomId, language);
+        await this.redisClient.set(key, chunkNumber.toString());
+        await this.redisClient.expire(key, 3600); // 1 hour TTL
+    }
+    /**
+     * Increment the expected chunk number
+     */
+    async incrementExpectedChunk(roomId, language) {
+        const key = this.expectedChunkKey(roomId, language);
+        const newValue = await this.redisClient.incr(key);
+        await this.redisClient.expire(key, 3600); // 1 hour TTL
+        return newValue;
+    }
+    /**
+     * Add a chunk to the waiting room
+     * Uses ZSET with timestamp as score for timeout checking
+     */
+    async addToWaitingRoom(roomId, chunkNumber, language) {
+        const key = this.waitingRoomKey(roomId, language);
+        const now = Date.now();
+        await this.redisClient.zadd(key, now, chunkNumber.toString());
+        await this.redisClient.expire(key, 3600); // 1 hour TTL
+    }
+    /**
+     * Get all chunks in waiting room sorted by arrival time (oldest first)
+     */
+    async getWaitingChunks(roomId, language) {
+        const key = this.waitingRoomKey(roomId, language);
+        // Get all members with scores (ZRANGE with WITHSCORES)
+        const results = await this.redisClient.zrangeWithScores(key, 0, -1);
+        if (!results || results.length === 0) {
+            return [];
+        }
+        const chunks = [];
+        for (const { value, score } of results) {
+            chunks.push({
+                chunkNumber: parseInt(value, 10),
+                arrivedAt: score,
+                language
+            });
+        }
+        return chunks;
+    }
+    /**
+     * Remove a chunk from the waiting room
+     */
+    async removeFromWaitingRoom(roomId, chunkNumber, language) {
+        const key = this.waitingRoomKey(roomId, language);
+        await this.redisClient.zrem(key, chunkNumber.toString());
+    }
+    /**
+     * Clear the entire waiting room for a room/language
+     * Used when skipping ahead (Option C)
+     */
+    async clearWaitingRoom(roomId, language) {
+        const key = this.waitingRoomKey(roomId, language);
+        const count = await this.redisClient.zcard(key);
+        await this.redisClient.del(key);
+        return count;
+    }
+    /**
+     * Get the size of the waiting room
+     */
+    async getWaitingRoomSize(roomId, language) {
+        const key = this.waitingRoomKey(roomId, language);
+        return await this.redisClient.zcard(key);
+    }
+    /**
+     * Check if a specific chunk is in the waiting room
+     */
+    async isChunkInWaitingRoom(roomId, chunkNumber, language) {
+        const key = this.waitingRoomKey(roomId, language);
+        const score = await this.redisClient.zscore(key, chunkNumber.toString());
+        return score !== null;
+    }
+    /**
+     * Get chunks that have exceeded the timeout
+     */
+    async getTimedOutChunks(roomId, language, timeoutMs) {
+        const allWaiting = await this.getWaitingChunks(roomId, language);
+        const now = Date.now();
+        return allWaiting.filter(chunk => {
+            const age = now - chunk.arrivedAt;
+            return age > timeoutMs;
+        });
+    }
+    /**
+     * Clean up all sequencer state for a room/language
+     * Called when room ends
+     */
+    async cleanupSequencerState(roomId, language) {
+        const expectedKey = this.expectedChunkKey(roomId, language);
+        const waitingKey = this.waitingRoomKey(roomId, language);
+        await this.redisClient.del(expectedKey);
+        await this.redisClient.del(waitingKey);
+    }
+    /**
+     * Clean up all sequencer state for an entire room (all languages)
+     */
+    async cleanupRoomSequencerState(roomId) {
+        // Find all sequencer keys for this room
+        const pattern = `sequencer:${roomId}:*`;
+        const keys = await this.redisClient.keys(pattern);
+        if (keys && keys.length > 0) {
+            await Promise.all(keys.map(key => this.redisClient.del(key)));
+        }
+    }
+}
+exports.ChunkSequencerManager = ChunkSequencerManager;

package/dist/managers/demo-state-manager.d.ts

@@ -112,4 +112,10 @@ export declare class DemoStateManager {
      * Call this periodically to remove demos that should have ended
      */
     cleanupStaleDemos(): Promise<number>;
+    /**
+     * Cleanup ALL demo states on startup
+     * This prevents stale states from service restarts
+     * Call this when the service initializes
+     */
+    cleanupAllDemosOnStartup(): Promise<number>;
 }

package/dist/managers/demo-state-manager.js

@@ -278,5 +278,30 @@ class DemoStateManager {
         }
         return cleaned;
     }
+    /**
+     * Cleanup ALL demo states on startup
+     * This prevents stale states from service restarts
+     * Call this when the service initializes
+     */
+    async cleanupAllDemosOnStartup() {
+        console.log('[Demo State Manager] Cleaning up all demo states from previous run...');
+        const activeDemoIds = await this.getActiveDemoRooms();
+        if (activeDemoIds.length === 0) {
+            console.log('[Demo State Manager] No stale demo states found');
+            return 0;
+        }
+        console.log(`[Demo State Manager] Found ${activeDemoIds.length} stale demo state(s): ${activeDemoIds.join(', ')}`);
+        // Delete all demo states
+        const pipeline = this.redisClient.pipeline();
+        for (const roomId of activeDemoIds) {
+            const key = this.getStateKey(roomId);
+            pipeline.del(key);
+        }
+        // Clear the active set
+        pipeline.del(this.ACTIVE_DEMOS_SET);
+        await pipeline.exec();
+        console.log(`[Demo State Manager] ✅ Cleaned up ${activeDemoIds.length} stale demo state(s)`);
+        return activeDemoIds.length;
+    }
 }
 exports.DemoStateManager = DemoStateManager;

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

@@ -108,5 +108,17 @@ export declare class MulingstreamChunkManager {
         isEmitted?: boolean;
     }): Promise<MulingstreamChunkData | null>;
     areTranslationsProcessed(roomId: string, n: number): Promise<boolean>;
+    /**
+     * @deprecated This function is replaced by ChunkSequencer (5-sequencer-handler.ts)
+     *
+     * This function tried to sort and emit chunks, but it discarded late-arriving chunks
+     * instead of waiting for them with a timeout. The new ChunkSequencer provides:
+     * - Waiting room for out-of-order chunks
+     * - Configurable timeout (20 seconds)
+     * - Option C overflow handling (gap skip)
+     * - Per-room-per-language isolation
+     *
+     * DO NOT USE THIS FUNCTION - use sequenceAndPublish() from 5-sequencer-handler.ts instead
+     */
     getAllReadyTts(roomId: string, lang: string): Promise<MulingstreamChunkData[]>;
 }

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

@@ -298,6 +298,18 @@ class MulingstreamChunkManager {
         const c = await this.getMulingstreamChunkById(roomId, n);
         return !!c && Object.values(c.translation).every((t) => t.status !== 'INIT');
     }
+    /**
+     * @deprecated This function is replaced by ChunkSequencer (5-sequencer-handler.ts)
+     *
+     * This function tried to sort and emit chunks, but it discarded late-arriving chunks
+     * instead of waiting for them with a timeout. The new ChunkSequencer provides:
+     * - Waiting room for out-of-order chunks
+     * - Configurable timeout (20 seconds)
+     * - Option C overflow handling (gap skip)
+     * - Per-room-per-language isolation
+     *
+     * DO NOT USE THIS FUNCTION - use sequenceAndPublish() from 5-sequencer-handler.ts instead
+     */
     async getAllReadyTts(roomId, lang) {
         var _a;
         const chunks = (_a = (await this.getMulingstreamChunksByRoom(roomId))) !== null && _a !== void 0 ? _a : [];

package/dist/redis-client.d.ts

@@ -24,6 +24,13 @@ export declare class RedisClient {
     zremrangebyrank(key: string, start: number, stop: number): Promise<number>;
     zrangebyscore(key: string, min: number | string, max: number | string): Promise<string[]>;
     zrem(key: string, ...members: string[]): Promise<number>;
+    zrangeWithScores(key: string, start: number, stop: number): Promise<Array<{
+        value: string;
+        score: number;
+    }>>;
+    zcard(key: string): Promise<number>;
+    zscore(key: string, member: string): Promise<number | null>;
+    incr(key: string): Promise<number>;
     scan(cursor: number, pattern: string, count?: number): Promise<[string, string[]]>;
     keys(pattern: string): Promise<string[]>;
     pipeline(): ReturnType<IORedis['pipeline']>;

package/dist/redis-client.js

@@ -67,6 +67,27 @@ class RedisClient {
     async zrem(key, ...members) {
         return this.client.zrem(key, members);
     }
+    async zrangeWithScores(key, start, stop) {
+        const results = await this.client.zrange(key, start, stop, 'WITHSCORES');
+        const parsed = [];
+        for (let i = 0; i < results.length; i += 2) {
+            parsed.push({
+                value: results[i],
+                score: parseFloat(results[i + 1])
+            });
+        }
+        return parsed;
+    }
+    async zcard(key) {
+        return this.client.zcard(key);
+    }
+    async zscore(key, member) {
+        const score = await this.client.zscore(key, member);
+        return score !== null ? parseFloat(score) : null;
+    }
+    async incr(key) {
+        return this.client.incr(key);
+    }
     async scan(cursor, pattern, count = 1000) {
         return this.client.scan(cursor, 'MATCH', pattern, 'COUNT', count);
     }

package/package.json

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