dubs-server 1.0.0

package/services/gamesCacheService.js

@@ -0,0 +1,539 @@
+/**
+ * Games Cache Service - Redis-backed high-performance games list layer
+ *
+ * Architecture (per-user, like notificationCacheService):
+ * - Redis Sorted Set: user_games:{walletAddress} → game IDs sorted by joinedAt timestamp
+ * - Redis Hash: user_game:{walletAddress}:{gameId} → trimmed game data (list-view fields only)
+ * - No TTL: cache persists until explicitly invalidated. Kept in sync via write-through
+ *   on create, join, resolve, and claim operations.
+ *
+ * Each user gets their own copy of game data (includes user-specific fields like
+ * claimedAt, teamChoice, etc.). This matches the notificationCacheService pattern
+ * and avoids cross-user concerns.
+ *
+ * Gracefully falls back to PostgreSQL when Redis is unavailable.
+ */
+
+const redisService = require('./redisService');
+
+// Key prefixes
+const KEYS = {
+  USER_GAMES: (wallet) => `user_games:${wallet}`,
+  GAME: (wallet, gameId) => `user_game:${wallet}:${gameId}`,
+};
+
+// Maximum games to cache per user
+const MAX_CACHED_GAMES = 50;
+
+/**
+ * Fields stored in the game hash (trimmed from the full 30+ field response).
+ * Complex objects (arrays, objects) are JSON-stringified.
+ */
+function serializeGameForCache(gameData) {
+  return {
+    gameId: gameData.gameId || '',
+    gameAddress: gameData.gameAddress || '',
+    title: gameData.title || '',
+    matchupImageUrl: gameData.matchupImageUrl || '',
+    imageUrl: gameData.imageUrl || '',
+    gameType: gameData.gameType || '',
+    buyIn: (gameData.buyIn ?? 0).toString(),
+    gameMode: (gameData.gameMode ?? 0).toString(),
+    createdBy: gameData.createdBy || '',
+    teamChoice: gameData.teamChoice || '',
+    claimedAt: gameData.claimedAt || '',
+    isLocked: gameData.isLocked ? '1' : '0',
+    isResolved: gameData.isResolved ? '1' : '0',
+    automaticStatus: gameData.automaticStatus || '',
+    status: gameData.status || '',
+    lockTimestamp: (gameData.lockTimestamp ?? '').toString(),
+    maxPlayers: (gameData.maxPlayers ?? 0).toString(),
+    // Arrays → JSON
+    homeTeamPlayers: JSON.stringify(gameData.homeTeamPlayers || []),
+    awayTeamPlayers: JSON.stringify(gameData.awayTeamPlayers || []),
+    drawTeamPlayers: JSON.stringify(gameData.drawTeamPlayers || []),
+    players: JSON.stringify(gameData.players || []),
+    // Extracted from sportsEvent (NOT the full blob)
+    strLeague: gameData.sportsEvent?.strLeague || gameData.strLeague || '',
+    strHomeTeam: gameData.sportsEvent?.strHomeTeam || gameData.homeTeam || '',
+    strAwayTeam: gameData.sportsEvent?.strAwayTeam || gameData.awayTeam || '',
+    strHomeTeamBadge: gameData.sportsEvent?.strHomeTeamBadge || gameData.homeTeamBadge || '',
+    strAwayTeamBadge: gameData.sportsEvent?.strAwayTeamBadge || gameData.awayTeamBadge || '',
+    strTimestamp: gameData.sportsEvent?.strTimestamp || gameData.strTimestamp || '',
+    // Final score fields
+    finalScoreWinner: gameData.finalScore?.winner ?? '',
+    finalScoreHome: (gameData.finalScore?.homeScore ?? '').toString(),
+    finalScoreAway: (gameData.finalScore?.awayScore ?? '').toString(),
+    // Connect4
+    winner: gameData.winner || '',
+    connect4Winner: gameData.connect4Winner || '',
+    // User-specific fields
+    role: gameData.role || '',
+    // CRITICAL: Convert Date objects to ISO strings before storing in Redis.
+    // Redis HSET calls .toString() on values, which produces "Thu Feb 12 2026 ..."
+    // format instead of ISO "2026-02-12T..." format. This caused inconsistent
+    // date formats between cache-served and DB-served responses.
+    joinedAt: gameData.joinedAt instanceof Date
+      ? gameData.joinedAt.toISOString()
+      : (gameData.joinedAt || ''),
+    mySignature: gameData.mySignature || '',
+    myExplorerUrl: gameData.myExplorerUrl || '',
+    walletType: gameData.walletType || '',
+    claimSignature: gameData.claimSignature || '',
+    claimExplorerUrl: gameData.claimExplorerUrl || '',
+    amountClaimed: (gameData.amountClaimed ?? '').toString(),
+    // Room name for billiards
+    roomName: gameData.roomName || '',
+  };
+}
+
+function deserializeGameFromCache(data) {
+  const finalScoreWinner = data.finalScoreWinner;
+  const finalScoreHome = data.finalScoreHome;
+  const finalScoreAway = data.finalScoreAway;
+
+  let finalScore = null;
+  if (finalScoreWinner !== '' || finalScoreHome !== '' || finalScoreAway !== '') {
+    finalScore = {
+      winner: finalScoreWinner === '' ? null : finalScoreWinner,
+      homeScore: finalScoreHome !== '' ? parseInt(finalScoreHome) || 0 : undefined,
+      awayScore: finalScoreAway !== '' ? parseInt(finalScoreAway) || 0 : undefined,
+    };
+  }
+
+  // Rebuild a minimal sportsEvent from extracted fields
+  const sportsEvent = {};
+  if (data.strLeague) sportsEvent.strLeague = data.strLeague;
+  if (data.strHomeTeam) sportsEvent.strHomeTeam = data.strHomeTeam;
+  if (data.strAwayTeam) sportsEvent.strAwayTeam = data.strAwayTeam;
+  if (data.strHomeTeamBadge) sportsEvent.strHomeTeamBadge = data.strHomeTeamBadge;
+  if (data.strAwayTeamBadge) sportsEvent.strAwayTeamBadge = data.strAwayTeamBadge;
+  if (data.strTimestamp) sportsEvent.strTimestamp = data.strTimestamp;
+  if (finalScore) sportsEvent.finalScore = finalScore;
+
+  return {
+    gameId: data.gameId,
+    gameAddress: data.gameAddress || null,
+    title: data.title || '',
+    imageUrl: data.imageUrl || null,
+    matchupImageUrl: data.matchupImageUrl || null,
+    gameType: data.gameType || '',
+    buyIn: parseFloat(data.buyIn) || 0,
+    maxPlayers: parseInt(data.maxPlayers) || 0,
+    gameMode: parseInt(data.gameMode) || 0,
+    createdBy: data.createdBy || null,
+    sportsEvent: Object.keys(sportsEvent).length > 0 ? sportsEvent : null,
+    homeTeam: data.strHomeTeam || undefined,
+    awayTeam: data.strAwayTeam || undefined,
+    league: data.strLeague || undefined,
+    homeTeamBadge: data.strHomeTeamBadge || undefined,
+    awayTeamBadge: data.strAwayTeamBadge || undefined,
+    strTimestamp: data.strTimestamp || undefined,
+    homeTeamPlayers: safeJsonParse(data.homeTeamPlayers) || [],
+    awayTeamPlayers: safeJsonParse(data.awayTeamPlayers) || [],
+    drawTeamPlayers: safeJsonParse(data.drawTeamPlayers) || [],
+    players: safeJsonParse(data.players) || [],
+    roomName: data.roomName || undefined,
+    lockTimestamp: data.lockTimestamp ? parseInt(data.lockTimestamp) || null : null,
+    isLocked: data.isLocked === '1',
+    isResolved: data.isResolved === '1',
+    automaticStatus: data.automaticStatus || null,
+    finalScore,
+    winner: data.winner || null,
+    connect4Winner: data.connect4Winner || null,
+    status: data.status || null,
+    // User-specific
+    role: data.role || null,
+    joinedAt: data.joinedAt || null,
+    teamChoice: data.teamChoice || null,
+    mySignature: data.mySignature || null,
+    myExplorerUrl: data.myExplorerUrl || null,
+    walletType: data.walletType || null,
+    claimedAt: data.claimedAt || null,
+    claimSignature: data.claimSignature || null,
+    claimExplorerUrl: data.claimExplorerUrl || null,
+    amountClaimed: data.amountClaimed ? parseFloat(data.amountClaimed) : null,
+  };
+}
+
+function safeJsonParse(str) {
+  if (!str) return null;
+  try {
+    return JSON.parse(str);
+  } catch {
+    return null;
+  }
+}
+
+class GamesCacheService {
+  constructor() {
+    this.enabled = false;
+  }
+
+  /**
+   * Initialize the cache service
+   * Called during server startup (after redisService.connect())
+   */
+  async initialize() {
+    // Redis connection is already established by notificationCacheService
+    this.enabled = redisService.isAvailable();
+    if (this.enabled) {
+      console.log('[GamesCache] Redis caching enabled');
+    } else {
+      console.log('[GamesCache] Running without Redis cache (PostgreSQL fallback)');
+    }
+    return this.enabled;
+  }
+
+  isEnabled() {
+    return this.enabled && redisService.isAvailable();
+  }
+
+  // ============================================
+  // WRITE OPERATIONS
+  // ============================================
+
+  /**
+   * Cache a game for a specific user.
+   * Called after saving a game to PostgreSQL.
+   */
+  async cacheGame(walletAddress, gameData) {
+    if (!this.isEnabled()) return false;
+
+    try {
+      const gameId = gameData.gameId;
+      const timestamp = gameData.joinedAt
+        ? new Date(gameData.joinedAt).getTime()
+        : Date.now();
+
+      const pipeline = redisService.pipeline();
+      if (!pipeline) return false;
+
+      // 1. Add to user's sorted set
+      pipeline.zadd(KEYS.USER_GAMES(walletAddress), timestamp, gameId);
+
+      // 2. Store game data as hash
+      pipeline.hset(KEYS.GAME(walletAddress, gameId), serializeGameForCache(gameData));
+
+      // 3. Trim sorted set to max size
+      pipeline.zremrangebyrank(KEYS.USER_GAMES(walletAddress), 0, -(MAX_CACHED_GAMES + 1));
+
+      await pipeline.exec();
+
+      console.log(`[GamesCache] Cached game ${gameId} for ${walletAddress.slice(0, 8)}...`);
+      return true;
+    } catch (error) {
+      console.error('[GamesCache] Error caching game:', error.message);
+      return false;
+    }
+  }
+
+  /**
+   * Partial update of a game hash for a specific user.
+   * Only updates the fields provided.
+   */
+  async updateGame(walletAddress, gameId, fields) {
+    if (!this.isEnabled()) return false;
+
+    try {
+      const key = KEYS.GAME(walletAddress, gameId);
+
+      // Check if hash exists
+      const exists = await redisService.exists(key);
+      if (!exists) return false;
+
+      // Build partial update object
+      const update = {};
+      if (fields.isLocked !== undefined) update.isLocked = fields.isLocked ? '1' : '0';
+      if (fields.isResolved !== undefined) update.isResolved = fields.isResolved ? '1' : '0';
+      if (fields.automaticStatus !== undefined) update.automaticStatus = fields.automaticStatus;
+      if (fields.status !== undefined) update.status = fields.status;
+      if (fields.claimedAt !== undefined) update.claimedAt = fields.claimedAt || '';
+      if (fields.claimSignature !== undefined) update.claimSignature = fields.claimSignature || '';
+      if (fields.claimExplorerUrl !== undefined) update.claimExplorerUrl = fields.claimExplorerUrl || '';
+      if (fields.amountClaimed !== undefined) update.amountClaimed = (fields.amountClaimed ?? '').toString();
+      if (fields.finalScoreWinner !== undefined) update.finalScoreWinner = fields.finalScoreWinner ?? '';
+      if (fields.finalScoreHome !== undefined) update.finalScoreHome = (fields.finalScoreHome ?? '').toString();
+      if (fields.finalScoreAway !== undefined) update.finalScoreAway = (fields.finalScoreAway ?? '').toString();
+      if (fields.homeTeamPlayers !== undefined) update.homeTeamPlayers = JSON.stringify(fields.homeTeamPlayers);
+      if (fields.awayTeamPlayers !== undefined) update.awayTeamPlayers = JSON.stringify(fields.awayTeamPlayers);
+      if (fields.drawTeamPlayers !== undefined) update.drawTeamPlayers = JSON.stringify(fields.drawTeamPlayers);
+      if (fields.winner !== undefined) update.winner = fields.winner || '';
+      if (fields.connect4Winner !== undefined) update.connect4Winner = fields.connect4Winner || '';
+
+      if (Object.keys(update).length === 0) return false;
+
+      await redisService.hset(key, update);
+      return true;
+    } catch (error) {
+      console.error('[GamesCache] Error updating game:', error.message);
+      return false;
+    }
+  }
+
+  /**
+   * Update a game for ALL users who have it cached.
+   * Used for shared state changes (lock, resolve) that affect all participants.
+   */
+  async updateGameForAllUsers(gameId, playerWallets, fields) {
+    if (!this.isEnabled()) return false;
+
+    try {
+      for (const wallet of playerWallets) {
+        await this.updateGame(wallet, gameId, fields);
+      }
+      return true;
+    } catch (error) {
+      console.error('[GamesCache] Error updating game for all users:', error.message);
+      return false;
+    }
+  }
+
+  /**
+   * Add a player to a game (when they join).
+   * Adds the game to the joiner's sorted set and creates their game hash.
+   * Also updates the team arrays in existing users' game hashes.
+   */
+  async addPlayerToGame(gameId, walletAddress, gameData, existingPlayerWallets) {
+    if (!this.isEnabled()) return false;
+
+    try {
+      // 1. Cache the game for the joining user
+      await this.cacheGame(walletAddress, gameData);
+
+      // 2. Update team arrays for all existing players
+      if (existingPlayerWallets && existingPlayerWallets.length > 0) {
+        const teamUpdate = {};
+        if (gameData.homeTeamPlayers) teamUpdate.homeTeamPlayers = gameData.homeTeamPlayers;
+        if (gameData.awayTeamPlayers) teamUpdate.awayTeamPlayers = gameData.awayTeamPlayers;
+        if (gameData.drawTeamPlayers) teamUpdate.drawTeamPlayers = gameData.drawTeamPlayers;
+
+        for (const existingWallet of existingPlayerWallets) {
+          if (existingWallet !== walletAddress) {
+            await this.updateGame(existingWallet, gameId, teamUpdate);
+          }
+        }
+      }
+
+      return true;
+    } catch (error) {
+      console.error('[GamesCache] Error adding player to game:', error.message);
+      return false;
+    }
+  }
+
+  // ============================================
+  // READ OPERATIONS
+  // ============================================
+
+  /**
+   * Get paginated games from cache.
+   * Uses cursor-based pagination with timestamps.
+   *
+   * @returns {Object|null} - { games, nextCursor, hasMore } or null on cache miss
+   */
+  async getGames(walletAddress, { limit = 10, cursor = null } = {}) {
+    if (!this.isEnabled()) return null;
+
+    // CRITICAL: Only serve the FIRST page from cache. Cursor (Load More) pages
+    // MUST always go to PostgreSQL. The cache is inherently incomplete — it holds
+    // at most MAX_CACHED_GAMES (50) items, warmed from the first page only.
+    // Serving cursor pages from an incomplete cache causes "missing games" where
+    // Load More returns a handful of games then stops, hiding hundreds of games.
+    if (cursor) {
+      console.log(`[GamesCache] Cursor page — bypassing cache for ${walletAddress.slice(0, 8)}...`);
+      return null;
+    }
+
+    try {
+      // Check if user has cached games
+      const exists = await redisService.exists(KEYS.USER_GAMES(walletAddress));
+      if (!exists) {
+        console.log(`[GamesCache] Cache miss for ${walletAddress.slice(0, 8)}...`);
+        return null;
+      }
+
+      // Check total cached count to know if cache is complete enough to serve first page
+      const totalCached = await redisService.zcard(KEYS.USER_GAMES(walletAddress));
+
+      // Get game IDs from sorted set (first page only)
+      let gameIds = await redisService.zrevrange(
+        KEYS.USER_GAMES(walletAddress),
+        0,
+        limit // Returns limit+1 items (indices 0 through limit, inclusive)
+      );
+
+      if (!gameIds || gameIds.length === 0) {
+        return { games: [], nextCursor: null, hasMore: false };
+      }
+
+      // If we don't have more than limit items cached, cache may be incomplete
+      // (warmed from first page only). Fall through to PostgreSQL.
+      const hasMore = gameIds.length > limit;
+      if (!hasMore && totalCached <= limit) {
+        return null;
+      }
+      if (hasMore) {
+        gameIds = gameIds.slice(0, limit);
+      }
+
+      // Batch fetch game data
+      const gameKeys = gameIds.map(id => KEYS.GAME(walletAddress, id));
+      const gamesData = await redisService.hmgetall(gameKeys);
+
+      if (!gamesData) {
+        return null; // Cache miss on individual games
+      }
+
+      // Check for missing game hashes (orphaned sorted set entries).
+      // If ANY hashes are missing, the cache is inconsistent — fall through to DB.
+      const missingCount = gamesData.filter(data => data === null).length;
+      if (missingCount > 0) {
+        console.log(`[GamesCache] ${missingCount}/${gameIds.length} game hashes missing for ${walletAddress.slice(0, 8)}... — cache inconsistent, falling through to DB`);
+        // Clean up orphaned sorted set entries in the background
+        const orphanedIds = gameIds.filter((id, i) => gamesData[i] === null);
+        this._cleanupOrphanedEntries(walletAddress, orphanedIds).catch(() => {});
+        return null;
+      }
+
+      // Parse and format games
+      const games = gamesData
+        .map(data => deserializeGameFromCache(data));
+
+      // Get next cursor (timestamp of last item)
+      let nextCursor = null;
+      if (hasMore && games.length > 0) {
+        const lastGame = games[games.length - 1];
+        const lastGameId = lastGame.gameId;
+        // Get the score (timestamp) for the last game
+        const score = await redisService.zscore(KEYS.USER_GAMES(walletAddress), lastGameId);
+        if (score) {
+          nextCursor = score.toString();
+        }
+      }
+
+      return { games, nextCursor, hasMore };
+    } catch (error) {
+      console.error('[GamesCache] Error getting games:', error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Bulk populate cache from PostgreSQL (called on first cache miss).
+   */
+  async warmCache(walletAddress, games) {
+    if (!this.isEnabled() || games.length === 0) return false;
+
+    try {
+      const pipeline = redisService.pipeline();
+      if (!pipeline) return false;
+
+      for (const game of games) {
+        const gameId = game.gameId;
+        const timestamp = game.joinedAt
+          ? new Date(game.joinedAt).getTime()
+          : Date.now();
+
+        pipeline.zadd(KEYS.USER_GAMES(walletAddress), timestamp, gameId);
+        pipeline.hset(KEYS.GAME(walletAddress, gameId), serializeGameForCache(game));
+      }
+
+      // Trim to max size
+      pipeline.zremrangebyrank(KEYS.USER_GAMES(walletAddress), 0, -(MAX_CACHED_GAMES + 1));
+
+      await pipeline.exec();
+
+      console.log(`[GamesCache] Warmed cache with ${games.length} games for ${walletAddress.slice(0, 8)}...`);
+      return true;
+    } catch (error) {
+      console.error('[GamesCache] Error warming cache:', error.message);
+      return false;
+    }
+  }
+
+  /**
+   * Invalidate user's game cache.
+   */
+  async invalidateUserCache(walletAddress) {
+    if (!this.isEnabled()) return false;
+
+    try {
+      const gameIds = await redisService.zrevrange(KEYS.USER_GAMES(walletAddress), 0, -1);
+
+      if (gameIds && gameIds.length > 0) {
+        const keysToDelete = gameIds.map(id => KEYS.GAME(walletAddress, id));
+        keysToDelete.push(KEYS.USER_GAMES(walletAddress));
+        await redisService.del(...keysToDelete);
+      }
+
+      console.log(`[GamesCache] Invalidated cache for ${walletAddress.slice(0, 8)}...`);
+      return true;
+    } catch (error) {
+      console.error('[GamesCache] Error invalidating cache:', error.message);
+      return false;
+    }
+  }
+
+  /**
+   * Flush ALL games cache data from Redis.
+   * Safe to call in production — all requests will fall through to PostgreSQL
+   * and re-warm the cache with correct data on next access.
+   * @returns {{ deletedKeys: number }} - Number of keys deleted
+   */
+  async flushAllGamesCaches() {
+    if (!this.isEnabled()) return { deletedKeys: 0 };
+
+    try {
+      // Use SCAN to find all games cache keys (non-blocking, safe for production)
+      const sortedSetKeys = await redisService.scanKeys('user_games:*');
+      const hashKeys = await redisService.scanKeys('user_game:*');
+      const allKeys = [...sortedSetKeys, ...hashKeys];
+
+      if (allKeys.length === 0) {
+        console.log('[GamesCache] No games cache keys found to flush');
+        return { deletedKeys: 0 };
+      }
+
+      // Delete in batches of 500 to avoid overloading Redis
+      const batchSize = 500;
+      for (let i = 0; i < allKeys.length; i += batchSize) {
+        const batch = allKeys.slice(i, i + batchSize);
+        await redisService.del(...batch);
+      }
+
+      console.log(`[GamesCache] Flushed ${allKeys.length} keys (${sortedSetKeys.length} sorted sets, ${hashKeys.length} game hashes)`);
+      return { deletedKeys: allKeys.length };
+    } catch (error) {
+      console.error('[GamesCache] Error flushing all caches:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Remove orphaned game IDs from the sorted set (IDs whose hash data is missing).
+   * Called in the background when inconsistency is detected during reads.
+   */
+  async _cleanupOrphanedEntries(walletAddress, orphanedGameIds) {
+    if (!this.isEnabled() || orphanedGameIds.length === 0) return;
+
+    try {
+      const pipeline = redisService.pipeline();
+      if (!pipeline) return;
+
+      for (const gameId of orphanedGameIds) {
+        pipeline.zrem(KEYS.USER_GAMES(walletAddress), gameId);
+      }
+      await pipeline.exec();
+
+      console.log(`[GamesCache] Cleaned up ${orphanedGameIds.length} orphaned entries for ${walletAddress.slice(0, 8)}...`);
+    } catch (error) {
+      console.error('[GamesCache] Error cleaning orphaned entries:', error.message);
+    }
+  }
+}
+
+// Singleton instance
+const gamesCacheService = new GamesCacheService();
+
+module.exports = gamesCacheService;