Merge pull request #749 from Amksongs/feat/570-etag-markets-caching

feat(markets): add ETag/304 caching on all market GET endpoints

Author: greatest0fallt1me

src/openapi/registry.ts

@@ -655,10 +655,32 @@ registry.registerPath({
   path: "/api/markets",
   operationId: "listMarkets",
   tags: ["Markets"],
-  summary: "List all markets",
+  summary: "List all markets with cursor pagination",
+  description:
+    "Returns a cursor-paginated list of markets. Supports strong ETag / conditional GET: " +
+    "send the ETag back as If-None-Match on subsequent requests; if the page is unchanged " +
+    "the server responds 304 Not Modified (no body).",
+  request: {
+    headers: z.object({
+      "if-none-match": z.string().optional().openapi({
+        description: "ETag from a previous 200 response. Triggers 304 when the page is unchanged.",
+        param: { name: "If-None-Match", in: "header" },
+      }),
+    }),
+  },
   responses: {
     200: {
       description: "Array of markets",
+      headers: {
+        ETag: {
+          description: "Strong ETag (SHA-256) of the response body.",
+          schema: { type: "string" },
+        },
+        "Cache-Control": {
+          description: "Always no-cache so clients revalidate before reuse.",
+          schema: { type: "string", example: "no-cache" },
+        },
+      },
       content: {
         "application/json": {
           schema: z.object({ data: z.array(Market) }),
@@ -695,6 +717,13 @@ registry.registerPath({
         },
       },
     },
+    304: {
+      description: "Not Modified — page unchanged since the ETag in If-None-Match.",
+    },
+    400: {
+      description: "Invalid query parameters",
+      content: { "application/json": { schema: ErrorBody } },
+    },
   },
 });
 
@@ -704,17 +733,36 @@ registry.registerPath({
   operationId: "searchMarkets",
   tags: ["Markets"],
   summary: "Full-text search across markets",
+  description:
+    "Full-text search with fuzzy trigram fallback. Supports strong ETag / conditional GET: " +
+    "send the ETag back as If-None-Match; if results are unchanged the server responds 304 Not Modified.",
   request: {
     query: z.object({
       q: z.string().min(1),
       limit: z.coerce.number().int().positive().default(20).optional(),
       offset: z.coerce.number().int().nonnegative().default(0).optional(),
       page: z.coerce.number().int().positive().optional(),
     }),
+    headers: z.object({
+      "if-none-match": z.string().optional().openapi({
+        description: "ETag from a previous 200 response. Triggers 304 when results are unchanged.",
+        param: { name: "If-None-Match", in: "header" },
+      }),
+    }),
   },
   responses: {
     200: {
       description: "Search results",
+      headers: {
+        ETag: {
+          description: "Strong ETag (SHA-256) of the response body.",
+          schema: { type: "string" },
+        },
+        "Cache-Control": {
+          description: "Always no-cache so clients revalidate before reuse.",
+          schema: { type: "string", example: "no-cache" },
+        },
+      },
       content: {
         "application/json": {
           schema: MarketSearchResult,
@@ -759,6 +807,9 @@ registry.registerPath({
         },
       },
     },
+    304: {
+      description: "Not Modified — search results unchanged since the ETag in If-None-Match.",
+    },
     400: {
       description: "Missing query parameter",
       content: {
@@ -822,10 +873,31 @@ registry.registerPath({
   operationId: "getMarketById",
   tags: ["Markets"],
   summary: "Get a market by ID",
-  request: { params: z.object({ id: z.string() }) },
+  description:
+    "Returns a single market by ID. Supports strong ETag / conditional GET: " +
+    "send the ETag back as If-None-Match; if unchanged the server responds 304 Not Modified.",
+  request: {
+    params: z.object({ id: z.string() }),
+    headers: z.object({
+      "if-none-match": z.string().optional().openapi({
+        description: "ETag from a previous 200 response. Triggers 304 when the market is unchanged.",
+        param: { name: "If-None-Match", in: "header" },
+      }),
+    }),
+  },
   responses: {
     200: {
       description: "Market",
+      headers: {
+        ETag: {
+          description: "Strong ETag (SHA-256) of the response body.",
+          schema: { type: "string" },
+        },
+        "Cache-Control": {
+          description: "Always no-cache so clients revalidate before reuse.",
+          schema: { type: "string", example: "no-cache" },
+        },
+      },
       content: {
         "application/json": {
           schema: z.object({ data: Market }),
@@ -854,6 +926,14 @@ registry.registerPath({
       content: { "application/json": { schema: ErrorBody } },
     },
   },
+    304: {
+      description: "Not Modified — market unchanged since the ETag in If-None-Match.",
+    },
+    404: {
+      description: "Not found",
+      content: { "application/json": { schema: ErrorBody } },
+    },
+  },
 });
 
 const PatchMarketRequest = z

src/routes/markets/index.ts

@@ -87,7 +87,7 @@ marketsRouter.get("/search", trackMarketsMetrics("search"), async (req, res, nex
 
     const result = await searchMarkets({ query: q, limit, offset });
 
-    return res.status(200).json({
+    const payload = {
       data: result.data,
       total: result.total,
       limit,
@@ -108,7 +108,13 @@ marketsRouter.get("/search", trackMarketsMetrics("search"), async (req, res, nex
         total: result.total,
         fallback: result.fallback,
       },
-    });
+    };
+
+    if (conditionalGet(payload, req, res)) {
+      return;
+    }
+
+    return res.status(200).json(payload);
   } catch (err) {
     logger.error({ reqId, correlationId: reqId, err }, "markets_search_failed");
     return next(err);
@@ -162,7 +168,13 @@ marketsRouter.get("/featured", trackMarketsMetrics("featured"), async (req, res,
 
     const { limit } = parsed.data;
     const data = await listFeaturedMarkets(limit);
-    return res.json({ data });
+    const payload = { data };
+
+    if (conditionalGet(payload, req, res)) {
+      return;
+    }
+
+    return res.json(payload);
   } catch (e) {
     logger.error({ reqId, correlationId: reqId, err: e }, "markets_featured_failed");
     return next(e);
@@ -179,11 +191,17 @@ marketsRouter.get("/upcoming", trackMarketsMetrics("upcoming"), async (req, res,
 
     const { limit } = parsed.data;
     const data = await listUpcomingMarkets({ limit });
+    const payload = { data };
+
+    if (conditionalGet(payload, req, res)) {
+      return;
+    }
+
     logger.info(
       { reqId, correlationId: reqId, count: data.length },
       "markets_upcoming_listed",
     );
-    return res.json({ data });
+    return res.json(payload);
   } catch (err) {
     logger.error(
       { reqId, correlationId: reqId, err },

src/routes/markets/prediction-count.ts

@@ -19,6 +19,7 @@
 import { Router } from "express";
 import { getPredictionCount } from "../../services/predictionCountService";
 import { NotFoundError } from "../../errors";
+import { conditionalGet } from "../../middleware/etag";
 import { logger } from "../../config/logger";
 import { getRequestId } from "../../lib/requestContext";
 
@@ -44,13 +45,18 @@ predictionCountRouter.get("/", async (req, res, next) => {
     logger.debug({ reqId, marketId }, "prediction_count_request");
 
     const result = await getPredictionCount(marketId);
+    const payload = { data: result };
+
+    if (conditionalGet(payload, req, res)) {
+      return;
+    }
 
     logger.info(
       { reqId, marketId, count: result.count, cached: result.cached },
       "prediction_count_success",
     );
 
-    return res.status(200).json({ data: result });
+    return res.status(200).json(payload);
   } catch (err) {
     if (err instanceof NotFoundError) {
       logger.warn({ reqId, marketId }, "prediction_count_not_found");

src/routes/markets/tags.ts

@@ -2,6 +2,7 @@
 import { Router } from "express";
 import { getMarketTags } from "../../repositories/marketRepository";
 import { rateLimitAnon } from "../../middleware/rateLimitAnon";
+import { conditionalGet } from "../../middleware/etag";
 import { logger } from "../../config/logger";
 
 export const tagsRouter = Router();
@@ -14,8 +15,14 @@ tagsRouter.get("/", async (req, res, next) => {
   try {
     logger.debug({ reqId, correlationId: reqId }, "Fetching market tags");
     const data = await getMarketTags();
+    const payload = { data };
+
+    if (conditionalGet(payload, req, res)) {
+      return;
+    }
+
     logger.info({ reqId, correlationId: reqId, count: data.length }, "Market tags fetched successfully");
-    res.json({ data });
+    res.json(payload);
   } catch (e) {
     logger.error({ reqId, correlationId: reqId, err: e }, "Failed to fetch market tags");
     next(e);

src/routes/markets/trending.ts

@@ -2,6 +2,7 @@ import { Router } from "express";
 import { getTrending } from "../../services/trendingService";
 import { rateLimitAnon } from "../../middleware/rateLimitAnon";
 import { trendingQuerySchema } from "../../validators/markets";
+import { conditionalGet } from "../../middleware/etag";
 
 export const trendingRouter = Router();
 
@@ -12,7 +13,13 @@ trendingRouter.get("/", async (req, res, next) => {
   try {
     const { limit, offset } = trendingQuerySchema.parse(req.query);
     const data = await getTrending(limit, offset);
-    res.json({ data, meta: { limit, offset, count: data.length } });
+    const payload = { data, meta: { limit, offset, count: data.length } };
+
+    if (conditionalGet(payload, req, res)) {
+      return;
+    }
+
+    res.json(payload);
   } catch (e) {
     next(e);
   }

src/routes/markets/watchers.ts

@@ -14,6 +14,7 @@
  */
 
 import { Router } from "express";
+import { conditionalGet } from "../../middleware/etag";
 import { logger } from "../../config/logger";
 import { getRequestId } from "../../lib/requestContext";
 import { AuthenticatedRequest } from "../../middleware/auth";
@@ -23,6 +24,7 @@ import {
   addMarketWatcher,
   removeMarketWatcher,
 } from "../../services/marketWatcherService";
+import { NotFoundError } from "../../errors";
 import {
   marketParamsSchema,
   marketWatchersQuerySchema,
@@ -68,6 +70,15 @@ watchersRouter.get("/", async (req, res, next) => {
     logger.debug({ reqId, correlationId: reqId, marketId, limit, cursor }, "market_watchers_list_request");
 
     const result = await listMarketWatchers(marketId, { limit, cursor });
+    const payload = {
+      data: result.data,
+      nextCursor: result.nextCursor,
+      total: result.total,
+    };
+
+    if (conditionalGet(payload, req, res)) {
+      return;
+    }
 
     logger.info(
       {
@@ -81,11 +92,7 @@ watchersRouter.get("/", async (req, res, next) => {
       "market_watchers_list_success",
     );
 
-    return res.status(200).json({
-      data: result.data,
-      nextCursor: result.nextCursor,
-      total: result.total,
-    });
+    return res.status(200).json(payload);
   } catch (err) {
     if (err instanceof NotFoundError) {
       logger.warn({ reqId, correlationId: reqId, marketId: req.params.id }, "market_watchers_not_found");

tests/marketWatchers.test.ts

@@ -120,6 +120,53 @@ describe("GET /api/markets/:id/watchers", () => {
     expect(res.status).toBe(400);
     expect(res.body.error.code).toBe("validation_error");
   });
+
+  // ── ETag / conditional GET ─────────────────────────────────────────────
+
+  it("returns a strong ETag header on 200", async () => {
+    mockListMarketWatchers.mockResolvedValueOnce({
+      data: [{ id: "w-1", marketId: "mkt-1", userId: "u-1", stellarAddress: "GABC123", createdAt: "2026-07-25T10:00:00.000Z" }],
+      nextCursor: null,
+      total: 1,
+    });
+
+    const res = await request(app).get("/mkt-1/watchers");
+    expect(res.status).toBe(200);
+    expect(res.headers["etag"]).toMatch(/^"[0-9a-f]{64}"$/);
+    expect(res.headers["cache-control"]).toBe("no-cache");
+  });
+
+  it("returns 304 when If-None-Match matches", async () => {
+    mockListMarketWatchers.mockResolvedValue({
+      data: [{ id: "w-1", marketId: "mkt-1", userId: "u-1", stellarAddress: "GABC123", createdAt: "2026-07-25T10:00:00.000Z" }],
+      nextCursor: null,
+      total: 1,
+    });
+
+    const first = await request(app).get("/mkt-1/watchers");
+    const etag = first.headers["etag"] as string;
+
+    const second = await request(app)
+      .get("/mkt-1/watchers")
+      .set("If-None-Match", etag);
+
+    expect(second.status).toBe(304);
+  });
+
+  it("returns 200 for a stale ETag", async () => {
+    mockListMarketWatchers.mockResolvedValueOnce({
+      data: [{ id: "w-1", marketId: "mkt-1", userId: "u-1", stellarAddress: "GABC123", createdAt: "2026-07-25T10:00:00.000Z" }],
+      nextCursor: null,
+      total: 1,
+    });
+
+    const res = await request(app)
+      .get("/mkt-1/watchers")
+      .set("If-None-Match", '"000000000000000000000000000000000000000000000000000000000000dead"');
+
+    expect(res.status).toBe(200);
+    expect(res.body).toHaveProperty("data");
+  });
 });
 
 describe("POST /api/markets/:id/watchers", () => {