relay¶

A production-grade declarative HTTP client for Go.

relay is a zero-boilerplate HTTP client that handles the hard parts - retries, circuit breaking, rate limiting, authentication, observability - so you can focus on your application logic.

Why relay?¶

Feature	relay	net/http	resty	heimdall
Retry with backoff	Yes	No	Yes	Yes
Circuit breaker	Yes	No	No	Yes
Bulkhead isolation	Yes	No	No	No
Request hedging	Yes	No	No	No
Semantic hooks	Yes	No	Partial	No
WebSocket (same client)	Yes	No	No	No
Dynamic TLS cert reload	Yes	No	No	No
Transport adapters	Yes	No	No	No
Extension ecosystem	18 modules	-	few	-

Quick install¶

go get github.com/jhonsferg/relay

30-second example¶

package main

import (
    "context"
    "fmt"
    "github.com/jhonsferg/relay"
)

type User struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}

func main() {
    client := relay.New(
        relay.WithBaseURL("https://api.example.com"),
        relay.WithBearerToken("my-token"),
        relay.WithRetry(&relay.RetryConfig{MaxAttempts: 3}),
    )

    req := client.Get("/users/1")
    resp, err := client.Execute(context.Background(), req)
    if err != nil {
        panic(err)
    }

    user, err := relay.DecodeJSON[User](resp)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Hello, %s!\n", user.Name)
}

Features at a glance¶

Retry & Backoff - Exponential backoff with jitter, retry budgets, per-status configuration
Auth - Bearer, Basic, API Key, Digest, OAuth2, HMAC, AWS SigV4
Circuit Breaker - Sliding-window failure detection with automatic recovery
Rate Limiting - Token bucket with burst support
Hooks - BeforeRetry, BeforeRedirect, OnError semantic hooks
Bulkhead - Limit concurrent requests to protect downstream services
Hedging - Race duplicate requests for tail-latency reduction
WebSocket - First-class WebSocket upgrade using the same client config
TLS - Dynamic certificate reloading without restarts
Transport - Custom transports per URL scheme, HTTP/3 QUIC
Extensions - 18 optional modules: OTel, Prometheus, Sentry, gRPC, GraphQL...
Testing - Built-in mock server and VCR cassette recording