redis unifier

backend/src/unify-redis/app.module.ts

@@ -0,0 +1,37 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { TerminusModule } from '@nestjs/terminus';
+import { CacheModule } from './cache/cache.module';
+import { HealthController } from './health/health.controller';
+import { RedisModule } from './redis/redis.module';
+// Import your feature modules below as usual — they no longer need to create
+// their own Redis clients.
+// import { LeaderboardsModule } from './leaderboards/leaderboards.module';
+
+@Module({
+  imports: [
+    // ── Config ──────────────────────────────────────────────────────────────
+    ConfigModule.forRoot({
+      isGlobal: true,
+      cache: true,
+    }),
+
+    // ── Redis — registered once, exported globally ───────────────────────────
+    // All feature modules that previously imported their own redis.module.ts
+    // now rely on the REDIS_CLIENT token provided here.
+    RedisModule.forRootAsync(),
+
+    // ── Cache — platform-level service available everywhere ──────────────────
+    // CacheService and CacheInterceptor are now injectable application-wide
+    // without re-importing CacheModule in every feature module.
+    CacheModule,
+
+    // ── Health ───────────────────────────────────────────────────────────────
+    TerminusModule,
+
+    // ── Feature modules ──────────────────────────────────────────────────────
+    // LeaderboardsModule,
+  ],
+  controllers: [HealthController],
+})
+export class AppModule {}

backend/src/unify-redis/cache.interceptor.spec.ts

@@ -0,0 +1,198 @@
+import { ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Test, TestingModule } from '@nestjs/testing';
+import { of } from 'rxjs';
+import { CacheInterceptor, CACHE_TTL_METADATA } from './cache.interceptor';
+import { CacheService } from './cache.service';
+
+// ---------------------------------------------------------------------------
+// Helper factories
+// ---------------------------------------------------------------------------
+
+function makeContext(method = 'GET', path = '/leaderboard', query = {}): ExecutionContext {
+  const mockRequest = { method, path, query };
+  const mockResponse = { setHeader: jest.fn() };
+  const mockHandler = {};
+
+  return {
+    switchToHttp: () => ({
+      getRequest: () => mockRequest,
+      getResponse: () => mockResponse,
+    }),
+    getHandler: () => mockHandler,
+  } as unknown as ExecutionContext;
+}
+
+function makeHandler(returnValue: unknown): jest.Mock {
+  return jest.fn().mockReturnValue(of(returnValue));
+}
+
+const mockCacheService = (): jest.Mocked<CacheService> =>
+  ({
+    get: jest.fn(),
+    set: jest.fn(),
+    ping: jest.fn(),
+    metrics: { hits: 0, misses: 0, errors: 0, degraded: false },
+    isConnected: true,
+  } as unknown as jest.Mocked<CacheService>);
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('CacheInterceptor', () => {
+  let interceptor: CacheInterceptor;
+  let cache: jest.Mocked<CacheService>;
+  let reflector: Reflector;
+
+  beforeEach(async () => {
+    cache = mockCacheService();
+
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        CacheInterceptor,
+        { provide: CacheService, useValue: cache },
+        Reflector,
+      ],
+    }).compile();
+
+    interceptor = module.get(CacheInterceptor);
+    reflector = module.get(Reflector);
+  });
+
+  describe('non-GET requests', () => {
+    it('passes through POST requests without touching the cache', async () => {
+      const ctx = makeContext('POST', '/leaderboard');
+      const next = { handle: makeHandler({ ok: true }) };
+
+      const result$ = await interceptor.intercept(ctx, next);
+      const emission = await new Promise((res) => result$.subscribe(res));
+
+      expect(emission).toEqual({ ok: true });
+      expect(cache.get).not.toHaveBeenCalled();
+      expect(cache.set).not.toHaveBeenCalled();
+    });
+
+    it('passes through DELETE requests without touching the cache', async () => {
+      const ctx = makeContext('DELETE', '/cache/key');
+      const next = { handle: makeHandler(null) };
+
+      const result$ = await interceptor.intercept(ctx, next);
+      await new Promise((res) => result$.subscribe(res));
+
+      expect(cache.get).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('GET without @CacheResponse decorator', () => {
+    it('passes through without caching when no TTL metadata is present', async () => {
+      jest.spyOn(reflector, 'get').mockReturnValue(undefined);
+      const ctx = makeContext('GET', '/leaderboard');
+      const next = { handle: makeHandler({ data: [] }) };
+
+      const result$ = await interceptor.intercept(ctx, next);
+      const emission = await new Promise((res) => result$.subscribe(res));
+
+      expect(emission).toEqual({ data: [] });
+      expect(cache.get).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('cache MISS — route decorated with @CacheResponse', () => {
+    beforeEach(() => {
+      jest.spyOn(reflector, 'get').mockImplementation((metadataKey) => {
+        if (metadataKey === CACHE_TTL_METADATA) return 60;
+        return undefined; // no custom key
+      });
+    });
+
+    it('calls the handler, stores the result, and sets X-Cache: MISS', async () => {
+      cache.get.mockResolvedValue(null);
+      cache.set.mockResolvedValue(true);
+
+      const ctx = makeContext('GET', '/leaderboard');
+      const response = ctx.switchToHttp().getResponse() as { setHeader: jest.Mock };
+      const next = { handle: makeHandler({ scores: [1, 2, 3] }) };
+
+      const result$ = await interceptor.intercept(ctx, next);
+      await new Promise<void>((res) => result$.subscribe({ complete: res }));
+
+      expect(cache.get).toHaveBeenCalledWith('http:/leaderboard');
+      expect(cache.set).toHaveBeenCalledWith(
+        'http:/leaderboard',
+        { scores: [1, 2, 3] },
+        { ttl: 60 },
+      );
+      expect(response.setHeader).toHaveBeenCalledWith('X-Cache', 'MISS');
+    });
+  });
+
+  describe('cache HIT', () => {
+    beforeEach(() => {
+      jest.spyOn(reflector, 'get').mockImplementation((metadataKey) => {
+        if (metadataKey === CACHE_TTL_METADATA) return 60;
+        return undefined;
+      });
+    });
+
+    it('returns cached value and sets X-Cache: HIT without calling handler', async () => {
+      const cached = { scores: [99, 88] };
+      cache.get.mockResolvedValue(cached);
+
+      const ctx = makeContext('GET', '/leaderboard');
+      const response = ctx.switchToHttp().getResponse() as { setHeader: jest.Mock };
+      const next = { handle: makeHandler({ scores: [] }) }; // should not be called
+
+      const result$ = await interceptor.intercept(ctx, next);
+      const emission = await new Promise((res) => result$.subscribe(res));
+
+      expect(emission).toEqual(cached);
+      expect(next.handle).not.toHaveBeenCalled();
+      expect(response.setHeader).toHaveBeenCalledWith('X-Cache', 'HIT');
+    });
+  });
+
+  describe('Redis degradation', () => {
+    beforeEach(() => {
+      jest.spyOn(reflector, 'get').mockImplementation((metadataKey) => {
+        if (metadataKey === CACHE_TTL_METADATA) return 60;
+        return undefined;
+      });
+    });
+
+    it('falls through to the handler when cache.get throws', async () => {
+      cache.get.mockRejectedValue(new Error('ECONNREFUSED'));
+      const ctx = makeContext('GET', '/leaderboard');
+      const next = { handle: makeHandler({ live: true }) };
+
+      const result$ = await interceptor.intercept(ctx, next);
+      const emission = await new Promise((res) => result$.subscribe(res));
+
+      expect(emission).toEqual({ live: true });
+    });
+  });
+
+  describe('cache key construction', () => {
+    beforeEach(() => {
+      jest.spyOn(reflector, 'get').mockImplementation((metadataKey) => {
+        if (metadataKey === CACHE_TTL_METADATA) return 30;
+        return undefined;
+      });
+    });
+
+    it('incorporates query-string parameters into the cache key', async () => {
+      cache.get.mockResolvedValue(null);
+      cache.set.mockResolvedValue(true);
+
+      const ctx = makeContext('GET', '/scores', { page: '2', limit: '20' });
+      const next = { handle: makeHandler([]) };
+
+      await interceptor.intercept(ctx, next);
+
+      const calledKey: string = (cache.get as jest.Mock).mock.calls[0][0];
+      expect(calledKey).toContain('/scores');
+      expect(calledKey).toContain('page=2');
+      expect(calledKey).toContain('limit=20');
+    });
+  });
+});

backend/src/unify-redis/cache.interceptor.ts

@@ -0,0 +1,81 @@
+import {
+  CallHandler,
+  ExecutionContext,
+  Injectable,
+  Logger,
+  NestInterceptor,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Request, Response } from 'express';
+import { Observable, of, tap } from 'rxjs';
+import { CacheService } from './cache.service';
+
+export const CACHE_TTL_METADATA = 'cache:ttl';
+export const CACHE_KEY_METADATA = 'cache:key';
+
+/**
+ * Decorate a controller method with @CacheResponse(ttl) to have its JSON
+ * payload cached automatically. Falls through silently when Redis is degraded.
+ */
+export function CacheResponse(ttl = 60, key?: string) {
+  return (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
+    Reflect.defineMetadata(CACHE_TTL_METADATA, ttl, descriptor.value);
+    if (key) Reflect.defineMetadata(CACHE_KEY_METADATA, key, descriptor.value);
+    return descriptor;
+  };
+}
+
+@Injectable()
+export class CacheInterceptor implements NestInterceptor {
+  private readonly logger = new Logger(CacheInterceptor.name);
+
+  constructor(
+    private readonly cache: CacheService,
+    private readonly reflector: Reflector,
+  ) {}
+
+  async intercept(ctx: ExecutionContext, next: CallHandler): Promise<Observable<unknown>> {
+    const request = ctx.switchToHttp().getRequest<Request>();
+
+    // Only cache idempotent reads
+    if (request.method !== 'GET') return next.handle();
+
+    const handler = ctx.getHandler();
+    const ttl = this.reflector.get<number>(CACHE_TTL_METADATA, handler);
+
+    // Only cache routes decorated with @CacheResponse
+    if (!ttl) return next.handle();
+
+    const customKey = this.reflector.get<string>(CACHE_KEY_METADATA, handler);
+    const cacheKey = customKey ?? this.buildKey(request);
+
+    try {
+      const cached = await this.cache.get(cacheKey);
+      if (cached !== null) {
+        this.logger.debug(`Cache HIT: ${cacheKey}`);
+        const response = ctx.switchToHttp().getResponse<Response>();
+        response.setHeader('X-Cache', 'HIT');
+        return of(cached);
+      }
+    } catch {
+      // Redis unavailable — serve live
+      return next.handle();
+    }
+
+    return next.handle().pipe(
+      tap(async (data) => {
+        const stored = await this.cache.set(cacheKey, data, { ttl });
+        if (stored) {
+          this.logger.debug(`Cache SET: ${cacheKey} (ttl=${ttl}s)`);
+          const response = ctx.switchToHttp().getResponse<Response>();
+          response.setHeader('X-Cache', 'MISS');
+        }
+      }),
+    );
+  }
+
+  private buildKey(req: Request): string {
+    const qs = new URLSearchParams(req.query as Record<string, string>).toString();
+    return `http:${req.path}${qs ? `?${qs}` : ''}`;
+  }
+}

backend/src/unify-redis/cache.module.ts

@@ -0,0 +1,24 @@
+import { Global, Module } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { RedisModule } from '../redis/redis.module';
+import { CacheInterceptor } from './cache.interceptor';
+import { CacheService } from './cache.service';
+
+/**
+ * CacheModule is marked @Global so that CacheService can be injected anywhere
+ * without repeating the import in every feature module.
+ *
+ * RedisModule is NOT imported here — it is registered once in AppModule via
+ * RedisModule.forRootAsync() which is already @Global itself. This module
+ * simply declares the service layer that wraps the shared Redis client.
+ */
+@Global()
+@Module({
+  providers: [
+    CacheService,
+    CacheInterceptor,
+    Reflector,
+  ],
+  exports: [CacheService, CacheInterceptor],
+})
+export class CacheModule {}