clientx

package
v0.16.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 9, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package clientx provides shared client-side reliability helpers.

Index

Constants

This section is empty.

Variables

View Source
var ErrCircuitOpen = errors.New("circuit breaker open")
View Source
var ErrNilOperation = errors.New("clientx: operation is nil")
View Source
var ErrRequestBodyTooLarge = errors.New("clientx: request body exceeds configured limit")
View Source
var ErrResponseBodyTooLarge = errors.New("clientx: response body exceeds configured limit")

Functions

func CodeOf

func CodeOf(err error) int

CodeOf returns a normalized code from err when possible.

func Do

func Do(ctx context.Context, cfg RetryConfig, fn func(context.Context) error) error

Do executes fn with retry. MaxAttempts includes the first attempt.

func IsRetryable

func IsRetryable(err error) bool

IsRetryable reports whether err is generally safe to retry.

func MapGRPCError

func MapGRPCError(err error) error

MapGRPCError maps gRPC errors to standard response codes.

func NewError

func NewError(code int, message string, err error) error

NewError creates a normalized client error.

Types

type Breaker

type Breaker struct {
	// contains filtered or unexported fields
}

Breaker is a small client-side circuit breaker.

func NewBreaker

func NewBreaker(cfg BreakerConfig) *Breaker

NewBreaker creates a circuit breaker.

func (*Breaker) Do

func (b *Breaker) Do(ctx context.Context, fn func(context.Context) error) error

Do executes fn when the circuit allows it.

func (*Breaker) State

func (b *Breaker) State() BreakerState

State returns the current breaker state.

type BreakerConfig

type BreakerConfig struct {
	Name             string
	FailureThreshold int
	Cooldown         time.Duration
	Now              func() time.Time
	ShouldCount      func(error) bool
}

BreakerConfig configures a circuit breaker.

type BreakerState

type BreakerState int
const (
	BreakerClosed BreakerState = iota
	BreakerOpen
	BreakerHalfOpen
)

type ClientError

type ClientError struct {
	Code    int
	Message string
	Err     error
}

ClientError is a normalized outbound service call error.

func (*ClientError) Error

func (e *ClientError) Error() string

func (*ClientError) Unwrap

func (e *ClientError) Unwrap() error

type HTTPClient added in v0.13.0

type HTTPClient struct {
	// contains filtered or unexported fields
}

HTTPClient applies timeout, retry, circuit breaking and trace propagation consistently to outbound HTTP calls.

func NewHTTPClient added in v0.13.0

func NewHTTPClient(cfg HTTPClientConfig) *HTTPClient

NewHTTPClient creates a governed HTTP client. The default retry policy only retries idempotent methods and transient transport/status failures.

func (*HTTPClient) Do added in v0.13.0

func (c *HTTPClient) Do(ctx context.Context, req *http.Request) (*http.Response, error)

Do executes req and returns a successful response. The caller owns and must close the response body. Non-2xx responses return HTTPStatusError.

type HTTPClientConfig added in v0.13.0

type HTTPClientConfig struct {
	Client             *http.Client
	Timeout            time.Duration
	Retry              RetryConfig
	Breaker            *Breaker
	Telemetry          *telemetry.Provider
	ServiceName        string
	RetryNonIdempotent bool
	MaxBodyBytes       int64
	// MaxResponseBodyBytes bounds successful response bodies returned to the
	// caller; zero uses a 10 MiB default.
	MaxResponseBodyBytes int64
}

HTTPClientConfig configures the shared outbound HTTP client.

type HTTPStatusError added in v0.13.0

type HTTPStatusError struct {
	StatusCode int
	Status     string
}

HTTPStatusError reports a non-success HTTP response after request execution.

func (*HTTPStatusError) Error added in v0.13.0

func (e *HTTPStatusError) Error() string

type RetryConfig

type RetryConfig struct {
	MaxAttempts int
	// Budget bounds the entire retry operation, including backoff sleeps.
	// Zero uses the caller's context without an additional deadline.
	Budget         time.Duration
	InitialBackoff time.Duration
	MaxBackoff     time.Duration
	Multiplier     float64
	Retryable      func(error) bool
	Sleep          func(context.Context, time.Duration) error
	JitterFraction float64
	DisableJitter  bool
}

RetryConfig configures retry behavior for outbound service calls.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL