Merge pull request #717

Closes #671

Author: Jagadeeshftw

docs/routes/analytics.md

@@ -262,6 +262,15 @@ block when the first request completes (success or error).
 - Unparseable amounts or malformed DB rows default to zero rather than crashing
   the endpoint with a 500 error.
 
+## Shared cache (optional)
+
+Set `REDIS_URL` to enable the Redis-backed analytics cache across backend
+replicas. It uses the same `buildAnalyticsCacheKey` format and the configured
+`ANALYTICS_CACHE_TTL_MS` expiry. When Redis is unset, the route keeps using the
+in-process cache; Redis connection, serialization, and invalidation failures
+are treated as cache misses so they do not turn into analytics errors. Use a
+private Redis instance and TLS/credentials appropriate for the deployment.
+
 ---
 
 ## Edge cases intentionally out of scope

src/config.ts

@@ -179,6 +179,10 @@ export const EnvSchema = z
       .optional()
       .default(30_000),
 
+    // Optional shared cache for analytics responses. When unset, the route
+    // uses its existing in-process cache.
+    REDIS_URL: z.string().url().optional(),
+
     // Session token lifetime in milliseconds (sliding expiry) — default 24 hours
     SESSION_TTL_MS: z.coerce
       .number()

src/routes/analytics.cache.test.ts

@@ -92,7 +92,11 @@ vi.mock("drizzle-orm", () => ({
 /* ── imports after mocks are registered ──────────────────────────────────── */
 
 import { analyticsRouter, analyticsAggregationCache } from "./analytics.js";
-import { AnalyticsCache, buildAnalyticsCacheKey } from "../utils/analytics-cache.js";
+import {
+  AnalyticsCache,
+  RedisAnalyticsCache,
+  buildAnalyticsCacheKey,
+} from "../utils/analytics-cache.js";
 
 /* ── helpers ─────────────────────────────────────────────────────────────── */
 
@@ -202,6 +206,32 @@ describe("AnalyticsCache unit", () => {
   });
 });
 
+describe("RedisAnalyticsCache", () => {
+  it("round-trips JSON values with a millisecond TTL", async () => {
+    const values = new Map<string, string>();
+    const redis = {
+      get: vi.fn(async (key: string) => values.get(key) ?? null),
+      set: vi.fn(async (key: string, value: string) => void values.set(key, value)),
+      del: vi.fn(async (key: string) => void values.delete(key)),
+    };
+    const cache = new RedisAnalyticsCache<{ total: number }>(redis, 30_000);
+
+    await cache.set("k", { total: 7 });
+    expect(await cache.get("k")).toEqual({ total: 7 });
+    expect(redis.set).toHaveBeenCalledWith("k", '{"total":7}', "PX", 30_000);
+    await cache.invalidate("k");
+    expect(await cache.get("k")).toBeUndefined();
+  });
+
+  it("turns Redis failures into misses", async () => {
+    const cache = new RedisAnalyticsCache(
+      { get: vi.fn().mockRejectedValue(new Error("offline")), set: vi.fn(), del: vi.fn() },
+      1000,
+    );
+    expect(await cache.get("k")).toBeUndefined();
+  });
+});
+
 /* ═══════════════════════════════════════════════════════════════════════════
    buildAnalyticsCacheKey unit tests
    ═══════════════════════════════════════════════════════════════════════════ */

src/routes/analytics.ts

@@ -6,7 +6,12 @@ import { asc, eq, and, gt, gte, lte, or, sql } from "drizzle-orm";
 import { StarknetAddress } from "../utils/validation.js";
 import { DEFAULT_TOKEN_DECIMALS } from "../utils/codec.js";
 import { env } from "../config.js";
-import { AnalyticsCache, buildAnalyticsCacheKey } from "../utils/analytics-cache.js";
+import Redis from "ioredis";
+import {
+  AnalyticsCache,
+  RedisAnalyticsCache,
+  buildAnalyticsCacheKey,
+} from "../utils/analytics-cache.js";
 
 export const analyticsRouter = Router();
 
@@ -19,6 +24,10 @@ export const ANALYTICS_ROLLUP_BATCH_SIZE = 500;
 export const analyticsAggregationCache = new AnalyticsCache(
   env.ANALYTICS_CACHE_TTL_MS ?? 30_000,
 );
+const redisAnalyticsCache = env.REDIS_URL
+  ? new RedisAnalyticsCache(new Redis(env.REDIS_URL), env.ANALYTICS_CACHE_TTL_MS ?? 30_000)
+  : undefined;
+const analyticsCache = redisAnalyticsCache ?? analyticsAggregationCache;
 
 const MONTH_NAMES = [
   "Jan",
@@ -242,7 +251,7 @@ analyticsRouter.get("/analytics/:user_address", async (req, res, next) => {
 
     const cacheKey = buildAnalyticsCacheKey(userAddress, { year });
 
-    const cached = analyticsAggregationCache.get(cacheKey);
+    const cached = await Promise.resolve(analyticsCache.get(cacheKey));
     if (cached) {
       res.set("Cache-Control", "private, max-age=60");
       const etag = computeETag(cached);
@@ -482,7 +491,7 @@ analyticsRouter.get("/analytics/:user_address", async (req, res, next) => {
         data: chartData,
         total: toDisplayNumber(totalRaw),
       };
-      analyticsAggregationCache.set(cacheKey, responseBody);
+      await Promise.resolve(analyticsCache.set(cacheKey, responseBody));
 
       res.set("Cache-Control", "private, max-age=60");
       const etag = computeETag(responseBody);

src/utils/analytics-cache.ts

@@ -138,3 +138,40 @@ export class AnalyticsCache<T> {
     return this.store.size;
   }
 }
+
+/** Redis implementation with cache failures isolated from analytics requests. */
+export class RedisAnalyticsCache<T> {
+  constructor(
+    private readonly redis: {
+      get(key: string): Promise<string | null>;
+      set(key: string, value: string, mode: "PX", ttl: number): Promise<unknown>;
+      del(key: string): Promise<unknown>;
+    },
+    private readonly ttlMs: number,
+  ) {}
+
+  async get(key: string): Promise<T | undefined> {
+    try {
+      const value = await this.redis.get(key);
+      return value === null ? undefined : (JSON.parse(value) as T);
+    } catch {
+      return undefined;
+    }
+  }
+
+  async set(key: string, value: T): Promise<void> {
+    try {
+      await this.redis.set(key, JSON.stringify(value), "PX", this.ttlMs);
+    } catch {
+      // Redis is optional; a failed write only causes the next request to miss.
+    }
+  }
+
+  async invalidate(key: string): Promise<void> {
+    try {
+      await this.redis.del(key);
+    } catch {
+      // Best-effort invalidation for an optional cache.
+    }
+  }
+}