Even better examples and README (#22)

.github/workflows/build.yml

@@ -27,7 +27,7 @@ jobs:
       uses: actions/checkout@v2
 
     - name: Test
-      run: go test -v -race -coverprofile=coverage.txt ./...
+      run: go test -v -race -shuffle=on -coverprofile=coverage.txt ./...
 
     - name: Upload Coverage
       uses: codecov/codecov-action@v1

README.md

@@ -4,6 +4,7 @@
 [![pkg-img]][pkg-url]
 [![reportcard-img]][reportcard-url]
 [![coverage-img]][coverage-url]
+[![version-img]][version-url]
 
 Hedged HTTP client which helps to reduce tail latency at scale.
 
@@ -21,6 +22,7 @@ Thanks to [Bohdan Storozhuk](https://github.com/storozhukbm) for the review and
 * Easy to integrate.
 * Optimized for speed.
 * Clean and tested code.
+* Supports `http.Client` and `http.RoundTripper`.
 * Dependency-free.
 
 ## Install
@@ -42,19 +44,11 @@ if err != nil {
 
 timeout := 10 * time.Millisecond
 upto := 7
-transport := http.DefaultTransport
-hedged, stats := hedgedhttp.NewRoundTripperAndStats(timeout, upto, transport)
-
-// print stats periodically
-go func() {
-	for {
-		time.Sleep(time.Second)
-		fmt.Printf("stats: %+v\n", stats)
-	}
-}()
+client := &http.Client{Timeout: time.Second}
+hedged := hedgedhttp.NewClient(timeout, upto, client)
 
 // will take `upto` requests, with a `timeout` delay between them
-resp, err := hedged.RoundTrip(req)
+resp, err := hedged.Do(req)
 if err != nil {
 	panic(err)
 }
@@ -63,7 +57,7 @@ defer resp.Body.Close()
 // and do something with resp
 ```
 
-Also see examples: [examples_test.go](https://github.com/cristalhq/hedgedhttp/blob/main/example_test.go).
+Also see examples: [examples_test.go](https://github.com/cristalhq/hedgedhttp/blob/main/examples_test.go).
 
 ## Documentation
 
@@ -81,3 +75,5 @@ See [these docs][pkg-url].
 [reportcard-url]: https://goreportcard.com/report/cristalhq/hedgedhttp
 [coverage-img]: https://codecov.io/gh/cristalhq/hedgedhttp/branch/main/graph/badge.svg
 [coverage-url]: https://codecov.io/gh/cristalhq/hedgedhttp
+[version-img]: https://img.shields.io/github/v/release/cristalhq/hedgedhttp
+[version-url]: https://github.com/cristalhq/hedgedhttp/releases

examples_test.go

@@ -11,7 +11,29 @@ import (
 	"github.com/cristalhq/hedgedhttp"
 )
 
-func ExampleHedged() {
+func ExampleHedgedClient() {
+	ctx := context.Background()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://google.com", http.NoBody)
+	if err != nil {
+		panic(err)
+	}
+
+	timeout := 10 * time.Millisecond
+	upto := 7
+	client := &http.Client{Timeout: time.Second}
+	hedged := hedgedhttp.NewClient(timeout, upto, client)
+
+	// will take `upto` requests, with a `timeout` delay between them
+	resp, err := hedged.Do(req)
+	if err != nil {
+		panic(err)
+	}
+	defer resp.Body.Close()
+
+	// and do something with resp
+}
+
+func ExampleHedgedRoundTripper() {
 	ctx := context.Background()
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://google.com", http.NoBody)
 	if err != nil {
@@ -46,10 +68,7 @@ func ExampleInstrumented() {
 		Transport: http.DefaultTransport,
 	}
 
-	timeout := 10 * time.Millisecond
-	upto := 7
-
-	_ = hedgedhttp.NewRoundTripper(timeout, upto, transport)
+	_ = hedgedhttp.NewRoundTripper(time.Millisecond, 3, transport)
 }
 
 type InstrumentedTransport struct {
@@ -75,10 +94,7 @@ func ExampleRatelimit() {
 		Limiter:   &RandomRateLimiter{},
 	}
 
-	timeout := 10 * time.Millisecond
-	upto := 7
-
-	_ = hedgedhttp.NewRoundTripper(timeout, upto, transport)
+	_ = hedgedhttp.NewRoundTripper(time.Millisecond, 3, transport)
 }
 
 // by example https://pkg.go.dev/golang.org/x/time/rate
@@ -110,3 +126,24 @@ func (r *RandomRateLimiter) Wait(ctx context.Context) error {
 	}
 	return nil
 }
+
+func ExampleMultiTransport() {
+	transport := &MultiTransport{
+		First:  &http.Transport{MaxIdleConns: 10}, // just an example
+		Hedged: &http.Transport{MaxIdleConns: 30}, // just an example
+	}
+
+	_ = hedgedhttp.NewRoundTripper(time.Millisecond, 3, transport)
+}
+
+type MultiTransport struct {
+	First  http.RoundTripper // Used to make 1st requests.
+	Hedged http.RoundTripper // Used to make hedged requests.
+}
+
+func (t *MultiTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	if hedgedhttp.IsHedgedRequest(req) {
+		return t.Hedged.RoundTrip(req)
+	}
+	return t.First.RoundTrip(req)
+}