feat: add etag

Author: kilee1230

src/app.test.ts

@@ -6,10 +6,24 @@ describe("GET /health", () => {
   const app = createApp();
   const request = new supertest.agent(app);
 
-  it("responds with 200 OK", async () => {
-    await expect(request.get("/health")).resolves.toMatchObject({
-      status: 200,
-      body: { status: "ok" }
-    });
+  it("responds with 200 OK and sets ETag", async () => {
+    const res = await request.get("/health");
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ status: "ok" });
+    expect(res.headers).toHaveProperty("etag");
+    expect(typeof res.headers["etag"]).toBe("string");
+  });
+
+  it("responds with 304 Not Modified when If-None-Match matches", async () => {
+    const first = await request.get("/health");
+    const etag = first.headers["etag"] as string;
+    expect(etag).toBeTruthy();
+
+    const second = await request.get("/health").set("If-None-Match", etag);
+    expect(second.status).toBe(304);
+    // No body on 304
+    expect(second.body).toEqual({});
+    // ETag should still be present (some servers echo it)
+    expect(second.headers["etag"]).toBe(etag);
   });
 });

src/app.ts

@@ -3,6 +3,7 @@ import cors from "cors";
 import express, { Application } from "express";
 
 import { errorMiddleware } from "./middleware/error";
+import etagMiddleware from "./middleware/etag";
 import logMiddleware from "./middleware/logger";
 import { router } from "./routes";
 
@@ -12,5 +13,6 @@ export const createApp = (): Application =>
     .use(bodyParser.json())
     .use(bodyParser.urlencoded({ extended: true }))
     .use(logMiddleware)
+    .use(etagMiddleware)
     .use(errorMiddleware)
     .use(router);

src/middleware/etag.ts

@@ -0,0 +1,89 @@
+import crypto from "crypto";
+
+import { NextFunction, Request, Response } from "express";
+
+/**
+ * ETag middleware
+ * Generates a strong ETag for JSON / text / javascript / html responses when one is not already set.
+ * Skips if the response already has an ETag, is a HEAD request, or the status code implies no body.
+ */
+export function etagMiddleware(
+  req: Request,
+  res: Response,
+  next: NextFunction
+) {
+  // capture original send
+  const originalSend = res.send.bind(res);
+
+  res.send = function patchedSend(body?: any): Response {
+    try {
+      if (
+        req.method !== "HEAD" &&
+        !res.getHeader("ETag") &&
+        shouldHaveEntityBody(res.statusCode) &&
+        body !== undefined
+      ) {
+        const contentType = (res.getHeader("Content-Type") || "").toString();
+        if (/json|text|javascript|xml|html/.test(contentType)) {
+          const buf = toBuffer(body, contentType);
+          const etag = generateStrongETag(buf);
+          res.setHeader("ETag", etag);
+
+          // Conditional request handling (If-None-Match)
+          const ifNoneMatch = req.headers["if-none-match"];
+          if (ifNoneMatch && etagMatches(ifNoneMatch, etag)) {
+            // Per RFC7232: 304 MUST NOT include message-body
+            res.statusCode = 304;
+            // Remove headers that only make sense with a body
+            res.removeHeader("Content-Type");
+            res.removeHeader("Content-Length");
+            return originalSend();
+          }
+        }
+      }
+    } catch {
+      // fail silently; do not block response on ETag failures
+    }
+    return originalSend(body);
+  } as any;
+
+  next();
+}
+
+function shouldHaveEntityBody(statusCode?: number) {
+  if (!statusCode) return true;
+  return ![204, 205, 304].includes(statusCode);
+}
+
+function toBuffer(body: any, contentType: string): Buffer {
+  if (Buffer.isBuffer(body)) return body;
+  if (typeof body === "string") return Buffer.from(body);
+  // assume json-like
+  if (/json/.test(contentType)) return Buffer.from(JSON.stringify(body));
+  return Buffer.from(String(body));
+}
+
+function generateStrongETag(content: Buffer): string {
+  const hash = crypto.createHash("sha256").update(content).digest("base64");
+  // shorten without losing much uniqueness (optional)
+  const short = hash.replace(/=+$/, "").slice(0, 27);
+  return '"' + short + '"';
+}
+
+function etagMatches(ifNoneMatchHeader: string | string[], current: string) {
+  const header = Array.isArray(ifNoneMatchHeader)
+    ? ifNoneMatchHeader.join(",")
+    : ifNoneMatchHeader;
+  if (header.trim() === "*") return true;
+  // Header may contain multiple comma-separated ETags possibly with weak validators (W/)
+  return header
+    .split(",")
+    .map((v) => v.trim())
+    .some((tag) => stripWeak(tag) === current);
+}
+
+function stripWeak(tag: string) {
+  return tag.startsWith("W/") ? tag.slice(2) : tag;
+}
+
+export default etagMiddleware;