wrap

README

call

Resilience decorators for communicating with runtime dependencies. Named after effectful call decorators — communication over unreliable channels. "Breaker, breaker."

All decorators wrap func(context.Context, T) (R, error) and return the same signature, so they compose by stacking. Use Func.With to build a stack in one expression:

safeFetch := call.From(fetchUser).With(
    call.CircuitBreaker(breaker),
    call.Retrier(3, backoff, isTransient),
    call.ErrMapper(classifyError),
)

Or apply one at a time with the direct wrappers:

classified := call.MapErr(fetchUser, classifyError)
retried := call.Retry(3, backoff, isTransient, classified)
safeFetch := call.WithBreaker(breaker, retried)

What It Looks Like

// Retry with exponential backoff, only for transient errors
backoff := call.ExponentialBackoff(100 * time.Millisecond)
fetcher := call.Retry(3, backoff, isTransient, fetchData)

// Circuit breaker — trips after 5 consecutive failures, resets after 30s
breaker := call.NewBreaker(call.BreakerConfig{
    ResetTimeout: 30 * time.Second,
    ReadyToTrip:  call.ConsecutiveFailures(5),
})
safeFetch := call.WithBreaker(breaker, fetchFromAPI)
resp, err := safeFetch(ctx, url)  // returns call.ErrOpen when tripped

// Bound concurrency — at most 5 in-flight API calls
callAPI := call.Throttle(5, fetchFromAPI)

// Bound by total cost — large items consume more budget
fetchData := call.ThrottleWeighted(100, estimateSize, fetchFromAPI)

// Cancel remaining work on first error
failFast := call.OnErr(fetchURL, func(_ error) { cancel() })

// Transform errors without changing the function signature
annotated := call.MapErr(fetchUser, classifyError)

// Debounce rapid calls, execute once after quiet period
d := call.NewDebouncer(500*time.Millisecond, saveConfig)
defer d.Close()
d.Call(cfg)

Operations

Circuit Breaking

• NewBreaker(cfg BreakerConfig) *Breaker — 3-state: closed → open → half-open → closed
• WithBreaker[T, R](b *Breaker, fn) fn — wrap fn with breaker protection
• ConsecutiveFailures(n int) func(Snapshot) bool — ReadyToTrip predicate
• ErrOpen — sentinel error when breaker rejects

Retry

• Retry[T, R](maxAttempts, backoff, shouldRetry, fn) fn — retry on error with pluggable backoff
• ConstantBackoff(delay) Backoff — fixed delay
• ExponentialBackoff(initial) Backoff — full jitter: random in [0, initial * 2^n)

Concurrency Control

• Throttle[T, R](n, fn) fn — bound by call count
• ThrottleWeighted[T, R](capacity, cost, fn) fn — bound by total cost

Side-Effect Wrappers

• OnErr[T, R](fn, onErr) fn — call handler on error
• MapErr[T, R](fn, mapper) fn — transform errors

Debounce

• NewDebouncer[T](wait, fn, opts...) *Debouncer[T] — trailing-edge coalescer
• MaxWait(d) DebounceOption — cap maximum deferral

All context-aware wrappers return ctx.Err() on cancellation. WithBreaker does not count context.Canceled as a failure. All functions panic on nil inputs.

See pkg.go.dev for complete API documentation and the orders example for a full integration demo.

Documentation

Overview

Package wrap provides chainable decorators for context-aware effectful functions.

Start with Func to wrap a plain function, then chain With* methods:

safe := wrap.Func(fetchOrder).
    WithRetry(3, wrap.ExpBackoff(time.Second), nil).
    WithBreaker(breaker).
    WithThrottle(10)

Each method returns Fn, preserving the func(context.Context, T) (R, error) signature so decorators compose freely. For custom decorators, use Fn.With with Decorator values.

For higher-order functions over plain signatures — func(A) B composition, partial application, debouncing — see the [hof] package.

Index

• Variables
• func ConsecutiveFailures(n int) func(Snapshot) bool
• type Backoff
  • func ExpBackoff(initial time.Duration) Backoff
• type Breaker
  • func NewBreaker(cfg BreakerConfig) *Breaker
  • func (b *Breaker) Snapshot() Snapshot
• type BreakerConfig
• type BreakerState
  • func (s BreakerState) String() string
• type Decorator
• type Features
• type Fn
  • func Func[T, R any](fn func(context.Context, T) (R, error)) Fn[T, R]
  • func (f Fn[T, R]) With(feat Features) Fn[T, R]
  • func (f Fn[T, R]) WithBreaker(b *Breaker) Fn[T, R]
  • func (f Fn[T, R]) WithMapError(mapper func(error) error) Fn[T, R]
  • func (f Fn[T, R]) WithOnError(handler func(error)) Fn[T, R]
  • func (f Fn[T, R]) WithRetry(maxAttempts int, backoff Backoff, shouldRetry func(error) bool) Fn[T, R]
  • func (f Fn[T, R]) WithThrottle(n int) Fn[T, R]
  • func (f Fn[T, R]) WithThrottleWeighted(capacity int, cost func(T) int) Fn[T, R]
• type RetryConfig
  • func Retry(max int, backoff Backoff, shouldRetry func(error) bool) *RetryConfig
• type Snapshot
• type ThrottleConfig
  • func Throttle(n int) *ThrottleConfig
• type Transition

Examples

• Fn (Chain)
• Fn.With
• Fn.WithBreaker
• Fn.WithMapError
• Fn.WithOnError
• Fn.WithRetry
• Fn.WithThrottle

Variables

var ErrCircuitOpen = errors.New("call: circuit breaker is open")

ErrCircuitOpen is returned when the circuit breaker is rejecting requests. This occurs when the breaker is open, or when half-open with a probe already in flight.

Functions

func ConsecutiveFailures

func ConsecutiveFailures(n int) func(Snapshot) bool

ConsecutiveFailures returns a ReadyToTrip predicate that trips after n consecutive failures. Panics if n < 1.

Types

type Backoff

type Backoff func(n int) time.Duration

Backoff computes the delay before retry number n (0-indexed). Called between attempts: backoff(0) is the delay before the first retry.

func ExpBackoff

func ExpBackoff(initial time.Duration) Backoff

ExpBackoff returns a randomized exponential Backoff: uniform random in [0, initial * 2^n). Spreads retries across the interval to minimize collisions under contention. Panics if initial <= 0.

type Breaker

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

Breaker is a circuit breaker that tracks failures and short-circuits requests when a dependency is unhealthy. Use NewBreaker to create and WithBreaker to wrap functions for composition with Retry, Throttle, and other hof wrappers.

The breaker uses a standard three-state model:

• Closed: requests pass through, failures are counted
• Open: requests fail immediately with ErrCircuitOpen
• HalfOpen: one probe request is admitted; success closes, failure reopens, uncounted error (context.Canceled or ShouldCount→false) releases the probe slot without changing state

State transitions are lazy (checked on admission, not timer-driven). One probe request is admitted in half-open; all others are rejected.

Each state transition increments an internal generation counter. Calls that complete after the breaker has moved to a new generation are silently ignored, preventing stale in-flight results from corrupting the current epoch's metrics.

A Breaker must represent a single dependency or failure domain. Sharing a breaker across unrelated dependencies causes pathological coupling: one dependency's failures can trip the breaker for all, and one dependency's successful probe can close it while others remain unhealthy.

func NewBreaker

func NewBreaker(cfg BreakerConfig) *Breaker

NewBreaker creates a circuit breaker with the given configuration. Panics if ResetTimeout <= 0.

func (*Breaker) Snapshot

func (b *Breaker) Snapshot() Snapshot

Snapshot returns a point-in-time view of the breaker's state and metrics. State is the committed state; lazy transitions (open to half-open after resetTimeout) are not reflected until the next admission check.

type BreakerConfig

type BreakerConfig struct {
	// ResetTimeout is how long the breaker stays open before allowing a probe request.
	// Must be > 0.
	ResetTimeout time.Duration

	// ReadyToTrip decides whether the breaker should open based on current metrics.
	// Called outside the internal lock after each counted failure while closed.
	// The snapshot reflects the state including the current failure.
	//
	// Under concurrency, the breaker validates that no metric mutations occurred
	// between ReadyToTrip evaluation and the trip commit. If metrics changed
	// (concurrent success or failure), the trip is aborted; the next failure
	// will re-evaluate with a fresh snapshot. This means predicates should be
	// monotone with respect to failure accumulation (e.g., >= threshold) for
	// reliable tripping under contention. Non-monotone predicates (e.g., == N)
	// may miss a trip if a concurrent mutation changes the count between
	// evaluation and commit.
	//
	// Must be side-effect-free. May be called concurrently from multiple goroutines.
	// Nil defaults to ConsecutiveFailures(5).
	ReadyToTrip func(Snapshot) bool

	// ShouldCount decides whether an error counts as a failure for trip purposes.
	// Called outside the internal lock.
	// Nil means all errors count. context.Canceled never counts regardless of this setting.
	ShouldCount func(error) bool

	// OnStateChange is called after each state transition on the normal (non-panic) path,
	// outside the internal lock. Transitions caused by panic recovery (e.g., a half-open
	// probe fn panic reopening the breaker) do not trigger the callback to avoid masking
	// the original panic.
	// Under concurrency, callback delivery may lag or overlap and should not
	// be treated as a total order. Panics in this callback propagate to the caller.
	// Nil means no notification.
	OnStateChange func(Transition)

	// Clock returns the current time. Nil defaults to time.Now.
	// Must be non-blocking, must not panic, and must not call Breaker methods
	// (deadlock risk). Useful for deterministic testing.
	Clock func() time.Time
}

BreakerConfig configures a circuit breaker.

type BreakerState

type BreakerState int

BreakerState represents the current state of a circuit breaker.

const (
	StateClosed BreakerState = iota
	StateOpen
	StateHalfOpen
)

func (BreakerState) String

func (s BreakerState) String() string

type Decorator

type Decorator[T, R any] func(Fn[T, R]) Fn[T, R]

Decorator wraps an Fn, returning an Fn with the same signature. For custom decorators not covered by Features, apply manually:

decorated := wrap.Fn[T, R](myDecorator(fn))

type Features

type Features struct {
	Breaker  *Breaker
	MapError func(error) error
	OnError  func(error)
	Retry    *RetryConfig
	Throttle *ThrottleConfig
}

Features configures which decorators to apply. Nil fields are skipped.

Decorators are applied in a fixed order (innermost to outermost): OnError → MapError → Retry → Breaker → Throttle.

type Fn

type Fn[T, R any] func(context.Context, T) (R, error)

Fn is the function shape all decorators operate on: a context-aware function that returns a value or an error.

Example (Chain)

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/binaryphile/fluentfp/wrap"
)

func main() {
	// fetchData simulates a remote call.
	fetchData := func(_ context.Context, key string) (string, error) {
		return fmt.Sprintf("data(%s)", key), nil
	}

	// Compose: retry transient errors, then limit concurrency.
	resilient := wrap.Func(fetchData).
		WithRetry(3, wrap.ExpBackoff(time.Millisecond), nil).
		WithThrottle(10)

	got, _ := resilient(context.Background(), "abc")
	fmt.Println(got)
}

Output:
data(abc)

func Func

func Func[T, R any](fn func(context.Context, T) (R, error)) Fn[T, R]

Func wraps a plain function as an Fn for fluent decoration. Go infers the type parameters from fn:

wrap.Func(fetchUser).With(wrap.Features{
    Retry: wrap.Retry(3, wrap.ExpBackoff(time.Second), nil),
})

func (Fn[T, R]) With

func (f Fn[T, R]) With(feat Features) Fn[T, R]

With applies the features to f in a fixed order. Nil fields are skipped. Innermost to outermost: OnError → MapError → Retry → Breaker → Throttle.

Example

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/binaryphile/fluentfp/wrap"
)

func main() {
	// fetchData simulates a remote call.
	fetchData := func(_ context.Context, key string) (string, error) {
		return fmt.Sprintf("data(%s)", key), nil
	}

	// Configure all features in one struct. Library controls decorator order.
	resilient := wrap.Func(fetchData).With(wrap.Features{
		Retry:    wrap.Retry(3, wrap.ExpBackoff(time.Millisecond), nil),
		Throttle: wrap.Throttle(10),
	})

	got, _ := resilient(context.Background(), "abc")
	fmt.Println(got)
}

Output:
data(abc)

func (Fn[T, R]) WithBreaker

func (f Fn[T, R]) WithBreaker(b *Breaker) Fn[T, R]

WithBreaker is shorthand for With(Features{Breaker: b}).

Example

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/binaryphile/fluentfp/wrap"
)

func main() {
	// double doubles the input.
	double := func(_ context.Context, n int) (int, error) { return n * 2, nil }

	// Protect a dependency with a circuit breaker.
	breaker := wrap.NewBreaker(wrap.BreakerConfig{
		ResetTimeout: 10 * time.Second,
	})

	protected := wrap.Func(double).WithBreaker(breaker)
	got, _ := protected(context.Background(), 21)
	fmt.Println(got)
}

Output:
42

func (Fn[T, R]) WithMapError

func (f Fn[T, R]) WithMapError(mapper func(error) error) Fn[T, R]

WithMapError is shorthand for With(Features{MapError: mapper}).

Example

package main

import (
	"context"
	"fmt"

	"github.com/binaryphile/fluentfp/wrap"
)

func main() {
	// fetchUser simulates a user lookup that fails.
	fetchUser := func(_ context.Context, id int) (string, error) {
		return "", fmt.Errorf("not found")
	}

	// annotate wraps errors with calling context.
	annotate := func(err error) error {
		return fmt.Errorf("fetchUser(%d): %w", 42, err)
	}

	wrapped := wrap.Func(fetchUser).WithMapError(annotate)
	_, err := wrapped(context.Background(), 42)
	fmt.Println(err)
}

Output:
fetchUser(42): not found

func (Fn[T, R]) WithOnError

func (f Fn[T, R]) WithOnError(handler func(error)) Fn[T, R]

WithOnError is shorthand for With(Features{OnError: handler}).

Example

package main

import (
	"context"
	"fmt"

	"github.com/binaryphile/fluentfp/wrap"
)

func main() {
	// fetchUser simulates a user lookup that fails.
	fetchUser := func(_ context.Context, id int) (string, error) {
		return "", fmt.Errorf("not found")
	}

	// logError prints the error without changing the return value.
	logError := func(err error) {
		fmt.Printf("logged: %v\n", err)
	}

	observed := wrap.Func(fetchUser).WithOnError(logError)
	_, err := observed(context.Background(), 1)
	fmt.Printf("returned: %v\n", err)
}

Output:
logged: not found
returned: not found

func (Fn[T, R]) WithRetry

func (f Fn[T, R]) WithRetry(maxAttempts int, backoff Backoff, shouldRetry func(error) bool) Fn[T, R]

WithRetry is shorthand for With(Features{Retry: Retry(...)}).

Example

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/binaryphile/fluentfp/wrap"
)

func main() {
	// double doubles the input. Succeeds on first try.
	double := func(_ context.Context, n int) (int, error) { return n * 2, nil }

	// Retry up to 3 times with exponential backoff.
	resilient := wrap.Func(double).WithRetry(3, wrap.ExpBackoff(time.Millisecond), nil)

	got, _ := resilient(context.Background(), 5)
	fmt.Println(got)
}

Output:
10

func (Fn[T, R]) WithThrottle

func (f Fn[T, R]) WithThrottle(n int) Fn[T, R]

WithThrottle is shorthand for With(Features{Throttle: Throttle(n)}).

Example

package main

import (
	"context"
	"fmt"

	"github.com/binaryphile/fluentfp/wrap"
)

func main() {
	// double doubles the input.
	double := func(_ context.Context, n int) (int, error) { return n * 2, nil }

	// Allow at most 5 concurrent calls.
	limited := wrap.Func(double).WithThrottle(5)

	got, _ := limited(context.Background(), 3)
	fmt.Println(got)
}

Output:
6

func (Fn[T, R]) WithThrottleWeighted

func (f Fn[T, R]) WithThrottleWeighted(capacity int, cost func(T) int) Fn[T, R]

WithThrottleWeighted wraps f with cost-based concurrency control. Not available via Features because the cost function requires type T.

type RetryConfig

type RetryConfig struct {
	Backoff     Backoff
	Max         int
	ShouldRetry func(error) bool
}

RetryConfig configures the retry feature.

func Retry

func Retry(max int, backoff Backoff, shouldRetry func(error) bool) *RetryConfig

Retry returns a RetryConfig for use in Features.

type Snapshot

type Snapshot struct {
	State               BreakerState
	Successes           int
	Failures            int
	ConsecutiveFailures int
	Rejected            int
	OpenedAt            time.Time
}

Snapshot is a point-in-time view of breaker state and metrics. Successes and Failures reset when the breaker transitions to closed. ConsecutiveFailures resets on any success (including while closed). Rejected is a lifetime counter. OpenedAt is the zero time when State is StateClosed.

type ThrottleConfig

type ThrottleConfig struct {
	N int
}

ThrottleConfig configures count-based concurrency control.

func Throttle

func Throttle(n int) *ThrottleConfig

Throttle returns a ThrottleConfig for use in Features.

type Transition

type Transition struct {
	From BreakerState
	To   BreakerState
	At   time.Time
}

Transition describes a circuit breaker state change.