Retry dan Backoff

Retry di heimdall dipecah menjadi dua kontrak terpisah. Retriable menentukan berapa lama menunggu sebelum percobaan berikutnya, dan Backoff menghitung besaran interval itu. Keduanya hanya punya satu method, sehingga strategi penundaan bisa diganti tanpa menyentuh loop retry di klien.

Dua interface dan komposisinya

Retriable mendefinisikan satu method, NextInterval(retry int) time.Duration retry.go:5-8¹. Backoff juga satu method, Next(retry int) time.Duration backoff.go:9-12².

NewRetrier membungkus sebuah Backoff menjadi Retriable. Struct retrier menyimpan field backoff, dan NextInterval meneruskan nilai retry ke r.backoff.Next(retry) retry.go:19-28³ retry.go:35-38⁴.

graph LR
  CB["NewConstantBackoff"] --> BO["Backoff"]
  EB["NewExponentialBackoff"] --> BO
  BO --> NR["NewRetrier"]
  NR --> RT["Retriable"]
  RF["NewRetrierFunc"] --> RT
  NN["NewNoRetrier"] --> RT
  RT --> CL["Client.retrier.NextInterval"]
  style BO fill:#f59e0b,color:#000
  style RT fill:#f59e0b,color:#000
  style CB fill:#8b5cf6,color:#fff
  style EB fill:#8b5cf6,color:#fff
  style NR fill:#8b5cf6,color:#fff
  style RF fill:#8b5cf6,color:#fff
  style NN fill:#8b5cf6,color:#fff
  style CL fill:#2d7d46,color:#fff
  %% fig: Komposisi Backoff dan Retriable
  %% desc: Dua konstruktor backoff menghasilkan Backoff, NewRetrier membungkusnya menjadi Retriable, sedangkan NewRetrierFunc dan NewNoRetrier langsung menghasilkan Retriable.

Tabel berikut merangkum lima konstruktor yang tersedia di paket heimdall.

Perpindahan percobaan di klien HTTP

Loop di Client.Do memanggil c.retrier.NextInterval(i-1) sebelum percobaan ulang, lalu menunggu lewat internal.SleepInterruptible httpclient/client.go:149-155¹⁰. Argumen i-1 berarti percobaan ulang pertama memakai retry = 0. Klien baru memakai NewNoRetrier() sebagai nilai default retry.go:43-50⁹ httpclient/client.go:39¹¹, dan strategi diganti dengan option WithRetrier httpclient/options.go:30-35¹². Urutan request secara utuh dijelaskan di Siklus Request dan Retry.

stateDiagram-v2
  [*] --> Attempt
  Attempt --> Success: "errs = nil"
  Attempt --> Sleep: "error atau StatusCode >= 500"
  Sleep --> Attempt: "SleepInterruptible(NextInterval(i-1))"
  Sleep --> Aborted: "ctx.Done()"
  Attempt --> Exhausted: "i == retryCount"
  Success --> [*]
  Exhausted --> [*]
  Aborted --> [*]
  style Success fill:#2d7d46,color:#fff
  style Sleep fill:#f59e0b,color:#000
  style Aborted fill:#dc2626,color:#fff
  style Exhausted fill:#dc2626,color:#fff
  %% fig: Perpindahan percobaan retry
  %% desc: Percobaan yang gagal masuk ke state Sleep dengan durasi dari NextInterval(i-1); pembatalan context memindahkan loop ke Aborted tanpa menunggu lagi.

SleepInterruptible memilih antara ctx.Done() dan time.After(d), jadi pembatalan context mengembalikan error dan loop retry dihentikan internal/sleep.go:9-16¹³.

Constant backoff

NewConstantBackoff menyimpan backoffInterval dan maximumJitterInterval dalam satuan milidetik, dan menetralkan jitter negatif menjadi 0 backoff.go:19-30⁵. Next mengembalikan interval tetap ditambah jitter acak rand.Int64N(maximumJitterInterval+1) milidetik backoff.go:32-35¹⁴. Nilai retry tidak mempengaruhi hasil.

Angka di atas berasal dari TestConstantBackoffNextTime backoff_test.go:83-92¹⁵. Lewat NewRetrier, NewConstantBackoff(2ms, 1ms) menghasilkan NextInterval(1) minimal 2ms retry_test.go:19-29¹⁶.

Exponential backoff

NewExponentialBackoff menerima initialTimeout, maxTimeout, exponentFactor, dan maximumJitterInterval backoff.go:44-57⁶. Next menormalkan retry < 0 menjadi 0, lalu memakai math.Min(initialTimeout*factor^retry, maxTimeout) dan menambahkan jitter acak backoff.go:59-65¹⁷.

Empat baris pertama diuji di TestExponentialBackoffNextTime backoff_test.go:10-19¹⁸, sedangkan pemotongan pada retry = 4 diuji di TestExponentialBackoffMaxTimeoutCrossed backoff_test.go:32-38¹⁹. Jika maxTimeout dinaikkan menjadi 1600ms, nilai Next(4) tepat 1600ms backoff_test.go:32-38. Nilai retry negatif menghasilkan interval percobaan pertama, yaitu 100ms backoff_test.go:48-54. Lewat NewRetrier dengan initialTimeout 2ms dan maxTimeout 10ms, NextInterval(1) minimal 4ms retry_test.go:10-17.

Jitter menambah rentang acak di atas nilai dasar.

⚠️ maximumJitterInterval negatif dinetralkan menjadi 0 di dalam konstruktor untuk menghindari panic saat membangkitkan jitter acak backoff.go:20-24²⁵. Perilaku ini diuji dengan nilai -1ms yang tetap menghasilkan 100ms, 200ms, 400ms, dan 800ms backoff_test.go:21-30²⁶. Jangan mengandalkan jitter negatif sebagai pembatas interval.

Adapter fungsi dan null object

RetriableFunc adalah tipe fungsi func(retry int) time.Duration dengan method NextInterval yang hanya memanggil fungsi tersebut retry.go:10-17²⁷. NewRetrierFunc mengembalikan f apa adanya sebagai Retriable, sehingga perhitungan interval bisa ditulis langsung tanpa struct backoff retry.go:30-33⁸. Pola ini dipakai pada test retrier linear yang mengembalikan retry milidetik dan 0 untuk retry <= 0 retry_test.go:31-42²⁸.

NewNoRetrier menyediakan null object: NextInterval selalu mengembalikan 0 * time.Millisecond retry.go:43-50⁹, dan test memastikan NextInterval(1) bernilai nol retry_test.go:44-50²⁹. Ini membuat klien tanpa konfigurasi tidak menunggu di antara percobaan.