X-Cache header: látható cache-status a kliens integrációk optimalizálásához

Most minden válasz egyik közül a három fejlécet hordozza:

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

Ez egy kis változás - a fejléc plusz egy oszlop az api_request_log-ban - de ez egy egész optimalizálási osztályt nyit meg, amely korábban körvonalatlan terület volt.

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

Hajtsa újra ugyanazzal a kérés törzsével:

# X-Cache: HIT

A /v1/transits/now típusú endpointokhoz (dinamikus idő) - X-Cache: BYPASS, mert az eredmény függ a jelenlegi Date.now()-től, és nincs értelme cache-elni.

Not all endpoints are cached - and this is intentional. Breakdown:

• Deterministic chart calculations (/v1/chart, /v1/houses, /v1/aspects, /v1/synastry, /v1/dasha/*, /v1/vargas/*) - fully cached. Expected MISS → HIT pattern.
• Time-dependent (/v1/transits/now, /v1/horoscope/today, /v1/moon/phase-now) - BYPASS. The cache could be correct only until the end of the minute, so it’s simpler not to cache at all.
• AI-generated content (/v1/horoscope/personal, /v1/interpret/*): BYPASS. LLM responses are not deterministic even with the same prompt, caching = fixing randomness.
• Render endpoints (/v1/render/*): MISS/HIT for some, BYPASS for those accepting large payloads (eclipse-path with 500 points).

The marker for a specific endpoint is visible immediately from the response - no need to read the documentation to understand whether it is cached or not.

This is the most important thing to understand - cached requests still deduct credits on the same tier as MISS. Why:

1. Az árazásunk a végpont üzleti értékére van kalibrálva, nem a CPU-költségre. A /v1/chart ugyanannyiba kerül, akár újra kiszámoltuk a chartot, akár a cache-ből jött - a kliens ugyanazt a chartot kapja.
2. Transparency. We don’t want a situation where one user base pays for MISS and another for HIT (theoretically through ‘luck with cache’). Pricing predictable.
3. Cache infrastructure: this is infrastructure, not value-add. We subsidize it in the tier.

But this does not mean that X-Cache is meaningless in a pricing context - it visibly shows architectural possibilities for the client (see next section).

Négy praktikus minta:

Ha látja az X-Cache: MISS fejlécet egy olyan kéréshez, amely ismételhető (egy személy natális térképe), gyorsítótárazza helyileg Redis/Memcached/IndexedDB-ben. A szerveroldali cache-nk TTL-vel és eviction-politikával rendelkezik - az ügyféloldali réteg, amely kontrollált TTL-vel rendelkezik, elkerüli a felesleges credit-deduct-et.

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;
}

Ha a szolgáltatásod tömeges kéréseket fogad egyforma birth-data-ra (onboarding kampánya, ahol a kollégák azonos demó adatokkal tesztelnek), használj promisos deduplikációt:

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;
}

Ez nem spórol créditet (minden hívás továbbra is számít), de eltávolítja a blokkolást a konkurencia-csúcsok idején.

Ha a termékben rituális diagramok vannak (népszerű napi horoszkóp jelek), előmelegítsé őket ütemezett cronnal. Az első hívás naponta - MISS, mindenkövetkező az eviction-ig - HIT. A felhasználó másodpercek alatt kapja a választ.

Az új oszlop a cache hit % a /dashboard/usage-ban, endpointenként mutatja:

• HIT% = 90+ - az endpoint jól gyorsítótárazható, valószínűleg ugyanazt a diagramot küldi többször is. Fontolja meg az ügyféloldali deduplikációt (#2).
• HIT% = 0 és BYPASS: az endpoint nem gyorsítótárazható tervezés szerint (transits/now, AI). Ez normális.
• HIT% = 50% és MISS: a kérések fele egyedi paraméterekkel, fele ismétlődéssel. Érdemes ügyféloldali cache-t használni.
• Alacsony HIT% + determinisztikus endpoint: gyanús. Ellenőrizze, hogy az ügyfele ne adja hozzá a payload-hoz véletlen mezőket (time stamps, request-id), amelyek elrontják a cache-kulcsot.

A nyomkövetés egy oszlopot használ a api_request_log.cache_status-ben (enum: MISS|HIT|BYPASS, migráció 030). Az oszlop feltöltése ugyanazt a handler-t használja, amely döntéshoz a keresésről a cache-ben - nem történik további DB lekérdezés.

A GET /v1/me/usage/endpoints most valós cache_hit_pct értéket ad vissza null helyett minden endpoint számára az előzményben. Az SDK metódus client.me.usage.endpoints() automatikusan kapja ezt a mezőt (típusok a következő codegen kiadásban).

A cache instrumentálás egy középső szintű optimalizálási szintet nyit meg a “no caching” és a “full edge cache” között. A következő lépések a térképen:

• Cache-Control válaszfejléc valós TTL-vel a gyorsítótárazható endpointokhoz - lehetővé teszi a CDN/proxy cache-t az ügyfél oldalán
• If-None-Match ETags: ismételt MISS-ellenőrzés teljes payload nélkül a válaszban
• Felhasználóankénti cache statisztikák a dashboardban invalidálási lehetőséggel (például kényszerített újraszámítás bizonyos diagramokra a birth-time javítása után)

A dokumentáció - /docs/api/ → Performance & Caching. A konkrét X-Cache referencia - az egyes endpointok fejlécek szakaszában.