{"id":21658200,"url":"https://github.com/twitchtv/circuitgen","last_synced_at":"2025-12-30T02:15:28.275Z","repository":{"id":39848608,"uuid":"190259110","full_name":"twitchtv/circuitgen","owner":"twitchtv","description":null,"archived":false,"fork":false,"pushed_at":"2023-04-27T15:20:44.000Z","size":48,"stargazers_count":23,"open_issues_count":5,"forks_count":7,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-06-20T15:03:27.462Z","etag":null,"topics":["circuit-breaker","circuit-breaker-pattern","code-generation","go","hystrix"],"latest_commit_sha":null,"homepage":null,"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/twitchtv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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}},"created_at":"2019-06-04T18:37:47.000Z","updated_at":"2024-04-13T17:42:26.000Z","dependencies_parsed_at":"2024-06-20T14:47:12.878Z","dependency_job_id":"d655e203-0654-4ff7-8be2-59d61c823f63","html_url":"https://github.com/twitchtv/circuitgen","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twitchtv%2Fcircuitgen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twitchtv%2Fcircuitgen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twitchtv%2Fcircuitgen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twitchtv%2Fcircuitgen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/twitchtv","download_url":"https://codeload.github.com/twitchtv/circuitgen/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226304453,"owners_count":17603597,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["circuit-breaker","circuit-breaker-pattern","code-generation","go","hystrix"],"created_at":"2024-11-25T09:28:52.036Z","updated_at":"2025-12-30T02:15:28.218Z","avatar_url":"https://github.com/twitchtv.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# circuitgen\n\ncircuitgen generates a circuit wrapper around an interface or struct that encapsulates calling [circuits](https://github.com/cep21/circuit).\nA wrapper struct matching the interface or struct method set is generated, and each method call that is context-aware and returning an error is wrapped\nby a circuit. These wrapper structs have no outside Go dependencies besides the interface or struct's dependencies.\n\nIt's important to provide a `IsBadRequest` to [not count user errors](https://github.com/cep21/circuit#not-counting-user-error-as-a-fault) against the circuit. A bad request is not counted as a success or failure in the circuit, so it does not affect opening or closing the circuit.\nFor example, a spike in HTTP 4xx errors (ex. Validation errors) should not open the circuit.\n\nAn optional `ShouldSkipError` can be provided so that the call is counted as successful even if there is a non-nil error.\nFor example, DynamoDB responses that return ConditionalCheckedFailException (CCFE) should be counted as successful requests. In the scenario where CCFE is counted as a bad request, if the client is getting CCFE a majority of the time, and the circuit opens (ex. spike of timeouts), then the circuit will prolong closing the circuit until the circuit happens to make a request that doesn't return CCFE.\n\n## Method Wrapping Requirements\n\nWhen deciding if making a circuit wrapper is right for your interface or struct, consider that methods will only be wrapped if:\n* The method accepts a context as the first argument\n* The method returns an error as the last value\n\nExample\n```go\ntype Publisher interface {\n\t// Method is wrapped\n\tPublish(ctx context.Context, message string) error\n\t// Method is *not* wrapped\n\tClose() error\n}\n```\n\n# Installation\n\n```bash\ngo get github.com/twitchtv/circuitgen\n```\n\n# Usage\n\n```bash\ncircuitgen --pkg \u003cpackage path\u003e --name \u003ctype name\u003e --out \u003coutput path\u003e [--alias \u003calias\u003e] [--circuit-major-version \u003ccircuit major version\u003e]\n```\n\nAdd `./vendor/` to package path if the dependency is vendored; when using Go modules this is unnecessary.\n\nSet the `circuit-major-version` flag if using Go modules and major version 3 or later. This makes the wrappers import the same version as the rest of your code.\n\n## Example\n\nGenerating the DynamoDB client into the wrappers directory with circuits aliased as \"DynamoDB\"\n\n```bash\ncircuitgen --pkg github.com/aws/aws-sdk-go/service/dynamodb/dynamodbiface --name DynamoDBAPI --alias DynamoDB --out internal/wrappers --circuit-major-version 3\n```\n\nThis generates a circuit wrapper that satifies the `github.com/aws/aws-sdk-go/service/dynamodb/dynamodbiface.DynamoDBAPI` interface.\n\n```go\n// Code generated by circuitgen tool. DO NOT EDIT\n\npackage wrappers\n\nimport (\n\t\"context\"\n\n\t\"github.com/aws/aws-sdk-go/aws/request\"\n\t\"github.com/aws/aws-sdk-go/service/dynamodb\"\n\t\"github.com/aws/aws-sdk-go/service/dynamodb/dynamodbiface\"\n\t\"github.com/cep21/circuit/v3\"\n)\n\n// CircuitWrapperDynamoDBConfig contains configuration for CircuitWrapperDynamoDB. All fields are optional\ntype CircuitWrapperDynamoDBConfig struct {\n\t// ShouldSkipError determines whether an error should be skipped and have the circuit\n\t// track the call as successful. This takes precedence over IsBadRequest\n\tShouldSkipError func(error) bool\n\n\t// IsBadRequest is an optional bad request checker. It is useful to not count user errors as faults\n\tIsBadRequest func(error) bool\n\n\t// Prefix is prepended to all circuit names\n\tPrefix string\n\n\t// Defaults are used for all created circuits. Per-circuit configs override this\n\tDefaults circuit.Config\n\n\t// CircuitBatchGetItemPagesWithContext is the configuration used for the BatchGetItemPagesWithContext circuit. This overrides values set by Defaults\n\tCircuitBatchGetItemPagesWithContext circuit.Config\n\t// CircuitBatchGetItemWithContext is the configuration used for the BatchGetItemWithContext circuit. This overrides values set by Defaults\n\tCircuitBatchGetItemWithContext circuit.Config\n\n\t// ... Rest omitted\n}\n\n// CircuitWrapperDynamoDB is a circuit wrapper for dynamodbiface.DynamoDBAPI\ntype CircuitWrapperDynamoDB struct {\n\tdynamodbiface.DynamoDBAPI\n\n\t// ShouldSkipError determines whether an error should be skipped and have the circuit\n\t// track the call as successful. This takes precedence over IsBadRequest\n\tShouldSkipError func(error) bool\n\n\t// IsBadRequest checks whether to count a user error against the circuit. It is recommended to set this\n\tIsBadRequest func(error) bool\n\n\t// CircuitBatchGetItemPagesWithContext is the circuit for method BatchGetItemPagesWithContext\n\tCircuitBatchGetItemPagesWithContext *circuit.Circuit\n\t// CircuitBatchGetItemWithContext is the circuit for method BatchGetItemWithContext\n\tCircuitBatchGetItemWithContext *circuit.Circuit\n\n\t// ... Rest omitted\n}\n\n// NewCircuitWrapperDynamoDB creates a new circuit wrapper and initializes circuits\nfunc NewCircuitWrapperDynamoDB(\n\tmanager *circuit.Manager,\n\tembedded dynamodbiface.DynamoDBAPI,\n\tconf CircuitWrapperDynamoDBConfig,\n) (*CircuitWrapperDynamoDB, error) {\n\tif conf.ShouldSkipError == nil {\n\t\tconf.ShouldSkipError = func(err error) bool {\n\t\t\treturn false\n\t\t}\n\t}\n\n\tif conf.IsBadRequest == nil {\n\t\tconf.IsBadRequest = func(err error) bool {\n\t\t\treturn false\n\t\t}\n\t}\n\n\tw := \u0026CircuitWrapperDynamoDB{\n\t\tDynamoDBAPI:     embedded,\n\t\tShouldSkipError: conf.ShouldSkipError,\n\t\tIsBadRequest:    conf.IsBadRequest,\n\t}\n\n\tvar err error\n\n\tw.CircuitBatchGetItemPagesWithContext, err = manager.CreateCircuit(conf.Prefix+\"DynamoDB.BatchGetItemPagesWithContext\", conf.CircuitBatchGetItemPagesWithContext, conf.Defaults)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tw.CircuitBatchGetItemWithContext, err = manager.CreateCircuit(conf.Prefix+\"DynamoDB.BatchGetItemWithContext\", conf.CircuitBatchGetItemWithContext, conf.Defaults)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\t// ... Rest omitted\n\n\treturn w, nil\n}\n\n// BatchGetItemPagesWithContext calls the embedded dynamodbiface.DynamoDBAPI's method BatchGetItemPagesWithContext with CircuitBatchGetItemPagesWithContext\nfunc (w *CircuitWrapperDynamoDB) BatchGetItemPagesWithContext(ctx context.Context, p1 *dynamodb.BatchGetItemInput, p2 func(*dynamodb.BatchGetItemOutput, bool) bool, p3 ...request.Option) error {\n\tvar skippedErr error\n\n\terr := w.CircuitBatchGetItemPagesWithContext.Run(ctx, func(ctx context.Context) error {\n\t\terr := w.DynamoDBAPI.BatchGetItemPagesWithContext(ctx, p1, p2, p3...)\n\n\t\tif w.ShouldSkipError(err) {\n\t\t\tskippedErr = err\n\t\t\treturn nil\n\t\t}\n\n\t\tif w.IsBadRequest(err) {\n\t\t\treturn \u0026circuit.SimpleBadRequest{Err: err}\n\t\t}\n\n\t\treturn err\n\t})\n\n\tif skippedErr != nil {\n\t\terr = skippedErr\n\t}\n\n\tif berr, ok := err.(*circuit.SimpleBadRequest); ok {\n\t\terr = berr.Err\n\t}\n\n\treturn err\n}\n\n// BatchGetItemWithContext calls the embedded dynamodbiface.DynamoDBAPI's method BatchGetItemWithContext with CircuitBatchGetItemWithContext\nfunc (w *CircuitWrapperDynamoDB) BatchGetItemWithContext(ctx context.Context, p1 *dynamodb.BatchGetItemInput, p2 ...request.Option) (*dynamodb.BatchGetItemOutput, error) {\n\tvar r0 *dynamodb.BatchGetItemOutput\n\tvar skippedErr error\n\n\terr := w.CircuitBatchGetItemWithContext.Run(ctx, func(ctx context.Context) error {\n\t\tvar err error\n\t\tr0, err = w.DynamoDBAPI.BatchGetItemWithContext(ctx, p1, p2...)\n\n\t\tif w.ShouldSkipError(err) {\n\t\t\tskippedErr = err\n\t\t\treturn nil\n\t\t}\n\n\t\tif w.IsBadRequest(err) {\n\t\t\treturn \u0026circuit.SimpleBadRequest{Err: err}\n\t\t}\n\n\t\treturn err\n\t})\n\n\tif skippedErr != nil {\n\t\terr = skippedErr\n\t}\n\n\tif berr, ok := err.(*circuit.SimpleBadRequest); ok {\n\t\terr = berr.Err\n\t}\n\n\treturn r0, err\n}\n\n// ... Rest of methods omitted\n\nvar _ dynamodbiface.DynamoDBAPI = (*CircuitWrapperDynamoDB)(nil)\n```\n\nThe wrapper can be used like such\n\n```go\nfunc createWrappedClient() (dynamodbiface.DynamoDBAPI, error) {\n\tm := \u0026circuit.Manager{} // Simplest manager\n\n\t// Create embedded client\n\tsess := session.Must(session.NewSession(\u0026aws.Config{}))\n\tclient := dynamodb.New(sess)\n\n\t// Create circuit wrapped client\n\twrappedClient, err := wrappers.NewCircuitWrapperDynamoDB(m, client, wrappers.CircuitWrapperDynamoDBConfig{\n\t\t// Custom check to skip errors to not count against the circuit. For DynamoDB specifically, ConditionalCheckFailedException\n\t\t// errors are considered successful requests\n\t\tShouldSkipError: func(err error) bool {\n\t\t\taerr, ok := err.(awserr.Error)\n\t\t\treturn ok \u0026\u0026 aerr.Code() == dynamodb.ErrCodeConditionalCheckFailedException\n\t\t},\n\t\t// Custom check for bad request. This is important to not count user errors as faults.\n\t\t// See https://github.com/cep21/circuit#not-counting-user-error-as-a-fault\n\t\tIsBadRequest: func(err error) bool {\n\t\t\trerr, ok := err.(awserr.RequestFailure)\n\t\t\tif ok {\n\t\t\t\treturn rerr.StatusCode() \u003e= 400 \u0026\u0026 rerr.StatusCode() \u003c 500\n\t\t\t}\n\t\t\treturn false\n\t\t},\n\t\t// Override defaults for the GetItemWithContext circuit\n\t\tCircuitGetItemWithContext: circuit.Config{\n\t\t\tExecution: circuit.ExecutionConfig{\n\t\t\t\tTimeout: 200 * time.Millisecond, // Override default timeout\n\t\t\t},\n\t\t},\n\t})\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\treturn wrappedClient, nil\n}\n```\n\n# Development\n\nGo version 1.12 or beyond is recommended for development.\n\nRun `make test` to run Go tests.\n\n# License\n\nThis library is licensed under the Apache 2.0 License. \n\n# Contributing\n\nAny pull requests are extremely welcome! If you run into problems or have questions, please raise a github issue!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwitchtv%2Fcircuitgen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftwitchtv%2Fcircuitgen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwitchtv%2Fcircuitgen/lists"}