Merge pull request #706 from Baskarayelu/feat/indexed-reads-673-etag

perf(cache): add ETags to indexed read responses

Author: Jagadeeshftw

src/routes/read.ts

@@ -31,13 +31,14 @@
  *     handlers — they remain exported and documented for future use.
  */
 import { Router } from "express";
-import type { Request } from "express";
+import type { Request, Response } from "express";
 import { z } from "zod";
 import { shortString } from "starknet";
 import { agreementContract, escrowContract, provider } from "../starknet/client.js";
 import { u256ToString, toHexString } from "../utils/codec.js";
 import { env } from "../config.js";
 import { NumericCursorSchema, loggedParse } from "../utils/validation.js";
+import { applyIndexedCacheHeaders } from "../utils/cache-headers.js";
 
 // ---------- validation ----------
 
@@ -379,6 +380,16 @@ function logReadTelemetry(entry: TelemetryEntry) {
 
 export const readRouter = Router();
 
+/** Send a read-only indexed response with conditional-request support. */
+function sendIndexedResponse(req: Request, res: Response, body: unknown): void {
+  applyIndexedCacheHeaders(res, body);
+  if (req.fresh) {
+    res.status(304).end();
+    return;
+  }
+  res.json(body);
+}
+
 // ---------- token / balances ----------
 
 readRouter.get("/token/:token/balance/:owner", async (req, res, next) => {
@@ -388,7 +399,7 @@ readRouter.get("/token/:token/balance/:owner", async (req, res, next) => {
     const token = AddressParam.parse(req.params.token);
     const owner = AddressParam.parse(req.params.owner);
     const balance = await erc20BalanceOf(token, owner);
-    res.json({ token, owner, balance });
+    sendIndexedResponse(req, res, { token, owner, balance });
   } catch (e: any) {
     const duration = Number(process.hrtime.bigint() - start) / 1_000_000;
     logReadTelemetry({
@@ -427,7 +438,7 @@ readRouter.get("/token/:token/decimals", async (req, res, next) => {
       token,
       request_id: res.locals.requestId,
     });
-    res.json({ token, decimals });
+    sendIndexedResponse(req, res, { token, decimals });
   } catch (e: any) {
     const duration = Number(process.hrtime.bigint() - start) / 1_000_000;
     logReadTelemetry({
@@ -465,7 +476,7 @@ readRouter.get("/token/:token/symbol", async (req, res, next) => {
       token,
       request_id: res.locals.requestId,
     });
-    res.json({ token, symbol });
+    sendIndexedResponse(req, res, { token, symbol });
   } catch (e: any) {
     const duration = Number(process.hrtime.bigint() - start) / 1_000_000;
     logReadTelemetry({
@@ -509,7 +520,7 @@ readRouter.get("/escrow/:address/balance/:agreement_id", async (req, res, next)
       agreement_id: agreement_id.toString(),
       request_id: requestId,
     });
-    res.json({
+    sendIndexedResponse(req, res, {
       escrow: escrowAddress,
       agreement_id: agreement_id.toString(),
       balance: u256ToString(balance),
@@ -562,7 +573,7 @@ readRouter.get("/escrow/:address/summary/:agreement_id", async (req, res, next)
       agreement_id: agreement_id.toString(),
       request_id: requestId,
     });
-    res.json({
+    sendIndexedResponse(req, res, {
       escrow: escrowAddress,
       agreement_id: agreement_id.toString(),
       employer: toHexString(employer),
@@ -622,7 +633,7 @@ readRouter.get("/agreement/:address/summary/:agreement_id", async (req, res, nex
       agreement_id: agreement_id.toString(),
       request_id: requestId,
     });
-    res.json({
+    sendIndexedResponse(req, res, {
       agreement: agreementAddress,
       agreement_id: agreement_id.toString(),
       employer: toHexString(employer),

src/routes/transactions.ts

@@ -25,6 +25,7 @@
  * the user **is** the employee (`employee-only`).
  */
 import { Router } from "express";
+import type { Request, Response } from "express";
 import { z } from "zod";
 import { db, schema } from "../db/index.js";
 import { eq, and, or, desc, gte, lte, inArray, sql, count } from "drizzle-orm";
@@ -37,6 +38,7 @@ import {
   getTokenInfo as resolveTokenInfo,
   type TokenInfo,
 } from "../utils/token-formatting.js";
+import { applyIndexedCacheHeaders } from "../utils/cache-headers.js";
 
 // ── Types ────────────────────────────────────────────────────────────────
 
@@ -1230,7 +1232,8 @@ function applySort(
  * - `limit` / `offset`: the requested parameters (clamped)
  */
 function respondPaginated(
-  res: import("express").Response,
+  req: Request,
+  res: Response,
   allTransactions: TransactionItem[],
   total: number,
   limit: number,
@@ -1248,6 +1251,11 @@ function respondPaginated(
     limit,
     offset,
   };
+  applyIndexedCacheHeaders(res, body);
+  if (req.fresh) {
+    res.status(304).end();
+    return;
+  }
   res.json(body);
 }
 
@@ -1301,7 +1309,7 @@ transactionsRouter.get(
         { deduplicateAgreementEvents: true },
       );
 
-      respondPaginated(res, allTransactions, total, limit, offset, sortBy, sortDir);
+      respondPaginated(req, res, allTransactions, total, limit, offset, sortBy, sortDir);
     } catch (e: any) {
       if (e?.status === 400 && e?.body) {
         res.status(400).json(e.body);
@@ -1354,7 +1362,7 @@ transactionsRouter.get(
         offset + limit,
       );
 
-      respondPaginated(res, allTransactions, total, limit, offset, sortBy, sortDir);
+      respondPaginated(req, res, allTransactions, total, limit, offset, sortBy, sortDir);
     } catch (e: any) {
       if (e?.status === 400 && e?.body) {
         res.status(400).json(e.body);

src/utils/address.test.ts

@@ -1,12 +1,19 @@
 import { getChecksumAddress } from "starknet";
-import { describe, expect, it } from "vitest";
-import { normalizeStarknetAddress } from "./address.js";
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  clearAddressNormalizationCache,
+  normalizeStarknetAddress,
+} from "./address.js";
 
 const zeroAddress = `0x${"0".repeat(64)}`;
 const oneAddress = `0x${"0".repeat(63)}1`;
 const fullAddress = `0x${"a".repeat(64)}`;
 
 describe("normalizeStarknetAddress", () => {
+  beforeEach(() => {
+    clearAddressNormalizationCache();
+  });
+
   it("normalizes missing prefixes, mixed case, whitespace, and short values", () => {
     expect(normalizeStarknetAddress("1")).toBe(oneAddress);
     expect(normalizeStarknetAddress("  0XABC  ")).toBe(`0x${"0".repeat(61)}abc`);
@@ -49,6 +56,22 @@ describe("normalizeStarknetAddress", () => {
     expect(() => normalizeStarknetAddress(`0x1${"0".repeat(64)}`)).toThrow(/exceeds/);
   });
 
+  it("reuses normalized values for repeated inputs", () => {
+    const first = normalizeStarknetAddress("0x0001");
+    const second = normalizeStarknetAddress("0x0001");
+    expect(second).toBe(first);
+  });
+
+  it("bounds cached entries while retaining the newest value", () => {
+    for (let index = 0; index < 1_025; index += 1) {
+      normalizeStarknetAddress(`0x${index.toString(16)}`);
+    }
+
+    expect(normalizeStarknetAddress("0x400")).toBe(
+      `0x${"0".repeat(61)}400`,
+    );
+  });
+
   describe("checksum validation", () => {
     const sampleAddress = "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
     const checksummed = getChecksumAddress(sampleAddress);

src/utils/address.ts

@@ -1,6 +1,40 @@
 import { getChecksumAddress } from "starknet";
 
 const STARKNET_ADDRESS_HEX_LENGTH = 64;
+const ADDRESS_NORMALIZATION_CACHE_MAX_ENTRIES = 1_024;
+
+/**
+ * Recently normalized inputs. Address normalization is on a number of hot
+ * request paths, and the same contract/token addresses are commonly parsed
+ * repeatedly while building one response. A Map gives us a small LRU without
+ * introducing a dependency or allowing unbounded user-controlled growth.
+ */
+const normalizedAddressCache = new Map<string, string>();
+
+/** Clear the address cache between tests or configuration reloads. */
+export function clearAddressNormalizationCache(): void {
+  normalizedAddressCache.clear();
+}
+
+function getCachedAddress(input: string): string | undefined {
+  const cached = normalizedAddressCache.get(input);
+  if (cached === undefined) return undefined;
+
+  // Refresh recency whenever an entry is used.
+  normalizedAddressCache.delete(input);
+  normalizedAddressCache.set(input, cached);
+  return cached;
+}
+
+function cacheAddress(input: string, normalized: string): void {
+  normalizedAddressCache.delete(input);
+  normalizedAddressCache.set(input, normalized);
+  while (normalizedAddressCache.size > ADDRESS_NORMALIZATION_CACHE_MAX_ENTRIES) {
+    const oldest = normalizedAddressCache.keys().next().value;
+    if (oldest === undefined) break;
+    normalizedAddressCache.delete(oldest);
+  }
+}
 
 /**
  * Normalize a Starknet address to the canonical database lookup key.
@@ -28,6 +62,9 @@ export function normalizeStarknetAddress(address: string): string {
   if (!trimmed) {
     throw new Error("Starknet address is required");
   }
+  const cached = getCachedAddress(trimmed);
+  if (cached !== undefined) return cached;
+
   const normalized = trimmed.toLowerCase();
   const prefixed = normalized.startsWith("0x") ? normalized : `0x${normalized}`;
   const hex = prefixed.replace(/^0x/, "");
@@ -51,5 +88,6 @@ export function normalizeStarknetAddress(address: string): string {
     }
   }
 
+  cacheAddress(trimmed, canonical);
   return canonical;
 }