Presigned URL cache key normalization

Definition

When placing presigned URLs (temporary object storage URLs with expiry and access signatures in the query) into HTTP cache, Service Worker, or proxy LRU, a normalization rule that removes only auth and expiry queries and keeps queries that change resource meaning, avoiding duplicate cache entries for the same file and wrong key collisions at once.

Why it matters

Object storage presigned URLs change Signature, X-Amz-Expires, X-Amz-Credential, etc. on every call. Using the full URL as cache key stacks separate entries per signature for the same image, killing hit rate and wasting storage.

Conversely, removing all queries merges masked=1 (masked result) and original under one key and shows the wrong image. Normalization needs explicit classification of what to strip and what to keep.

How it works

1. Parse URL: origin + pathname + searchParams.
2. Strip list (example): X-Amz-*, Signature, Expires, AWSAccessKeyId — auth and expiry only.
3. Keep list (example): masked, v, version, resize w/h — semantics that change response bytes.
4. Serialize remaining queries sorted: pathname + '?' + sortedParams.
5. SW, server proxy, and client must share the same rule.

Proxy pattern: the browser only sees /api/image-proxy?url=<encoded>, and the SW cache key normalizes on the proxy URL.

Practical application

const STRIP = new Set([
  "Signature",
  "Expires",
  "X-Amz-Signature",
  "X-Amz-Expires",
]);

function normalizeCacheKey(raw: string): string {
  const u = new URL(raw, "https://example.com");
  const kept = [...u.searchParams.entries()]
    .filter(([k]) => !STRIP.has(k) && !k.startsWith("X-Amz-"))
    .sort(([a], [b]) => a.localeCompare(b));
  const qs = new URLSearchParams(kept).toString();
  return `${u.pathname}${qs ? `?${qs}` : ""}`;
}

• Purge key (or prefix) on 404 and 410 responses.
• With cache-generation-stale-write-guard, prevent in-flight revalidate from reviving old bytes.
• Confirm CDN Vary: Accept etc. does not diverge from browser key policy.

Trade-offs

• Too wide a keep list still duplicates cache — keep only parameters that truly change bytes.
• Too narrow a keep list collides masking and resize variants.
• Different server vs SW rules cause double behavior like "proxy hits, SW misses".

When not to use

• Immutable URL with version only in path (/v2/asset.png) — query strip may be unnecessary.
• Schemes with signature embedded in path — query rules alone are insufficient.
• Per-user response bodies with pathname-only keys — conflicts with authorization model.

Common mistakes

• Deleting entire search causes masked/original collision.
• Stripping resize w merges different sizes into one cache entry.
• SW normalizes but server proxy LRU uses raw URL.
• Serving stale entries forever after presigned expiry — revalidate and TTL policy needed.

Related concepts

• presigned-url-direct-upload — presigned issuance for upload
• service-worker-stale-while-revalidate — SWR with normalized keys
• server-image-proxy-transcoding-cache — proxy-side LRU key design