{"id":18463960,"url":"https://github.com/unleash/unleash-client-go","last_synced_at":"2025-04-05T13:08:56.494Z","repository":{"id":15287008,"uuid":"77830373","full_name":"Unleash/unleash-client-go","owner":"Unleash","description":"Unleash client SDK for Go","archived":false,"fork":false,"pushed_at":"2024-08-29T08:01:36.000Z","size":389,"stargazers_count":135,"open_issues_count":2,"forks_count":54,"subscribers_count":5,"default_branch":"v4","last_synced_at":"2024-08-29T09:27:40.975Z","etag":null,"topics":["feature","feature-flags","feature-management","feature-toggles","go","hacktoberfest","toggles","unleash"],"latest_commit_sha":null,"homepage":"https://docs.getunleash.io","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/Unleash.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":"2017-01-02T11:58:02.000Z","updated_at":"2024-08-29T08:00:12.000Z","dependencies_parsed_at":"2023-10-17T00:05:48.628Z","dependency_job_id":"97db9685-cbb6-42f3-bc29-3250bfb97ae8","html_url":"https://github.com/Unleash/unleash-client-go","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unleash%2Funleash-client-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unleash%2Funleash-client-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unleash%2Funleash-client-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unleash%2Funleash-client-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Unleash","download_url":"https://codeload.github.com/Unleash/unleash-client-go/tar.gz/refs/heads/v4","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247339158,"owners_count":20923014,"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":["feature","feature-flags","feature-management","feature-toggles","go","hacktoberfest","toggles","unleash"],"created_at":"2024-11-06T09:08:28.090Z","updated_at":"2025-04-05T13:08:56.471Z","avatar_url":"https://github.com/Unleash.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://github.com/Unleash/unleash-client-go/actions/workflows/build.yml/badge.svg)](https://github.com/Unleash/unleash-client-go/actions/workflows/build.yml) [![GoDoc](https://pkg.go.dev/badge/github.com/Unleash/unleash-client-go/v4?status.svg)](https://pkg.go.dev/github.com/Unleash/unleash-client-go/v4) [![Go Report Card](https://goreportcard.com/badge/github.com/Unleash/unleash-client-go)](https://goreportcard.com/report/github.com/Unleash/unleash-client-go)\n[![Coverage Status](https://coveralls.io/repos/github/Unleash/unleash-client-go/badge.svg?branch=v4)](https://coveralls.io/github/Unleash/unleash-client-go?branch=v4)\n\n# unleash-client-go\n\nUnleash Client for Go. Read more about the [Unleash project](https://github.com/Unleash/unleash)\n\n**Version 3.x of the client requires `unleash-server` v4.x or higher.**\n\n## Go Version\n\nThe client is currently tested against Go 1.10.x and 1.13.x. These versions will be updated\nas new versions of Go are released.\n\nThe client may work on older versions of Go as well, but is not actively tested.\n\n## Getting started\n\n### 1. Install unleash-client-go\n\nTo install the latest version of the client use:\n\n```bash\ngo get github.com/Unleash/unleash-client-go/v4\n```\n\nIf you are still using Unleash Server v2.x.x, then you should use:\n\n```bash\ngo get github.com/Unleash/unleash-client-go\n```\n\n### 2. Initialize unleash\n\nThe easiest way to get started with Unleash is to initialize it early in your application code:\n\n**Asynchronous initialization example:**\n```go\nimport (\n\t\"github.com/Unleash/unleash-client-go/v4\"\n)\n\nfunc init() {\n\tunleash.Initialize(\n\t\tunleash.WithListener(\u0026unleash.DebugListener{}),\n\t\tunleash.WithAppName(\"my-application\"),\n\t\tunleash.WithUrl(\"http://unleash.herokuapp.com/api/\"),\n\t\tunleash.WithCustomHeaders(http.Header{\"Authorization\": {\"\u003cAPI token\u003e\"}}),\n\t)\n}\n```\n\n**Synchronous initialization example:**\n\n```go\nimport (\n\t\"github.com/Unleash/unleash-client-go/v4\"\n)\n\nfunc init() {\n\tunleash.Initialize(\n\t\tunleash.WithListener(\u0026unleash.DebugListener{}),\n\t\tunleash.WithAppName(\"my-application\"),\n\t\tunleash.WithUrl(\"http://unleash.herokuapp.com/api/\"),\n\t\tunleash.WithCustomHeaders(http.Header{\"Authorization\": {\"\u003cAPI token\u003e\"}}),\n\t)\n\n\t// Note this will block until the default client is ready\n\tunleash.WaitForReady()\n}\n```\n\n#### Preloading feature toggles\n\nIf you'd like to prebake your application with feature toggles (maybe you're working without persistent storage, so Unleash's backup isn't available), you can replace the defaultStorage implementation with a BootstrapStorage. This allows you to pass in a reader to where data in the format of `/api/client/features` can be found.\n\n#### Bootstrapping from file\n\nBootstrapping from file on disk is then done using something similar to:\n\n```go\nimport (\n\t\"github.com/Unleash/unleash-client-go/v4\"\n)\n\nfunc init() {\n\tmyBootstrap := os.Open(\"bootstrapfile.json\") // or wherever your file is located at runtime\n\t// BootstrapStorage handles the case where Reader is nil\n\tunleash.Initialize(\n\t\tunleash.WithListener(\u0026unleash.DebugListener{}),\n\t\tunleash.WithAppName(\"my-application\"),\n\t\tunleash.WithUrl(\"http://unleash.herokuapp.com/api/\"),\n\t\tunleash.WithStorage(\u0026BootstrapStorage{Reader: myBootstrap})\n\t)\n}\n```\n\n#### Bootstrapping from S3\n\nBootstrapping from S3 is then done by downloading the file using the AWS library and then passing in a Reader to the just downloaded file:\n\n```go\nimport (\n\t\"github.com/Unleash/unleash-client-go/v4\"\n\t\"github.com/aws/aws-sdk-go-v2/aws\"\n\t\"github.com/aws/aws-sdk-go-v2/config\"\n\t\"github.com/aws/aws-sdk-go-v2/service/s3\"\n)\n\nfunc init() {\n\t// Load the shared AWS config\n\tcfg, err := config.LoadDefaultConfig(context.TODO())\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\t// Create an S3 client\n\tclient := s3.NewFromConfig(cfg)\n\n\tobj, err := client.GetObject(context.TODO(), \u0026s3.GetObjectInput{\n\t\tBucket: aws.String(\"YOURBUCKET\"),\n\t\tKey:    aws.String(\"YOURKEY\"),\n\t})\n\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\treader := obj.Body\n\tdefer reader.Close()\n\n\t// BootstrapStorage handles the case where Reader is nil\n\tunleash.Initialize(\n\t\tunleash.WithListener(\u0026unleash.DebugListener{}),\n\t\tunleash.WithAppName(\"YOURAPPNAME\"),\n\t\tunleash.WithUrl(\"YOURINSTANCE_URL\"),\n\t\tunleash.WithStorage(\u0026BootstrapStorage{Reader: reader})\n\t)\n}\n```\n\n#### Bootstrapping from Google\n\nSince the Google Cloud Storage API returns a Reader, implementing a Bootstrap from GCS is done using something similar to\n\n```go\nimport (\n\t\"github.com/Unleash/unleash-client-go/v4\"\n\t\"cloud.google.com/go/storage\"\n)\n\nfunc init() {\n\tctx := context.Background() // Configure Google Cloud context\n\tclient, err := storage.NewClient(ctx) // Configure your client\n\tif err != nil {\n\t\t// TODO: Handle error.\n\t}\n\tdefer client.Close()\n\n\t// Fetch the bucket, then object and then create a reader\n\treader := client.Bucket(bucketName).Object(\"my-bootstrap.json\").NewReader(ctx)\n\n\t// BootstrapStorage handles the case where Reader is nil\n\tunleash.Initialize(\n\t\tunleash.WithListener(\u0026unleash.DebugListener{}),\n\t\tunleash.WithAppName(\"my-application\"),\n\t\tunleash.WithUrl(\"http://unleash.herokuapp.com/api/\"),\n\t\tunleash.WithStorage(\u0026unleash.BootstrapStorage{Reader: reader})\n\t)\n}\n```\n\n### 3. Use unleash\n\nAfter you have initialized the unleash-client you can easily check if a feature\ntoggle is enabled or not.\n\n```go\nunleash.IsEnabled(\"app.ToggleX\")\n```\n\n### 4. Stop unleash\n\nTo shut down the client (turn off the polling) you can simply call the\ndestroy-method. This is typically not required.\n\nunleash.Close()\n\n### Built in activation strategies\n\nThe Go client comes with implementations for the built-in activation strategies\nprovided by unleash.\n\n- DefaultStrategy\n- UserIdStrategy\n- FlexibleRolloutStrategy\n- GradualRolloutUserIdStrategy\n- GradualRolloutSessionIdStrategy\n- GradualRolloutRandomStrategy\n- RemoteAddressStrategy\n- ApplicationHostnameStrategy\n\n[Read more about activation strategies in the docs](https://docs.getunleash.io/reference/activation-strategies).\n\n### Unleash context\n\nIn order to use some of the common activation strategies you must provide an\n[unleash-context](https://docs.getunleash.io/reference/unleash-context).\nThis client SDK allows you to send in the unleash context as part of the `isEnabled` call:\n\n```go\nctx := context.Context{\n\tUserId:        \"123\",\n\tSessionId:     \"some-session-id\",\n\tRemoteAddress: \"127.0.0.1\",\n}\n\nunleash.IsEnabled(\"someToggle\", unleash.WithContext(ctx))\n```\n\n### Caveat\n\nThis client uses go routines to report several events and doesn't drain the channel by default. So you need to either register a listener using `WithListener` or drain the channel \"manually\" (demonstrated in [this example](https://github.com/Unleash/unleash-client-go/blob/master/example_with_instance_test.go)).\n\n### Feature Resolver\n\n`FeatureResolver` is a `FeatureOption` used in `IsEnabled` via the `WithResolver`.\n\nThe `FeatureResolver` can be used to provide a feature instance in a different way than the client would normally retrieve it. This alternative resolver can be useful if you already have the feature instance and don't want to incur the cost to retrieve it from the repository.\n\nAn example of its usage is below:\n\n```go\nctx := context.Context{\n\tUserId:        \"123\",\n\tSessionId:     \"some-session-id\",\n\tRemoteAddress: \"127.0.0.1\",\n}\n\n// the FeatureResolver function that will be passed into WithResolver\nresolver := func(featureName string) *api.Feature {\n    if featureName == \"someToggle\" {\n        // Feature being created in place for sake of example, but it is preferable an existing feature instance is used\n        return \u0026api.Feature{\n            Name:        \"someToggle\",\n            Description: \"Example of someToggle\",\n            Enabled:     true,\n            Strategies: []api.Strategy{\n                {\n                    Id:   1,\n                    Name: \"default\",\n                },\n            },\n            CreatedAt:  time.Time{},\n            Strategy:   \"default-strategy\",\n        }\n    } else {\n        // it shouldn't reach this block because the name will match above \"someToggle\" for this example\n        return nil\n    }\n}\n\n// This would return true because the matched strategy is default and the feature is Enabled\nunleash.IsEnabled(\"someToggle\", unleash.WithContext(ctx), unleash.WithResolver(resolver))\n```\n\n## Development\n\nTo override dependency on unleash-client-go github repository to a local development folder (for instance when building a local test-app for the SDK),  \nyou can add the following to your apps `go.mod`:\n\n```mod\n    replace github.com/Unleash/unleash-client-go/v4 =\u003e ../unleash-client-go/\n```\n\n\n\n## Steps to release\n\n- Update the clientVersion in `client.go`\n- Tag the repository with the new tag\n\n## Adding client specifications\n\nIn order to make sure the unleash clients uphold their contract, we have defined a set of\nclient specifications that define this contract. These are used to make sure that each unleash client\nat any time adhere to the contract, and define a set of functionality that is core to unleash. You can view\nthe [client specifications here](https://github.com/Unleash/client-specification).\n\nIn order to make the tests run please do the following steps.\n\n```\n// in repository root\n// testdata is gitignored\nmkdir testdata\ncd testdata\ngit clone https://github.com/Unleash/client-specification.git\n```\n\nRequirements:\n\n- make\n- golint (go get -u golang.org/x/lint/golint)\n\nRun tests:\n\n    make\n\nRun lint check:\n\n    make lint\n\nRun code-style checks:(currently failing)\n\n    make strict-check\n\nRun race-tests:\n\n    make test-race\n\n## Benchmarking\n\nYou can benchmark feature toggle evaluation by running:\n\n```\ngo test -run=^$ -bench=BenchmarkFeatureToggleEvaluation -benchtime=10s\n```\n\nHere's an example of how the output could look like:\n\n```\ngoos: darwin\ngoarch: arm64\npkg: github.com/Unleash/unleash-client-go/v4\nBenchmarkFeatureToggleEvaluation-8 Final Estimated Operations Per Day: 101.131 billion (1.011315e+11)\n13635154 854.3 ns/op\nPASS\nok github.com/Unleash/unleash-client-go/v4 13.388s\n```\n\nIn this example the benchmark was run on a MacBook Pro (M1 Pro, 2021) with 16GB RAM.\n\nWe can see a result of **854.3 ns/op**, which means around **101.131 billion** feature toggle evaluations per day.\n\n**Note**: The benchmark is run with a single CPU core, no parallelism.\n\n## Design philsophy\n\nThis feature flag SDK is designed according to our design philosophy. You can [read more about that here](https://docs.getunleash.io/topics/feature-flags/feature-flag-best-practices).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funleash%2Funleash-client-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funleash%2Funleash-client-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funleash%2Funleash-client-go/lists"}