feat: Redis profile cache and offline QR session tokens (#46) (#354)

- Cache public profiles in Redis under profile:<username> with 5-min TTL
- Return X-Cache: HIT on cache hit, X-Cache: MISS on DB fetch
- Add Cache-Control: public, max-age=300, stale-while-revalidate=60 to
  all public profile and QR session responses
- Add GET /api/public/:username/qr-session returning a signed 10-minute
  JWT snapshot for offline QR use cases (spec section 5.9)
- Invalidate profile cache in PUT /api/profiles/me immediately after a
  successful update so stale data is never served
- Register publicRoutes under /api/public in addition to /api/u
- Tests: cache HIT skips DB, MISS queries DB and writes cache, Redis
  error falls through to DB, qr-session token shape, payload contents,
  cache back-fill from qr-session DB path

Closes #46

Signed-off-by: amritbej.sh <amritbej750@gmail.com>
Co-authored-by: Amrit <amrit@example.com>

Author: amritbej

apps/backend/src/__tests__/public.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 import Fastify from 'fastify';
+import jwt from '@fastify/jwt';
 import { publicRoutes } from '../routes/public.js';
 import type { PrismaClient } from '@prisma/client';
 
@@ -41,13 +42,23 @@ const mockPrisma = {
   card: {} as any,
 };
 
+// ── Redis mock ────────────────────────────────────────────────────────────────
+// Simulates ioredis behaviour: get returns null (MISS) by default.
+const mockRedis = {
+  get: vi.fn().mockResolvedValue(null),
+  set: vi.fn().mockResolvedValue('OK'),
+  del: vi.fn().mockResolvedValue(1),
+};
+
 async function buildApp() {
   const app = Fastify();
+  // Register JWT so app.jwt.sign() is available for the qr-session route.
+  // @fastify/jwt also adds request.jwtVerify(), which throws when no valid
+  // Authorization header is present — matching the soft-auth pattern in the routes.
+  await app.register(jwt, { secret: 'test-secret-for-unit-tests-only' });
   app.decorate('prisma', mockPrisma as unknown as PrismaClient);
-  // Soft auth: jwtVerify rejects by default (unauthenticated visitor)
-  app.decorateRequest('jwtVerify', async function () {
-    throw new Error('no token');
-  });
+  // Decorate with the Redis mock so cache branches execute in tests.
+  app.decorate('redis', mockRedis as any);
   app.register(publicRoutes, { prefix: '/api/public' });
   await app.ready();
   return app;
@@ -61,6 +72,8 @@ describe('GET /api/public/:username/qr — size validation', () => {
     // Re-attach default mock behaviour cleared by clearAllMocks
     (generateQRBuffer as ReturnType<typeof vi.fn>).mockResolvedValue(Buffer.from('fake-png'));
     (generateQRSvg as ReturnType<typeof vi.fn>).mockResolvedValue('<svg>fake</svg>');
+    mockRedis.get.mockResolvedValue(null);
+    mockRedis.set.mockResolvedValue('OK');
   });
 
   // ── Reject before DB touch ─────────────────────────────────────────────────
@@ -222,3 +235,232 @@ describe('GET /api/public/:username/qr — size validation', () => {
     expect(res.json().error).toBe('QR code generation failed');
   });
 });
+
+// ─── Redis cache HIT / MISS behaviour ────────────────────────────────────────
+
+describe('GET /api/public/:username — Redis cache', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockRedis.get.mockResolvedValue(null);
+    mockRedis.set.mockResolvedValue('OK');
+    mockPrisma.followLog.findMany.mockResolvedValue([]);
+    mockPrisma.cardView.create.mockReturnValue({ catch: vi.fn() });
+  });
+
+  it('returns X-Cache: MISS and queries DB on first request', async () => {
+    mockPrisma.user.findUnique.mockResolvedValue(mockUser);
+    const app = await buildApp();
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/public/testuser',
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.headers['x-cache']).toBe('MISS');
+    expect(res.headers['cache-control']).toBe('public, max-age=300, stale-while-revalidate=60');
+    // DB was queried since Redis returned null
+    expect(mockPrisma.user.findUnique).toHaveBeenCalledOnce();
+    // Profile should be written to Redis after the DB fetch
+    expect(mockRedis.set).toHaveBeenCalledWith(
+      'profile:testuser',
+      expect.any(String),
+      'EX',
+      300,
+    );
+  });
+
+  it('returns X-Cache: HIT and skips DB on cached request', async () => {
+    // Simulate a warm cache entry
+    const cached = JSON.stringify({
+      _userId: 'user-123',
+      username: 'testuser',
+      displayName: 'Test User',
+      bio: null,
+      pronouns: null,
+      role: null,
+      company: null,
+      avatarUrl: null,
+      accentColor: '#ffffff',
+      links: [],
+    });
+    mockRedis.get.mockResolvedValue(cached);
+
+    const app = await buildApp();
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/public/testuser',
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.headers['x-cache']).toBe('HIT');
+    // DB must NOT be queried when cache is warm
+    expect(mockPrisma.user.findUnique).not.toHaveBeenCalled();
+  });
+
+  it('response body on cache HIT matches the cached profile', async () => {
+    const cached = JSON.stringify({
+      _userId: 'user-123',
+      username: 'testuser',
+      displayName: 'Test User',
+      bio: 'A bio',
+      pronouns: null,
+      role: 'Engineer',
+      company: null,
+      avatarUrl: null,
+      accentColor: '#123456',
+      links: [],
+    });
+    mockRedis.get.mockResolvedValue(cached);
+
+    const app = await buildApp();
+    const res = await app.inject({ method: 'GET', url: '/api/public/testuser' });
+    const body = res.json();
+
+    expect(body.username).toBe('testuser');
+    expect(body.accentColor).toBe('#123456');
+    // Internal _userId field must not leak into the HTTP response
+    expect(body._userId).toBeUndefined();
+  });
+
+  it('falls through to DB when Redis.get throws', async () => {
+    mockRedis.get.mockRejectedValue(new Error('Redis down'));
+    mockPrisma.user.findUnique.mockResolvedValue(mockUser);
+
+    const app = await buildApp();
+    const res = await app.inject({ method: 'GET', url: '/api/public/testuser' });
+
+    expect(res.statusCode).toBe(200);
+    // DB was reached despite the Redis failure
+    expect(mockPrisma.user.findUnique).toHaveBeenCalledOnce();
+  });
+
+  it('returns 404 when user does not exist (cache MISS)', async () => {
+    mockPrisma.user.findUnique.mockResolvedValue(null);
+
+    const app = await buildApp();
+    const res = await app.inject({ method: 'GET', url: '/api/public/nobody' });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().error).toBe('User not found');
+  });
+});
+
+// ─── QR session endpoint ──────────────────────────────────────────────────────
+
+describe('GET /api/public/:username/qr-session', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockRedis.get.mockResolvedValue(null);
+    mockRedis.set.mockResolvedValue('OK');
+  });
+
+  it('returns 404 when the user does not exist', async () => {
+    mockPrisma.user.findUnique.mockResolvedValue(null);
+
+    const app = await buildApp();
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/public/nobody/qr-session',
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().error).toBe('User not found');
+  });
+
+  it('returns a JWT token with correct shape on DB fetch (cache MISS)', async () => {
+    mockPrisma.user.findUnique.mockResolvedValue(mockUser);
+
+    const app = await buildApp();
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/public/testuser/qr-session',
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(typeof body.token).toBe('string');
+    expect(body.tokenType).toBe('JWT');
+    expect(body.expiresIn).toBe(600);
+    expect(typeof body.expiresAt).toBe('string');
+    // expiresAt must be a valid ISO 8601 date string
+    expect(new Date(body.expiresAt).getTime()).toBeGreaterThan(Date.now());
+  });
+
+  it('token payload encodes the public profile snapshot', async () => {
+    mockPrisma.user.findUnique.mockResolvedValue(mockUser);
+
+    const app = await buildApp();
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/public/testuser/qr-session',
+    });
+
+    const { token } = res.json();
+    // Decode without verifying so we can inspect the payload in the test
+    const decoded = JSON.parse(
+      Buffer.from(token.split('.')[1], 'base64url').toString(),
+    );
+    expect(decoded.sub).toBe('testuser');
+    expect(decoded.profile.username).toBe('testuser');
+    expect(decoded.profile.displayName).toBe('Test User');
+  });
+
+  it('serves snapshot from Redis cache without querying DB', async () => {
+    const cached = JSON.stringify({
+      _userId: 'user-123',
+      username: 'testuser',
+      displayName: 'Cached User',
+      bio: null,
+      pronouns: null,
+      role: null,
+      company: null,
+      avatarUrl: null,
+      accentColor: '#ffffff',
+      links: [],
+    });
+    mockRedis.get.mockResolvedValue(cached);
+
+    const app = await buildApp();
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/public/testuser/qr-session',
+    });
+
+    expect(res.statusCode).toBe(200);
+    // DB must not be reached when the cache is warm
+    expect(mockPrisma.user.findUnique).not.toHaveBeenCalled();
+
+    const { token } = res.json();
+    const decoded = JSON.parse(
+      Buffer.from(token.split('.')[1], 'base64url').toString(),
+    );
+    expect(decoded.profile.displayName).toBe('Cached User');
+  });
+
+  it('includes Cache-Control header in qr-session response', async () => {
+    mockPrisma.user.findUnique.mockResolvedValue(mockUser);
+
+    const app = await buildApp();
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/public/testuser/qr-session',
+    });
+
+    expect(res.headers['cache-control']).toBe('public, max-age=300, stale-while-revalidate=60');
+  });
+
+  it('caches the profile in Redis when served from DB', async () => {
+    mockPrisma.user.findUnique.mockResolvedValue(mockUser);
+
+    const app = await buildApp();
+    await app.inject({ method: 'GET', url: '/api/public/testuser/qr-session' });
+
+    expect(mockRedis.set).toHaveBeenCalledWith(
+      'profile:testuser',
+      expect.any(String),
+      'EX',
+      300,
+    );
+  });
+});

apps/backend/src/app.ts

@@ -101,6 +101,7 @@ export async function buildApp():Promise<FastifyInstance> {
   await app.register(profileRoutes, { prefix: '/api/profiles' });
   await app.register(cardRoutes, { prefix: '/api/cards' });
   await app.register(publicRoutes, { prefix: '/api/u' });
+  await app.register(publicRoutes, { prefix: '/api/public' });
   await app.register(followRoutes, { prefix: '/api/follow' });
   await app.register(connectRoutes, { prefix: '/api/connect' });
   await app.register(analyticsRoutes, { prefix: '/api/analytics' });

apps/backend/src/routes/profiles.ts

@@ -5,6 +5,7 @@ import {
   createLinkSchema,
   reorderLinksSchema,
 } from '../utils/validators.js';
+import { getErrorMessage } from '../utils/error.util.js';
 
 // ── Response types ────────────────────────────────────────────────────────────
 // Declared explicitly so the API contract is visible without tracing through
@@ -84,6 +85,13 @@ export async function profileRoutes(app: FastifyInstance) {
       }
     }
 
+    // Fetch current username before the update so we can invalidate the correct
+    // Redis cache key even if the username is being changed in this request.
+    const currentUser = await app.prisma.user.findUnique({
+      where: { id: userId },
+      select: { username: true },
+    });
+
     try {
       const response: ProfileUpdateResponse = await app.prisma.user.update({
         where: { id: userId },
@@ -102,6 +110,17 @@ export async function profileRoutes(app: FastifyInstance) {
         },
       });
 
+      // Invalidate the public profile cache so stale data is not served after
+      // an update.  Fire-and-forget — a cache miss on the next request is
+      // preferable to blocking the response on a Redis round-trip.
+      if (app.redis && currentUser) {
+        app.redis
+          .del(`profile:${currentUser.username}`)
+          .catch((err: unknown) =>
+            app.log.warn(`Failed to invalidate profile cache: ${getErrorMessage(err)}`)
+          );
+      }
+
       return response;
     } catch (error: any) {
       // Unique constraint violation — two concurrent requests raced through the