https://github.com/exaring/hoglet

Simple low-overhead circuit breaker library for go
https://github.com/exaring/hoglet

circuit-breaker golang library

Last synced: 23 days ago
JSON representation

Simple low-overhead circuit breaker library for go

• Host: GitHub
• URL: https://github.com/exaring/hoglet
• Owner: exaring
• License: mit
• Created: 2023-03-09T20:07:35.000Z (almost 3 years ago)
• Default Branch: main
• Last Pushed: 2025-12-19T13:47:54.000Z (about 2 months ago)
• Last Synced: 2025-12-22T05:36:52.504Z (about 1 month ago)
• Topics: circuit-breaker, golang, library
• Language: Go
• Homepage:
• Size: 107 KB
• Stars: 17
• Watchers: 8
• Forks: 1
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
[![Build Status](https://github.com/exaring/hoglet/actions/workflows/main.yaml/badge.svg)](https://github.com/exaring/hoglet/actions/workflows/main.yaml)

[![Go Reference](https://pkg.go.dev/badge/github.com/exaring/hoglet.svg)](https://pkg.go.dev/github.com/exaring/hoglet)

[![Go Report Card](https://goreportcard.com/badge/github.com/exaring/hoglet)](https://goreportcard.com/report/github.com/exaring/hoglet)

# hoglet

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(

    hoglet.NewSlidingWindowBreaker(5*time.Second, 0.1),

    hoglet.WithFailureCondition(hoglet.IgnoreContextCanceled),

)

/* if err != nil ... */

f, _ := hoglet.Wrap(h, foo)(context.Background(), 42)

fmt.Println(f.Bar) // 42

_, err = hoglet.Wrap(h, foo)(context.Background(), 0)

fmt.Println(err) // bar is not 42

_, err = hoglet.Wrap(h, foo)(context.Background(), 42)

fmt.Println(err) // hoglet: breaker is open

time.Sleep(5 * time.Second)

f, _ = hoglet.Wrap(h, foo)(context.Background(), 42)

fmt.Println(f.Bar) // 42

```

## Operation

Each call to the wrapped function (via `Circuit.Call`) is tracked and its result "observed". Breakers then react to

these observations according to their own logic, optionally opening the circuit.

An open circuit does not allow any calls to go through, and will return an error immediately.

If the wrapped function blocks, `Circuit.Call` will block as well, but any context cancellations or expirations will

count towards the failure rate, allowing the circuit to respond timely to failures, while still having well-defined and

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.