Arsitektur Multi-Provider Failover & SSE Streaming untuk Aplikasi LLM Produksi

1. Risiko Single Point of Failure pada Integrasi LLM Langsung

Dalam lingkungan produksi, endpoint LLM upstream dapat mengembalikan HTTP 429 (Too Many Requests), HTTP 502/503 (Bad Gateway / Overloaded), atau mengalami stalled socket di tengah pengiriman token. Jika aplikasi Anda terhubung langsung ke satu kredensial vendor tanpa lapisan gateway, kegagalan tersebut langsung dirasakan oleh pengguna akhir.

2. Algoritma Pemilihan Kandidat & Failover Otomatis

Ketika klien mengirim permintaan dengan nama model bersih (misalnya deepseek-v4.1-flash atau claude-sonnet-4-5), modul katalog TokenFajri menyusun daftar kandidat rute upstream aktif berdasarkan urutan prioritas (displayOrder), status verifikasi kesehatan (isVerified), dan efisiensi biaya.

Apabila kandidat utama merespons dengan status 5xx, 429, atau kegagalan jaringan sebelum aliran byte dimulai, gateway secara otomatis membatalkan pembacaan body kandidat pertama dan mengalihkan permintaan ke kandidat rute berikutnya tanpa memutuskan koneksi klien.

1. Klien -> POST /v1/chat/completions (model: "claude-sonnet-4-5")
2. Gateway memuat kandidat rute aktif yang telah lolos health probe (isVerified = true)
3. Percobaan Rute #1 -> Jika HTTP 429 / 503 / Timeout -> Batalkan socket Rute #1
4. Failover instan ke Rute #2 -> Teruskan respons / SSE stream ke klien
5. Catat UsageLog & selesaikan perhitungan kuota/saldo secara atomik

3. Penanganan Stream SSE & Deteksi Koneksi Menggantung (Idle Guard)

Pada mode streaming (stream: true), koneksi HTTP tetap terbuka selama model menghasilkan token demi token. TokenFajri membungkus ReadableStream dari upstream menggunakan penjaga waktu diam (guardStreamIdle) serta menyuntikkan opsi stream_options: { include_usage: true }.

Dengan demikian, setiap potongan data (chunk) langsung dikirimkan ke klien tanpa buffering (X-Accel-Buffering: no), sementara penghitungan jumlah token prompt dan completion tetap terekam secara presisi pada akhir stream.