Server Rumahan & Self-Hosting

Menyajikan Konten Stale dengan NGINX - Menukar Sedikit Kesegaran demi Gangguan yang Lebih Kecil

Menyajikan Konten Stale dengan NGINX - Menukar Sedikit Kesegaran demi Gangguan yang Lebih Kecil

Server aplikasi berhenti merespons, tetapi NGINX masih menyimpan artikel publik kemarin di cache. Respons mana yang lebih jujur: artikel lama itu atau halaman 502 Bad Gateway yang baru?

Tidak ada jawaban yang berlaku untuk semua keadaan. Halaman dokumentasi lama mungkin masih berguna selama gangguan singkat. Saldo akun, keputusan akses, atau koreksi darurat yang lama bisa jadi tidak dapat diterima. Karena itu, menyajikan konten stale bukan sekadar sakelar performa. Ini adalah kebijakan yang menukar sebagian freshness dengan kontinuitas terbatas, dan pertukaran tersebut hanya masuk akal jika respons, cache key, dan jendela kegagalannya dipahami.

NGINX dapat membuat kebijakan itu eksplisit dengan proxy_cache_use_stale. Bagian yang berguna bukan hanya directive tersebut, melainkan batas di sekelilingnya: apa yang boleh masuk ke cache, kegagalan mana yang memenuhi syarat, berapa lama konten lama masih dapat ditoleransi, dan bagaimana operator mengetahui bahwa fallback sedang terjadi.

Stale bukan berarti hilang atau rusak

RFC 9111 menyebut respons tersimpan sebagai fresh selama usianya belum melampaui freshness lifetime. Setelah titik itu, respons tersebut menjadi stale. Stale menjelaskan usia, bukan integritas. Cache mungkin masih menyimpan respons lengkap yang valid saat disimpan.

Dalam kondisi biasa, cache dapat melakukan revalidation terhadap respons itu ke origin, sering kali dengan mengirim If-None-Match atau If-Modified-Since. Origin dapat mengonfirmasinya dengan 304 Not Modified atau mengirim representasi baru. Ketika origin gagal, percakapan itu belum tentu dapat selesai. Kebijakan stale-on-error mengizinkan cache memakai respons lama yang tersimpan alih-alih meneruskan kegagalan.

Fallback tersebut memiliki dua prasyarat yang mudah terlewat:

  • Entri cache yang cocok harus sudah ada. Request dingin tidak bisa memakai objek yang belum pernah disimpan sebagai fallback.
  • Entri itu harus masih dipertahankan. Di NGINX, parameter inactive dapat menghapus entri setelah suatu periode tanpa akses, terlepas dari apakah freshness dan stale window yang diizinkan menceritakan hal berbeda.

Karena itu, stale delivery adalah jaring pengaman bersyarat, bukan salinan offline seluruh situs dan bukan jaminan availability.

Tiga jam menjawab pertanyaan yang berbeda

Konfigurasi yang cermat memisahkan tiga jenis waktu:

  1. Freshness lifetime: berapa lama respons secara normal boleh digunakan kembali tanpa validation, biasanya dikendalikan oleh max-age, s-maxage, Expires, atau aturan validitas cache NGINX.
  2. Staleness yang diizinkan: berapa lama respons kedaluwarsa masih dapat diterima dalam pengecualian tertentu, seperti error dari origin.
  3. Retensi cache: berapa lama NGINX menyimpan entri yang tidak diakses, yang antara lain dikendalikan oleh inactive, ukuran cache, dan eviction.

Ketiganya tidak dapat saling menggantikan. Respons bisa stale tetapi masih disimpan, fresh tetapi terhapus demi ruang, atau tersimpan jauh melampaui periode ketika kebijakan mengizinkannya disajikan. Menyebut ketiga nilai itu sebagai “cache timeout” menyembunyikan keputusan yang seharusnya tetap terpisah.

Kebijakan NGINX dan kebijakan respons HTTP

Ada dua tempat yang berguna untuk menyatakan izin menyajikan konten stale.

Di reverse proxy, dokumentasi NGINX menjelaskan proxy_cache_use_stale dengan kondisi spesifik seperti error, timeout, invalid_header, updating, dan kode status HTTP tertentu. Nilai default-nya adalah off. Ini memberi operator infrastruktur suatu kebijakan untuk sebuah cakupan konfigurasi.

proxy_cache_use_stale error timeout invalid_header
                      http_500 http_502 http_503 http_504;

Di respons origin, extension yang didefinisikan oleh RFC 5861 dapat menempelkan kebijakan berbatas pada representasi itu sendiri:

Cache-Control: public, max-age=300, stale-if-error=900

Contoh ini menyatakan bahwa respons fresh selama 300 detik dan dapat digunakan ketika terjadi error hingga tambahan 900 detik dalam keadaan stale. Ini tidak membuat respons fresh selama 1.200 detik dan tidak menjanjikan bahwa cache akan menyimpannya. RFC 5861 menjelaskan error untuk extension ini sebagai respons yang jika tidak memakai fallback akan berupa 500, 502, 503, atau 504.

NGINX mendukung stale-if-error dan stale-while-revalidate dari field Cache-Control upstream. Dokumentasinya mencatat bahwa izin berbasis header ini memiliki prioritas lebih rendah daripada parameter yang dikonfigurasi dalam proxy_cache_use_stale. Urutan itu penting: aturan proxy yang luas dapat melampaui atau mengesampingkan maksud lebih sempit yang dinyatakan aplikasi.

Pilih pemilik kebijakan dengan sengaja. Header yang dimiliki aplikasi dapat ikut bersama setiap respons dan berbeda menurut resource. Aturan NGINX dapat menyediakan satu kebijakan operasional meski upstream tidak dapat mengirim extension tersebut. Menggabungkan keduanya sah, tetapi hanya jika prioritas efektifnya ditinjau, bukan sekadar diasumsikan.

Konfigurasi sempit untuk halaman publik

Sketsa berikut sengaja dibatasi pada path publik anonim. Durasinya adalah contoh, bukan nilai universal yang direkomendasikan, dan konfigurasi ini tidak disajikan sebagai konfigurasi production situs ini.

# http context
proxy_cache_path /var/cache/nginx/public
    levels=1:2
    keys_zone=public_pages:10m
    max_size=1g
    inactive=60m
    use_temp_path=off;

server {
    location /public/ {
        proxy_pass http://app_backend;

        proxy_cache public_pages;
        proxy_cache_methods GET HEAD;
        proxy_cache_valid 200 5m;
        proxy_cache_revalidate on;
        proxy_cache_lock on;

        proxy_cache_use_stale error timeout invalid_header
                              http_500 http_502 http_503 http_504
                              updating;
        proxy_cache_background_update on;

        add_header X-Cache-Status $upstream_cache_status always;
    }
}

proxy_cache_background_update on memulai subrequest di background untuk memperbarui entri kedaluwarsa sementara client menerima entri stale. NGINX mengharuskan stale dapat digunakan selama updating agar perilaku itu bekerja. Ini menyelesaikan masalah yang berbeda dari stale-if-error: background update menyembunyikan latency refresh, sedangkan stale-on-error menangani kegagalan saat menjangkau atau menggunakan upstream.

proxy_cache_lock on juga memiliki tugas berbeda. Directive ini mengizinkan satu request pada satu waktu mengisi elemen cache baru untuk sebuah key sementara request lain menunggu, sehingga mengurangi ledakan miss setara yang mencapai upstream. Ia tidak menciptakan konten stale dan tidak dapat membantu request pertama jika tidak ada entri yang dapat digunakan.

Panduan caching NGINX menjelaskan berbagai kontrol ini bersama-sama, tetapi deployment nyata tetap membutuhkan aturan aplikasinya sendiri. Cache-Control dari upstream, Set-Cookie, Vary, authorization, dan cache key sama-sama memengaruhi apakah reuse sudah benar. NGINX secara normal menghindari caching respons dengan Set-Cookie dan respons dengan Vary: *; default tersebut adalah pengaman, bukan pengganti klasifikasi route.

Tentukan apa yang tidak boleh memakai fallback ini

Aturan cache terpenting mungkin justru daftar pengecualian. Shared cache dapat menggunakan kembali satu respons tersimpan untuk banyak pengguna, sehingga batas yang keliru dapat membocorkan data atau menampilkan keadaan seorang pengguna kepada pengguna lain. Referensi Cache-Control MDN merekomendasikan private untuk konten personal dan menjelaskan bahwa no-store mencegah penyimpanan. RFC 9111 juga memberi batasan khusus pada shared caching untuk request yang membawa Authorization.

Jangan menempatkan halaman login, dashboard akun, respons API per pengguna, keranjang, keputusan authorization, atau state sensitif lain di bawah aturan public cache yang luas hanya karena semuanya memakai GET. Bypass berdasarkan session cookie dapat menjadi bagian desain, tetapi “kebetulan tidak ada cookie” bukan bukti bahwa setiap representasi pada route tersebut bersifat publik.

Konten dapat bersifat publik tetapi tetap menjadi kandidat stale yang buruk. Pertimbangkan pemberitahuan keamanan mendesak, download yang dicabut, ketersediaan yang cepat berubah, atau halaman dengan instruksi lama yang menjadi berbahaya setelah deployment. Untuk resource seperti itu, error yang terlihat mungkin lebih jujur daripada respons yang tampak normal tetapi sudah usang. Directive seperti no-cache, must-revalidate, dan no-store menyatakan persyaratan lebih ketat; RFC 9111 melarang penyajian stale ketika directive protokol yang berlaku melarangnya.

Buat fallback terlihat sebelum mengandalkannya

Respons 200 yang berhasil dapat menyembunyikan origin yang tidak sehat. NGINX menyediakan variable $upstream_cache_status, dengan kemungkinan state termasuk HIT, MISS, EXPIRED, REVALIDATED, STALE, dan UPDATING. Contoh tadi menerbitkannya sebagai X-Cache-Status untuk diagnosis. Jika membuka state internal cache ke publik tidak diinginkan, masukkan nilainya ke access log.

Pengujian yang aman membutuhkan lebih dari nginx -t. Validasi syntax tidak dapat membuktikan kebijakan cache. Di staging environment atau maintenance window yang terkendali:

  1. Minta URL publik yang sudah diketahui dan pastikan respons yang memenuhi syarat masuk ke cache yang dituju.
  2. Minta kembali URL itu dan amati cache status yang diharapkan.
  3. Tunggu hingga respons menjadi stale, lalu buat upstream pengujian mengembalikan satu kegagalan yang secara khusus dikonfigurasi.
  4. Pastikan response body merupakan representasi lama yang sudah diketahui dan status melaporkan STALE, alih-alih menganggap setiap 200 membuktikan fallback.
  5. Ulangi dengan URL dingin dan route private; keduanya tidak boleh menerima objek stale publik.
  6. Pulihkan upstream dan pastikan revalidation atau replacement mengembalikan cache ke konten terkini.

Uji juga dimensi cache key yang relevan: host, query string, encoding, bahasa, dan setiap field yang disebut oleh Vary. Perilaku saat gagal hanya seaman perilaku pemilihan respons yang mendahuluinya.

Pertukaran ini berguna karena terbatas

Konten stale dapat mengurangi dampak kegagalan aplikasi singkat yang terlihat pengguna, tetapi tidak memperbaiki aplikasi, mempertahankan operasi write, atau menjamin setiap URL tetap tersedia. Mekanisme ini juga dapat menunda penemuan masalah jika monitoring hanya mengawasi status code client. Karena itu, kesehatan origin dan respons stale memerlukan sinyal terpisah.

Keputusannya lebih mudah ketika dirumuskan per resource: Seberapa tua representasi ini boleh menjadi sebelum error lebih jujur? Kegagalan mana yang membenarkan pengecualian itu? Apakah respons tersimpan yang sama aman disajikan kepada setiap request yang dipetakan ke key tersebut? Bagaimana operator mengetahui bahwa pengecualian sedang aktif?

Untuk artikel atau dokumentasi anonim yang stabil, stale window singkat dan teramati mungkin menjadi alat kontinuitas yang masuk akal. Untuk state personal, sensitif, dapat dicabut, atau cepat berubah, alat ini mungkin sepenuhnya keliru. Tujuannya bukan menyembunyikan setiap outage. Tujuannya adalah memilih sejak awal di mana informasi publik yang sedikit lama lebih aman daripada tidak ada informasi, lalu menjaga izinnya cukup sempit agar keputusan itu tetap benar.

References