feat(iios): socket.io Redis adapter for cross-replica realtime (P9 scaling)

Adds an opt-in RedisIoAdapter (wired in main.ts when REDIS_URL is set) so
socket.io room emits fan out across instances via Redis pub/sub — a client on
replica B now receives messages emitted by replica A. Without REDIS_URL the
in-memory adapter is kept (single-instance dev unchanged). Adds redis to
docker-compose, REDIS_URL to the env contract, and smoke-realtime-cluster.mjs
which proves cross-instance delivery fails without Redis and passes with it.
Delivery is at-least-once at N>1; clients dedupe by message id (documented).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

packages/iios-service/src/main.ts

@@ -4,6 +4,7 @@ import { NestFactory } from '@nestjs/core';
 import { ValidationPipe } from '@nestjs/common';
 import { AppModule } from './app.module';
 import { traceMiddleware } from './observability/trace.middleware';
+import { RedisIoAdapter } from './realtime/redis-io.adapter';
 
 async function bootstrap(): Promise<void> {
   const app = await NestFactory.create(AppModule, { rawBody: true });
@@ -12,6 +13,15 @@ async function bootstrap(): Promise<void> {
     new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true }),
   );
   app.enableCors({ origin: true, credentials: true });
+
+  // Multi-replica realtime: fan socket.io room emits across instances via Redis.
+  // Opt-in — without REDIS_URL the default in-memory adapter is used (single instance).
+  if (process.env.REDIS_URL) {
+    const redisAdapter = new RedisIoAdapter(app, process.env.REDIS_URL);
+    await redisAdapter.connect();
+    app.useWebSocketAdapter(redisAdapter);
+  }
+
   const port = Number(process.env.PORT ?? 3200);
   await app.listen(port);
   // eslint-disable-next-line no-console

packages/iios-service/src/realtime/redis-io.adapter.ts

@@ -0,0 +1,46 @@
+import { Logger, type INestApplicationContext } from '@nestjs/common';
+import { IoAdapter } from '@nestjs/platform-socket.io';
+import { createAdapter } from '@socket.io/redis-adapter';
+import { Redis } from 'ioredis';
+import type { Server, ServerOptions } from 'socket.io';
+
+/**
+ * Socket.io adapter backed by Redis pub/sub (P9 scaling). With the default in-memory
+ * adapter, `server.to(room).emit()` only reaches sockets on the SAME instance; behind a
+ * load balancer a client on replica B never sees a message emitted by replica A. This
+ * adapter fans room emits across every replica through Redis, so realtime works at N>1.
+ * Wired only when REDIS_URL is set (single-instance dev keeps the in-memory adapter).
+ */
+export class RedisIoAdapter extends IoAdapter {
+  private readonly logger = new Logger(RedisIoAdapter.name);
+  private adapterConstructor?: ReturnType<typeof createAdapter>;
+  private clients: Redis[] = [];
+
+  constructor(
+    app: INestApplicationContext,
+    private readonly url: string,
+  ) {
+    super(app);
+  }
+
+  /** Establish the pub/sub clients + the socket.io Redis adapter factory. */
+  async connect(): Promise<void> {
+    const pubClient = new Redis(this.url, { maxRetriesPerRequest: null });
+    const subClient = pubClient.duplicate();
+    this.clients = [pubClient, subClient];
+    pubClient.on('error', (err) => this.logger.error(`redis pub error: ${err.message}`));
+    subClient.on('error', (err) => this.logger.error(`redis sub error: ${err.message}`));
+    this.adapterConstructor = createAdapter(pubClient, subClient);
+    this.logger.log('socket.io Redis adapter connected — realtime fans out across replicas');
+  }
+
+  createIOServer(port: number, options?: ServerOptions): Server {
+    const server = super.createIOServer(port, options) as Server;
+    if (this.adapterConstructor) server.adapter(this.adapterConstructor);
+    return server;
+  }
+
+  async dispose(): Promise<void> {
+    await Promise.all(this.clients.map((c) => c.quit().catch(() => undefined)));
+  }
+}