httpclient

Overview ¶

Package httpclient provides an HTTP client that transparently adds distributed tracing and structured logging to every outgoing request.

Tracing and logging are implemented as a custom http.RoundTripper so they apply to all requests regardless of which helper method is used.

• Tracing: creates a client span named "METHOD host", records HTTP method, URL, host, and response status as span attributes, and injects outgoing W3C traceparent / tracestate headers so downstream services can parent their spans correctly.
• Logging: emits a structured log line after each round trip with method, URL, status, elapsed duration, and attempt number (when retrying). Uses ErrorContext for network errors and InfoContext for completed requests.

Both the tracer and logger are optional; omitting either disables that instrumentation layer.

Dependency injection ¶

The package defines a Doer interface that Client implements. Code that makes HTTP calls should accept a Doer rather than a concrete *Client so that callers can substitute test doubles:

type Service struct {
	http httpclient.Doer
}

func NewService(http httpclient.Doer) *Service {
	return &Service{http: http}
}

Basic usage ¶

client := httpclient.NewWithConfig(&httpclient.Config{
	Logger:  a.Logger(),
	Tracer:  a.Tracer(),
	Timeout: 10 * time.Second,
})

resp, err := client.Get(ctx, "https://api.example.com/users")
if err != nil { ... }
defer resp.Body.Close()

Retry with network error recovery ¶

resp, err := client.DoWithRetry(req, &httpclient.RetryConfig{
	MaxAttempts:  3,
	RetryOnError: true,              // retry DNS/connection failures
	BaseDelay:    2 * time.Second,   // fallback when no Retry-After
})

Composing with a custom transport ¶

Pass Transport to layer the instrumented transport on top of your own:

client := httpclient.NewWithConfig(&httpclient.Config{
	Tracer:    a.Tracer(),
	Logger:    a.Logger(),
	Transport: &http.Transport{TLSClientConfig: tlsCfg},
})

Testing ¶

Use net/http/httptest.NewServer to capture outgoing requests without real network calls:

ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusOK)
}))
defer ts.Close()

resp, err := client.Get(ctx, ts.URL)

Alternatively, implement the Doer interface directly to build a test double without any network:

type mockDoer struct {
	resp *http.Response
	err  error
}
func (m *mockDoer) Do(req *http.Request) (*http.Response, error) {
	return m.resp, m.err
}

package main

import (
	"context"
	"time"

	"gitlab.com/gitlab-org/labkit/v2/httpclient"
)

func main() {
	client := httpclient.NewWithConfig(&httpclient.Config{
		// Logger: a.Logger(),
		// Tracer: a.Tracer(),
		Timeout: 10 * time.Second,
	})

	ctx := context.Background()
	resp, err := client.Get(ctx, "https://example.com/api/projects")
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	_ = resp
}

Output: