holodepth

Asset pipeline · Üretim → runtime köprüsü

Versiyon & Önbellek Mührü: Hash, Stale ve Immutable

Aynı URL farklı byte taşıyabilir; tarayıcı ve CDN önbelleği bunu fark etmez. Bu sayfa versiyon mührü ve cache-bust disiplinini anlatır — HTTP header derinliği CDN yaprağına bırakılır.

CDN header stratejisi bir sonraki izlekte derinleşir. Burada dosya adı, hash ve build manifest arasındaki ilişki kurulur: hangi byte'ın hangi sürüme ait olduğunu söyleyen tek gerçek kaynağın ne olduğu netleştirilir.

Versiyon mührü küçük görünen ama pahalı bir sorunu çözer: bir kod deploy'u ile bir asset güncellemesi genellikle farklı zamanlarda olur. Mühür yoksa kullanıcı tarayıcısı eski dosyayı, yeni kodla birlikte sunar — ve bu hata genelde «bende çalışıyor» diye kapatılır çünkü geliştiricinin kendi tarayıcısı zaten güncel dosyayı indirmiştir.

Sayfayı bitirdiğinizde şu cümleyi kurabilmelisiniz: «Content hash dosya adında mühürdür; query string tek başına yeterli güvence vermez; manifest hangi hash'in aktif olduğunu söyler; build ve runtime versiyonu senkron değilse stale asset kaçınılmazdır.»

Bu sayfanın sınırı

Bu sayfa şunları anlatır:

  • Content hash ve dosya adı mührü
  • Stale asset riski ve rollback senaryosu
  • Build ↔ runtime versiyon eşlemesi

Bilinçli olarak dışarıda bırakılan konular:

  • Cache-Control header detayı → CDN & dağıtım
  • glTF iç şema versiyonu → glTF format
  • Sunucu tarafı build sistemi kurulumu → DevOps

Kısa ayrım: Bu sayfa «hangi byte hangi sürüm» · CDN «header politikası».

Content hash: dosya adında mühür

Holodepth önerisi: hero-scan.[hash].glb veya klasör + manifest.json içinde hash alanı. Query string (?v=2) hızlıdır ama bazı proxy ve CDN katmanları query'yi cache anahtarından hariç tutabilir — bu da tutarsızlık üretir; hash dosya adında daha güvenilirdir çünkü path'in kendisi değişir.

Hash, dosya içeriğinden türetilir (içerik hash'i), sıra numarasından değil — böylece içerik değişmediği sürece hash aynı kalır ve gereksiz cache invalidation olmaz. Aynı byte iki kere aynı hash'i üretir; bu da CDN'de deduplication imkânı sağlar.

Stale riski: eski mesh, yeni kod

Kod deploy oldu, asset aynı URL'de kaldı → kullanıcı eski geometriyi görür, hatta yeni kodun beklediği bir node ismi eski dosyada yoksa sahne hiç render olmaz. Çözüm: asset manifest versiyonu uygulama build id ile birlikte artar; loader URL'i manifest'ten okur, sabit string olarak koda gömülmez.

Stale riski özellikle uzun süreli sekme açık bırakan kullanıcılarda görünür — sekme kapatılıp açılmadıkça tarayıcı yeni bir manifest çekmeyebilir. Bu nedenle manifest'in kendisi kısa ömürlü cache politikasıyla sunulmalıdır (detay CDN yaprağında).

Immutable dosya + değişen manifest

Hash'li dosyalar uzun ömürlü cache alabilir çünkü içerik değişirse zaten yeni bir hash/dosya adı üretilir — aynı URL asla farklı byte taşımaz. Kısa ömürlü manifest.json ise hangi hash'in şu an aktif olduğunu söyler. CDN yaprağında bu ikisine farklı header eşlemesi yapılır.

Bu iki katmanlı model («immutable içerik + değişken işaretçi») web'de yaygın bir desendir; asset pipeline'da da aynı mantıkla çalışır ve versiyon geçişini anlık, geri alınabilir hale getirir.

Query string mühür ile path hash karşılaştırması

İki yaygın yaklaşım da «doğru» olabilir; hangisinin seçileceği altyapıya bağlıdır. Aşağıdaki tablo, ikisi arasındaki pratik farkı özetler.

Query string vs dosya adında hash
Yaklaşım Avantaj Risk
?v=hash Uygulamak kolay, dosya adı sabit Bazı proxy'lerde cache anahtarı dışı
name.hash.glb Her CDN'de güvenilir immutable cache Dosya listeleme/temizlik biraz daha karmaşık

Build pipeline entegrasyonu: hash ne zaman üretilir?

Hash, ideal olarak CI/CD sürecinde otomatik üretilir — asset export edildikten hemen sonra bir betik dosya içeriğini hash'ler, manifest'i günceller ve bu güncel manifest ile birlikte deploy eder. Elle hash hesaplayıp elle manifest düzenlemek, insan hatasına en açık noktadır.

Holodepth önerisi: hash üretimi ile manifest güncellemesi aynı otomasyon adımında olur; ikisi ayrı adımlarda yapılırsa aralarında senkronsuzluk penceresi açılır.

Rollback ve A/B: iki versiyon bir arada

İçerik hash'i sayesinde eski ve yeni versiyon aynı CDN'de yan yana yaşayabilir — hiçbiri diğerinin üzerine yazmaz. Bu, rollback'i «yeniden deploy» değil «manifest'i eski hash'e geri döndürme» işlemine indirir, saniyeler sürer.

Aynı özellik A/B testleri için de kullanılabilir: manifest, kullanıcı segmentine göre farklı hash'lere işaret edebilir. Bu senaryo, karar mantığının manifest sözleşmesine yaslandığını gösterir.

Geliştirici deneyimi: local dev'de hash disiplini

Yerel geliştirmede hash üretmek gereksiz karmaşıklık gibi görünebilir; bu yüzden çoğu proje dev modunda sabit dosya adı, prod modunda hash'li dosya adı kullanır. Önemli olan, iki modun da aynı manifest sözleşmesini (loader'ın URL'i manifest'ten okuması) izlemesidir — aksi halde dev'de çalışan kod prod'da farklı davranır.

Yanlış versiyon kalıpları

  • model.glb tek adıyla sonsuz overwrite
  • Hard-coded URL string'lerin kod içinde dağınık tekrarı
  • Hash'siz dosyaya CDN'de «immutable» header basmak
  • Manifest üretimi ile deploy CI'da senkron değil
  • Rollback'i «eski koda dönüş» ile karıştırmak, asset'i unutmak

Versiyon mührü yoksa hız optimizasyonlarının hepsi «yanlış dosyayı daha hızlı sunmak» riskini taşır.

Simüle: manifest + hash URL çözümleme

{
  "buildId": "2026.07.14-1042",
  "assets": {
    "hero-scan": {
      "path": "/cdn/characters/hero-scan.a8f3c2.glb",
      "hash": "a8f3c2",
      "bytes": 1840000,
      "previousHash": "7e11d0"
    }
  }
}
export function resolveAssetUrl(manifest, key) {
  const entry = manifest.assets[key]
  if (!entry?.path) throw new Error('Asset missing: ' + key)
  return entry.path // hash dosya adinda - query gerekmez
}

export function resolveRollbackUrl(manifest, key) {
  const entry = manifest.assets[key]
  if (!entry?.previousHash) return null
  return entry.path.replace(entry.hash, entry.previousHash)
}

Üç versiyonlama profili

  • 01 · Versiyon

    Tek sürüm

    Hash kaynağı
    Manuel/CI opsiyonel
    Rollback
    Elle
    Risk
    Stale asset fark edilmez
  • 02 · Versiyon

    Kademeli rollout

    Hash kaynağı
    CI otomatik
    Rollback
    Manifest geri al
    Risk
    İki hash arası tutarlılık
  • 03 · Versiyon

    A/B içerik

    Hash kaynağı
    Segment bazlı manifest
    Rollback
    Segment geri al
    Risk
    Manifest karmaşıklığı

Holodepth perspektifleri

Mühür, hız değil güven meselesidir

Versiyon mührü olmadan CDN hızlandırması «yanlış modeli hızlı göstermek» olur — hız, doğruluğun yerini tutmaz.

Manifest tek gerçek kaynaktır

Hangi hash'in aktif olduğu bilgisi koda değil manifest'e ait olmalı; kod her zaman manifest'i sorar, asla kendi tahminini yapmaz.

Rollback bir özellik olarak tasarlanır

previousHash gibi küçük bir alan, acil bir üretim sorununda dakikalar kazandırır — sonradan eklemek yerine baştan planlanmalıdır.

  1. Her asset dosya adında içerik hash'i taşıyor mu?
  2. Loader URL'i manifest'ten mi okunuyor, kodda mı gömülü?
  3. Manifest kısa ömürlü, hash'li dosyalar uzun ömürlü cache mi alıyor?
  4. Hash üretimi ile deploy aynı otomasyon adımında mı?
  5. Rollback için önceki hash saklanıyor mu?
  6. Dev ve prod ortamı aynı manifest sözleşmesini mi izliyor?

Holodepth içgörüsü

Üretim → runtime izleği burada kapanır; dağıtım izleği CDN ile devam eder ve bu mührü header politikasına bağlar.

Sonraki kapı

Sıradaki izlek Dağıtım & varlık ömrü; ilk yaprak CDN & statik dağıtım — mühür burada header politikasıyla buluşur.