{"id":36519737,"url":"https://github.com/vnykmshr/autobreaker","last_synced_at":"2026-01-23T19:03:05.790Z","repository":{"id":323535770,"uuid":"1092860568","full_name":"vnykmshr/autobreaker","owner":"vnykmshr","description":"Adaptive circuit breaker for Go with percentage-based thresholds that automatically adjust to traffic patterns. Zero dependencies, \u003c100ns overhead.","archived":false,"fork":false,"pushed_at":"2025-11-24T14:18:42.000Z","size":8024,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-12T05:25:26.844Z","etag":null,"topics":["adaptive-threshold","circuit-breaker","distributed-systems","fault-tolerance","go","golang","microservices","observability","reliability-engineering","resilience"],"latest_commit_sha":null,"homepage":"https://github.com/vnykmshr/autobreaker/blob/main/docs/TECHNICAL_BLOG.md","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vnykmshr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP_RFCS.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-09T13:08:13.000Z","updated_at":"2025-11-24T14:18:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vnykmshr/autobreaker","commit_stats":null,"previous_names":["vnykmshr/autobreaker"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/vnykmshr/autobreaker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vnykmshr%2Fautobreaker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vnykmshr%2Fautobreaker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vnykmshr%2Fautobreaker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vnykmshr%2Fautobreaker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vnykmshr","download_url":"https://codeload.github.com/vnykmshr/autobreaker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vnykmshr%2Fautobreaker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28698344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T17:25:48.045Z","status":"ssl_error","status_checked_at":"2026-01-23T17:25:47.153Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adaptive-threshold","circuit-breaker","distributed-systems","fault-tolerance","go","golang","microservices","observability","reliability-engineering","resilience"],"created_at":"2026-01-12T02:49:47.210Z","updated_at":"2026-01-23T19:03:05.785Z","avatar_url":"https://github.com/vnykmshr.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AutoBreaker\n\nAdaptive circuit breaker for Go with percentage-based thresholds that automatically adjust to traffic patterns.\n\n[![CI](https://github.com/vnykmshr/autobreaker/workflows/CI/badge.svg)](https://github.com/vnykmshr/autobreaker/actions)\n[![Go Reference](https://pkg.go.dev/badge/github.com/vnykmshr/autobreaker.svg)](https://pkg.go.dev/github.com/vnykmshr/autobreaker)\n[![Go Report Card](https://goreportcard.com/badge/github.com/vnykmshr/autobreaker)](https://goreportcard.com/report/github.com/vnykmshr/autobreaker)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n## Overview\n\nTraditional circuit breakers use static failure thresholds (e.g., \"trip after 10 failures\"). This creates problems: at high traffic, 10 failures may represent \u003c1% error rate (too sensitive), while at low traffic, 10 failures may be 100% error rate (too slow to protect).\n\nAutoBreaker uses **percentage-based thresholds** that adapt to request volume automatically. Configure once, works correctly across all traffic levels and environments.\n\n**Features:**\n- **Adaptive Thresholds** - Percentage-based failure detection scales with traffic\n- **Runtime Configuration** - Update settings without restart\n- **Zero Dependencies** - Standard library only\n- **High Performance** - \u003c100ns overhead per request, zero allocations\n- **Observability** - Metrics() and Diagnostics() APIs built-in\n- **Thread-Safe** - Lock-free atomic operations throughout\n\n## Installation\n\n```bash\ngo get github.com/vnykmshr/autobreaker\n```\n\nRequires Go 1.21 or later.\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"time\"\n    \"github.com/vnykmshr/autobreaker\"\n)\n\nfunc main() {\n    breaker := autobreaker.New(autobreaker.Settings{\n        Name:    \"api-client\",\n        Timeout: 10 * time.Second,\n    })\n\n    result, err := breaker.Execute(func() (interface{}, error) {\n        return httpClient.Get(\"https://api.example.com/data\")\n    })\n\n    if err == autobreaker.ErrOpenState {\n        fmt.Println(\"Circuit open, using fallback\")\n        return\n    }\n\n    fmt.Printf(\"Result: %v\\n\", result)\n}\n```\n\n## Configuration\n\n### Basic Settings\n\n```go\nbreaker := autobreaker.New(autobreaker.Settings{\n    Name:    \"service-name\",\n    Timeout: 30 * time.Second, // Open → HalfOpen transition time\n})\n```\n\nDefault behavior uses adaptive thresholds (5% failure rate, minimum 20 observations).\n\n### Advanced Configuration\n\n```go\nbreaker := autobreaker.New(autobreaker.Settings{\n    Name:                 \"service-name\",\n    Timeout:              30 * time.Second,\n    MaxRequests:          3,     // Concurrent requests in half-open state\n    Interval:             60 * time.Second, // Stats reset interval\n\n    // Adaptive threshold settings\n    AdaptiveThreshold:    true,\n    FailureRateThreshold: 0.05,  // Trip at 5% error rate\n    MinimumObservations:  20,    // Minimum requests before evaluating\n\n    // Callbacks (must be fast: \u003c1μs)\n    OnStateChange: func(name string, from, to autobreaker.State) {\n        go log.Printf(\"%s: %v → %v\", name, from, to) // Async\n    },\n\n    IsSuccessful: func(err error) bool {\n        // Don't count 4xx client errors as failures\n        if httpErr, ok := err.(*HTTPError); ok {\n            return httpErr.Code \u003e= 400 \u0026\u0026 httpErr.Code \u003c 500\n        }\n        return err == nil\n    },\n})\n```\n\n### Runtime Updates\n\n```go\nerr := breaker.UpdateSettings(autobreaker.SettingsUpdate{\n    FailureRateThreshold: autobreaker.Float64Ptr(0.10),\n    Timeout:              autobreaker.DurationPtr(15 * time.Second),\n})\n```\n\n## Observability\n\n### Metrics\n\n```go\nmetrics := breaker.Metrics()\nfmt.Printf(\"State: %v, Requests: %d, Failure Rate: %.2f%%\\n\",\n    metrics.State, metrics.Requests, metrics.FailureRate*100)\n```\n\n### Diagnostics\n\n```go\ndiag := breaker.Diagnostics()\nif diag.WillTripNext {\n    log.Warn(\"Circuit about to trip on next failure\")\n}\n```\n\nSee [examples/observability](examples/observability/) for Prometheus integration and monitoring patterns.\n\n## How It Works\n\nAutoBreaker calculates failure rate as a percentage of recent requests:\n\n```\nAdaptive: \"Trip when error rate \u003e 5%\"\n\nAt 100 RPS → trips at 50 failures (5% of 1000 req/10s)\nAt 10 RPS  → trips at 5 failures  (5% of 100 req/10s)\n\nSame config, correct behavior at any traffic level.\n```\n\nThe implementation uses a three-state machine (Closed → Open → HalfOpen → Closed) with lock-free atomic operations for minimal overhead.\n\n**Architecture Details:** See [docs/TECHNICAL_BLOG.md](docs/TECHNICAL_BLOG.md) for design details with diagrams.\n\n## Performance\n\nBenchmarks (Go 1.21, Apple M1):\n\n| Operation          | Latency | Allocations |\n|--------------------|---------|-------------|\n| Execute (Closed)   | 78.5 ns | 0 allocs    |\n| Execute (Open)     | 0.34 ns | 0 allocs    |\n| UpdateSettings()   | 89.2 ns | 0 allocs    |\n\nSee [docs/BENCHMARKS.md](docs/BENCHMARKS.md) for detailed performance analysis.\n\n## Examples\n\nProduction-ready examples in [`examples/`](examples/):\n\n- [**production_ready**](examples/production_ready/) - HTTP client integration, recommended starting point\n- [**runtime_config**](examples/runtime_config/) - Dynamic configuration updates (file, API, signals)\n- [**observability**](examples/observability/) - Monitoring, metrics, and diagnostics\n- [**prometheus**](examples/prometheus/) - Prometheus collector integration\n- [**adaptive**](examples/adaptive/) - Adaptive vs static threshold comparison\n- [**custom_errors**](examples/custom_errors/) - Custom error classification\n\nRun examples:\n```bash\ngo run examples/production_ready/main.go\n```\n\n## Documentation\n\n- [Technical Blog](docs/TECHNICAL_BLOG.md) - Architecture deep-dive with diagrams\n- [State Machine](docs/STATE_MACHINE.md) - State transition specification\n- [Concurrency](docs/CONCURRENCY.md) - Lock-free implementation details\n- [Error Classification](docs/ERROR_CLASSIFICATION.md) - Custom error handling\n- [API Reference](https://pkg.go.dev/github.com/vnykmshr/autobreaker) - Full API documentation\n\n## Important Notes\n\n**Callback Performance:** `ReadyToTrip`, `OnStateChange`, and `IsSuccessful` callbacks execute synchronously on every request. Keep them \u003c1μs. Use goroutines for slow operations:\n\n```go\nOnStateChange: func(name string, from, to State) {\n    go metrics.Record(name, from, to) // Async, non-blocking\n}\n```\n\n**Compatibility:** Drop-in replacement for sony/gobreaker API. Enable adaptive thresholds with `AdaptiveThreshold: true`.\n\n## Status\n\n**Production-Ready** - v1.0.0\n\n- 102 tests, 97.1% coverage, race detector clean\n- Zero dependencies, zero allocations in hot path\n- Compatible with Go 1.21+\n\nSee [docs/ROADMAP_RFCS.md](docs/ROADMAP_RFCS.md) for future plans.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file.\n\n## Contributing\n\nContributions welcome! Please open an issue to discuss changes before submitting PRs.\n\nSee [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvnykmshr%2Fautobreaker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvnykmshr%2Fautobreaker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvnykmshr%2Fautobreaker/lists"}