X-Cache header: görünür cache-status istemci entegrasyonları için optimizasyon

Server-side ön bellek uzun süredir çalışıyor - deterministik grafik hesaplaması aynı date/time/lat/lon için ön bellekten döndürülür, yeniden hesaplanmaz. Ancak istemci bu görmedi. Dashboard’daki “cache hit %” sütunu – gösteriyordu, çünkü backend cache-outcome’u dahili metrikede logluyordu, yanıtta değil.

Şimdi her yanıt üç başlıktan birini içerir:

X-Cache: HIT      # обслужено з кешу
X-Cache: MISS     # обчислено з нуля, результат збережено
X-Cache: BYPASS   # не кешується за дизайном

Bu küçük bir değişiklik - başlık plus api_request_log tablosunda bir sütun - ancak bu, önceki olarak kör nokta olan bir optimizasyon sınıfını açar.

curl -I -X POST https://api.astroway.info/v1/chart \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1990-05-15",
    "time": "14:30:00",
    "timezoneOffset": 3,
    "latitude": 50.45,
    "longitude": 30.52
  }' | grep -i x-cache
# X-Cache: MISS

Aynı istek gövdesi ile ikinci kez çalıştırın:

# X-Cache: HIT

/v1/transits/now türü endpoint’ler için (dinamik zaman) - X-Cache: BYPASS, çünkü sonuç şu anki Date.now()’a bağlı ve önbellekleme anlamlı değil.

Her endpoint önbelleklenmez - ve bu amaçlı. Ayrıntı:

• Deterministic chart hesaplamaları (/v1/chart, /v1/houses, /v1/aspects, /v1/synastry, /v1/dasha/*, /v1/vargas/*) - tamamen önbelleklenir. Beklenen MISS → HIT deseni.
• Zaman bağımlı (/v1/transits/now, /v1/horoscope/today, /v1/moon/phase-now) - BYPASS. Önbellek sadece dakika sonuna kadar doğru olabilirdi, bu yüzden genel olarak önbelleklememek daha basit.
• AI tarafından üretilen içerik (/v1/horoscope/personal, /v1/interpret/*): BYPASS. LLM yanıtları aynı promptta bile deterministik değildir, önbellekleme = rastgeleliği sabitlemek.
• Render endpoint’leri (/v1/render/*): bazıları için MISS/HIT, büyük payload kabul edenler için BYPASS (örneğin 500 noktadan oluşan eclipse-path).

Belirli bir endpoint için işaret, yanıttan hemen görülebilir - dokümantasyonu okumadan önbelleklenip önbelleklenmediğini anlamak gerekmez.

Bu anlaşılması için en önemli şey - önbelleklenmiş istekler hâlâ crediti düşürür, MISS ile aynı tier’de. Neden:

1. Pricing’imiz endpoint’in iş değerine göre kalibre edilmiştir, CPU maliyeti değil. /v1/chart, grafik yeniden hesaplansa da ön bellekten gelse de aynı maliyette olur - istemci aynı grafiği alır.
2. Şeffaflık. Bir kullanım grubunun MISS için ödemesi ve diğerinin HIT için ödemesi (teoretik olarak “önbellek şansı” ile) olmasını istemiyoruz. Fiyatlandırma tahmin edilebilir.
3. Önbellek altyapısı: bu altyapı, değer eklemiyor. Bunun tier içinde subvansiyonu yapıyoruz.

Ama bu, X-Cache’in pricing bağlamında anlamlı olmadığı anlamına gelmez - görünüşe göre istemci için mimari olanaklar gösterir (bölümümün devamına bakın).

Dört pratik desen:

X-Cache: MISS görürseniz, tekrarlanabilecek bir istek için (örneğin aynı kişinin natal haritası), yerel olarak Redis/Memcached/IndexedDB’de önbellekleyin. Server-side ön belleğimiz TTL ve çıkarma politikasına sahiptir - istemci tarafınızın kontrollü TTL’li katmanı gereksiz crediti düşürmesini önler.

import { Astroway } from "@astroway/sdk";

const cache = new Redis();
const client = new Astroway({
  apiKey: process.env.ASTROWAY_KEY,
  // optional: hook on response headers
  onResponse(req, res) {
    const cacheStatus = res.headers["x-cache"];
    metrics.increment(`astroway.cache.${cacheStatus.toLowerCase()}`);
  },
});

async function getChart(input: ChartInput) {
  const cacheKey = `chart:${hashChart(input)}`;
  const cached = await cache.get(cacheKey);
  if (cached) return JSON.parse(cached);

  const chart = await client.chart.create(input);
  await cache.set(cacheKey, JSON.stringify(chart), "EX", 86400);
  return chart;
}

Servisiniz aynı birth-data’ya yönelik toplu istekler alıyorsa (onboarding kampanyası, arkadaşlar aynı demo verileriyle test ediyorsa), promiseli dedupe kullanın:

const inFlight = new Map<string, Promise<Chart>>();

function getChart(input: ChartInput) {
  const key = hashChart(input);
  if (inFlight.has(key)) return inFlight.get(key)!;

  const promise = client.chart.create(input);
  inFlight.set(key, promise);
  promise.finally(() => inFlight.delete(key));
  return promise;
}

Bu crediti tasarruf etmez (her çağrı yine sayılır), ancak eşzamanlılık dalgalanmalarında bottleneck’leri kaldırır.

Ürününüzde ritüel grafikler varsa (popüler günlük horoskop burçları), bunları zamanlanmış cron ile önceden ısıtın. Günün ilk çağrısı MISS, sonraki tüm çağrılar çıkarma olana kadar HIT. Kullanıcı alt-saniye yanıt alır.

/dashboard/usage’deki yeni cache hit % sütunu endpoint bazında şunu gösterir:

• HIT% = 90+ - endpoint iyi önbelleklenir, muhtemelen aynı grafik birkaç kez gönderiliyor. İstemci tarafı dedupe (#2)yi düşünün.
• HIT% = 0 ve BYPASS: endpoint tasarım olarak önbelleklenmez (transits/now, AI). Bu normal.
• HIT% = 50% ve MISS: isteklerin yarısı benzersiz parametreler taşıyor, yarısı tekrarlar. İstemci tarafı önbellekleme değerli.
• HIT% düşük + endpoint deterministik: şüpheli. İstemcinizin payload’a (zaman damgaları, request-id) rastgele alanlar ekleyip eklemediğini kontrol edin, bu anahtarları önbellek anahtarını bloke edebilir.

Takip, api_request_log.cache_status adlı bir sütun maliyetidir (enum: MISS|HIT|BYPASS, migration 030). Sütun, кеш-lookup kararı alan aynı handler tarafından doldurulur - ekstra DB sorgusu yapılmaz.

GET /v1/me/usage/endpoints artık geçmişinizdeki her endpoint için gerçek cache_hit_pct değerini döndürür, null yerine. SDK metodu client.me.usage.endpoints() bu alanı otomatik olarak alır (tipler sonraki codegen sürümünde).

Önbellek enstrümantasyonu, “no caching” ve “full edge cache” arasında bir optimizasyon seviyesi açar. Roadmap’teki sonraki adımlar:

• Cache-Control yanıt başlığı, önbelleklenmiş endpoint’ler için gerçek TTL ile - CDN/proxy önbelleği istemci tarafında kullanılabilir hale getirecek.
• If-None-Match ETags: yanıtta tam payload olmadan tekrar MISS kontrolleri.
• Dashboard’da per-user önbellek istatistikleri, invalidate imkanıyla (örneğin, birth-time düzeltildikten sonra certain chart’ı zorla yeniden hesapla).

Dokümantasyon - /docs/api/ → Performance & Caching. Belirli X-Cache referansı - her endpoint’in headers bölümünde.