Timeout dan Retry di Apache APISIX: Cara Menghindari Transaksi Ganda

Timeout tidak selalu berarti transaksi gagal. Backend bisa saja sudah menyimpan transaksi, tetapi responsnya terlambat atau terputus. Jika permintaan dikirim ulang tanpa perlindungan, pengguna dapat melihat transaksi ganda. Karena itu, pengaturan timeout dan retry di Apache APISIX perlu dirancang bersama mekanisme idempotency pada aplikasi, bukan diputuskan hanya di gateway.

Apa hubungan timeout, retry, dan idempotency?

Timeout menentukan berapa lama suatu tahap komunikasi ditunggu. Retry adalah percobaan ulang saat terjadi kegagalan yang memenuhi kondisi tertentu. Idempotency memastikan pengulangan operasi yang sama tidak menimbulkan efek bisnis tambahan yang tidak diinginkan.

Ketiganya menjawab masalah berbeda. Timeout terlalu pendek dapat memutus permintaan yang sebenarnya masih berjalan. Timeout terlalu panjang membuat pengguna menunggu dan sumber daya tertahan. Retry dapat membantu gangguan sementara, tetapi juga menambah beban pada layanan yang sedang bermasalah. Idempotency membantu menangani permintaan berulang, tetapi harus diterapkan dan diuji di layanan yang memproses transaksi.

Apa yang dapat diatur di Apache APISIX?

Dalam dokumentasi Admin API, APISIX menyediakan timeout untuk tahap koneksi, pengiriman, dan penerimaan data dari upstream. Konfigurasi timeout pada Route dapat menimpa nilai pada Upstream. Dokumentasi juga menjelaskan pengaturan jumlah retries dan retry_timeout pada Upstream. Nilai retries nol menonaktifkan retry; retry_timeout nol menonaktifkan batas waktu retry tersebut. Periksa dokumentasi dan perilaku versi yang digunakan sebelum menerapkan konfigurasi.

Upstream adalah abstraksi kelompok node layanan tujuan. Jika beberapa Route memakai konfigurasi yang sama, objek Upstream bersama dapat mengurangi pengulangan konfigurasi. Namun, perubahan bersama juga berdampak pada seluruh Route yang merujuknya. Petakan dependensi dan uji dampaknya sebelum mengubah nilai.

Apache APISIX adalah proyek API gateway; API7 adalah produk dan perusahaan yang terkait dengan ekosistem APISIX. Jangan menganggap pengaturan, antarmuka, atau fitur setiap produk dan versinya identik tanpa memeriksa dokumentasi yang sesuai.

Skenario ilustrasi: respons pembayaran terlambat

Misalkan aplikasi mengirim permintaan membuat pembayaran melalui gateway. Backend berhasil mencatat pembayaran, tetapi respons tidak sampai sebelum batas tunggu. Client melihat error lalu mengirim ulang. Jika backend memperlakukan setiap permintaan sebagai transaksi baru, pembayaran dapat tercatat dua kali.

Sebaliknya, bila endpoint mendukung kunci idempotency, client membuat satu kunci untuk satu niat transaksi dan menggunakan kunci yang sama saat mengulang permintaan tersebut. Backend mengenali kunci itu dan menangani pengulangan sesuai kontrak API. Kunci baru diperlukan untuk transaksi baru. Implementasi harus menangani permintaan bersamaan secara atomik, menyimpan hasil atau status yang relevan, dan mendefinisikan masa berlaku kunci.

Ini contoh rancangan, bukan jaminan bahwa gateway otomatis menyediakan perlindungan transaksi. Periksa juga bagaimana sistem menangani kunci sama dengan isi berbeda, proses yang masih berjalan, dan kegagalan setelah perubahan tersimpan tetapi sebelum respons tercatat.

Cara menentukan batas waktu dan retry

Mulai dari perjalanan permintaan secara menyeluruh: client, gateway, layanan tujuan, database, dan dependensi lain. Ukur durasi pada setiap tahap dan tentukan batas waktu total yang dapat diterima pengguna. Anggaran setiap percobaan dan jeda retry harus sesuai dengan batas total tersebut; timeout koneksi, kirim, dan baca bukan otomatis batas waktu total transaksi.

Contoh ilustrasi: jika client hanya menunggu sepuluh detik, rancangan dua percobaan yang masing-masing dapat menghabiskan delapan detik berisiko membuat client menyerah sebelum gateway selesai. Nilai sebenarnya harus ditentukan berdasarkan pengukuran, kebutuhan bisnis, dan uji beban, bukan disalin dari contoh.

Pilih retry secara selektif untuk kegagalan sementara dan operasi yang aman diulang. Batasi jumlah percobaan; gunakan jeda dengan variasi pada komponen yang melakukan retry bila didukung. Pastikan client, gateway, dan backend tidak masing-masing mengulang tanpa koordinasi: satu permintaan dapat berkembang menjadi banyak panggilan ke dependensi.

Untuk operasi yang tidak aman diulang dan belum memiliki idempotency, pertimbangkan menonaktifkan retry otomatis serta menyediakan cara memeriksa status transaksi berdasarkan identitas bisnis. Tetap ada risiko pengguna mengirim ulang secara manual, sehingga desain di backend tetap penting.

Checklist sebelum produksi

• Catat endpoint, pemilik layanan, efek bisnis, dan dependensinya.
• Pastikan implementasi endpoint sesuai sifat idempotent yang dijanjikan; metode HTTP saja tidak membuktikan perilaku aktual.
• Tetapkan batas waktu client dan gateway serta anggaran retry menyeluruh.
• Tinjau konfigurasi Route dan Upstream, termasuk override dan penggunaan bersama.
• Definisikan kesalahan yang layak dicoba ulang, batas percobaan, dan penanganan saat layanan kelebihan beban.
• Uji respons hilang setelah transaksi sukses, timeout sebelum koneksi, permintaan bersamaan, dan backend yang lambat.
• Pantau latensi, timeout, percobaan ulang, error, serta korelasi permintaan dengan identitas transaksi tanpa mencatat data sensitif secara berlebihan.
• Dokumentasikan cara memeriksa dan memulihkan transaksi dengan status tidak pasti.

Pertanyaan yang sering muncul

Apakah timeout berarti backend membatalkan proses?

Tidak selalu. Timeout menunjukkan pihak yang menunggu berhenti menunggu; proses di backend mungkin sudah selesai atau masih berjalan. Periksa status melalui mekanisme yang disediakan layanan.

Apakah semua POST aman di-retry?

Tidak. POST tidak dijamin idempotent. Retry memerlukan kontrak endpoint dan implementasi server yang mendukungnya, misalnya kunci idempotency untuk operasi yang relevan. Menambahkan header saja tidak cukup bila server tidak memprosesnya.

Apakah retry lebih banyak selalu meningkatkan keandalan?

Tidak. Retry yang berlebihan dapat memperparah antrean dan memperpanjang waktu respons. Gunakan batas yang terukur dan uji saat dependensi lambat atau tidak tersedia.

Langkah berikutnya

Mulailah dari satu alur penting, misalnya pembuatan transaksi, lalu petakan batas waktu dan mekanisme pemeriksaan status dari ujung ke ujung. Untuk membahas arsitektur dan integrasi API sesuai kebutuhan sistem Anda, lihat layanan integrasi dan konsultasi teknis StaraSolution.

Referensi

• Apache APISIX — Admin API: timeout dan retry pada Route dan Upstream.
• Apache APISIX — Upstream: konsep Upstream dan prioritas konfigurasi.
• MDN — Idempotent: sifat metode HTTP dan batas implementasinya.
• MDN — Idempotency-Key: tanggung jawab client dan server serta masa berlaku kunci.