定義
presigned URL（有効期限・アクセス署名がクエリに付く一時オブジェクトストレージ URL）を HTTP キャッシュ・Service Worker・プロキシ LRU に入れるとき、認証・有効期限用クエリだけ除去し リソース意味を変えるクエリは維持 し、同一ファイルの重複キャッシュと誤ったキー衝突を同時に避ける正規化ルールである。
なぜ必要か
オブジェクトストレージ presigned URL は呼び出しごとに Signature、X-Amz-Expires、X-Amz-Credential 等が変わる。URL 全体をキャッシュキーにすると 同一画像が署名ごとに別項目 として積み、hit 率がなく保存容量だけ浪費する。
逆にクエリを 全部 除去すると masked=1（マスキング結果）と原本が同一キーに合流し 誤った画像 が見える。正規化には「何を除き何を残すか」の明示的分類が必要である。
動作原理
- URL パース:
origin + pathname + searchParams。 - strip リスト（例）:
X-Amz-*、Signature、Expires、AWSAccessKeyId— 認証・有効期限専用。 - keep リスト（例）:
masked、v、version、リサイズw/h— 応答バイトが変わる意味。 - 残りクエリをソートして直列化:
pathname + '?' + sortedParams。 - SW・サーバープロキシ・クライアントが 同一ルール を共有する必要がある。
プロキシパターン: ブラウザは /api/image-proxy?url=<encoded> だけ見ればよく、SW キャッシュキーは プロキシ URL 基準 で正規化する。
実務での適用
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}` : ""}`;
}
- 404・410 応答時に該当キー（または prefix）を purge。
- cache-generation-stale-write-guard と併用し in-flight revalidate が古いバイトを蘇らせない。
- CDN
Vary: Accept等とブラウザキーポリシーがずれないか確認。
トレードオフ
- keep リストが広すぎると依然重複キャッシュ — 本当にバイトが変わるパラメータだけ残す。
- keep リストが狭すぎるとマスキング・リサイズ変種が衝突。
- サーバーと SW ルールが異なると「プロキシは hit、SW は miss」等の二重動作。
使ってはいけない場合
- URL 自体が不変でバージョンが path のみの CDN（
/v2/asset.png）— クエリ strip が不要な場合がある。 - 署名が path 一部に embedded のスキーム — クエリルールだけでは不足。
- ユーザーごとに応答ボディが異なるのにキーを pathname のみ — 権限モデルと衝突。
よくある間違い
search全体削除で masked/original 衝突。- リサイズ
wまで strip し別サイズが同一キャッシュ項目に合流。 - SW だけ正規化しサーバープロキシ LRU は raw URL。
- presigned 失効後も stale 項目を無限 serve — revalidate・TTL 方針が必要。
関連概念
- presigned-url-direct-upload — アップロード用 presigned 発行
- service-worker-stale-while-revalidate — 正規化キーでの SWR
- server-image-proxy-transcoding-cache — プロキシ側 LRU キー設計