feat(backend): add HTTP cache headers (ETag + Cache-Control) for GET endpoints — fix #129

[gbengaeben]

Summary

Resolves #129.

Adds HttpCacheInterceptor as the innermost app-level NestJS interceptor. It emits RFC 7232-compliant ETag + Cache-Control + Vary headers on GET/HEAD responses, Cache-Control: no-store + Pragma: no-cache (HTTP/1.0 fallback) on every mutation response (POST/PUT/PATCH/DELETE), and overrides the pre-set Cache-Control to no-store when a controller throws so 4xx/5xx responses are never cached by an intermediary.

Behavior

• GET / HEAD → ETag (sha256 of canonical JSON), Cache-Control: private, must-revalidate, Vary: Authorization, Accept-Encoding. On a matching If-None-Match (strong, W/ weak, comma-separated multi-value, or * wildcard), short-circuits to 304 Not Modified with empty body.
• POST / PUT / PATCH / DELETE → Cache-Control: no-store + Pragma: no-cache, set before any path / decorator check.
• 4xx / 5xx via thrown error → interceptor catches via catchError, overrides to no-store + Pragma: no-cache and strips any pre-set ETag / Vary so an error can never be cached.
• Streams / Buffers / Uint8Array / non-JSON Content-Type / responses larger than HTTP_CACHE_MAX_ETAG_BYTES → ETag skipped but Cache-Control retained.

Decorators

• @HttpCache({ public?: boolean, ttl?: number }) — switch to public cache or set explicit max-age.
• @HttpCacheTtl(seconds) — override max-age while preserving private.
• @SkipHttpCache() — opt-out per handler / controller for sensitive or already-cached responses.

Configuration

Env var	Default	Behavior
HTTP_CACHE_ENABLED	true	Kill switch for staged rollout.
HTTP_CACHE_DEFAULT_TTL	0 (→ no-cache)	Default max-age for the private directive.
HTTP_CACHE_MAX_ETAG_BYTES	262144	Skip ETag hashing on larger payloads.
NODE_ENV	—	`X-Http-Cache: miss

Files

• app/backend/src/common/interceptors/http-cache.interceptor.ts (new, ~270 LOC)
• app/backend/src/common/interceptors/__tests__/http-cache.interceptor.spec.ts (new, ~330 LOC of specs)
• app/backend/src/common/decorators/http-cache.decorator.ts (new)
• app/backend/src/common/utils/json-canonicalize.util.ts (new)
• app/backend/src/common/utils/__tests__/json-canonicalize.util.spec.ts (new)
• app/backend/src/app.module.ts (registers the interceptor as last APP_INTERCEPTOR)
• app/backend/tsconfig.json (adds rootDir: "./" so ts-jest can compile isolated spec files in __tests__ subdirs without TS5011, and ignoreDeprecations: "6.0" to silence TS5101 / TS5107 on the existing project-wide baseUrl and moduleResolution: "node")

Why it sits between Deprecation and the handler

APP_INTERCEPTOR runs after APP_GUARD (the JWT / API key / rate-limit guards mutate request.user before our layer is reached) and after DeprecationInterceptor (so we don't re-cache the body of a deprecated endpoint that is being phased out). NestJS runs interceptors outer→inner on the request side and inner→outer on the response side, so being registered last means map sees the raw handler body for ETag hashing.

Risk

Low. The interceptor is conservative: no-store is set before any path / decorator check on mutating methods, all __tests__ co-located specs cover the full behavior matrix (Pragma on mutations, catchError override on GET/HEAD when controller throws, primitive response bodies, ETag skip on non-JSON Content-Type, all If-None-Match forms, all decorators, all skipped paths).

Maintainer notes

• A previous attempt at the same fix (feat(backend): add HTTP cache headers (ETag + Cache-Control) for GET endpoints — fixes #129 #197) was closed because the new unit specs could not run: ts-jest failed with TS5011 (__tests__ subdir falsely inferred as rootDir) and TS5101 / TS5107 (deprecated baseUrl / moduleResolution: "node") inside the same compile. Both are addressed by the two-line tsconfig.json change above; no globals or build outputs are touched.
• The Pragma: no-cache header on mutations and on thrown errors is the RFC 7234 §5.5 HTTP/1.0 fallback. It is not set on GET/HEAD because doing so would defeat the cache entirely — we accept that an old HTTP/1.0 intermediary could still cache a GET response and document that here.

Closes #129