feat(proxy): add cacheControl override; force immutable on VTEX /files/*?v=* (#1590)

The generic proxy handler in website/handlers/proxy.ts passes upstream
Cache-Control verbatim. For VTEX-proxied versioned static assets like
/files/checkout6-custom.css?v=920636e4 the upstream sends short TTLs,
even though the `?v=HASH` query param makes the content immutable by
definition. Production CDN data on lojastorra.com.br showed 51%-81%
expired rates on these checkout assets.

This commit adds an opt-in `cacheControl` prop on the proxy:

  cacheControl?: {
    value: string;
    matchQueryParam?: string;
  };

When `matchQueryParam` is set, the override applies only if the
incoming request URL has that param — letting us safely opt in only
versioned variants of a path. The override applies only to 2xx
responses so error pages keep their upstream cache semantics.

In vtex/loaders/proxy.ts, /files/*, /assets/*, /arquivos/* are now
wired to the override with `value: "public, max-age=31536000,
immutable"` and `matchQueryParam: "v"`. Unversioned requests on the
same paths keep upstream Cache-Control.

Follows the immutable-asset idiom already used in
website/loaders/asset.ts (s-maxage=15552000, max-age=15552000,
immutable).

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: vibegui

vtex/loaders/proxy.ts

@@ -68,6 +68,17 @@ const buildProxyRoutes = (
     const urlToProxy = `https://${hostname}`;
     const hostToUse = hostname;
 
+    // Versioned VTEX static assets (e.g. /files/foo.css?v=HASH) are immutable
+    // by definition: the hash changes whenever the content does. VTEX upstream
+    // serves them with short TTLs, so we force `immutable` on the proxy hop
+    // when the request carries a `v` query param. Unversioned variants of the
+    // same path keep upstream Cache-Control.
+    const IMMUTABLE_ASSET_PATHS = new Set([
+      "/files/*",
+      "/assets/*",
+      "/arquivos/*",
+    ]);
+
     const routeFromPath = (pathTemplate: string): Route => {
       const handlerValue = {
         __resolveType: "website/handlers/proxy.ts",
@@ -77,6 +88,12 @@ const buildProxyRoutes = (
         includeScriptsToBody,
         removeDirtyCookies: true,
         pathsThatRequireSameReferer: VTEX_PATHS_THAT_REQUIRES_SAME_REFERER,
+        ...(IMMUTABLE_ASSET_PATHS.has(pathTemplate) && {
+          cacheControl: {
+            value: "public, max-age=31536000, immutable",
+            matchQueryParam: "v",
+          },
+        }),
       };
 
       return ({

website/handlers/proxy.ts

@@ -86,6 +86,26 @@ export interface Props {
   removeDirtyCookies?: boolean;
   excludeHeaders?: string[];
   pathsThatRequireSameReferer?: string[];
+  /**
+   * @description Override Cache-Control on proxied responses. Use when the
+   *              upstream (e.g. VTEX IO) sends a Cache-Control that does not
+   *              match the resource's true cacheability — for example
+   *              versioned static assets at /files/*?v=HASH which are
+   *              immutable but get short upstream TTLs.
+   *
+   *              When matchQueryParam is set, the override only applies if
+   *              that query param is present on the incoming request URL.
+   *              This lets you safely opt in only the versioned variant of a
+   *              path (e.g. matchQueryParam: "v" → /files/x.js?v=abc gets
+   *              overridden, /files/x.js does not).
+   *
+   *              Only applied when the upstream response is 2xx, so error
+   *              responses retain their upstream caching semantics.
+   */
+  cacheControl?: {
+    value: string;
+    matchQueryParam?: string;
+  };
 }
 /**
  * @title Proxy
@@ -104,6 +124,7 @@ export default function Proxy({
   replaces,
   removeDirtyCookies = false,
   pathsThatRequireSameReferer = [],
+  cacheControl,
 }: Props): Handler {
   return async (req, _ctx) => {
     const url = new URL(req.url);
@@ -218,6 +239,13 @@ export default function Proxy({
         responseHeaders.set("location", location.replace(proxyUrl, url.origin));
       }
     }
+    if (cacheControl && response.ok) {
+      const matches = !cacheControl.matchQueryParam ||
+        url.searchParams.has(cacheControl.matchQueryParam);
+      if (matches) {
+        responseHeaders.set("Cache-Control", cacheControl.value);
+      }
+    }
     let text: undefined | string = undefined;
     if (replaces && replaces.length > 0 && contentType?.includes("text/html")) {
       if (response.ok) {