Flag for specifying a jitter duration (#18)

Author: joshdk

README.md

@@ -50,21 +50,23 @@ This tool is an attempt to solve that broader problem. ⏰
 $ retry -help
 Usage: retry [flags] command|url
   -attempts int
-    	maximum number of attempts (default 3)
+        maximum number of attempts (default 3)
   -backoff
-    	use exponential backoff when sleeping
+        use exponential backoff when sleeping
   -consecutive int
-    	required number of back to back successes
+        required number of back to back successes
+  -jitter duration
+        time range randomly added to sleep
   -max-time duration
-    	maximum total time (default 1m0s)
+        maximum total time (default 1m0s)
   -quiet
-    	silence all output
+        silence all output
   -sleep duration
-    	time to sleep between attempts (default 5s)
+        time to sleep between attempts (default 5s)
   -task-time duration
-    	maximum time for a single attempt
+        maximum time for a single attempt
   -version
-    	print the version "1.0.0" and exit
+        print the version "1.0.0" and exit
 ```
 
 ### Running a command
@@ -123,6 +125,16 @@ The `-backoff` flag is used with `-sleep`, and will double the time delay betwee
 > $ retry -sleep=15s -backoff wget https://example.com
 > ```
 
+### Random jitter
+
+The `-jitter` flag adds a random time range to the sleep duration. Jitter added on top of exponential backoff.
+
+> Run `cat kubeconfig.yml`, sleep for 15 seconds minimum, plus a random 0-10 seconds between each run.
+>
+> ```bash
+> $ retry -sleep=15s -jitter=10s cat kubeconfig.yml
+> ```
+
 ### Consecutive successes
 
 The `-consecutive` flag requires a number of successful command runs to occur in a row in order to be considered successful. Useful for health checking a service that is inconsistent until if if fully started.

main.go

@@ -31,6 +31,7 @@ func main() {
 	flag.IntVar(&flags.Attempts, "attempts", 3, "maximum number of attempts")
 	flag.BoolVar(&flags.Backoff, "backoff", false, "use exponential backoff when sleeping")
 	flag.IntVar(&flags.Consecutive, "consecutive", 0, "required number of back to back successes")
+	flag.DurationVar(&flags.Jitter, "jitter", 0, "time range randomly added to sleep")
 	flag.DurationVar(&flags.TotalTime, "max-time", time.Minute, "maximum total time")
 	flag.BoolVar(&flags.quiet, "quiet", false, "silence all output")
 	flag.DurationVar(&flags.Sleep, "sleep", 5*time.Second, "time to sleep between attempts")

retry/retry.go

@@ -7,6 +7,7 @@ package retry
 import (
 	"context"
 	"errors"
+	"math/rand"
 	"time"
 )
 
@@ -35,6 +36,10 @@ type Spec struct {
 	// row in order for the task to be considered successful overall.
 	Consecutive int
 
+	// Jitter is the duration range to randomly add to the Sleep time.
+	//  Sleep + [0, Jitter)
+	Jitter time.Duration
+
 	// Sleep is the duration to pause between individual task invocations.
 	Sleep time.Duration
 
@@ -89,7 +94,7 @@ func Retry(spec Spec, task Task) error {
 			}
 
 			// Sleep for the specified duration.
-			snooze := spec.Sleep * time.Duration(multiplier)
+			snooze := spec.Sleep*time.Duration(multiplier) + jitter(spec.Jitter)
 			if err := contextSleep(ctxMaxTime, snooze); err != nil {
 				return ErrExceededTime
 			}
@@ -117,6 +122,19 @@ func maybeTimed(parent context.Context, timeout time.Duration) (context.Context,
 	return context.WithTimeout(parent, timeout)
 }
 
+// jitter returns a random duration in the range of:
+//   [0, variance)
+func jitter(variance time.Duration) time.Duration {
+	if variance <= 0 {
+		return 0
+	}
+
+	// rng is a seeded source capable of generating random values.
+	rng := rand.New(rand.NewSource(time.Now().UnixNano()))
+
+	return time.Duration(rng.Int63n(int64(variance)))
+}
+
 // contextSleep is a context-aware sleep. It will sleep for the given timeout,
 // but will return early if the given context is cancelled. The return value
 // will be nil after a full sleep, and non-nil if the given context was