KASUGAI Canvas v6.17.0

2本の Service Worker

本ドキュメントではこの2本を 「DuckDB-WASM 永続キャッシュ」（sw-duckdb.js） と 「vendor 同一オリジン中継」（vendor-proxy-sw.js） と呼びます。

SW（呼称）	ファイル	役割	CacheStorage
DuckDB-WASM 永続キャッシュ	web/sw-duckdb.js	DuckDB-WASM の CDN 資産（約60MB）を永続キャッシュ	kasugai-duckdb-wasm
vendor 同一オリジン中継	web/vendor-proxy-sw.js	vendor/* を上流オリジナルへ中継し同一オリジンとして供給。成功応答は保険としてキャッシュ	kasugai-vendor-v1

ブラウザから見た構成図

flowchart TB
  subgraph BR["ブラウザ（ページ＝web/ スコープ配下）"]
    ENG["エンジンページ
cesium / gsimaps / navara 等"]
    PROBE["duckDbAssetsCached()
キャッシュ済みなら非表示の
クエリ系レイヤー分も DuckDB を
先行初期化"]
  end

  subgraph SW["Service Worker（スコープ web/ ・常に1本のみ active）"]
    DSW["sw-duckdb.js
＝「DuckDB-WASM 永続キャッシュ」"]
    VSW["vendor-proxy-sw.js
＝「vendor 同一オリジン中継」"]
  end

  ENG -->|"cesium 起動時 register"| DSW
  ENG -->|"vendor-guard.js 経由 register
（gsimaps / navara）"| VSW
  DSW <-.->|"エンジン切替で制御交代
controllerchange 待機＋1回リロード"| VSW

  ENG -->|"ページ・Worker 内の全 fetch"| ACTIVE{"active SW の
fetch ハンドラ"}
  SW --- ACTIVE

  ACTIVE -->|"@duckdb/duckdb-wasm@*
extensions.duckdb.org"| HITQ{"kasugai-duckdb-wasm
ヒット？"}
  HITQ -->|"hit"| RESP1["キャッシュから即応答
（ネットワーク不使用）"]
  HITQ -->|"miss → 取得後 cache.put"| EXT1[("jsdelivr /
extensions.duckdb.org")]
  PROBE -.->|"keys() で本体 wasm の有無を確認"| HITQ

  ACTIVE -->|"vendor/*（同一オリジン）"| PINQ["vendor.json のピンへ解決
npm/gh → jsdelivr
失敗時 raw.githubusercontent
（?u= でミラーモード）"]
  PINQ --> EXT2[("上流オリジナル /
?u= ミラー")]
  EXT2 -->|"Content-Type 包み直し
＋kasugai-vendor-v1 に保険保存"| RESP2["同一オリジンとして応答"]
  EXT2 -.->|"上流不通時"| VCACHE[("kasugai-vendor-v1")]
  VCACHE -.-> RESP2

  ACTIVE -->|"対象外のリクエスト"| PASS["ネットワークへ素通し
（タイル・レイヤーデータ等）"]

  classDef duckdb fill:#eef0ff,stroke:#667eea,color:#1a2230
  classDef vendor fill:#e9f7ee,stroke:#2e9e56,color:#1a2230
  classDef neutral fill:#f6f8fa,stroke:#9aa5b1,color:#5a6577
  class DSW,HITQ,RESP1,EXT1,PROBE duckdb
  class VSW,PINQ,EXT2,VCACHE,RESP2 vendor
  class ENG,ACTIVE,PASS neutral
          

対象資産（約60MB）

• cdn.jsdelivr.net/npm/@duckdb/duckdb-wasm@* — WASM 本体（約33MB）・ワーカースクリプト・+esm/dist 配下すべて
• extensions.duckdb.org — INSTALL spatial（約22MB）・httpfs・parquet 拡張の内部取得

Worker 内部のフェッチも対象です。DuckDB が内部で行う importScripts や拡張 INSTALL の取得も SW スコープ配下の fetch として横取りされるため、利用者側で意識する必要はありません。

キャッシュ戦略

• キャッシュキーは URL そのまま。@duckdb/duckdb-wasm@1.32.0・拡張 v1.4.3 のようにバージョンが URL に含まれるため、キーの衝突は起きません
• cache-first：キャッシュにあればネットワークに行かず返す。無ければ取得して cache.put（成功応答のみ・GET 要求のみ対象）
• activate 時に旧バージョンを掃除：CURRENT_ASSET_MARKERS（現行は /npm/@duckdb/duckdb-wasm@1.32.0 と /v1.4.3/）に一致しないエントリだけを削除します。DuckDB のバージョンを上げると新資産が自動的にダウンロードされ、旧資産は次回起動時に消えます

キャッシュ有無で起動動作が変わります。ページ側も duckDbAssetsCached()（app.js）で同じ CacheStorage を読み、本体 wasm の存在を確認します。キャッシュ済みなら非表示のクエリ系レイヤーぶんまで含めて DuckDB を先行初期化します（ディスク読み込みで実質無料のため選択をほぼ即応答にできる）。未キャッシュ＝実質初回は ~60MB の実コストがかかるため、表示対象のクエリ系レイヤーがあるときだけ先行します。

バージョンを上げるときは sw-duckdb.js の CURRENT_ASSET_MARKERS と web/cesium/app.js の DUCKDB_WASM_VERSION を同時に更新してください（片方だけだと掃除対象がずれます）。

上流解決（vendor.json のピン）

• npm ピン（navara）: https://cdn.jsdelivr.net/npm/<pkg>@<ver>/<tail>
• github ピン（gsimaps）: https://cdn.jsdelivr.net/gh/<repo>@<sha>/<rest> → 失敗時 raw.githubusercontent.com へ再試行
• SW スクリプト URL の ?u=<base> で自前ミラーモード（?hosted= / localStorage kasugai_hosted_base で指定。ミラー失敗時はオリジナルピンへフォールバック）

応答の包み直しとキャッシュ

• 上流応答は new Response で包み直し、Content-Type を拡張子から決め打ちします（jsdelivr/gh は text/plain を返すため、module script・Worker・iframe の MIME 厳格判定で拒否されるのを回避）
• 成功応答は kasugai-vendor-v1 に保存し、上流不通時の保険として使います。転送は cache: "no-store" で毎回上流を見るため、ピン更新後の陳腐化は起きません
• Range / 条件付きヘッダ（if-none-match 等）は上流へ転送します

制御交代の流れ

1. vendor エンジンのページを開く → vendor-guard.js が vendor-proxy-sw.js を register → SW 更新が走り install→activate→clients.claim で制御を取る
2. ガードは controllerchange と controller.scriptURL の一致で制御確定を待ってからエンジンを起動します（確定前に進むと vendor/* が中継されず 404 で起動不能）
3. 制御が確定できない場合は sessionStorage フラグで1回だけリロードして SW 制御下で読み直します（無限リロード防止）
4. Cesium に戻ると sw-duckdb.js 側が register され、再び制御が交代します

sw-duckdb.js の fetch ハンドラは対象外 URL を無視するだけで、制御中に vendor/* を中継することはありません。そのため vendor エンジンでは必ずガード経由で vendor-proxy-sw.js への交代を待つ必要があります。