feat(cache): add in-memory LRU cache for GET /api/campaigns with 5-second TTL

Adds campaignCache.ts backed by lru-cache to avoid SQLite on every
campaign-list request. Cache hit returns the pre-serialised JSON body
directly, skipping the query entirely. All write paths (create, pledge,
reconcile, claim, refund) call invalidateCampaignCache() so stale data
is never served past the current request. Cache-Control: max-age=5 and
X-Cache: HIT/MISS headers are set on every response. Max cache size is
configurable via CAMPAIGN_CACHE_MAX_SIZE env var (default 100).

Closes #216

Author: Williams-1604

backend/package-lock.json

@@ -10,6 +10,7 @@
     "cors": "^2.8.5",
     "dotenv": "^17.3.1",
     "express": "^4.21.2",
+    "lru-cache": "^11.5.1",
     "redis": "^4.6.13",
     "zod": "^4.3.6"
   },

backend/package.json

@@ -58,6 +58,12 @@ import {
   normalizeQueryValue,
 } from './validation/schemas';
 import { logError, logInfo } from './logger';
+import {
+  buildCampaignCacheKey,
+  getCampaignCacheEntry,
+  invalidateCampaignCache,
+  setCampaignCacheEntry,
+} from './services/campaignCache';
 export const app = express();
 
 type CampaignListItem = CampaignRecord & { progress: CampaignProgress };
@@ -270,6 +276,22 @@ app.get('/api/campaigns', (req: Request, res: Response) => {
 
   const params = queryResult.data;
 
+  // Build a stable cache key from the sorted query string
+  const qs = Object.keys(req.query as Record<string, unknown>)
+    .sort()
+    .map((k) => `${k}=${(req.query as Record<string, unknown>)[k]}`)
+    .join('&');
+  const cacheKey = buildCampaignCacheKey(qs);
+
+  const cached = getCampaignCacheEntry(cacheKey);
+  if (cached) {
+    res.setHeader('Cache-Control', 'max-age=5');
+    res.setHeader('X-Cache', 'HIT');
+    res.setHeader('Content-Type', 'application/json');
+    res.send(cached);
+    return;
+  }
+
   const listOptions: ListCampaignsOptions = {
     searchQuery: params.search || params.q,
     assetCodes: params.asset,
@@ -299,7 +321,7 @@ app.get('/api/campaigns', (req: Request, res: Response) => {
       ? 1
       : Math.max(1, Math.ceil(totalCount / limit));
 
-  res.json({
+  const responseBody = JSON.stringify({
     data,
     pagination: {
       total: totalCount,
@@ -308,6 +330,13 @@ app.get('/api/campaigns', (req: Request, res: Response) => {
       totalPages,
     },
   });
+
+  setCampaignCacheEntry(cacheKey, responseBody);
+
+  res.setHeader('Cache-Control', 'max-age=5');
+  res.setHeader('X-Cache', 'MISS');
+  res.setHeader('Content-Type', 'application/json');
+  res.send(responseBody);
 });
 
 app.get('/api/campaigns/:id', (req: Request, res: Response) => {
@@ -382,6 +411,7 @@ app.post('/api/campaigns', (req: Request, res: Response) => {
   };
 
   const campaign = createCampaign(campaignInput);
+  invalidateCampaignCache();
   res.status(201).json({ data: { ...campaign, progress: calculateProgress(campaign) } });
 });
 
@@ -400,6 +430,7 @@ app.post(
     }
 
     const campaign = addPledge(parsedId.value, parsedBody.data);
+    invalidateCampaignCache();
     res.status(201).json({ data: { ...campaign, progress: calculateProgress(campaign) } });
   },
 );
@@ -419,6 +450,7 @@ app.post(
     }
 
     const campaign = reconcileOnChainPledge(parsedId.value, parsedBody.data);
+    invalidateCampaignCache();
     res.status(201).json({
       data: {
         campaign: { ...campaign, progress: calculateProgress(campaign) },
@@ -447,6 +479,7 @@ app.post(
       transactionHash: parsedBody.data.transactionHash,
       confirmedAt: parsedBody.data.confirmedAt,
     });
+    invalidateCampaignCache();
     res.json({ data: { ...campaign, progress: calculateProgress(campaign) } });
   },
 );
@@ -476,6 +509,7 @@ app.post(
         latestLedger: verified.latestLedger ?? parsedBody.data.soroban.latestLedger,
         source: 'soroban-contract',
       });
+      invalidateCampaignCache();
 
       res.json({
         data: {

backend/src/index.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  buildCampaignCacheKey,
+  getCampaignCacheEntry,
+  setCampaignCacheEntry,
+  invalidateCampaignCache,
+  getCampaignCacheSize,
+} from './campaignCache';
+
+describe('campaignCache', () => {
+  beforeEach(() => {
+    invalidateCampaignCache();
+  });
+
+  it('returns undefined for a key that has not been set', () => {
+    expect(getCampaignCacheEntry('campaigns:missing')).toBeUndefined();
+  });
+
+  it('returns the stored body after a set', () => {
+    const key = buildCampaignCacheKey('status=open');
+    const body = JSON.stringify({ data: [], pagination: {} });
+    setCampaignCacheEntry(key, body);
+    expect(getCampaignCacheEntry(key)).toBe(body);
+  });
+
+  it('buildCampaignCacheKey namespaces the key correctly', () => {
+    expect(buildCampaignCacheKey('foo=bar')).toBe('campaigns:foo=bar');
+    expect(buildCampaignCacheKey('')).toBe('campaigns:');
+  });
+
+  it('stores separate entries for different query strings', () => {
+    const k1 = buildCampaignCacheKey('status=open');
+    const k2 = buildCampaignCacheKey('status=funded');
+    setCampaignCacheEntry(k1, 'open-response');
+    setCampaignCacheEntry(k2, 'funded-response');
+    expect(getCampaignCacheEntry(k1)).toBe('open-response');
+    expect(getCampaignCacheEntry(k2)).toBe('funded-response');
+  });
+
+  it('invalidateCampaignCache clears all entries', () => {
+    setCampaignCacheEntry(buildCampaignCacheKey('a=1'), 'body-a');
+    setCampaignCacheEntry(buildCampaignCacheKey('b=2'), 'body-b');
+    expect(getCampaignCacheSize()).toBe(2);
+
+    invalidateCampaignCache();
+
+    expect(getCampaignCacheSize()).toBe(0);
+    expect(getCampaignCacheEntry(buildCampaignCacheKey('a=1'))).toBeUndefined();
+  });
+
+  it('overwrites an existing entry for the same key', () => {
+    const key = buildCampaignCacheKey('page=1');
+    setCampaignCacheEntry(key, 'first');
+    setCampaignCacheEntry(key, 'second');
+    expect(getCampaignCacheEntry(key)).toBe('second');
+  });
+});

backend/src/services/campaignCache.test.ts

@@ -0,0 +1,33 @@
+import { LRUCache } from 'lru-cache';
+
+const CACHE_TTL_MS = 5_000;
+const CACHE_MAX_SIZE = Number(process.env.CAMPAIGN_CACHE_MAX_SIZE ?? 100);
+
+interface CacheEntry {
+  body: string;
+}
+
+const cache = new LRUCache<string, CacheEntry>({
+  max: CACHE_MAX_SIZE,
+  ttl: CACHE_TTL_MS,
+});
+
+export function buildCampaignCacheKey(queryString: string): string {
+  return `campaigns:${queryString}`;
+}
+
+export function getCampaignCacheEntry(key: string): string | undefined {
+  return cache.get(key)?.body;
+}
+
+export function setCampaignCacheEntry(key: string, body: string): void {
+  cache.set(key, { body });
+}
+
+export function invalidateCampaignCache(): void {
+  cache.clear();
+}
+
+export function getCampaignCacheSize(): number {
+  return cache.size;
+}