client

func Backoff ¶

func Backoff(initial time.Duration, factor float64, maximum time.Duration) func(attempt int) time.Duration

Backoff returns a delay function for Builder.Backoff: exponential with full jitter. The delay before the first retry (attempt 2) is drawn uniformly from [0, initial), and the bound is multiplied by factor for each later retry and capped at maximum. The argument order matches queue.JobBuilder.Backoff.

Backoff never panics or fails. A negative initial or maximum counts as zero, a zero maximum omits the configured cap, and a factor below one (or NaN) counts as one. With a zero initial every delay is zero, even when exponential growth would overflow. Attempts below two use the first retry's bound. Infinite growth saturates at maximum, with an internal bound of 1<<62 nanoseconds for safe jitter sampling even when maximum is omitted.

Example:

httpClient := &http.Client{Transport: client.Transport(nil,
	func(transport *client.Builder) {
		transport.Backoff(client.Backoff(50*time.Millisecond, 3, time.Second))
	})}

A zero initial delay remains zero even with unbounded growth:

backoff := client.Backoff(0, math.Inf(1), 0)
delay := backoff(2048) // zero, without overflow or panic
_ = delay

package main

import (
	"fmt"
	"math"

	"arkoren.dev/core/http/client"
)

func main() {
	backoff := client.Backoff(0, math.Inf(1), 0)
	fmt.Println(backoff(2048))
}

Output:
0s

func NewTransport ¶

func NewTransport(config *tls.Config, configure ...BuilderFunc) (http.RoundTripper, error)

NewTransport clones the current http.DefaultTransport and wraps it with Transport's retry and telemetry policy. The default must be a nonnil *http.Transport; any other value returns an error before callbacks run. Native proxy, connection pooling, and HTTP/2 settings are preserved.

A nil config preserves the cloned default's TLS settings. A nonnil config replaces them with config.Clone(): the top-level configuration is independent, but native nested values (pools, certificates, callbacks, and their captures) remain shared. Configure those values before construction and do not mutate them while in use. Neither the supplied config nor the default is modified.

Construction opens no connections. Callbacks run once, synchronously in order, through Transport; nil callbacks and application panics propagate. Use Transport directly when you already have a custom round tripper. Retire the owned connection pool with http.Client.CloseIdleConnections; active requests are not interrupted.

Example:

roundTripper, err := client.NewTransport(&tls.Config{
	MinVersion: tls.VersionTLS12,
}, func(transport *client.Builder) {
	transport.Attempts(5)
})
if err != nil {
	return err
}
httpClient := &http.Client{Transport: roundTripper}
_ = httpClient

package main

import (
	"crypto/tls"
	"fmt"
	"net/http"
	"time"

	"arkoren.dev/core/http/client"
)

func main() {
	transport, err := client.NewTransport(&tls.Config{MinVersion: tls.VersionTLS12},
		func(transport *client.Builder) {
			transport.Attempts(5)
		},
	)

	if err != nil {
		fmt.Println(err)

		return
	}

	outgoing := &http.Client{Transport: transport, Timeout: 10 * time.Second}
	outgoing.CloseIdleConnections()
	fmt.Println("configured")
}

Output:
configured

func Transport ¶

func Transport(base http.RoundTripper, configure ...BuilderFunc) http.RoundTripper

Transport returns a round tripper that retries failed requests through base. A nil base uses http.DefaultTransport.

A request is retried only when its method is idempotent (GET, HEAD, OPTIONS, TRACE, PUT, DELETE) or it has an Idempotency-Key header, and when it has no body or http.Request.GetBody can rewind it. These rules always apply; Builder.RetryIf only decides on the outcome of an attempt. Each attempt uses a clone of the request, so the caller's request is never modified, and the previous response body is drained (up to 4 KiB) and closed before the next attempt.

Between attempts it waits Builder.Backoff, or the Retry-After header of a 429 or 503 response. If that header asks for more than 10 seconds (a fixed cap, independent of Builder.Backoff) or for more time than the context deadline allows, retrying stops and the response is returned as is. A wait ends early when the request context is done, and Transport then returns the context's error. When attempts run out, the last response or error is returned unchanged. With Builder.Events, returning a transport error, or a response Builder.RetryIf still wanted retried, publishes RequestFailed; a done request context publishes nothing.

The transport wraps the telemetry transport, so every attempt is its own client span, and every resend has the http.request.resend_count attribute. Trace context is injected only into internal destinations unless Builder.Propagate says otherwise.

A 101 Switching Protocols response retains io.Writer when the native body provides it, so callers can assert io.ReadWriteCloser for an upgraded stream. Read-only bodies do not gain write capability. Callers own the returned body: reads and writes preserve native results without closing it or canceling its attempt context. Close closes the native body once, then releases the attempt context, even if closing fails; repeated or concurrent closes return the same error. An upgrade retains the attempt context and its deadline until Close; the native body determines how cancellation affects its I/O.

Example:

httpClient := &http.Client{Transport: client.Transport(nil, func(transport *client.Builder) {
	transport.Attempts(5)
})}

package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"
	"sync/atomic"
	"time"

	"arkoren.dev/core/http/client"
)

func main() {
	var calls atomic.Int32
	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, _ *http.Request) {
		if calls.Add(1) == 1 {
			writer.WriteHeader(http.StatusServiceUnavailable)

			return
		}

		writer.WriteHeader(http.StatusOK)
	}))
	defer server.Close()
	sender := &http.Client{
		Transport: client.Transport(nil,
			func(transport *client.Builder) {
				transport.Attempts(5)
			},
			func(transport *client.Builder) {
				transport.Backoff(client.Backoff(10*time.Millisecond, 2, time.Second))
			},
		),
	}

	response, err := sender.Get(server.URL)

	if err != nil {
		fmt.Println(err)

		return
	}

	defer func() {
		// Closing this empty test response is best-effort cleanup.
		_ = response.Body.Close()
	}()
	fmt.Println(response.StatusCode, calls.Load())
}

Output:
200 2

package main

import (
	"errors"
	"fmt"
	"io"
	"net/http"
	"testing/fstest"

	"arkoren.dev/core/http/client"
)

func main() {
	files := fstest.MapFS{"health": {Data: []byte("ready")}}
	base := &http.Transport{}
	base.RegisterProtocol("file", http.NewFileTransportFS(files))

	transport := client.Transport(base)

	request, err := http.NewRequest(http.MethodGet, "file:///health", nil)

	if err != nil {
		fmt.Println(err)

		return
	}

	response, err := transport.RoundTrip(request)

	if err != nil {
		fmt.Println(err)

		return
	}

	data, err := io.ReadAll(response.Body)

	err = errors.Join(err, response.Body.Close())

	if err != nil {
		fmt.Println(err)

		return
	}

	fmt.Println(response.StatusCode, string(data))
}

Output:
200 ready