feat!: move the type parameters to a separate wrapper

This makes the circuit itself type-agnostic, allowing reuse of circuits for multiple functions with different types.

BREAKING CHANGE: circuit initialization now does not require the function and does not provide the Call() method
anymore, instead relying on the package-level Wrap().

Author: Leo Antunes

README.md

@@ -9,30 +9,32 @@ Simple low-overhead circuit breaker library.
 ## Usage
 
 ```go
+// some arbitrary function
+foo := func(ctx context.Context, bar int) (Foo, error) {
+    if bar == 42 {
+        return Foo{Bar: bar}, nil
+    }
+    return Foo{}, fmt.Errorf("bar is not 42")
+}
+
 h, err := hoglet.NewCircuit(
-    func(ctx context.Context, bar int) (Foo, error) {
-        if bar == 42 {
-            return Foo{Bar: bar}, nil
-        }
-        return Foo{}, fmt.Errorf("bar is not 42")
-    },
     hoglet.NewSlidingWindowBreaker(5*time.Second, 0.1),
     hoglet.WithFailureCondition(hoglet.IgnoreContextCanceled),
 )
 /* if err != nil ... */
 
-f, _ := h.Call(context.Background(), 42)
+f, _ := hoglet.Wrap(h, foo)(context.Background(), 42)
 fmt.Println(f.Bar) // 42
 
-_, err = h.Call(context.Background(), 0)
+_, err = hoglet.Wrap(h, foo)(context.Background(), 0)
 fmt.Println(err) // bar is not 42
 
-_, err = h.Call(context.Background(), 42)
+_, err = hoglet.Wrap(h, foo)(context.Background(), 42)
 fmt.Println(err) // hoglet: breaker is open
 
 time.Sleep(5 * time.Second)
 
-f, _ = h.Call(context.Background(), 42)
+f, _ = hoglet.Wrap(h, foo)(context.Background(), 42)
 fmt.Println(f.Bar) // 42
 ```
 
@@ -51,4 +53,4 @@ non-racy behavior around the failed function.
 ## Design
 
 Hoglet prefers throughput to correctness (e.g. by avoiding locks), which means it cannot guarantee an exact number of
-calls will go through.
+calls will go through.

example_test.go

@@ -22,29 +22,28 @@ func foo(ctx context.Context, bar int) (Foo, error) {
 
 func ExampleEWMABreaker() {
 	h, err := hoglet.NewCircuit(
-		foo,
 		hoglet.NewEWMABreaker(10, 0.1),
 		hoglet.WithHalfOpenDelay(time.Second),
 	)
 	if err != nil {
 		log.Fatal(err)
 	}
 
-	f, err := h.Call(context.Background(), 1)
+	f, err := hoglet.Wrap(h, foo)(context.Background(), 1)
 	if err != nil {
 		log.Fatal(err)
 	}
 	fmt.Println(f.Bar)
 
-	_, err = h.Call(context.Background(), 100)
+	_, err = hoglet.Wrap(h, foo)(context.Background(), 100)
 	fmt.Println(err)
 
-	_, err = h.Call(context.Background(), 2)
+	_, err = hoglet.Wrap(h, foo)(context.Background(), 2)
 	fmt.Println(err)
 
 	time.Sleep(time.Second) // wait for half-open delay
 
-	f, err = h.Call(context.Background(), 3)
+	f, err = hoglet.Wrap(h, foo)(context.Background(), 3)
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -59,28 +58,27 @@ func ExampleEWMABreaker() {
 
 func ExampleSlidingWindowBreaker() {
 	h, err := hoglet.NewCircuit(
-		foo,
 		hoglet.NewSlidingWindowBreaker(time.Second, 0.1),
 	)
 	if err != nil {
 		log.Fatal(err)
 	}
 
-	f, err := h.Call(context.Background(), 1)
+	f, err := hoglet.Wrap(h, foo)(context.Background(), 1)
 	if err != nil {
 		log.Fatal(err)
 	}
 	fmt.Println(f.Bar)
 
-	_, err = h.Call(context.Background(), 100)
+	_, err = hoglet.Wrap(h, foo)(context.Background(), 100)
 	fmt.Println(err)
 
-	_, err = h.Call(context.Background(), 2)
+	_, err = hoglet.Wrap(h, foo)(context.Background(), 2)
 	fmt.Println(err)
 
 	time.Sleep(time.Second) // wait for sliding window
 
-	f, err = h.Call(context.Background(), 3)
+	f, err = hoglet.Wrap(h, foo)(context.Background(), 3)
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -94,14 +92,15 @@ func ExampleSlidingWindowBreaker() {
 }
 
 func ExampleConcurrencyLimiter() {
+	foo := func(ctx context.Context, _ any) (any, error) {
+		select {
+		case <-ctx.Done():
+		case <-time.After(time.Second):
+		}
+		return nil, nil
+	}
+
 	h, err := hoglet.NewCircuit(
-		func(ctx context.Context, _ any) (any, error) {
-			select {
-			case <-ctx.Done():
-			case <-time.After(time.Second):
-			}
-			return nil, nil
-		},
 		hoglet.NewSlidingWindowBreaker(10, 0.1),
 		hoglet.WithBreakerMiddleware(hoglet.ConcurrencyLimiter(1, false)),
 	)
@@ -116,15 +115,15 @@ func ExampleConcurrencyLimiter() {
 
 	go func() {
 		// use up the concurrency limit
-		_, _ = h.Call(ctx, 42)
+		_, _ = hoglet.Wrap(h, foo)(ctx, 42)
 	}()
 
 	// ensure call above actually started
 	time.Sleep(time.Millisecond * 100)
 
 	go func() {
 		defer close(errCh)
-		_, err := h.Call(ctx, 42)
+		_, err := hoglet.Wrap(h, foo)(ctx, 42)
 		if err != nil {
 			errCh <- err
 		}

hoglet.go

@@ -13,8 +13,7 @@ import (
 // stops calling the wrapped function until it closes again, returning [ErrCircuitOpen] in the meantime.
 //
 // A zero Circuit will panic, analogous to calling a nil function variable. Initialize with [NewCircuit].
-type Circuit[IN, OUT any] struct {
-	f WrappedFunc[IN, OUT]
+type Circuit struct {
 	options
 
 	// State
@@ -64,8 +63,8 @@ func (f BreakerMiddlewareFunc) Wrap(of ObserverFactory) (ObserverFactory, error)
 	return f(of)
 }
 
-// WrappedFunc is the type of the function wrapped by a Breaker.
-type WrappedFunc[IN, OUT any] func(context.Context, IN) (OUT, error)
+// WrappableFunc is the type of the function wrapped by a [Circuit].
+type WrappableFunc[IN, OUT any] func(context.Context, IN) (OUT, error)
 
 // dedupObservableCall wraps an [Observer] ensuring it can only be observed a single time.
 func dedupObservableCall(obs Observer) Observer {
@@ -83,12 +82,10 @@ func (d *dedupedObserver) Observe(failure bool) {
 	})
 }
 
-// NewCircuit instantiates a new [Circuit] that wraps the provided function. See [Circuit.Call] for calling semantics.
-// A Circuit with a nil breaker is a noop wrapper around the provided function and will never open.
-func NewCircuit[IN, OUT any](f WrappedFunc[IN, OUT], breaker Breaker, opts ...Option) (*Circuit[IN, OUT], error) {
-	c := &Circuit[IN, OUT]{
-		f: f,
-	}
+// NewCircuit instantiates a new [Circuit]. See [Wrap] for further usage.
+// A [Circuit] with a nil breaker is a noop and will never open for any of its wrapped functions.
+func NewCircuit(breaker Breaker, opts ...Option) (*Circuit, error) {
+	c := &Circuit{}
 
 	o := options{
 		isFailure: defaultFailureCondition,
@@ -115,10 +112,10 @@ func NewCircuit[IN, OUT any](f WrappedFunc[IN, OUT], breaker Breaker, opts ...Op
 	return c, nil
 }
 
-// State reports the current [State] of the circuit.
+// State reports the current [State] of the [Circuit].
 // It should only be used for informational purposes. To minimize race conditions, the circuit should be called directly
 // instead of checking its state first.
-func (c *Circuit[IN, OUT]) State() State {
+func (c *Circuit) State() State {
 	oa := c.openedAt.Load()
 
 	if oa == 0 {
@@ -137,7 +134,7 @@ func (c *Circuit[IN, OUT]) State() State {
 
 // stateForCall returns the state of the circuit meant for the next call.
 // It wraps [State] to keep the mutable part outside of the external API.
-func (c *Circuit[IN, OUT]) stateForCall() State {
+func (c *Circuit) stateForCall() State {
 	state := c.State()
 
 	if state == StateHalfOpen {
@@ -152,18 +149,18 @@ func (c *Circuit[IN, OUT]) stateForCall() State {
 
 // open marks the circuit as open, if it not already.
 // It is safe for concurrent calls and only the first one will actually set opening time.
-func (c *Circuit[IN, OUT]) open() {
+func (c *Circuit) open() {
 	// CompareAndSwap is needed to avoid clobbering another goroutine's openedAt value.
 	c.openedAt.CompareAndSwap(0, time.Now().UnixMicro())
 }
 
 // reopen forcefully (re)marks the circuit as open, resetting the half-open time.
-func (c *Circuit[IN, OUT]) reopen() {
+func (c *Circuit) reopen() {
 	c.openedAt.Store(time.Now().UnixMicro())
 }
 
 // close closes the circuit.
-func (c *Circuit[IN, OUT]) close() {
+func (c *Circuit) close() {
 	c.openedAt.Store(0)
 }
 
@@ -173,22 +170,22 @@ func (c *Circuit[IN, OUT]) close() {
 // If the breaker is closed, it returns a non-nil [Observer] that will be used to observe the result of the call.
 //
 // It implements [ObserverFactory], so that the [Circuit] can act as the base for [BreakerMiddleware].
-func (c *Circuit[IN, OUT]) ObserverForCall(_ context.Context, state State) (Observer, error) {
+func (c *Circuit) ObserverForCall(_ context.Context, state State) (Observer, error) {
 	if state == StateOpen {
 		return nil, ErrCircuitOpen
 	}
-	return stateObserver[IN, OUT]{
+	return stateObserver{
 		circuit: c,
 		state:   state,
 	}, nil
 }
 
-type stateObserver[IN, OUT any] struct {
-	circuit *Circuit[IN, OUT]
+type stateObserver struct {
+	circuit *Circuit
 	state   State
 }
 
-func (s stateObserver[IN, OUT]) Observe(failure bool) {
+func (s stateObserver) Observe(failure bool) {
 	switch s.circuit.breaker.observe(s.state == StateHalfOpen, failure) {
 	case stateChangeNone:
 		return // noop
@@ -199,59 +196,59 @@ func (s stateObserver[IN, OUT]) Observe(failure bool) {
 	}
 }
 
-// Call calls the wrapped function if the circuit is closed and returns its result. If the circuit is open, it returns
-// [ErrCircuitOpen].
+// Wrap wraps the provided function with the given [Circuit].
+//
+// Calling the returned function if the circuit is closed and returns the result of the wrapped function.
+// If the circuit is open, it returns [ErrCircuitOpen].
 //
 // The wrapped function is called synchronously, but possible context errors are recorded as soon as they occur. This
 // ensures the circuit opens quickly, even if the wrapped function blocks.
 //
 // By default, all errors are considered failures (including [context.Canceled]), but this can be customized via
-// [WithFailureCondition] and [IgnoreContextCanceled].
+// [WithFailureCondition] and [IgnoreContextCanceled] on the provided [Circuit].
 //
 // Panics are observed as failures, but are not recovered (i.e.: they are "repanicked" instead).
-func (c *Circuit[IN, OUT]) Call(ctx context.Context, in IN) (out OUT, err error) {
-	if c.f == nil {
-		return out, nil
-	}
-
-	obs, err := c.observerFactory.ObserverForCall(ctx, c.stateForCall())
-	if err != nil {
-		// Note: any errors here are not "observed" and do not count towards the breaker's failure rate.
-		// This includes:
-		// - ErrCircuitOpen
-		// - ErrConcurrencyLimit (for blocking limited circuits)
-		// - context timeouts while blocked on concurrency limit
-		// And any other errors that may be returned by optional breaker wrappers.
-		return out, err
-	}
+func Wrap[IN, OUT any](c *Circuit, f WrappableFunc[IN, OUT]) WrappableFunc[IN, OUT] {
+	return func(ctx context.Context, in IN) (out OUT, err error) {
+		obs, err := c.observerFactory.ObserverForCall(ctx, c.stateForCall())
+		if err != nil {
+			// Note: any errors here are not "observed" and do not count towards the breaker's failure rate.
+			// This includes:
+			// - ErrCircuitOpen
+			// - ErrConcurrencyLimit (for blocking limited circuits)
+			// - context timeouts while blocked on concurrency limit
+			// And any other errors that may be returned by optional breaker wrappers.
+			return out, err
+		}
 
-	// ensure we dedup the final - potentially wrapped - observer.
-	obs = dedupObservableCall(obs)
+		// ensure we dedup the final - potentially wrapped - observer.
+		obs = dedupObservableCall(obs)
 
-	obsCtx, cancel := context.WithCancelCause(ctx)
-	defer cancel(errWrappedFunctionDone)
+		obsCtx, cancel := context.WithCancelCause(ctx)
+		defer cancel(errWrappedFunctionDone)
 
-	// TODO: we could skip this if we could ensure the original context has neither cancellation nor deadline
-	go c.observeCtx(obs, obsCtx)
+		// TODO: we could skip this if we could ensure the original context has neither cancellation nor deadline
+		go c.observeCtx(obs, obsCtx)
 
-	defer func() {
-		// ensure we also open the breaker on panics
-		if err := recover(); err != nil {
-			obs.Observe(true)
-			panic(err) // let the caller deal with panics
-		}
-		obs.Observe(c.options.isFailure(err))
-	}()
+		defer func() {
+			// ensure we also open the breaker on panics
+			if err := recover(); err != nil {
+				obs.Observe(true)
+				panic(err) // let the caller deal with panics
+			}
+			obs.Observe(c.options.isFailure(err))
+		}()
 
-	return c.f(ctx, in)
+		return f(ctx, in)
+	}
 }
 
 // errWrappedFunctionDone is used to distinguish between internal and external (to the lib) context cancellations.
 var errWrappedFunctionDone = errors.New("wrapped function done")
 
 // observeCtx observes the given context for cancellation and records it as a failure.
 // It assumes [Observer] is idempotent and deduplicates calls itself.
-func (c *Circuit[IN, OUT]) observeCtx(obs Observer, ctx context.Context) {
+func (c *Circuit) observeCtx(obs Observer, ctx context.Context) {
 	// We want to observe a context error as soon as possible to open the breaker, but at the same time we want to
 	// keep the call to the wrapped function synchronous to avoid all pitfalls that come with asynchronicity.
 	<-ctx.Done()