Debugging API Edge SvelteKit sering menuntut pendekatan sistematis ketika produksi menunjukkan timeout yang tidak konsisten. Kasus ini dimulai dari servis API edge yang kadang memberikan timeout berulang di satu endpoint penting, meskipun load normal, dan kepastian bahwa service lain tetap sehat.

Dalam 1-2 paragraf ini, jawaban langsungnya: timeout tersebut disebabkan oleh cache stale di layer CDN / edge cache internal yang dipaksa tetap valid karena race invalidasi. Artikel ini memaparkan gejala, korelasi log dan metric, analisis root cause, langkah perbaikan yang konkret, serta tata observability untuk mencegah regresi serupa.

Gejala Timeout dan Konteks Produksi

Tim operasi mencatat bahwa timeout muncul hanya pada endpoint API yang mengembalikan data tabel master. Timeout tercatat di edge API gateway setelah 1,5 detik, walaupun upstream origin mampu memberikan respons < 200 ms. Endpoint sama berjalan normal di staging, sementara dashboard latensi menunjukkan spike instan secara sporadis di lingkungan edge.

Cache control header standar sudah diterapkan, sehingga awalnya diduga network atau origin overload. Namun, request log memperlihatkan bahwa edge cache kerap menyajikan respons dengan status 200 walaupun hash konten seharusnya berbeda karena update data. Ini memberitahu kita bahwa cache tidak selalu invalidasi secara konsisten.

Analisis Log dan Korelasi Metric

Tahap selanjutnya adalah menggabungkan log edge gateway dengan metric observability. Dalam sistem kita terdapat metric latency per edge node, error rate, dan cache hit ratio. Pada waktu timeout, terlihat spike cache hit ratio mendekati 99% dan latency meningkat drastis, menandakan edge tetap melayani konten lama secara berulang walau data origin sudah berubah.

Log internal SvelteKit yang dikirim dari events.fetch mengonfirmasi bahwa salah satu panggilan background untuk invalidasi cache diproses dengan delay panjang. Kunci observasi: entry invalidasi cache berjalan melalui queue yang sharing resource, sehingga request update dan fetch bersamaan memunculkan race state.

Root Cause: Cache Stale dan Race Invalidasi

Root cause teridentifikasi sebagai stale cache di layer edge bersamaan dengan race invalidasi. Arsitektur kita memakai CDN + SvelteKit edge function. Ketika data berubah, backend menerbitkan webhook untuk memanggil endpoint API edge dan mengirim header Surrogate-Key untuk invalidasi.

Masalah muncul saat webhook diproses hampir bersamaan dengan request publik: tugas invalidasi dijalankan di worker queue yang kadang tertunda, sementara edge cache masih melayani respons berdasarkan key lama. Jika queue backlog naik, invalidasi terlambat hingga request berikutnya mengalami timeout karena cache lookup menunggu key lama yang dianggap valid.

Terminologi race: request pertama yang memicu invalidasi akan melihat cache kotor, tetapi cache controller menganggap key belum kadaluarsa. Request publik berikutnya kemudian menghadapi waktu tunggu tambahan saat edge mencoba menghubungi origin, lalu berakhir dengan timeout. Inilah alasan log latency edge meningkat bersamaan dengan hit ratio yang tinggi.

Perbaikan Langsung pada API Edge

Perbaikan dilakukan dalam tiga langkah konkrit:

  1. Perbaiki mekanisme invalidasi agar bersifat atomic: tambahkan flag pada queue untuk menandai invalidation ongoing, sehingga request baru bisa memaksa bypass cache sementara.
  2. Tingkatkan logika header cache di SvelteKit edge, menggunakan kombinasi Cache-Control dan Surrogate-Key agar edge cache dapat dipurge secara spesifik.
  3. Tambahkan fallback cache bypass saat webhook invalidasi terlambat, sehingga request publik bisa memaksa origin fetch, dan memastikan response tak timeout meskipun cache stale.

Berikut contoh potongan +server.ts untuk memastikan bypass cache saat invalidasi berjalan:

export const GET = async ({ url, setHeaders, fetch }) => {
  const forceFresh = url.searchParams.get('bypass_cache') === '1';

  if (forceFresh) {
    setHeaders({
      'Cache-Control': 'no-store',
      'Surrogate-Control': 'max-age=0'
    });
  } else {
    setHeaders({
      'Cache-Control': 'public, max-age=30',
      'Surrogate-Control': 'max-age=60'
    });
  }

  const response = await fetch('https://origin.internal/api/master');
  return new Response(await response.text(), response);
};

Dengan flag bypass_cache yang diatur oleh proses invalidasi, edge dapat memaksa origin fetch saat queue invalidasi masih pending. Perhatikan juga bahwa header surrogate diberikan agar CDN dapat menyasar invalidasi lebih presisi.

Observabilitas untuk Mencegah Regresi

Setelah perbaikan, observability perlu ditingkatkan untuk memastikan deteksi dini saat cache stale kembali terjadi. Rekomendasi metric dan log:

  • Tambahkan metric invalidations_pending dan cache_bypass_hits untuk memantau antrian invalidasi dan berapa banyak request memaksa bypass cache.
  • Catat timestamp invalidasi dan hasilnya pada log terstruktur, termasuk header Surrogate-Key yang digunakan. Ini memudahkan korelasi antara webhook, worker queue, dan request timeout.
  • Gunakan tracing distribusi untuk melihat apakah edge function masih menunggu worker invalidation sebelum menyelesaikan request.

Juga penting menyusun runbook: jika latency spike disertai cache hit tinggi dan invalidations_pending meningkat, maka jalankan perintah purge manual dan periksa backlog queue worker. Dengan pemantauan tersebut, regresi serupa dapat diidentifikasi sebelum pengguna akhir mengalami timeout.

Ringkasnya, debugging API Edge SvelteKit pada kasus timeout ini berhasil karena pendekatan kombinasi data log, analisis cache stale, dan implementasi perbaikan cache control serta observabilitas yang konkret.