본문으로 건너뛰기

CDN 버전 관리

모든 embed asset은 major-alias 경로에서 제공됩니다:

https://cdn.kaleidr.com/embed/v1/kaleidr.js   ← the loader (façade)
https://cdn.kaleidr.com/embed/v1/chat.js      ← chat bundle
https://cdn.kaleidr.com/embed/v1/viewer.js    ← viewer loader
https://cdn.kaleidr.com/embed/v1/editor.js    ← editor bundle
https://cdn.kaleidr.com/embed/v1/tile.js      ← tile loader

kaleidr.js를 고정하면 각 product bundle의 v1을 차례로 요청합니다.

v1의 실제 의미​

  • v1은 major-contract alias이며 특정 build pin이 아닙니다. /embed/v1/* 아래에는 patch 또는 content-hash 경로가 없습니다. 해당 URL이 제공하는 파일은 현재 v1 build이며 같은 위치에 게시됩니다. 고정할 수 있는 /embed/v1.2.3/… 경로는 없습니다.
  • 하위 호환 수정은 /embed/v1/ 아래에 배포됩니다 — 자동으로 받게 됩니다. 여기에는 동작 추가(새로운 안정적 SSE event, 새로운 handle method)도 포함됩니다 — 호환성 규칙은 client가 알 수 없는 wire 추가를 무시해야 하고 지원되지 않는 handle method는 경고와 함께 no-op으로 동작해야 한다는 것입니다.
  • breaking wire/postMessage 변경은 v1 옆에 새 major로 배포됩니다: /embed/v2/kaleidr.js (+ /embed/v2/<product>.js). 고정한 v1 URL은 그대로 계속 작동하며, 원하는 일정에 맞춰 path를 올려 마이그레이션할 수 있습니다.

SSE wire contract도 동일한 방식으로 /inference-api/b2b/v1/*에서 버전 관리됩니다 — v2는 breaking stream 변경이 있을 때만 나타납니다.

캐싱​

bundle은 Cache-Control: public, max-age=300으로 제공되며 모든 publish는 CloudFront distribution을 invalidation합니다 — 따라서 실제 전파 시간은 edge에서 약 1–5분, 이전 파일을 이미 캐시한 browser의 경우 최대 300초가 추가될 수 있습니다. 수정 배포에는 빠르지만, 같은 이유로 교체 계획 없이 이러한 파일을 fingerprint하거나 장기간 로컬 캐시해서는 안 됩니다.

Self-hosting​

kaleidr.js만 자체 origin으로 지정해도 Kaleidr CDN에서 분리되는 것은 아닙니다 — loader는 mount 시 lazy bundle (chat.js, editor.js, viewer.js, tile.js)을 계속 cdn.kaleidr.com에서 가져옵니다. 완전히 self-host하려면 loader base를 재정의하고 5개 파일 모두를 {origin}/embed/v1/에 미러링하세요:

<script>window.__KALEIDR_EMBED_BASE__ = 'https://cdn.example.com';</script>
<script src="https://cdn.example.com/embed/v1/kaleidr.js"></script>

embed가 platform API 또는 private tile CDN과도 통신한다면 각 항목을 개별적으로 재정의하세요 — api-base, viewer-base, tile-base를 참조하세요.