{"id":41784885,"url":"https://github.com/aponysus/recourse","last_synced_at":"2026-01-25T04:10:24.244Z","repository":{"id":328535302,"uuid":"1114743049","full_name":"aponysus/recourse","owner":"aponysus","description":"Policy-driven, observable resilience for Go services: retries, hedging, circuit breaking, and budgets.","archived":false,"fork":false,"pushed_at":"2026-01-23T12:57:54.000Z","size":341,"stargazers_count":1,"open_issues_count":12,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-24T04:54:39.840Z","etag":null,"topics":["backoff","backpressure","circuit-breaker","distributed-systems","fault-tolerance","go","golang","hedging","microservices","observability","rate-limiting","reliability","resilience","retry"],"latest_commit_sha":null,"homepage":"https://aponysus.github.io/recourse/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aponysus.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"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-12-11T20:25:16.000Z","updated_at":"2026-01-23T12:57:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aponysus/recourse","commit_stats":null,"previous_names":["aponysus/rego","aponysus/recourse"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/aponysus/recourse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aponysus%2Frecourse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aponysus%2Frecourse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aponysus%2Frecourse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aponysus%2Frecourse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aponysus","download_url":"https://codeload.github.com/aponysus/recourse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aponysus%2Frecourse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28742983,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T02:46:29.005Z","status":"ssl_error","status_checked_at":"2026-01-25T02:44:29.968Z","response_time":113,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["backoff","backpressure","circuit-breaker","distributed-systems","fault-tolerance","go","golang","hedging","microservices","observability","rate-limiting","reliability","resilience","retry"],"created_at":"2026-01-25T04:10:22.519Z","updated_at":"2026-01-25T04:10:24.239Z","avatar_url":"https://github.com/aponysus.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# recourse\n\nPolicy-driven, observable resilience for Go services: retries, hedging, circuit breaking, and budgets.\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/aponysus/recourse.svg)](https://pkg.go.dev/github.com/aponysus/recourse)\n[![Go Report Card](https://goreportcard.com/badge/github.com/aponysus/recourse)](https://goreportcard.com/report/github.com/aponysus/recourse)\n[![Coverage](https://codecov.io/gh/aponysus/recourse/branch/main/graph/badge.svg)](https://codecov.io/gh/aponysus/recourse)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n\u003e recourse (n.): a source of help or strength.\n\nDocs site: https://aponysus.github.io/recourse/\nChangelog: [CHANGELOG.md](CHANGELOG.md)\n\n## When to use recourse\n\n- You have multiple services and want consistent retry behavior.\n- You need per-attempt visibility for incident debugging.\n- You want explicit backpressure to avoid retry storms.\n- You are willing to enforce low-cardinality policy keys and governance.\n\n## When not to use recourse\n\n- You only need a simple retry helper at one or two call sites.\n- The operation is not safe to retry and you cannot add idempotency safeguards.\n- You do not want to manage keys, policies, or rollout discipline.\n\n## What makes it different\n\n- **Policy keys**: call sites provide a stable key; policies define the retry envelope.\n  \u003c!-- Claim-ID: CLM-019 --\u003e\n- **Classifiers**: outcomes are protocol-aware instead of \"retry on any error\".\n- **Backpressure**: budgets gate attempts to prevent load amplification.\n  \u003c!-- Claim-ID: CLM-010 --\u003e\n- **Explainability**: timelines and observer hooks make behavior debuggable.\n  \u003c!-- Claim-ID: CLM-013 --\u003e\n  \u003c!-- Claim-ID: CLM-014 --\u003e\n\n## Install\n\n```bash\ngo get github.com/aponysus/recourse@latest\n```\n\n## Quick start\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\n\t\"github.com/aponysus/recourse/recourse\"\n)\n\ntype User struct{ ID string }\n\nfunc main() {\n\tctx := context.Background()\n\n\tuser, err := recourse.DoValue[User](ctx, \"user-service.GetUser\", func(ctx context.Context) (User, error) {\n\t\treturn User{ID: \"123\"}, nil\n\t})\n\t_ = user\n\t_ = err\n}\n```\n\n## Debugging\n\nCapture a timeline when you need to answer \"what happened on each attempt\":\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\n\t\"github.com/aponysus/recourse/observe\"\n\t\"github.com/aponysus/recourse/recourse\"\n)\n\nfunc main() {\n\tctx, capture := observe.RecordTimeline(context.Background())\n\n\t_ = recourse.Do(ctx, \"user-service.GetUser\", func(ctx context.Context) error {\n\t\treturn nil\n\t})\n\n\tif tl := capture.Timeline(); tl != nil {\n\t\tfor _, a := range tl.Attempts {\n\t\t\t// a.Outcome, a.Err, a.Backoff, a.BudgetAllowed, ...\n\t\t\t_ = a\n\t\t}\n\t}\n}\n```\n\u003c!-- Claim-ID: CLM-013 --\u003e\n\nFor streaming logs/metrics/tracing, implement `observe.Observer`. See the observability docs for details.\n\u003c!-- Claim-ID: CLM-014 --\u003e\n\n## Docs\n\n- Design overview: https://aponysus.github.io/recourse/design-overview/\n- Getting started: https://aponysus.github.io/recourse/getting-started/\n- Gotchas and safety checklist: https://aponysus.github.io/recourse/gotchas/\n- Key patterns and taxonomy: https://aponysus.github.io/recourse/concepts/key-patterns/\n- Adoption guide: https://aponysus.github.io/recourse/adoption-guide/\n- Incident debugging: https://aponysus.github.io/recourse/incident-debugging/\n- Comparison: https://aponysus.github.io/recourse/comparison/\n- Why recourse: https://aponysus.github.io/recourse/blog/why-recourse/\n- Defaults and safety model: https://aponysus.github.io/recourse/reference/defaults-safety/\n- Policy schema reference: https://aponysus.github.io/recourse/reference/policy-schema/\n- Reason codes and timelines: https://aponysus.github.io/recourse/reference/reason-codes/\n\n## Compatibility policy\n\n- v1.x follows SemVer; exported APIs in the core packages are stable.\n- Stable packages: `recourse`, `retry`, `policy`, `observe`, `classify`, `budget`, `controlplane`, `circuit`, `hedge`, `integrations/http`.\n- `integrations/grpc` is a separate module with its own tags (intended to track root releases).\n- `internal` and `examples` are not part of the API contract.\n- Telemetry fields and reason codes are treated as stable and documented in the generated references.\n\u003c!-- Claim-ID: CLM-020 --\u003e\n\n## Versioning\n\n- Releases: see `CHANGELOG.md` or GitHub releases.\n- Go version: see `go.mod` (currently 1.23)\n\u003c!-- Claim-ID: CLM-021 --\u003e\n\n## Contributing\n\n- See [CONTRIBUTING.md](CONTRIBUTING.md).\n- Onboarding: `docs/onboarding.md`\n- Extending: `docs/extending.md`\n\n## License\n\nApache-2.0. See `LICENSE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faponysus%2Frecourse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faponysus%2Frecourse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faponysus%2Frecourse/lists"}