https://github.com/featurehub-io/featurehub-go-sdk
FeatureHub Go server SDK
https://github.com/featurehub-io/featurehub-go-sdk
feature-flags feature-toggles flags go go-ab-testing go-feature-flags go-feature-flags-server go-feature-toggles go-feature-toggles-server go-sdk golang golang-feature-flags sdk toggles
Last synced: 5 months ago
JSON representation
FeatureHub Go server SDK
- Host: GitHub
- URL: https://github.com/featurehub-io/featurehub-go-sdk
- Owner: featurehub-io
- License: mit
- Created: 2021-06-08T19:54:59.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-08-30T14:01:02.000Z (almost 3 years ago)
- Last Synced: 2024-06-19T19:46:25.600Z (almost 2 years ago)
- Topics: feature-flags, feature-toggles, flags, go, go-ab-testing, go-feature-flags, go-feature-flags-server, go-feature-toggles, go-feature-toggles-server, go-sdk, golang, golang-feature-flags, sdk, toggles
- Language: Go
- Homepage:
- Size: 58.6 KB
- Stars: 9
- Watchers: 4
- Forks: 6
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
client-go
=========
A GoLang client SDK for FeatureHub.
Features
--------
* Client interface, with an autogenerated mock so you can unit test with this SDK
* Config type, with validation and defaults
* StreamingClient implementation:
- Features are made available through "Get" methods:
- `GetFeature` returns a whole feature (by key) with full metadata (but an untyped value)
- `GetBoolean` returns a boolean feature (by key), or an error if it is unable to assert the value to a boolean
- `GetNumber` / `GetRawJSON` / `GetString` as above
- Levelled Logging (you can choose how verbose to make this)
- Notifiers can be added for named feature keys, which will trigger a user-provided callback function whenever a feature with this key is updated
- Notifiers can be added ahead of time (before the client even knows about the feature-keys in question)
* Custom errors (allows you to handle different errors in specific ways)
Usage
-----
Some snippets to get you going.
### Connecting to FeatureHub
There are 3 steps to connecting:
1) Prepare a config
2) Use the config to make a client
3) Tell the client to start handling features
#### Prepare a configuration (with a client):
```go
// Start by creating a config with your serverAddress and API-key:
fhConfig, err := client.New(serverAddress, apiKey).WithLogLevel(logrus.WarnLevel).WithWaitForData(true).Connect()
if err != nil {
log.Panicf("Error creating config: %s", err)
}
// Get a context from this config:
fhClient := fhClient.NewContext()
```
### Requesting Features
The client SDK offers various `Get` methods to retrieve different types of features:
* `GetBoolean(key)`: returns a true or false
* `GetRawJSON(key)`: returns a serialised JSON object
* `GetNumber(key)`: returns a float64
* `GetString(key)`: returns a string
#### Retrieve a BOOLEAN value:
```go
someBoolean, err := fhClient.GetBoolean("booleanfeature")
if err != nil {
log.Fatalf("Error retrieving a BOOLEAN feature: %s", err)
}
log.Printf("Retrieved a BOOLEAN feature: %v", someBoolean)
```
#### Retrieve a JSON value:
```go
someJSON, err := fhClient.GetRawJSON("jsonfeature")
if err != nil {
log.Fatalf("Error retrieving a JSON feature: %s", err)
}
log.Printf("Retrieved a JSON feature: %s", someJSON)
```
#### Retrieve a NUMBER value:
```go
someNumber, err := fhClient.GetNumber("numberfeature")
if err != nil {
log.Fatalf("Error retrieving a NUMBER feature: %s", err)
}
log.Printf("Retrieved a NUMBER feature: %f", someNumber)
```
#### Retrieve a STRING value:
```go
someString, err := fhClient.GetString("stringfeature")
if err != nil {
log.Fatalf("Error retrieving a STRING feature: %s", err)
}
log.Printf("Retrieved a STRING feature: %s", someString)
```
### Configuring Notifiers (callbacks)
The client SDK allows the user to define callback notifications which will be triggered whenever a specific feature key is updated.
Notifiers can be defined at any time, even before the client has received data.
* `AddNotifierBoolean(key string, callback func(bool))`: Calls the provided function with a boolean value
* `AddNotifierFeature(key string, callback func(*models.FeatureState))`: Calls the provided function with a raw feature state
* `AddNotifierJSON(key string, callback func(string))`: Calls the provided function with a JSON string value
* `AddNotifierNumber(key string, callback func(float64))`: Calls the provided function with a float64 value
* `AddNotifierString(key string, callback func(string))`: Calls the provided function with a string value
* `DeleteNotifier(key string) error`: Deletes any configured notifier for the given key (or returns an error if no notifier was found)
### Configuring a Readiness Listener
The client SDK allows the user to define a callback function which will be triggered once, when the client first receives some data from the server.
* `ReadinessListener(callback func())`: Sets the readiness listener to a specific user-provided function
### Analytics Collector
The client SDK provides the ability to generate analytics events with the `LogAnalyticsEvent` method. An event will be generated for each feature that we have.
```go
action := "payment"
tags := map[string]string{"user": "bob"}
fhClient.LogAnalyticsEvent(action, tags)
```
The SDK offers a logging analytics collector which will log events to the console at DEBUG level (useful in your unit tests probably).
#### Google Analytics
The GoLang SDK comes with a pre-made Google Analytics collector. Here is how to use it:
```go
googleAnalyticsCollector, err := analytics.NewGoogleAnalyticsCollector(clientID, trackingID, userAgentKey)
if err != nil {
panic(err)
}
fhClient.AddAnalyticsCollector(googleAnalyticsCollector)
```
Any subsequent calls to `client.LogAnalyticsEvent()` will result in events being sent via the Google Analytics collector (as well as any other which you have added).
### Client-side rollout strategies
Some rollout strategies need to be calculated per-request, which means that we can't rely on the server to do this for us. For this we provide the ability to apply a client context to a feature before using its value:
```go
// Add some values to the context:
fhClient.Country = "russia"
fhClient.Custom["test"] = true
// Now retrieved feature values will be evaluated against your context:
featureValue, err = fhClient.GetString("featureKey")
```
If you have a complex context then you can define it as a single struct:
```go
// You can also define a context as a struct:
clientContext := &models.Context{
Userkey: "12345",
Device: "server",
Platform: "linux",
Country: "New Zealand",
Version: "1.0.5",
Custom: map[string]interface{}{
"startDate": "now",
"username": "prawn",
"iteration", float64(5),
},
}
// And get the config to return you a fully-loaded context:
fhClient := fhConfig.WithContext(clientContext)
// Now retrieved feature values will be evaluated against your context:
featureValue, err = fhClient.GetString("featureKey")
```
If the featureValue has rollout strategies defined then they will be applied according to the client context you provide.
Note the map of `Custom` values, which are evaluated against your custom features according to their field names (keys).
Setup using docker
----------------
We have dockerfile, use below commands to setup
```
1. docker build -t featurehub-go-sdk:v1 .
2. docker run -p 8080:8080 featurehub-go-sdk:v1
```
Further examples
----------------
Further examples can be found in the [examples directory](examples)