Option dan Fallback hystrix

hystrix.NewClient menerima opts ...Option, dan Option sendiri hanyalah func(*Client) hystrix/options.go:13-14¹. Setiap option menulis satu field ke struct Client, lalu NewClient memindahkan field-field itu ke hystrix.CommandConfig lewat hystrix.ConfigureCommand hystrix/hystrix_client.go:54-80². Pemisahan ini yang perlu dipegang: option hanya mengisi field heimdall, sedangkan ConfigureCommand yang menentukan perilaku circuit breaker sebenarnya.

Option, field, dan nilai default

Tabel berikut memetakan setiap option ke field Client yang diisinya. Struct Client beserta field-field itu ada di hystrix/hystrix_client.go:21-37³, dan nilai default yang dipasang NewClient tercantum di hystrix/hystrix_client.go:39-49⁴.

Baris-baris tabel itu bertumpu pada definisi option berikut: WithCommandName hystrix/options.go:16-21⁵, WithHystrixTimeout hystrix/options.go:30-35⁶, WithMaxConcurrentRequests hystrix/options.go:37-42, WithRequestVolumeThreshold hystrix/options.go:44-49, WithSleepWindow hystrix/options.go:51-56, dan WithErrorPercentThreshold hystrix/options.go:58-63.

Option retry pada klien yang sama ada di hystrix/options.go:82-94¹¹, sedangkan WithRetryableStatusCodes mengurutkan status code dengan slices.Sort sebelum menyimpannya hystrix/options.go:104-113¹². Dua option yang diarahkan ke httpclient menyusun ulang option dari paket itu, yaitu WithHTTPTimeout hystrix/options.go:23-28¹³ dan WithHTTPClient hystrix/options.go:96-102¹⁴.

Nilai default di tabel di atas diverifikasi langsung oleh TestOptionsHaveDefaults hystrix/options_test.go:35-46¹⁵, sedangkan TestOptionsAreSet memastikan setiap option menimpa field yang benar, termasuk retryableCodes yang menjadi []int{200, 400, 424} hystrix/options_test.go:12-33¹⁶.

Dua timeout yang berbeda

Klien ini memegang dua timeout dengan tugas berbeda. WithHystrixTimeout hanya menyimpan durasi ke field hystrixTimeout hystrix/options.go:30-35⁶, dan nilainya dipakai hystrix untuk mencatat error. WithHTTPTimeout, sebaliknya, meneruskan durasi ke httpclient.WithHTTPTimeout pada klien HTTP di dalamnya hystrix/options.go:23-28¹³, sehingga yang berubah adalah kapan klien HTTP sendiri mengembalikan timeout. README menyebut kedua nilai ini sebaiknya sama kecuali ada kebutuhan khusus README.md:108¹⁷. Opsi httpclient yang lain dibahas di Option pada httpclient.

⚠️ Kedua durasi dikonversi ke bilangan bulat milidetik oleh durationToInt sebelum masuk ke hystrix.CommandConfig hystrix/hystrix_client.go:82-92¹⁸. Artinya nilai di bawah satu milidetik terpotong menjadi 0, dan nilai yang melewati maxInt dipangkas ke maxInt tanpa error. TestOptionsAreSet bahkan memakai WithHystrixTimeout(1100) tanpa satuan, yaitu 1100 nanodetik, sehingga field berisi 1100 tetapi konfigurasi hystrix menjadi 0 milidetik hystrix/options_test.go:12-33¹⁶.

Konfigurasi yang dikirim ke hystrix-go

Setelah semua option dijalankan, NewClient memanggil hystrix.ConfigureCommand dengan nama command sebagai kunci dan lima nilai sebagai isi CommandConfig: Timeout, MaxConcurrentRequests, RequestVolumeThreshold, SleepWindow, dan ErrorPercentThreshold hystrix/hystrix_client.go:71-77¹⁹.

Nama command itu juga muncul di pesan error pembuatan request, misalnya "GET %s - request creation failed: %w" pada Get hystrix/hystrix_client.go:95-105²⁰. Jadi WithCommandName bukan sekadar label: ia menamai konfigurasi circuit breaker sekaligus memberi konteks pada error yang dikembalikan.

Alur fallback

Fallback diteruskan sebagai argumen ketiga hystrix.DoC di dalam hystrixDo hystrix/hystrix_client.go:220-241²¹. Fungsi run yang dibungkus hystrix.DoC mengembalikan error dari hhc.client.Do, atau mengembalikan errRetryableCode ketika status code ada di retryableCodes maupun bernilai 500 ke atas. errRetryableCode didefinisikan sebagai errors.New("server returned status code to retry") hystrix/hystrix_client.go:52²².

graph LR
  RUN["run func: hhc.client.Do"] -->|"doErr tidak nil"| FB
  RUN -->|"status di retryableCodes atau 5xx"| RETRY["errRetryableCode"]
  RETRY --> FB["hystrix.DoC dengan fallback"]
  FB --> CALL["hhc.fallbackFunc(ctx, err)"]
  CALL -->|"return nil"| OK["hystrixDo: response, nil"]
  CALL -->|"return err"| FAIL["hystrixDo: nil, error"]
  OK --> DONE["Do: err == nil, loop retry berhenti"]
  style OK fill:#2d7d46,color:#fff
  style DONE fill:#2d7d46,color:#fff
  style RETRY fill:#f59e0b,color:#000
  style CALL fill:#8b5cf6,color:#fff
  style FAIL fill:#dc2626,color:#fff
%% fig: Alur fallback di hystrixDo
%% desc: Fungsi run mengembalikan doErr atau errRetryableCode, lalu hystrix.DoC memanggil fallbackFunc; nilai balik fallback menentukan apakah Do mengembalikan error atau melanjutkan tanpa error.

Perilaku cabang-cabang itu tampak di test paket hystrix.

Fallback tanpa context dan dengan context

Paket ini mendefinisikan dua tipe fungsi: fallbackFunc func(error) error dan fallbackCtxFunc func(context.Context, error) error hystrix/hystrix_client.go:18-19²⁸. WithFallbackFunc menerima bentuk pertama, tetapi tidak menyimpannya langsung: ia membungkusnya menjadi WithFallbackCtxFunc dan mengabaikan context.Context yang diberikan hystrix/options.go:65-80²⁹. WithFallbackCtxFunc adalah yang benar-benar menulis ke field fallbackFunc hystrix/options.go:76-80³⁰.

Bentuk kedua ini yang akhirnya diserahkan ke hystrix.DoC, karena field fallbackFunc pada struct Client bertipe func(ctx context.Context, err error) error hystrix/hystrix_client.go:21-37³.

WithFallbackFunc(nil) tidak memasang fallback apa pun: option itu mengembalikan fungsi kosong func(_ *Client) {} sehingga field fallbackFunc tetap nil hystrix/options.go:65-73³¹. Karena itu, klien dengan WithFallbackFunc(nil) tetap mengembalikan error HTTP aslinya hystrix/hystrix_client_test.go:558-576²⁵.

Setelah fallback mengembalikan nil

Fallback yang mengembalikan nil membuat hystrix.DoC selesai tanpa error, sehingga hystrixDo mengembalikan response beserta nil sebagai error hystrix/hystrix_client.go:220-241²¹. Di lapisan atas, Do melihat err == nil lalu mencatat Success() pada error budget dan keluar dari loop retry hystrix/hystrix_client.go:198-207³². Konsekuensinya, request dianggap berhasil walaupun tidak ada response HTTP yang terisi.

Jalur khusus berlaku untuk errRetryableCode: Do mengembalikan response bersama nil ketika errors.Is(err, errRetryableCode) benar, dan hanya mengembalikan error lain apa adanya hystrix/hystrix_client.go:209-215³³.

⚠️ Fallback yang selalu mengembalikan nil akan menutupi kegagalan sepenuhnya: tidak ada error yang naik ke pemanggil, sehingga retry tidak pernah berjalan. Pastikan fallback mengembalikan error ketika kegagalan perlu terlihat, seperti pola di TestHystrixHTTPClientReturnsFallbackFailureWithAFallBackFunctionWhichReturnAnError hystrix/hystrix_client_test.go:535-556²⁴.