feat(websockets): add Redis adapter for horizontal scaling

Add Redis-based Socket.IO adapter to enable WebSocket communication across multiple API instances. This allows horizontal scaling by using Redis pub/sub for message broadcasting between servers.

The adapter falls back to in-memory adapter when Redis is unavailable (e.g., development environments). Also added proper TypeScript types for third-party emote APIs in shared package for better type safety.

Author: christopherldo

apps/api/package.json

@@ -22,11 +22,13 @@
     "@nestjs/swagger": "^11.4.2",
     "@nestjs/terminus": "^11.1.1",
     "@nestjs/websockets": "^11.1.19",
+    "@socket.io/redis-adapter": "^8.3.0",
     "@twitch-chat-visualizer/shared": "workspace:*",
     "axios": "^1.15.2",
     "cache-manager": "^7.2.8",
     "cache-manager-redis-yet": "^5.1.5",
     "fastify": "^5.0.0",
+    "ioredis": "^5.10.1",
     "nestjs-pino": "^4.6.1",
     "pino-http": "^11.0.0",
     "pino-pretty": "^13.1.3",

apps/api/src/adapters/redis-io.adapter.ts

@@ -0,0 +1,30 @@
+import { IoAdapter } from '@nestjs/platform-socket.io';
+import { ServerOptions } from 'socket.io';
+import { createAdapter } from '@socket.io/redis-adapter';
+import { Redis } from 'ioredis';
+
+export class RedisIoAdapter extends IoAdapter {
+  private adapterConstructor: ReturnType<typeof createAdapter>;
+
+  async connectToRedis(): Promise<void> {
+    const pubClient = new Redis(process.env.REDIS_URL || 'redis://localhost:6379');
+    const subClient = pubClient.duplicate();
+
+    await Promise.all([pubClient.connect(), subClient.connect()]).catch((err) => {
+      // Ignorando erros de conexão inicial para permitir fallback caso redis não exista no ambiente dev
+      console.warn('⚠️  Redis for Socket.IO failed to connect. Falling back to memory adapter.', err.message);
+    });
+
+    if (pubClient.status === 'ready' && subClient.status === 'ready') {
+      this.adapterConstructor = createAdapter(pubClient, subClient);
+    }
+  }
+
+  createIOServer(port: number, options?: ServerOptions): any {
+    const server = super.createIOServer(port, options);
+    if (this.adapterConstructor) {
+      server.adapter(this.adapterConstructor);
+    }
+    return server;
+  }
+}

apps/api/src/cache/emote-cache.service.ts

@@ -5,13 +5,7 @@ import { TokenManagerService } from '../auth/token-manager.service';
 import { ConfigService } from '@nestjs/config';
 import axios from 'axios';
 import qs from 'qs';
-
-export interface ChannelAssets {
-  globalBadges: any;
-  channelBadges: any;
-  bttvEmotes: any[];
-  ffzEmotes: any[];
-}
+import { ChannelAssets, BttvEmote, FfzEmote } from '@twitch-chat-visualizer/shared';
 
 @Injectable()
 export class EmoteCacheService {
@@ -86,7 +80,7 @@ export class EmoteCacheService {
       const globalBadges = globalBadgesRes.status === 'fulfilled' ? globalBadgesRes.value.data : null;
       const channelBadges = channelBadgesRes.status === 'fulfilled' ? channelBadgesRes.value.data : null;
 
-      const bttvEmotes: any[] = [];
+      const bttvEmotes: BttvEmote[] = [];
       if (bttvChannelRes.status === 'fulfilled') {
         bttvEmotes.push(...(bttvChannelRes.value.data.channelEmotes || []));
         bttvEmotes.push(...(bttvChannelRes.value.data.sharedEmotes || []));
@@ -95,7 +89,7 @@ export class EmoteCacheService {
         bttvEmotes.push(...(bttvGlobalRes.value.data || []));
       }
 
-      const ffzEmotes: any[] = [];
+      const ffzEmotes: FfzEmote[] = [];
       if (ffzChannelRes.status === 'fulfilled') {
         const sets = ffzChannelRes.value.data.sets;
         const setKey = Object.keys(sets)[0];

apps/api/src/gateways/chat.gateway.ts

@@ -11,6 +11,7 @@ import { Server, Socket } from 'socket.io';
 import { Logger } from '@nestjs/common';
 import { TwitchService, TwitchMessagePayload } from '../twitch/twitch.service';
 import { EmoteCacheService } from '../cache/emote-cache.service';
+import { BttvEmote, FfzEmote, TwitchBadgesResponse } from '@twitch-chat-visualizer/shared';
 
 @WebSocketGateway({
   cors: {
@@ -82,15 +83,15 @@ export class ChatGateway implements OnGatewayConnection, OnGatewayDisconnect {
     client.emit('redirect', link);
   }
 
-  private findBadgeUrl(badgesPayload: any, setId: string, versionId: string): string | null {
+  private findBadgeUrl(badgesPayload: TwitchBadgesResponse | null | undefined, setId: string, versionId: string): string | null {
     if (!badgesPayload || !badgesPayload.data) return null;
-    const set = badgesPayload.data.find((s: any) => s.set_id === setId);
+    const set = badgesPayload.data.find((s) => s.set_id === setId);
     if (!set) return null;
-    const version = set.versions.find((v: any) => v.id === versionId);
+    const version = set.versions.find((v) => v.id === versionId);
     return version ? (version.image_url_4x || version.image_url_2x || version.image_url_1x) : null;
   }
 
-  private parseEmotes(message: string, emotesRaw: string | undefined, bttvEmotes: any[] = [], ffzEmotes: any[] = []): string {
+  private parseEmotes(message: string, emotesRaw: string | undefined, bttvEmotes: BttvEmote[] = [], ffzEmotes: FfzEmote[] = []): string {
     if (!message) return '';
 
     let messageWords = message.split(' ');
@@ -119,13 +120,13 @@ export class ChatGateway implements OnGatewayConnection, OnGatewayDisconnect {
       }
 
       // Checa BTTV
-      const bttvMatch = bttvEmotes.find((e: any) => e.code === word);
+      const bttvMatch = bttvEmotes.find((e) => e.code === word);
       if (bttvMatch) {
         return `<img src="https://cdn.betterttv.net/emote/${bttvMatch.id}/1x" alt="${word}">`;
       }
 
       // Checa FFZ
-      const ffzMatch = ffzEmotes.find((e: any) => e.name === word);
+      const ffzMatch = ffzEmotes.find((e) => e.name === word);
       if (ffzMatch) {
         return `<img src="https://cdn.frankerfacez.com/emote/${ffzMatch.id}/1" alt="${word}">`;
       }

apps/api/src/main.ts

@@ -3,6 +3,7 @@ import { FastifyAdapter, NestFastifyApplication } from '@nestjs/platform-fastify
 import { AppModule } from './app.module';
 import { Logger } from 'nestjs-pino';
 import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import { RedisIoAdapter } from './adapters/redis-io.adapter';
 
 async function bootstrap() {
   const app = await NestFactory.create<NestFastifyApplication>(
@@ -13,6 +14,11 @@ async function bootstrap() {
 
   app.useLogger(app.get(Logger));
 
+  // Configure Redis Socket.io Adapter for Horizontal Scaling (Stateless)
+  const redisIoAdapter = new RedisIoAdapter(app);
+  await redisIoAdapter.connectToRedis();
+  app.useWebSocketAdapter(redisIoAdapter);
+
   const port = process.env.PORT || 3000;
 
   // Swagger Configuration

packages/shared/src/index.ts

@@ -16,6 +16,43 @@ export interface Emote {
   url: string;
 }
 
+export interface BttvEmote {
+  id: string;
+  code: string;
+  imageType: string;
+  animated: boolean;
+}
+
+export interface FfzEmote {
+  id: number;
+  name: string;
+  height: number;
+  width: number;
+}
+
+export interface TwitchBadgeVersion {
+  id: string;
+  image_url_1x: string;
+  image_url_2x: string;
+  image_url_4x: string;
+}
+
+export interface TwitchBadgeSet {
+  set_id: string;
+  versions: TwitchBadgeVersion[];
+}
+
+export interface TwitchBadgesResponse {
+  data: TwitchBadgeSet[];
+}
+
+export interface ChannelAssets {
+  globalBadges: TwitchBadgesResponse | null;
+  channelBadges: TwitchBadgesResponse | null;
+  bttvEmotes: BttvEmote[];
+  ffzEmotes: FfzEmote[];
+}
+
 export interface ChannelMessage {
   username: string;
   message: string;